@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.27 2003/09/11 21:42:20 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.28 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation PostgreSQL documentation
--> -->
@ -44,9 +44,10 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
format. Once the information comes back in text form, the client format. Once the information comes back in text form, the client
application may need to convert it to a binary format to manipulate application may need to convert it to a binary format to manipulate
it. In addition, data in the text format is often larger in size it. In addition, data in the text format is often larger in size
than in the binary format. Binary cursors return the data in the than in the binary format. Binary cursors return the data in a
native binary representation. Nevertheless, if you intend to binary representation that may be more easily manipulated.
display the data as text anyway, retrieving it in text form will Nevertheless, if you intend to display the data as text anyway,
retrieving it in text form will
save you some effort on the client side. save you some effort on the client side.
</para> </para>
@ -54,7 +55,8 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
As an example, if a query returns a value of one from an integer column, As an example, if a query returns a value of one from an integer column,
you would get a string of <literal>1</> with a default cursor you would get a string of <literal>1</> with a default cursor
whereas with a binary cursor you would get whereas with a binary cursor you would get
a 4-byte value containing the internal representation of the value. a 4-byte field containing the internal representation of the value
(in big-endian byte order).
</para> </para>
<para> <para>
@ -64,16 +66,16 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
format. format.
</para> </para>
<para > <note >
The string representation is architecture-neutral whereas binary <para>
representation can differ between different machine architectures. When the client application uses the <quote>extended query</> protocol
<emphasis><productname>PostgreSQL</productname> does not resolv e to issue a <command>FETCH</> command, the Bind protocol messag e
byte ordering or representation issues for binary specifies whether data is to be retrieved in text or binary format.
cursors.</emphasis> Therefore, if your client machine and server This choice overrides the way that the cursor is defined. The concept
machine use different representations (e.g., of a binary cursor as such is thus obsolete when using extended query
<quote>big-endian</quote> versus <quote>little-endian</quote>), you protocol --- any cursor can be treated as either text or binary.
will probably not want your data returned in binary format. </para>
</para > </note >
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -84,8 +86,7 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
<term><replaceable class="parameter">cursorname</replaceable></term> <term><replaceable class="parameter">cursorname</replaceable></term>
<listitem> <listitem>
<para> <para>
The name of the cursor to be used in subsequent The name of the cursor to be created.
<command>FETCH</command> operations.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -192,48 +193,18 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
</para> </para>
</refsect1> </refsect1>
<refsect1>
<title>Diagnostics</title>
<variablelist>
<varlistentry>
<term><computeroutput>DECLARE CURSOR</computeroutput></term>
<listitem>
<para>
The message returned if the cursor was successfully defined.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: cursor "<replaceable class="parameter">cursorname</replaceable>" already exists</computeroutput></term>
<listitem>
<para>
This error occurs if a cursor with the same name already exists.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks</computeroutput></term>
<listitem>
<para>
This error occurs if the cursor is not declared within a
transaction block, and <literal>WITH HOLD</literal> is not
specified.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1> <refsect1>
<title>Notes</title> <title>Notes</title>
<para> <para>
If <literal>WITH HOLD</literal> is not specified, the cursor Unless <literal>WITH HOLD</literal> is specified, the cursor
created by this command can only be used within the current created by this command can only be used within the current
transaction. Use transaction. Thus, <command>DECLARE</> 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 this
command is used outside a transaction block.
Use
<xref linkend="sql-begin" endterm="sql-begin-title">, <xref linkend="sql-begin" endterm="sql-begin-title">,
<xref linkend="sql-commit" endterm="sql-commit-title"> <xref linkend="sql-commit" endterm="sql-commit-title">
and and
Tom Lane
23 years ago