php-doc-en/reference/ibm_db2/functions/db2-pconnect.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="function.db2-pconnect">
 <refnamediv>
  <refname>db2_pconnect</refname>
  <refpurpose>
   Returns a persistent connection to a database
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>db2_pconnect</methodname>
   <methodparam><type>string</type><parameter>database</parameter></methodparam>
   <methodparam><type>string</type><parameter>username</parameter></methodparam>
   <methodparam><type>string</type><parameter>password</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
  </methodsynopsis>


  <para>
   Returns a persistent connection to an IBM DB2 Universal Database, IBM
   Cloudscape, or Apache Derby database. 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>
   Note that you are strongly urged to only use persistent connections on
   connections with autocommit turned on. If you attempt to combine
   transactions with persistent connections, issuing
   <function>db2_commit</function> or <function>db2_rollback</function>
   against a persistent connection will affect every persistent connection
   that is currently using the same underlying DB2 client connection. You may
   also rapidly experience locking escalation if you do not use autocommit for
   your persistent connections.
  </para>

 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>database</parameter></term>
     <listitem>
      <para>
       The database alias in the DB2 client catalog.
      </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 <literal>DB2_AUTOCOMMIT_ON</literal> value turns
           autocommit on for this connection handle.
          </para>
          <para>
           Passing the <literal>DB2_AUTOCOMMIT_OFF</literal> value turns
           autocommit off for this connection handle.
          </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="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>
  </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:"../../../../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
-->