.\" XXX standard disclaimer belongs here....
.\" $Header: /private/postgres/ref/postquel/RCS/retrieve,v 1.10 1992/07/31 17:01:40 mer Exp $
.SP RETRIEVE COMMANDS 6/14/90
.XA 2 Retrieve
.uh NAME
.lp
retrieve \*- retrieve instances from a class
.uh SYNOPSIS
.lp
.(l
\fBretrieve\fR
[ (\fBinto\fR classname [ archive_mode ] | \fBportal\fR portal_name ) | \fBiportal\fR portal_name ]
    [\fBunique\fR]
    \fB(\fR [ attr_name1 \fB=\fR] expression1 {\fB,\fR [attr_name-i \fB=\fR] expression-i} \fB)\fR
    [ \fBfrom\fR from_list ] 
    [ \fBwhere\fR qual ] 
    [ \fBsort\fR \fBby\fR attr_name\-1 [\fBusing\fR operator] { \fB,\fR attr_name-j [\fBusing\fR operator] } ]
.)l
.uh DESCRIPTION
.lp
.b Retrieve 
will get all instances which satisfy the qualification,
.i qual ,
compute the value of each element in the target list,
and either 
return them to an application program through one of two different kinds
of portals
or store them in a new class.
.lp
If
.i classname
is specified, the result of the query will be stored in a new
class with the indicated name.
If an archive specification,
.i archive_mode
of
.b light ,
.b heavy ,
or
.b none
is not specifed, then it
defaults to
.b light
archiving.
(This default may be changed at a site by the
.A DBA .)
The current user will be the owner of the new class.
The class will have attribute names as specified in the 
res_target_list.
A class with this name
owned by the user must not already exist.
The keyword 
.b all
can be used when it is desired to
retrieve all fields of a class.
.lp
If no result
.i classname
is specified, then the result of the query will be
available on the specified portal
and will not be saved.
If no portal name is specified, the blank portal is used by default.
For a portal specified with the 
.b iportal
keyword, retrieve passes data to an application without conversion to
external format.  For a portal specified with the
.b portal
keyword, retrieve passes data to an application after first converting
it to the external representation.
For the blank portal, all data is converted to external format.
Duplicate instances are not removed when the result is
displayed through a portal
unless the optional
.b unique
tag is appended, in which case the instances in the res_target_list
are sorted according to the sort clause and duplicates are
removed before being returned.
.lp
Instances retrieved into a portal may be fetched in subsequent
queries by using the
.b fetch
command.
Since the results of a
.b "retrieve portal"
span queries,
.b "retrieve portal"
may only be executed inside of a
\fBbegin\fP/\fBend\fP
transaction block.
Attempts to use named portals outside of a transaction
block will result in a warning message from the parser,
and the query will be discarded.
.lp
The
.b sort
clause allows a user to specify that he wishes the instances sorted
according to the corresponding operator.
This operator must be a binary one returning a boolean.
Multiple sort fields are allowed and are applied from left to right.
.uh EXAMPLE
.lp
.nf
.ft C
/* Find all employees who make more than their manager */

retrieve (e.name)
   from e, m in emp
   where e.mgr = m.name
   and e.sal > m.sal

/*
 * Retrieve all fields for those employees who make
 * more than the average salary
 */

retrieve into avgsal(ave = float8ave {emp.sal}) \eg

retrieve (e.all)
   from e in emp
   where e.sal > avgsal.ave \eg

/* retrieve employees's names sorted */

retrieve unique (emp.name)
   sort by name using <

/* retrieve all employees's names that were valid on 1/7/85 
   in sorted order */

retrieve (e.name)
   from e in emp["January 7 1985"]
   sort by name using <

/* construct a new class, raise, containing 1.1 */
/* times all employee's salaries                */

retrieve into raise (salary = 1.1 * emp.salary)

/* do a retrieve into a portal */
begin \eg
   retrieve portal myportal (pg_user.all) \eg
   fetch 2 in myportal \eg
   fetch all in myportal \eg
   close myportal \eg
end \eg
.ft
.uh "SEE ALSO"
.lp
postquel(commands),
fetch(commands),
close(commands),
create(commands).
.uh BUGS
.lp
.q "Retrieve into"
does not delete duplicates in Version \*(PV.
.lp
.q Archive_mode 
is not implemented in Version \*(PV.
.lp
If the backend crashes in the course of executing a 
.q "Retrieve into,"
the class file will remain on disk.  It can be safely removed by the
database DBA, but a subsequent 
.b retrieve
.b into
to the same name will fail with a cryptic error message about "BlockExtend".
A solution to this problem is being investigated and will be released in
later version.
.lp
.q "Retrieve iportal"
returns data in an architecture dependent format, namely that of the
server on which the backend is running.  A standard data format should
be adopted, most likely XDR.  At that point, there will be no need to
distinguish among external and internal data.
.lp
Aggregate functions must appear in the target list.
