cvs: phpdoc /en/reference/ibm_db2 configure.xml /en/reference/ibm_db2/functions db2-conn-error.xml db2-conn-errormsg.xml db2-exec.xml db2-execute.xml
db2-prepare.xml
| From: | Dan Scott | Date: | Wed, 13 Apr 2005 18:49:30 +0000 |
| Subject: | cvs: phpdoc /en/reference/ibm_db2 configure.xml /en/reference/ibm_db2/functions db2-conn-error.xml db2-conn-errormsg.xml db2-exec.xml db2-execute.xml db2-prepare.xml |
||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969367809@lists.php.net to get a copy of this message | ||
dbs Wed Apr 13 14:49:30 2005 EDT
Modified files:
/phpdoc/en/reference/ibm_db2 configure.xml
/phpdoc/en/reference/ibm_db2/functions db2-conn-error.xml
db2-conn-errormsg.xml
db2-exec.xml db2-execute.xml
db2-prepare.xml
Log:
More ibm_db2 function documentation goodness.
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/configure.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/configure.xml diff -u phpdoc/en/reference/ibm_db2/configure.xml:1.1 phpdoc/en/reference/ibm_db2/configure.xml:1.2 --- phpdoc/en/reference/ibm_db2/configure.xml:1.1 Tue Apr 12 19:45:14 2005 +++ phpdoc/en/reference/ibm_db2/configure.xml Wed Apr 13 14:49:24 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <section id="ibm_db2.installation"> &reftitle.install; <para> @@ -17,11 +17,11 @@ <para> ibm_db2 is a <ulink url="&url.pecl;">PECL</ulink> extension, so follow the instructions in <xref linkend='install.pecl' /> to install the ibm_db2 - extension for PHP. Issue the <command>configure</command> to point + extension for PHP. Issue the <command>configure</command> command to point to the location of your DB2 header files and libraries as follows: <screen> <![CDATA[ -bash$ ./configure --with-IBM_DB2 +bash$ ./configure --with-IBM_DB2=/path/to/DB2 ]]> </screen> The <command>configure</command> command defaults to http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml Wed Apr 13 14:49:29 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-conn-error"> <refnamediv> @@ -15,8 +15,27 @@ <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + <para> + <function>db2_conn_error</function> returns an SQLSTATE value representing + the reason the last attempt to connect to a database failed. As + <function>db2_connect</function> returns &false; in the event of a failed + connection attempt, you do not pass any parameters to + <function>db2_conn_error</function> to retrieve the SQLSTATE value. + </para> + <para> + If, however, the connection was successful but becomes invalid over time, + you can pass the <parameter>connection</parameter> parameter to retrieve + the SQLSTATE value for a specific connection. + </para> + <para> + To learn what the SQLSTATE value means, you can issue the following command + at a DB2 Command Line Processor prompt: + <userinput>db2 '? <parameter>sqlstate-value</parameter>'</userinput>. You + can also call <function>db2_conn_errormsg</function> to retrieve an + explicit error message and the associated SQLCODE value. + </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; @@ -24,74 +43,41 @@ <variablelist> <varlistentry> <term><parameter>connection</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <listitem> + <para> + A connection resource associated with a connection that initially + succeeded, but which over time became invalid. + </para> + </listitem> + </varlistentry> </variablelist> </para> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity - </para> - </refsect1> - - <!-- Use when EXCEPTIONS exist - <refsect1 role="exceptions"> - &reftitle.exceptions; - <para> - When does this function throw exceptions? - </para> - </refsect1> - --> - - - <!-- Use when a CHANGELOG exists - <refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Enter the PHP version of change here - <entry>Description of change - </row> - </tbody> - </tgroup> - </informaltable> + Returns the SQLSTATE value resulting from a failed connection attempt. + Returns an empty string if there is no error associated with the last + connection attempt. </para> </refsect1> - --> - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title>A <function>db2_conn_error</function> example</title> + <title>Retrieving an SQLSTATE value for a failed connection attempt</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example demonstrates how to return an SQLSTATE value + after deliberately passing invalid parameters to + <function>db2_connect</function>. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$conn = db2_connect('badname', 'baduser', 'badpassword'); +if (!$conn) { + print "SQLSTATE value: " . db2_conn_error(); } ?> ]]> @@ -99,26 +85,24 @@ &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +SQLSTATE value: 08001 ]]> </screen> </example> </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>db2_conn_errormsg</function></member> + <member><function>db2_connect</function></member> + <member><function>db2_stmt_error</function></member> + <member><function>db2_stmt_errormsg</function></member> </simplelist> </para> </refsect1> - --> </refentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml Wed Apr 13 14:49:30 2005 @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-conn-errormsg"> <refnamediv> <refname>db2_conn_errormsg</refname> <refpurpose> - Returns a string containing the last connection error message + Returns the last connection error message and SQLCODE value </refpurpose> </refnamediv> <refsect1 role="description"> @@ -15,8 +15,20 @@ <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; - + &warn.experimental.func; + <para> + <function>db2_conn_errormsg</function> returns an error message and SQLCODE + value representing the reason the last database connection attempt failed. + As <function>db2_connect</function> returns &false; in the event of a failed + connection attempt, do not pass any parameters to + <function>db2_conn_errormsg</function> to retrieve the associated error + message and SQLCODE value. + </para> + <para> + If, however, the connection was successful but becomes invalid over time, + you can pass the <parameter>connection</parameter> parameter to retrieve + the associated error message and SQLCODE value for a specific connection. + </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; @@ -26,7 +38,8 @@ <term><parameter>connection</parameter></term> <listitem> <para> - Its description + A connection resource associated with a connection that initially + succeeded, but which over time became invalid. </para> </listitem> </varlistentry> @@ -36,62 +49,29 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity - </para> - </refsect1> - - <!-- Use when EXCEPTIONS exist - <refsect1 role="exceptions"> - &reftitle.exceptions; - <para> - When does this function throw exceptions? - </para> - </refsect1> - --> - - - <!-- Use when a CHANGELOG exists - <refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Enter the PHP version of change here - <entry>Description of change - </row> - </tbody> - </tgroup> - </informaltable> + Returns a string containing the error message and SQLCODE value resulting + from a failed connection attempt. If there is no error associated with the last + connection attempt, <function>db2_conn_errormsg</function> returns an empty + string. </para> </refsect1> - --> - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title>A <function>db2_conn_errormsg</function> example</title> + <title>Retrieving the error message returned by a failed connection attempt</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example demonstrates how to return an error message and + SQLCODE value after deliberately passing invalid parameters to + <function>db2_connect</function>. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$conn = db2_connect('badname', 'baduser', 'badpassword'); +if (!$conn) { + print db2_conn_errormsg(); } ?> ]]> @@ -99,27 +79,26 @@ &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +Msg:[IBM][CLI Driver] SQL1013N The database alias name +or database name "BADNAME" could not be found. SQLSTATE=42705 + Err Code: -1013 ]]> </screen> </example> </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>db2_conn_error</function></member> + <member><function>db2_connect</function></member> + <member><function>db2_stmt_error</function></member> + <member><function>db2_stmt_errormsg</function></member> </simplelist> </para> </refsect1> - --> - </refentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-exec.xml?r1=1.2&r2=1.3&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-exec.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.2 phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.3 --- phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.2 Tue Apr 12 20:37:15 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-exec.xml Wed Apr 13 14:49:30 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-exec"> <refnamediv> @@ -54,7 +54,7 @@ <term><parameter>statement</parameter></term> <listitem> <para> - An SQL statement. + An SQL statement. The statement cannot contain any parameter markers. </para> </listitem> </varlistentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-execute.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-execute.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-execute.xml Wed Apr 13 14:49:30 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-execute"> <refnamediv> @@ -13,10 +13,31 @@ <methodsynopsis> <type>bool</type><methodname>db2_execute</methodname> <methodparam><type>resource</type><parameter>stmt</parameter></methodparam> - <methodparam choice="opt"><type>array</type><parameter>parameters_array</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>parameters</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + + <para> + <function>db2_execute</function> executes an SQL statement that was + prepared by <function>db2_prepare</function>. + </para> + <para> + If the SQL statement returns a result set, for example, a SELECT statement + or a CALL to a stored procedure that returns one or more result sets, you + can retrieve a row as an array from the <literal>stmt</literal> resource + using <function>db2_fetch_assoc</function>, + <function>db2_fetch_both</function>, or + <function>db2_fetch_into</function>. Alternatively, you can use + <function>db2_fetch_row</function> to move the result set pointer to the + next row and fetch a column at a time from that row with + <function>db2_result</function>. + </para> + <para> + Refer to <function>db2_prepare</function> for a brief discussion of the + advantages of using <function>db2_prepare</function> and + <function>db2_execute</function> rather than <function>db2_exec</function>. + </para> </refsect1> <refsect1 role="parameters"> @@ -27,15 +48,16 @@ <term><parameter>stmt</parameter></term> <listitem> <para> - Its description + A prepared statement returned from <function>db2_prepare</function>. </para> </listitem> </varlistentry> <varlistentry> - <term><parameter>parameters_array</parameter></term> + <term><parameter>parameters</parameter></term> <listitem> <para> - Its description + An array of input parameters matching any parameter markers contained + in the prepared statement. </para> </listitem> </varlistentry> @@ -45,62 +67,34 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity - </para> - </refsect1> - - <!-- Use when EXCEPTIONS exist - <refsect1 role="exceptions"> - &reftitle.exceptions; - <para> - When does this function throw exceptions? + &return.success; </para> </refsect1> - --> - - <!-- Use when a CHANGELOG exists - <refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Enter the PHP version of change here - <entry>Description of change - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </refsect1> - --> - - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title>A <function>db2_execute</function> example</title> + <title>Preparing and executing an SQL statement with parameter markers</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example prepares an INSERT statement that accepts four + parameter markers, then iterates over an array of arrays containg the + input values to be passed to <function>db2_execute</function>. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$pet = array(0, 'cat', 'Pook', 3.2); + +$insert = 'INSERT INTO animals (id, breed, name, weight) + VALUES (?, ?, ?, ?)'; + +$stmt = db2_prepare($conn, $insert); +if ($stmt) { + $result = db2_execute($stmt, $pet); + if ($result) { + print "Successfully added new pet."; + } } ?> ]]> @@ -108,26 +102,59 @@ &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +Successfully added new pet. ]]> </screen> </example> + <example> + <title>Calling a stored procedure with an OUT parameter</title> + <para> + The following example prepares a CALL statement that accepts one + parameter marker representing an OUT parameter, binds the PHP variable + <literal>$my_pets</literal> to the parameter using + <function>db2_bind_param</function>, then issues + <function>db2_execute</function> to execute the CALL statement. After the + CALL to the stored procedure has been made, the value of + <literal>$num_pets</literal> changes to reflect the value returned by the + stored procedure for that OUT parameter. + </para> + <programlisting role="php"> +<![CDATA[ +<?php +$num_pets = 0; +$res = db2_prepare($conn, "CALL count_my_pets(?)"); +$rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT); +$rc = db2_execute($res); +print "I have $num_pets pets!"; +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +I have 7 pets! +]]> + </screen> + </example> + + </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>db2_exec</function></member> + <member><function>db2_fetch_assoc</function></member> + <member><function>db2_fetch_both</function></member> + <member><function>db2_fetch_into</function></member> + <member><function>db2_fetch_row</function></member> + <member><function>db2_prepare</function></member> + <member><function>db2_result</function></member> </simplelist> </para> </refsect1> - --> </refentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml Wed Apr 13 14:49:30 2005 @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-prepare"> <refnamediv> <refname>db2_prepare</refname> <refpurpose> - Prepares an SQL statement + Prepares an SQL statement to be executed </refpurpose> </refnamediv> <refsect1 role="description"> @@ -13,11 +13,53 @@ <methodsynopsis> <type>resource</type><methodname>db2_prepare</methodname> <methodparam><type>resource</type><parameter>connection</parameter></methodparam> - <methodparam><type>string</type><parameter>stmt_string</parameter></methodparam> + <methodparam><type>string</type><parameter>statement</parameter></methodparam> <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + + <para> + <function>db2_prepare</function> creates a prepared SQL statement which can + include 0 or more parameter markers (<literal>?</literal> characters) + representing parameters for input, output, or input/output. You can pass + parameters to the prepared statement using + <function>db2_bind_param</function>, or for input values only, as an array + passed to <function>db2_execute</function>. + </para> + <para> + There are three main advantages to using prepared statements in your + application: + <itemizedlist> + <listitem> + <para> + <emphasis>Performance</emphasis>: when you prepare a statement, the + database server creates an optimized access plan for retrieving data with + that statement. Subsequently issuing the prepared statement with + <function>db2_execute</function> enables the statements to reuse that + access plan and avoids the overhead of dynamically creating a new access + plan for every statement you issue. + </para> + </listitem> + <listitem> + <para> + <emphasis>Security</emphasis>: when you prepare a statement, you can + include parameter markers for input values. When you execute a prepared + statement with input values for placeholders, the database server checks + each input value to ensure that the type matches the column definition or + parameter definition. + </para> + </listitem> + <listitem> + <para> + <emphasis>Advanced functionality</emphasis>: Parameter markers not only + enable you to pass input values to prepared SQL statements, they also + enable you to retrieve OUT and INOUT parameters from stored procedures + using <function>db2_bind_param</function>. + </para> + </listitem> + </itemizedlist> + </para> </refsect1> <refsect1 role="parameters"> @@ -26,118 +68,148 @@ <variablelist> <varlistentry> <term><parameter>connection</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <listitem> + <para> + A valid database connection resource variable as returned from + <function>db2_connect</function> or <function>db2_pconnect</function>. + </para> + </listitem> + </varlistentry> <varlistentry> - <term><parameter>stmt_string</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <term><parameter>statement</parameter></term> + <listitem> + <para> + An SQL statement, optionally containing one or more parameter markers.. + </para> + </listitem> + </varlistentry> <varlistentry> <term><parameter>options</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <listitem> + <para> + An associative array containing statement options. You can use this + parameter to request a scrollable cursor on database servers that + support this functionality. + <variablelist> + <varlistentry> + <term><parameter>cursor</parameter></term> + <listitem> + <para> + Passing the <literal>DB2_FORWARD_ONLY</literal> value requests a + forward-only cursor for this SQL statement. This is the default + type of cursor, and it is supported by all database servers. It is + also much faster than a scrollable cursor. + </para> + <para> + Passing the <literal>DB2_SCROLLABLE</literal> value requests a + scrollable cursor for this SQL statement. This type of cursor + enables you to fetch rows non-sequentially from the database + server. However, it is only supported by DB2 servers, and is much + slower than forward-only cursors. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> </variablelist> </para> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity - </para> - </refsect1> - - <!-- Use when EXCEPTIONS exist - <refsect1 role="exceptions"> - &reftitle.exceptions; - <para> - When does this function throw exceptions? - </para> - </refsect1> - --> - - - <!-- Use when a CHANGELOG exists - <refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Enter the PHP version of change here - <entry>Description of change - </row> - </tbody> - </tgroup> - </informaltable> + Returns a statement resource if the SQL statement was successfully parsed and + prepared by the database server. Returns &false; if the database server + returned an error. You can determine which error was returned by calling + <function>db2_stmt_error</function> or <function>db2_stmt_errormsg</function>. </para> </refsect1> - --> - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title>A <function>db2_prepare</function> example</title> + <title>Preparing and executing an SQL statement with parameter markers</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example prepares an INSERT statement that accepts four + parameter markers, then iterates over an array of arrays containg the + input values to be passed to <function>db2_execute</function>. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$animals = array( + array(0, 'cat', 'Pook', 3.2), + array(1, 'dog', 'Peaches', 12.3), + array(2, 'horse', 'Smarty', 350.0), +); + +$insert = 'INSERT INTO animals (id, breed, name, weight) + VALUES (?, ?, ?, ?)'; +$stmt = db2_prepare($conn, $insert); +if ($stmt) { + foreach ($animals as $animal) { + $result = db2_execute($stmt, $animal); + } } ?> ]]> </programlisting> + </example> + <!-- + <example> + <title>Preventing SQL injection attacks using parameter markers</title> + <para> + Parameter markers make it impossible for a malicious user of your + application to pass input values that map to more than one database + field or stored procedure parameter. The following example demonstrates + a common tactic for attacking database-driven Web applications, SQL + injection, which takes advantage of applications that often simply + interpolate the input values from a user directly into an SQL statement + rather than defining parameter markers and binding the input values to + those parameter markers. + </para> + <para> + In the following example, assume that the PHP script has been placed on + a publically accessible Web server and the application provides + different levels of access for different users. We shall also assume + that the application issues an SQL statement that updates the privilege + level of a newly registered user to the lowest level, taking the user ID + from a GET input variable. In the following example, a malicious user + can pass <userinput>userid=0+OR+1=1</userinput> (instead of the expected + <userinput>userid=0</userinput>) to trick your application into + setting the privilege level of every user in the database to the lowest + level. + </para> + <programlisting role="php"> +<![CDATA[ +<?php + +?> +]]> + </programlisting> &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards ]]> </screen> </example> + --> </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>db2_bind_param</function></member> + <member><function>db2_execute</function></member> + <member><function>db2_stmt_error</function></member> + <member><function>db2_stmt_errormsg</function></member> </simplelist> </para> </refsect1> - --> - </refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/configure.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/configure.xml diff -u phpdoc/en/reference/ibm_db2/configure.xml:1.1 phpdoc/en/reference/ibm_db2/configure.xml:1.2 --- phpdoc/en/reference/ibm_db2/configure.xml:1.1 Tue Apr 12 19:45:14 2005 +++ phpdoc/en/reference/ibm_db2/configure.xml Wed Apr 13 14:49:24 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <section id="ibm_db2.installation"> &reftitle.install; <para> @@ -17,11 +17,11 @@ <para> ibm_db2 is a <ulink url="&url.pecl;">PECL</ulink> extension, so follow the instructions in <xref linkend='install.pecl' /> to install the ibm_db2 - extension for PHP. Issue the <command>configure</command> to point + extension for PHP. Issue the <command>configure</command> command to point to the location of your DB2 header files and libraries as follows: <screen> <![CDATA[ -bash$ ./configure --with-IBM_DB2 +bash$ ./configure --with-IBM_DB2=/path/to/DB2 ]]> </screen> The <command>configure</command> command defaults to http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-conn-error.xml Wed Apr 13 14:49:29 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-conn-error"> <refnamediv> @@ -15,8 +15,27 @@ <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + <para> + <function>db2_conn_error</function> returns an SQLSTATE value representing + the reason the last attempt to connect to a database failed. As + <function>db2_connect</function> returns &false; in the event of a failed + connection attempt, you do not pass any parameters to + <function>db2_conn_error</function> to retrieve the SQLSTATE value. + </para> + <para> + If, however, the connection was successful but becomes invalid over time, + you can pass the <parameter>connection</parameter> parameter to retrieve + the SQLSTATE value for a specific connection. + </para> + <para> + To learn what the SQLSTATE value means, you can issue the following command + at a DB2 Command Line Processor prompt: + <userinput>db2 '? <parameter>sqlstate-value</parameter>'</userinput>. You + can also call <function>db2_conn_errormsg</function> to retrieve an + explicit error message and the associated SQLCODE value. + </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; @@ -24,74 +43,41 @@ <variablelist> <varlistentry> <term><parameter>connection</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <listitem> + <para> + A connection resource associated with a connection that initially + succeeded, but which over time became invalid. + </para> + </listitem> + </varlistentry> </variablelist> </para> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity - </para> - </refsect1> - - <!-- Use when EXCEPTIONS exist - <refsect1 role="exceptions"> - &reftitle.exceptions; - <para> - When does this function throw exceptions? - </para> - </refsect1> - --> - - - <!-- Use when a CHANGELOG exists - <refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Enter the PHP version of change here - <entry>Description of change - </row> - </tbody> - </tgroup> - </informaltable> + Returns the SQLSTATE value resulting from a failed connection attempt. + Returns an empty string if there is no error associated with the last + connection attempt. </para> </refsect1> - --> - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title>A <function>db2_conn_error</function> example</title> + <title>Retrieving an SQLSTATE value for a failed connection attempt</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example demonstrates how to return an SQLSTATE value + after deliberately passing invalid parameters to + <function>db2_connect</function>. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$conn = db2_connect('badname', 'baduser', 'badpassword'); +if (!$conn) { + print "SQLSTATE value: " . db2_conn_error(); } ?> ]]> @@ -99,26 +85,24 @@ &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +SQLSTATE value: 08001 ]]> </screen> </example> </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>db2_conn_errormsg</function></member> + <member><function>db2_connect</function></member> + <member><function>db2_stmt_error</function></member> + <member><function>db2_stmt_errormsg</function></member> </simplelist> </para> </refsect1> - --> </refentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-conn-errormsg.xml Wed Apr 13 14:49:30 2005 @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-conn-errormsg"> <refnamediv> <refname>db2_conn_errormsg</refname> <refpurpose> - Returns a string containing the last connection error message + Returns the last connection error message and SQLCODE value </refpurpose> </refnamediv> <refsect1 role="description"> @@ -15,8 +15,20 @@ <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; - + &warn.experimental.func; + <para> + <function>db2_conn_errormsg</function> returns an error message and SQLCODE + value representing the reason the last database connection attempt failed. + As <function>db2_connect</function> returns &false; in the event of a failed + connection attempt, do not pass any parameters to + <function>db2_conn_errormsg</function> to retrieve the associated error + message and SQLCODE value. + </para> + <para> + If, however, the connection was successful but becomes invalid over time, + you can pass the <parameter>connection</parameter> parameter to retrieve + the associated error message and SQLCODE value for a specific connection. + </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; @@ -26,7 +38,8 @@ <term><parameter>connection</parameter></term> <listitem> <para> - Its description + A connection resource associated with a connection that initially + succeeded, but which over time became invalid. </para> </listitem> </varlistentry> @@ -36,62 +49,29 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity - </para> - </refsect1> - - <!-- Use when EXCEPTIONS exist - <refsect1 role="exceptions"> - &reftitle.exceptions; - <para> - When does this function throw exceptions? - </para> - </refsect1> - --> - - - <!-- Use when a CHANGELOG exists - <refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Enter the PHP version of change here - <entry>Description of change - </row> - </tbody> - </tgroup> - </informaltable> + Returns a string containing the error message and SQLCODE value resulting + from a failed connection attempt. If there is no error associated with the last + connection attempt, <function>db2_conn_errormsg</function> returns an empty + string. </para> </refsect1> - --> - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title>A <function>db2_conn_errormsg</function> example</title> + <title>Retrieving the error message returned by a failed connection attempt</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example demonstrates how to return an error message and + SQLCODE value after deliberately passing invalid parameters to + <function>db2_connect</function>. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$conn = db2_connect('badname', 'baduser', 'badpassword'); +if (!$conn) { + print db2_conn_errormsg(); } ?> ]]> @@ -99,27 +79,26 @@ &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +Msg:[IBM][CLI Driver] SQL1013N The database alias name +or database name "BADNAME" could not be found. SQLSTATE=42705 + Err Code: -1013 ]]> </screen> </example> </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>db2_conn_error</function></member> + <member><function>db2_connect</function></member> + <member><function>db2_stmt_error</function></member> + <member><function>db2_stmt_errormsg</function></member> </simplelist> </para> </refsect1> - --> - </refentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-exec.xml?r1=1.2&r2=1.3&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-exec.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.2 phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.3 --- phpdoc/en/reference/ibm_db2/functions/db2-exec.xml:1.2 Tue Apr 12 20:37:15 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-exec.xml Wed Apr 13 14:49:30 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.2 $ --> +<!-- $Revision: 1.3 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-exec"> <refnamediv> @@ -54,7 +54,7 @@ <term><parameter>statement</parameter></term> <listitem> <para> - An SQL statement. + An SQL statement. The statement cannot contain any parameter markers. </para> </listitem> </varlistentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-execute.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-execute.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-execute.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-execute.xml Wed Apr 13 14:49:30 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-execute"> <refnamediv> @@ -13,10 +13,31 @@ <methodsynopsis> <type>bool</type><methodname>db2_execute</methodname> <methodparam><type>resource</type><parameter>stmt</parameter></methodparam> - <methodparam choice="opt"><type>array</type><parameter>parameters_array</parameter></methodparam> + <methodparam choice="opt"><type>array</type><parameter>parameters</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + + <para> + <function>db2_execute</function> executes an SQL statement that was + prepared by <function>db2_prepare</function>. + </para> + <para> + If the SQL statement returns a result set, for example, a SELECT statement + or a CALL to a stored procedure that returns one or more result sets, you + can retrieve a row as an array from the <literal>stmt</literal> resource + using <function>db2_fetch_assoc</function>, + <function>db2_fetch_both</function>, or + <function>db2_fetch_into</function>. Alternatively, you can use + <function>db2_fetch_row</function> to move the result set pointer to the + next row and fetch a column at a time from that row with + <function>db2_result</function>. + </para> + <para> + Refer to <function>db2_prepare</function> for a brief discussion of the + advantages of using <function>db2_prepare</function> and + <function>db2_execute</function> rather than <function>db2_exec</function>. + </para> </refsect1> <refsect1 role="parameters"> @@ -27,15 +48,16 @@ <term><parameter>stmt</parameter></term> <listitem> <para> - Its description + A prepared statement returned from <function>db2_prepare</function>. </para> </listitem> </varlistentry> <varlistentry> - <term><parameter>parameters_array</parameter></term> + <term><parameter>parameters</parameter></term> <listitem> <para> - Its description + An array of input parameters matching any parameter markers contained + in the prepared statement. </para> </listitem> </varlistentry> @@ -45,62 +67,34 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity - </para> - </refsect1> - - <!-- Use when EXCEPTIONS exist - <refsect1 role="exceptions"> - &reftitle.exceptions; - <para> - When does this function throw exceptions? + &return.success; </para> </refsect1> - --> - - <!-- Use when a CHANGELOG exists - <refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Enter the PHP version of change here - <entry>Description of change - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </refsect1> - --> - - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title>A <function>db2_execute</function> example</title> + <title>Preparing and executing an SQL statement with parameter markers</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example prepares an INSERT statement that accepts four + parameter markers, then iterates over an array of arrays containg the + input values to be passed to <function>db2_execute</function>. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$pet = array(0, 'cat', 'Pook', 3.2); + +$insert = 'INSERT INTO animals (id, breed, name, weight) + VALUES (?, ?, ?, ?)'; + +$stmt = db2_prepare($conn, $insert); +if ($stmt) { + $result = db2_execute($stmt, $pet); + if ($result) { + print "Successfully added new pet."; + } } ?> ]]> @@ -108,26 +102,59 @@ &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +Successfully added new pet. ]]> </screen> </example> + <example> + <title>Calling a stored procedure with an OUT parameter</title> + <para> + The following example prepares a CALL statement that accepts one + parameter marker representing an OUT parameter, binds the PHP variable + <literal>$my_pets</literal> to the parameter using + <function>db2_bind_param</function>, then issues + <function>db2_execute</function> to execute the CALL statement. After the + CALL to the stored procedure has been made, the value of + <literal>$num_pets</literal> changes to reflect the value returned by the + stored procedure for that OUT parameter. + </para> + <programlisting role="php"> +<![CDATA[ +<?php +$num_pets = 0; +$res = db2_prepare($conn, "CALL count_my_pets(?)"); +$rc = db2_bind_param($res, 1, "num_pets", DB2_PARAM_OUT); +$rc = db2_execute($res); +print "I have $num_pets pets!"; +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +I have 7 pets! +]]> + </screen> + </example> + + </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>db2_exec</function></member> + <member><function>db2_fetch_assoc</function></member> + <member><function>db2_fetch_both</function></member> + <member><function>db2_fetch_into</function></member> + <member><function>db2_fetch_row</function></member> + <member><function>db2_prepare</function></member> + <member><function>db2_result</function></member> </simplelist> </para> </refsect1> - --> </refentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-prepare.xml Wed Apr 13 14:49:30 2005 @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.db2-prepare"> <refnamediv> <refname>db2_prepare</refname> <refpurpose> - Prepares an SQL statement + Prepares an SQL statement to be executed </refpurpose> </refnamediv> <refsect1 role="description"> @@ -13,11 +13,53 @@ <methodsynopsis> <type>resource</type><methodname>db2_prepare</methodname> <methodparam><type>resource</type><parameter>connection</parameter></methodparam> - <methodparam><type>string</type><parameter>stmt_string</parameter></methodparam> + <methodparam><type>string</type><parameter>statement</parameter></methodparam> <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + + <para> + <function>db2_prepare</function> creates a prepared SQL statement which can + include 0 or more parameter markers (<literal>?</literal> characters) + representing parameters for input, output, or input/output. You can pass + parameters to the prepared statement using + <function>db2_bind_param</function>, or for input values only, as an array + passed to <function>db2_execute</function>. + </para> + <para> + There are three main advantages to using prepared statements in your + application: + <itemizedlist> + <listitem> + <para> + <emphasis>Performance</emphasis>: when you prepare a statement, the + database server creates an optimized access plan for retrieving data with + that statement. Subsequently issuing the prepared statement with + <function>db2_execute</function> enables the statements to reuse that + access plan and avoids the overhead of dynamically creating a new access + plan for every statement you issue. + </para> + </listitem> + <listitem> + <para> + <emphasis>Security</emphasis>: when you prepare a statement, you can + include parameter markers for input values. When you execute a prepared + statement with input values for placeholders, the database server checks + each input value to ensure that the type matches the column definition or + parameter definition. + </para> + </listitem> + <listitem> + <para> + <emphasis>Advanced functionality</emphasis>: Parameter markers not only + enable you to pass input values to prepared SQL statements, they also + enable you to retrieve OUT and INOUT parameters from stored procedures + using <function>db2_bind_param</function>. + </para> + </listitem> + </itemizedlist> + </para> </refsect1> <refsect1 role="parameters"> @@ -26,118 +68,148 @@ <variablelist> <varlistentry> <term><parameter>connection</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <listitem> + <para> + A valid database connection resource variable as returned from + <function>db2_connect</function> or <function>db2_pconnect</function>. + </para> + </listitem> + </varlistentry> <varlistentry> - <term><parameter>stmt_string</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <term><parameter>statement</parameter></term> + <listitem> + <para> + An SQL statement, optionally containing one or more parameter markers.. + </para> + </listitem> + </varlistentry> <varlistentry> <term><parameter>options</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <listitem> + <para> + An associative array containing statement options. You can use this + parameter to request a scrollable cursor on database servers that + support this functionality. + <variablelist> + <varlistentry> + <term><parameter>cursor</parameter></term> + <listitem> + <para> + Passing the <literal>DB2_FORWARD_ONLY</literal> value requests a + forward-only cursor for this SQL statement. This is the default + type of cursor, and it is supported by all database servers. It is + also much faster than a scrollable cursor. + </para> + <para> + Passing the <literal>DB2_SCROLLABLE</literal> value requests a + scrollable cursor for this SQL statement. This type of cursor + enables you to fetch rows non-sequentially from the database + server. However, it is only supported by DB2 servers, and is much + slower than forward-only cursors. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> </variablelist> </para> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity - </para> - </refsect1> - - <!-- Use when EXCEPTIONS exist - <refsect1 role="exceptions"> - &reftitle.exceptions; - <para> - When does this function throw exceptions? - </para> - </refsect1> - --> - - - <!-- Use when a CHANGELOG exists - <refsect1 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Enter the PHP version of change here - <entry>Description of change - </row> - </tbody> - </tgroup> - </informaltable> + Returns a statement resource if the SQL statement was successfully parsed and + prepared by the database server. Returns &false; if the database server + returned an error. You can determine which error was returned by calling + <function>db2_stmt_error</function> or <function>db2_stmt_errormsg</function>. </para> </refsect1> - --> - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title>A <function>db2_prepare</function> example</title> + <title>Preparing and executing an SQL statement with parameter markers</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example prepares an INSERT statement that accepts four + parameter markers, then iterates over an array of arrays containg the + input values to be passed to <function>db2_execute</function>. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$animals = array( + array(0, 'cat', 'Pook', 3.2), + array(1, 'dog', 'Peaches', 12.3), + array(2, 'horse', 'Smarty', 350.0), +); + +$insert = 'INSERT INTO animals (id, breed, name, weight) + VALUES (?, ?, ?, ?)'; +$stmt = db2_prepare($conn, $insert); +if ($stmt) { + foreach ($animals as $animal) { + $result = db2_execute($stmt, $animal); + } } ?> ]]> </programlisting> + </example> + <!-- + <example> + <title>Preventing SQL injection attacks using parameter markers</title> + <para> + Parameter markers make it impossible for a malicious user of your + application to pass input values that map to more than one database + field or stored procedure parameter. The following example demonstrates + a common tactic for attacking database-driven Web applications, SQL + injection, which takes advantage of applications that often simply + interpolate the input values from a user directly into an SQL statement + rather than defining parameter markers and binding the input values to + those parameter markers. + </para> + <para> + In the following example, assume that the PHP script has been placed on + a publically accessible Web server and the application provides + different levels of access for different users. We shall also assume + that the application issues an SQL statement that updates the privilege + level of a newly registered user to the lowest level, taking the user ID + from a GET input variable. In the following example, a malicious user + can pass <userinput>userid=0+OR+1=1</userinput> (instead of the expected + <userinput>userid=0</userinput>) to trick your application into + setting the privilege level of every user in the database to the lowest + level. + </para> + <programlisting role="php"> +<![CDATA[ +<?php + +?> +]]> + </programlisting> &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards ]]> </screen> </example> + --> </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>db2_bind_param</function></member> + <member><function>db2_execute</function></member> + <member><function>db2_stmt_error</function></member> + <member><function>db2_stmt_errormsg</function></member> </simplelist> </para> </refsect1> - --> - </refentry>