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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="function.db2-connect">
 <refnamediv>
  <refname>db2_connect</refname>
  <refpurpose>
   Returns a connection to a database
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>db2_connect</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>
   Creates a new connection to an IBM DB2 Universal Database, IBM Cloudscape,
   or Apache Derby database.
  </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:
       <literal>DRIVER={IBM DB2 ODBC DRIVER};DATABASE=<parameter>database</parameter>;HOSTNAME=<parameter>hostname</parameter>;PORT=<parameter>port</parameter>;PROTOCOL=TCPIP;UID=<parameter>username</parameter>;PWD=<parameter>password</parameter>;</literal>
       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>
      <para>
       For uncataloged connections, you must pass a &null; value or empty
       string.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>password</parameter></term>
     <listitem>
      <para>
       The password with which you are connecting to the database.
      </para>
      <para>
       For uncataloged connections, you must pass a &null; value or empty
       string.
      </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>
        <varlistentry>
         <term><parameter>DB2_ATTR_CASE</parameter></term>
         <listitem>
          <para>
           Passing the <literal>DB2_CASE_NATURAL</literal> value specifies
           that column names are returned in natural case.
          </para>
          <para>
           Passing the <literal>DB2_CASE_LOWER</literal> value specifies
           that column names are returned in lower case.
          </para>
          <para>
           Passing the <literal>DB2_CASE_UPPER</literal> value specifies
           that column names are returned in upper case.
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>CURSOR</parameter></term>
         <listitem>
          <para>
           Passing the <literal>DB2_FORWARD_ONLY</literal> 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 <literal>DB2_SCROLLABLE</literal> 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 i5/OS options are available as of ibm_db2 version 1.5.1. 
       Note: prior versions of ibm_db2 do not support these new i5 options.
       <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_connect</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_connect</function> for the connection handle.
          </para>
          <para>
           Note: 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>
          <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 All</literal> 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. 
          </para>
          <para>
           Note: 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>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>i5_date_fmt</parameter></term>
         <listitem>
          <para>
           <literal>SQL_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 
           date separator.
          </para>
          <para>
           <literal>DB2_I5_SEP_JOB</literal> - The job default is used.
          </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. If the connection attempt fails, <function>db2_connect</function>
   returns &false;.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Creating a cataloged connection</title>
    <para>
     Cataloged connections require you to have previously cataloged the target
     database through the DB2 Command Line Processor (CLP) or DB2
     Configuration Assistant.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';

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

if ($conn) {
    echo "Connection succeeded.";
    db2_close($conn);
}
else {
    echo "Connection failed.";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Connection succeeded.
]]>
    </screen>
   </example>
   <example>
    <title>Creating an uncataloged connection</title>
    <para>
     An uncataloged connection enables you to dynamically connect to a
     database.
    </para>
    <programlisting role="php">
<![CDATA[
<?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 "Connection succeeded.";
    db2_close($conn);
}
else {
    echo "Connection failed.";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Connection succeeded.
]]>
    </screen>
   </example>
   <example>
    <title>Creating a connection with autocommit off by default</title>
    <para>
     Passing an array of options to <function>db2_connect</function> enables
     you to modify the default behavior of the connection handle.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$database = 'SAMPLE';
$user = 'db2inst1';
$password = 'ibmdb2';
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF);

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

if ($conn) {
    echo "Connection succeeded.\n";
    if (db2_autocommit($conn)) {
         echo "Autocommit is on.\n";
    }
    else {
         echo "Autocommit is off.\n";
    }
    db2_close($conn);
}
else {
    echo "Connection failed.";
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Connection succeeded.
Autocommit is off.
]]>
    </screen>
   </example>
   <example>
    <title>i5/OS best performance</title>
    <para>
     To achieve best performance for your i5/OS ibm_db2 1.5.1 PHP application 
     use the default host, userid, and password for your 
     <function>db2_connect</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
ANIMALS
NAMES
PICTURES
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>db2_close</function></member>
    <member><function>db2_pconnect</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
-->