← Back to branch summary

~ubuntu-branches/ubuntu/precise/postgresql-9.1/precise-security

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/man3/dblink_fetch.3
 
1
'\" t
 
2
.\"     Title: dblink_fetch
 
3
.\"    Author: The PostgreSQL Global Development Group
 
4
.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
 
5
.\"      Date: 2011-04-27
 
6
.\"    Manual: PostgreSQL 9.1beta1 Documentation
 
7
.\"    Source: PostgreSQL 9.1beta1
 
8
.\"  Language: English
 
9
.\"
 
10
.TH "DBLINK_FETCH" "3" "2011-04-27" "PostgreSQL 9.1beta1" "PostgreSQL 9.1beta1 Documentation"
 
11
.\" -----------------------------------------------------------------
 
12
.\" * set default formatting
 
13
.\" -----------------------------------------------------------------
 
14
.\" disable hyphenation
 
15
.nh
 
16
.\" disable justification (adjust text to left margin only)
 
17
.ad l
 
18
.\" -----------------------------------------------------------------
 
19
.\" * MAIN CONTENT STARTS HERE *
 
20
.\" -----------------------------------------------------------------
 
21
.SH "NAME"
 
22
dblink_fetch \- returns rows from an open cursor in a remote database
 
23
.SH "SYNOPSIS"
 
24
.sp
 
25
.nf
 
26
dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) returns setof record
 
27
dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) returns setof record
 
28
.fi
 
29
.SH "DESCRIPTION"
 
30
.PP
 
31
\fBdblink_fetch\fR
 
32
fetches rows from a cursor previously established by
 
33
\fBdblink_open\fR\&.
 
34
.SH "ARGUMENTS"
 
35
.PP
 
36
\fIconname\fR
 
37
.RS 4
 
38
Name of the connection to use; omit this parameter to use the unnamed connection\&.
 
39
.RE
 
40
.PP
 
41
\fIcursorname\fR
 
42
.RS 4
 
43
The name of the cursor to fetch from\&.
 
44
.RE
 
45
.PP
 
46
\fIhowmany\fR
 
47
.RS 4
 
48
The maximum number of rows to retrieve\&. The next
 
49
\fIhowmany\fR
 
50
rows are fetched, starting at the current cursor position, moving forward\&. Once the cursor has reached its end, no more rows are produced\&.
 
51
.RE
 
52
.PP
 
53
\fIfail_on_error\fR
 
54
.RS 4
 
55
If true (the default when omitted) then an error thrown on the remote side of the connection causes an error to also be thrown locally\&. If false, the remote error is locally reported as a NOTICE, and the function returns no rows\&.
 
56
.RE
 
57
.SH "RETURN VALUE"
 
58
.PP
 
59
The function returns the row(s) fetched from the cursor\&. To use this function, you will need to specify the expected set of columns, as previously discussed for
 
60
\fBdblink\fR\&.
 
61
.SH "NOTES"
 
62
.PP
 
63
On a mismatch between the number of return columns specified in the
 
64
FROM
 
65
clause, and the actual number of columns returned by the remote cursor, an error will be thrown\&. In this event, the remote cursor is still advanced by as many rows as it would have been if the error had not occurred\&. The same is true for any other error occurring in the local query after the remote
 
66
FETCH
 
67
has been done\&.
 
68
.SH "EXAMPLE"
 
69
.sp
 
70
.if n \{\
 
71
.RS 4
 
72
.\}
 
73
.nf
 
74
SELECT dblink_connect(\(aqdbname=postgres\(aq);
 
75
 dblink_connect
 
76
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 
77
 OK
 
78
(1 row)
 
79
 
 
80
SELECT dblink_open(\(aqfoo\(aq, \(aqselect proname, prosrc from pg_proc where proname like \(aq\(aqbytea%\(aq\(aq\(aq);
 
81
 dblink_open
 
82
\-\-\-\-\-\-\-\-\-\-\-\-\-
 
83
 OK
 
84
(1 row)
 
85
 
 
86
SELECT * FROM dblink_fetch(\(aqfoo\(aq, 5) AS (funcname name, source text);
 
87
 funcname |  source
 
88
\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-
 
89
 byteacat | byteacat
 
90
 byteacmp | byteacmp
 
91
 byteaeq  | byteaeq
 
92
 byteage  | byteage
 
93
 byteagt  | byteagt
 
94
(5 rows)
 
95
 
 
96
SELECT * FROM dblink_fetch(\(aqfoo\(aq, 5) AS (funcname name, source text);
 
97
 funcname  |  source
 
98
\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-
 
99
 byteain   | byteain
 
100
 byteale   | byteale
 
101
 bytealike | bytealike
 
102
 bytealt   | bytealt
 
103
 byteane   | byteane
 
104
(5 rows)
 
105
 
 
106
SELECT * FROM dblink_fetch(\(aqfoo\(aq, 5) AS (funcname name, source text);
 
107
  funcname  |   source
 
108
\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-
 
109
 byteanlike | byteanlike
 
110
 byteaout   | byteaout
 
111
(2 rows)
 
112
 
 
113
SELECT * FROM dblink_fetch(\(aqfoo\(aq, 5) AS (funcname name, source text);
 
114
 funcname | source
 
115
\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-
 
116
(0 rows)
 
117
.fi
 
118
.if n \{\
 
119
.RE
 
120
.\}