doc/src/sgml/ref/close.sgml

   1 <!--
   2 doc/src/sgml/ref/close.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="sql-close">
   7  <indexterm zone="sql-close">
   8   <primary>CLOSE</primary>
   9  </indexterm>
  10
  11  <indexterm zone="sql-close">
  12   <primary>cursor</primary>
  13   <secondary>CLOSE</secondary>
  14  </indexterm>
  15
  16  <refmeta>
  17   <refentrytitle>CLOSE</refentrytitle>
  18   <manvolnum>7</manvolnum>
  19   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  20  </refmeta>
  21
  22  <refnamediv>
  23   <refname>CLOSE</refname>
  24   <refpurpose>close a cursor</refpurpose>
  25  </refnamediv>
  26
  27  <refsynopsisdiv>
  28 <synopsis>
  29 CLOSE { <replaceable class="parameter">name</replaceable> | ALL }
  30 </synopsis>
  31  </refsynopsisdiv>
  32
  33  <refsect1>
  34   <title>Description</title>
  35
  36   <para>
  37    <command>CLOSE</command> frees the resources associated with an open cursor.
  38    After the cursor is closed, no subsequent operations
  39    are allowed on it. A cursor should be closed when it is
  40    no longer needed.
  41   </para>
  42
  43   <para>
  44    Every non-holdable open cursor is implicitly closed when a
  45    transaction is terminated by <command>COMMIT</command> or
  46    <command>ROLLBACK</command>.  A holdable cursor is implicitly
  47    closed if the transaction that created it aborts via
  48    <command>ROLLBACK</command>.  If the creating transaction
  49    successfully commits, the holdable cursor remains open until an
  50    explicit <command>CLOSE</command> is executed, or the client
  51    disconnects.
  52   </para>
  53  </refsect1>
  54
  55  <refsect1>
  56   <title>Parameters</title>
  57
  58   <variablelist>
  59    <varlistentry>
  60     <term><replaceable class="parameter">name</replaceable></term>
  61     <listitem>
  62      <para>
  63       The name of an open cursor to close.
  64      </para>
  65     </listitem>
  66    </varlistentry>
  67
  68    <varlistentry>
  69     <term><literal>ALL</literal></term>
  70     <listitem>
  71      <para>
  72       Close all open cursors.
  73      </para>
  74     </listitem>
  75    </varlistentry>
  76
  77   </variablelist>
  78  </refsect1>
  79
  80  <refsect1>
  81   <title>Notes</title>
  82
  83   <para>
  84    <productname>PostgreSQL</productname> does not have an explicit
  85    <command>OPEN</command> cursor statement; a cursor is considered
  86    open when it is declared.  Use the
  87    <link linkend="sql-declare"><command>DECLARE</command></link>
  88    statement to declare a cursor.
  89   </para>
  90
  91   <para>
  92    You can see all available cursors by querying the <link
  93    linkend="view-pg-cursors"><structname>pg_cursors</structname></link> system view.
  94   </para>
  95
  96   <para>
  97    If a cursor is closed after a savepoint which is later rolled back,
  98    the <command>CLOSE</command> is not rolled back; that is, the cursor
  99    remains closed.
 100   </para>
 101  </refsect1>
 102
 103  <refsect1>
 104   <title>Examples</title>
 105
 106   <para>
 107    Close the cursor <literal>liahona</literal>:
 108 <programlisting>
 109 CLOSE liahona;
 110 </programlisting></para>
 111  </refsect1>
 112
 113  <refsect1>
 114   <title>Compatibility</title>
 115
 116   <para>
 117    <command>CLOSE</command> is fully conforming with the SQL
 118    standard. <command>CLOSE ALL</command> is a <productname>PostgreSQL</productname>
 119    extension.
 120   </para>
 121  </refsect1>
 122
 123  <refsect1>
 124   <title>See Also</title>
 125
 126   <simplelist type="inline">
 127    <member><xref linkend="sql-declare"/></member>
 128    <member><xref linkend="sql-fetch"/></member>
 129    <member><xref linkend="sql-move"/></member>
 130   </simplelist>
 131  </refsect1>
 132 </refentry>