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 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) 2008 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
       PQparamCreate(3), PQparamSendQuery(3), PQparamSendQueryPrepared(3)



libpqtypes                           2008                       PQparamExec(3)

libpqtypes home page