spi_prepare

SPI_prepare()	       PostgreSQL 7.4.19 Documentation		SPI_prepare()



NAME
       SPI_prepare - prepare a plan for a command, without executing it yet


SYNOPSIS
       void * SPI_prepare(const char * command, int nargs, Oid * argtypes)


DESCRIPTION
       SPI_prepare  creates  and  returns an execution plan for the specified
       command but doesn’t execute the command.	 This function should only be
       called from a connected procedure.

       When  the  same	or a similar command is to be executed repeatedly, it
       may be advantageous to perform the planning  only  once.	  SPI_prepare
       converts	 a command string into an execution plan that can be executed
       repeatedly using SPI_execp.

       A prepared command can be generalized by writing parameters  ($1,  $2,
       etc.)  in  place	 of  what would be constants in a normal command. The
       actual values of the parameters are then specified when	SPI_execp  is
       called.	 This  allows  the  prepared  command to be used over a wider
       range of situations than would be possible without parameters.

       The plan returned by SPI_prepare can be used only in the current invo-
       cation  of the procedure since SPI_finish frees memory allocated for a
       plan.  But a plan can be saved for longer using the function SPI_save-
       plan.

ARGUMENTS
       const char * command
	      command string

       int nargs
	      number of input parameters ($1, $2, etc.)

       Oid * argtypes
	      pointer  to  an  array containing the OIDs of the data types of
	      the parameters

RETURN VALUE
       SPI_prepare returns non-null pointer to an execution plan.  On  error,
       NULL  will  be returned.	 In both cases, SPI_result will be set analo-
       gous to the value returned by SPI_exec,	except	that  it  is  set  to
       SPI_ERROR_ARGUMENT  if command is NULL, or if nargs is less than 0, or
       if nargs is greater than 0 and argtypes is NULL.

NOTES
       There is a disadvantage to using parameters: since  the	planner	 does
       not  know  the values that will be supplied for the parameters, it may
       make worse planning choices than it would make for  a  normal  command
       with all constants visible.



				  2008-01-03			SPI_prepare()