begriffs open source - ai-pg/blob - full-docs/txt/spi-spi-cursor-parse-open.txt

   1
   2 SPI_cursor_parse_open
   3
   4    SPI_cursor_parse_open — set up a cursor using a query string and
   5    parameters
   6
   7 Synopsis
   8
   9 Portal SPI_cursor_parse_open(const char *name,
  10                              const char *command,
  11                              const SPIParseOpenOptions * options)
  12
  13 Description
  14
  15    SPI_cursor_parse_open sets up a cursor (internally, a portal) that will
  16    execute the specified query string. This is comparable to
  17    SPI_prepare_cursor followed by SPI_cursor_open_with_paramlist, except
  18    that parameter references within the query string are handled entirely
  19    by supplying a ParamListInfo object.
  20
  21    For one-time query execution, this function should be preferred over
  22    SPI_prepare_cursor followed by SPI_cursor_open_with_paramlist. If the
  23    same command is to be executed with many different parameters, either
  24    method might be faster, depending on the cost of re-planning versus the
  25    benefit of custom plans.
  26
  27    The options->params object should normally mark each parameter with the
  28    PARAM_FLAG_CONST flag, since a one-shot plan is always used for the
  29    query.
  30
  31    The passed-in parameter data will be copied into the cursor's portal,
  32    so it can be freed while the cursor still exists.
  33
  34 Arguments
  35
  36    const char * name
  37           name for portal, or NULL to let the system select a name
  38
  39    const char * command
  40           command string
  41
  42    const SPIParseOpenOptions * options
  43           struct containing optional arguments
  44
  45    Callers should always zero out the entire options struct, then fill
  46    whichever fields they want to set. This ensures forward compatibility
  47    of code, since any fields that are added to the struct in future will
  48    be defined to behave backwards-compatibly if they are zero. The
  49    currently available options fields are:
  50
  51    ParamListInfo params
  52           data structure containing query parameter types and values; NULL
  53           if none
  54
  55    int cursorOptions
  56           integer bit mask of cursor options; zero produces default
  57           behavior
  58
  59    bool read_only
  60           true for read-only execution
  61
  62 Return Value
  63
  64    Pointer to portal containing the cursor. Note there is no error return
  65    convention; any error will be reported via elog.