PostgreSQL 9.6.2 Documentation
Prev | Up |  | Next

# SPI_modifytuple

## Name

SPI_modifytuple -- create a row by replacing selected fields of a given row

## Synopsis

    HeapTuple SPI_modifytuple(Relation rel, HeapTuple row, int ncols,
                              int * colnum, Datum * values, const char * nulls)

## Description

`SPI_modifytuple` creates a new row by substituting new values for selected columns, copying the original row's columns at other positions. The input row is not modified.

## Arguments

`Relation `rel``

  Used only as the source of the row descriptor for the row. (Passing a relation rather than a row descriptor is a misfeature.)

`HeapTuple `row``

  row to be modified

`int `ncols``

  number of columns to be changed

`int * `colnum``

  an array of length `ncols`, containing the numbers of the columns that are to be changed (column numbers start at 1)

`Datum * `values``

  an array of length `ncols`, containing the new values for the specified columns

`const char * `nulls``

  an array of length `ncols`, describing which new values are null

  If `nulls` is `NULL` then `SPI_modifytuple` assumes that no new values are null. Otherwise, each entry of the `nulls` array should be `' '` if the corresponding new value is non-null, or `'n'` if the corresponding new value is null. (In the latter case, the actual value in the corresponding `values` entry doesn't matter.) Note that `nulls` is not a text string, just an array: it does not need a `'\0'` terminator.

## Return Value

new row with modifications, allocated in the upper executor context; `NULL` only if `row` is `NULL`

On error, `SPI_result` is set as follows:

`SPI_ERROR_ARGUMENT`

  if `rel` is `NULL`, or if `row` is `NULL`, or if `ncols` is less than or equal to 0, or if `colnum` is `NULL`, or if `values` is `NULL`.

`SPI_ERROR_NOATTRIBUTE`

  if `colnum` contains an invalid column number (less than or equal to 0 or greater than the number of column in `row`)

Prev | Home | Next
SPI_returntuple | Up | SPI_freetuple