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 parameterized 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 previously prepared via PQprepare().

Both functions take a param argument, which must contain the same number 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 composites 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 PQparamExecPrepared() 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 functions 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, PQgeterror().

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 PQparamExecPrepared

PQparamExecPrepared() 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.