2024 年 PHP 日本大会

    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

    ibm_db2 1.5.1 及更高版本提供了以下新的 i5/OS 选项：

    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身份执行某些操作。

    //切换到可信用户。
    $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.

    另请参见

    发现问题？

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

    用户贡献的备注 1 条备注

    2
    d dot lanza38 at gmail dot com
    9 年前
    截至 2015 年 9 月 29 日，当使用 ibm_db2 驱动程序并使用 'i5_libl' 选项指定无效的库列表时，连接将成功创建，但使用默认库列表。发生的情况是建立连接，然后尝试更改库列表。连接将成功，但库列表更改将失败，而不会报告任何“db2_conn_error()”或“db2_conn_errormsg()”，并且将使用默认库列表。但是，“db2_stmt_error()”和“db2_stmt_errormsg()”将注册一个值。此外，如果启用错误报告，则警告将输出到屏幕。这并非错误，而是 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)”在屏幕上显示此警告：
    //警告：db2_connect(): 语句执行失败 in /PATH/TO/FILE/test.php on line 58

    if (db2_stmt_error()) { //计算结果为真
    echo "错误 ID： " . (db2_stmt_error()); //显示错误代码：38501
    echo "<br>错误消息： " . (db2_stmt_errormsg()); //显示：触发程序或外部例程检测到错误。SQLCODE=-443
    }

    echo     "<br />|".db2_conn_error()." ||| ".db2_conn_errormsg()."|<br />"; //仅显示“| ||| |”
    print_r($conn); //显示资源 ID
    echo "<br />";

    if(isset(    $conn) && $conn === true){
    echo     "布尔值 true<br />";
    //从不执行，但并非预期，因为应该返回 false 或资源 ID。
    //此外，从上面可以清楚地看到 $conn 包含资源 ID。
    }
    if(isset(    $conn) && $conn == true){
    echo     "非布尔值 true 2<br />";
    //无论库列表是否准确，这始终都会执行
    //我想“if($conn)”将计算为非布尔值 true，所以这是有道理的。
    }
    if(isset(    $conn) && $conn == "true"){
    echo     "字符串 true";
    //从不执行，但并非预期。
    }
    if(isset(    $conn) && $conn === false){
    echo     "布尔值 false<br />";
    //从不执行，因为连接本身成功。
    //如果提供无效的凭据，则执行此操作。
    }
    if(isset(    $conn) && $conn == false){
    echo     "非布尔值 false 2<br />";
    //从不执行，因为连接本身成功。
    //我在这里添加了这个，因为我不确定是否会返回布尔值 false。
    //如果提供无效的凭据，则也执行此操作。
    }
    if(isset(    $conn) && $conn == "false"){
    echo     "字符串 false";
    //从不执行，因为连接本身成功。
    //我在这里添加了这个，因为我不确定是否会返回字符串“false”
    }
    ?>
    ＋添加备注
    To Top