db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — Устанавливает опции для ресурса соединения или ресурса запроса

Описание

db2_set_option(resource $resource, array $options, int $type): bool

Функция устанавливает опции для ресурса запроса или ресурса соединения. Нельзя установить опции для ресурсов результирующих наборов.

Список параметров

resource

Корректный ресурс запроса, который вернула функция db2_prepare() или корректный ресурс соединения, который вернула функция db2_connect() или db2_pconnect().

options

Ассоциативный массив, который содержит корректный запрос или опции соединения. Этот параметр изменяет значения автофиксации, типы курсоров (прокручиваемых или прямой) и указывает регистр имён столбцов (нижний, верхний или натуральный), которые будут отображаться в результирующем наборе.

autocommit

DB2_AUTOCOMMIT_ON — включает режим автофиксации для ресурса соединения.

DB2_AUTOCOMMIT_OFF — отключает режим автофиксации для ресурса соединения.

cursor

DB2_FORWARD_ONLY — задаёт тип курсора последовательного доступа для ресурса запроса. Это тип курсора по умолчанию, который поддерживается всеми серверами баз данных.

DB2_SCROLLABLE — задаёт тип прокручиваемого курсора для ресурса запроса. Прокручиваемые курсоры разрешают получать доступ к произвольным строкам результирующего набора, но поддерживаются только базами данных IBM DB2 Universal Database.

binmode

DB2_BINARY — указывает, что функция вернёт двоичные данные как есть. Это эквивалент установки опции конфигурации ibm_db2.binmode=1 в файле php.ini.

DB2_CONVERT — указывает, что функция преобразует двоичные данные в шестнадцатеричное представление и вернёт данные в таком виде. Это эквивалент установки опции конфигурации ibm_db2.binmode=2 в файле php.ini.

DB2_PASSTHRU — указывает, что функция преобразует двоичные в null. Это эквивалент установки опции конфигурации ibm_db2.binmode=3 в файле php.ini.

db2_attr_case

DB2_CASE_LOWER — определяет, что имена столбцов будут возвращаться в нижнем регистре.

DB2_CASE_UPPER — определяет, что имена столбцов будут возвращаться в верхнем регистре.

DB2_CASE_NATURAL — определяет, что имена столбцов будут возвращаться как есть.

deferred_prepare

DB2_DEFERRED_PREPARE_ON - включает отложенную подготовку ресурса запроса.

DB2_DEFERRED_PREPARE_OFF - выключает отложенную подготовку ресурса запроса.

Следующие новые опции ОС i5/OS доступны в модуле ibm_db2 1.5.1 и более поздних версиях. Эти опции применяются, только если PHP и модуль ibm_db2 запускаются на системах i5.

i5_fetch_only

DB2_I5_FETCH_ON — курсоры доступны только для чтения и не могут использоваться для позиционирования при операциях DELETE или UPDATE. Это значение по умолчанию, только если для переменной окружения SQL_ATTR_FOR_FETCH_ONLY не установили значение SQL_FALSE.

DB2_I5_FETCH_OFF — курсоры можно использовать для позиционирования при операциях DELETE или UPDATE.

Следующие новые опции доступны в модуле ibm_db2 1.8.0 и более поздних версиях.

rowcount

DB2_ROWCOUNT_PREFETCH_ON — клиент может запросить полное количество строк перед извлечением, что означает, что функция db2_num_rows() вернёт количество выбранных строк, даже если используется курсор ROLLFORWARD_ONLY.

DB2_ROWCOUNT_PREFETCH_OFF — клиент не может запросить полное количество строк перед извлечением.

Следующие новые опции доступны в модуле ibm_db2 1.7.0 и более поздних версиях.

trusted_user

Чтобы переключить пользователя в статус доверенного пользователя, указывают идентификатор (строку) доверенного пользователя как значение этого параметра. Эту опцию можно установить только для ресурса соединения. Чтобы использовать эту опцию, требуется включить доверенный контекст на ресурсе подключения.

trusted_password

Пароль (строка), который соответствует идентификатору пользователя, который задали в опции trusted_user.

Следующие новые опции доступны в модуле ibm_db2 1.6.0 и более поздних версиях. Эти опции предоставляют полезную информацию отслеживания, доступ к которой можно получить функцией db2_get_option() во время выполнения.

Замечание:

При установке значений для каждой опции отдельные серверы смогут обработать не всё значение и обрежут его.

Чтобы гарантировать правильное преобразование данных каждой опции при передаче на хост-систему, указывают только символы A-Z, 0-9, подчёркивание(_) и точку (.).

userid

SQL_ATTR_INFO_USERID — указатель на строку, которая заканчивается символом null-байта и используется для распознавания клиентского идентификатора пользователя, который передаётся на хост сервера баз данных при соединении через клиент Db2 Connect.

Замечание:

БД DB2 для серверов z/OS и OS/390 поддерживает длину значения до 16 символов. Этот идентификатор пользователя не следует путать с идентификатором пользователя для аутентификации, он предназначен только для идентификации и не используется для авторизации.

acctstr

SQL_ATTR_INFO_ACCTSTR — указатель на строку, которая заканчивается символом null-байта и используется для идентификации учётной строки, которая передаётся на хост сервера баз данных при соединении через клиент Db2 Connect.

Замечание:

БД DB2 для серверов z/OS и OS/390 поддерживает длину значения до 200 символов.

applname

SQL_ATTR_INFO_APPLNAME — указатель на строку, которая заканчивается символом null-байта и используется для идентификации имени клиентского приложения, которое передаётся на хост сервера баз данных при соединении через клиент Db2 Connect.

Замечание:

БД DB2 для серверов z/OS и OS/390 поддерживает длину значения до 32 символов.

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME — указатель на строку, которая заканчивается символом null-байта и используется для идентификации имени рабочей станции, которое передаётся на хост сервера баз данных при соединении через клиент Db2 Connect.

Замечание:

БД DB2 для серверов z/OS и OS/390 поддерживает длину значения до 18 символов.

type

Целочисленное значение, которое указывает тип ресурса, который передали в функцию. Тип ресурса и это значение должны совпадать.

1 — ресурс соединения передали в функцию.

Передача в качестве значения целого числа, которое не равно 1, указывает, что в функцию передали ресурс запроса.

В следующей таблице указывается совместимость параметров с доступными типами ресурсов:

Матрица ресурс-параметр
Ключ Значение Тип ресурса
  Соединение Запрос Результирующий набор
autocommit DB2_AUTOCOMMIT_ON X - -
autocommit DB2_AUTOCOMMIT_OFF X - -
cursor DB2_SCROLLABLE - X -
cursor DB2_FORWARD_ONLY - X -
binmode DB2_BINARY X X -
binmode DB2_CONVERT X X -
binmode DB2_PASSTHRU X X -
db2_attr_case DB2_CASE_LOWER X X -
db2_attr_case DB2_CASE_UPPER X X -
db2_attr_case DB2_CASE_NATURAL X X -
deferred_prepare DB2_DEFERRED_PREPARE_ON - X -
deferred_prepare DB2_DEFERRED_PREPARE_OFF - X -
i5_fetch_only DB2_I5_FETCH_ON - X -
i5_fetch_only DB2_I5_FETCH_OFF - X -
rowcount DB2_ROWCOUNT_PREFETCH_ON - X -
rowcount DB2_ROWCOUNT_PREFETCH_OFF - X -
trusted_user <USER NAME> (String) X - -
trusted_password <PASSWORD> (String) X - -
userid SQL_ATTR_INFO_USERID X X -
acctstr SQL_ATTR_INFO_ACCTSTR X X -
applname SQL_ATTR_INFO_APPLNAME X X -
wrkstnname SQL_ATTR_INFO_WRKSTNNAME X X -

Возвращаемые значения

Функция возвращает true, если выполнилась успешно, или false, если возникла ошибка.

Примеры

Пример #1 Пример установки одного параметра для ресурса соединения

<?php

/* Параметры соединения с базой данных */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* Строка соединения */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* Получаем ресурс соединения */
$conn = db2_connect($conn_string, '', '');

/* Создаём ассоциативный массив опций */
$options = array('autocommit' => DB2_AUTOCOMMIT_ON);

/* Вызываем функцию */
$result = db2_set_option($conn, $options, 1);

/* Проверяем, все ли опции установились */
if($result) {
echo 'Options Set Successfully';
} else {
echo 'Could Not Set Options';
}

?>

Результат выполнения приведённого примера: 

Options Set Successfully

Пример #2 Пример установки набора параметров для ресурса соединения

<?php

/* Параметры соединения с базой данных */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* Строка соединения */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* Получаем ресурс соединения */
$conn = db2_connect($conn_string, '', '');

/* Создаём ассоциативный массив опций */
$options = array(
'autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE
);

/* Вызываем функцию */
$result = db2_set_option($conn, $options, 1);

/* Проверяем, все ли опции установились */
if ($result) {
echo 'Options Set Successfully';
} else {
echo 'Could Not Set Options';
}

?>

Результат выполнения приведённого примера: 

Options Set Successfully

Пример #3 Пример установки набора параметров с одним некорректным ключом

<?php

/* Параметры соединения с базой данных */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* Строка соединения */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* Получаем ресурс соединения */
$conn = db2_connect($conn_string, '', '');

/* Создаём ассоциативный массив опций */
$options = array(
'autocommit' => DB2_AUTOCOMMIT_OFF,
'MY_INVALID_KEY' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE
);

/* Вызываем функцию */
$result = db2_set_option($conn, $options, 1);

/* Проверяем, все ли опции установились */
if ($result) {
echo 'Options Set Successfully';
} else {
echo 'Could Not Set Options';
}

?>

Результат выполнения приведённого примера: 

Could Not Set Options

Пример #4 Пример установки набора параметров с одним некорректным значением

<?php

/* Параметры соединения с базой данных */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* Строка соединения */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* Получаем ресурс соединения */
$conn = db2_connect($conn_string, '', '');

/* Создаём ассоциативный массив опций */
$options = array(
'autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => 'INVALID_VALUE',
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE
);

/* Вызываем функцию */
$result = db2_set_option($conn, $options, 1);

/* Проверяем, все ли опции установились */
if ($result) {
echo 'Options Set Successfully';
} else {
echo 'Could Not Set Options';
}

?>

Результат выполнения приведённого примера: 

Could Not Set Options

Пример #5 Пример установки набора параметров с ресурсом соединения и неправильным типом

<?php

/* Параметры соединения с базой данных */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* Строка соединения */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* Получаем ресурс соединения */
$conn = db2_connect($conn_string, '', '');

/* Создаём ассоциативный массив опций */
$options = array(
'autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE
);

/* Вызываем функцию */
$result = db2_set_option($conn, $options, 2);

/* Проверяем, все ли опции установились */
if ($result) {
echo 'Options Set Successfully';
} else {
echo 'Could Not Set Options';
}

?>

Результат выполнения приведённого примера: 

Could Not Set Options

Пример #6 Пример установки набора параметров с неправильным ресурсом

<?php

/* Параметры соединения с базой данных */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* Строка соединения */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* Получаем ресурс соединения */
$conn = db2_connect($conn_string, '', '');

/* Создаём ассоциативный массив опций */
$options = array(
'autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE
);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

/* Вызываем функцию */
$result = db2_set_option($stmt, $options, 1);

/* Проверяем, все ли опции установились */
if ($result) {
echo 'Options Set Successfully';
} else {
echo 'Could Not Set Options';
}

?>

Результат выполнения приведённого примера: 

Could Not Set Options

Пример #7 Пример объединения опций

<?php

/* Параметры соединения с базой данных */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* Строка соединения */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* Получаем ресурс соединения */
$conn = db2_connect($conn_string, '', '');

/* Создаём ассоциативный массив опций */
$options = array(
'db2_attr_case' => DB2_CASE_LOWER,
'cursor' => DB2_SCROLLABLE
);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

/* Вызываем функцию */
$option_result = db2_set_option($stmt, $options, 2);
$result = db2_execute($stmt, array('000130', '000140'));

/* Получаем строку 2 перед строкой 1. Перематываемый курсор! */
print_r(db2_fetch_assoc($stmt, 2));
print '<br /><br />';
print_r(db2_fetch_assoc($stmt, 1));

?>

Результат выполнения приведённого примера: 

Array
(
    [empno] => 000140
    [firstnme] => HEATHER
    [midinit] => A
    [lastname] => NICHOLLS
    [workdept] => C01
    [phoneno] => 1793
    [hiredate] => 1976-12-15
    [job] => ANALYST
    [edlevel] => 18
    [sex] => F
    [birthdate] => 1946-01-19
    [salary] => 28420.00
    [bonus] => 600.00
    [comm] => 2274.00
)

Array
(
    [empno] => 000130
    [firstnme] => DELORES
    [midinit] => M
    [lastname] => QUINTANA
    [workdept] => C01
    [phoneno] => 4578
    [hiredate] => 1971-07-28
    [job] => ANALYST
    [edlevel] => 16
    [sex] => F
    [birthdate] => 1925-09-15
    [salary] => 23800.00
    [bonus] => 500.00
    [comm] => 1904.00
)

Пример #8 Пример курсора ОС i5/OS только для чтения

<?php
$conn = db2_connect("", "", "", array("i5_lib" => "nobody"));
$stmt = db2_prepare($conn, 'select * from names where first = ?');
$name = "first2";

db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);

$options = array("i5_fetch_only" => DB2_I5_FETCH_ON);

db2_set_option($stmt, $options, 0);

if (db2_execute($stmt)) {
while ($row = db2_fetch_array($stmt)) {
echo "{$row[0]} {$row[1]}";
}
}

?>

Результат выполнения приведённого примера: 

first2 last2

Смотрите также

  • db2_connect() - Возвращает соединение с базой данных
  • db2_pconnect() - Возвращает постоянное соединение с базой данных
  • db2_exec() - Выполняет SQL-запрос напрямую
  • db2_prepare() - Подготавливает SQL-запрос к выполнению
  • db2_cursor_type() - Возвращает тип курсора, который используется в ресурсе оператора