cvs: phpdoc /en/reference/pdo/functions PDOStatement-closeCursor.xml

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;