diff options
Diffstat (limited to 'doc/src/sgml')
-rw-r--r-- | doc/src/sgml/catalogs.sgml | 132 | ||||
-rw-r--r-- | doc/src/sgml/protocol.sgml | 4 | ||||
-rw-r--r-- | doc/src/sgml/ref/close.sgml | 7 | ||||
-rw-r--r-- | doc/src/sgml/ref/declare.sgml | 7 |
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> |