.\" XXX standard disclaimer belongs here....
.\" $Header: RCS/fetch,v 1.3 91/08/16 00:53:27 mao Exp $
.SP FETCH COMMANDS 6/14/90
.XA 2 Fetch
.uh NAME
.lp
fetch \*- fetch instance(s) from a portal 
.uh SYNOPSIS
.lp
.b fetch
[ (
.b forward
|
.b backward
) ] [ ( number |
.b all
) ] [
.b in
portal_name
]
.uh DESCRIPTION
.lp
.b Fetch
allows a user to retrieve instances from a portal named
.i portal_name .
The number of instances retrieved is specified by
.i number .
If the number of instances remaining in the portal is less than
.i number ,
then only those available are fetched.
Substituting the keyword
.b all
in place of a number will cause all remaining instances in the portal
to be retrieved.
Instances may be fetched in both
.i forward
and
.i backward
directions.
The default direction is 
.i forward .
.lp
Updating data in a portal is not supported by \*(PP,
because mapping portal updates back to base classes is impossible
in general as with view updates.
Consequently, users must issue
explicit replace commands to update data.
.lp
Portals may only be used inside of
\fBbegin\fP/\fBend\fP transaction blocks,
since the data that they store spans multiple user queries.
.uh EXAMPLE
.lp
.nf
/* set up and use a portal */
   begin
   retrieve portal myportal (pg_user.all)
   fetch 2 in myportal
   fetch all in myportal
   close myportal
   end

/* Fetch all the instances available in the portal FOO */
   fetch all in FOO
	
/* Fetch 5 instances backward in the portal FOO */
   fetch backward 5 in FOO
.fi
.uh "SEE ALSO"
.lp
retrieve(commands),
close(commands),
move(commands).
.uh BUGS
.lp
Currently, the smallest transaction in POSTGRES is a single
POSTQUEL command.  It should be possible for a single fetch to be a transaction.
