dbs Sat Apr 16 22:50:02 2005 EDT
Modified files:
/phpdoc/en/reference/ibm_db2/functions db2-fetch-assoc.xml
db2-fetch-both.xml
db2-fetch-into.xml
db2-num-rows.xml
Log:
Document db2_fetch* functions that return arrays.
Document db2_num_rows.
Over-emphasize why it's a bad idea to use db2_num_rows with SELECT.
http://cvs.php.net/diff.php/phpdoc/en/reference/ibm_db2/functions/db2-fetch-assoc.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-fetch-assoc.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-fetch-assoc.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-fetch-assoc.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-fetch-assoc.xml:1.1 Tue Apr
12 17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-fetch-assoc.xml Sat Apr 16
22:50:00 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-fetch-assoc">
<refnamediv>
@@ -16,7 +16,12 @@
<methodparam
choice="opt"><type>int</type><parameter>row_number</parameter></methodparam>
</methodsynopsis>
- &warn.undocumented.func;
+ &warn.experimental.func;
+
+ <para>
+ Returns an array, indexed by column name, representing a row in a result
+ set.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -25,82 +30,55 @@
<variablelist>
<varlistentry>
<term><parameter>stmt</parameter></term>
- <listitem>
- <para>
- Its description
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ A valid <literal>stmt</literal> resource containing a result set.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><parameter>row_number</parameter></term>
- <listitem>
- <para>
- Its description
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ Requests a specific 1-indexed row from the result set. Passing this
+ parameter results in a PHP warning if the result set uses a
+ forward-only cursor.
+ </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 an associative array with column values indexed by the column name
+ representing the next or requested row in the result set. Returns &false; if
+ there are no rows left in the result set, or if the row requested by
+ <parameter>row_number</parameter> does not exist in the result set.
</para>
</refsect1>
- -->
-
- <!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
- <title>A <function>db2_fetch_assoc</function> example</title>
+ <title>Iterating through a forward-only cursor</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
+ If you call <function>db2_fetch_assoc</function> without a specific row
+ number, it automatically retrieves the next row in the result set.
</para>
<programlisting role="php">
<![CDATA[
<?php
-if ($anexample === true) {
- echo 'Use the PEAR Coding Standards';
+
+$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
+$stmt = db2_prepare($conn, $sql);
+$result = db2_execute($stmt, $sql);
+
+while ($row = db2_fetch_assoc($result)) {
+ printf ("%-5d %-16s %-32s %10s\n",
+ $row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
}
?>
]]>
@@ -108,27 +86,61 @@
&example.outputs;
<screen>
<![CDATA[
-Use the PEAR Coding Standards
+0 Pook cat 3.20
+5 Rickety Ride goat 9.70
+2 Smarty horse 350.00
+]]>
+ </screen>
+ </example>
+
+ <example>
+ <title>Retrieving specific rows with <function>db2_fetch_assoc</function>
+ from a scrollable cursor</title>
+ <para>
+ If your result set uses a scrollable cursor, you can call
+ <function>db2_fetch_assoc</function> with a specific row number. The
+ following example retrieves every other row in the result set, starting
+ with the second row.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
+$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));
+
+$i=2;
+while ($row = db2_fetch_assoc($result, $i)) {
+ printf ("%-5d %-16s %-32s %10s\n",
+ $row['ID'], $row['NAME'], $row['BREED'], $row['WEIGHT']);
+ $i = $i + 2;
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+0 Pook cat 3.20
+5 Rickety Ride goat 9.70
+2 Smarty horse 350.00
]]>
</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_fetch_both</function></member>
+ <member><function>db2_fetch_into</function></member>
+ <member><function>db2_fetch_row</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-fetch-both.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-fetch-both.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-fetch-both.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-fetch-both.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-fetch-both.xml:1.1 Tue Apr
12 17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-fetch-both.xml Sat Apr 16
22:50:00 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-fetch-both">
<refnamediv>
@@ -16,7 +16,15 @@
<methodparam
choice="opt"><type>int</type><parameter>row_number</parameter></methodparam>
</methodsynopsis>
- &warn.undocumented.func;
+ &warn.experimental.func;
+
+ <para>
+ Returns an array, indexed by both column name and position, representing a
+ row in a result set. Note that the row returned by
+ <function>db2_fetch_both</function> requires more memory than the
+ single-indexed arrays returned by <function>db2_fetch_assoc</function> or
+ <function>db2_fetch_into</function>.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -25,82 +33,93 @@
<variablelist>
<varlistentry>
<term><parameter>stmt</parameter></term>
- <listitem>
- <para>
- Its description
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ A valid <literal>stmt</literal> resource containing a result set.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><parameter>row_number</parameter></term>
- <listitem>
- <para>
- Its description
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ Requests a specific 1-indexed row from the result set. Passing this
+ parameter results in a PHP warning if the result set uses a
+ forward-only cursor.
+ </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
+ Returns an associative array with column values indexed by both the column
+ name and 0-indexed column number. The array represents the next or
+ requested row in the result set. Returns &false; if there are no rows left
+ in the result set, or if the row requested by
+ <parameter>row_number</parameter> does not exist in the result set.
</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;
<para>
<example>
- <title>A <function>db2_fetch_both</function> example</title>
+ <title>Iterating through a forward-only cursor</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
+ If you call <function>db2_fetch_both</function> without a specific row
+ number, it automatically retrieves the next row in the result set. The
+ following example accesses columns in the returned array by both column
+ name and by numeric index.
</para>
<programlisting role="php">
<![CDATA[
<?php
-if ($anexample === true) {
- echo 'Use the PEAR Coding Standards';
+
+$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
+$stmt = db2_prepare($conn, $sql);
+$result = db2_execute($stmt, $sql);
+
+while ($row = db2_fetch_both($result)) {
+ printf ("%-5d %-16s %-32s %10s\n",
+ $row['ID'], $row[0], $row['BREED'], $row[3]);
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+0 Pook cat 3.20
+5 Rickety Ride goat 9.70
+2 Smarty horse 350.00
+]]>
+ </screen>
+ </example>
+
+ <example>
+ <title>Retrieving specific rows with <function>db2_fetch_both</function>
+ from a scrollable cursor</title>
+ <para>
+ If your result set uses a scrollable cursor, you can call
+ <function>db2_fetch_both</function> with a specific row number. The
+ following example retrieves every other row in the result set, starting
+ with the second row.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
+$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));
+
+$i=2;
+while ($row = db2_fetch_both($result, $i)) {
+ printf ("%-5d %-16s %-32s %10s\n",
+ $row[0], $row['NAME'], $row[2], $row['WEIGHT']);
+ $i = $i + 2;
}
?>
]]>
@@ -108,26 +127,27 @@
&example.outputs;
<screen>
<![CDATA[
-Use the PEAR Coding Standards
+0 Pook cat 3.20
+5 Rickety Ride goat 9.70
+2 Smarty horse 350.00
]]>
</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_fetch_assoc</function></member>
+ <member><function>db2_fetch_into</function></member>
+ <member><function>db2_fetch_row</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-fetch-into.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-fetch-into.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-fetch-into.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-fetch-into.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-fetch-into.xml:1.1 Tue Apr
12 17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-fetch-into.xml Sat Apr 16
22:50:00 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-fetch-into">
<refnamediv>
@@ -16,7 +16,12 @@
<methodparam
choice="opt"><type>int</type><parameter>row_number</parameter></methodparam>
</methodsynopsis>
- &warn.undocumented.func;
+ &warn.experimental.func;
+
+ <para>
+ Returns an array, indexed by column position, representing a row in a result
+ set. The columns are 0-indexed.
+ </para>
</refsect1>
<refsect1 role="parameters">
@@ -25,82 +30,55 @@
<variablelist>
<varlistentry>
<term><parameter>stmt</parameter></term>
- <listitem>
- <para>
- Its description
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ A valid <literal>stmt</literal> resource containing a result set.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><parameter>row_number</parameter></term>
- <listitem>
- <para>
- Its description
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ Requests a specific 1-indexed row from the result set. Passing this
+ parameter results in a PHP warning if the result set uses a
+ forward-only cursor.
+ </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 0-indexed array with column values indexed by the column position
+ representing the next or requested row in the result set. Returns &false; if
+ there are no rows left in the result set, or if the row requested by
+ <parameter>row_number</parameter> does not exist in the result set.
</para>
</refsect1>
- -->
-
- <!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
- <title>A <function>db2_fetch_into</function> example</title>
+ <title>Iterating through a forward-only cursor</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
+ If you call <function>db2_fetch_into</function> without a specific row
+ number, it automatically retrieves the next row in the result set.
</para>
<programlisting role="php">
<![CDATA[
<?php
-if ($anexample === true) {
- echo 'Use the PEAR Coding Standards';
+
+$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
+$stmt = db2_prepare($conn, $sql);
+$result = db2_execute($stmt, $sql);
+
+while ($row = db2_fetch_into($result)) {
+ printf ("%-5d %-16s %-32s %10s\n",
+ $row[0], $row[1], $row[2], $row[3]);
}
?>
]]>
@@ -108,27 +86,61 @@
&example.outputs;
<screen>
<![CDATA[
-Use the PEAR Coding Standards
+0 Pook cat 3.20
+5 Rickety Ride goat 9.70
+2 Smarty horse 350.00
+]]>
+ </screen>
+ </example>
+
+ <example>
+ <title>Retrieving specific rows with <function>db2_fetch_assoc</function>
+ from a scrollable cursor</title>
+ <para>
+ If your result set uses a scrollable cursor, you can call
+ <function>db2_fetch_assoc</function> with a specific row number. The
+ following example retrieves every other row in the result set, starting
+ with the second row.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$sql = "SELECT id, name, breed, weight FROM animals ORDER BY breed";
+$result = db2_exec($stmt, $sql, array('cursor' => DB2_SCROLLABLE));
+
+$i=2;
+while ($row = db2_fetch_into($result, $i)) {
+ printf ("%-5d %-16s %-32s %10s\n",
+ $row[0], $row[1], $row[2], $row[3]);
+ $i = $i + 2;
+}
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+0 Pook cat 3.20
+5 Rickety Ride goat 9.70
+2 Smarty horse 350.00
]]>
</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_fetch_assoc</function></member>
+ <member><function>db2_fetch_both</function></member>
+ <member><function>db2_fetch_row</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-num-rows.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/ibm_db2/functions/db2-num-rows.xml
diff -u phpdoc/en/reference/ibm_db2/functions/db2-num-rows.xml:1.1
phpdoc/en/reference/ibm_db2/functions/db2-num-rows.xml:1.2
--- phpdoc/en/reference/ibm_db2/functions/db2-num-rows.xml:1.1 Tue Apr 12
17:12:48 2005
+++ phpdoc/en/reference/ibm_db2/functions/db2-num-rows.xml Sat Apr 16
22:50:00 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-num-rows">
<refnamediv>
@@ -15,7 +15,38 @@
<methodparam><type>resource</type><parameter>stmt</parameter></methodparam>
</methodsynopsis>
- &warn.undocumented.func;
+ &warn.experimental.func;
+
+ <para>
+ Returns the number of rows deleted, inserted, or updated by an SQL
+ statement.
+ </para>
+ <para>
+ To determine the number of rows that will be returned by a SELECT
+ statement, issue SELECT COUNT(*) with the same predicates as your
+ intended SELECT statement and retrieve the value.
+ </para>
+ <para>
+ If your application logic checks the number of rows returned by a SELECT
+ statement and branches if the number of rows is 0, consider modifying your
+ application to attempt to return the first row with one of
+ <function>db2_fetch_assoc</function>, <function>db2_fetch_both</function>,
+ <function>db2_fetch_into</function>, or <function>db2_fetch_row</function>,
+ and branch if the fetch function returns &false;.
+ </para>
+
+ <note>
+ <para>
+ If you issue a SELECT statement using a scrollable cursor,
+ <function>db2_num_rows</function> returns the number of rows returned by
+ the SELECT statement. However, the overhead associated with scrollable
+ cursors significantly degrades the performance of your application, so if
+ this is the only reason you are considering using scrollable cursors,
+ you should use a forward-only cursor and either call SELECT COUNT(*) or
+ rely on the <type>boolean</type> return value of the fetch functions to
+ achieve the equivalent functionality with much better performance.
+ </para>
+ </note>
</refsect1>
<refsect1 role="parameters">
@@ -24,57 +55,22 @@
<variablelist>
<varlistentry>
<term><parameter>stmt</parameter></term>
- <listitem>
- <para>
- Its description
- </para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>
+ A valid <literal>stmt</literal> resource containing a result set.
+ </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 the number of rows affected by the last SQL statement issued by
+ the specified statement handle.
</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">
