specification appears, it is
     query-dependent whether backward fetches will be allowed.
     <replaceable>arguments</replaceable>, if specified, is a
     comma-separated list of pairs <literal><replaceable>name</replaceable>
     <replaceable>datatype</replaceable></literal> that define names to be
     replaced by parameter values in the given query.  The actual
     values to substitute for these names will be specified later,
     when the cursor is opened.
    </para>
    <para>
     Some examples:
<programlisting>
DECLARE
    curs1 refcursor;
    curs2 CURSOR FOR SELECT * FROM tenk1;
    curs3 CURSOR (key integer) FOR SELECT * FROM tenk1 WHERE unique1 = key;
</programlisting>
     All three of these variables have the data type <type>refcursor</type>,
     but the first can be used with any query, while the second has
     a fully specified query already <firstterm>bound</firstterm> to it, and the last
     has a parameterized query bound to it.  (<literal>key</literal> will be
     replaced by an integer parameter value when the cursor is opened.)
     The variable <literal>curs1</literal>
     is said to be <firstterm>unbound</firstterm> since it is not bound to
     any particular query.
    </para>

    <para>
     The <literal>SCROLL</literal> option cannot be used when the cursor's
     query uses <literal>FOR UPDATE/SHARE</literal>.  Also, it is
     best to use <literal>NO SCROLL</literal> with a query that involves
     volatile functions.  The implementation of <literal>SCROLL</literal>
     assumes that re-reading the query's output will give consistent
     results, which a volatile function might not do.
    </para>
   </sect2>

   <sect2 id="plpgsql-cursor-opening">
    <title>Opening Cursors</title>

    <para>
     Before a cursor can be used to retrieve rows, it must be
     <firstterm>opened</firstterm>. (This is the equivalent action to the SQL
     command <link linkend="sql-declare"><command>DECLARE
     CURSOR</command></link>.)
     <application>PL/pgSQL</application> has
     three forms of the <command>OPEN</command> statement, two of which use unbound
     cursor variables while the third uses a bound cursor variable.
    </para>

    <note>
     <para>
      Bound cursor variables can also be used without explicitly opening the cursor,
      via the <command>FOR</command> statement described in
      <xref linkend="plpgsql-cursor-for-loop"/>.
      A <command>FOR</command> loop will open the cursor and then
      close it again when the loop completes.
     </para>
    </note>

    <indexterm>
     <primary>portal</primary>
     <secondary>in PL/pgSQL</secondary>
    </indexterm>

    <para>
     Opening a cursor involves creating a server-internal data structure
     called a <firstterm>portal</firstterm>, which holds the execution
     state for the cursor's query.  A portal has a name, which must be
     unique within the session for the duration of the portal's existence.
     By default, <application>PL/pgSQL</application> will assign a unique
     name to each portal it creates.  However, if you assign a non-null
     string value to a cursor variable, that string will be used as its
     portal name.  This feature can be used as described in
     <xref linkend="plpgsql-cursor-returning"/>.
    </para>

    <sect3 id="plpgsql-cursor-opening-open-for-query">
     <title><command>OPEN FOR</command> <replaceable>query</replaceable></title>

<synopsis>
OPEN <replaceable>unbound_cursorvar</replaceable> <optional> <optional> NO </optional> SCROLL </optional> FOR <replaceable>query</replaceable>;
</synopsis>

       <para>
        The cursor variable is opened and given the specified query to
        execute.  The cursor cannot be open already, and it must have been
        declared as an unbound cursor variable (that is, as a simple
        <type>refcursor</type> variable).  The query must be a
        <command>SELECT</command>, or something else that returns rows
        (such as <command>EXPLAIN</command>).