PDOStatement::closeCursor

PHP PDO Reference Manual

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 so that other SQL statements can be issued, while leaving the statement in a state that allows it to be executed again.

When the previously executed PDOStatement object still has un-fetched rows, this method is useful for database drivers that do not support re-executing a PDOStatement object. If the database driver has this limitation, the problem of out-of-order errors may occur.

PDOStatement::closeCursor() is implemented either as a driver-specific method (most efficient), or as the generic PDO fallback if no driver-specific functionality is available. The generic fallback is semantically equivalent to the following PHP code:

<?php
do {
    while ($stmt->fetch())
        ;
    if (!$stmt->nextRowset())
        break;
} while (true);
?>

Return Values

Returns TRUE on success, or FALSE on failure.

Examples

An example of PDOStatement::closeCursor()

In the following example, the $stmt PDOStatement object returns multiple rows, but the application only fetches the first row, leaving the PDOStatement object in a state with un-fetched rows. To ensure the application works correctly with all database drivers, before executing the $otherStmt PDOStatement object, $stmt calls PDOStatement::closeCursor() once.

<?php
/* 创建一个 PDOStatement 对象 */
$stmt = $dbh->prepare('SELECT foo FROM bar');

/* 创建第二个 PDOStatement 对象 */
$otherStmt = $dbh->prepare('SELECT foobaz FROM foobar');

/* 执行第一条语句 */
$stmt->execute();

/*  从结果集中只取出第一行 */
$stmt->fetch();

/* The following call to closeCursor() may be required by some drivers */
$stmt->closeCursor();

/*  现在可以执行第二条语句了 */
$otherStmt->execute();
?>

PHP PDO Reference Manual