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>
