db2-pconnect.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 61374bbe228e8e9c55a24aba59a1e2bb2a871148 Maintainer: takagi Status: ready -->
<refentry xml:id="function.db2-pconnect" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>db2_pconnect</refname>
  <refpurpose>
   データベースへの持続的接続を返す
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>resource</type><type>false</type></type><methodname>db2_pconnect</methodname>
   <methodparam><type>string</type><parameter>database</parameter></methodparam>
   <methodparam><type class="union"><type>string</type><type>null</type></type><parameter>username</parameter></methodparam>
   <methodparam><type class="union"><type>string</type><type>null</type></type><parameter>password</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>


  <para>
   IBM DB2 Universal Database、IBM Cloudscape
   あるいは Apache Derby データベースへの持続的接続を返します。
  </para>

  <para>
   持続的接続についての詳細な情報は、
   <xref linkend='features.persistent-connections'/> を参照ください。
  </para>

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

  <para>
   ibm_db2 のバージョン 1.9.0 以降を使っている場合は、
   持続的接続上ではリクエストが終了するたびにトランザクションがロールバックされることに気をつけましょう。
   リクエストが終了するたびにトランザクションも終了します。
   これは、トランザクションによるブロックが次のリクエストまで持ち越されてしまって
   同じ接続を利用する別のスクリプトの実行に影響するのを防ぐためです。
  </para>

 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>database</parameter></term>
     <listitem>
      <para>
       DB2 クライアントカタログ内のデータベースエイリアス。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>username</parameter></term>
     <listitem>
      <para>
       データベースに接続するユーザー名。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>password</parameter></term>
     <listitem>
      <para>
       データベースに接続するパスワード。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       接続の振る舞いを指定する接続オプションの連想配列。
       使用可能なキーは以下のとおりです。
       <variablelist>
        <varlistentry>
         <term><parameter>autocommit</parameter></term>
         <listitem>
          <para>
           <constant>DB2_AUTOCOMMIT_ON</constant> を渡すと、
           この接続ハンドルで自動コミットを有効にします。
          </para>
          <para>
           <constant>DB2_AUTOCOMMIT_OFF</constant> を渡すと、
           この接続ハンドルで自動コミットを無効にします。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>DB2_ATTR_CASE</parameter></term>
         <listitem>
          <para>
           <constant>DB2_CASE_NATURAL</constant> を渡すと、
           カラム名の大文字小文字を変換せずに返します。
          </para>
          <para>
           <constant>DB2_CASE_LOWER</constant> を渡すと、
           カラム名を小文字に変換して返します。
          </para>
          <para>
           <constant>DB2_CASE_UPPER</constant> を渡すと、
           カラム名を大文字に変換して返します。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>CURSOR</parameter></term>
         <listitem>
          <para>
           <constant>DB2_FORWARD_ONLY</constant> を渡すと、
           ステートメントリソースで前進のみのカーソルを使用します。
           これはデフォルトのカーソル型であり、
           すべてのデータベースサーバーでサポートされています。
          </para>
          <para>
           <constant>DB2_SCROLLABLE</constant> を渡すと、
           ステートメントリソースでスクロール可能なカーソルを使用します。
           このモードでは結果セット内の行へのランダムアクセスが可能となりますが、
           現在は IBM DB2 Universal Database でしかサポートされていません。
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       以下の新しいオプションは、ibm_db2 のバージョン 1.7.0 以降で使用可能です。
       <variablelist>
        <varlistentry>
         <term><parameter>trustedcontext</parameter></term>
         <listitem>
          <para>
           DB2_TRUSTED_CONTEXT_ENABLE を渡すと、この接続ハンドルでの信頼済みコンテキストを有効にします。
           このパラメータを <function>db2_set_option</function> で設定することはできません。
          </para>
          <para>
           このキーは、カタログ接続の場合 (たとえローカルデータベースであっても)
           あるいは接続時に完全な DSN を指定した場合にのみ動作します。
          </para>
          <para>
           データベースをカタログするには次のコマンドを実行します。
          </para>
          <para>
           <literallayout>db2 catalog tcpip node loopback remote &lt;SERVERNAME&gt; server &lt;SERVICENAME&gt;
db2 catalog database &lt;LOCALDBNAME&gt; as &lt;REMOTEDBNAME&gt; at node loopback
db2 "update dbm cfg using svcename &lt;SERVICENAME&gt;"
db2set DB2COMM=TCPIP</literallayout>
          </para>
          
         </listitem>
        </varlistentry>             
      </variablelist>
      </para>
      <para>
       以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.5.1 以降で使用可能です。
       <tip>
        <para>
         持続的接続と衝突する属性を使用すると、i5/OS では結果は未定義となります。
         持続的接続のユーザープロファイルを使用するすべてのアプリケーションについて、
         サイトポリシーを確立しておく必要があります。持続的接続を使用する場合は、
         デフォルトの DB2_AUTOCOMMIT_ON をおすすめします。
        </para>
       </tip>
       <variablelist>
        <varlistentry>
         <term><parameter>i5_lib</parameter></term>
         <listitem>
          <para>
           未解決のファイル参照を解決する際に使用するデフォルトのライブラリを指定します。
           システムのネーミングモードを使用している接続の場合は、これは無効です。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_naming</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_NAMING_ON</literal> は、DB2 UDB CLI iSeries 
           のシステムネーミングモードを有効にします。ファイルの識別の際、
           区切り文字としてスラッシュ (/) を使用します。
           識別されないファイルの解決には、ジョブのライブラリ一覧を使用します。
          </para>
          <para>
           <literal>DB2_I5_NAMING_OFF</literal> は、DB2 UDB CLI
           のデフォルトのネーミングモード (SQL ネーミング) を無効にします。
           ファイルの識別の際、区切り文字としてピリオド (.) を使用します。
           識別されないファイルの解決には、
           デフォルトのライブラリあるいは現在のユーザー ID を使用します。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_commit</parameter></term>
         <listitem>
          <para>
           <parameter>i5_commit</parameter> 属性は、
           <function>db2_pconnect</function> の前に設定しなければなりません。
           接続が確立された後にこの値が変更され、その接続がリモートデータソースに対するものだった場合は、
           その接続ハンドルに対してもう一度 <function>db2_pconnect</function>
           がコールされるまで変更は反映されません。
           <note>
            <para>
             php.ini の設定は <parameter>ibm_db2.i5_allow_commit</parameter>==0
             あるいは <literal>DB2_I5_TXN_NO_COMMIT</literal> がデフォルトです。
             しかし、その設定よりも <parameter>i5_commit</parameter>
             オプションの内容のほうが優先されます。
            </para>
           </note>           
          </para>
          <para>
           <literal>DB2_I5_TXN_NO_COMMIT</literal> - コミットの管理を使用しません。
          </para>
          <para>
           <literal>DB2_I5_TXN_READ_UNCOMMITTED</literal> - ダーティリード、
           反復不能読み取り、ファントムリードが発生する可能性があります。
          </para>
          <para>
           <literal>DB2_I5_TXN_READ_COMMITTED</literal> - ダーティリードは発生しません。
           反復不能読み取り、ファントムリードが発生する可能性があります。
          </para>
          <para>
           <literal>DB2_I5_TXN_REPEATABLE_READ</literal> - ダーティリード、
           反復不能読み取りは発生しません。
           ファントムリードが発生する可能性があります。
          </para>
          <para>
           <literal>DB2_I5_TXN_SERIALIZABLE</literal> -
           トランザクションの一貫性を保持します。
           ダーティリード、反復不能読み取り、ファントムリードは発生しません。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_query_optimize</parameter></term>
         <listitem>
          <para>
            <literal>DB2_FIRST_IO</literal>
            すべてのクエリは、結果の一行目をできるだけ早く返すように最適化されます。
            これが有効なのは、出力の制御をユーザーが行う場合です。出力の制御とは、
            たとえば、出力の最初のページを見てそこで処理を停止させるなどのことです。
            OPTIMIZE FOR nnn ROWS 句を指定したクエリは、その指定が優先されます。
          </para>
          <para>
           <literal>DB2_ALL_IO</literal>
           すべてのクエリは、結果全体をできるだけ短時間で取得できるように最適化されます。
           これは、結果をファイルや帳票に書き出す場合に有用なオプションです。
           あるいは出力データを順次処理するインターフェイスなどにも有用です。
           OPTIMIZE FOR nnn ROWS 句を指定したクエリは、その指定が優先されます。
           これはデフォルトの設定です。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_dbcs_alloc</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_DBCS_ALLOC_ON</literal> は、
           DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを有効にします。
          </para>
          <para>
           <literal>DB2_I5_DBCS_ALLOC_OFF</literal> は、
           DBCS トランザクションカラムサイズ用の DB2 6X アロケーションを無効にします。
           <note>
            <para>
             php.ini では <parameter>ibm_db2.i5_dbcs_alloc</parameter>==0 あるいは
             <literal>DB2_I5_DBCS_ALLOC_OFF</literal> がデフォルト設定となっています。
             しかし、<parameter>i5_dbcs_alloc</parameter> の値のほうが優先されます。
            </para>
           </note>
           </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_date_fmt</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_FMT_ISO</literal> - 国際標準化機構 (ISO) の日付書式
           yyyy-mm-dd を使用します。デフォルトです。
          </para>
          <para>
           <literal>DB2_I5_FMT_USA</literal> - 合衆国の日付書式 mm/dd/yyyy を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_EUR</literal> - 欧州の日付書式 dd.mm.yyyy を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_JIS</literal> - 日本工業規格 (JIS) の日付書式 yyyy-mm-dd を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_MDY</literal> - 日付書式 mm/dd/yyyy を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_DMY</literal> - 日付書式 dd/mm/yyyy を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_YMD</literal> - 日付書式 yy/mm/dd を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_JUL</literal> - ユリウス日 yy/ddd を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_JOB</literal> - そのジョブのデフォルトを使用します。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_date_sep</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_SEP_SLASH</literal> - スラッシュ ( / ) を日付の区切り文字として使用します。
           デフォルトです。
          </para>
          <para>
           <literal>DB2_I5_SEP_DASH</literal> - ダッシュ ( - ) を日付の区切り文字として使用します。
          </para>
          <para>
           <literal>DB2_I5_SEP_PERIOD</literal> - ピリオド ( . ) を日付の区切り文字として使用します。
           separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_COMMA</literal> - カンマ ( , ) を日付の区切り文字として使用します。
          </para>
          <para>
           <literal>DB2_I5_SEP_BLANK</literal> - ブランクを日付の区切り文字として使用します。
          </para>
          <para>
           <literal>DB2_I5_SEP_JOB</literal> - そのジョブのデフォルトを使用します。
          </para>
         </listitem>
        </varlistentry>     
        <varlistentry>
         <term><parameter>i5_time_fmt</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_FMT_ISO</literal> - 国際標準化機構 (ISO) の時刻書式
           hh.mm.ss を使用します。デフォルトです。
          </para>
          <para>
           <literal>DB2_I5_FMT_USA</literal> - 合衆国の時刻書式
           hh:mmxx を使用します。xx には AM あるいは PM が入ります。
          </para>
          <para>
           <literal>DB2_I5_FMT_EUR</literal> - 欧州の時刻書式 hh.mm.ss 
           を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_JIS</literal> - 日本工業規格 (JIS) の時刻書式
           hh:mm:ss を使用します。
          </para>
          <para>
           <literal>DB2_I5_FMT_HMS</literal> - hh:mm:ss を使用します。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_time_sep</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_SEP_COLON</literal> - コロン ( : ) を時刻の区切り文字として使用します。
           デフォルトです。
          </para>
          <para>
           <literal>DB2_I5_SEP_PERIOD</literal> - ピリオド ( . ) を時刻の区切り文字として使用します。
          </para>
          <para>
           <literal>DB2_I5_SEP_COMMA</literal> - カンマ ( , ) を時刻の区切り文字として使用します。
          </para>
          <para>
           <literal>DB2_I5_SEP_BLANK</literal> - ブランクを時刻の区切り文字として使用します。
          </para>
          <para>
           <literal>DB2_I5_SEP_JOB</literal> - そのジョブのデフォルトを使用します。
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_decimal_sep</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_SEP_PERIOD</literal> - ピリオド ( . ) を小数点として使用します。
           デフォルトです。
          </para>
          <para>
           <literal>DB2_I5_SEP_COMMA</literal> - カンマ ( , ) を小数点として使用します。
          </para>
          <para>
           <literal>DB2_I5_SEP_JOB</literal> - そのジョブのデフォルトを使用します。
          </para>
         </listitem>
        </varlistentry>        
       </variablelist>
      </para> 
      <para>
       以下の新しい i5/OS オプションは、ibm_db2 のバージョン 1.8.0 以降で使用可能です。
       <variablelist>
        <varlistentry>
         <term><parameter>i5_libl</parameter></term>
         <listitem>
          <para>
           ファイル参照を解決する際に用いるライブラリ一覧を表す文字。
           ライブラリ一覧の項目を指定する際は、空白で区切って
           'i5_libl'=>"MYLIB YOURLIB ANYLIB" のようにします。
           <note>
            <para>
             i5_libl は qsys2/qcmdexc('cmd',cmdlen) をコールします。
             これは i5/OS V5R4 以降でのみ使用可能です。
            </para>
           </note>
          </para>
         </listitem>
        </varlistentry>         
       </variablelist>
      </para>      
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   接続に成功した場合は接続ハンドルリソースを返します。
   パラメータ <parameter>database</parameter>、<parameter>username</parameter>
   および <parameter>password</parameter> に完全に一致する接続が
   既に存在した場合、<function>db2_pconnect</function>
   はそれを再利用します。接続に失敗した場合は
   <function>db2_pconnect</function> は &false; を返します。
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>ibm_db2 1.9.0</entry>
       <entry>
        持続的接続上のアクティブなトランザクションは、各接続の終了時にロールバックされるようになりました。
       </entry>
      </row>
      <row>
       <entry>ibm_db2 1.8.0</entry>
       <entry>
        i5/OS ユーザーは <parameter>i5_libl</parameter> オプションが使えるようになりました。
       </entry>
      </row>
      <row>
       <entry>ibm_db2 1.7.0</entry>
       <entry>
        <parameter>trustedcontext</parameter> オプションが使えるようになりました。
       </entry>
      </row>
      <row>
       <entry>ibm_db2 1.5.1</entry>
       <entry>
        i5/OS ユーザーは
        <parameter>i5_lib</parameter>, <parameter>i5_naming</parameter>,
        <parameter>i5_commit</parameter>,
        <parameter>i5_query_optimize</parameter>,
        <parameter>i5_dbcs_alloc</parameter>,
        <parameter>i5_date_fmt</parameter>,
        <parameter>i5_date_sep</parameter>,
        <parameter>i5_time_fmt</parameter>, <parameter>i5_time_sep</parameter>
        および <parameter>i5_decimal_sep</parameter>
        が使えるようになりました。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>db2_pconnect</function> の例</title>
    <para>
     以下の例で、最初に <function>db2_pconnect</function>
     をコールした際には新しい持続的接続リソースを返します。
     二度目に <function>db2_pconnect</function> をコールすると、
     最初の持続的接続のリソースが再利用されます。
    </para>
    <programlisting role="php">
<![CDATA[
<?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 回目の持続的接続に失敗しました。";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
持続的接続に成功しました。
2 回目の持続的接続に成功しました。
]]>
    </screen>
   </example>
   <example>
    <title>信頼済みコンテキストの使用</title>
    <para>
     次の例は、信頼済みのコンテキストを有効にしてユーザーを変更し、現在のユーザー ID
     を取得するものです。
    </para>
    <programlisting role="php">
<![CDATA[
<?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";
}
?>

]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Explicit trusted connection succeeded.
User has been switched.
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>db2_connect</function></member>
   </simplelist>
  </para>
 </refsect1>


</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->