<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry xml:id="function.db2-pconnect" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>db2_pconnect</refname>
  <refpurpose>
   Returns a persistent connection to a database
  </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>
   Returns a persistent connection to an IBM DB2 Universal Database, IBM
   Cloudscape, or Apache Derby database.
  </para>

  <para>
   For more information on persistent
   connections, refer to <xref linkend="features.persistent-connections"/>.
  </para>

  <para>
   Calling <function>db2_close</function> on a persistent connection always
   returns &true;, but the underlying DB2 client connection remains open and
   waiting to serve the next matching <function>db2_pconnect</function>
   request.
  </para>

  <para>
   Users running version 1.9.0 or later of ibm_db2 should be aware that the
   extension will perform a transaction rollback on persistent connections at
   the end of a request, thus ending the transaction.  This prevents the
   transaction block from carrying over to the next request which uses that
   connection if script execution ends before the transaction block does.
  </para>

 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>database</parameter></term>
     <listitem>
      <para>
       For a cataloged connection to a database, <parameter>database</parameter>
       represents the database alias in the DB2 client catalog.
      </para>
      <para>
       For an uncataloged connection to a database,
       <parameter>database</parameter> represents a complete connection
       string in the following format:
       <literallayout>DATABASE=<parameter>database</parameter>;HOSTNAME=<parameter>hostname</parameter>;PORT=<parameter>port</parameter>;PROTOCOL=TCPIP;UID=<parameter>username</parameter>;PWD=<parameter>password</parameter>;</literallayout>
       <note>
        <para>
         When connecting to Db2 on IBM i, the underlying system calls
         <link xlink:href="https://www.ibm.com/docs/en/i/7.5?topic=functions-sqldriverconnect-connect-data-source">SQLDriverConnect</link>,
         which only accepts DSN, UID, and PWD for the
         <link xlink:href="https://www.ibm.com/docs/en/i/7.5?topic=functions-sqldriverconnect-connect-data-source#rzadpfndvcon__title__5">connection string</link>.
         Like so:
         <literallayout>DSN=<parameter>database</parameter>;UID=<parameter>username</parameter>;PWD=<parameter>password</parameter>;</literallayout>
        </para>
       </note>
       where the parameters represent the following values:
       <variablelist>
        <varlistentry>
         <term><parameter>database</parameter></term>
         <listitem>
          <para>
           The name of the database.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>hostname</parameter></term>
         <listitem>
          <para>
           The hostname or IP address of the database server.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>port</parameter></term>
         <listitem>
          <para>
           The TCP/IP port on which the database is listening for
           requests.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>username</parameter></term>
         <listitem>
          <para>
           The username with which you are connecting to the
           database.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>password</parameter></term>
         <listitem>
          <para>
           The password with which you are connecting to the database.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>username</parameter></term>
     <listitem>
      <para>
       The username with which you are connecting to the database.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>password</parameter></term>
     <listitem>
      <para>
       The password with which you are connecting to the database.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       An associative array of connection options that affect the behavior
       of the connection, where valid array keys include:
       <variablelist>
        <varlistentry>
         <term><parameter>autocommit</parameter></term>
         <listitem>
          <para>
           Passing the <constant>DB2_AUTOCOMMIT_ON</constant> value turns
           autocommit on for this connection handle.
          </para>
          <para>
           Passing the <constant>DB2_AUTOCOMMIT_OFF</constant> value turns
           autocommit off for this connection handle.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>DB2_ATTR_CASE</parameter></term>
         <listitem>
          <para>
           Passing the <constant>DB2_CASE_NATURAL</constant> value specifies
           that column names are returned in natural case.
          </para>
          <para>
           Passing the <constant>DB2_CASE_LOWER</constant> value specifies
           that column names are returned in lower case.
          </para>
          <para>
           Passing the <constant>DB2_CASE_UPPER</constant> value specifies
           that column names are returned in upper case.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>CURSOR</parameter></term>
         <listitem>
          <para>
           Passing the <constant>DB2_FORWARD_ONLY</constant> value specifies a
           forward-only cursor for a statement resource. This is the default
           cursor type and is supported on all database servers.
          </para>
          <para>
           Passing the <constant>DB2_SCROLLABLE</constant> value specifies a
           scrollable cursor for a statement resource. This mode enables
           random access to rows in a result set, but currently is supported
           only by IBM DB2 Universal Database.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       The following new option is available in ibm_db2 version 1.7.0
       and later.
       <variablelist>
        <varlistentry>
         <term><parameter>trustedcontext</parameter></term>
         <listitem>
          <para>
           Passing the DB2_TRUSTED_CONTEXT_ENABLE value turns trusted context
           on for this connection handle. This parameter cannot be set using
           <function>db2_set_option</function>.
          </para>
          <para>
           This key works only if the database is cataloged (even if the
           database is local), or if you specify the full DSN when you create
           the connection.
          </para>
          <para>
           To catalog the database, use following commands:
          </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>
       The following new i5/OS options are available in ibm_db2 version 1.5.1
       and later.
       <tip>
        <para>Conflicting connection attributes used in conjunction with persistent
         connections can produce indeterminate results on i5/OS. Site policies should
         be establish for all applications using each persistent connection user
         profile. The default DB2_AUTOCOMMIT_ON is suggested when using persistent connections.
        </para>
       </tip>
       <variablelist>
        <varlistentry>
         <term><parameter>i5_lib</parameter></term>
         <listitem>
          <para>
           A character value that indicates the default library that will be
           used for resolving unqualified file references. This is not valid
           if the connection is using system naming mode.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_naming</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_NAMING_ON</literal> value turns on DB2 UDB CLI iSeries
           system naming mode. Files are qualified using the slash (/) delimiter.
           Unqualified files are resolved using the library list for the job.
          </para>
          <para>
           <literal>DB2_I5_NAMING_OFF</literal> value turns off DB2 UDB CLI default
           naming mode, which is SQL naming. Files are qualified using the period (.)
           delimiter. Unqualified files are resolved using either the default library
           or the current user ID.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_commit</parameter></term>
         <listitem>
          <para>
           The <parameter>i5_commit</parameter> attribute should be set before the
           <function>db2_pconnect</function>. If the value is changed after the
           connection has been established, and the connection is to a remote data
           source, the change does not take effect until the next successful
           <function>db2_pconnect</function> for the connection handle.
           <note>
            <para>
             The php.ini setting <parameter>ibm_db2.i5_allow_commit</parameter>==0
             or <literal>DB2_I5_TXN_NO_COMMIT</literal> is the default, but may be
             overridden with the <parameter>i5_commit</parameter> option.
            </para>
           </note>
          </para>
          <para>
           <literal>DB2_I5_TXN_NO_COMMIT</literal> - Commitment control is not used.
          </para>
          <para>
           <literal>DB2_I5_TXN_READ_UNCOMMITTED</literal> - Dirty reads, nonrepeatable
           reads, and phantoms are possible.
          </para>
          <para>
           <literal>DB2_I5_TXN_READ_COMMITTED</literal> - Dirty reads are not possible.
           Nonrepeatable reads, and phantoms are possible.
          </para>
          <para>
           <literal>DB2_I5_TXN_REPEATABLE_READ</literal> - Dirty reads and nonrepeatable
           reads are not possible. Phantoms are possible.
          </para>
          <para>
           <literal>DB2_I5_TXN_SERIALIZABLE</literal> - Transactions are serializable.
           Dirty reads, non-repeatable reads, and phantoms are not possible
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_query_optimize</parameter></term>
         <listitem>
          <para>
            <literal>DB2_FIRST_IO</literal> All queries are optimized with the goal of
            returning the first page of output as fast as possible. This goal works well
            when the output is controlled by a user who is most likely to cancel the query
            after viewing the first page of output data. Queries coded with an
            OPTIMIZE FOR nnn ROWS clause honor the goal specified by the clause.
          </para>
          <para>
           <literal>DB2_ALL_IO</literal> All queries are optimized with the goal of running
           the entire query to completion in the shortest amount of elapsed time. This is a
           good option when the output of a query is being written to a file or report, or
           the interface is queuing the output data. Queries coded with an OPTIMIZE FOR nnn
           ROWS clause honor the goal specified by the clause. This is the default.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_dbcs_alloc</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_DBCS_ALLOC_ON</literal> value turns on DB2 6X allocation scheme
           for DBCS translation column size growth.
          </para>
          <para>
           <literal>DB2_I5_DBCS_ALLOC_OFF</literal> value turns off DB2 6X allocation scheme
           for DBCS translation column size growth.
           <note>
            <para>
             The php.ini setting <parameter>ibm_db2.i5_dbcs_alloc</parameter>==0 or
             <literal>DB2_I5_DBCS_ALLOC_OFF</literal> is the default, but may be overridden
             with the <parameter>i5_dbcs_alloc</parameter> option.
            </para>
           </note>
           </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_date_fmt</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_FMT_ISO</literal> - The International Organization for Standardization
           (ISO) date format yyyy-mm-dd is used. This is the default.
          </para>
          <para>
           <literal>DB2_I5_FMT_USA</literal> - The United States date format mm/dd/yyyy is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_EUR</literal> - The European date format dd.mm.yyyy is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_JIS</literal> - The Japanese Industrial Standard date format
           yyyy-mm-dd is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_MDY</literal> - The date format mm/dd/yyyy is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_DMY</literal> - The date format dd/mm/yyyy is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_YMD</literal> - The date format yy/mm/dd is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_JUL</literal> - The Julian date format yy/ddd is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_JOB</literal> - The job default is used.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_date_sep</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_SEP_SLASH</literal> - A slash ( / ) is used as the date separator.
           This is the default.
          </para>
          <para>
           <literal>DB2_I5_SEP_DASH</literal> - A dash ( - ) is used as the date separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_PERIOD</literal> - A period ( . ) is used as the date
           separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_COMMA</literal> - A comma ( , ) is used as the date separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_BLANK</literal> - A blank is used as the date separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_JOB</literal> - The job default is used
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_time_fmt</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_FMT_ISO</literal> - The International Organization for
           Standardization (ISO) time format hh.mm.ss is used. This is the default.
          </para>
          <para>
           <literal>DB2_I5_FMT_USA</literal> - The United States time format
           hh:mmxx is used, where xx is AM or PM.
          </para>
          <para>
           <literal>DB2_I5_FMT_EUR</literal> - The European time format hh.mm.ss
           is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_JIS</literal> - The Japanese Industrial Standard
           time format hh:mm:ss is used.
          </para>
          <para>
           <literal>DB2_I5_FMT_HMS</literal> - The hh:mm:ss format is used.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_time_sep</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_SEP_COLON</literal> - A colon ( : ) is used as the time
           separator. This is the default.
          </para>
          <para>
           <literal>DB2_I5_SEP_PERIOD</literal> - A period ( . ) is used as the time
           separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_COMMA</literal> - A comma ( , ) is used as the time
           separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_BLANK</literal> - A blank is used as the time separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_JOB</literal> - The job default is used.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_decimal_sep</parameter></term>
         <listitem>
          <para>
           <literal>DB2_I5_SEP_PERIOD</literal> - A period ( . ) is used as
           the decimal separator. This is the default.
          </para>
          <para>
           <literal>DB2_I5_SEP_COMMA</literal> - A comma ( , ) is used as the
           decimal separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_JOB</literal> - The job default is used.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       The following new i5/OS option is available in ibm_db2 version 1.8.0
       and later.
       <variablelist>
        <varlistentry>
         <term><parameter>i5_libl</parameter></term>
         <listitem>
          <para>
           A character value that indicates the library list that will be used for
           resolving unqualified file references. Specify the library list
           elements separated by blanks 'i5_libl'=&gt;"MYLIB YOURLIB ANYLIB".
           <note>
            <para>
             i5_libl calls qsys2/qcmdexc('cmd',cmdlen), which is only available
             in i5/OS V5R4 and later.
            </para>
           </note>
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a connection handle resource if the connection attempt is
   successful. <function>db2_pconnect</function> tries to reuse an existing
   connection resource that exactly matches the
   <parameter>database</parameter>, <parameter>username</parameter>, and
   <parameter>password</parameter> parameters. If the connection attempt fails,
   <function>db2_pconnect</function> returns &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>PECL ibm_db2 1.9.0</entry>
       <entry>
        Active transactions within a persistent connection will be rolled back
        at the end of each request.
       </entry>
      </row>
      <row>
       <entry>PECL ibm_db2 1.8.0</entry>
       <entry>
        The <parameter>i5_libl</parameter> option is available for i5/OS
        users.
       </entry>
      </row>
      <row>
       <entry>PECL ibm_db2 1.7.0</entry>
       <entry>
        The <parameter>trustedcontext</parameter> option is available.
       </entry>
      </row>
      <row>
       <entry>PECL ibm_db2 1.5.1</entry>
       <entry>
        The <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>
        and <parameter>i5_decimal_sep</parameter> options are available for
        i5/OS users.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>A <function>db2_pconnect</function> example</title>
    <para>
     In the following example, the first call to
     <function>db2_pconnect</function> returns a new persistent connection
     resource. The second call to <function>db2_pconnect</function> returns
     a persistent connection resource that simply reuses the first persistent
     connection resource.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

$pconn = db2_pconnect($database, $user, $password);

if ($pconn) {
    echo "Persistent connection succeeded.";
}
else {
    echo "Persistent connection failed.";
}

$pconn2 = db2_pconnect($database, $user, $password);
if ($pconn) {
    echo "Second persistent connection succeeded.";
}
else {
    echo "Second persistent connection failed.";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Persistent connection succeeded.
Second persistent connection succeeded.
]]>
    </screen>
   </example>
   <example>
    <title>Using trusted context</title>
    <para>
     The following example shows how to enable trusted context, switch
     users, and get the current user 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");

        //Do some work as user 1.

        //Switching to trusted user.
        $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");
        //Do more work as 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
-->