<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Command Execution Functions</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 8.2.14 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="libpq - C Library"
HREF="libpq.html"><LINK
REL="PREVIOUS"
TITLE="Connection Status Functions"
HREF="libpq-status.html"><LINK
REL="NEXT"
TITLE="Asynchronous Command Processing"
HREF="libpq-async.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2009-09-04T05:25:47"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
>PostgreSQL 8.2.14 Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq-status.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq.html"
>Fast Backward</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 29. <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> - C Library</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpq.html"
>Fast Forward</A
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpq-async.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="LIBPQ-EXEC"
>29.3. Command Execution Functions</A
></H1
><P
>Once a connection to a database server has been successfully
established, the functions described here are used to perform
SQL queries and commands.</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LIBPQ-EXEC-MAIN"
>29.3.1. Main Functions</A
></H2
><P
><P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="FUNCTION"
>PQexec</CODE
><A
NAME="AEN27091"
></A
></DT
><DD
><P
> Submits a command to the server
and waits for the result.
</P><PRE
CLASS="SYNOPSIS"
>PGresult *PQexec(PGconn *conn, const char *command);</PRE
><P></P
><P
> Returns a <TT
CLASS="STRUCTNAME"
>PGresult</TT
> pointer or possibly a null pointer.
A non-null pointer will generally be returned except in
out-of-memory conditions or serious errors such as inability
to send the command to the server.
If a null pointer is returned, it
should be treated like a <TT
CLASS="SYMBOL"
>PGRES_FATAL_ERROR</TT
> result.
Use <CODE
CLASS="FUNCTION"
>PQerrorMessage</CODE
> to get more information
about such errors.</P
></DD
></DL
></DIV
><P>
It is allowed to include multiple SQL commands (separated by semicolons) in
the command string. Multiple queries sent in a single <CODE
CLASS="FUNCTION"
>PQexec</CODE
>
call are processed in a single transaction, unless there are explicit
<TT
CLASS="COMMAND"
>BEGIN</TT
>/<TT
CLASS="COMMAND"
>COMMIT</TT
> commands included in the query string to divide it into multiple
transactions. Note however that the returned <TT
CLASS="STRUCTNAME"
>PGresult</TT
>
structure describes only the result of the last command executed from the
string. Should one of the commands fail, processing of the string stops with
it and the returned <TT
CLASS="STRUCTNAME"
>PGresult</TT
> describes the error
condition.</P
><P
><P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="FUNCTION"
>PQexecParams</CODE
><A
NAME="AEN27110"
></A
></DT
><DD
><P
> Submits a command to the server and waits for the result,
with the ability to pass parameters separately from the SQL
command text.
</P><PRE
CLASS="SYNOPSIS"
>PGresult *PQexecParams(PGconn *conn,
const char *command,
int nParams,
const Oid *paramTypes,
const char * const *paramValues,
const int *paramLengths,
const int *paramFormats,
int resultFormat);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQexecParams</CODE
> is like <CODE
CLASS="FUNCTION"
>PQexec</CODE
>, but offers additional
functionality: parameter values can be specified separately from the command
string proper, and query results can be requested in either text or binary
format. <CODE
CLASS="FUNCTION"
>PQexecParams</CODE
> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.</P
><P
>The function arguments are:
<P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="PARAMETER"
>conn</TT
></DT
><DD
><P
> The connection object to send the command through.
</P
></DD
><DT
><TT
CLASS="PARAMETER"
>command</TT
></DT
><DD
><P
> The SQL command string to be executed. If parameters are used, they are
referred to in the command string as <TT
CLASS="LITERAL"
>$1</TT
>, <TT
CLASS="LITERAL"
>$2</TT
>,
etc.
</P
></DD
><DT
><TT
CLASS="PARAMETER"
>nParams</TT
></DT
><DD
><P
> The number of parameters supplied; it is the length of the arrays
<TT
CLASS="PARAMETER"
>paramTypes[]</TT
>, <TT
CLASS="PARAMETER"
>paramValues[]</TT
>,
<TT
CLASS="PARAMETER"
>paramLengths[]</TT
>, and <TT
CLASS="PARAMETER"
>paramFormats[]</TT
>. (The
array pointers may be <TT
CLASS="SYMBOL"
>NULL</TT
> when <TT
CLASS="PARAMETER"
>nParams</TT
>
is zero.)
</P
></DD
><DT
><TT
CLASS="PARAMETER"
>paramTypes[]</TT
></DT
><DD
><P
> Specifies, by OID, the data types to be assigned to the parameter
symbols. If <TT
CLASS="PARAMETER"
>paramTypes</TT
> is <TT
CLASS="SYMBOL"
>NULL</TT
>, or any
particular element in the array is zero, the server infers a data type
for the parameter symbol in the same way it would do for an untyped
literal string.
</P
></DD
><DT
><TT
CLASS="PARAMETER"
>paramValues[]</TT
></DT
><DD
><P
> Specifies the actual values of the parameters.
A null pointer in this array means the corresponding parameter is null;
otherwise the pointer points to a zero-terminated text string (for text
format) or binary data in the format expected by the server (for binary
format).
</P
></DD
><DT
><TT
CLASS="PARAMETER"
>paramLengths[]</TT
></DT
><DD
><P
> Specifies the actual data lengths of binary-format parameters.
It is ignored for null parameters and text-format parameters.
The array pointer may be null when there are no binary parameters.
</P
></DD
><DT
><TT
CLASS="PARAMETER"
>paramFormats[]</TT
></DT
><DD
><P
> Specifies whether parameters are text (put a zero in the array entry for
the corresponding parameter) or binary (put a one in the array entry for
the corresponding parameter). If the array pointer is null then all
parameters are presumed to be text strings.
</P
></DD
><DT
><TT
CLASS="PARAMETER"
>resultFormat</TT
></DT
><DD
><P
> Specify zero to obtain results in text format, or one to obtain results
in binary format. (There is not currently a provision to obtain
different result columns in different formats, although that is
possible in the underlying protocol.)
</P
></DD
></DL
></DIV
><P></P
></DD
></DL
></DIV
><P></P
><P
>The primary advantage of <CODE
CLASS="FUNCTION"
>PQexecParams</CODE
> over <CODE
CLASS="FUNCTION"
>PQexec</CODE
>
is that parameter values may be separated from the command string, thus
avoiding the need for tedious and error-prone quoting and escaping.</P
><P
>Unlike <CODE
CLASS="FUNCTION"
>PQexec</CODE
>, <CODE
CLASS="FUNCTION"
>PQexecParams</CODE
> allows at most one SQL
command in the given string. (There can be semicolons in it, but not more
than one nonempty command.) This is a limitation of the underlying protocol,
but has some usefulness as an extra defense against SQL-injection attacks.</P
><DIV
CLASS="TIP"
><BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
>Specifying parameter types via OIDs is tedious, particularly if you prefer
not to hard-wire particular OID values into your program. However, you can
avoid doing so even in cases where the server by itself cannot determine the
type of the parameter, or chooses a different type than you want. In the
SQL command text, attach an explicit cast to the parameter symbol to show what
data type you will send. For example,
</P><PRE
CLASS="PROGRAMLISTING"
>select * from mytable where x = $1::bigint;</PRE
><P>
This forces parameter <TT
CLASS="LITERAL"
>$1</TT
> to be treated as <TT
CLASS="TYPE"
>bigint</TT
>, whereas
by default it would be assigned the same type as <TT
CLASS="LITERAL"
>x</TT
>. Forcing the
parameter type decision, either this way or by specifying a numeric type OID,
is strongly recommended when sending parameter values in binary format, because
binary format has less redundancy than text format and so there is less chance
that the server will detect a type mismatch mistake for you.</P
></BLOCKQUOTE
></DIV
><P
><P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="FUNCTION"
>PQprepare</CODE
><A
NAME="AEN27188"
></A
></DT
><DD
><P
> Submits a request to create a prepared statement with the
given parameters, and waits for completion.
</P><PRE
CLASS="SYNOPSIS"
>PGresult *PQprepare(PGconn *conn,
const char *stmtName,
const char *query,
int nParams,
const Oid *paramTypes);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQprepare</CODE
> creates a prepared statement for later execution with
<CODE
CLASS="FUNCTION"
>PQexecPrepared</CODE
>.
This feature allows commands
that will be used repeatedly to be parsed and planned just once, rather
than each time they are executed.
<CODE
CLASS="FUNCTION"
>PQprepare</CODE
> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.</P
><P
>The function creates a prepared statement named <TT
CLASS="PARAMETER"
>stmtName</TT
>
from the <TT
CLASS="PARAMETER"
>query</TT
> string, which must contain a single SQL command.
<TT
CLASS="PARAMETER"
>stmtName</TT
> may be <TT
CLASS="LITERAL"
>""</TT
> to create an unnamed statement,
in which case any pre-existing unnamed statement is automatically replaced;
otherwise it is an error if the statement name is already defined in the
current session.
If any parameters are used, they are referred
to in the query as <TT
CLASS="LITERAL"
>$1</TT
>, <TT
CLASS="LITERAL"
>$2</TT
>, etc.
<TT
CLASS="PARAMETER"
>nParams</TT
> is the number of parameters for which types are
pre-specified in the array <TT
CLASS="PARAMETER"
>paramTypes[]</TT
>. (The array pointer
may be <TT
CLASS="SYMBOL"
>NULL</TT
> when <TT
CLASS="PARAMETER"
>nParams</TT
> is zero.)
<TT
CLASS="PARAMETER"
>paramTypes[]</TT
> specifies, by OID, the data types to be assigned to
the parameter symbols. If <TT
CLASS="PARAMETER"
>paramTypes</TT
> is <TT
CLASS="SYMBOL"
>NULL</TT
>,
or any particular element in the array is zero, the server assigns a data type
to the parameter symbol in the same way it would do for an untyped literal
string. Also, the query may use parameter symbols with numbers higher than
<TT
CLASS="PARAMETER"
>nParams</TT
>; data types will be inferred for these symbols as
well. (See <CODE
CLASS="FUNCTION"
>PQdescribePrepared</CODE
> for a means to find out
what data types were inferred.)</P
><P
>As with <CODE
CLASS="FUNCTION"
>PQexec</CODE
>, the result is normally a
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> object whose contents indicate server-side
success or failure. A null result indicates out-of-memory or inability to
send the command at all.
Use <CODE
CLASS="FUNCTION"
>PQerrorMessage</CODE
> to get more information
about such errors.</P
></DD
></DL
></DIV
><P>
Prepared statements for use with <CODE
CLASS="FUNCTION"
>PQexecPrepared</CODE
> can also
be created by executing SQL <A
HREF="sql-prepare.html"
><I
>PREPARE</I
></A
> statements. (But <CODE
CLASS="FUNCTION"
>PQprepare</CODE
>
is more flexible since it does not require parameter types to be
pre-specified.) Also, although there is no <SPAN
CLASS="APPLICATION"
>libpq</SPAN
>
function for deleting a prepared statement, the SQL <A
HREF="sql-deallocate.html"
><I
>DEALLOCATE</I
></A
> statement can
be used for that purpose.</P
><P
><P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="FUNCTION"
>PQexecPrepared</CODE
><A
NAME="AEN27227"
></A
></DT
><DD
><P
> Sends a request to execute a prepared statement with given
parameters, and waits for the result.
</P><PRE
CLASS="SYNOPSIS"
>PGresult *PQexecPrepared(PGconn *conn,
const char *stmtName,
int nParams,
const char * const *paramValues,
const int *paramLengths,
const int *paramFormats,
int resultFormat);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQexecPrepared</CODE
> is like <CODE
CLASS="FUNCTION"
>PQexecParams</CODE
>, but the
command to be executed is specified by naming a previously-prepared
statement, instead of giving a query string.
This feature allows commands
that will be used repeatedly to be parsed and planned just once, rather
than each time they are executed.
The statement must have been prepared previously in the current session.
<CODE
CLASS="FUNCTION"
>PQexecPrepared</CODE
> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.</P
><P
>The parameters are identical to <CODE
CLASS="FUNCTION"
>PQexecParams</CODE
>, except that the
name of a prepared statement is given instead of a query string, and the
<TT
CLASS="PARAMETER"
>paramTypes[]</TT
> parameter is not present (it is not needed since
the prepared statement's parameter types were determined when it was created).</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQdescribePrepared</CODE
><A
NAME="AEN27242"
></A
></DT
><DD
><P
> Submits a request to obtain information about the specified
prepared statement, and waits for completion.
</P><PRE
CLASS="SYNOPSIS"
>PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQdescribePrepared</CODE
> allows an application to obtain information
about a previously prepared statement.
<CODE
CLASS="FUNCTION"
>PQdescribePrepared</CODE
> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.</P
><P
><TT
CLASS="PARAMETER"
>stmtName</TT
> may be <TT
CLASS="LITERAL"
>""</TT
> or NULL to reference the unnamed
statement, otherwise it must be the name of an existing prepared statement.
On success, a <TT
CLASS="STRUCTNAME"
>PGresult</TT
> with status
<TT
CLASS="LITERAL"
>PGRES_COMMAND_OK</TT
> is returned. The functions
<CODE
CLASS="FUNCTION"
>PQnparams</CODE
> and <CODE
CLASS="FUNCTION"
>PQparamtype</CODE
>
may be applied to this <TT
CLASS="STRUCTNAME"
>PGresult</TT
> to obtain information
about the parameters of the prepared statement, and the functions
<CODE
CLASS="FUNCTION"
>PQnfields</CODE
>, <CODE
CLASS="FUNCTION"
>PQfname</CODE
>,
<CODE
CLASS="FUNCTION"
>PQftype</CODE
>, etc provide information about the result
columns (if any) of the statement.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQdescribePortal</CODE
><A
NAME="AEN27264"
></A
></DT
><DD
><P
> Submits a request to obtain information about the specified
portal, and waits for completion.
</P><PRE
CLASS="SYNOPSIS"
>PGresult *PQdescribePortal(PGconn *conn, const char *portalName);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQdescribePortal</CODE
> allows an application to obtain information
about a previously created portal. (<SPAN
CLASS="APPLICATION"
>libpq</SPAN
> does not provide
any direct access to portals, but you can use this function to inspect the
properties of a cursor created with a <TT
CLASS="COMMAND"
>DECLARE CURSOR</TT
> SQL command.)
<CODE
CLASS="FUNCTION"
>PQdescribePortal</CODE
> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.</P
><P
><TT
CLASS="PARAMETER"
>portalName</TT
> may be <TT
CLASS="LITERAL"
>""</TT
> or NULL to reference the unnamed
portal, otherwise it must be the name of an existing portal.
On success, a <TT
CLASS="STRUCTNAME"
>PGresult</TT
> with status
<TT
CLASS="LITERAL"
>PGRES_COMMAND_OK</TT
> is returned. The functions
<CODE
CLASS="FUNCTION"
>PQnfields</CODE
>, <CODE
CLASS="FUNCTION"
>PQfname</CODE
>,
<CODE
CLASS="FUNCTION"
>PQftype</CODE
>, etc may be applied to the
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> to obtain information about the result
columns (if any) of the portal.</P
></DD
></DL
></DIV
><P></P
><P
>The
<TT
CLASS="STRUCTNAME"
>PGresult</TT
><A
NAME="AEN27285"
></A
>
structure encapsulates the result returned by the server.
<SPAN
CLASS="APPLICATION"
>libpq</SPAN
> application programmers should be
careful to maintain the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> abstraction.
Use the accessor functions below to get at the contents of
<TT
CLASS="STRUCTNAME"
>PGresult</TT
>. Avoid directly referencing the
fields of the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> structure because they
are subject to change in the future.
<P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="FUNCTION"
>PQresultStatus</CODE
><A
NAME="AEN27295"
></A
></DT
><DD
><P
> Returns the result status of the command.
</P><PRE
CLASS="SYNOPSIS"
>ExecStatusType PQresultStatus(const PGresult *res);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQresultStatus</CODE
> can return one of the following values:
<P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>PGRES_EMPTY_QUERY</TT
></DT
><DD
><P
>The string sent to the server was empty.</P
></DD
><DT
><TT
CLASS="LITERAL"
>PGRES_COMMAND_OK</TT
></DT
><DD
><P
>Successful completion of a command returning no data.</P
></DD
><DT
><TT
CLASS="LITERAL"
>PGRES_TUPLES_OK</TT
></DT
><DD
><P
>Successful completion of a command returning data (such as
a <TT
CLASS="COMMAND"
>SELECT</TT
> or <TT
CLASS="COMMAND"
>SHOW</TT
>).</P
></DD
><DT
><TT
CLASS="LITERAL"
>PGRES_COPY_OUT</TT
></DT
><DD
><P
>Copy Out (from server) data transfer started.</P
></DD
><DT
><TT
CLASS="LITERAL"
>PGRES_COPY_IN</TT
></DT
><DD
><P
>Copy In (to server) data transfer started.</P
></DD
><DT
><TT
CLASS="LITERAL"
>PGRES_BAD_RESPONSE</TT
></DT
><DD
><P
>The server's response was not understood.</P
></DD
><DT
><TT
CLASS="LITERAL"
>PGRES_NONFATAL_ERROR</TT
></DT
><DD
><P
>A nonfatal error (a notice or warning) occurred.</P
></DD
><DT
><TT
CLASS="LITERAL"
>PGRES_FATAL_ERROR</TT
></DT
><DD
><P
>A fatal error occurred.</P
></DD
></DL
></DIV
><P>
If the result status is <TT
CLASS="LITERAL"
>PGRES_TUPLES_OK</TT
>, then the
functions described below can be used to retrieve the rows returned by
the query. Note that a <TT
CLASS="COMMAND"
>SELECT</TT
> command that happens
to retrieve zero rows still shows <TT
CLASS="LITERAL"
>PGRES_TUPLES_OK</TT
>.
<TT
CLASS="LITERAL"
>PGRES_COMMAND_OK</TT
> is for commands that can never
return rows (<TT
CLASS="COMMAND"
>INSERT</TT
>, <TT
CLASS="COMMAND"
>UPDATE</TT
>,
etc.). A response of <TT
CLASS="LITERAL"
>PGRES_EMPTY_QUERY</TT
> may indicate
a bug in the client software.</P
><P
>A result of status <TT
CLASS="SYMBOL"
>PGRES_NONFATAL_ERROR</TT
> will never be
returned directly by <CODE
CLASS="FUNCTION"
>PQexec</CODE
> or other query
execution functions; results of this kind are instead passed to the notice
processor (see <A
HREF="libpq-notice-processing.html"
>Section 29.11</A
>).</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQresStatus</CODE
><A
NAME="AEN27359"
></A
></DT
><DD
><P
> Converts the enumerated type returned by <CODE
CLASS="FUNCTION"
>PQresultStatus</CODE
> into
a string constant describing the status code. The caller should not
free the result.
</P><PRE
CLASS="SYNOPSIS"
>char *PQresStatus(ExecStatusType status);</PRE
><P></P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQresultErrorMessage</CODE
><A
NAME="AEN27368"
></A
></DT
><DD
><P
>Returns the error message associated with the command, or an empty string
if there was no error.
</P><PRE
CLASS="SYNOPSIS"
>char *PQresultErrorMessage(const PGresult *res);</PRE
><P>
If there was an error, the returned string will include a trailing newline.
The caller should not free the result directly. It will be freed when the
associated <TT
CLASS="STRUCTNAME"
>PGresult</TT
> handle is passed to
<CODE
CLASS="FUNCTION"
>PQclear</CODE
>.</P
><P
>Immediately following a <CODE
CLASS="FUNCTION"
>PQexec</CODE
> or <CODE
CLASS="FUNCTION"
>PQgetResult</CODE
>
call, <CODE
CLASS="FUNCTION"
>PQerrorMessage</CODE
> (on the connection) will return the same
string as <CODE
CLASS="FUNCTION"
>PQresultErrorMessage</CODE
> (on the result). However, a
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> will retain its error message
until destroyed, whereas the connection's error message will change when
subsequent operations are done. Use <CODE
CLASS="FUNCTION"
>PQresultErrorMessage</CODE
> when you want to
know the status associated with a particular <TT
CLASS="STRUCTNAME"
>PGresult</TT
>; use <CODE
CLASS="FUNCTION"
>PQerrorMessage</CODE
>
when you want to know the status from the latest operation on the connection.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQresultErrorField</CODE
><A
NAME="AEN27387"
></A
></DT
><DD
><P
>Returns an individual field of an error report.
</P><PRE
CLASS="SYNOPSIS"
>char *PQresultErrorField(const PGresult *res, int fieldcode);</PRE
><P>
<TT
CLASS="PARAMETER"
>fieldcode</TT
> is an error field identifier; see the symbols
listed below. <TT
CLASS="SYMBOL"
>NULL</TT
> is returned if the
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> is not an error or warning result,
or does not include the specified field. Field values will normally
not include a trailing newline. The caller should not free the
result directly. It will be freed when the
associated <TT
CLASS="STRUCTNAME"
>PGresult</TT
> handle is passed to
<CODE
CLASS="FUNCTION"
>PQclear</CODE
>.</P
><P
>The following field codes are available:
<P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_SEVERITY</TT
></DT
><DD
><P
>The severity; the field contents are <TT
CLASS="LITERAL"
>ERROR</TT
>,
<TT
CLASS="LITERAL"
>FATAL</TT
>, or <TT
CLASS="LITERAL"
>PANIC</TT
> (in an error message), or
<TT
CLASS="LITERAL"
>WARNING</TT
>, <TT
CLASS="LITERAL"
>NOTICE</TT
>, <TT
CLASS="LITERAL"
>DEBUG</TT
>,
<TT
CLASS="LITERAL"
>INFO</TT
>, or <TT
CLASS="LITERAL"
>LOG</TT
> (in a notice message), or a
localized translation of one of these. Always present.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_SQLSTATE</TT
></DT
><DD
><P
>The SQLSTATE code for the error. The SQLSTATE code identifies the type
of error that has occurred; it can be used by front-end applications
to perform specific operations (such as error handling) in response to
a particular database error. For a list of the possible SQLSTATE
codes, see <A
HREF="errcodes-appendix.html"
>Appendix A</A
>. This field is not
localizable, and is always present.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_MESSAGE_PRIMARY</TT
></DT
><DD
><P
>The primary human-readable error message (typically one line). Always
present.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_MESSAGE_DETAIL</TT
></DT
><DD
><P
>Detail: an optional secondary error message carrying more detail about
the problem. May run to multiple lines.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_MESSAGE_HINT</TT
></DT
><DD
><P
>Hint: an optional suggestion what to do about the problem. This is
intended to differ from detail in that it offers advice (potentially
inappropriate) rather than hard facts. May run to multiple lines.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_STATEMENT_POSITION</TT
></DT
><DD
><P
>A string containing a decimal integer indicating an error cursor
position as an index into the original statement string. The first
character has index 1, and positions are measured in characters not
bytes.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_INTERNAL_POSITION</TT
></DT
><DD
><P
>This is defined the same as the <TT
CLASS="SYMBOL"
>PG_DIAG_STATEMENT_POSITION</TT
>
field, but it is used when the cursor position refers to an internally
generated command rather than the one submitted by the client.
The <TT
CLASS="SYMBOL"
>PG_DIAG_INTERNAL_QUERY</TT
> field will always appear when this field
appears.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_INTERNAL_QUERY</TT
></DT
><DD
><P
>The text of a failed internally-generated command.
This could be, for example, a SQL query issued by a PL/pgSQL function.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_CONTEXT</TT
></DT
><DD
><P
>An indication of the context in which the error occurred.
Presently this includes a call stack traceback of active
procedural language functions and internally-generated queries.
The trace is one entry per line, most recent first.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_SOURCE_FILE</TT
></DT
><DD
><P
>The file name of the source-code location where the error was
reported.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_SOURCE_LINE</TT
></DT
><DD
><P
>The line number of the source-code location where the error was
reported.</P
></DD
><DT
><TT
CLASS="SYMBOL"
>PG_DIAG_SOURCE_FUNCTION</TT
></DT
><DD
><P
>The name of the source-code function reporting the error.</P
></DD
></DL
></DIV
><P></P
><P
>The client is responsible for formatting displayed information to meet
its needs; in particular it should break long lines as needed.
Newline characters appearing in the error message fields should be
treated as paragraph breaks, not line breaks.</P
><P
>Errors generated internally by <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> will
have severity and primary message, but typically no other fields.
Errors returned by a pre-3.0-protocol server will include severity and
primary message, and sometimes a detail message, but no other fields.</P
><P
>Note that error fields are only available from
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> objects, not
<TT
CLASS="STRUCTNAME"
>PGconn</TT
> objects; there is no
<CODE
CLASS="FUNCTION"
>PQerrorField</CODE
> function.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQclear</CODE
><A
NAME="AEN27483"
></A
></DT
><DD
><P
> Frees the storage associated with a <TT
CLASS="STRUCTNAME"
>PGresult</TT
>.
Every command result should be freed via <CODE
CLASS="FUNCTION"
>PQclear</CODE
> when
it is no longer needed.
</P><PRE
CLASS="SYNOPSIS"
>void PQclear(PGresult *res);</PRE
><P></P
><P
> You can keep a <TT
CLASS="STRUCTNAME"
>PGresult</TT
> object around for as long as you
need it; it does not go away when you issue a new command,
nor even if you close the connection. To get rid of it,
you must call <CODE
CLASS="FUNCTION"
>PQclear</CODE
>. Failure to do this will
result in memory leaks in your application.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQmakeEmptyPGresult</CODE
><A
NAME="AEN27496"
></A
></DT
><DD
><P
> Constructs an empty <TT
CLASS="STRUCTNAME"
>PGresult</TT
> object with the given status.
</P><PRE
CLASS="SYNOPSIS"
>PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);</PRE
><P></P
><P
>This is <SPAN
CLASS="APPLICATION"
>libpq</SPAN
>'s internal function to allocate and
initialize an empty <TT
CLASS="STRUCTNAME"
>PGresult</TT
> object. This
function returns NULL if memory could not be allocated. It is exported
because some applications find it useful to generate result objects
(particularly objects with error status) themselves. If
<TT
CLASS="PARAMETER"
>conn</TT
> is not null and <TT
CLASS="PARAMETER"
>status</TT
>
indicates an error, the current error message of the specified
connection is copied into the <TT
CLASS="STRUCTNAME"
>PGresult</TT
>. Note
that <CODE
CLASS="FUNCTION"
>PQclear</CODE
> should eventually be called on the
object, just as with a <TT
CLASS="STRUCTNAME"
>PGresult</TT
> returned by
<SPAN
CLASS="APPLICATION"
>libpq</SPAN
> itself.</P
></DD
></DL
></DIV
><P></P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LIBPQ-EXEC-SELECT-INFO"
>29.3.2. Retrieving Query Result Information</A
></H2
><P
>These functions are used to extract information from a
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> object that represents a successful
query result (that is, one that has status
<TT
CLASS="LITERAL"
>PGRES_TUPLES_OK</TT
>). They can also be used to extract
information from a successful Describe operation: a Describe's result
has all the same column information that actual execution of the query
would provide, but it has zero rows. For objects with other status values,
these functions will act as though the result has zero rows and zero columns.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="FUNCTION"
>PQntuples</CODE
><A
NAME="AEN27520"
></A
></DT
><DD
><P
> Returns the number of rows (tuples)
in the query result.
</P><PRE
CLASS="SYNOPSIS"
>int PQntuples(const PGresult *res);</PRE
><P></P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQnfields</CODE
><A
NAME="AEN27528"
></A
></DT
><DD
><P
> Returns the number of columns (fields)
in each row of the query result.
</P><PRE
CLASS="SYNOPSIS"
>int PQnfields(const PGresult *res);</PRE
><P></P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQfname</CODE
><A
NAME="AEN27536"
></A
></DT
><DD
><P
>Returns the column name associated with the given column number.
Column numbers start at 0. The caller should not free the result
directly. It will be freed when the associated <TT
CLASS="STRUCTNAME"
>PGresult</TT
>
handle is passed to <CODE
CLASS="FUNCTION"
>PQclear</CODE
>.
</P><PRE
CLASS="SYNOPSIS"
>char *PQfname(const PGresult *res,
int column_number);</PRE
><P></P
><P
><TT
CLASS="SYMBOL"
>NULL</TT
> is returned if the column number is out of range.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQfnumber</CODE
><A
NAME="AEN27548"
></A
></DT
><DD
><P
> Returns the column number associated with the given column name.
</P><PRE
CLASS="SYNOPSIS"
>int PQfnumber(const PGresult *res,
const char *column_name);</PRE
><P></P
><P
> -1 is returned if the given name does not match any column.</P
><P
> The given name is treated like an identifier in an SQL command,
that is, it is downcased unless double-quoted. For example,
given a query result generated from the SQL command
</P><PRE
CLASS="PROGRAMLISTING"
>select 1 as FOO, 2 as "BAR";</PRE
><P>
we would have the results:
</P><PRE
CLASS="PROGRAMLISTING"
>PQfname(res, 0) <I
CLASS="LINEANNOTATION"
>foo</I
>
PQfname(res, 1) <I
CLASS="LINEANNOTATION"
>BAR</I
>
PQfnumber(res, "FOO") <I
CLASS="LINEANNOTATION"
>0</I
>
PQfnumber(res, "foo") <I
CLASS="LINEANNOTATION"
>0</I
>
PQfnumber(res, "BAR") <I
CLASS="LINEANNOTATION"
>-1</I
>
PQfnumber(res, "\"BAR\"") <I
CLASS="LINEANNOTATION"
>1</I
></PRE
><P></P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQftable</CODE
><A
NAME="AEN27566"
></A
></DT
><DD
><P
> Returns the OID of the table from which the given column was fetched.
Column numbers start at 0.
</P><PRE
CLASS="SYNOPSIS"
>Oid PQftable(const PGresult *res,
int column_number);</PRE
><P></P
><P
><TT
CLASS="LITERAL"
>InvalidOid</TT
> is returned if the column number is out of range,
or if the specified column is not a simple reference to a table column,
or when using pre-3.0 protocol.
You can query the system table <TT
CLASS="LITERAL"
>pg_class</TT
> to determine
exactly which table is referenced.</P
><P
> The type <TT
CLASS="TYPE"
>Oid</TT
> and the constant
<TT
CLASS="LITERAL"
>InvalidOid</TT
> will be defined when you include
the <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> header file. They will
both be some integer type.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQftablecol</CODE
><A
NAME="AEN27581"
></A
></DT
><DD
><P
> Returns the column number (within its table) of the column making up
the specified query result column.
Query-result column numbers start at 0, but table columns have nonzero
numbers.
</P><PRE
CLASS="SYNOPSIS"
>int PQftablecol(const PGresult *res,
int column_number);</PRE
><P></P
><P
>Zero is returned if the column number is out of range,
or if the specified column is not a simple reference to a table column,
or when using pre-3.0 protocol.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQfformat</CODE
><A
NAME="AEN27590"
></A
></DT
><DD
><P
> Returns the format code indicating the format of the given column.
Column numbers start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PQfformat(const PGresult *res,
int column_number);</PRE
><P></P
><P
>Format code zero indicates textual data representation, while format
code one indicates binary representation. (Other codes are reserved
for future definition.)</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQftype</CODE
><A
NAME="AEN27599"
></A
></DT
><DD
><P
> Returns the data type associated with the
given column number. The integer returned is the
internal OID number of the type. Column numbers start
at 0.
</P><PRE
CLASS="SYNOPSIS"
>Oid PQftype(const PGresult *res,
int column_number);</PRE
><P></P
><P
>You can query the system table <TT
CLASS="LITERAL"
>pg_type</TT
> to obtain
the names and properties of the various data types. The <ACRONYM
CLASS="ACRONYM"
>OID</ACRONYM
>s
of the built-in data types are defined in the file <TT
CLASS="FILENAME"
>src/include/catalog/pg_type.h</TT
>
in the source tree.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQfmod</CODE
><A
NAME="AEN27611"
></A
></DT
><DD
><P
> Returns the type modifier of the column
associated with the given column number.
Column numbers start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PQfmod(const PGresult *res,
int column_number);</PRE
><P></P
><P
>The interpretation of modifier values is type-specific; they typically
indicate precision or size limits. The value -1 is used to indicate
<SPAN
CLASS="QUOTE"
>"no information available"</SPAN
>. Most data types do not use modifiers,
in which case the value is always -1.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQfsize</CODE
><A
NAME="AEN27621"
></A
></DT
><DD
><P
> Returns the size in bytes of the column
associated with the given column number.
Column numbers start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PQfsize(const PGresult *res,
int column_number);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQfsize</CODE
> returns the space allocated for this column in a database
row, in other words the size of the server's internal representation
of the data type. (Accordingly, it is not really very useful to clients.)
A negative value indicates the data type is variable-length.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQbinaryTuples</CODE
><A
NAME="AEN27631"
></A
></DT
><DD
><P
>Returns 1 if the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> contains binary data
and 0 if it contains text data.
</P><PRE
CLASS="SYNOPSIS"
>int PQbinaryTuples(const PGresult *res);</PRE
><P></P
><P
>This function is deprecated (except for its use in connection with
<TT
CLASS="COMMAND"
>COPY</TT
>), because it is possible for a single
<TT
CLASS="STRUCTNAME"
>PGresult</TT
>
to contain text data in some columns and binary data in others.
<CODE
CLASS="FUNCTION"
>PQfformat</CODE
> is preferred. <CODE
CLASS="FUNCTION"
>PQbinaryTuples</CODE
>
returns 1 only if all columns of the result are binary (format 1).</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQgetvalue</CODE
><A
NAME="AEN27645"
></A
></DT
><DD
><P
> Returns a single field value of one row of a
<TT
CLASS="STRUCTNAME"
>PGresult</TT
>. Row and column numbers
start at 0. The caller should not free the result
directly. It will be freed when the associated
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> handle is passed to
<CODE
CLASS="FUNCTION"
>PQclear</CODE
>.
</P><PRE
CLASS="SYNOPSIS"
>char *PQgetvalue(const PGresult *res,
int row_number,
int column_number);</PRE
><P></P
><P
>For data in text format, the value returned by <CODE
CLASS="FUNCTION"
>PQgetvalue</CODE
>
is a null-terminated character string representation
of the field value. For data in binary format, the value is in the binary
representation determined by the data type's <CODE
CLASS="FUNCTION"
>typsend</CODE
> and
<CODE
CLASS="FUNCTION"
>typreceive</CODE
> functions. (The value is actually followed by
a zero byte in this case too, but that is not ordinarily useful, since
the value is likely to contain embedded nulls.)</P
><P
>An empty string is returned if the field value is null. See
<CODE
CLASS="FUNCTION"
>PQgetisnull</CODE
> to distinguish null values from empty-string values.</P
><P
>The pointer
returned by <CODE
CLASS="FUNCTION"
>PQgetvalue</CODE
> points to storage that is
part of the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> structure. One should not modify the data it points to,
and one must explicitly
copy the data into other storage if it is to
be used past the lifetime of the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> structure itself.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQgetisnull</CODE
><A
NAME="AEN27666"
></A
></DT
><DD
><P
> Tests a field for a null value.
Row and column numbers start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PQgetisnull(const PGresult *res,
int row_number,
int column_number);</PRE
><P></P
><P
>This function returns 1 if the field is null and 0 if
it contains a non-null value. (Note that <CODE
CLASS="FUNCTION"
>PQgetvalue</CODE
>
will return an empty string, not a null pointer, for a null field.)</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQgetlength</CODE
><A
NAME="AEN27679"
></A
></DT
><DD
><P
> Returns the actual length of a field value in bytes.
Row and column numbers start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PQgetlength(const PGresult *res,
int row_number,
int column_number);</PRE
><P></P
><P
>This is the actual data length for the particular data value, that is, the
size of the object pointed to by <CODE
CLASS="FUNCTION"
>PQgetvalue</CODE
>. For text
data format this is the same as <CODE
CLASS="FUNCTION"
>strlen()</CODE
>. For binary format
this is essential information. Note that one should <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> rely
on <CODE
CLASS="FUNCTION"
>PQfsize</CODE
> to obtain the actual data length.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQnparams</CODE
><A
NAME="AEN27692"
></A
></DT
><DD
><P
> Returns the number of parameters of a prepared statement.
</P><PRE
CLASS="SYNOPSIS"
>int PQnparams(const PGresult *res);</PRE
><P></P
><P
>This function is only useful when inspecting the result of
<CODE
CLASS="FUNCTION"
>PQdescribePrepared</CODE
>. For other types of queries it will
return zero.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQparamtype</CODE
><A
NAME="AEN27702"
></A
></DT
><DD
><P
> Returns the data type of the indicated statement parameter.
Parameter numbers start at 0.
</P><PRE
CLASS="SYNOPSIS"
>Oid PQparamtype(const PGresult *res, int param_number);</PRE
><P></P
><P
>This function is only useful when inspecting the result of
<CODE
CLASS="FUNCTION"
>PQdescribePrepared</CODE
>. For other types of queries it will
return zero.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQprint</CODE
><A
NAME="AEN27712"
></A
></DT
><DD
><P
> Prints out all the rows and, optionally, the
column names to the specified output stream.
</P><PRE
CLASS="SYNOPSIS"
>void PQprint(FILE *fout, /* output stream */
const PGresult *res,
const PQprintOpt *po);
typedef struct {
pqbool header; /* print output field headings and row count */
pqbool align; /* fill align the fields */
pqbool standard; /* old brain dead format */
pqbool html3; /* output HTML tables */
pqbool expanded; /* expand tables */
pqbool pager; /* use pager for output if needed */
char *fieldSep; /* field separator */
char *tableOpt; /* attributes for HTML table element */
char *caption; /* HTML table caption */
char **fieldName; /* null-terminated array of replacement field names */
} PQprintOpt;</PRE
><P></P
><P
>This function was formerly used by <SPAN
CLASS="APPLICATION"
>psql</SPAN
>
to print query results, but this is no longer the case. Note that it
assumes all the data is in text format.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LIBPQ-EXEC-NONSELECT"
>29.3.3. Retrieving Result Information for Other Commands</A
></H2
><P
>These functions are used to extract information from
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> objects that are not <TT
CLASS="COMMAND"
>SELECT</TT
>
results.</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="FUNCTION"
>PQcmdStatus</CODE
><A
NAME="AEN27728"
></A
></DT
><DD
><P
> Returns the command status tag from the SQL command that
generated the <TT
CLASS="STRUCTNAME"
>PGresult</TT
>.
</P><PRE
CLASS="SYNOPSIS"
>char *PQcmdStatus(PGresult *res);</PRE
><P></P
><P
>Commonly this is just the name of the command, but it may include additional
data such as the number of rows processed. The caller should
not free the result directly. It will be freed when the
associated <TT
CLASS="STRUCTNAME"
>PGresult</TT
> handle is passed to
<CODE
CLASS="FUNCTION"
>PQclear</CODE
>.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQcmdTuples</CODE
><A
NAME="AEN27740"
></A
></DT
><DD
><P
> Returns the number of rows affected by the SQL command.
</P><PRE
CLASS="SYNOPSIS"
>char *PQcmdTuples(PGresult *res);</PRE
><P></P
><P
> This function returns a string containing the number of rows
affected by the <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> statement that generated the
<TT
CLASS="STRUCTNAME"
>PGresult</TT
>. This function can only be used
following the execution of an <TT
CLASS="COMMAND"
>INSERT</TT
>,
<TT
CLASS="COMMAND"
>UPDATE</TT
>, <TT
CLASS="COMMAND"
>DELETE</TT
>, <TT
CLASS="COMMAND"
>MOVE</TT
>,
<TT
CLASS="COMMAND"
>FETCH</TT
>, or <TT
CLASS="COMMAND"
>COPY</TT
> statement,
or an <TT
CLASS="COMMAND"
>EXECUTE</TT
> of a
prepared query that contains an <TT
CLASS="COMMAND"
>INSERT</TT
>,
<TT
CLASS="COMMAND"
>UPDATE</TT
>, or <TT
CLASS="COMMAND"
>DELETE</TT
> statement. If the
command that generated the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> was
anything else, <CODE
CLASS="FUNCTION"
>PQcmdTuples</CODE
> returns an empty
string. The caller should not free the return value
directly. It will be freed when the associated
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> handle is passed to
<CODE
CLASS="FUNCTION"
>PQclear</CODE
>.</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQoidValue</CODE
><A
NAME="AEN27765"
></A
></DT
><DD
><P
> Returns the OID<A
NAME="AEN27769"
></A
> of the inserted row, if the <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
>
command was an <TT
CLASS="COMMAND"
>INSERT</TT
> that inserted exactly one
row into a table that has OIDs, or a <TT
CLASS="COMMAND"
>EXECUTE</TT
> of
a prepared query containing a suitable <TT
CLASS="COMMAND"
>INSERT</TT
>
statement. Otherwise, this function returns
<TT
CLASS="LITERAL"
>InvalidOid</TT
>. This function will also
return <TT
CLASS="LITERAL"
>InvalidOid</TT
> if the table affected
by the <TT
CLASS="COMMAND"
>INSERT</TT
> statement does not contain OIDs.
</P><PRE
CLASS="SYNOPSIS"
>Oid PQoidValue(const PGresult *res);</PRE
><P></P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQoidStatus</CODE
><A
NAME="AEN27783"
></A
></DT
><DD
><P
> Returns a string with the OID of the inserted row, if the
<ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
> command was an
<TT
CLASS="COMMAND"
>INSERT</TT
> that inserted exactly one row, or
a <TT
CLASS="COMMAND"
>EXECUTE</TT
> of a prepared statement
consisting of a suitable <TT
CLASS="COMMAND"
>INSERT</TT
>. (The string will be
<TT
CLASS="LITERAL"
>0</TT
> if the <TT
CLASS="COMMAND"
>INSERT</TT
> did not
insert exactly one row, or if the target table does not have
OIDs.) If the command was not an <TT
CLASS="COMMAND"
>INSERT</TT
>,
returns an empty string.
</P><PRE
CLASS="SYNOPSIS"
>char *PQoidStatus(const PGresult *res);</PRE
><P></P
><P
>This function is deprecated in favor of <CODE
CLASS="FUNCTION"
>PQoidValue</CODE
>.
It is not thread-safe.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LIBPQ-EXEC-ESCAPE-STRING"
>29.3.4. Escaping Strings for Inclusion in SQL Commands</A
></H2
><A
NAME="AEN27799"
></A
><A
NAME="AEN27801"
></A
><A
NAME="AEN27803"
></A
><P
><CODE
CLASS="FUNCTION"
>PQescapeStringConn</CODE
> escapes a string for use within an SQL
command. This is useful when inserting data values as literal constants
in SQL commands. Certain characters (such as quotes and backslashes) must
be escaped to prevent them from being interpreted specially by the SQL parser.
<CODE
CLASS="FUNCTION"
>PQescapeStringConn</CODE
> performs this operation.</P
><DIV
CLASS="TIP"
><BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
>It is especially important to do proper escaping when handling strings that
were received from an untrustworthy source. Otherwise there is a security
risk: you are vulnerable to <SPAN
CLASS="QUOTE"
>"SQL injection"</SPAN
> attacks wherein unwanted
SQL commands are fed to your database.</P
></BLOCKQUOTE
></DIV
><P
>Note that it is not necessary nor correct to do escaping when a data
value is passed as a separate parameter in <CODE
CLASS="FUNCTION"
>PQexecParams</CODE
> or
its sibling routines.
</P><PRE
CLASS="SYNOPSIS"
>size_t PQescapeStringConn (PGconn *conn,
char *to, const char *from, size_t length,
int *error);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQescapeStringConn</CODE
> writes an escaped
version of the <TT
CLASS="PARAMETER"
>from</TT
> string to the <TT
CLASS="PARAMETER"
>to</TT
>
buffer, escaping special characters so that they cannot cause any
harm, and adding a terminating zero byte. The single quotes that
must surround <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> string literals are not
included in the result string; they should be provided in the SQL
command that the result is inserted into.
The parameter <TT
CLASS="PARAMETER"
>from</TT
> points to the first character of the string
that is to be escaped, and the <TT
CLASS="PARAMETER"
>length</TT
> parameter gives the
number of bytes in this string. A terminating zero byte is not
required, and should not be counted in <TT
CLASS="PARAMETER"
>length</TT
>. (If
a terminating zero byte is found before <TT
CLASS="PARAMETER"
>length</TT
> bytes are
processed, <CODE
CLASS="FUNCTION"
>PQescapeStringConn</CODE
> stops at the zero; the behavior
is thus rather like <CODE
CLASS="FUNCTION"
>strncpy</CODE
>.)
<TT
CLASS="PARAMETER"
>to</TT
> shall point to a
buffer that is able to hold at least one more byte than twice
the value of <TT
CLASS="PARAMETER"
>length</TT
>, otherwise the behavior is
undefined.
Behavior is likewise undefined if the <TT
CLASS="PARAMETER"
>to</TT
> and <TT
CLASS="PARAMETER"
>from</TT
>
strings overlap.</P
><P
>If the <TT
CLASS="PARAMETER"
>error</TT
> parameter is not NULL, then <TT
CLASS="LITERAL"
>*error</TT
>
is set to zero on success, nonzero on error. Presently the only possible
error conditions involve invalid multibyte encoding in the source string.
The output string is still generated on error, but it can be expected that
the server will reject it as malformed. On error, a suitable message is
stored in the <TT
CLASS="PARAMETER"
>conn</TT
> object, whether or not <TT
CLASS="PARAMETER"
>error</TT
>
is NULL.</P
><P
><CODE
CLASS="FUNCTION"
>PQescapeStringConn</CODE
> returns the number of bytes written
to <TT
CLASS="PARAMETER"
>to</TT
>, not including the terminating zero byte.</P
><P
></P><PRE
CLASS="SYNOPSIS"
>size_t PQescapeString (char *to, const char *from, size_t length);</PRE
><P></P
><P
><CODE
CLASS="FUNCTION"
>PQescapeString</CODE
> is an older, deprecated version of
<CODE
CLASS="FUNCTION"
>PQescapeStringConn</CODE
>; the difference is that it does not
take <TT
CLASS="PARAMETER"
>conn</TT
> or <TT
CLASS="PARAMETER"
>error</TT
> parameters. Because of this,
it cannot adjust its behavior depending on the connection properties (such as
character encoding) and therefore <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>it may give the wrong results</I
></SPAN
>.
Also, it has no way to report error conditions.</P
><P
><CODE
CLASS="FUNCTION"
>PQescapeString</CODE
> can be used safely in single-threaded client
programs that work with only one <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> connection at
a time (in this case it can find out what it needs to know <SPAN
CLASS="QUOTE"
>"behind the
scenes"</SPAN
>). In other contexts it is a security hazard and should be avoided
in favor of <CODE
CLASS="FUNCTION"
>PQescapeStringConn</CODE
>.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="LIBPQ-EXEC-ESCAPE-BYTEA"
>29.3.5. Escaping Binary Strings for Inclusion in SQL Commands</A
></H2
><A
NAME="AEN27853"
></A
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="FUNCTION"
>PQescapeByteaConn</CODE
><A
NAME="AEN27860"
></A
></DT
><DD
><P
> Escapes binary data for use within an SQL command with the type
<TT
CLASS="TYPE"
>bytea</TT
>. As with <CODE
CLASS="FUNCTION"
>PQescapeStringConn</CODE
>,
this is only used when inserting data directly into an SQL command string.
</P><PRE
CLASS="SYNOPSIS"
>unsigned char *PQescapeByteaConn(PGconn *conn,
const unsigned char *from,
size_t from_length,
size_t *to_length);</PRE
><P></P
><P
> Certain byte values <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>must</I
></SPAN
> be escaped (but all
byte values <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>can</I
></SPAN
> be escaped) when used as part
of a <TT
CLASS="TYPE"
>bytea</TT
> literal in an <ACRONYM
CLASS="ACRONYM"
>SQL</ACRONYM
>
statement. In general, to escape a byte, it is converted into the
three digit octal number equal to the octet value, and preceded by
usually two backslashes. The single quote (<TT
CLASS="LITERAL"
>'</TT
>) and backslash
(<TT
CLASS="LITERAL"
>\</TT
>) characters have special alternative escape
sequences. See <A
HREF="datatype-binary.html"
>Section 8.4</A
> for more
information. <CODE
CLASS="FUNCTION"
>PQescapeByteaConn</CODE
> performs this
operation, escaping only the minimally required bytes.
</P
><P
> The <TT
CLASS="PARAMETER"
>from</TT
> parameter points to the first
byte of the string that is to be escaped, and the
<TT
CLASS="PARAMETER"
>from_length</TT
> parameter gives the number of
bytes in this binary string. (A terminating zero byte is
neither necessary nor counted.) The <TT
CLASS="PARAMETER"
>to_length</TT
>
parameter points to a variable that will hold the resultant
escaped string length. This result string length includes the terminating
zero byte of the result.
</P
><P
> <CODE
CLASS="FUNCTION"
>PQescapeByteaConn</CODE
> returns an escaped version of the
<TT
CLASS="PARAMETER"
>from</TT
> parameter binary string in memory
allocated with <CODE
CLASS="FUNCTION"
>malloc()</CODE
>. This memory must be freed using
<CODE
CLASS="FUNCTION"
>PQfreemem()</CODE
> when the result is no longer needed. The
return string has all special characters replaced so that they can
be properly processed by the <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>
string literal parser, and the <TT
CLASS="TYPE"
>bytea</TT
> input function. A
terminating zero byte is also added. The single quotes that must
surround <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> string literals are
not part of the result string.
</P
><P
> On error, a NULL pointer is returned, and a suitable error message
is stored in the <TT
CLASS="PARAMETER"
>conn</TT
> object. Currently, the only
possible error is insufficient memory for the result string.
</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQescapeBytea</CODE
><A
NAME="AEN27893"
></A
></DT
><DD
><P
> <CODE
CLASS="FUNCTION"
>PQescapeBytea</CODE
> is an older, deprecated version of
<CODE
CLASS="FUNCTION"
>PQescapeByteaConn</CODE
>.
</P><PRE
CLASS="SYNOPSIS"
>unsigned char *PQescapeBytea(const unsigned char *from,
size_t from_length,
size_t *to_length);</PRE
><P></P
><P
> The only difference from <CODE
CLASS="FUNCTION"
>PQescapeByteaConn</CODE
> is that
<CODE
CLASS="FUNCTION"
>PQescapeBytea</CODE
> does not
take a <TT
CLASS="STRUCTNAME"
>PGconn</TT
> parameter. Because of this, it cannot adjust
its behavior depending on the connection properties (in particular,
whether standard-conforming strings are enabled)
and therefore <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>it may give the wrong results</I
></SPAN
>. Also, it
has no way to return an error message on failure.
</P
><P
> <CODE
CLASS="FUNCTION"
>PQescapeBytea</CODE
> can be used safely in single-threaded client
programs that work with only one <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> connection at
a time (in this case it can find out what it needs to know <SPAN
CLASS="QUOTE"
>"behind the
scenes"</SPAN
>). In other contexts it is a security hazard and should be
avoided in favor of <CODE
CLASS="FUNCTION"
>PQescapeByteaConn</CODE
>.
</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQunescapeBytea</CODE
><A
NAME="AEN27913"
></A
></DT
><DD
><P
> Converts a string representation of binary data into binary
data — the reverse of <CODE
CLASS="FUNCTION"
>PQescapeBytea</CODE
>.
This is needed when retrieving <TT
CLASS="TYPE"
>bytea</TT
> data in text format,
but not when retrieving it in binary format.
</P><PRE
CLASS="SYNOPSIS"
>unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);</PRE
><P></P
><P
> The <TT
CLASS="PARAMETER"
>from</TT
> parameter points to a string
such as might be returned by <CODE
CLASS="FUNCTION"
>PQgetvalue</CODE
> when applied
to a <TT
CLASS="TYPE"
>bytea</TT
> column. <CODE
CLASS="FUNCTION"
>PQunescapeBytea</CODE
>
converts this string representation into its binary representation.
It returns a pointer to a buffer allocated with
<CODE
CLASS="FUNCTION"
>malloc()</CODE
>, or null on error, and puts the size of
the buffer in <TT
CLASS="PARAMETER"
>to_length</TT
>. The result must be
freed using <CODE
CLASS="FUNCTION"
>PQfreemem</CODE
> when it is no longer needed.
</P
><P
> This conversion is not exactly the inverse of
<CODE
CLASS="FUNCTION"
>PQescapeBytea</CODE
>, because the string is not expected
to be <SPAN
CLASS="QUOTE"
>"escaped"</SPAN
> when received from <CODE
CLASS="FUNCTION"
>PQgetvalue</CODE
>.
In particular this means there is no need for string quoting considerations,
and so no need for a <TT
CLASS="STRUCTNAME"
>PGconn</TT
> parameter.
</P
></DD
><DT
><CODE
CLASS="FUNCTION"
>PQfreemem</CODE
><A
NAME="AEN27936"
></A
></DT
><DD
><P
> Frees memory allocated by <SPAN
CLASS="APPLICATION"
>libpq</SPAN
>.
</P><PRE
CLASS="SYNOPSIS"
>void PQfreemem(void *ptr);</PRE
><P></P
><P
> Frees memory allocated by <SPAN
CLASS="APPLICATION"
>libpq</SPAN
>, particularly
<CODE
CLASS="FUNCTION"
>PQescapeByteaConn</CODE
>,
<CODE
CLASS="FUNCTION"
>PQescapeBytea</CODE
>,
<CODE
CLASS="FUNCTION"
>PQunescapeBytea</CODE
>,
and <CODE
CLASS="FUNCTION"
>PQnotifies</CODE
>.
It is particularly important that this function, rather than
<CODE
CLASS="FUNCTION"
>free()</CODE
>, be used on Microsoft Windows. This is because
allocating memory in a DLL and releasing it in the application works
only if multithreaded/single-threaded, release/debug, and static/dynamic
flags are the same for the DLL and the application. On non-Microsoft
Windows platforms, this function is the same as the standard library
function <CODE
CLASS="FUNCTION"
>free()</CODE
>.
</P
></DD
></DL
></DIV
></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="libpq-status.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="libpq-async.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Connection Status Functions</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Asynchronous Command Processing</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a866202fe868538f89a755dbcabc378b
>
files
>
292
