PDOStatement::closeCursor
PDOStatement::closeCursor — Closes the cursor, enabling the statement to be executed again. (PHP 5 >= 5.1.0, PECL pdo >= 0.9.0)
Description
Syntax
bool PDOStatement::closeCursor ( void )
PDOStatement::closeCursor() releases the connection to the database server, allowing other SQL statements to be issued, but leaves the statement in a state that allows it to be executed again.
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 the database driver suffers from this limitation, issues with out-of-order errors may occur.
PDOStatement::closeCursor() is either implemented as a specific method for optional drivers (for highest efficiency) or as a generic PDO fallback when there is no driver-specific functionality. The generic fallback is semantically equivalent to the following PHP code:
<?php
do {
while ($stmt->fetch())
;
if (!$stmt->nextRowset())
break;
} while (true);
?>
Return Value
Returns TRUE on success or FALSE on failure.
Examples
Example of PDOStatement::closeCursor()
In the following example, the $stmt PDOStatement object returns multiple rows, but the application fetches only the first row, leaving the PDOStatement object in a state with unfetched rows. To ensure the application works correctly with all database drivers, $stmt calls PDOStatement::closeCursor() before executing the $otherStmt PDOStatement object.
<?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 result set */
$stmt->fetch();
/* The following call to closeCursor() may be required by some drivers */
$stmt->closeCursor();
/* Now the second statement can be executed */
$otherStmt->execute();
?>