aboutsummaryrefslogtreecommitdiff
path: root/doc/src/sgml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/sgml')
-rw-r--r--doc/src/sgml/catalogs.sgml132
-rw-r--r--doc/src/sgml/protocol.sgml4
-rw-r--r--doc/src/sgml/ref/close.sgml7
-rw-r--r--doc/src/sgml/ref/declare.sgml7
4 files changed, 145 insertions, 5 deletions
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index c346005bd96..aee68c2f893 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -1,6 +1,6 @@
<!--
Documentation of the system catalogs, directed toward PostgreSQL developers
- $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.117 2006/01/16 18:15:30 neilc Exp $
+ $PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.118 2006/01/18 06:49:25 neilc Exp $
-->
<chapter id="catalogs">
@@ -4360,6 +4360,11 @@
<tbody>
<row>
+ <entry><link linkend="view-pg-cursors"><structname>pg_cursors</structname></link></entry>
+ <entry>open cursors</entry>
+ </row>
+
+ <row>
<entry><link linkend="view-pg-group"><structname>pg_group</structname></link></entry>
<entry>groups of database users</entry>
</row>
@@ -4429,6 +4434,131 @@
</table>
</sect1>
+ <sect1 id="view-pg-cursors">
+ <title><structname>pg_cursors</structname></title>
+
+ <indexterm zone="view-pg-cursors">
+ <primary>pg_cursors</primary>
+ </indexterm>
+
+ <para>
+ The <structname>pg_cursors</structname> view lists the cursors that
+ are currently available. Cursors can be defined in several ways:
+ <itemizedlist>
+ <listitem>
+ <para>
+ via the <xref linkend="sql-declare" endterm="sql-declare-title">
+ statement in SQL
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ via the Bind message in the frontend/backend protocol, as
+ described in <xref linkend="protocol-flow-ext-query">
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ via the Server Programming Interface (SPI), as described in
+ <xref linkend="spi-interface">
+ </itemizedlist>
+
+ The <structname>pg_cursors</structname> view displays cursors
+ created by any of these means. Cursors only exist for the duration
+ of the transaction that defines them, unless they have been
+ declared <literal>WITH HOLD</literal>. Therefore non-holdable
+ cursors are only present in the view until the end of their
+ creating transaction.
+
+ <note>
+ <para>
+ Cursors are used internally to implement some of the components
+ of <productname>PostgreSQL</>, such as procedural languages.
+ Therefore, the <structname>pg_cursors</> view may include cursors
+ that have not been explicitly created by the user.
+ </para>
+ </note>
+ </para>
+
+ <table>
+ <title><structname>pg_cursors</> Columns</title>
+
+ <tgroup cols=4>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>References</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><structfield>name</structfield></entry>
+ <entry><type>text</type></entry>
+ <entry></entry>
+ <entry>The name of the cursor</entry>
+ </row>
+
+ <row>
+ <entry><structfield>statement</structfield></entry>
+ <entry><type>text</type></entry>
+ <entry></entry>
+ <entry>The verbatim query string submitted to declare this cursor</entry>
+ </row>
+
+ <row>
+ <entry><structfield>is_holdable</structfield></entry>
+ <entry><type>boolean</type></entry>
+ <entry></entry>
+ <entry>
+ <literal>true</literal> if the cursor is holdable (that is, it
+ can be accessed after the transaction that declared the cursor
+ has committed); <literal>false</literal> otherwise
+ </entry>
+ </row>
+
+ <row>
+ <entry><structfield>is_binary</structfield></entry>
+ <entry><type>boolean</type></entry>
+ <entry></entry>
+ <entry>
+ <literal>true</literal> if the cursor was declared
+ <literal>BINARY</literal>; <literal>false</literal>
+ otherwise
+ </entry>
+ </row>
+
+ <row>
+ <entry><structfield>is_scrollable</structfield></entry>
+ <entry><type>boolean</type></entry>
+ <entry></entry>
+ <entry>
+ <literal>true</> if the cursor is scrollable (that is, it
+ allows rows to be retrieved in a nonsequential manner);
+ <literal>false</literal> otherwise
+ </entry>
+ </row>
+
+ <row>
+ <entry><structfield>creation_time</structfield></entry>
+ <entry><type>timestamptz</type></entry>
+ <entry></entry>
+ <entry>The time at which the cursor was declared</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The <structname>pg_cursors</structname> view is read only.
+ </para>
+
+ </sect1>
+
<sect1 id="view-pg-group">
<title><structname>pg_group</structname></title>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 07c9c642c75..689460ed92f 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.62 2005/08/14 22:19:49 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.63 2006/01/18 06:49:25 neilc Exp $ -->
<chapter id="protocol">
<title>Frontend/Backend Protocol</title>
@@ -602,7 +602,7 @@
</para>
</sect2>
- <sect2>
+ <sect2 id="protocol-flow-ext-query">
<title>Extended Query</title>
<para>
diff --git a/doc/src/sgml/ref/close.sgml b/doc/src/sgml/ref/close.sgml
index 3376476e26d..35f0993e6a2 100644
--- a/doc/src/sgml/ref/close.sgml
+++ b/doc/src/sgml/ref/close.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/close.sgml,v 1.22 2005/01/04 00:39:53 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/close.sgml,v 1.23 2006/01/18 06:49:26 neilc Exp $
PostgreSQL documentation
-->
@@ -76,6 +76,11 @@ CLOSE <replaceable class="PARAMETER">name</replaceable>
<xref linkend="sql-declare" endterm="sql-declare-title">
statement to declare a cursor.
</para>
+
+ <para>
+ You can see all available cursors by querying the
+ <structname>pg_cursors</structname> system view.
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml
index 0263145927d..f43e08f970d 100644
--- a/doc/src/sgml/ref/declare.sgml
+++ b/doc/src/sgml/ref/declare.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/declare.sgml,v 1.33 2005/01/04 00:39:53 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/declare.sgml,v 1.34 2006/01/18 06:49:26 neilc Exp $
PostgreSQL documentation
-->
@@ -253,6 +253,11 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
the standard SQL cursor conventions, including those involving
<command>DECLARE</command> and <command>OPEN</command> statements.
</para>
+
+ <para>
+ You can see all available cursors by querying the
+ <structname>pg_cursors</structname> system view.
+ </para>
</refsect1>
<refsect1>