NAME

       PQexecf - Prepares parameters and executes a command.

SYNOPSIS

       #include <libpqtypes.h>

       PGresult *PQexecf(const PGconn *conn, const char *cmd, ...);
       PGresult *PQexecvf(const PGconn *conn, const char *cmd, va_list ap);
       int PQsendf(const PGconn *conn, const char *cmd, ...);
       int PQsendvf(const PGconn *conn, const char *cmd, va_list ap);

DESCRIPTION

       The  PQexecf() function executes a command that uses libpqtypes type specifiers instead of
       $1, $2, etc... syntax.  The idea is to combine PQputvf() and PQparamExec() into  a  single
       call.   The  variable  argument  list must match the type specs listed within the cmd. The
       type specifiers should be placed where one would normally place $1, $2, etc...

       The PQexecvf() function is identical to PQexecf() except it takes a va_list.

       The PQsendf() and PQsendvf() functions are identical to PQexecf()  and  PQexecvf()  except
       they are asynchronous versions, meaning an additional call, PQgetResult, must be issued to
       get the  PGresult  object.   For  more  information,  see  the  PostgreSQL  Documentation:
       specifically  the  "Asynchronous  Command  Processing"  section under "Client Interfaces |
       libpq - C library".

       A  prepared  type  spec  "@name"  can  be  used  with  these   functions,   granted   that
       PQspecPrepare()  was  called  with  a  non-zero  value  for  the  is_stmt argument.  These
       functions needs an actual SQL statement to execute.

RETURN VALUE

       PQexecf and PQexecvf return NULL on error and a valid PGresult on  success.   PQsendf  and
       PQsendvf  return  zero  on  error  and  a  non-zero  value  on  success.   On  error,  use
       PQgeterror(3) to obtain an error message.

EXAMPLES

   Using PQexecf
       The example uses PQexecf function to execute a query.

              /* The PQexecf call is shorthand for:
               *
               *   PGparam *param = PQparamCreate(conn);
               *   PQputf(param, "%int4 %int4", 1, 1);
               *   res = PQparamExec(conn, param, "SELECT $1 + $2", 1);
               *   PQparamClear(param);
               *
               * As you may notice, PQexecf makes life much simpler.
               */
              PGresult *res = PQexecf(conn, "SELECT %int4 + %int4", 1, 1);

              if(!res)
                   fprintf(stderr, "PQexecf failed: %s", PQgeterror());
              else
                   PQclear(res);

              /* A bit more common, this puts an int4 and a text into a generated
               * PGparam and then executes 'myfunc($1, $2)'
               */
              res = PQexecf(conn, "SELECT * FROM myfunc(%int4, %text)", 2, "abc");

              /* Prepared type spec example.  To use with execf, the final "is_stmt"
               * argument must be set to a non-zero value!
               */
              PQspecPrepare(conn, "account_insert", "INSERT INTO account VALUES "
                   "(%int8, %text, %int4)", 1);

              PGint8 acc_id = 78236;
              PGtext acc_name = "ABC Coders, LLC.";
              PGint4 acc_biz = ACC_BIZ_TECHNOLOGY;

              PQexecf(conn, "@account_insert", acc_id, acc_name, acc_biz);

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

       PQgeterror(3), PQputvf(3), PQparamExec(3)