Programming the Perl DBI

Name

finish

Synopsis

$rc  = $sth->finish;

Indicates that no more data will be fetched from this statement handle before it is either executed again or destroyed. The finish method is rarely needed, but can sometimes be helpful in very specific situations to allow the server to free up resources (such as sort buffers).

When all the data has been fetched from a SELECT statement, the driver should automatically call finish for you. So you should not normally need to call it explicitly.

Consider a query like:

SELECT foo FROM table WHERE bar=? ORDER BY foo

where you want to select just the first (smallest) “foo” value from a very large table. When executed, the database server will have to use temporary buffer space to store the sorted rows. If, after executing the handle and selecting one row, the handle won’t be re-executed for some time and won’t be destroyed, the finish method can be used to tell the server that the buffer space can be freed.

Calling finish resets the Active attribute for the statement. It may also make some statement handle attributes (such as NAME and TYPE) unavailable if they have not already been accessed (and thus cached).

The finish method does not affect the transaction status of the database connection. It has nothing to do with transactions. It’s mostly an internal “housekeeping” method that is rarely needed. There’s no need to call finish if you’re about to destroy or re-execute the statement handle. See also disconnect and the Active attribute.