begriffs open source - ai-pg/blob - full-docs/man3/SPI_cursor_open.3

   1 '\" t
   2 .\"     Title: SPI_cursor_open
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "SPI_CURSOR_OPEN" "3" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 SPI_cursor_open \- set up a cursor using a statement created with \fBSPI_prepare\fR
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 Portal SPI_cursor_open(const char * \fIname\fR, SPIPlanPtr \fIplan\fR,
  36                        Datum * \fIvalues\fR, const char * \fInulls\fR,
  37                        bool \fIread_only\fR)
  38 .fi
  39 .SH "DESCRIPTION"
  40 .PP
  41 \fBSPI_cursor_open\fR
  42 sets up a cursor (internally, a portal) that will execute a statement prepared by
  43 \fBSPI_prepare\fR\&. The parameters have the same meanings as the corresponding parameters to
  44 \fBSPI_execute_plan\fR\&.
  45 .PP
  46 Using a cursor instead of executing the statement directly has two benefits\&. First, the result rows can be retrieved a few at a time, avoiding memory overrun for queries that return many rows\&. Second, a portal can outlive the current C function (it can, in fact, live to the end of the current transaction)\&. Returning the portal name to the C function\*(Aqs caller provides a way of returning a row set as result\&.
  47 .PP
  48 The passed\-in parameter data will be copied into the cursor\*(Aqs portal, so it can be freed while the cursor still exists\&.
  49 .SH "ARGUMENTS"
  50 .PP
  51 const char * \fIname\fR
  52 .RS 4
  53 name for portal, or
  54 NULL
  55 to let the system select a name
  56 .RE
  57 .PP
  58 SPIPlanPtr \fIplan\fR
  59 .RS 4
  60 prepared statement (returned by
  61 \fBSPI_prepare\fR)
  62 .RE
  63 .PP
  64 Datum * \fIvalues\fR
  65 .RS 4
  66 An array of actual parameter values\&. Must have same length as the statement\*(Aqs number of arguments\&.
  67 .RE
  68 .PP
  69 const char * \fInulls\fR
  70 .RS 4
  71 An array describing which parameters are null\&. Must have same length as the statement\*(Aqs number of arguments\&.
  72 .sp
  73 If
  74 \fInulls\fR
  75 is
  76 NULL
  77 then
  78 \fBSPI_cursor_open\fR
  79 assumes that no parameters are null\&. Otherwise, each entry of the
  80 \fInulls\fR
  81 array should be
  82 \*(Aq\ \&\*(Aq
  83 if the corresponding parameter value is non\-null, or
  84 \*(Aqn\*(Aq
  85 if the corresponding parameter value is null\&. (In the latter case, the actual value in the corresponding
  86 \fIvalues\fR
  87 entry doesn\*(Aqt matter\&.) Note that
  88 \fInulls\fR
  89 is not a text string, just an array: it does not need a
  90 \*(Aq\e0\*(Aq
  91 terminator\&.
  92 .RE
  93 .PP
  94 bool \fIread_only\fR
  95 .RS 4
  96 true
  97 for read\-only execution
  98 .RE
  99 .SH "RETURN VALUE"
 100 .PP
 101 Pointer to portal containing the cursor\&. Note there is no error return convention; any error will be reported via
 102 \fBelog\fR\&.