.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Ace::Iterator 3pm"
.TH Ace::Iterator 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Ace::Iterator \- Iterate Across an ACEDB Query
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Ace;
\&    $db = Ace\->connect(\-host => \*(Aqbeta.crbm.cnrs\-mop.fr\*(Aq,
\&                       \-port => 20000100);
\&
\&    $i  = $db\->fetch_many(Sequence=>\*(Aq*\*(Aq);  # fetch a cursor
\&    while ($obj = $i\->next) {
\&       print $obj\->asTable;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Ace::Iterator class implements a persistent query on an Ace
database.  You can create multiple simultaneous queries and retrieve
objects from each one independently of the others.  This is useful
when a query is expected to return more objects than can easily fit
into memory.  The iterator is essentially a database \*(L"cursor.\*(R"
.SS "\fBnew()\fP Method"
.IX Subsection "new() Method"
.Vb 4
\&  $iterator = Ace::Iterator\->new(\-db        => $db,
\&                                 \-query     => $query,
\&                                 \-filled    => $filled,
\&                                 \-chunksize => $chunksize);
.Ve
.PP
An Ace::Iterator is returned by the Ace accessor's object's
\&\fBfetch_many()\fR method. You usually will not have cause to call the \fBnew()\fR
method directly.  If you do so, the parameters are as follows:
.IP "\-db" 4
.IX Item "-db"
The Ace database accessor object to use.
.IP "\-query" 4
.IX Item "-query"
A query, written in Ace query language, to pass to the database.  This
query should return a list of objects.
.IP "\-filled" 4
.IX Item "-filled"
If true, then retrieve complete objects from the database, rather than
empty object stubs.  Retrieving filled objects uses more memory and
network bandwidth than retrieving unfilled objects, but it's
recommended if you know in advance that you will be accessing most or
all of the objects' fields, for example, for the purposes of
displaying the objects.
.IP "\-chunksize" 4
.IX Item "-chunksize"
The iterator will fetch objects from the database in chunks controlled
by this argument.  The default is 40.  You may want to tune the
chunksize to optimize the retrieval for your application.
.SS "\fBnext()\fP method"
.IX Subsection "next() method"
.Vb 1
\&  $object = $iterator\->next;
.Ve
.PP
This method retrieves the next object from the query, performing
whatever database accesses it needs.  After the last object has been
fetched, the \fBnext()\fR will return undef.  Usually you will call \fBnext()\fR
inside a loop like this:
.PP
.Vb 3
\&  while (my $object = $iterator\->next) {
\&     # do something with $object
\&  }
.Ve
.PP
Because of the way that object caching works, \fBnext()\fR will be most
efficient if you are only looping over one iterator at a time.
Although parallel access will work correctly, it will be less
efficient than serial access.  If possible, avoid this type of code:
.PP
.Vb 6
\&  my $iterator1 = $db\->fetch_many(\-query=>$query1);
\&  my $iterator2 = $db\->fetch_many(\-query=>$query2);
\&  do {
\&     my $object1 = $iterator1\->next;
\&     my $object2 = $iterator2\->next;
\&  } while $object1 && $object2;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Ace, Ace::Model, Ace::Object
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lstein@cshl.org> with extensive help from Jean
Thierry-Mieg <mieg@kaa.crbm.cnrs\-mop.fr>
.PP
Copyright (c) 1997\-1998 Cold Spring Harbor Laboratory
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.  See \s-1DISCLAIMER\s0.txt for
disclaimers of warranty.