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)

libpqtypes                                            2011                                        PQparamExec(3)