pg_sendquery_prepared

pg_sendquery_prepared
Prev	4.4. Asynchronous Query Processing Commands	Next

pg_sendquery_prepared — Send a pre-prepared SQL command to the server for asynchronous execution

Synopsis

pg_sendquery_prepared conn statementName resultFormats argFormats ?param...?

Description

pg_sendquery_prepared initiates execution of a pre-prepared SQL named statement on the server and returns immediately, without waiting for the command to complete. This command allows binding arguments to SQL statement parameters without quoting issues, and supports sending and receiving raw binary data. The syntax of pg_sendquery_prepared is the same as pg_exec_prepared which is for synchronous query execution.

Arguments

conn: The handle of the connection on which to execute the command.
statementName: The name of the pre-prepared statement.
resultFormats: The format that the query results are expected in. Use T or TEXT for text format results, and B or BINARY for binary format results. If this parameter is an empty string, TEXT is assumed.
argFormats: The formats that the query parameters are sent in. This parameter can be an empty string, a single word, or a list. If this parameter is an empty string, all query parameters are sent in text format. If this parameter is a single word, it specifies the format for all query parameters. Use T (or TEXT) for text format, and B (or BINARY) for binary format. If this parameter is a list, it must contain a single word (T or TEXT or B or BINARY) specifying the format for each query parameter.
param...: Zero or more parameter values to bind to command string place-holders. The first parameter will replace $1 in the prepared query, the second parameter will replace $2, etc. The parameters will be interpreted as text or binary data according to the argFormats argument.

Return Value

None.

A Tcl error will be thrown if an error occurs.

Notes

The statement must be prepared with an SQL PREPARE command, for example:

    PREPARE statementName (INTEGER) AS SELECT * FROM mytable WHERE ID > $1

This can be sent to the database with pg_exec or pg_execute (but note that $1 must be escaped for Tcl as \$1). Prepared statements persist until the end of a session.

Use pg_isbusy to see if the command is still being executed. Use pg_getresult to get the result, waiting for the command to complete if necessary. Alternatively, use pg_result_callback to register a callback command to be executed when a result is ready (that is, when pg_getresult will not block).

The command syntax of pg_sendquery_prepared supports mixed text and binary result columns, but the underlying PostgreSQL library (libpq) does not currently support this. Therefore, all result columns must be text format, or all columns must be binary format.

There is no support for passing NULL value arguments to prepared statements.

This command uses or emulates the PostgreSQL libpq function PQsendQueryPrepared.

Caution

The original Pgtcl implementation has a command with the same name but incompatible arguments.