.\" XXX standard disclaimer belongs here....
.\" $Header: RCS/retrieve,v 1.5 91/08/16 02:59:24 kemnitz Exp $
.SP RETRIEVE COMMANDS 6/14/90
.XA 2 Retrieve
.uh NAME
.lp
retrieve \*- retrieve instances from a class
.uh SYNTAX
.lp
.b retrieve \c
[ (
.b into
classname [ archive_mode ]
|
.b portal
portal_name ) ]
.br
[
.b unique
]
.b (
[ attr_name1
.b =
] expression1 {
.b ,
[
.r attr_name \c
.i i
.b =
]
.r expression \c
.i i
}
.b )
.br
[
.b from
from_list ] 
.br
[
.b where
qual ] 
.br
[
.b "sort"
.b by
attr_name\-1
[
.b using
operator
] {
.b ,
.r attr_name\- \c
.i j
[
.b using
operator ] }
]
.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 a portal
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 named portals, retrieve passes data to an application
without conversion to external format.
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
/* 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 temp (e.all)
   from e in emp
   where e.sal > avg {emp.salary}

/* 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[\*(lqJanuary 7 1985\*(rq]
   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
   retrieve portal myportal (pg_user.all)
   fetch 2 from myportal
   fetch all from myportal
   close myportal
   end

.uh "SEE ALSO"
.lp
postquel(postquel),
fetch(postquel),
close(postquel),
create(commands).
.uh BUGS
.lp
.q "Retrieve into"
does not delete duplicates in Version 3.0.
.lp
.q Archive_mode 
is not implemented in Version 3.0.
.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
Version 4.
