<application>psql</application>, are not prepared to
handle binary cursors and expect data to come back in the text
format.
</para>
<note>
<para>
When the client application uses the <quote>extended query</quote> protocol
to issue a <command>FETCH</command> command, the Bind protocol message
specifies whether data is to be retrieved in text or binary format.
This choice overrides the way that the cursor is defined. The concept
of a binary cursor as such is thus obsolete when using extended query
protocol — any cursor can be treated as either text or binary.
</para>
</note>
<para>
Unless <literal>WITH HOLD</literal> is specified, the cursor
created by this command can only be used within the current
transaction. Thus, <command>DECLARE</command> without <literal>WITH
HOLD</literal> is useless outside a transaction block: the cursor would
survive only to the completion of the statement. Therefore
<productname>PostgreSQL</productname> reports an error if such a
command is used outside a transaction block.
Use
<link linkend="sql-begin"><command>BEGIN</command></link> and
<link linkend="sql-commit"><command>COMMIT</command></link>
(or <link linkend="sql-rollback"><command>ROLLBACK</command></link>)
to define a transaction block.
</para>
<para>
If <literal>WITH HOLD</literal> is specified and the transaction
that created the cursor successfully commits, the cursor can
continue to be accessed by subsequent transactions in the same
session. (But if the creating transaction is aborted, the cursor
is removed.) A cursor created with <literal>WITH HOLD</literal>
is closed when an explicit <command>CLOSE</command> command is
issued on it, or the session ends. In the current implementation,
the rows represented by a held cursor are copied into a temporary
file or memory area so that they remain available for subsequent
transactions.
</para>
<para>
<literal>WITH HOLD</literal> may not be specified when the query
includes <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>.
</para>
<para>
The <literal>SCROLL</literal> option should be specified when defining a
cursor that will be used to fetch backwards. This is required by
the SQL standard. However, for compatibility with earlier
versions, <productname>PostgreSQL</productname> will allow
backward fetches without <literal>SCROLL</literal>, if the cursor's query
plan is simple enough that no extra overhead is needed to support
it. However, application developers are advised not to rely on
using backward fetches from a cursor that has not been created
with <literal>SCROLL</literal>. If <literal>NO SCROLL</literal> is
specified, then backward fetches are disallowed in any case.
</para>
<para>
Backward fetches are also disallowed when the query
includes <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>; therefore
<literal>SCROLL</literal> may not be specified in this case.
</para>
<caution>
<para>
Scrollable cursors may give unexpected
results if they invoke any volatile functions (see <xref
linkend="xfunc-volatility"/>). When a previously fetched row is
re-fetched, the functions might be re-executed, perhaps leading to
results different from the first time. It's best to
specify <literal>NO SCROLL</literal> for a query involving volatile
functions. If that is not practical, one workaround
is to declare the cursor <literal>SCROLL WITH HOLD</literal> and commit the
transaction before reading any rows from it. This will force the
entire output of the cursor to be materialized in temporary storage,
so that volatile functions are executed exactly once for each row.
</para>
</caution>
<para>
If the cursor's query includes <literal>FOR UPDATE</literal> or <literal>FOR