Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PQspecPrepare(3)	       libpqtypes Manual	      PQspecPrepare(3)

NAME
       PQspecPrepare - Prepares	a libpqtypes specifier format string.

SYNOPSIS
       #include	<libpqtypes.h>

       int PQspecPrepare(PGconn	*conn, const char *name,
			     const char	*format, int is_stmt);
       void PQclearSpecs(PGconn	*conn);

DESCRIPTION
       PQspecPrepare allows an application to prepare specifier	format strings
       that will be used frequently.  By preparing a specifier format  string,
       one  avoids  the	parsing	and type handler lookup	costs.	This becomes a
       significant win when managing large result sets or  arrays,  where  the
       specifier  format, like "%int4 %text %bytea", must be prepared for each
       tuple/element.

       As with PQregisterXXX, only specifier format strings prepared prior  to
       the creation of a PGresult or PGparam, will be available	for use.  This
       is because the prepared type spec is cached within a PGconn object  and
       copied to all subsequent	PGparam	and PGresult objects.

       Every  prepared	type spec is given a name, which is used as its	unique
       identifier.  To use a prepared type spec, the name  is  provided	 where
       ever  a	regular	 specifier  format  string  is allowed,	like PQputf or
       PQgetf.	The name must be proceeded by a	'@' AT sign.  For more	infor-
       mation about the	syntax,	see the	pqt-specs(3) man page.

       The  format  argument  is  the  specifier format	string being prepared.
       When this is NULL, the name prepared type spec is removed from the  PG-
       conn's internal array.

       The is_stmt argument indicates if a parementerized statement version of
       format should be	cached along with the prepared type spec.  This	 means
       all  type specifiers in format, like "%int4", will be converted to "$1"
       syntax.	When is_stmt is	non-zero, a statement will created and cached.
       For  more  information on specifer format string	to paremterized	state-
       ments, see the PQputf(3)	man page.  NOTE: to use	a prepared  type  spec
       with execution functions	like PQexecf, is_stmt must be set to non-zero.

       PQclearSpecs  removes all prepared specifiers from the given PGconn, as
       opposed to removing them	one by one by setting  PQspecPrepare's	format
       argument	 to NULL.  A good use for this is after	a PQresetXXX call when
       it might	be desired to re-prepare all type specifiers.

       Functions that support the use of a prepared  type  spec	 are:  PQputf,
       PQputvf,	 PQgetf,  PQgetvf,  PQexecf,  PQexecvf,	PQsendf, PQsendvf, PQ-
       paramExec, PQparamSendQuery.

       HINT: A good rule of thumb for using prepared type specs, is when there
       are  a  large  number  of  PQputf/PQgetf	calls per statement execution.
       This commonly occurs when dealing with large result sets	and arrays.

RETURN VALUE
       PQspecPrepare and PQclearSpecs return a nonzero value  on  success  and
       zero if it fails.  Use PQgeterror() to get an error message.

EXAMPLES
       This example prepares a type spec and issues some PQputf	calls.

	      int i;
	      PQparam *param;

	      if(!PQspecPrepare(conn, "prepared_spec", "%int4 %text", 0))
	      {
		   fprintf(stderr, "PQspecPrepare: %s0,	PQgeterror());
		   exit(1);
	      }

	      /* create	after preparing	spec */
	      param = PQparamCreate(conn);

	      for(i=0; i < 100000; i++)
	      {
		   /* NOTE: nothing else can be	in format string */
		   PQputf(param, "@prepared_spec", 4, "text");
	      }

	      /* This elects to	prepare	a statement as well.  After this returns,
	       * "SELECT myfunc($1, $2)" will be cached	along with the prepared	spec.
	       */
	      PQspecPrepare(conn, "myfunc", "SELECT myfunc(%int4, %text)", 1);

	      /* "myfunc" tells	execf to execute "SELECT myfunc($1, $2)".  If is_stmt
	       * was set to zero during	the PQspecPrepare, the below would be invalid
	       * because execf doesn't know what to execute.
	       */
	      PQexecf(conn, "@myfunc", 123, "text");

	      /* clear'm all */
	      PQclearSpecs(conn);

RATIONALE
       None.

AUTHOR
       A  contribution	of  eSilo, LLC.	for the	PostgreSQL Database Management
       System.	Written	by Andrew Chernow.

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
       pqt-specs(3), PQgetf(3),	PQputf(3).

libpqtypes			     2011		      PQspecPrepare(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLES | RATIONALE | AUTHOR | REPORTING BUGS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PQspecPrepare&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help