1Ace::Iterator(3)      User Contributed Perl Documentation     Ace::Iterator(3)
2
3
4

NAME

6       Ace::Iterator - Iterate Across an ACEDB Query
7

SYNOPSIS

9           use Ace;
10           $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
11                              -port => 20000100);
12
13           $i  = $db->fetch_many(Sequence=>'*');  # fetch a cursor
14           while ($obj = $i->next) {
15              print $obj->asTable;
16           }
17

DESCRIPTION

19       The Ace::Iterator class implements a persistent query on an Ace data‐
20       base.  You can create multiple simultaneous queries and retrieve
21       objects from each one independently of the others.  This is useful when
22       a query is expected to return more objects than can easily fit into
23       memory.  The iterator is essentially a database "cursor."
24
25       new() Method
26
27         $iterator = Ace::Iterator->new(-db        => $db,
28                                        -query     => $query,
29                                        -filled    => $filled,
30                                        -chunksize => $chunksize);
31
32       An Ace::Iterator is returned by the Ace accessor's object's
33       fetch_many() method. You usually will not have cause to call the new()
34       method directly.  If you do so, the parameters are as follows:
35
36       -db The Ace database accessor object to use.
37
38       -query
39           A query, written in Ace query language, to pass to the database.
40           This query should return a list of objects.
41
42       -filled
43           If true, then retrieve complete objects from the database, rather
44           than empty object stubs.  Retrieving filled objects uses more mem‐
45           ory and network bandwidth than retrieving unfilled objects, but
46           it's recommended if you know in advance that you will be accessing
47           most or all of the objects' fields, for example, for the purposes
48           of displaying the objects.
49
50       -chunksize
51           The iterator will fetch objects from the database in chunks con‐
52           trolled by this argument.  The default is 40.  You may want to tune
53           the chunksize to optimize the retrieval for your application.
54
55       next() method
56
57         $object = $iterator->next;
58
59       This method retrieves the next object from the query, performing what‐
60       ever database accesses it needs.  After the last object has been
61       fetched, the next() will return undef.  Usually you will call next()
62       inside a loop like this:
63
64         while (my $object = $iterator->next) {
65            # do something with $object
66         }
67
68       Because of the way that object caching works, next() will be most effi‐
69       cient if you are only looping over one iterator at a time.  Although
70       parallel access will work correctly, it will be less efficient than
71       serial access.  If possible, avoid this type of code:
72
73         my $iterator1 = $db->fetch_many(-query=>$query1);
74         my $iterator2 = $db->fetch_many(-query=>$query2);
75         do {
76            my $object1 = $iterator1->next;
77            my $object2 = $iterator2->next;
78         } while $object1 && $object2;
79

SEE ALSO

81       Ace, Ace::Model, Ace::Object
82

AUTHOR

84       Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
85       Mieg <mieg@kaa.crbm.cnrs-mop.fr>
86
87       Copyright (c) 1997-1998 Cold Spring Harbor Laboratory
88
89       This library is free software; you can redistribute it and/or modify it
90       under the same terms as Perl itself.  See DISCLAIMER.txt for dis‐
91       claimers of warranty.
92
93
94
95perl v5.8.8                       2001-02-20                  Ace::Iterator(3)