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

   1
   2 SPI_modifytuple
   3
   4    SPI_modifytuple — create a row by replacing selected fields of a given
   5    row
   6
   7 Synopsis
   8
   9 HeapTuple SPI_modifytuple(Relation rel, HeapTuple row, int ncols,
  10                           int * colnum, Datum * values, const char * nulls)
  11
  12 Description
  13
  14    SPI_modifytuple creates a new row by substituting new values for
  15    selected columns, copying the original row's columns at other
  16    positions. The input row is not modified. The new row is returned in
  17    the upper executor context.
  18
  19    This function can only be used while connected to SPI. Otherwise, it
  20    returns NULL and sets SPI_result to SPI_ERROR_UNCONNECTED.
  21
  22 Arguments
  23
  24    Relation rel
  25           Used only as the source of the row descriptor for the row.
  26           (Passing a relation rather than a row descriptor is a
  27           misfeature.)
  28
  29    HeapTuple row
  30           row to be modified
  31
  32    int ncols
  33           number of columns to be changed
  34
  35    int * colnum
  36           an array of length ncols, containing the numbers of the columns
  37           that are to be changed (column numbers start at 1)
  38
  39    Datum * values
  40           an array of length ncols, containing the new values for the
  41           specified columns
  42
  43    const char * nulls
  44           an array of length ncols, describing which new values are null
  45
  46           If nulls is NULL then SPI_modifytuple assumes that no new values
  47           are null. Otherwise, each entry of the nulls array should be ' '
  48           if the corresponding new value is non-null, or 'n' if the
  49           corresponding new value is null. (In the latter case, the actual
  50           value in the corresponding values entry doesn't matter.) Note
  51           that nulls is not a text string, just an array: it does not need
  52           a '\0' terminator.
  53
  54 Return Value
  55
  56    new row with modifications, allocated in the upper executor context, or
  57    NULL on error (see SPI_result for an error indication)
  58
  59    On error, SPI_result is set as follows:
  60
  61    SPI_ERROR_ARGUMENT
  62           if rel is NULL, or if row is NULL, or if ncols is less than or
  63           equal to 0, or if colnum is NULL, or if values is NULL.
  64
  65    SPI_ERROR_NOATTRIBUTE
  66           if colnum contains an invalid column number (less than or equal
  67           to 0 or greater than the number of columns in row)
  68
  69    SPI_ERROR_UNCONNECTED
  70           if SPI is not active