db2_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — 接続リソースあるいはステートメントリソースのオプションを設定する

説明

db2_set_option(resource $resource, array $options, int $type): bool

ステートメントリソースあるいは接続リソースのオプションを設定します。結果セットリソースのオプションを設定することはできません。

パラメータ

resource

db2_prepare() が返す有効なステートメントリソースか、あるいは db2_connect() や db2_pconnect() が返す有効な接続リソース。

options

ステートメントあるいは接続のオプションを含む連想配列。このパラメータは、自動コミットの値を変更したりカーソルの型を (スクロール可能、あるいは前進のみに) 変更したり、結果セットに表示されるカラム名を (小文字、大文字、あるいは元のままに) 設定したりする際に使用します。

autocommit: DB2_AUTOCOMMIT_ON を渡すと、指定した接続リソースの自動コミットをオンにします。 DB2_AUTOCOMMIT_OFF を渡すと、指定した接続リソースの自動コミットをオフにします。
cursor: DB2_FORWARD_ONLY を渡すと、ステートメントリソースに前進のみのカーソルを指定します。これはデフォルトのカーソル型であり、すべてのデータベースサーバーでサポートされています。 DB2_SCROLLABLE を渡すと、ステートメントリソースにスクロール可能なカーソルを指定します。このカーソルは、順番どおり以外の方法で結果セットの行にアクセス可能です。しかし、IBM DB2 Universal Database でしかサポートされていません。
binmode: DB2_BINARY を渡すと、バイナリデータがそのままの形式で返されるようになります。これはデフォルトのモードです。php.ini で ibm_db2.binmode=1 とするのと同じことです。 DB2_CONVERT を渡すと、バイナリデータを十六進エンコーディングで変換して返します。これは、php.ini で ibm_db2.binmode=2 とするのと同じことです。 DB2_PASSTHRU を渡すと、バイナリデータを null に変換するようになります。これは php.ini で ibm_db2.binmode=3 とするのと同じことです。
db2_attr_case: DB2_CASE_LOWER を渡すと、結果セットのカラム名を小文字で返します。 DB2_CASE_UPPER を渡すと、結果セットのカラム名を大文字で返します。 DB2_CASE_NATURAL を渡すと、結果セットのカラム名をそのまま何もせずに返します。
deferred_prepare: DB2_DEFERRED_PREPARE_ON を渡すと、指定したステートメントリソースについて遅延プリペアを有効にします。 DB2_DEFERRED_PREPARE_OFF を渡すと、指定したステートメントリソースについて遅延プリペアを無効にします。

以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.5.1 以降で使用可能です。これらのオプションが適用されるのは、PHP と ibm_db2 が i5 システム上でネイティブに動作している場合のみです。

i5_fetch_only: DB2_I5_FETCH_ON - カーソルは読み込み専用となり、場所を指定しての更新や削除には使用できません。これは、SQL_ATTR_FOR_FETCH_ONLY が SQL_FALSE に設定されていない場合のデフォルト設定です。 DB2_I5_FETCH_OFF - カーソルは、場所を指定しての更新や削除に使用できるようになります。

以下の新しいオプションが、ibm_db2 バージョン 1.8.0 以降で使用可能です。

rowcount: DB2_ROWCOUNT_PREFETCH_ON - クライアントは、取得する前に全行数を問い合わせることができます。つまり、 ROLLFORWARD_ONLY カーソルを使っている場合でも選択された行数を db2_num_rows() で取得することができます。 DB2_ROWCOUNT_PREFETCH_OFF - クライアントは、取得する前に全行数を問い合わせることができません。

以下の新しいオプションが、ibm_db2 バージョン 1.7.0 以降で使用可能です。

trusted_user: ユーザーを信頼済みユーザーに変更する際に、信頼済みユーザーのユーザー ID (文字列) をこのキーの値として渡します。このオプションは、接続リソース上でのみ設定可能です。このオプションを使用するには、信頼済みコンテキストを接続リソース上で有効にしなければなりません。
trusted_password: trusted_user キーで指定したユーザーに対応するパスワード (文字列)。

以下の新しいオプションが、ibm_db2 バージョン 1.6.0 以降で使用可能です。これらは、有用な情報を提供します。これらの情報は、 db2_get_option() によって取得します。

注意: 各オプションの値を設定する際、サーバーによっては指定したすべての内容を処理できないことがあります。その場合、値が切り詰められます。指定したオプションが正しく変換されてホストシステムに送信されることを確実にするには、 A から Z までの文字と 0 から 9 までの数字、そしてアンダースコア (_) とピリオド (.) のみを使用するようにします。

userid

SQL_ATTR_INFO_USERID - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信するクライアントのユーザー ID として使用します。

注意: z/OS および OS/390 サーバー版の DB2 は 16 文字までの長さをサポートしています。このユーザー ID を、認証時に使用するユーザー ID と混同しないでください。これは識別のためだけに使用するものであり、認証には用いられません。

acctstr

SQL_ATTR_INFO_ACCTSTR - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信するクライアントのアカウンティング・ストリングとして使用します。

注意: z/OS および OS/390 サーバー版の DB2 は 200 文字までの長さをサポートしています。

applname

SQL_ATTR_INFO_APPLNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信するクライアントのアプリケーション名として使用します。

注意: z/OS および OS/390 サーバー版の DB2 は 32 文字までの長さをサポートしています。

wrkstnname

SQL_ATTR_INFO_WRKSTNNAME - ヌル終端の文字列へのポインタで、DB2 接続の際にホストデータベースサーバーに送信するクライアントのワークステーション名として使用します。

注意: z/OS および OS/390 サーバー版の DB2 は 18 文字までの長さをサポートしています。

type

この関数に渡すリソースの型を、整数値で指定します。リソースの型とこの値は必ず一致していなければなりません。 1 は、接続リソースがこの関数に渡されることを表します。 1 以外の整数を指定すると、ステートメントリソースがこの関数に渡されることを表します。

次の表は、それぞれのオプションがどのリソース型で使用可能かをまとめたものです。
リソースとパラメータの対応

キー値リソースの型

接続ステートメント結果セット

autocommit DB2_AUTOCOMMIT_ON X - -

autocommit DB2_AUTOCOMMIT_OFF X - -

cursor DB2_SCROLLABLE - X -

cursor DB2_FORWARD_ONLY - X -

binmode DB2_BINARY X X -

binmode DB2_CONVERT X X -

binmode DB2_PASSTHRU X X -

db2_attr_case DB2_CASE_LOWER X X -

db2_attr_case DB2_CASE_UPPER X X -

db2_attr_case DB2_CASE_NATURAL X X -

deferred_prepare DB2_DEFERRED_PREPARE_ON - X -

deferred_prepare DB2_DEFERRED_PREPARE_OFF - X -

i5_fetch_only DB2_I5_FETCH_ON - X -

i5_fetch_only DB2_I5_FETCH_OFF - X -

rowcount DB2_ROWCOUNT_PREFETCH_ON - X -

rowcount DB2_ROWCOUNT_PREFETCH_OFF - X -

trusted_user <USER NAME> (文字列) X - -

trusted_password <PASSWORD> (文字列) X - -

userid SQL_ATTR_INFO_USERID X X -

acctstr SQL_ATTR_INFO_ACCTSTR X X -

applname SQL_ATTR_INFO_APPLNAME X X -

wrkstnname SQL_ATTR_INFO_WRKSTNNAME X X -

**リソースとパラメータの対応**
キー	値	リソースの型
		接続	ステートメント	結果セット
autocommit	`DB2_AUTOCOMMIT_ON`	X	-	-
autocommit	`DB2_AUTOCOMMIT_OFF`	X	-	-
cursor	`DB2_SCROLLABLE`	-	X	-
cursor	`DB2_FORWARD_ONLY`	-	X	-
binmode	`DB2_BINARY`	X	X	-
binmode	`DB2_CONVERT`	X	X	-
binmode	`DB2_PASSTHRU`	X	X	-
db2_attr_case	`DB2_CASE_LOWER`	X	X	-
db2_attr_case	`DB2_CASE_UPPER`	X	X	-
db2_attr_case	`DB2_CASE_NATURAL`	X	X	-
deferred_prepare	`DB2_DEFERRED_PREPARE_ON`	-	X	-
deferred_prepare	`DB2_DEFERRED_PREPARE_OFF`	-	X	-
i5_fetch_only	`DB2_I5_FETCH_ON`	-	X	-
i5_fetch_only	`DB2_I5_FETCH_OFF`	-	X	-
rowcount	`DB2_ROWCOUNT_PREFETCH_ON`	-	X	-
rowcount	`DB2_ROWCOUNT_PREFETCH_OFF`	-	X	-
trusted_user	`<USER NAME> (文字列)`	X	-	-
trusted_password	`<PASSWORD> (文字列)`	X	-	-
userid	`SQL_ATTR_INFO_USERID`	X	X	-
acctstr	`SQL_ATTR_INFO_ACCTSTR`	X	X	-
applname	`SQL_ATTR_INFO_APPLNAME`	X	X	-
wrkstnname	`SQL_ATTR_INFO_WRKSTNNAME`	X	X	-

戻り値

成功した場合に true を、失敗した場合に false を返します。

例

例1 接続リソースにひとつのパラメータを設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_ON);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

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

オプションの設定に成功しました

例2 接続リソースに複数のパラメータを設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                    'binmode' => DB2_PASSTHRU,
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

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

オプションの設定に成功しました

例3 複数のパラメータを間違ったキーで設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
             'MY_INVALID_KEY' => DB2_PASSTHRU,
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

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

オプションが設定できませんでした

例4 複数のパラメータを間違った値で設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                    'binmode' => 'INVALID_VALUE',
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

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

オプションが設定できませんでした

例5 複数のパラメータを接続リソースに設定する (間違った型を指定する)

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                    'binmode' => DB2_PASSTHRU,
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

/* 正しいリソースとオプションの配列、そして間違った型を表す値を指定して関数をコールします */
$result = db2_set_option($conn, $options, 2);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

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

オプションが設定できませんでした

例6 複数のパラメータを間違ったリソースに設定する

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
                    'binmode' => DB2_PASSTHRU,
              'db2_attr_case' => DB2_CASE_UPPER,
                     'cursor' => DB2_SCROLLABLE);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');

/* 間違ったリソース、そして正しいオプションの配列と型を表す値を指定して関数をコールします */
$result = db2_set_option($stmt, $options, 1);

/* すべてのオプションが正しく設定できたかどうかを調べます */
if($result)
{
  echo 'オプションの設定に成功しました';
}
else
{
  echo 'オプションが設定できませんでした';
}
?>

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

オプションが設定できませんでした

例7 すべてひとつにまとめる

<?php
/* データベース接続用のパラメータ */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';

/* 接続文字列 */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";

/* 接続リソースを取得します */
$conn = db2_connect($conn_string, '', '');

/* 有効なキーと値を使用して、オプションの連想配列を作成します */
$options = array('db2_attr_case' => DB2_CASE_LOWER,
                        'cursor' => DB2_SCROLLABLE);

$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO = ?');

/* 正しいリソースとオプションの配列、そして型を表す値を指定して関数をコールします */
$option_result = db2_set_option($stmt, $options, 2);
$result = db2_execute($stmt, array('000130', '000140'));

/* スクロール可能なカーソルのため、1 行目より先に 2 行目を取得します */
print_r(db2_fetch_assoc($stmt, 2));
print '<br /><br />';
print_r(db2_fetch_assoc($stmt, 1));

?>

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

Array
(
    [empno] => 000140
    [firstnme] => HEATHER
    [midinit] => A
    [lastname] => NICHOLLS
    [workdept] => C01
    [phoneno] => 1793
    [hiredate] => 1976-12-15
    [job] => ANALYST
    [edlevel] => 18
    [sex] => F
    [birthdate] => 1946-01-19
    [salary] => 28420.00
    [bonus] => 600.00
    [comm] => 2274.00
)

Array
(
    [empno] => 000130
    [firstnme] => DELORES
    [midinit] => M
    [lastname] => QUINTANA
    [workdept] => C01
    [phoneno] => 4578
    [hiredate] => 1971-07-28
    [job] => ANALYST
    [edlevel] => 16
    [sex] => F
    [birthdate] => 1925-09-15
    [salary] => 23800.00
    [bonus] => 500.00
    [comm] => 1904.00
)

例8 i5/OS カーソルは読み込み専用

<?php
  $conn = db2_connect("", "", "", array("i5_lib"=>"nobody"));
  $stmt = db2_prepare($conn, 'select * from names where first = ?');
  $name = "first2";
  db2_bind_param($stmt, 1, "name", DB2_PARAM_IN);
  $options = array("i5_fetch_only"=>DB2_I5_FETCH_ON);
  db2_set_option($stmt,$options,0);
  if (db2_execute($stmt)) {
    while ($row = db2_fetch_array($stmt)) {
      echo "{$row[0]} {$row[1]}";
    }
  }
?>

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

first2 last2

参考

db2_connect() - データベースへの接続を返す
db2_pconnect() - データベースへの持続的接続を返す
db2_exec() - SQL 文を直接実行する
db2_prepare() - 実行する SQL 文を準備する
db2_cursor_type() - ステートメントリソースが使用しているカーソルの型を返す