Возвращает постоянное соединение с базой данных

Описание

db2_pconnect(
    string $database,
    ?string $username,
    ?string $password,
    array $options = []
): resource|false

Функция возвращает постоянное соединение с базой данных IBM DB2 Universal Database, IBM Cloudscape или Apache Derby.

Дополнительную информацию о постоянных соединениях даёт раздел «Постоянные соединения с базами данных».

Вызов функции db2_close() при постоянном соединении каждый раз возвращает true, но базовое клиентское DB2-соединение остаётся открытым и ожидает обслуживания следующего соответствующего запроса функции db2_pconnect().

Пользователи, которые используют модуль ibm_db2 версии 1.9.0 или новее, должны знать, что модуль выполнит откат транзакции для постоянных соединений в конце запроса, чем завершит транзакцию. Это предотвращает перенос блока транзакции на следующий запрос, который использует это соединение, если выполнение скрипта завершается раньше, чем блок транзакции.

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

database

Для каталогизированного подключения к базе данных параметр database представляет псевдоним базы данных в клиентском каталоге БД DB2.

Для некаталогизированного подключения к базе данных параметр database представляет полную строку подключения в следующем формате:

DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password;

Замечание:
При подключении к БД Db2 на ОС IBM i базовая система вызывает функцию » SQLDriverConnect, которая принимает только имя источника данных DSN, идентификатор пользователя UID и пароль PWD для » строки подключения. Вот так:
DSN=database;UID=username;PWD=password;

где параметры представляют следующие значения:

database: Имя базы данных.
hostname: Имя хоста или IP-адрес сервера базы данных.
port: Порт TCP/IP, который используется базой данных для принятия запросов.
username: Имя пользователя, под которым выполняется подключение к базе данных.
password: Пароль, с которым выполняется подключение к базе данных.

username

Имя пользователя, под которым выполняется подключение к базе данных.

password

Пароль, который используется при подключении к базе данных.

options

Ассоциативный массив параметров подключения, которые влияют на поведение подключения, в котором допустимые ключи массива включают:

autocommit

Передача значения DB2_AUTOCOMMIT_ON включает автоматическую фиксацию для этого дескриптора соединения.

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

DB2_ATTR_CASE

Передача значения DB2_CASE_NATURAL указывает, что имена столбцов возвращаются в естественном регистре.

Передача значения DB2_CASE_LOWER указывает, что имена столбцов возвращаются в нижнем регистре.

Передача значения DB2_CASE_UPPER указывает, что имена столбцов возвращаются в верхнем регистре.

CURSOR

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

Передача значения DB2_SCROLLABLE задаёт прокручиваемый курсор для ресурса оператора. Этот режим включает произвольный доступ к строкам в наборе результатов, но пока поддерживается только СУБД DB2 Universal Database операционной системы IBM.

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

trustedcontext

Передача значения DB2_TRUSTED_CONTEXT_ENABLE включает доверенный контекст для этого дескриптора соединения. Параметр нельзя установить функцией db2_set_option().

Ключ работает только тогда, когда базу данных каталогизировали (даже если база данных локальная) или если указали полное DSN-имя при создании соединения.

Чтобы каталогизировать базу данных, вызывают следующие команды:

db2 catalog tcpip node loopback remote <SERVERNAME> server <SERVICENAME>
db2 catalog database <LOCALDBNAME> as <REMOTEDBNAME> at node loopback
db2 "update dbm cfg using svcename <SERVICENAME>"
db2set DB2COMM=TCPIP

Следующие новые параметры ОС i5/OS доступны в модуле ibm_db2 версии 1.5.1 и новее.

Подсказка

Конфликтующие атрибуты соединения, которые используются вместе с постоянными соединениями, могут привести к неопределённым результатам в ОС i5/OS. Требуется установить политики сайта для каждого приложения, которое использует каждый профиль пользователя с постоянным подключением. При работе с постоянными соединениями предлагается значение по умолчанию: DB2_AUTOCOMMIT_ON.

i5_lib

Символьное значение, которое указывает библиотеку по умолчанию, которая будет использоваться для разрешения неквалифицированных ссылок на файлы. Недопустимо, если соединение использует режим именования системы.

i5_naming

Значение DB2_I5_NAMING_ON включает режим именования системы DB2 UDB CLI iSeries. Файлы квалифицируются через разделитель в виде слеша (/). Неквалифицированные файлы разрешаются через список библиотек для задания.

Значение DB2_I5_NAMING_OFF отключает режим именования по умолчанию CLI DB2 UDB, который представляет собой именование SQL. Файлы квалифицируются через разделитель в виде точки (.). Неквалифицированные файлы разрешаются либо через библиотеки по умолчанию, либо через текущий идентификатор пользователя.

i5_commit

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

Замечание:
Параметр ibm_db2.i5_allow_commit==0 файла php.ini или параметр DB2_I5_TXN_NO_COMMIT — значение по умолчанию, но он доступен для изменения через параметр i5_commit.

DB2_I5_TXN_NO_COMMIT — Контроль фиксации не используется.

DB2_I5_TXN_READ_UNCOMMITTED — Грязное чтение, неповторимые reads, and phantoms are possible.

DB2_I5_TXN_READ_COMMITTED — Грязное чтение невозможно. Возможны неповторяющееся чтение и фантомы.

DB2_I5_TXN_REPEATABLE_READ — Грязное чтение и неповторяющиеся читки невозможны. Возможны фантомы.

DB2_I5_TXN_SERIALIZABLE — Транзакции сериализуемы. Грязное чтение, неповторяющееся чтение и фантомы невозможны.

i5_query_optimize

DB2_FIRST_IO Все запросы оптимизированы с целью максимально быстрого возврата первой страницы вывода. Эта цель хорошо работает, когда вывод контролируется пользователем, который, скорее всего, отменит запрос после просмотра первой страницы выходных данных. Запросы, закодированные с предложением OPTIMIZE FOR nnn ROWS, соответствуют цели, указанной в предложении.

DB2_ALL_IO Все запросы оптимизированы с целью выполнить весь запрос о завершения в кратчайшие сроки. Это хороший вариант, когда выходные данные запроса записываются в файл или отчёт или когда интерфейс ставит выходные данные в очередь. Запросы, закодированные с предложением OPTIMIZE FOR nnn ROWS, соответствуют цели, указанной в предложении. Это значение по умолчанию.

i5_dbcs_alloc

DB2_I5_DBCS_ALLOC_ON Значение включает схему распределения DB2 6X для увеличения размера столбца преобразования DBCS.

DB2_I5_DBCS_ALLOC_OFF Значение выключает схему распределения DB2 6X для увеличения размера столбца преобразования DBCS.

Замечание:
Параметр ibm_db2.i5_dbcs_alloc==0 файла php.ini или параметр DB2_I5_DBCS_ALLOC_OFF — значение по умолчанию, но его можно изменить через параметр i5_dbcs_alloc.

i5_date_fmt

DB2_I5_FMT_ISO — Формат даты Международной организации по стандартизации ISO yyyy-mm-dd. Это значение по умолчанию.

DB2_I5_FMT_USA — Формат даты США mm/dd/yyyy.

DB2_I5_FMT_EUR — Европейский формат даты dd.mm.yyyy.

DB2_I5_FMT_JIS — Японский формат даты yyyy-mm-dd.

DB2_I5_FMT_MDY — Формат даты mm/dd/yyyy.

DB2_I5_FMT_DMY — Формат даты dd/mm/yyyy.

DB2_I5_FMT_YMD — Формат даты yy/mm/dd.

DB2_I5_FMT_JUL — Используется юлианский формат даты yy/ddd.

DB2_I5_FMT_JOB — Используется задание по умолчанию.

i5_date_sep

DB2_I5_SEP_SLASH — Разделитель даты — слеш (/). Это значение по умолчанию.

DB2_I5_SEP_DASH — Разделитель даты — дефис (-).

DB2_I5_SEP_PERIOD — Разделитель даты — точка (.).

DB2_I5_SEP_COMMA — Разделитель даты — запятая (,).

DB2_I5_SEP_BLANK — Разделитель даты — пробел.

DB2_I5_SEP_JOB — Задание по умолчанию.

i5_time_fmt

DB2_I5_FMT_ISO — Формат времени Международной организации по стандартизации ISO hh.mm.ss. Это значение по умолчанию.

DB2_I5_FMT_USA — Формат времени США hh:mmxx, где xx — это AM или PM.

DB2_I5_FMT_EUR — Европейский формат времени hh.mm.ss.

DB2_I5_FMT_JIS — Японский промышленный стандартный формат времени hh:mm:ss.

DB2_I5_FMT_HMS — Формат hh:mm:ss.

i5_time_sep

DB2_I5_SEP_COLON — Разделитель времени — двоеточие (:). Это значение по умолчанию.

DB2_I5_SEP_PERIOD — Разделитель времени — точка (.).

DB2_I5_SEP_COMMA — Разделитель времени — запятая (,).

DB2_I5_SEP_BLANK — Разделитель времени — пробел.

DB2_I5_SEP_JOB — Задание по умолчанию.

i5_decimal_sep

DB2_I5_SEP_PERIOD — Десятичный разделитель — точка (.). Это значение по умолчанию.

DB2_I5_SEP_COMMA — Десятичный разделитель — запятая (,).

DB2_I5_SEP_JOB — Задание по умолчанию.

Следующая новая опция ОС i5/OS доступна в модуле ibm_db2 версии 1.8.0 и новее.

i5_libl

Символьное значение, которое указывает список библиотек, через которые будут разрешаться неквалифицированные ссылки на файлы. Элементы списка библиотек указывают через пробелы: 'i5_libl'=>"MYLIB YOURLIB ANYLIB".

Замечание:
Библиотека i5_libl вызывает qsys2/qcmdexc ('cmd',cmdlen), который доступен только в ОС i5/OS V5R4 и новее.

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

Функция возвращает ресурс дескриптора подключения в случае успешной попытки подключения. Функция db2_pconnect() пытается переиспользовать существующий ресурс подключения, который точно соответствует параметрам database, username и password. Функция db2_pconnect() возвращает false, если возникла ошибка подключения.

Список изменений

Версия	Описание
PECL-модуль ibm_db2 1.9.0	Активные транзакции в постоянном соединении будут откатываться в конце каждого запроса.
PECL-модуль ibm_db2 1.8.0	Параметр `i5_libl` доступен пользователям i5/OS.
PECL-модуль ibm_db2 1.7.0	Доступен параметр `trustedcontext`.
PECL-модуль ibm_db2 1.5.1	Параметры `i5_lib`, `i5_naming`, `i5_commit`, `i5_query_optimize`, `i5_dbcs_alloc`, `i5_date_fmt`, `i5_date_sep`, `i5_time_fmt`, `i5_time_sep` и `i5_decimal_sep` доступны для пользователей i5/OS.

Примеры

Пример #1 Пример возврата постоянного соединения с базой данных функцией db2_pconnect()

В следующем примере первый вызов функции db2_pconnect() возвращает новый ресурс постоянного соединения. Второй вызов функции db2_pconnect() возвращает ресурс постоянного соединения, который просто переиспользует первый ресурс постоянного соединения.

<?php

$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

$pconn = db2_pconnect($database, $user, $password);

if ($pconn) {
    echo "Постоянное соединение успешно установилось.";
} else {
    echo "Постоянное соединение завершилось ошибкой.";
}

$pconn2 = db2_pconnect($database, $user, $password);

if ($pconn) {
    echo "Второе постоянное соединение успешно установилось.";
} else {
    echo "Второе постоянное соединение завершилось ошибкой";
}

?>

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

Постоянное соединение успешно установилось.
Второе постоянное соединение успешно установилось.

Пример #2 Пример работы с доверенным контекстом

Следующий пример показывает, как включить доверенный контекст, переключить пользователей и получить текущий идентификатор пользователя.

<?php

$database = "SAMPLE";
$hostname = "localhost";
$port = 50000;
$authID = "db2inst1";
$auth_pass = "ibmdb2";

$tc_user = "tcuser";
$tc_pass = "tcpassword";

$dsn = "DATABASE=$database;HOSTNAME=$hostname;PORT=$port;"
    . "PROTOCOL=TCPIP;UID=$authID;PWD=$auth_pass;";

$options = array("trustedcontext" => DB2_TRUSTED_CONTEXT_ENABLE);


$tc_conn = db2_pconnect($dsn, "", "", $options);
if ($tc_conn) {
    echo "Явное доверенное соединение успешно установилось.\n";

    if (db2_get_option($tc_conn, "trustedcontext")) {
        $userBefore = db2_get_option($tc_conn, "trusted_user");

        // Поработайте как пользователь 1.

        // Переход на доверенного пользователя
        $parameters = array(
            "trusted_user" => $tc_user,
            "trusted_password" => $tcuser_pass
        );

        $res = db2_set_option($tc_conn, $parameters, 1);

        $userAfter = db2_get_option($tc_conn, "trusted_user");
        // Сделайте больше в качестве доверенного пользователя.

        if ($userBefore != $userAfter) {
            echo "Пользователь переключился." . "\n";
        }
    }

    db2_close($tc_conn);
} else {
    echo "Явное доверенное соединение завершилось ошибкой.\n";
}

?>

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

Явное доверенное соединение успешно установилось
Пользователь переключился.

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

db2_connect() - Возвращает соединение с базой данных