<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Closes the cursor, enabling the statement to be executed again.</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="pdostatement.bindvalue.html">PDOStatement::bindValue</a></div>
<div class="next" style="text-align: right; float: right;"><a href="pdostatement.columncount.html">PDOStatement::columnCount</a></div>
<div class="up"><a href="class.pdostatement.html">PDOStatement</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="pdostatement.closecursor" class="refentry">
<div class="refnamediv">
<h1 class="refname">PDOStatement::closeCursor</h1>
<p class="verinfo">(PHP 5 >= 5.1.0, PECL pdo >= 0.9.0)</p><p class="refpurpose"><span class="refname">PDOStatement::closeCursor</span> — <span class="dc-title">
Closes the cursor, enabling the statement to be executed again.
</span></p>
</div>
<div class="refsect1 description" id="refsect1-pdostatement.closecursor-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><strong>PDOStatement::closeCursor</strong></span>
( <span class="methodparam">void</span>
)</div>
<p class="para rdfs-comment">
<span class="function"><strong>PDOStatement::closeCursor()</strong></span> 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.
</p>
<p class="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.
</p>
<p class="para">
<span class="function"><strong>PDOStatement::closeCursor()</strong></span> 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:
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">do {<br /> while (</span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">())<br /> ;<br /> if (!</span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">nextRowset</span><span style="color: #007700">())<br /> break;<br />} while (</span><span style="color: #0000BB">true</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-pdostatement.closecursor-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 examples" id="refsect1-pdostatement.closecursor-examples">
<h3 class="title">Examples</h3>
<p class="para">
<div class="example" id="example-939">
<p><strong>Example #1 A <span class="function"><strong>PDOStatement::closeCursor()</strong></span> example</strong></p>
<div class="example-contents"><p>
In the following example, the <var class="varname"><var class="varname">$stmt</var></var> 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 <span class="function"><strong>PDOStatement::closeCursor()</strong></span>
on <var class="varname"><var class="varname">$stmt</var></var> before executing the
<var class="varname"><var class="varname">$otherStmt</var></var> PDOStatement object.
</p></div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Create a PDOStatement object */<br /></span><span style="color: #0000BB">$stmt </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">'SELECT foo FROM bar'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Create a second PDOStatement object */<br /></span><span style="color: #0000BB">$otherStmt </span><span style="color: #007700">= </span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">prepare</span><span style="color: #007700">(</span><span style="color: #DD0000">'SELECT foobaz FROM foobar'</span><span style="color: #007700">);<br /><br /></span><span style="color: #FF8000">/* Execute the first statement */<br /></span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">/* Fetch only the first row from the results */<br /></span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">/* The following call to closeCursor() may be required by some drivers */<br /></span><span style="color: #0000BB">$stmt</span><span style="color: #007700">-></span><span style="color: #0000BB">closeCursor</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">/* Now we can execute the second statement */<br /></span><span style="color: #0000BB">$otherStmt</span><span style="color: #007700">-></span><span style="color: #0000BB">execute</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div>
<div class="refsect1 seealso" id="refsect1-pdostatement.closecursor-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="pdostatement.execute.html" class="function" rel="rdfs-seeAlso">PDOStatement::execute()</a> - Executes a prepared statement</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="pdostatement.bindvalue.html">PDOStatement::bindValue</a></div>
<div class="next" style="text-align: right; float: right;"><a href="pdostatement.columncount.html">PDOStatement::columnCount</a></div>
<div class="up"><a href="class.pdostatement.html">PDOStatement</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
