File: sql-fetch.html

package info (click to toggle)
mpsql 2.1-2
links: PTS
area: non-free
in suites: potato
size: 3,528 kB
ctags: 4,886
sloc: ansic: 35,184; makefile: 3,761; sh: 44
file content (570 lines) | stat: -rw-r--r-- 9,056 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML
><HEAD
><TITLE
>FETCH</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet version 1.19"><LINK
REL="HOME"
TITLE="PostgreSQL User's Guide"
HREF="user.html"><LINK
REL="UP"
TITLE="SQL Commands"
HREF="sql-commands.html"><LINK
REL="PREVIOUS"
TITLE="EXPLAIN"
HREF="sql-explain.html"><LINK
REL="NEXT"
TITLE="GRANT"
HREF="sql-grant.html"></HEAD
><BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PostgreSQL User's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="sql-explain.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sql-grant.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
>FETCH</H1
><DIV
CLASS="REFNAMEDIV"
><H2
>Name</H2
>FETCH &#8212; Gets rows using a cursor</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><PRE
CLASS="SYNOPSIS"
>FETCH [ <TT
CLASS="REPLACEABLE"
><I
>selector</I
></TT
> ] [ <TT
CLASS="REPLACEABLE"
><I
>count</I
></TT
> ] 
    { IN | FROM } <TT
CLASS="REPLACEABLE"
><I
>cursor</I
></TT
>
FETCH [ RELATIVE ] [ { [ <TT
CLASS="REPLACEABLE"
><I
>#</I
></TT
> | ALL | NEXT | PRIOR ] } ]
    FROM ] <TT
CLASS="REPLACEABLE"
><I
>cursor</I
></TT
></PRE
><DIV
CLASS="REFSECT2"
><H3
>Inputs</H3
><P
>&#13;<P
></P
></P><DL
><DT
><TT
CLASS="REPLACEABLE"
><I
>selector</I
></TT
></DT
><DD
><P
><TT
CLASS="REPLACEABLE"
><I
>selector</I
></TT
>
defines the fetch direction. It can be one
         the following:

<P
></P
></P><DL
><DT
>FORWARD</DT
><DD
><P
>fetch next row(s). This is the default
 if <TT
CLASS="REPLACEABLE"
><I
>selector</I
></TT
> is omitted.&#13;</P
></DD
><DT
>BACKWARD</DT
><DD
><P
>fetch previous row(s).&#13;</P
></DD
><DT
>RELATIVE</DT
><DD
><P
>Noise word for SQL92 compatibility.&#13;</P
></DD
></DL
><P>&#13;</P
></DD
><DT
><TT
CLASS="REPLACEABLE"
><I
>count</I
></TT
></DT
><DD
><P
><TT
CLASS="REPLACEABLE"
><I
>count</I
></TT
>
determines how many rows to fetch. It can be one of the following:

<P
></P
></P><DL
><DT
><TT
CLASS="REPLACEABLE"
><I
>#</I
></TT
></DT
><DD
><P
>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.&#13;</P
></DD
><DT
>ALL</DT
><DD
><P
>Retrieve all remaining rows.&#13;</P
></DD
><DT
>NEXT</DT
><DD
><P
>Equivalent to specifying a count of <B
CLASS="COMMAND"
>1</B
>.&#13;</P
></DD
><DT
>PRIOR</DT
><DD
><P
>Equivalent to specifying a count of <B
CLASS="COMMAND"
>-1</B
>.&#13;</P
></DD
></DL
><P>&#13;</P
></DD
><DT
><TT
CLASS="REPLACEABLE"
><I
>cursor</I
></TT
></DT
><DD
><P
>An open cursor's name.&#13;</P
></DD
></DL
><P>&#13;</P
></DIV
><DIV
CLASS="REFSECT2"
><H3
>Outputs</H3
><P
>FETCH returns the results of the query defined by the specified cursor.
The following messages will be returned if the query fails:

<P
></P
></P><DL
><DT
>NOTICE:  PerformPortalFetch: portal "<TT
CLASS="REPLACEABLE"
><I
>cursor</I
></TT
>" not found</DT
><DD
><P
>If <TT
CLASS="REPLACEABLE"
><I
>cursor</I
></TT
>
 is not previously declared.
The cursor must be declared within a transaction block.&#13;</P
></DD
><DT
>NOTICE:  FETCH/ABSOLUTE not supported, using RELATIVE</DT
><DD
><P
><SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> does not support absolute
positioning of cursors.&#13;</P
></DD
><DT
>ERROR:  FETCH/RELATIVE at current position is not supported</DT
><DD
><P
><SPAN
CLASS="ACRONYM"
>SQL92</SPAN
> allows one to repetatively retrieve the cursor
at its "current position" using the syntax
<PRE
CLASS="PROGRAMLISTING"
>FETCH RELATIVE 0 FROM <TT
CLASS="REPLACEABLE"
><I
>cursor</I
></TT
></PRE
>

<SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> 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 <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> 
assumes that the user intended <SPAN
CLASS="ACRONYM"
>SQL92</SPAN
> behavior
and returns this error message.&#13;</P
></DD
></DL
><P>&#13;</P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><H2
>Description</H2
><P
>   FETCH allows a user to retrieve rows using a cursor.
   The number of rows retrieved is specified by
 <TT
CLASS="REPLACEABLE"
><I
>#</I
></TT
>.
   If the number of rows remaining in the cursor is less
   than <TT
CLASS="REPLACEABLE"
><I
>#</I
></TT
>,
 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.

<BLOCKQUOTE
CLASS="TIP"
><P
><B
>Tip: </B
>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,
<B
CLASS="COMMAND"
>FORWARD -1</B
> is the same as <B
CLASS="COMMAND"
>BACKWARD 1</B
>.</P
></BLOCKQUOTE
>&#13;</P
><P
>Note that the FORWARD and BACKWARD keywords are
 <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> extensions.
The <SPAN
CLASS="ACRONYM"
>SQL92</SPAN
> syntax is also supported, specified
in the second form of the command. See below for details
on compatibility issues.&#13;</P
><P
>   Once all rows are fetched, every other fetch access returns
   no rows.&#13;</P
><P
>   Updating data in a cursor is not supported by 
<SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>,
   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.&#13;</P
><P
>   Cursors may only be used inside of transactions because
   the data that they store spans multiple user queries.&#13;</P
><DIV
CLASS="REFSECT2"
><H3
>Notes</H3
><P
>   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.&#13;</P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><H2
>Usage</H2
><P
><PRE
CLASS="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;</PRE
>
        </P
></DIV
><DIV
CLASS="REFSECT1"
><H2
>Compatibility</H2
><P
>The non-embedded use of cursors is a <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>
extension. The syntax and usage of cursors is being compared
against the embedded form of cursors defined in <SPAN
CLASS="ACRONYM"
>SQL92</SPAN
>.</P
><DIV
CLASS="REFSECT2"
><H3
>SQL92</H3
><P
><SPAN
CLASS="ACRONYM"
>SQL92</SPAN
> allows absolute positioning of the cursor for
FETCH, and allows placing the results into explicit variables.

<PRE
CLASS="SYNOPSIS"
>FETCH ABSOLUTE <TT
CLASS="REPLACEABLE"
><I
>#</I
></TT
>
    FROM <TT
CLASS="REPLACEABLE"
><I
>cursor</I
></TT
>
    INTO :<TT
CLASS="REPLACEABLE"
><I
>variable</I
></TT
> [, ...]</PRE
>

<P
></P
></P><DL
><DT
>ABSOLUTE</DT
><DD
><P
>The cursor should be positioned to the specified absolute
row number. All row numbers in <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>
are relative numbers so this capability is not supported.&#13;</P
></DD
><DT
>:<TT
CLASS="REPLACEABLE"
><I
>variable</I
></TT
></DT
><DD
><P
>Target host variable(s).&#13;</P
></DD
></DL
><P>&#13;</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sql-explain.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="user.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sql-grant.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>EXPLAIN</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="sql-commands.html"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>GRANT</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>