db2_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — データベースへの接続を返す

説明

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

IBM DB2 Universal Database、IBM Cloudscape あるいは Apache Derby データベースへの新しい接続を作成します。

パラメータ

database

データベースへのカタログ接続の場合には、database は DB2 クライアントカタログ内でのデータベースエイリアスを表します。

データベースへの非カタログ接続の場合には、 database は以下のような形式の接続文字列を表します。

DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;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 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_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 は、 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 - ピリオド ( . ) を日付の区切り文字として使用します。

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 以降でのみ使用可能です。

戻り値

接続に成功した場合は接続ハンドルリソースを返します。接続に失敗した場合は、db2_connect() は false を返します。

例

例1 カタログ接続の作成

カタログ接続を行うには、DB2 コマンドラインプロセッサ (CLP) あるいは DB2 Configuration Assistant を使用して事前に対象データベースをカタログしておく必要があります。

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

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

if ($conn) {
    echo "接続に成功しました。";
    db2_close($conn);
}
else {
    echo "接続に失敗しました。";
}
?>

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

接続に成功しました。

例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 "接続に失敗しました。";
}
?>

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

接続に成功しました。

例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 "接続に失敗しました。";
}
?>

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

接続に成功しました。
自動コミットは無効です。

例4 i5/OS best performance

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 "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_close() - データベース接続を閉じる
db2_pconnect() - データベースへの持続的接続を返す

add a note

User Contributed Notes 1 note

down

d dot lanza38 at gmail dot com ¶

9 years ago


As of 09/29/2015 when using the ibm_db2 driver and specifying an invalid library list with the 'i5_libl' option, the connection will be successfully created but with a default library list.  What happens is the connection is made and THEN the library list is attempted to be changed.  The connection will be a success but the library list change will fail without "db2_conn_error()" or "db2_conn_errormsg()" reporting anything and a default library list will be used.  However, "db2_stmt_error()" and "db2_stmt_errormsg()" will register with a value.  Also if error reporting is enable, the warning will be output to the screen.  This is not a bug, rather intended behavior according to Zend (I opened a ticked) and depending on which library list is used/swapped could lead to major problems (development VS production).  I stumbled upon this behavior when an anomaly (which I still can't explain) was imploding my library list with the character 'Z'.  I realized I was in my development environment but accessing production data as a result.  Going forward I will make sure to add this additional check for good measure.

See below to recreate behavior:

<?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);
//This line causes "ini_set("display_errors", 1)" to dislay this warning on the screen:
//Warning: db2_connect(): Statement Execute Failed in /PATH/TO/FILE/test.php on line 58

if (db2_stmt_error()) { //Evaluates to true
    echo "error ID: " . (db2_stmt_error()); //Displays error code: 38501
    echo "<br>error message: " . (db2_stmt_errormsg()); //Displays: Trigger program or external routine detected an error. SQLCODE=-443
}

echo "<br />|".db2_conn_error()." ||| ".db2_conn_errormsg()."|<br />"; //Only "| ||| |" is displayed
print_r($conn); //A resource ID is displayed
echo "<br />";

if(isset($conn) && $conn === true){
    echo "Boolean true<br />";
    //never executes, but not expected since either false or a resource ID should be returned.
    //Plus it is clear $conn contains a resource ID from above.
}
if(isset($conn) && $conn == true){
    echo "Non-Boolean true 2<br />"; 
    //This always executes regardless of an accurate library list or not
    //I suppose "if($conn)" would evaluate to non-boolean true so this makes sense.
}
if(isset($conn) && $conn == "true"){
    echo "String true";
    //Never executes, but not expected.
}
if(isset($conn) && $conn === false){
    echo "Boolean false<br />";
    //never executes because the connection itself was a success.
    //If invalid credentials were provided this executes.
}
if(isset($conn) && $conn == false){
    echo "Non-Boolean false 2<br />";
    //never executes because the connection itself was a success.
    //Added this here because I was unsure if a boolean false would be returned or not.
    //If invalid credentials were provided this executes as well.
}
if(isset($conn) && $conn == "false"){
    echo "String false";
    //never executes because the connection itself was a success.
    //Added this here because I was unsure if a String "false" would be returned
}
?>

add a note