332 lines
9.4 KiB
Plaintext
332 lines
9.4 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.15 2001/12/08 03:24:35 thomas Exp $
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="SQL-DECLARE">
|
|
<refmeta>
|
|
<refentrytitle id="SQL-DECLARE-TITLE">
|
|
DECLARE
|
|
</refentrytitle>
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>
|
|
DECLARE
|
|
</refname>
|
|
<refpurpose>
|
|
define a cursor
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<refsynopsisdivinfo>
|
|
<date>1999-07-20</date>
|
|
</refsynopsisdivinfo>
|
|
<synopsis>
|
|
DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INSENSITIVE ] [ SCROLL ]
|
|
CURSOR FOR <replaceable class="parameter">query</replaceable>
|
|
[ FOR { READ ONLY | UPDATE [ OF <replaceable class="parameter">column</replaceable> [, ...] ] ]
|
|
</synopsis>
|
|
<refsect2 id="R2-SQL-DECLARE-1">
|
|
<refsect2info>
|
|
<date>1998-04-15</date>
|
|
</refsect2info>
|
|
<title>
|
|
Inputs
|
|
</title>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">cursorname</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The name of the cursor to be used in subsequent FETCH operations.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>BINARY</term>
|
|
<listitem>
|
|
<para>
|
|
Causes the cursor to fetch data in binary
|
|
rather than in text format.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>INSENSITIVE</term>
|
|
<listitem>
|
|
<para>
|
|
<acronym>SQL92</acronym> keyword indicating that data retrieved
|
|
from the cursor should be unaffected by updates from other processes or cursors.
|
|
Since cursor operations occur within transactions
|
|
in <productname>PostgreSQL</productname> this is always the case.
|
|
This keyword has no effect.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>SCROLL</term>
|
|
<listitem>
|
|
<para>
|
|
<acronym>SQL92</acronym> keyword indicating that data may be retrieved
|
|
in multiple rows per FETCH operation. Since this is allowed at all times
|
|
by <productname>PostgreSQL</productname> this keyword has no effect.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">query</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
An SQL query which will provide the rows to be governed by the
|
|
cursor.
|
|
Refer to the SELECT statement for further information about
|
|
valid arguments.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>READ ONLY</term>
|
|
<listitem>
|
|
<para>
|
|
<acronym>SQL92</acronym> keyword indicating that the cursor will be used
|
|
in a read only mode. Since this is the only cursor access mode
|
|
available in <productname>PostgreSQL</productname> this keyword has no effect.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>UPDATE</term>
|
|
<listitem>
|
|
<para>
|
|
<acronym>SQL92</acronym> keyword indicating that the cursor will be used
|
|
to update tables. Since cursor updates are not currently
|
|
supported in <productname>PostgreSQL</productname> this keyword
|
|
provokes an informational error message.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">column</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Column(s) to be updated.
|
|
Since cursor updates are not currently
|
|
supported in <productname>PostgreSQL</productname> the UPDATE clause
|
|
provokes an informational error message.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2 id="R2-SQL-DECLARE-2">
|
|
<refsect2info>
|
|
<date>1998-04-15</date>
|
|
</refsect2info>
|
|
<title>
|
|
Outputs
|
|
</title>
|
|
<para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
SELECT
|
|
</computeroutput></term>
|
|
<listitem>
|
|
<para>
|
|
The message returned if the SELECT is run successfully.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
NOTICE: Closing pre-existing portal "<replaceable class="parameter">cursorname</replaceable>"
|
|
</computeroutput></term>
|
|
<listitem>
|
|
<para>
|
|
This message is reported if the same cursor name was already declared
|
|
in the current transaction block. The previous definition is
|
|
discarded.
|
|
</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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect2>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="R1-SQL-DECLARE-1">
|
|
<refsect1info>
|
|
<date>1998-09-04</date>
|
|
</refsect1info>
|
|
<title>
|
|
Description
|
|
</title>
|
|
<para>
|
|
<command>DECLARE</command> allows a user to create cursors, which
|
|
can be used to retrieve
|
|
a small number of rows at a time out of a larger query. Cursors can
|
|
return data either in text or in binary format using
|
|
<xref linkend="sql-fetch" endterm="sql-fetch-title">.
|
|
</para>
|
|
|
|
<para>
|
|
Normal cursors return data in text format, either ASCII or another
|
|
encoding scheme depending on how the <productname>PostgreSQL</productname>
|
|
backend was built. Since
|
|
data is stored natively in binary format, the system must
|
|
do a conversion to produce the text format. In addition,
|
|
text formats are often larger in size than the corresponding binary format.
|
|
Once the information comes back in text form, the client
|
|
application may need to convert it to a binary format to
|
|
manipulate it.
|
|
BINARY cursors give you back the data in the native binary
|
|
representation.
|
|
</para>
|
|
|
|
<para>
|
|
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
|
|
whereas with a binary cursor you would get
|
|
a 4-byte value equal to control-A (<literal>^A</literal>).
|
|
</para>
|
|
|
|
<para>
|
|
BINARY cursors should be used carefully. User applications such
|
|
as <application>psql</application> are not aware of binary cursors
|
|
and expect data to come back in a text format.
|
|
</para>
|
|
|
|
<para>
|
|
String representation is architecture-neutral whereas binary
|
|
representation can differ between different machine architectures.
|
|
<emphasis><productname>PostgreSQL</productname> does not resolve
|
|
byte ordering or representation issues for binary cursors</emphasis>.
|
|
Therefore, if your client machine and server machine use different
|
|
representations (e.g., <quote>big-endian</quote> versus <quote>little-endian</quote>),
|
|
you will probably not want your data returned in
|
|
binary format.
|
|
However, binary cursors may be a
|
|
little more efficient since there is less conversion overhead in
|
|
the server to client data transfer.
|
|
|
|
<tip>
|
|
<para>
|
|
If you intend to display the data in
|
|
ASCII, getting it back in ASCII will save you some
|
|
effort on the client side.
|
|
</para>
|
|
</tip>
|
|
</para>
|
|
|
|
<refsect2 id="R2-SQL-DECLARE-3">
|
|
<refsect2info>
|
|
<date>1998-09-04</date>
|
|
</refsect2info>
|
|
<title>
|
|
Notes
|
|
</title>
|
|
|
|
<para>
|
|
Cursors are only available in transactions. Use to
|
|
<xref linkend="sql-begin" endterm="sql-begin-title">,
|
|
<xref linkend="sql-commit" endterm="sql-commit-title">
|
|
and
|
|
<xref linkend="sql-rollback" endterm="sql-rollback-title">
|
|
to define a transaction block.
|
|
</para>
|
|
|
|
<para>
|
|
In <acronym>SQL92</acronym> cursors are only available in
|
|
embedded <acronym>SQL</acronym> (<acronym>ESQL</acronym>) applications.
|
|
The <productname>PostgreSQL</productname> backend
|
|
does not implement an explicit <command>OPEN cursor</command>
|
|
statement; a cursor is considered to be open when it is declared.
|
|
However, <application>ecpg</application>, the
|
|
embedded SQL preprocessor for <productname>PostgreSQL</productname>,
|
|
supports the <acronym>SQL92</acronym> cursor conventions, including those
|
|
involving DECLARE and OPEN statements.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 id="R1-SQL-DECLARESTATEMENT-2">
|
|
<title>
|
|
Usage
|
|
</title>
|
|
<para>
|
|
To declare a cursor:
|
|
|
|
<programlisting>
|
|
DECLARE liahona CURSOR
|
|
FOR SELECT * FROM films;
|
|
</programlisting>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id="R1-SQL-DECLARESTATEMENT-3">
|
|
<title>
|
|
Compatibility
|
|
</title>
|
|
|
|
<refsect2 id="R2-SQL-DECLARESTATEMENT-4">
|
|
<refsect2info>
|
|
<date>1998-04-15</date>
|
|
</refsect2info>
|
|
<title>
|
|
SQL92
|
|
</title>
|
|
<para>
|
|
<acronym>SQL92</acronym> allows cursors only in embedded <acronym>SQL</acronym>
|
|
and in modules. <productname>PostgreSQL</productname> permits cursors to be used
|
|
interactively.
|
|
<acronym>SQL92</acronym> allows embedded or modular cursors to
|
|
update database information.
|
|
All <productname>PostgreSQL</productname> cursors are read only.
|
|
The BINARY keyword is a <productname>PostgreSQL</productname> extension.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:nil
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../reference.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:"/usr/lib/sgml/catalog"
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|