cvs: phpdoc /en/reference/ibm_db2/functions db2-commit.xml db2-next-result.xml db2-rollback.xml

dbs Wed Apr 20 02:16:13 2005 EDT Modified files: /phpdoc/en/reference/ibm_db2/functions db2-commit.xml db2-next-result.xml db2-rollback.xml Log: Document the transactional functions. Add docs for returning multiple result sets from stored procedures.

http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-commit.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-commit.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-commit.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-commit.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-commit.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-commit.xml Wed Apr 20 02:16:12 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-commit"> <refnamediv> @@ -15,7 +15,22 @@ <methodparam><type>resource</type><parameter>connection</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + + <para> + Commits an in-progress transaction on the specified connection resource and + begins a new transaction. PHP applications normally default to AUTOCOMMIT + mode, so <function>db2_commit</function> is not necessary unless AUTOCOMMIT + has been turned off for the connection resource. + </para> + <note> + <para> + If the specified connection resource is a persistent connection, all + transactions in progress for all applications using that persistent + connection will be committed. For this reason, persistent connections are + not recommended for use in applications that require transactions. + </para> + </note> </refsect1> <refsect1 role="parameters"> @@ -24,58 +39,23 @@ <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> </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 + &return.success; </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> - </para> - </refsect1> - --> - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; @@ -107,19 +87,15 @@ </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_autocommit</function></member> + <member><function>db2_rollback</function></member> </simplelist> </para> </refsect1> - --> - </refentry> http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-next-result.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-next-result.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-next-result.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-next-result.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-next-result.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-next-result.xml Wed Apr 20 02:16:13 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-next-result"> <refnamediv> @@ -15,7 +15,16 @@ <methodparam><type>resource</type><parameter>stmt</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + + <para> + A stored procedure can return zero or more result sets. While you handle + the first result set in exactly the same way you would handle the results + returned by a simple SELECT statement, to fetch the second and subsequent + result sets from a stored procedure you must call the + <function>db2_next_result</function> function and return the result to a + uniquely named PHP variable. + </para> </refsect1> <refsect1 role="parameters"> @@ -24,74 +33,68 @@ <variablelist> <varlistentry> <term><parameter>stmt</parameter></term> - <listitem> - <para> - Its description - </para> - </listitem> - </varlistentry> + <listitem> + <para> + A prepared statement returned from <function>db2_exec</function> or + <function>db2_execute</function>. + </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? + Returns a new statement resource containing the next result set if the + stored procedure returned another result set. Returns &false; if the stored + procedure did not return another result set. </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_next_result</function> example</title> + <title>Calling a stored procedure that returns multiple result sets</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 + In the following example, we call a stored procedure that returns three + result sets. The first result set is fetched directly from the same + statement resource on which we invoked the CALL statement, while the + second and third result sets are fetched from statement resources + returned from our calls to the <function>db2_next_result</function> + function. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; +$conn = db2_connect($database, $user, $password); + +if ($conn) { + $stmt = db2_exec($conn, 'CALL multiResults()'); + + print "Fetching first result set\n"; + while ($row = db2_fetch_into($stmt)) { + var_dump($row); + } + + print "\nFetching second result set\n"; + $res = db2_next_result($stmt); + if ($res) { + while ($row = db2_fetch_into($res)) { + var_dump($row); + } + } + + print "\nFetching third result set\n"; + $res2 = db2_next_result($stmt); + if ($res2) { + while ($row = db2_fetch_into($res2)) { + var_dump($row); + } + } + + db2_close($conn); } ?> ]]> @@ -99,13 +102,56 @@ &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +Fetching first result set +array(2) { + [0]=> + string(16) "Bubbles " + [1]=> + int(3) +} +array(2) { + [0]=> + string(16) "Gizmo " + [1]=> + int(4) +} + +Fetching second result set +array(4) { + [0]=> + string(16) "Sweater " + [1]=> + int(6) + [2]=> + string(5) "llama" + [3]=> + string(6) "150.00" +} +array(4) { + [0]=> + string(16) "Smarty " + [1]=> + int(2) + [2]=> + string(5) "horse" + [3]=> + string(6) "350.00" +} + +Fetching third result set +array(1) { + [0]=> + string(16) "Bubbles " +} +array(1) { + [0]=> + string(16) "Gizmo " +} ]]> </screen> </example> </para> </refsect1> - --> <!-- Use when adding See Also links http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-rollback.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/ibm_db2/functions/db2-rollback.xml diff -u phpdoc/en/reference/ibm_db2/functions/db2-rollback.xml:1.1 phpdoc/en/reference/ibm_db2/functions/db2-rollback.xml:1.2 --- phpdoc/en/reference/ibm_db2/functions/db2-rollback.xml:1.1 Tue Apr 12 17:12:48 2005 +++ phpdoc/en/reference/ibm_db2/functions/db2-rollback.xml Wed Apr 20 02:16:13 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-rollback"> <refnamediv> @@ -15,7 +15,22 @@ <methodparam><type>resource</type><parameter>connection</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + <para> + Rolls back an in-progress transaction on the specified connection resource and + begins a new transaction. PHP applications normally default to AUTOCOMMIT + mode, so <function>db2_rollback</function> normally has no effect unless + AUTOCOMMIT has been turned off for the connection resource. + </para> + <note> + <para> + If the specified connection resource is a persistent connection, all + transactions in progress for all applications using that persistent + connection will be rolled back. For this reason, persistent connections + are not recommended for use in applications that require transactions. + </para> + </note> + </refsect1> <refsect1 role="parameters"> @@ -24,102 +39,89 @@ <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> </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? + &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_rollback</function> example</title> + <title>Rolling back a DELETE statement</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 + In the following example, we count the number of rows in a table, turn + off AUTOCOMMIT mode on a database connection, delete all of the rows in + the table and return the count of <literal>0</literal> to prove that the + rows have been removed. We then issue <function>db2_rollback</function> + and return the updated count of rows in the table to show that the number + is the same as before we issued the DELETE statement. The return to the + original state of the table demonstrates that the roll back of the + transaction succeeded. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; -} +$conn = db2_connect($database, $user, $password); + +if ($conn) { + $stmt = db2_exec($conn, "SELECT count(*) FROM animals"); + $res = db2_fetch_into( $stmt ); + echo $res[0] . "\n"; + + // Turn AUTOCOMMIT off + db2_autocommit($conn, DB2_AUTOCOMMIT_OFF); + + // Delete all rows from ANIMALS + db2_exec($conn, "DELETE FROM animals"); + + $stmt = db2_exec($conn, "SELECT count(*) FROM animals"); + $res = db2_fetch_into( $stmt ); + echo $res[0] . "\n"; + + // Roll back the DELETE statement + db2_rollback( $conn ); + + $stmt = db2_exec( $conn, "SELECT count(*) FROM animals" ); + $res = db2_fetch_into( $stmt ); + echo $res[0] . "\n"; + db2_close($conn); ?> ]]> </programlisting> &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +7 +0 +7 ]]> </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_autocommit</function></member> + <member><function>db2_commit</function></member> </simplelist> </para> </refsect1> - --> - </refentry>