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.

SEE ALSO

       PQparamCreate(3), PQparamSendQuery(3), PQparamSendQueryPrepared(3)