db2_pclose
db2_prepare
IBM DB2 関数
PHP Manual

# db2_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — データベースへの持続的接続を返す

### 説明

resource db2_pconnect ( string `$database` , string `$username` , string `$password` [, array `$options` ] )

IBM DB2 Universal Database、IBM Cloudscape あるいは Apache Derby データベースへの持続的接続を返します。 持続的接続についての詳細な情報は、 持続的データベース接続 を参照ください。

持続的接続に対して db2_close() をコールすると、 常に `TRUE` を返します。しかし DB2 クライアント接続はオープンされたままであり、 条件に一致する次の db2_pconnect() リクエストを待ち続けます。

### パラメータ

`database`

  DB2 クライアントカタログ内のデータベースエイリアス。

`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` を返します。

### 例

例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() - データベースへの接続を返す

db2_pclose
db2_prepare
IBM DB2 関数
PHP Manual