doc/src/sgml/ref/close.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CLOSE">
   7  <refmeta>
   8   <refentrytitle id="SQL-CLOSE-TITLE">CLOSE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>CLOSE</refname>
  15   <refpurpose>close a cursor</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-close">
  19   <primary>CLOSE</primary>
  20  </indexterm>
  21
  22  <indexterm zone="sql-close">
  23   <primary>cursor</primary>
  24   <secondary>CLOSE</secondary>
  25  </indexterm>
  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    <xref linkend="sql-declare" endterm="sql-declare-title">
  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</></> 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>
 111   </para>
 112  </refsect1>
 113
 114  <refsect1>
 115   <title>Compatibility</title>
 116
 117   <para>
 118    <command>CLOSE</command> is fully conforming with the SQL
 119    standard. <command>CLOSE ALL</> is a <productname>PostgreSQL</>
 120    extension.
 121   </para>
 122  </refsect1>
 123
 124  <refsect1>
 125   <title>See Also</title>
 126
 127   <simplelist type="inline">
 128    <member><xref linkend="sql-declare" endterm="sql-declare-title"></member>
 129    <member><xref linkend="sql-fetch" endterm="sql-fetch-title"></member>
 130    <member><xref linkend="sql-move" endterm="sql-move-title"></member>
 131   </simplelist>
 132  </refsect1>
 133 </refentry>