SPI_cursor_open_with_args
SPI_cursor_open_with_args — set up a cursor using a query and parameters
Synopsis
Portal SPI_cursor_open_with_args(const char *name
, const char *command
, intnargs
, Oid *argtypes
, Datum *values
, const char *nulls
, boolread_only
, intcursorOptions
)
Description
SPI_cursor_open_with_args
sets up a cursor (internally, a portal) that will execute the specified query. Most of the parameters have the same meanings as the corresponding parameters to SPI_prepare_cursor
and SPI_cursor_open
.
For one-time query execution, this function should be preferred over SPI_prepare_cursor
followed by SPI_cursor_open
. If the same command is to be executed with many different parameters, either method might be faster, depending on the cost of re-planning versus the benefit of custom plans.
The passed-in parameter data will be copied into the cursor's portal, so it can be freed while the cursor still exists.
Arguments
const char *
name
name for portal, or
NULL
to let the system select a nameconst char *
command
command string
int
nargs
number of input parameters (
$1
,$2
, etc.)Oid *
argtypes
an array of length
nargs
, containing the OIDs of the data types of the parametersDatum *
values
an array of length
nargs
, containing the actual parameter valuesconst char *
nulls
an array of length
nargs
, describing which parameters are nullIf
nulls
isNULL
thenSPI_cursor_open_with_args
assumes that no parameters are null. Otherwise, each entry of thenulls
array should be' '
if the corresponding parameter value is non-null, or'n'
if the corresponding parameter value is null. (In the latter case, the actual value in the correspondingvalues
entry doesn't matter.) Note thatnulls
is not a text string, just an array: it does not need a'\0'
terminator.bool
read_only
true
for read-only executionint
cursorOptions
integer bit mask of cursor options; zero produces default behavior
Return Value
Pointer to portal containing the cursor. Note there is no error return convention; any error will be reported via elog
.