Provided by: postgresql-client-8.0_8.0.7-2build1_i386 bug


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


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


       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_execute_plan.

       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_execute_plan  is  called.   This  allows the prepared command to be
       used over a wider range of situations than would  be  possible  without

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


       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


       SPI_prepare  returns a non-null pointer to an execution plan. On error,
       NULL will be returned, and SPI_result will be set to one  of  the  same
       error   codes   used   by   SPI_execute,  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.


       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.

                                  2005-01-17                     SPI_prepare()