NAME

       Ace::Iterator - Iterate Across an ACEDB Query

SYNOPSIS

           use Ace;
           $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                              -port => 20000100);

           $i  = $db->fetch_many(Sequence=>'*');  # fetch a cursor
           while ($obj = $i->next) {
              print $obj->asTable;
           }

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 "cursor."

   new() Method
         $iterator = Ace::Iterator->new(-db        => $db,
                                        -query     => $query,
                                        -filled    => $filled,
                                        -chunksize => $chunksize);

       An Ace::Iterator is returned by the Ace accessor's object's fetch_many() method. You
       usually will not have cause to call the new() method directly.  If you do so, the
       parameters are as follows:

       -db The Ace database accessor object to use.

       -query
           A query, written in Ace query language, to pass to the database.  This query should
           return a list of objects.

       -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.

       -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.

   next() method
         $object = $iterator->next;

       This method retrieves the next object from the query, performing whatever database
       accesses it needs.  After the last object has been fetched, the next() will return undef.
       Usually you will call next() inside a loop like this:

         while (my $object = $iterator->next) {
            # do something with $object
         }

       Because of the way that object caching works, next() 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:

         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;

SEE ALSO

       Ace, Ace::Model, Ace::Object

AUTHOR

       Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-Mieg
       <mieg@kaa.crbm.cnrs-mop.fr>

       Copyright (c) 1997-1998 Cold Spring Harbor Laboratory

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See DISCLAIMER.txt for disclaimers of warranty.