NAME¶
PQputf, PQputvf - Packs a set of parameters in a PGparam for use with a
parameterized query.
SYNOPSIS¶
#include <libpqtypes.h>
int PQputf(PGparam *
param, const char *
format, ...);
int PQputvf(PGparam *
param, char *
stmtBuf, size_t
stmtBufLen,
const char *
format, va_list
ap);
DESCRIPTION¶
The
PQputf() and
PQputvf() functions put one or more query
parameters into a PGparam using a printf style interface. Any number of
parameters can be put at the same time.
The
format argument is a data type specifier string indicating the
parameters being put, such as "%int4 %polygon".
format cannot
be NULL or an empty string. The variable argument list must match the
format, either "..." or
ap. The number of arguments
required for each data type is dependant on the data type itself; built-in
PostgreSQL types always require a single argument.
The
PQputvf() function can construct a parameterized command string from
format, as long as
stmtBuf and
stmtBufLen have been
provided. If the construction of
stmtBuf is not desired, set it to NULL
and set
stmtBufLen to 0. When a constructed statement is desired, the
contents of
format will be copied to
stmtBuf and all data type
specifiers, like "%int4", will be replaced with $1, $2, etc...
syntax. The result is a parameterized statement in synch with
param and
ready to be executed. For instance: if
spec is "SELECT %int4 +
%int4", the resulting
stmtBuf would be "SELECT $1 + $2".
RETURN VALUE¶
On success, a non-zero value is returned. On error, zero is returned and
PQgeterror(3) will contain an error message.
If any put operation fails, the
param is reverted back to the number of
parameters it had prior to the function call; partial puts are not allowed.
EXAMPLES¶
Using PQputf¶
The example uses
PQputf() to put a couple parameters into a PGparam.
PGtext text = "foobar";
PGint8 i8 = PQT_INT64CONST(1099511627776);
PGparam *param = PQparamCreate(conn);
if(!PQputf(param, "%text %int8", text, i8))
fprintf(stderr, "*ERROR: %s\n", PQgeterror());
PQparamClear(param);
Using PQputvf¶
The example creates an application function named execf. execf is a wrapper to
PQputvf(), as well as
PQparamExec(3). It is similar to
PQexecf(). The only difference is that the PQexecf implementation uses
a smaller stack buffer and allocates heap memory when needed.
PGresult *
execf(PGconn *conn, const char *format, ...)
{
va_list ap;
char stmt[32768];
PGparam *param;
PGresult *res = NULL;
/* create the temporary PGparam */
if(!(param = PQparamCreate(conn)))
return NULL; /* PQseterror already called */
/* put the params, create the stmt and exec it */
va_start(ap, format);
if(PQputvf(param, stmt, sizeof(stmt), format, ap))
res = PQparamExec(conn, param, stmt, 1); // resfmt is binary
va_end(ap);
/* param must be cleared */
PQparamClear(param);
return res;
}
/* Example: execf will put 2 ints and execute "SELECT $1 + $2" */
PGresult *res = execf(conn, "SELECT %int4 + %int4", 100, 67);
if(!res)
fprintf(stderr, "*ERROR: %s\n", PQgeterror());
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 ALSO¶
pqt-specs(3),
PQparamCreate(3),
PQgeterror(3),
PQseterror(3)