<REFENTRY ID="SQL-FETCH">
<REFMETA>
<REFENTRYTITLE>
FETCH
</REFENTRYTITLE>
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>
FETCH
</REFNAME>
<REFPURPOSE>
Gets rows using a cursor
</REFPURPOSE>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-09-01</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
FETCH [ <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> ] [ <REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE> ] 
    { IN | FROM } <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
FETCH [ RELATIVE ] [ { [ <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE> | ALL | NEXT | PRIOR ] } ]
    FROM ] <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-SQL-FETCH-1">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
Inputs
</TITLE>
<PARA>

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
defines the fetch direction. It can be one
         the following:

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
FORWARD
</TERM>
<LISTITEM>
<PARA>
fetch next row(s). This is the default
 if <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> is omitted.

<VARLISTENTRY>
<TERM>
BACKWARD
</TERM>
<LISTITEM>
<PARA>
fetch previous row(s).

<VARLISTENTRY>
<TERM>
RELATIVE
</TERM>
<LISTITEM>
<PARA>
Noise word for SQL92 compatibility.

</VARIABLELIST>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
<REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE>
determines how many rows to fetch. It can be one of the following:

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A signed integer that specify how many rows to fetch.
Note that a negative integer is equivalent to changing the sense of
FORWARD and BACKWARD.

<VARLISTENTRY>
<TERM>
ALL
</TERM>
<LISTITEM>
<PARA>
Retrieve all remaining rows.

<VARLISTENTRY>
<TERM>
NEXT
</TERM>
<LISTITEM>
<PARA>
Equivalent to specifying a count of <command>1</command>.

<VARLISTENTRY>
<TERM>
PRIOR
</TERM>
<LISTITEM>
<PARA>
Equivalent to specifying a count of <command>-1</command>.

</VARIABLELIST>

<VARLISTENTRY>
<TERM>
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
An open cursor's name.

</variablelist>

</REFSECT2>

<REFSECT2 ID="R2-SQL-FETCH-2">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Outputs
</TITLE>
<PARA>
FETCH returns the results of the query defined by the specified cursor.
The following messages will be returned if the query fails:

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
NOTICE:  PerformPortalFetch: portal "<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>" not found
</TERM>
<LISTITEM>
<PARA>
If <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
 is not previously declared.
The cursor must be declared within a transaction block.

<VARLISTENTRY>
<TERM>
NOTICE:  FETCH/ABSOLUTE not supported, using RELATIVE
</TERM>
<LISTITEM>
<PARA>
<productname>Postgres</productname> does not support absolute
positioning of cursors.

<VARLISTENTRY>
<TERM>
ERROR:  FETCH/RELATIVE at current position is not supported
</TERM>
<LISTITEM>
<PARA>
<acronym>SQL92</acronym> allows one to repetatively retrieve the cursor
at its "current position" using the syntax
<programlisting>
FETCH RELATIVE 0 FROM <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
</programlisting>

<productname>Postgres</productname> does not currently support
this notion; in fact the value zero is reserved to indicate that
all rows should be retrieved and is equivalent to specifying the ALL keyword.
If the RELATIVE keyword has been used, the <productname>Postgres</productname> 
assumes that the user intended <acronym>SQL92</acronym> behavior
and returns this error message.

</variablelist>

</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-SQL-FETCH-1">
<REFSECT1INFO>
<DATE>1998-04-15</DATE>
</REFSECT1INFO>
<TITLE>
Description
</TITLE>
<PARA>
   FETCH allows a user to retrieve rows using a cursor.
   The number of rows retrieved is specified by
 <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>.
   If the number of rows remaining in the cursor is less
   than <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>,
 then only those available are fetched.
   Substituting the keyword ALL in place of a number will
   cause all remaining rows in the cursor to be retrieved.
   Instances may be fetched in both FORWARD and BACKWARD
   directions. The default direction is FORWARD.

<tip>
<para>
Negative numbers are now allowed to be specified for the
row count. A negative number is equivalent to reversing
the sense of the FORWARD and BACKWARD keywords. For example,
<command>FORWARD -1</command> is the same as <command>BACKWARD 1</command>.
</tip>

<para>
Note that the FORWARD and BACKWARD keywords are
 <productname>Postgres</productname> extensions.
The <acronym>SQL92</acronym> syntax is also supported, specified
in the second form of the command. See below for details
on compatibility issues.

<para>
   Once all rows are fetched, every other fetch access returns
   no rows.

<para>
   Updating data in a cursor is not supported by 
<productname>Postgres</productname>,
   because mapping cursor updates back to base tables is
not generally possible, as is also the case with VIEW updates.
 Consequently,
   users must issue explicit UPDATE commands to replace data.

<para>
   Cursors may only be used inside of transactions because
   the data that they store spans multiple user queries.

<REFSECT2 ID="R2-SQL-FETCH-3">
<REFSECT2INFO>
<DATE>1998-04-15</DATE>
</REFSECT2INFO>
<TITLE>
Notes
</TITLE>
<PARA>
   Refer to MOVE statements to change cursor position.
   Refer to DECLARE statements to declare a cursor.
   Refer to BEGIN WORK, COMMIT WORK, ROLLBACK WORK statements
     for further information about transactions.

</REFSECT2>

<REFSECT1 ID="R1-SQL-FETCH-2">
<TITLE>
Usage
</TITLE>
<PARA>
<ProgramListing>
   --set up and use a cursor:
   --
   BEGIN WORK;
     DECLARE liahona CURSOR
        FOR SELECT * FROM films;

   --Fetch first 5 rows in the cursor liahona:
   --
     FETCH FORWARD 5 IN liahona;

     code |title                  |did| date_prod|kind      |len
     -----+-----------------------+---+----------+----------+------
     BL101|The Third Man          |101|1949-12-23|Drama     | 01:44
     BL102|The African Queen      |101|1951-08-11|Romantic  | 01:43
     JL201|Une Femme est une Femme|102|1961-03-12|Romantic  | 01:25
     P_301|Vertigo                |103|1958-11-14|Action    | 02:08
     P_302|Becket                 |103|1964-02-03|Drama     | 02:28
 

   --Fetch previous row:
   --
     FETCH BACKWARD 1 IN liahona;

     code |title                  |did| date_prod|kind      |len
     -----+-----------------------+---+----------+----------+------
     P_301|Vertigo                |103|1958-11-14|Action    | 02:08

   -- close the cursor and commit work:
   --
     CLOSE liahona;
   COMMIT WORK;
</ProgramListing>
        
</REFSECT1>

<REFSECT1 ID="R1-SQL-FETCH-3">
<TITLE>
Compatibility
</TITLE>
<PARA>
The non-embedded use of cursors is a <productname>Postgres</productname>
extension. The syntax and usage of cursors is being compared
against the embedded form of cursors defined in <acronym>SQL92</acronym>.
</PARA>

<REFSECT2 ID="R2-SQL-FETCH-4">
<REFSECT2INFO>
<DATE>1998-09-01</DATE>
</REFSECT2INFO>
<TITLE>
SQL92
</TITLE>
<PARA>
<acronym>SQL92</acronym> allows absolute positioning of the cursor for
FETCH, and allows placing the results into explicit variables.

<synopsis>
FETCH ABSOLUTE <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
    FROM <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
    INTO :<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> [, ...]
</synopsis>

<VARIABLELIST>
<VARLISTENTRY>
<TERM>
ABSOLUTE
</TERM>
<LISTITEM>
<PARA>
The cursor should be positioned to the specified absolute
row number. All row numbers in <productname>Postgres</productname>
are relative numbers so this capability is not supported.

<VARLISTENTRY>
<TERM>
:<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Target host variable(s).

</variablelist>

</REFENTRY>

<!--
<REPLACEABLE CLASS="PARAMETER">
</REPLACEABLE>
<ReturnValue></ReturnValue>
<PARA>
</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>&bull;
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA>
</PARA>
-->
