PQparamExec(3) libpqtypes Manual PQparamExec(3)NAME
PQparamExec, PQparamExecPrepared - Executes a paramertized query using
the parameters in a PGparam.
SYNOPSIS
#include <libpqtypes.h>
PGresult *PQparamExec(PGconn *conn, PGparam *param,
const char *command, int resultFormat);
PGresult *PQparamExecPrepared(PGconn *conn, PGparam *param,
const char *stmtName, int resultFormat);
DESCRIPTION
The PQparamExec() and PQparamExecPrepared() functions execute a parame‐
terized query using the parameters in a PGparam. The only difference
between these functions is that PQparamExec() expects a parameterized
command string while PQparamExecPrepared() expects a stmtName previ‐
ously prepared via PQprepare().
Both functions take a param argument, which must contain the same num‐
ber of parameters as either the command string or previously prepared
stmtName. Internally, the param is transformed into parallel arrays
that are supplied to a PQexecParams() or PQexecPrepared() call.
The resultFormat argument indicates if text or binary results are
desired; a value of zero or one respectively. PQgetf supports both
text and binary result formats, with the exclusion of arrays and com‐
posites which only support binary.
RETURN VALUE
On success, a pointer to a PGresult is returned. On error, NULL is
returned and PQgeterror(3) will contain an error message.
IMPORTANT!
There is a difference in behavior between PQparamExec() and PQparamEx‐
ecPrepared() and the libpq functions they wrap, PQexecParams() and
PQexecPrepared(). PQparamExec() and PQparamExecPrepared() only return
a non-NULL PGresult when the result status is either PGRES_COMMAND_OK,
PGRES_TUPLES_OK or PGRES_EMPTY_QUERY. If these functions detect any
other result status, the PGresult is cleared and a NULL result is
returned. Before clearing the PGresult and returning NULL, these func‐
tions first copy the result error message into the libpqtypes error
system, accessible via PQgeterror(3). This allows applications to get
a result´s error message without needing the result object. conn error
messages are also copied to the libpqtypes error system.
This behavior difference provides a single error indicator, a NULL
return, and a single function that can get the error message, PQgeter‐
ror().
EXAMPLES
Using PQparamExec
The example uses PQparamExec() to execute a query using a PGparam. The
example also demonstrates how to detect a failed exec and output an
error message.
PGparam *param = PQparamCreate(conn);
if(!PQputf(param, "%text %int4", "ACTIVE", CAT_CAR))
{
fprintf(stderr, "PQputf: %s\n", PQgeterror());
}
else
{
PGresult *res = PQparamExec(conn, param,
"SELECT * FROM t WHERE status=$1 AND category=$2", 1);
if(!res)
fprintf(stderr, "PQparamExec: %s\n", PQgeterror());
else
print_results(res);
PQclear(res);
}
PQparamClear(param);
Using PQparamExecPreparedPQparamExecPrepared() is behaves identically to PQparamExec(), except
PQparamExecPrepared() requires that a statement has been previously
prepared via PQprepare(). Also, a stmtName is supplied rather than a
parameterized command string.
AUTHOR
A contribution of eSilo, LLC. for the PostgreSQL Database Management
System. Written by Andrew Chernow and Merlin Moncure.
REPORTING BUGS
Report bugs to <libpqtypes@esilo.com>.
COPYRIGHT
Copyright (c) 2011 eSilo, LLC. All rights reserved.
This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
SEE ALSOPQparamCreate(3), PQparamSendQuery(3), PQparamSendQueryPrepared(3)libpqtypes 2011 PQparamExec(3)
