説明

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 だけを » connection string として受け入れます。たとえば以下のようになります:
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 は、 DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを有効にします。

DB2_I5_DBCS_ALLOC_OFF は、 DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを無効にします。

注意: 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 - 日本工業規格 (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 - ピリオド ( . ) を日付の区切り文字として使用します。 separator. 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 - 日本工業規格 (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 以降でのみ使用可能です。

戻り値

接続に成功した場合は接続ハンドルリソースを返します。パラメータ database、username および password に完全に一致する接続が既に存在した場合、db2_pconnect() はそれを再利用します。接続に失敗した場合は db2_pconnect() は false を返します。

変更履歴

バージョン	説明
PECL ibm_db2 1.9.0	持続的接続上のアクティブなトランザクションは、各接続の終了時にロールバックされるようになりました。
PECL ibm_db2 1.8.0	i5/OS ユーザーは `i5_libl` オプションが使えるようになりました。
PECL ibm_db2 1.7.0	`trustedcontext` オプションが使えるようになりました。
PECL 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 "2 回目の持続的接続に成功しました。";
}
else {
    echo "2 回目の持続的接続に失敗しました。";
}
?>

上の例の出力は以下となります。

持続的接続に成功しました。
2 回目の持続的接続に成功しました。

例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 "Explicit trusted connection succeeded.\n";

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

        // 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 "User has been switched." . "\n";
        }
    }

    db2_close($tc_conn);
}
else {
    echo "Explicit trusted connection failed.\n";
}
?>

上の例の出力は以下となります。

Explicit trusted connection succeeded.
User has been switched.

参考

db2_connect() - データベースへの接続を返す