---
name: "SPI_cursor_open_with_args"
section: "3"
platform: "linux"
package: "postgresql"
version: "18.6-4"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/SPI_cursor_open_with_args"
---

# SPI\_cursor\_open\_with\_args(3)

set up a cursor using a query and parameters

## NAME

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,
                                 int nargs, Oid *argtypes,
                                 Datum *values, const char *nulls,
                                 bool read_only, int cursorOptions)
```

## 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.

This function is now deprecated in favor of **SPI\_cursor\_parse\_open**, which provides equivalent functionality using a more modern API for handling query parameters.

## ARGUMENTS

const char \* *name*

name for portal, or NULL to let the system select a name

const 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 parameters

Datum \* *values*

an array of length *nargs*, containing the actual parameter values

const char \* *nulls*

an array of length *nargs*, describing which parameters are null

If *nulls* is NULL then **SPI\_cursor\_open\_with\_args** assumes that no parameters are null. Otherwise, each entry of the *nulls* 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 corresponding *values* entry doesn't matter.) Note that *nulls* is not a text string, just an array: it does not need a '\\0' terminator.

bool *read\_only*

true for read-only execution

int *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**.