DragonFly On-Line Manual Pages

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
       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)