pg_sendquery_prepared — Send a pre-prepared SQL command to the server for asynchronous execution
pg_sendquery_preparedconn
statementName
resultFormats
argFormats
?param...
?
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.
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.
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
.
The original Pgtcl implementation has a command with the same name but incompatible arguments.
This version of the manual was produced for the
Pgtcl-ng Sourceforge project web service site, which requires the logo on each
page.
To download a logo-free copy of the manual, see the
Pgtcl-ng project
downloads area.