dbs Tue Oct 3 02:35:03 2006 UTC
Added files:
/phpdoc/en/reference/ibm_db2/functions db2-set-option.xml
Log:
Document db2_set_option() (based on a draft by Kitman Cheung)
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/ibm_db2/functions/db2-set-option.xml?view=markup&rev=1.1
Index: phpdoc/en/reference/ibm_db2/functions/db2-set-option.xml
+++ phpdoc/en/reference/ibm_db2/functions/db2-set-option.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.db2-set-option">
<refnamediv>
<refname>db2_set_option</refname>
<refpurpose>Set options for connection or statement resources</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<!-- All Functions have this -->
<type>bool</type><methodname>db2_set_option</methodname>
<!-- Required Parameter (First Param) -->
<methodparam><type>resource</type><parameter>resource</parameter></methodparam>
<!-- Required Parameter (Second Param) -->
<methodparam><type>array</type><parameter>options</parameter></methodparam>
<!-- Optional Parameter (Third Param) -->
<methodparam
choice="opt"><type>int</type><parameter>type</parameter></methodparam>
</methodsynopsis>
<para>
Sets options for a statement resource or a connection resource. You
cannot set options for result set resources.
</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>options</parameter></term>
<listitem>
<para>
An associative array containing valid statement or connection
options. This parameter can be used to change autocommit values,
cursor types (scrollable or forward), and to specify the case of
the column names (lower, upper, or natural) that will appear in a
result set.
<variablelist>
<varlistentry>
<term><parameter>autocommit</parameter></term>
<listitem>
<para>
Passing <literal>DB2_AUTOCOMMIT_ON</literal> turns
autocommit on for the specified connection resource.
</para>
<para>
Passing <literal>DB2_AUTOCOMMIT_OFF</literal> turns
autocommit off for the specified connection resource.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>cursor</parameter></term>
<listitem>
<para>
Passing <literal>DB2_FORWARD_ONLY</literal> specifies a
forward-only cursor for a statement resource. This is the
default cursor type, and is supported by all database
servers.
</para>
<para>
Passing <literal>DB2_SCROLLABLE</literal> specifies a
scrollable cursor for a statement resource. Scrollable
cursors enable result set rows to be accessed in
non-sequential order, but are only supported by
IBM DB2 Universal Database databases.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>binmode</parameter></term>
<listitem>
<para>
Passing <literal>DB2_BINARY</literal> specifies that
binary data will be returned as is. This is the default
mode. This is the equivalent of setting
<literal>ibm_db2.binmode=1</literal> in &php.ini;.
</para>
<para>
Passing <literal>DB2_CONVERT</literal> specifies that
binary data will be converted to hexadecimal encoding,
and will be returned as such. This is the equivalent of
setting <literal>ibm_db2.binmode=2</literal> in &php.ini;.
</para>
<para>
Passing <literal>DB2_PASSTHRU</literal> specifies that
binary data will be converted to &null;. This is the
equivalent of setting <literal>ibm_db2.binmode=3</literal>
in &php.ini;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>db2_attr_case</parameter></term>
<listitem>
<para>
Passing <literal>DB2_CASE_LOWER</literal> specifies that
column names of the result set are returned in lower case.
</para>
<para>
Passing <literal>DB2_CASE_UPPER</literal> specifies that
column names of the result set are returned in upper case.
</para>
<para>
Passing <literal>DB2_CASE_NATURAL</literal> specifies that
column names of the result set are returned in natural
case.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
<para>
An integer value that specifies the type of resource that was
passed into the function. The type of resource and this value
must correspond.
<variablelist>
<varlistentry>
<term><parameter></parameter></term>
<listitem>
<para>
Passing <literal>1</literal> as the value specifies that
a connection resource has been passed into the function.
</para>
<para>
Passing any integer not equal to <literal>1</literal> as
the value specifies that a statement resource has been
passed into the function.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
</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>autocommit</entry>
<entry><literal>DB2_AUTOCOMMIT_ON</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">-</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>autocommit</entry>
<entry><literal>DB2_AUTOCOMMIT_OFF</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">-</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>cursor</entry>
<entry><literal>DB2_SCROLLABLE</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">X</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>cursor</entry>
<entry><literal>DB2_FORWARD_ONLY</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">X</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>binmode</entry>
<entry><literal>DB2_BINARY</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">X</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>binmode</entry>
<entry><literal>DB2_CONVERT</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">X</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>binmode</entry>
<entry><literal>DB2_PASSTHRU</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">X</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>db2_attr_case</entry>
<entry><literal>DB2_CASE_LOWER</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">X</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>db2_attr_case</entry>
<entry><literal>DB2_CASE_UPPER</literal></entry>
<entry colname="col3">X</entry>
<entry colname="col4">X</entry>
<entry colname="col5">-</entry>
</row>
<row>
<entry>db2_attr_case</entry>
<entry><literal>DB2_CASE_NATURAL</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>
&return.success;
</para>
</refsect1>
<!-- Place Changelog next if any -->
<!-- Place Examples next if any -->
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Setting one parameter with a connection resource</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_ON);
/* Call the function using the correct resource, options array, and type values
*/
$result = db2_set_option($conn, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
]]>
</programlisting>
&example.outputs;
<screen><![CDATA[Options Set Successfully]]></screen>
</example>
<example>
<title>Setting multiple parameters with a connection resource</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1'; //change to db2inst1
$password = 'ibmdb2'; //change to ibmdb2
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
/* Call the function using the correct resource, options array, and type values
*/
$result = db2_set_option($conn, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
]]>
</programlisting>
&example.outputs;
<screen><![CDATA[Options Set Successfully]]></screen>
</example>
<!-- Behaves Incorrectly -->
<example>
<title>Setting multiple parameters with an invalid key</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'MY_INVALID_KEY' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
/* Call the function using the correct resource, options array, and type values
*/
$result = db2_set_option($conn, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
]]>
</programlisting>
&example.outputs;
<screen><![CDATA[Could Not Set Options]]></screen>
</example>
<!-- Behaves Incorrectly -->
<example>
<title>Setting multiple parameters with an invalid value</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => 'INVALID_VALUE',
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
/* Call the function using the correct resource, options array, and type values
*/
$result = db2_set_option($conn, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
]]>
</programlisting>
&example.outputs;
<screen><![CDATA[Could Not Set Options]]></screen>
</example>
<example>
<title>Setting multiple parameters with a connection resource and the
wrong type</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
/* Call the function using the correct resource, options array, and the wrong
type value */
$result = db2_set_option($conn, $options, 2);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
]]>
</programlisting>
&example.outputs;
<screen><![CDATA[Could Not Set Options]]></screen>
</example>
<example>
<title>Setting multiple parameters with the wrong resource</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('autocommit' => DB2_AUTOCOMMIT_OFF,
'binmode' => DB2_PASSTHRU,
'db2_attr_case' => DB2_CASE_UPPER,
'cursor' => DB2_SCROLLABLE);
$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE');
/* Call the function using the wrong resource, and the correct options array,
and type values */
$result = db2_set_option($stmt, $options, 1);
/* Check if all options could be set correctly */
if($result)
{
echo 'Options Set Successfully';
}
else
{
echo 'Could Not Set Options';
}
?>
]]>
</programlisting>
&example.outputs;
<screen><![CDATA[Could Not Set Options]]></screen>
</example>
<example>
<title>Putting it all together</title>
<para>
</para>
<programlisting role="php">
<![CDATA[
<?php
/* Database Connection Parameters */
$database = 'SAMPLE';
$hostname = 'localhost';
$port = 50000;
$protocol = 'TCPIP';
$username = 'db2inst1';
$password = 'ibmdb2';
/* Connection String */
$conn_string = "DRIVER={IBM DB2 ODBC DRIVER};DATABASE=$database;";
$conn_string .= "HOSTNAME=$hostname;PORT=$port;PROTOCOL=$protocol;";
$conn_string .= "UID=$username;PWD=$password;";
/* Obtain Connection Resource */
$conn = db2_connect($conn_string, '', '');
/* Create the associative options array with valid key-value pairs */
$options = array('db2_attr_case' => DB2_CASE_LOWER,
'cursor' => DB2_SCROLLABLE);
$stmt = db2_prepare($conn, 'SELECT * FROM EMPLOYEE WHERE EMPNO = ? OR EMPNO =
?');
/* Call the function using the correct resource, options array, and type values
*/
$option_result = db2_set_option($stmt, $options, 2);
$result = db2_execute($stmt, array('000130', '000140'));
/* Get Row 2 before Row 1 since Scrollable Cursor */
print_r(db2_fetch_assoc($stmt, 2));
print '<br /><br />';
print_r(db2_fetch_assoc($stmt, 1));
?>
]]>
</programlisting>
&example.outputs;
<screen><![CDATA[Array
(
[empno] => 000140
[firstnme] => HEATHER
[midinit] => A
[lastname] => NICHOLLS
[workdept] => C01
[phoneno] => 1793
[hiredate] => 1976-12-15
[job] => ANALYST
[edlevel] => 18
[sex] => F
[birthdate] => 1946-01-19
[salary] => 28420.00
[bonus] => 600.00
[comm] => 2274.00
)
Array
(
[empno] => 000130
[firstnme] => DELORES
[midinit] => M
[lastname] => QUINTANA
[workdept] => C01
[phoneno] => 4578
[hiredate] => 1971-07-28
[job] => ANALYST
[edlevel] => 16
[sex] => F
[birthdate] => 1925-09-15
[salary] => 23800.00
[bonus] => 500.00
[comm] => 1904.00
)]]></screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>db2_connect</function></member>
<member><function>db2_pconnect</function></member>
<member><function>db2_exec</function></member>
<member><function>db2_prepare</function></member>
<member><function>db2_cursor_type</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
-->
