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_CONVERT - определяет, что бинарные данные будут сконвертированы в 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 для серверов z/OS и OS/390 поддерживает длину вплоть до 16 символов. Идентификатор пользователя никак не скомпрометирует идентификатор авторизации - это разные сущности.

acctstr

SQL_ATTR_INFO_ACCTSTR - указатель на символьную строку, кончающуюся null-байтом и использующуюся для идентификации учетной строки клиента, соответствующей посланой на сервер при соединении.

Замечание:

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

applname

SQL_ATTR_INFO_APPLNAME - указатель на символьную строку, кончающуюся null-байтом и использующуюся для идентификации имени клиентского приложения, соответствующей посланой на сервер при соединении.

Замечание:

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

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME - указатель на символьную строку, кончающуюся null-байтом и использующуюся для идентификации имени рабочей станции, соответствующей посланой на сервер при соединении.

Замечание:

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 Setting multiple parameters with a connection resource and the wrong type

<?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 Setting multiple parameters with the wrong resource

<?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 Putting it all together

<?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() - Returns a connection to a database
  • db2_pconnect() - Returns a persistent connection to a database
  • db2_exec() - Executes an SQL statement directly
  • db2_prepare() - Prepares an SQL statement to be executed
  • db2_cursor_type() - Возвращает тип курсора, который используется в ресурсе оператора