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

NAME

6       Ace - Object-Oriented Access to ACEDB Databases
7

SYNOPSIS

9           use Ace;
10           # open a remote database connection
11           $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
12                              -port => 20000100);
13
14           # open a local database connection
15           $local = Ace->connect(-path=>'~acedb/my_ace');
16
17           # simple queries
18           $sequence  = $db->fetch(Sequence => 'D12345');
19           $count     = $db->count(Sequence => 'D*');
20           @sequences = $db->fetch(Sequence => 'D*');
21           $i         = $db->fetch_many(Sequence=>'*');  # fetch a cursor
22           while ($obj = $i->next) {
23              print $obj->asTable;
24           }
25
26           # complex queries
27           $query = <<END;
28           find Annotation Ready_for_submission ; follow gene ;
29           follow derived_sequence ; >DNA
30           END
31           @ready_dnas= $db->fetch(-query=>$query);
32
33           $ready = $db->fetch_many(-query=>$query);
34           while ($obj = $ready->next) {
35               # do something with obj
36           }
37
38           # database cut and paste
39           $sequence = $db->fetch(Sequence => 'D12345');
40           $local_db->put($sequence);
41           @sequences = $db->fetch(Sequence => 'D*');
42           $local_db->put(@sequences);
43
44           # Get errors
45           print Ace->error;
46           print $db->error;
47

DESCRIPTION

49       AcePerl provides an interface to the ACEDB object-oriented database.
50       Both read and write access is provided, and ACE objects are returned as
51       similarly-structured Perl objects.  Multiple databases can be opened
52       simultaneously.
53
54       You will interact with several Perl classes: Ace, Ace::Object,
55       Ace::Iterator, Ace::Model.  Ace is the database accessor, and can be
56       used to open both remote Ace databases (running aceserver or
57       gifaceserver), and local ones.
58
59       Ace::Object is the superclass for all objects returned from the
60       database.  Ace and Ace::Object are linked: if you retrieve an
61       Ace::Object from a particular database, it will store a reference to
62       the database and use it to fetch any subobjects contained within it.
63       You may make changes to the Ace::Object and have those changes written
64       into the database.  You may also create Ace::Objects from scratch and
65       store them in the database.
66
67       Ace::Iterator is a utility class that acts as a database cursor for
68       long-running ACEDB queries.  Ace::Model provides object-oriented access
69       to ACEDB's schema.
70
71       Internally, Ace uses the Ace::Local class for access to local databases
72       and Ace::AceDB for access to remote databases.  Ordinarily you will not
73       need to interact directly with either of these classes.
74

CREATING NEW DATABASE CONNECTIONS

76   connect() -- multiple argument form
77           # remote database
78           $db = Ace->connect(-host  =>  'beta.crbm.cnrs-mop.fr',
79                              -port  =>  20000100);
80
81           # local (non-server) database
82           $db = Ace->connect(-path  =>  '/usr/local/acedb);
83
84       Use Ace::connect() to establish a connection to a networked or local
85       AceDB database.  To establish a connection to an AceDB server, use the
86       -host and/or -port arguments.  For a local server, use the -port
87       argument.  The database must be up and running on the indicated host
88       and port prior to connecting to an AceDB server.  The full syntax is as
89       follows:
90
91           $db = Ace->connect(-host  =>  $host,
92                              -port  =>  $port,
93                              -path  =>  $database_path,
94                              -program     => $local_connection_program
95                              -classmapper =>  $object_class,
96                              -timeout     => $timeout,
97                              -query_timeout => $query_timeout
98                              -cache        => {cache parameters},
99                             );
100
101       The connect() method uses a named argument calling style, and
102       recognizes the following arguments:
103
104       -host, -port
105           These arguments point to the host and port of an AceDB server.
106           AcePerl will use its internal compiled code to establish a
107           connection to the server unless explicitly overridden with the
108           -program argument.
109
110       -path
111           This argument indicates the path of an AceDB directory on the local
112           system.  It should point to the directory that contains the wspec
113           subdirectory.  User name interpolations (~acedb) are OK.
114
115       -user
116           Name of user to log in as (when using socket server only).  If not
117           provided, will attempt an anonymous login.
118
119       -pass
120           Password to log in with (when using socket server).
121
122       -url
123           An Acedb URL that combines the server type, host, port, user and
124           password in a single string.  See the connect() method's "single
125           argument form" description.
126
127       -cache
128           AcePerl can use the Cache::SizeAwareFileCache module to cache
129           objects to disk. This can result in dramatically increased
130           performance in environments such as web servers in which the same
131           Acedb objects are frequently reused.  To activate this mechanism,
132           the Cache::SizeAwareFileCache module must be installed, and you
133           must pass the -cache argument during the connect() call.
134
135           The value of -cache is a hash reference containing the arguments to
136           be passed to Cache::SizeAwareFileCache.  For example:
137
138              -cache => {
139                         cache_root         => '/usr/tmp/acedb',
140                         cache_depth        => 4,
141                         default_expires_in => '1 hour'
142                         }
143
144           If not otherwise specified, the following cache parameters are
145           assumed:
146
147                  Parameter               Default Value
148                  ---------               -------------
149                  namespace               Server URL (e.g. sace://localhost:2005)
150                  cache_root              /tmp/FileCache (dependent on system temp directory)
151                  default_expires_in      1 day
152                  auto_purge_interval     12 hours
153
154           By default, the cache is not size limited (the "max_size" property
155           is set to $NO_MAX_SIZE).  To adjust the size you may consider
156           calling the Ace object's cache() method to retrieve the physical
157           cache and then calling the cache object's limit_size($max_size)
158           method from time to time.  See Cache::SizeAwareFileCache for more
159           details.
160
161       -program
162           By default AcePerl will use its internal compiled code calls to
163           establish a connection to Ace servers, and will launch a tace
164           subprocess to communicate with local Ace databases.  The -program
165           argument allows you to customize this behavior by forcing AcePerl
166           to use a local program to communicate with the database.  This
167           argument should point to an executable on your system.  You may use
168           either a complete path or a bare command name, in which case the
169           PATH environment variable will be consulted.  For example, you
170           could force AcePerl to use the aceclient program to connect to the
171           remote host by connecting this way:
172
173             $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
174                                -port => 20000100,
175                                -program=>'aceclient');
176
177       -classmapper
178           The optional -classmapper argument (alias -class) points to the
179           class you would like to return from database queries.  It is
180           provided for your use if you subclass Ace::Object.  For example, if
181           you have created a subclass of Ace::Object called
182           Ace::Object::Graphics, you can have the database return this
183           subclass by default by connecting this way:
184
185             $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
186                                -port => 20000100,
187                                -class=>'Ace::Object::Graphics');
188
189           The value of -class can be a hash reference consisting of AceDB
190           class names as keys and Perl class names as values.  If a class
191           name does not exist in the hash, a key named _DEFAULT_ will be
192           looked for.  If that does not exist, then Ace will default to
193           Ace::Object.
194
195           The value of -class can also be an object or a classname that
196           implements a class_for() method.  This method will receive three
197           arguments containing the AceDB class name, object ID and database
198           handle.  It should return a string indicating the perl class to
199           create.
200
201       -timeout
202           If no response from the server is received within $timeout seconds,
203           the call will return an undefined value.  Internally timeout sets
204           an alarm and temporarily intercepts the ALRM signal.  You should be
205           aware of this if you use ALRM for your own purposes.
206
207           NOTE: this feature is temporarily disabled (as of version 1.40)
208           because it is generating unpredictable results when used with
209           Apache/mod_perl.
210
211       -query_timeout
212           If any query takes longer than $query_timeout seconds, will return
213           an undefined value.  This value can only be set at connect time,
214           and cannot be changed once set.
215
216       If arguments are omitted, they will default to the following values:
217
218           -host          localhost
219           -port          200005;
220           -path          no default
221           -program       tace
222           -class         Ace::Object
223           -timeout       25
224           -query_timeout 120
225
226       If you prefer to use a more Smalltalk-like message-passing syntax, you
227       can open a connection this way too:
228
229         $db = connect Ace -host=>'beta.crbm.cnrs-mop.fr',-port=>20000100;
230
231       The return value is an Ace handle to use to access the database, or
232       undef if the connection fails.  If the connection fails, an error
233       message can be retrieved by calling Ace->error.
234
235       You may check the status of a connection at any time with ping().  It
236       will return a true value if the database is still connected.  Note that
237       Ace will timeout clients that have been inactive for any length of
238       time.  Long-running clients should attempt to reestablish their
239       connection if ping() returns false.
240
241           $db->ping() || die "not connected";
242
243       You may perform low-level calls using the Ace client C API by calling
244       db().  This fetches an Ace::AceDB object.  See THE LOW LEVEL C API for
245       details on using this object.
246
247           $low_level = $db->db();
248
249   connect() -- single argument form
250         $db = Ace->connect('sace://stein.cshl.org:1880')
251
252       Ace->connect() also accepts a single argument form using a URL-type
253       syntax.  The general syntax is:
254
255          protocol://hostname:port/path
256
257       The :port and /path parts are protocol-dependent as described above.
258
259       Protocols:
260
261       sace://hostname:port
262           Connect to a socket server at the indicated hostname and port.
263           Example:
264
265              sace://stein.cshl.org:1880
266
267           If not provided, the port defaults to 2005.
268
269       rpcace://hostname:port
270           Connect to an RPC server at the indicated hostname and RPC service
271           number.  Example:
272
273             rpcace://stein.cshl.org:400000
274
275           If not provided, the port defaults to 200005
276
277       tace:/path/to/database
278           Open up the local database at /path/to/database using tace.
279           Example:
280
281             tace:/~acedb/elegans
282
283       /path/to/database
284           Same as the previous.
285
286   close() Method
287       You can explicitly close a database by calling its close() method:
288
289          $db->close();
290
291       This is not ordinarily necessary because the database will be
292       automatically close when it -- and all objects retrieved from it -- go
293       out of scope.
294
295   reopen() Method
296       The ACeDB socket server can time out.  The reopen() method will ping
297       the server and if it is not answering will reopen the connection.  If
298       the database is live (or could be resurrected), this method returns
299       true.
300

RETRIEVING ACEDB OBJECTS

302       Once you have established a connection and have an Ace databaes handle,
303       several methods can be used to query the ACE database to retrieve
304       objects.  You can then explore the objects, retrieve specific fields
305       from them, or update them using the Ace::Object methods.  Please see
306       Ace::Object.
307
308   fetch() method
309           $count   = $db->fetch($class,$name_pattern);
310           $object  = $db->fetch($class,$name);
311           @objects = $db->fetch($class,$name_pattern,[$count,$offset]);
312           @objects = $db->fetch(-name=>$name_pattern,
313                                 -class=>$class
314                                 -count=>$count,
315                                 -offset=>$offset,
316                                 -fill=>$fill,
317                                 -filltag=>$tag,
318                                 -total=>\$total);
319           @objects = $db->fetch(-query=>$query);
320
321       Ace::fetch() retrieves objects from the database based on their class
322       and name.  You may retrieve a single object by requesting its name, or
323       a group of objects by fetching a name pattern.  A pattern contains one
324       or more wildcard characters, where "*" stands for zero or more
325       characters, and "?" stands for any single character.
326
327       This method behaves differently depending on whether it is called in a
328       scalar or a list context, and whether it is asked to search for a name
329       pattern or a simple name.
330
331       When called with a class and a simple name, it returns the object
332       referenced by that time, or undef, if no such object exists.  In an
333       array context, it will return an empty list.
334
335       When called with a class and a name pattern in a list context, fetch()
336       returns the list of objects that match the name.  When called with a
337       pattern in a scalar context, fetch() returns the number of objects that
338       match without actually retrieving them from the database.  Thus, it is
339       similar to count().
340
341       In the examples below, the first line of code will fetch the Sequence
342       object whose database ID is D12345.  The second line will retrieve all
343       objects matching the pattern D1234*.  The third line will return the
344       count of objects that match the same pattern.
345
346          $object =  $db->fetch(Sequence => 'D12345');
347          @objects = $db->fetch(Sequence => 'D1234*');
348          $cnt =     $db->fetch(Sequence =>'D1234*');
349
350       A variety of communications and database errors may occur while
351       processing the request.  When this happens, undef or an empty list will
352       be returned, and a string describing the error can be retrieved by
353       calling Ace->error.
354
355       When retrieving database objects, it is possible to retrieve a "filled"
356       or an "unfilled" object.  A filled object contains the entire contents
357       of the object, including all tags and subtags.  In the case of certain
358       Sequence objects, this may be a significant amount of data.  Unfilled
359       objects consist just of the object name.  They are filled in from the
360       database a little bit at a time as tags are requested.  By default,
361       fetch() returns the unfilled object.  This is usually a performance
362       win, but if you know in advance that you will be needing the full
363       contents of the retrieved object (for example, to display them in a
364       tree browser) it can be more efficient to fetch them in filled mode.
365       You do this by calling fetch() with the argument of -fill set to a true
366       value.
367
368       The -filltag argument, if provided, asks the database to fill in the
369       subtree anchored at the indicated tag.  This will improve performance
370       for frequently-accessed subtrees.  For example:
371
372          @objects = $db->fetch(-name    => 'D123*',
373                                -class   => 'Sequence',
374                                -filltag => 'Visible');
375
376       This will fetch all Sequences named D123* and fill in their Visible
377       trees in a single operation.
378
379       Other arguments in the named parameter calling form are -count, to
380       retrieve a certain maximum number of objects, and -offset, to retrieve
381       objects beginning at the indicated offset into the list.  If you want
382       to limit the number of objects returned, but wish to learn how many
383       objects might have been retrieved, pass a reference to a scalar
384       variable in the -total argument.  This will return the object count.
385       This example shows how to fetch 100 Sequence objects, starting at
386       Sequence number 500:
387
388         @some_sequences = $db->fetch('Sequence','*',100,500);
389
390       The next example uses the named argument form to fetch 100 Sequence
391       objects starting at Sequence number 500, and leave the total number of
392       Sequences in $total:
393
394         @some_sequences = $db->fetch(-class  => 'Sequence',
395                                      -count  => 100,
396                                      -offset => 500,
397                                      -total  => \$total);
398
399       Notice that if you leave out the -name argument the "*" wildcard is
400       assumed.
401
402       You may also pass an arbitrary Ace query string with the -query
403       argument.  This will supersede any name and class you provide.
404       Example:
405
406         @ready_dnas= $db->fetch(-query=>
407             'find Annotation Ready_for_submission ; follow gene ;
408              follow derived_sequence ; >DNA');
409
410       If your request is likely to retrieve very many objects, fetch() many
411       consume a lot of memory, even if -fill is false.  Consider using
412       fetch_many() instead (see below).  Also see the get() method, which is
413       equivalent to the simple two-argument form of fetch().
414
415       get() method
416              $object = $db->get($class,$name [,$fill]);
417
418           The get() method will return one and only one AceDB object
419           identified by its class and name.  The optional $fill argument can
420           be used to control how much data is retrieved from the database. If
421           $fill is absent or undefined, then the method will return a
422           lightweight "stub" object that is filled with information as
423           requested in a lazy fashion. If $fill is the number "1" then the
424           retrieved object contains all the relevant information contained
425           within the database.  Any other true value of $fill will be treated
426           as a tag name: the returned object will be prefilled with the
427           subtree to the right of that tag.
428
429           Examples:
430
431              # return lightweight stub for Author object "Sulston JE."
432              $author = $db->get(Author=>'Sulston JE');
433
434              # return heavyweight object
435              $author = $db->get(Author=>'Sulston JE',1);
436
437              # return object containing the Address subtree
438              $author = $db->get(Author=>'Sulston JE','Address');
439
440           The get() method is equivalent to this form of the fetch() method:
441
442              $object = $db->fetch($class=>$name);
443
444   aql() method
445           $count   = $db->aql($aql_query);
446           @objects = $db->aql($aql_query);
447
448       Ace::aql() will perform an AQL query on the database.  In a scalar
449       context it returns the number of rows returned.  In an array context it
450       returns a list of rows.  Each row is an anonymous array containing the
451       columns returned by the query as an Ace::Object.
452
453       If an AQL error is encountered, will return undef or an empty list and
454       set Ace->error to the error message.
455
456       Note that this routine is not optimized -- there is no iterator
457       defined.  All results are returned synchronously, leading to large
458       memory consumption for certain queries.
459
460   put() method
461          $cnt = $db->put($obj1,$obj2,$obj3);
462
463       This method will put the list of objects into the database, overwriting
464       like-named objects if they are already there.  This can be used to copy
465       an object from one database to another, provided that the models are
466       compatible.
467
468       The method returns the count of objects successfully written into the
469       database.  In case of an error, processing will stop at the last object
470       successfully written and an error message will be placed in
471       Ace->error();
472
473   parse() method
474         $object = $db->parse('data to parse');
475
476       This will parse the Ace tags contained within the "data to parse"
477       string, convert it into an object in the databse, and return the
478       resulting Ace::Object.  In case of a parse error, the undefined value
479       will be returned and a (hopefully informative) description of the error
480       will be returned by Ace->error().
481
482       For example:
483
484         $author = $db->parse(<<END);
485         Author : "Glimitz JR"
486         Full_name "Jonathan R. Glimitz"
487         Mail  "128 Boylston Street"
488         Mail  "Boston, MA"
489         Mail  "USA"
490         Laboratory GM
491         END
492
493       This method can also be used to parse several objects, but only the
494       last object successfully parsed will be returned.
495
496   parse_longtext() method
497         $object = $db->parse($title,$text);
498
499       This will parse the long text (which may contain carriage returns and
500       other funny characters) and place it into the database with the given
501       title.  In case of a parse error, the undefined value will be returned
502       and a (hopefully informative) description of the error will be returned
503       by Ace->error(); otherwise, a LongText object will be returned.
504
505       For example:
506
507         $author = $db->parse_longtext('A Novel Inhibitory Domain',<<END);
508         We have discovered a novel inhibitory domain that inhibits
509         many classes of proteases, including metallothioproteins.
510         This inhibitory domain appears in three different gene families studied
511         to date...
512         END
513
514   parse_file() method
515         @objects = $db->parse_file('/path/to/file');
516         @objects = $db->parse_file('/path/to/file',1);
517
518       This will call parse() to parse each of the objects found in the
519       indicated .ace file, returning the list of objects successfully loaded
520       into the database.
521
522       By default, parsing will stop at the first object that causes a parse
523       error.  If you wish to forge on after an error, pass a true value as
524       the second argument to this method.
525
526       Any parse error messages are accumulated in Ace->error().
527
528   new() method
529         $object = $db->new($class => $name);
530
531       This method creates a new object in the database of type $class and
532       name $name.  If successful, it returns the newly-created object.
533       Otherwise it returns undef and sets $db->error().
534
535       $name may contain sprintf()-style patterns.  If one of the patterns is
536       %d (or a variant), Acedb uses a class-specific unique numbering to
537       return a unique name.  For example:
538
539         $paper = $db->new(Paper => 'wgb%06d');
540
541       The object is created in the database atomically.  There is no chance
542       to rollback as there is in Ace::Object's object editing methods.
543
544       See also the Ace::Object->add() and replace() methods.
545
546   list() method
547           @objects = $db->list(class,pattern,[count,offset]);
548           @objects = $db->list(-class=>$class,
549                                -name=>$name_pattern,
550                                -count=>$count,
551                                -offset=>$offset);
552
553       This is a deprecated method.  Use fetch() instead.
554
555   count() method
556           $count = $db->count($class,$pattern);
557           $count = $db->count(-query=>$query);
558
559       This function queries the database for a list of objects matching the
560       specified class and pattern, and returns the object count.  For large
561       sets of objects this is much more time and memory effective than
562       fetching the entire list.
563
564       The class and name pattern are the same as the list() method above.
565
566       You may also provide a -query argument to instead specify an arbitrary
567       ACE query such as "find Author COUNT Paper > 80".  See find() below.
568
569   find() method
570           @objects = $db->find($query_string);
571           @objects = $db->find(-query => $query_string,
572                                -offset=> $offset,
573                                -count => $count
574                                -fill  => $fill);
575
576       This allows you to pass arbitrary Ace query strings to the server and
577       retrieve all objects that are returned as a result.  For example, this
578       code fragment retrieves all papers written by Jean and Danielle
579       Thierry-Mieg.
580
581           @papers = $db->find('author IS "Thierry-Mieg *" ; >Paper');
582
583       You can find the full query syntax reference guide plus multiple
584       examples at http://probe.nalusda.gov:8000/acedocs/index.html#query.
585
586       In the named parameter calling form, -count, -offset, and -fill have
587       the same meanings as in fetch().
588
589   fetch_many() method
590           $obj = $db->fetch_many($class,$pattern);
591
592           $obj = $db->fetch_many(-class=>$class,
593                                  -name =>$pattern,
594                                  -fill =>$filled,
595                                  -chunksize=>$chunksize);
596
597           $obj = $db->fetch_many(-query=>$query);
598
599       If you expect to retrieve many objects, you can fetch an iterator
600       across the data set.  This is friendly both in terms of network
601       bandwidth and memory consumption.  It is simple to use:
602
603           $i = $db->fetch_many(Sequence,'*');  # all sequences!!!!
604           while ($obj = $i->next) {
605              print $obj->asTable;
606           }
607
608       The iterator will return undef when it has finished iterating, and
609       cannot be used again.  You can have multiple iterators open at once and
610       they will operate independently of each other.
611
612       Like fetch(), fetch_many() takes an optional -fill (or -filled)
613       argument which retrieves the entire object rather than just its name.
614       This is efficient on a network with high latency if you expect to be
615       touching many parts of the object (rather than just retrieving the
616       value of a few tags).
617
618       fetch_many() retrieves objects from the database in groups of a certain
619       maximum size, 40 by default.  This can be tuned using the optional
620       -chunksize argument.  Chunksize is only a hint to the database.  It may
621       return fewer objects per transaction, particularly if the objects are
622       large.
623
624       You may provide raw Ace query string with the -query argument.  If
625       present the -name and -class arguments will be ignored.
626
627   find_many() method
628       This is an alias for fetch_many().  It is now deprecated.
629
630   keyset() method
631           @objects = $db->keyset($keyset_name);
632
633       This method returns all objects in a named keyset.  Wildcard characters
634       are accepted, in which case all keysets that match the pattern will be
635       retrieved and merged into a single list of unique objects.
636
637   grep() method
638           @objects = $db->grep($grep_string);
639           $count   = $db->grep($grep_string);
640           @objects = $db->grep(-pattern => $grep_string,
641                                -offset=> $offset,
642                                -count => $count,
643                                -fill  => $fill,
644                                -filltag => $filltag,
645                                -total => \$total,
646                                -long  => 1,
647                               );
648
649       This performs a "grep" on the database, returning all object names or
650       text that contain the indicated grep pattern.  In a scalar context this
651       call will return the number of matching objects.  In an array context,
652       the list of matching objects are retrieved.  There is also a named-
653       parameter form of the call, which allows you to specify the number of
654       objects to retrieve, the offset from the beginning of the list to
655       retrieve from, whether the retrieved objects should be filled
656       initially.  You can use -total to discover the total number of objects
657       that match, while only retrieving a portion of the list.
658
659       By default, grep uses a fast search that only examines class names and
660       lexiques.  By providing a true value to the -long parameter, you can
661       search inside LongText and other places that are not usually touched
662       on, at the expense of much more CPU time.
663
664       Due to "not listable" objects that may match during grep, the list of
665       objects one can retrieve may not always match the count.
666
667   model() method
668         $model = $db->model('Author');
669
670       This will return an Ace::Model object corresponding to the indicated
671       class.
672
673   new() method
674          $obj = $db->new($class,$name);
675          $obj = $db->new(-class=>$class,
676                          -name=>$name);
677
678       Create a new object in the database with the indicated class and name
679       and return a pointer to it.  Will return undef if the object already
680       exists in the database.  The object isn't actually written into the
681       database until you call Ace::Object::commit().
682
683   raw_query() method
684           $r = $db->raw_query('Model');
685
686       Send a command to the database and return its unprocessed output.  This
687       method is necessary to gain access to features that are not yet
688       implemented in this module, such as model browsing and complex queries.
689
690   classes() method
691          @classes = $db->classes();
692          @all_classes = $db->classes(1);
693
694       This method returns a list of all the object classes known to the
695       server.  In a list context it returns an array of class names.  In a
696       scalar context, it the number of classes defined in the database.
697
698       Ordinarily classes() will return only those classes that are exposed to
699       the user interface for browsing, the so-called "visible" classes.  Pass
700       a true argument to the call to retrieve non-visible classes as well.
701
702   class_count() method
703          %classes = $db->class_count()
704
705       This returns a hash in which the keys are the class names and the
706       values are the total number of objects in that class.  All classes are
707       returned, including invisible ones.  Use this method if you need to
708       count all classes simultaneously.  If you only want to count one or two
709       classes, it may be more efficient to call count($class_name) instead.
710
711       This method transiently uses a lot of memory.  It should not be used
712       with Ace 4.5 servers, as they contain a memory leak in the counting
713       routine.
714
715   status() method
716           %status = $db->status;
717           $status = $db->status;
718
719       Returns various bits of status information from the server.  In an
720       array context, returns a hash of hashes.  In a scalar context, returns
721       a reference to a hash of hashes.  Keys and subkeys are as follows
722
723          code
724                  program     name of acedb binary
725                  version     version of acedb binary
726                  build       build date of acedb binary in format Jan 25 2003 16:21:24
727
728          database
729                  title       name of the database
730                  version     version of the database
731                  dbformat    database format version number
732                  directory   directory in which the database is stored
733                  session     session number
734                  user        user under which server is running
735                  write       whether the server has write access
736                  address     global address - not known if this is useful
737
738          resources
739                  classes     number of classes defined
740                  keys        number of keys defined
741                  memory      amount of memory used by acedb objects (bytes)
742
743       For example, to get the program version:
744
745          my $version = $db->status->{code}{version};
746
747   title() method
748           my $title = $db->title
749
750       Returns the version of the current database, equivalent to
751       $db->status->{database}{title};
752
753   version() method
754           my $version = $db->version;
755
756       Returns the version of the current database, equivalent to
757       $db->status->{database}{version};
758
759   date_style() method
760         $style = $db->date_style();
761         $style = $db->date_style('ace');
762         $style = $db->date_style('java');
763
764       For historical reasons, AceDB can display dates using either of two
765       different formats.  The first format, which I call "ace" style, puts
766       the year first, as in "1997-10-01".  The second format, which I call
767       "java" style, puts the day first, as in "01 Oct 1997 00:00:00" (this is
768       also the style recommended for Internet dates).  The default is to use
769       the latter notation.
770
771       date_style() can be used to set or retrieve the current style.  Called
772       with no arguments, it returns the current style, which will be one of
773       "ace" or "java."  Called with an argument, it will set the style to one
774       or the other.
775
776   timestamps() method
777         $timestamps_on = $db->timestamps();
778         $db->timestamps(1);
779
780       Whenever a data object is updated, AceDB records the time and date of
781       the update, and the user ID it was running under.  Ordinarily, the
782       retrieval of timestamp information is suppressed to conserve memory and
783       bandwidth.  To turn on timestamps, call the timestamps() method with a
784       true value.  You can retrieve the current value of the setting by
785       calling the method with no arguments.
786
787       Note that activating timestamps disables some of the speed
788       optimizations in AcePerl.  Thus they should only be activated if you
789       really need the information.
790
791   auto_save()
792       Sets or queries the auto_save variable.  If true, the "save" command
793       will be issued automatically before the connection to the database is
794       severed.  The default is true.
795
796       Examples:
797
798          $db->auto_save(1);
799          $flag = $db->auto_save;
800
801   error() method
802           Ace->error;
803
804       This returns the last error message.  Like UNIX errno, this variable is
805       not reset between calls, so its contents are only valid after a method
806       call has returned a result value indicating a failure.
807
808       For your convenience, you can call error() in any of several ways:
809
810           print Ace->error();
811           print $db->error();  # $db is an Ace database handle
812           print $obj->error(); # $object is an Ace::Object
813
814       There's also a global named $Ace::Error that you are free to use.
815
816   datetime() and date()
817         $datetime = Ace->datetime($time);
818         $today    = Ace->datetime();
819         $date     = Ace->date($time);
820         $today    = Ace->date([$time]);
821
822       These convenience functions convert the UNIX timestamp given by $time
823       (seconds since the epoch) into a datetime string in the format that
824       ACEDB requires.  date() will truncate the time portion.
825
826       If not provided, $time defaults to localtime().
827

OTHER METHODS

829   debug()
830         $debug_level = Ace->debug([$new_level])
831
832       This class method gets or sets the debug level.  Higher integers
833       increase verbosity.  0 or undef turns off debug messages.
834
835   name2db()
836        $db = Ace->name2db($name [,$database])
837
838       This class method associates a database URL with an Ace database
839       object. This is used internally by the Ace::Object class in order to
840       discover what database they "belong" to.
841
842   cache()
843       Get or set the Cache::SizeAwareFileCache object, if one has been
844       created.
845
846   memory_cache_fetch()
847         $obj = $db->memory_cache_fetch($class,$name)
848
849       Given an object class and name return a copy of the object from the in-
850       memory cache.  The object will only be cached if a copy of the object
851       already exists in memory space.  This is ordinarily called internally.
852
853   memory_cache_store($obj)
854       Store an object into the memory cache.  This is ordinarily called
855       internally.
856
857   memory_cache_delete($obj)
858       Delete an object from the memory cache. This is ordinarily called
859       internally.
860
861   memory_cache_clear()
862       Completely clears the memory cache.
863
864   file_cache_fetch()
865         $obj = $db->file_cache_fetch($class,$name)
866
867       Given an object class and name return a copy of the object from the
868       file cache.  This is ordinarily called internally.
869
870   file_cache_store($obj)
871       Store an object into the file cache.  This is ordinarily called
872       internally.
873
874   file_cache_delete($obj)
875       Delete an object from the file cache.  This is ordinarily called
876       internally.
877

THE LOW LEVEL C API

879       Internally Ace.pm makes C-language calls to libace to send query
880       strings to the server and to retrieve the results.  The class that
881       exports the low-level calls is named Ace::AceDB.
882
883       The following methods are available in Ace::AceDB:
884
885       new($host,$port,$query_timeout)
886           Connect to the host $host at port $port. Queries will time out
887           after $query_timeout seconds.  If timeout is not specified, it
888           defaults to 120 (two minutes).
889
890           If successful, this call returns an Ace::AceDB connection object.
891           Otherwise, it returns undef.  Example:
892
893             $acedb = Ace::AceDB->new('localhost',200005,5)
894                      || die "Couldn't connect";
895
896           The Ace::AceDB object can also be accessed from the high-level Ace
897           interface by calling the ACE::db() method:
898
899             $db = Ace->new(-host=>'localhost',-port=>200005);
900             $acedb = $db->db();
901
902       query($request)
903           Send the query string $request to the server and return a true
904           value if successful.  You must then call read() repeatedly in order
905           to fetch the query result.
906
907       read()
908           Read the result from the last query sent to the server and return
909           it as a string.  ACE may return the result in pieces, breaking
910           between whole objects.  You may need to read repeatedly in order to
911           fetch the entire result.  Canonical example:
912
913             $acedb->query("find Sequence D*");
914             die "Got an error ",$acedb->error() if $acedb->status == STATUS_ERROR;
915             while ($acedb->status == STATUS_PENDING) {
916                $result .= $acedb->read;
917             }
918
919       status()
920           Return the status code from the last operation.  Status codes are
921           exported by default when you use Ace.pm.  The status codes you may
922           see are:
923
924             STATUS_WAITING    The server is waiting for a query.
925             STATUS_PENDING    A query has been sent and Ace is waiting for
926                               you to read() the result.
927             STATUS_ERROR      A communications or syntax error has occurred
928
929       error()
930           Returns a more detailed error code supplied by the Ace server.
931           Check this value when STATUS_ERROR has been returned.  These
932           constants are also exported by default.  Possible values:
933
934            ACE_INVALID
935            ACE_OUTOFCONTEXT
936            ACE_SYNTAXERROR
937            ACE_UNRECOGNIZED
938
939           Please see the ace client library documentation for a full
940           description of these error codes and their significance.
941
942       encore()
943           This method may return true after you have performed one or more
944           read() operations, and indicates that there is more data to read.
945           You will not ordinarily have to call this method.
946

BUGS

948       1. The ACE model should be consulted prior to updating the database.
949
950       2. There is no automatic recovery from connection errors.
951
952       3. Debugging has only one level of verbosity, despite the best of
953       intentions.
954
955       4. Performance is poor when fetching big objects, because of many
956       object references that must be created.  This could be improved.
957
958       5. When called in an array context at("tag[0]") should return the
959       current tag's entire column.  It returns the current subtree instead.
960
961       6. There is no way to add comments to objects.
962
963       7. When timestamps are active, many optimizations are disabled.
964
965       8. Item number eight is still missing.
966

SEE ALSO

968       Ace::Object, Ace::Local, Ace::Model,
969       Ace::Sequence,Ace::Sequence::Multi.
970

AUTHOR

972       Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
973       Mieg <mieg@kaa.crbm.cnrs-mop.fr>
974
975       Copyright (c) 1997-1998 Cold Spring Harbor Laboratory
976
977       This library is free software; you can redistribute it and/or modify it
978       under the same terms as Perl itself.  See DISCLAIMER.txt for
979       disclaimers of warranty.
980

POD ERRORS

982       Hey! The above document had some coding errors, which are explained
983       below:
984
985       Around line 1194:
986           '=item' outside of any '=over'
987
988       Around line 1224:
989           You forgot a '=back' before '=head2'
990
991
992
993perl v5.12.0                      2008-11-11                            Ace(3)
Impressum