Description

pg_describe_cursor gets information about an open cursor (or portal, the term used by the PostgreSQL documentation). A cursor is created with the SQL DECLARE command. A result structure is returned, for use with pg_result to get information about the cursor.

Arguments

Return Value

Returns a result handle which can be used with pg_result to obtain information about the cursor.

Notes

On success, a result structure which has status PGRES_COMMAND_OK will be returned. The result structure will have no data rows, only attribute (column) information. If no such cursor exists, the result structure will have status PGRES_FATAL_ERROR. A Tcl error may be thrown under other error conditions.

Use pg_result to get information from the returned result structure, and be sure to free the returned result handle with pg_result -clear when you are done with it.

This command uses or emulates the PostgreSQL libpq function PQdescribePortal.

This command was added in pgtclng-1.7.0 and in pgintcl-3.1.0.

Example

Declare a cursor and get the names of its columns:

pg_execute $conn "DECLARE mycursor CURSOR FOR SELECT * FROM mytable"
set result [pg_describe_cursor $conn mycursor]
if {[pg_result $result -status] eq "PGRES_COMMAND_OK"} {
  puts "Cursor columns are: [pg_result $result -attributes]"
}