db2-get-option.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.db2-get-option" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>db2_get_option</refname>
  <refpurpose>Retrieves an option value for a statement resource or a connection resource</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>db2_get_option</methodname>
   <methodparam><type>resource</type><parameter>resource</parameter></methodparam>      
   <methodparam><type>string</type><parameter>option</parameter></methodparam>
  </methodsynopsis>
  <para>
   Retrieves the value of a specified option value for a statement resource 
   or a connection resource.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>resource</parameter></term>
     <listitem>
     <para>
      A valid statement resource as returned from
      <function>db2_prepare</function> or a valid connection resource as
      returned from <function>db2_connect</function> or
      <function>db2_pconnect</function>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>option</parameter></term>
    <listitem>
     <para>
      A valid statement or connection options. The following new options are available 
      as of ibm_db2 version 1.6.0. They provide useful tracking information 
      that can be set during execution with <function>db2_get_option</function>.
      <note>
       <para>
        Prior versions of ibm_db2 do not support these new options.
       </para>
       <para>
        When the value in each option is being set, some servers might not handle 
        the entire length provided and might truncate the value.
       </para>
       <para>
        To ensure that the data specified in each option is converted correctly 
        when transmitted to a host system, use only the characters A through Z, 
        0 through 9, and the underscore (_) or period (.).
       </para>
      </note>
      <variablelist>
       <varlistentry>
        <term><parameter>userid</parameter></term>
         <listitem>
          <para>
           <literal>SQL_ATTR_INFO_USERID</literal> - A pointer to a null-terminated 
           character string used to identify the client user ID sent to the host 
           database server when using DB2 Connect.
           <note>
            <para>
             DB2 for z/OS and OS/390 servers support up to a length of 16 characters. 
             This user-id is not to be confused with the authentication user-id, it is for 
             identification purposes only and is not used for any authorization.
            </para>
           </note>
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>acctstr</parameter></term>
         <listitem>
          <para>
           <literal>SQL_ATTR_INFO_ACCTSTR</literal> - A pointer to a null-terminated 
           character string used to identify the client accounting string sent to the 
           host database server when using DB2 Connect.
           <note>
            <para>
             DB2 for z/OS and OS/390 servers support up to a length of 200 characters.
            </para>
           </note>
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>applname</parameter></term>
         <listitem>
          <para>
           <literal>SQL_ATTR_INFO_APPLNAME</literal> - A pointer to a null-terminated 
           character string used to identify the client application name sent to the 
           host database server when using DB2 Connect.
           <note>
            <para>
             DB2 for z/OS and OS/390 servers support up to a length of 32 characters.
            </para>
           </note>
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>wrkstnname</parameter></term>
         <listitem>
          <para>
           <literal>SQL_ATTR_INFO_WRKSTNNAME</literal> - A pointer to a null-terminated 
           character string used to identify the client workstation name sent to the 
           host database server when using DB2 Connect.
           <note>
            <para>
             DB2 for z/OS and OS/390 servers support up to a length of 18 characters.
            </para>
           </note>
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  <para>
   The following table specifies which options are compatible with
   the available resource types:
   <table>
    <title>Resource-Parameter Matrix</title>
    <tgroup cols="5">
     <colspec colnum="1" colname="col1" align="center" />
     <colspec colnum="2" colname="col2" align="center" />
     <colspec colnum="3" colname="col3" align="center" />
     <colspec colnum="4" colname="col4" align="center" />
     <colspec colnum="5" colname="col5" align="center" />
     <thead>
      <row>
       <entry morerows="1">Key</entry>
       <entry morerows="1">Value</entry>
       <entry namest="col3" nameend="col5">Resource Type</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry colname="col3">Connection</entry>
       <entry colname="col4">Statement</entry>
       <entry colname="col5">Result Set</entry>
      </row>
      <row>
       <entry>userid</entry>
       <entry><literal>SQL_ATTR_INFO_USERID</literal></entry>
       <entry colname="col3">X</entry>
       <entry colname="col4">X</entry>
       <entry colname="col5">-</entry>
      </row>
      <row>
       <entry>acctstr</entry>
       <entry><literal>SQL_ATTR_INFO_ACCTSTR</literal></entry>
       <entry colname="col3">X</entry>
       <entry colname="col4">X</entry>
       <entry colname="col5">-</entry>
      </row>
      <row>
       <entry>applname</entry>
       <entry><literal>SQL_ATTR_INFO_APPLNAME</literal></entry>
       <entry colname="col3">X</entry>
       <entry colname="col4">X</entry>
       <entry colname="col5">-</entry>
      </row>
      <row>
       <entry>wrkstnname</entry>
       <entry><literal>SQL_ATTR_INFO_WRKSTNNAME</literal></entry>
       <entry colname="col3">X</entry>
       <entry colname="col4">X</entry>
       <entry colname="col5">-</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the current setting of the connection attribute provided on success 
  &return.falseforfailure;.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Setting and retrieving parameters through a connection resource</title>
    <programlisting role="php">
<![CDATA[
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$user     = 'db2inst1';
$password = 'ibmdb2';

/* Obtain Connection Resource */
$conn = db2_connect($database, $user, $password);

echo "Client attributes passed through connection string:\n";

/* Create the associative options array with valid key-value pairs */
/* Assign the attributes through connection string */
/* Access the options specified */
$options1 = array('userid' => 'db2inst1');
$conn1 = db2_connect($database, $user, $password, $options1);
$val = db2_get_option($conn1, 'userid');
echo $val . "\n";

$options2 = array('acctstr' => 'account');
$conn2 = db2_connect($database, $user, $password, $options2);
$val = db2_get_option($conn2, 'acctstr');
echo $val . "\n";

$options3 = array('applname' => 'myapp');
$conn3 = db2_connect($database, $user, $password, $options3);
$val = db2_get_option($conn3, 'applname');
echo $val . "\n";

$options4 = array('wrkstnname' => 'workstation');
$conn4 = db2_connect($database, $user, $password, $options4);
$val = db2_get_option($conn4, 'wrkstnname');
echo $val . "\n";

echo "Client attributes passed post-connection:\n";

/* Create the associative options array with valid key-value pairs */
/* Assign the attributes after a connection is made */
/* Access the options specified */
$options5 = array('userid' => 'db2inst1');
$conn5 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn5, $options5, 1);
$val = db2_get_option($conn5, 'userid');
echo $val . "\n";

$options6 = array('acctstr' => 'account');
$conn6 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn6, $options6, 1);
$val = db2_get_option($conn6, 'acctstr');
echo $val . "\n";

$options7 = array('applname' => 'myapp');
$conn7 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn7, $options7, 1);
$val = db2_get_option($conn7, 'applname');
echo $val . "\n";

$options8 = array('wrkstnname' => 'workstation');
$conn8 = db2_connect($database, $user, $password);
$rc = db2_set_option($conn8, $options8, 1);
$val = db2_get_option($conn8, 'wrkstnname');
echo $val . "\n";
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Client attributes passed through connection string:
db2inst1
account
myapp
workstation
Client attributes passed post-connection:
db2inst1
account
myapp
workstation]]>
    </screen>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>db2_connect</function></member>
    <member><function>db2_cursor_type</function></member>
    <member><function>db2_exec</function></member>
    <member><function>db2_set_option</function></member>
    <member><function>db2_pconnect</function></member>
    <member><function>db2_prepare</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
-->