php-doc-en/reference/pdo/functions/PDOStatement-closeCursor.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDOStatement-closeCursor">
 <refnamediv>
  <refname>PDOStatement::closeCursor</refname>
  <refpurpose>
   Closes the cursor, enabling the statement to be executed again.
  </refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>PDOStatement::closeCursor</methodname>
   <void/>
  </methodsynopsis>

  <para>
   <function>PDOStatement::closeCursor</function> frees up the connection
   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 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">
<![CDATA[
<?php
do {
    while ($stmt->fetch())
        ;
    if (!$stmt->nextRowset())
        break;
} while (true);
?>
]]>
   </programlisting>
  </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>
 -->

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>A <function>PDOStatement::closeCursor</function> example</title>
    <para>
     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
/* Create a PDOStatement object */
$stmt = $dbh->prepare('SELECT foo FROM bar');

/* Create a second PDOStatement object */
$otherStmt = $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>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>PDOStatement::execute</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->