db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — 返回与数据库的连接

描述

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

创建一个到 IBM DB2 通用数据库、IBM Cloudscape 或 Apache Derby 数据库的新连接。

参数

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

您用于连接到数据库的用户名。

对于非目录连接，您必须传递一个 null 值或空字符串。

password

您用于连接到数据库的密码。

对于非目录连接，您必须传递一个 null 值或空字符串。

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 通用数据库支持。

以下新选项在 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_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_connect() 之前设置。如果在连接建立后更改该值，并且连接到远程数据源，则更改直到下次成功 db2_connect() 用于连接句柄时才会生效。

注意:
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_connect() 将返回 false。

示例

示例 #1 创建已编目连接

已编目连接要求您之前已通过 DB2 命令行处理器 (CLP) 或 DB2 配置助手编目目标数据库。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

$conn = db2_connect($database, $user, $password);

if ($conn) {
 echo "连接成功.";
 db2_close($conn);
}
else {
 echo "连接失败.";
}
?>

上面的示例将输出

Connection succeeded.

示例 #2 创建未编目连接

未编目连接使您能够动态连接到数据库。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$hostname = 'localhost';
$port = 50000;

$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;" .
 "HOSTNAME=$hostname;PORT=$port;PROTOCOL=TCPIP;UID=$user;PWD=$password;";
$conn = db2_connect($conn_string, '', '');

if ($conn) {
 echo "连接成功.";
 db2_close($conn);
}
else {
 echo "连接失败.";
}
?>

上面的示例将输出

Connection succeeded.

示例 #3 创建默认情况下自动提交关闭的连接

将选项数组传递给 db2_connect() 使您能够修改连接句柄的默认行为。

<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

$conn = db2_connect($database, $user, $password, $options);

if ($conn) {
 echo "连接成功。\n";
 if (db2_autocommit($conn)) {
 echo "自动提交已开启。\n";
 }
 else {
 echo "自动提交已关闭。\n";
 }
 db2_close($conn);
}
else {
 echo "连接失败.";
}
?>

上面的示例将输出

Connection succeeded.
Autocommit is off.

示例 #4 i5/OS 最佳性能

要为您的 i5/OS ibm_db2 1.5.1 PHP 应用程序实现最佳性能，请使用 db2_connect() 的默认主机、用户 ID 和密码。

<?php
 $library = "ADC";
 $i5 = db2_connect("", "", "", array("i5_lib"=>"qsys2"));
 $result = db2_exec($i5,
 "select * from systables where table_schema = '$library'");
 while ($row = db2_fetch_both($result)) {
 echo $row['TABLE_NAME']."</br>";
 }
 db2_close($i5);
?>

上面的示例将输出

ANIMALS
NAMES
PICTURES

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

以下示例演示如何启用受信任的上下文、切换用户并获取当前用户 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_connect($dsn, "", "", $options);
if($tc_conn) {
 echo "显式可信连接成功。\n";

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

 // 以用户 1 的身份执行一些操作。\n\n // 切换到可信用户。\n $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");
 // 以可信用户的身份执行更多操作。\n\n if($userBefore != $userAfter) {
 echo "用户已切换。" . "\n";
 }
 }

 db2_close($tc_conn);
}
else {
 echo "显式可信连接失败。\n";
}
?>

上面的示例将输出

Explicit trusted connection succeeded.
User has been switched.

另请参阅

db2_close() - 关闭数据库连接
db2_pconnect() - 返回到数据库的持久连接

改进此页面

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

＋添加注释

用户贡献的注释 1 条注释

向上

向下

d dot lanza38 at gmail dot com ¶

8 年前

截至 2015 年 9 月 29 日，当使用 ibm_db2 驱动程序并使用 'i5_libl' 选项指定无效的库列表时，连接将成功创建，但使用默认库列表。发生的情况是，连接被建立，然后尝试更改库列表。连接将成功，但库列表更改将失败，而不会报告任何 "db2_conn_error()" 或 "db2_conn_errormsg()"，并且将使用默认库列表。但是，"db2_stmt_error()" 和 "db2_stmt_errormsg()" 将注册一个值。另外，如果启用错误报告，则警告将输出到屏幕。这不是 bug，而是 Zend 的预期行为（我打开了一个票证），并且根据使用/交换的库列表，可能会导致重大问题（开发与生产）。当我发现一个异常（我仍然无法解释）使用字符 'Z' 使我的库列表爆炸时，我偶然发现了这种行为。我意识到我在开发环境中，但因此访问了生产数据。今后，我将确保添加此额外检查以确保万无一失。

请参阅以下内容以重现行为

<?php
ini_set("display_errors", 1);

$systemName = 'systemName';
$userID = 'userName';
$password = 'password';

$options['i5_libl'] = implode('Z', array(
 'INVALID', 
 'LIB', 
 'LIST', 
 'IMPLODED', 
 'WITH', 
 'THE', 
 'LETTER', 
 'Z'
 ));

$options['i5_naming'] = DB2_I5_NAMING_ON;

$conn = db2_connect($systemName, $userID, $password, $options);
// 此行导致 "ini_set("display_errors", 1)" 在屏幕上显示此警告：\n// 警告：db2_connect()：语句执行失败，位于 /PATH/TO/FILE/test.php 的第 58 行\n\nif (db2_stmt_error()) { // 评估为 true\n echo "错误 ID： " . (db2_stmt_error()); // 显示错误代码：38501\n echo "<br>错误消息： " . (db2_stmt_errormsg()); // 显示：触发程序或外部例程检测到错误。SQLCODE=-443\n}

echo "<br />|".db2_conn_error()." ||| ".db2_conn_errormsg()."|<br />"; // 仅显示 "| ||| |"\nprint_r($conn); // 显示资源 ID\necho "<br />";

if(isset($conn) && $conn === true){
 echo "布尔值 true<br />";
 // 从未执行，但并不意外，因为应该返回 false 或资源 ID。\n // 另外，很明显 $conn 包含来自上面的资源 ID。\n}
if(isset($conn) && $conn == true){
 echo "非布尔值 true 2<br />"; 
 // 无论库列表是否准确，这始终执行\n // 我想 "if($conn)" 将评估为非布尔值 true，因此这是有道理的。\n}
if(isset($conn) && $conn == "true"){
 echo "字符串 true";
 // 从未执行，但并不意外。\n}
if(isset($conn) && $conn === false){
 echo "布尔值 false<br />";
 // 从未执行，因为连接本身成功。\n // 如果提供无效的凭据，则执行此操作。\n}
if(isset($conn) && $conn == false){
 echo "非布尔值 false 2<br />";
 // 从未执行，因为连接本身成功。\n // 添加到这里是因为我不确定是否会返回布尔值 false。\n // 如果提供无效的凭据，则也执行此操作。\n}
if(isset($conn) && $conn == "false"){
 echo "字符串 false";
 // 从未执行，因为连接本身成功。\n // 添加到这里是因为我不确定是否会返回字符串 "false"\n}
?>

＋添加注释