← Back to branch summary

~ubuntu-branches/debian/sid/postgresql-9.3/sid

« back to all changes in this revision

Viewing changes to doc/src/sgml/man3/SPI_cursor_open.3

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2013-05-08 05:39:52 UTC
  • Revision ID: package-import@ubuntu.com-20130508053952-1j7uilp7mjtrvq8q
Tags: upstream-9.3~beta1
Import upstream version 9.3~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/man3/SPI_cursor_open.3
 
1
'\" t
 
2
.\"     Title: SPI_cursor_open
 
3
.\"    Author: The PostgreSQL Global Development Group
 
4
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
 
5
.\"      Date: 2013-05-06
 
6
.\"    Manual: PostgreSQL 9.3beta1 Documentation
 
7
.\"    Source: PostgreSQL 9.3beta1
 
8
.\"  Language: English
 
9
.\"
 
10
.TH "SPI_CURSOR_OPEN" "3" "2013-05-06" "PostgreSQL 9.3beta1" "PostgreSQL 9.3beta1 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
.\" SPI_cursor_open
 
33
.SH "SYNOPSIS"
 
34
.sp
 
35
.nf
 
36
Portal SPI_cursor_open(const char * \fIname\fR, SPIPlanPtr \fIplan\fR,
 
37
                       Datum * \fIvalues\fR, const char * \fInulls\fR,
 
38
                       bool \fIread_only\fR)
 
39
.fi
 
40
.SH "DESCRIPTION"
 
41
.PP
 
42
 
 
43
\fBSPI_cursor_open\fR
 
44
sets up a cursor (internally, a portal) that will execute a statement prepared by
 
45
\fBSPI_prepare\fR\&. The parameters have the same meanings as the corresponding parameters to
 
46
\fBSPI_execute_plan\fR\&.
 
47
.PP
 
48
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 procedure (it can, in fact, live to the end of the current transaction)\&. Returning the portal name to the procedure\*(Aqs caller provides a way of returning a row set as result\&.
 
49
.PP
 
50
The passed\-in parameter data will be copied into the cursor\*(Aqs portal, so it can be freed while the cursor still exists\&.
 
51
.SH "ARGUMENTS"
 
52
.PP
 
53
const char * \fIname\fR
 
54
.RS 4
 
55
name for portal, or
 
56
NULL
 
57
to let the system select a name
 
58
.RE
 
59
.PP
 
60
SPIPlanPtr \fIplan\fR
 
61
.RS 4
 
62
prepared statement (returned by
 
63
\fBSPI_prepare\fR)
 
64
.RE
 
65
.PP
 
66
Datum * \fIvalues\fR
 
67
.RS 4
 
68
An array of actual parameter values\&. Must have same length as the statement\*(Aqs number of arguments\&.
 
69
.RE
 
70
.PP
 
71
const char * \fInulls\fR
 
72
.RS 4
 
73
An array describing which parameters are null\&. Must have same length as the statement\*(Aqs number of arguments\&.
 
74
.sp
 
75
If
 
76
\fInulls\fR
 
77
is
 
78
NULL
 
79
then
 
80
\fBSPI_cursor_open\fR
 
81
assumes that no parameters are null\&. Otherwise, each entry of the
 
82
\fInulls\fR
 
83
array should be
 
84
\*(Aq\ \&\*(Aq
 
85
if the corresponding parameter value is non\-null, or
 
86
\*(Aqn\*(Aq
 
87
if the corresponding parameter value is null\&. (In the latter case, the actual value in the corresponding
 
88
\fIvalues\fR
 
89
entry doesn\*(Aqt matter\&.) Note that
 
90
\fInulls\fR
 
91
is not a text string, just an array: it does not need a
 
92
\*(Aq\e0\*(Aq
 
93
terminator\&.
 
94
.RE
 
95
.PP
 
96
bool \fIread_only\fR
 
97
.RS 4
 
98
true
 
99
for read\-only execution
 
100
.RE
 
101
.SH "RETURN VALUE"
 
102
.PP
 
103
Pointer to portal containing the cursor\&. Note there is no error return convention; any error will be reported via
 
104
\fBelog\fR\&.