dbs Sun Jul 10 23:28:34 2005 EDT
Modified files:
/phpdoc/en/reference/pdo/functions PDOStatement-closeCursor.xml
Log:
More guidance on when closeCursor() is useful.
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/functions/PDOStatement-closeCursor.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pdo/functions/PDOStatement-closeCursor.xml
diff -u phpdoc/en/reference/pdo/functions/PDOStatement-closeCursor.xml:1.1
phpdoc/en/reference/pdo/functions/PDOStatement-closeCursor.xml:1.2
--- phpdoc/en/reference/pdo/functions/PDOStatement-closeCursor.xml:1.1 Sat Jul
9 01:19:02 2005
+++ phpdoc/en/reference/pdo/functions/PDOStatement-closeCursor.xml Sun Jul
10 23:28:34 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.PDOStatement-closeCursor">
<refnamediv>
@@ -19,15 +19,19 @@
<para>
<function>PDOStatement::closeCursor</function> frees up the connection
- to the server so that other queries may be issued, but leaves the
+ to the server so that other SQL statements may be issued, but leaves the
statement in a state that enables it to be executed again.
</para>
<para>
- This is implemented either as an optional driver specific method (allowing
- for maximum efficiency), or as the generic PDO fallback if no driver
- specific function is installed.
+ This method is useful for database drivers that do not support executing
+ a PDOStatement object when a previously executed PDOStatement object still
+ has unfetched rows. If your database driver suffers from this limitation,
+ the problem may manifest itself in an out-of-sequence error.
</para>
<para>
+ <function>PDOStatement::closeCursor</function> is implemented either as an
+ optional driver specific method (allowing for maximum efficiency), or as
+ the generic PDO fallback if no driver specific function is installed.
The PDO generic fallback is semantically the same as writing the following
code in your PHP script:
<programlisting role="php">
@@ -39,6 +43,7 @@
if (!$stmt->nextRowset())
break;
} while (true);
+?>
]]>
</programlisting>
</para>
@@ -79,38 +84,46 @@
</refsect1>
-->
-
- <!-- Use when examples exist
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>A <function>PDOStatement::closeCursor</function> example</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, the <varname>$stmt</varname> PDOStatement
+ object returns multiple rows but the application fetches only the first
+ row, leaving the PDOStatement object in a state of having unfetched rows.
+ To ensure that the application will work with all database drivers, the
+ author inserts a call to <function>PDOStatement::closeCursor</function>
+ on <varname>$stmt</varname> before executing the
+ <varname>$otherStmt</varname> PDOStatement object.
</para>
<programlisting role="php">
<![CDATA[
<?php
-if ($anexample === true) {
- echo 'Use the PEAR Coding Standards';
-}
+// Create a PDOStatement object
+$stmt = $dbh->prepare('SELECT foo FROM bar');
+
+// Create a second PDOStatement object
+$stmt = $dbh->prepare('SELECT foobaz FROM foobar');
+
+// Execute the first statement
+$stmt->execute();
+
+// Fetch only the first row from the results
+$stmt->fetch();
+
+// The following call to closeCursor() may be required by some drivers
+$stmt->closeCursor();
+
+// Now we can execute the second statement
+$otherStmt->execute();
?>
]]>
</programlisting>
- &example.outputs;
- <screen>
-<![CDATA[
-Use the PEAR Coding Standards
-]]>
- </screen>
</example>
</para>
</refsect1>
- -->
-
<refsect1 role="seealso">
&reftitle.seealso;
