db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — 返回到数据库的持久连接

说明

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;

注意:
当连接到 IBM i 上的 Db2 时，底层系统调用 » 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 值指定语句资源的可滚动游标。此模式允许对结果集中的行进行随机访问，但目前仅由 IBM DB2 Universal Database 支持。

以下新选项在 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 值关闭 DB2 UDB CLI 默认命名模式，即 SQL 命名。文件使用句点 (.) 分隔符进行限定。未限定的文件使用默认库或当前用户 ID 进行解析。

i5_commit

i5_commit 属性应在 db2_pconnect() 之前设置。如果在连接建立后更改该值，并且连接到远程数据源，则更改直到下一个成功的 db2_pconnect() 用于连接句柄时才会生效。

注意:
php.ini 设置 ibm_db2.i5_allow_commit==0 或 DB2_I5_TXN_NO_COMMIT 是默认值，但可以使用 i5_commit 选项覆盖。

DB2_I5_TXN_NO_COMMIT - 不使用提交控制。

DB2_I5_TXN_READ_UNCOMMITTED - 脏读、不可重复读和幻读是可能的。

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 翻译列大小增长分配的方案。

注意:
php.ini 设置 ibm_db2.i5_dbcs_alloc==0 或 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。

变更日志

版本	说明
ibm_db2 1.9.0	持久连接中的活动事务将在每个请求结束时回滚。
ibm_db2 1.8.0	i5/OS 用户可以使用 `i5_libl` 选项。
ibm_db2 1.7.0	可以使用 `trustedcontext` 选项。
ibm_db2 1.5.1	i5/OS 用户可以使用 `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` 选项。

示例

示例 #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 "第二次持久连接失败。";
}
?>

上面的示例将输出

Persistent connection succeeded.
Second persistent connection succeeded.

示例 #2 使用受信任的上下文

以下示例演示如何启用受信任的上下文，切换用户并获取当前用户 ID。

<?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";
}
?>

上面的示例将输出

Explicit trusted connection succeeded.
User has been switched.

另请参阅

db2_connect() - 返回到数据库的连接

改进此页面

了解如何改进此页面 • 提交拉取请求 • 报告错误

＋添加备注

用户贡献备注 2 则备注

上移

下移

satoruyoshida at php dot net ¶

12 年前

如果要在 IBMi 上创建 db2 连接，则将在 QSYSWRK 子系统下创建 QSQSRVR 作业，并使用指定的用户。
您可以使用 db2_pconnect() 函数确保这一点。

例如，db2_pconnect('*LOCAL', 'TESTUSR', 'PASSWORD') 将为我们带来使用 TESTUSR 用户的 QSQSRVR 作业。

如果您省略用户，则作业将使用 IHS 默认用户。

上移

下移

php at redlagoon dot net ¶

6 年前

ibm_db2.ini 文件控制许多与 pconnect 相关的属性。例如，可以配置过时连接处理。