| PostgreSQL 8.2.15 Documentation | ||||
|---|---|---|---|---|
| Prev | Fast Backward | Fast Forward | Next | |
   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 parameters.
  
   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
   SPI_saveplan.
  
command string
number of input parameters ($1, $2, etc.)
pointer to an array containing the OIDs of the data types of the parameters
   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.