<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>pg_exec_params</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="Pgtcl Reference Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Query Execution Commands"
HREF="pgtcl-ref-query.html"><LINK
REL="PREVIOUS"
TITLE="pg_select"
HREF="pg-select.html"><LINK
REL="NEXT"
TITLE="pg_exec_prepared"
HREF="pg-exec-prepared.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
NAME="creation"
CONTENT="2004-11-09T00:53:06"></HEAD
><BODY
CLASS="REFENTRY"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Pgtcl Reference Manual: The PostgreSQL Tcl Interface</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="pg-select.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="pg-exec-prepared.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="PG-EXEC-PARAMS"
></A
>pg_exec_params</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN1131"
></A
><H2
>Name</H2
>pg_exec_params -- Parse and execute a parameterized SQL statement</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN1134"
></A
><H2
>Synopsis</H2
><PRE
CLASS="SYNOPSIS"
>pg_exec_params <VAR
CLASS="PARAMETER"
>conn</VAR
> <VAR
CLASS="PARAMETER"
>commandString</VAR
> <VAR
CLASS="PARAMETER"
>resultFormats</VAR
> <VAR
CLASS="PARAMETER"
>argFormats</VAR
> <VAR
CLASS="PARAMETER"
>argTypes</VAR
> <VAR
CLASS="PARAMETER"
>arg...</VAR
></PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1142"
></A
><H2
>Description</H2
><P
><CODE
CLASS="FUNCTION"
>pg_exec_params</CODE
> sends an SQL command to the server with
parameters to be bound to place-holders in the command, and returns a result
handle. This is similar to <A
HREF="pg-exec-prepared.html"
>pg_exec_prepared</A
>, but doesn't
use a pre-prepared statement, and if you want to use binary parameters you
must also provide the type OIDs. By separating parameters from the SQL
command string, this command allows binding arguments to SQL statement
parameters without quoting issues, and supports sending and receiving raw
binary data.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1147"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="REPLACEABLE"
>conn</VAR
></DT
><DD
><P
> The handle of the connection on which to execute the prepared command.
</P
></DD
><DT
><VAR
CLASS="REPLACEABLE"
>commandString</VAR
></DT
><DD
><P
> The SQL command to parse, bind arguments to, and execute.
Argument placeholders are indicated as <TT
CLASS="LITERAL"
>$1</TT
>,
<TT
CLASS="LITERAL"
>$2</TT
>, etc.
</P
></DD
><DT
><VAR
CLASS="REPLACEABLE"
>resultFormats</VAR
></DT
><DD
><P
>The format that the query results are expected in. Use <TT
CLASS="LITERAL"
>T</TT
>
or <TT
CLASS="LITERAL"
>TEXT</TT
> for text (ASCII) format results,
and <TT
CLASS="LITERAL"
>B</TT
> or <TT
CLASS="LITERAL"
>BINARY</TT
> for binary format
results. If this parameter is an empty string, <TT
CLASS="LITERAL"
>TEXT</TT
> is
assumed.
</P
></DD
><DT
><VAR
CLASS="REPLACEABLE"
>argFormats</VAR
></DT
><DD
><P
>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 (ASCII) format. If this
parameter is a single word, it specifies the format for all query
parameters. Use <TT
CLASS="LITERAL"
>T</TT
> (or <TT
CLASS="LITERAL"
>TEXT</TT
>) for text
format, and <TT
CLASS="LITERAL"
>B</TT
> (or <TT
CLASS="LITERAL"
>BINARY</TT
>) for binary
format. If this parameter is a list, it must contain a single word
(<TT
CLASS="LITERAL"
>T</TT
> or <TT
CLASS="LITERAL"
>TEXT</TT
> or <TT
CLASS="LITERAL"
>B</TT
> or
<TT
CLASS="LITERAL"
>BINARY</TT
>) specifying the format for each query parameter.
</P
></DD
><DT
><VAR
CLASS="REPLACEABLE"
>argTypes</VAR
></DT
><DD
><P
>A list of PostgreSQL Type OIDs for the query parameter arguments.
This list must either be empty, or contain one entry for each query
parameter. If the list is empty, all arguments are treated as untyped
literal strings, and all argument formats must be text. If the list is
non-empty, each zero entry results in the corresponding text format
argument being treated as an untyped literal string. Each non-zero entry
is the type OID for the corresponding binary format argument. To get
type OIDs, query the <TT
CLASS="LITERAL"
>pg_type</TT
> table.
</P
></DD
><DT
><VAR
CLASS="REPLACEABLE"
>arg...</VAR
></DT
><DD
><P
>Zero or more arguments to bind to query parameters.
The first argument will replace <TT
CLASS="LITERAL"
>$1</TT
> in the
prepared query, the second argument will replace <TT
CLASS="LITERAL"
>$2</TT
>,
etc. The arguments will be interpreted as text or binary data
according to the <VAR
CLASS="REPLACEABLE"
>argFormats</VAR
> argument.
</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1199"
></A
><H2
>Return Value</H2
><P
> Returns a result handle which can be used with
<A
HREF="pg-result.html"
>pg_result</A
> to obtain the results of the command.
</P
><P
> A Tcl error will be thrown if an error occurs communicating with
the database. Note that no Tcl error will be thrown if an invalid
query is successfully sent to the server and a response successfully
received. The result status must be checked after a normal return.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1204"
></A
><H2
>Notes</H2
><P
>Be sure to brace-quote or escape the parameter placeholders such as
<TT
CLASS="LITERAL"
>$1</TT
> in the SQL command string
to protect them from Tcl variable expansion.
</P
><P
>The command syntax of <CODE
CLASS="FUNCTION"
>pg_exec_params</CODE
> supports mixed
text and binary result columns, but the underlying
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> library
(<SPAN
CLASS="APPLICATION"
>libpq</SPAN
>) does not currently support this.
Therefore, all result columns must be text format, or all columns must be
binary format.
</P
><P
> There is no support for passing NULL value arguments to prepared statements.
</P
><P
> Be sure to free the result handle with
<CODE
CLASS="FUNCTION"
>pg_result -clear</CODE
> when you are done with it.
</P
><P
> This command was added in
<SPAN
CLASS="APPLICATION"
>pgtclng-1.5.1</SPAN
> and in
<SPAN
CLASS="APPLICATION"
>pgintcl-2.1.0</SPAN
>.
</P
><P
> This command uses or emulates the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>
<SPAN
CLASS="APPLICATION"
>libpq</SPAN
>
function <CODE
CLASS="FUNCTION"
>PQexecParams</CODE
>.
</P
><DIV
CLASS="CAUTION"
><P
></P
><TABLE
CLASS="CAUTION"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Caution</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>This is a new command, and should be considered experimental.
The command may change and backwards compatibility is not assured.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="pg-select.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="pg-exec-prepared.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>pg_select</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="pgtcl-ref-query.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>pg_exec_prepared</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
