1Ace(3) User Contributed Perl Documentation Ace(3)
2
6 Ace - Object-Oriented Access to ACEDB Databases
7
9 use Ace;
10 # open a remote database connection
11 $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
12 -port => 20000100);
13 # open a local database connection
15 $local = Ace->connect(-path=>'~acedb/my_ace');
16 # 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 # 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 $ready = $db->fetch_many(-query=>$query);
34 while ($obj = $ready->next) {
35 # do something with obj
36 }
37 # 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 # Get errors
45 print Ace->error;
46 print $db->error;
47
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 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 giface‐
57 server), and local ones.
58 Ace::Object is the superclass for all objects returned from the data‐
60 base. Ace and Ace::Object are linked: if you retrieve an Ace::Object
61 from a particular database, it will store a reference to the database
62 and use it to fetch any subobjects contained within it. You may make
63 changes to the Ace::Object and have those changes written into the
64 database. You may also create Ace::Objects from scratch and store them
65 in the database.
66 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 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
76 connect() -- multiple argument form
77 # remote database
79 $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
80 -port => 20000100);
81 # local (non-server) database
83 $db = Ace->connect(-path => '/usr/local/acedb);
84 Use Ace::connect() to establish a connection to a networked or local
86 AceDB database. To establish a connection to an AceDB server, use the
87 -host and/or -port arguments. For a local server, use the -port argu‐
88 ment. The database must be up and running on the indicated host and
89 port prior to connecting to an AceDB server. The full syntax is as
90 follows:
91 $db = Ace->connect(-host => $host,
93 -port => $port,
94 -path => $database_path,
95 -program => $local_connection_program
96 -classmapper => $object_class,
97 -timeout => $timeout,
98 -query_timeout => $query_timeout
99 -cache => {cache parameters},
100 );
101 The connect() method uses a named argument calling style, and recog‐
103 nizes the following arguments:
104 -host, -port
106 These arguments point to the host and port of an AceDB server.
107 AcePerl will use its internal compiled code to establish a connec‐
108 tion to the server unless explicitly overridden with the -program
109 argument.
110 -path
112 This argument indicates the path of an AceDB directory on the local
113 system. It should point to the directory that contains the wspec
114 subdirectory. User name interpolations (~acedb) are OK.
115 -user
117 Name of user to log in as (when using socket server only). If not
118 provided, will attempt an anonymous login.
119 -pass
121 Password to log in with (when using socket server).
122 -url
124 An Acedb URL that combines the server type, host, port, user and
125 password in a single string. See the connect() method's "single
126 argument form" description.
127 -cache
129 AcePerl can use the Cache::SizeAwareFileCache module to cache
130 objects to disk. This can result in dramatically increased perfor‐
131 mance in environments such as web servers in which the same Acedb
132 objects are frequently reused. To activate this mechanism, the
133 Cache::SizeAwareFileCache module must be installed, and you must
134 pass the -cache argument during the connect() call.
135 The value of -cache is a hash reference containing the arguments to
137 be passed to Cache::SizeAwareFileCache. For example:
138 -cache => {
140 cache_root => '/usr/tmp/acedb',
141 cache_depth => 4,
142 default_expires_in => '1 hour'
143 }
144 If not otherwise specified, the following cache parameters are
146 assumed:
147 Parameter Default Value
149 --------- -------------
150 namespace Server URL (e.g. sace://localhost:2005)
151 cache_root /tmp/FileCache (dependent on system temp directory)
152 default_expires_in 1 day
153 auto_purge_interval 12 hours
154 By default, the cache is not size limited (the "max_size" property
156 is set to $NO_MAX_SIZE). To adjust the size you may consider call‐
157 ing the Ace object's cache() method to retrieve the physical cache
158 and then calling the cache object's limit_size($max_size) method
159 from time to time. See Cache::SizeAwareFileCache for more details.
160 -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 sub‐
164 process 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 $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
174 -port => 20000100,
175 -program=>'aceclient');
176 -classmapper
178 The optional -classmapper argument (alias -class) points to the
179 class you would like to return from database queries. It is pro‐
180 vided 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 sub‐
183 class by default by connecting this way:
184 $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
186 -port => 20000100,
187 -class=>'Ace::Object::Graphics');
188 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 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 -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 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 -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 If arguments are omitted, they will default to the following values:
217 -host localhost
219 -port 200005;
220 -path no default
221 -program tace
222 -class Ace::Object
223 -timeout 25
224 -query_timeout 120
225 If you prefer to use a more Smalltalk-like message-passing syntax, you
227 can open a connection this way too:
228 $db = connect Ace -host=>'beta.crbm.cnrs-mop.fr',-port=>20000100;
230 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 mes‐
233 sage can be retrieved by calling Ace->error.
234 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 connec‐
239 tion if ping() returns false.
240 $db->ping() ⎪⎪ die "not connected";
242 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 $low_level = $db->db();
248 connect() -- single argument form
250 $db = Ace->connect('sace://stein.cshl.org:1880')
252 Ace->connect() also accepts a single argument form using a URL-type
254 syntax. The general syntax is:
255 protocol://hostname:port/path
257 The :port and /path parts are protocol-dependent as described above.
259 Protocols:
261 sace://hostname:port
263 Connect to a socket server at the indicated hostname and port.
264 Example:
265 sace://stein.cshl.org:1880
267 If not provided, the port defaults to 2005.
269 rpcace://hostname:port
271 Connect to an RPC server at the indicated hostname and RPC service
272 number. Example:
273 rpcace://stein.cshl.org:400000
275 If not provided, the port defaults to 200005
277 tace:/path/to/database
279 Open up the local database at /path/to/database using tace. Exam‐
280 ple:
281 tace:/~acedb/elegans
283 /path/to/database
285 Same as the previous.
286 close() Method
288 You can explicitly close a database by calling its close() method:
290 $db->close();
292 This is not ordinarily necessary because the database will be automati‐
294 cally close when it -- and all objects retrieved from it -- go out of
295 scope.
296 reopen() Method
298 The ACeDB socket server can time out. The reopen() method will ping
300 the server and if it is not answering will reopen the connection. If
301 the database is live (or could be resurrected), this method returns
302 true.
303
305 Once you have established a connection and have an Ace databaes handle,
306 several methods can be used to query the ACE database to retrieve
307 objects. You can then explore the objects, retrieve specific fields
308 from them, or update them using the Ace::Object methods. Please see
309 Ace::Object.
310 fetch() method
312 $count = $db->fetch($class,$name_pattern);
314 $object = $db->fetch($class,$name);
315 @objects = $db->fetch($class,$name_pattern,[$count,$offset]);
316 @objects = $db->fetch(-name=>$name_pattern,
317 -class=>$class
318 -count=>$count,
319 -offset=>$offset,
320 -fill=>$fill,
321 -filltag=>$tag,
322 -total=>\$total);
323 @objects = $db->fetch(-query=>$query);
324 Ace::fetch() retrieves objects from the database based on their class
326 and name. You may retrieve a single object by requesting its name, or
327 a group of objects by fetching a name pattern. A pattern contains one
328 or more wildcard characters, where "*" stands for zero or more charac‐
329 ters, and "?" stands for any single character.
330 This method behaves differently depending on whether it is called in a
332 scalar or a list context, and whether it is asked to search for a name
333 pattern or a simple name.
334 When called with a class and a simple name, it returns the object ref‐
336 erenced by that time, or undef, if no such object exists. In an array
337 context, it will return an empty list.
338 When called with a class and a name pattern in a list context, fetch()
340 returns the list of objects that match the name. When called with a
341 pattern in a scalar context, fetch() returns the number of objects that
342 match without actually retrieving them from the database. Thus, it is
343 similar to count().
344 In the examples below, the first line of code will fetch the Sequence
346 object whose database ID is D12345. The second line will retrieve all
347 objects matching the pattern D1234*. The third line will return the
348 count of objects that match the same pattern.
349 $object = $db->fetch(Sequence => 'D12345');
351 @objects = $db->fetch(Sequence => 'D1234*');
352 $cnt = $db->fetch(Sequence =>'D1234*');
353 A variety of communications and database errors may occur while pro‐
355 cessing the request. When this happens, undef or an empty list will be
356 returned, and a string describing the error can be retrieved by calling
357 Ace->error.
358 When retrieving database objects, it is possible to retrieve a "filled"
360 or an "unfilled" object. A filled object contains the entire contents
361 of the object, including all tags and subtags. In the case of certain
362 Sequence objects, this may be a significant amount of data. Unfilled
363 objects consist just of the object name. They are filled in from the
364 database a little bit at a time as tags are requested. By default,
365 fetch() returns the unfilled object. This is usually a performance
366 win, but if you know in advance that you will be needing the full con‐
367 tents of the retrieved object (for example, to display them in a tree
368 browser) it can be more efficient to fetch them in filled mode. You do
369 this by calling fetch() with the argument of -fill set to a true value.
370 The -filltag argument, if provided, asks the database to fill in the
372 subtree anchored at the indicated tag. This will improve performance
373 for frequently-accessed subtrees. For example:
374 @objects = $db->fetch(-name => 'D123*',
376 -class => 'Sequence',
377 -filltag => 'Visible');
378 This will fetch all Sequences named D123* and fill in their Visible
380 trees in a single operation.
381 Other arguments in the named parameter calling form are -count, to
383 retrieve a certain maximum number of objects, and -offset, to retrieve
384 objects beginning at the indicated offset into the list. If you want
385 to limit the number of objects returned, but wish to learn how many
386 objects might have been retrieved, pass a reference to a scalar vari‐
387 able in the -total argument. This will return the object count. This
388 example shows how to fetch 100 Sequence objects, starting at Sequence
389 number 500:
390 @some_sequences = $db->fetch('Sequence','*',100,500);
392 The next example uses the named argument form to fetch 100 Sequence
394 objects starting at Sequence number 500, and leave the total number of
395 Sequences in $total:
396 @some_sequences = $db->fetch(-class => 'Sequence',
398 -count => 100,
399 -offset => 500,
400 -total => \$total);
401 Notice that if you leave out the -name argument the "*" wildcard is
403 assumed.
404 You may also pass an arbitrary Ace query string with the -query argu‐
406 ment. This will supersede any name and class you provide. Example:
407 @ready_dnas= $db->fetch(-query=>
409 'find Annotation Ready_for_submission ; follow gene ;
410 follow derived_sequence ; >DNA');
411 If your request is likely to retrieve very many objects, fetch() many
413 consume a lot of memory, even if -fill is false. Consider using
414 fetch_many() instead (see below). Also see the get() method, which is
415 equivalent to the simple two-argument form of fetch().
416
418 $object = $db->get($class,$name [,$fill]);
419The get() method will return one and only one AceDB object identified by its
421class and name. The optional $fill argument can be used to control how much
422data is retrieved from the database. If $fill is absent or undefined, then the
423method will return a lightweight "stub" object that is filled with information
424as requested in a lazy fashion. If $fill is the number "1" then the retrieved
425object contains all the relevant information contained within the database.
426Any other true value of $fill will be treated as a tag name: the returned
427object will be prefilled with the subtree to the right of that tag.
428Examples:
430 # return lightweight stub for Author object "Sulston JE."
432 $author = $db->get(Author=>'Sulston JE');
433 # return heavyweight object
435 $author = $db->get(Author=>'Sulston JE',1);
436 # return object containing the Address subtree
438 $author = $db->get(Author=>'Sulston JE','Address');
439The get() method is equivalent to this form of the fetch() method:
441 $object = $db->fetch($class=>$name);
443
445 $count = $db->aql($aql_query);
447 @objects = $db->aql($aql_query);
448
450returns the number of rows returned. In an array context it returns a list of
451rows. Each row is an anonymous array containing the columns returned by the
452query as an Ace::Object.
453If an AQL error is encountered, will return undef or an empty list and set
455Ace->error to the error message.
456Note that this routine is not optimized -- there is no iterator defined. All
458results are returned synchronously, leading to large memory consumption for
459certain queries.
460
462 $cnt = $db->put($obj1,$obj2,$obj3);
464This method will put the list of objects into the database, overwriting like-
466named objects if they are already there. This can be used to copy an object
467from one database to another, provided that the models are compatible.
468The method returns the count of objects successfully written into the data‐
470base. In case of an error, processing will stop at the last object success‐
471fully written and an error message will be placed in Ace->error();
472
474 $object = $db->parse('data to parse');
476This will parse the Ace tags contained within the "data to parse" string, con‐
478vert it into an object in the databse, and return the resulting Ace::Object.
479In case of a parse error, the undefined value will be returned and a (hope‐
480fully informative) description of the error will be returned by Ace->error().
481For example:
483 $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
492This method can also be used to parse several objects, but only the last
494object successfully parsed will be returned.
495
497 $object = $db->parse($title,$text);
499This will parse the long text (which may contain carriage returns and other
501funny characters) and place it into the database with the given title. In
502case of a parse error, the undefined value will be returned and a (hopefully
503informative) description of the error will be returned by Ace->error(); other‐
504wise, a LongText object will be returned.
505For example:
507 $author = $db->parse_longtext('A Novel Inhibitory Domain',<<END);
509 We have discovered a novel inhibitory domain that inhibits
510 many classes of proteases, including metallothioproteins.
511 This inhibitory domain appears in three different gene families studied
512 to date...
513 END
514
516 @objects = $db->parse_file('/path/to/file');
518 @objects = $db->parse_file('/path/to/file',1);
519This will call parse() to parse each of the objects found in the indicated
521.ace file, returning the list of objects successfully loaded into the data‐
522base.
523By default, parsing will stop at the first object that causes a parse error.
525If you wish to forge on after an error, pass a true value as the second argu‐
526ment to this method.
527Any parse error messages are accumulated in Ace->error().
529
531 $object = $db->new($class => $name);
533This method creates a new object in the database of type $class and name
535$name. If successful, it returns the newly-created object. Otherwise it
536returns undef and sets $db->error().
537$name may contain sprintf()-style patterns. If one of the patterns is %d (or
539a variant), Acedb uses a class-specific unique numbering to return a unique
540name. For example:
541 $paper = $db->new(Paper => 'wgb%06d');
543The object is created in the database atomically. There is no chance to roll‐
545back as there is in Ace::Object's object editing methods.
546See also the Ace::Object->add() and replace() methods.
548
550 @objects = $db->list(class,pattern,[count,offset]);
552 @objects = $db->list(-class=>$class,
553 -name=>$name_pattern,
554 -count=>$count,
555 -offset=>$offset);
556This is a deprecated method. Use fetch() instead.
558
560 $count = $db->count($class,$pattern);
562 $count = $db->count(-query=>$query);
563This function queries the database for a list of objects matching the speci‐
565fied class and pattern, and returns the object count. For large sets of
566objects this is much more time and memory effective than fetching the entire
567list.
568The class and name pattern are the same as the list() method above.
570You may also provide a -query argument to instead specify an arbitrary ACE
572query such as "find Author COUNT Paper > 80". See find() below.
573
575 @objects = $db->find($query_string);
577 @objects = $db->find(-query => $query_string,
578 -offset=> $offset,
579 -count => $count
580 -fill => $fill);
581This allows you to pass arbitrary Ace query strings to the server and retrieve
583all objects that are returned as a result. For example, this code fragment
584retrieves all papers written by Jean and Danielle Thierry-Mieg.
585 @papers = $db->find('author IS "Thierry-Mieg *" ; >Paper');
587You can find the full query syntax reference guide plus multiple examples at
589http://probe.nalusda.gov:8000/acedocs/index.html#query.
590In the named parameter calling form, -count, -offset, and -fill have the same
592meanings as in fetch().
593
595 $obj = $db->fetch_many($class,$pattern);
597 $obj = $db->fetch_many(-class=>$class,
599 -name =>$pattern,
600 -fill =>$filled,
601 -chunksize=>$chunksize);
602 $obj = $db->fetch_many(-query=>$query);
604If you expect to retrieve many objects, you can fetch an iterator across the
606data set. This is friendly both in terms of network bandwidth and memory con‐
607sumption. It is simple to use:
608 $i = $db->fetch_many(Sequence,'*'); # all sequences!!!!
610 while ($obj = $i->next) {
611 print $obj->asTable;
612 }
613The iterator will return undef when it has finished iterating, and cannot be
615used again. You can have multiple iterators open at once and they will oper‐
616ate independently of each other.
617Like fetch(), fetch_many() takes an optional -fill (or -filled) argument which
619retrieves the entire object rather than just its name. This is efficient on a
620network with high latency if you expect to be touching many parts of the
621object (rather than just retrieving the value of a few tags).
622
624mum size, 40 by default. This can be tuned using the optional -chunksize
625argument. Chunksize is only a hint to the database. It may return fewer
626objects per transaction, particularly if the objects are large.
627You may provide raw Ace query string with the -query argument. If present the
630
632This is an alias for fetch_many(). It is now deprecated.
634
636 @objects = $db->keyset($keyset_name);
638This method returns all objects in a named keyset. Wildcard characters are
640accepted, in which case all keysets that match the pattern will be retrieved
641and merged into a single list of unique objects.
642
644 @objects = $db->grep($grep_string);
646 $count = $db->grep($grep_string);
647 @objects = $db->grep(-pattern => $grep_string,
648 -offset=> $offset,
649 -count => $count,
650 -fill => $fill,
651 -filltag => $filltag,
652 -total => \$total,
653 -long => 1,
654 );
655This performs a "grep" on the database, returning all object names or text
657that contain the indicated grep pattern. In a scalar context this call will
658return the number of matching objects. In an array context, the list of
659matching objects are retrieved. There is also a named-parameter form of the
660call, which allows you to specify the number of objects to retrieve, the off‐
661set from the beginning of the list to retrieve from, whether the retrieved
662objects should be filled initially. You can use -total to discover the total
663number of objects that match, while only retrieving a portion of the list.
664By default, grep uses a fast search that only examines class names and lex‐
666iques. By providing a true value to the -long parameter, you can search
667inside LongText and other places that are not usually touched on, at the
668expense of much more CPU time.
669Due to "not listable" objects that may match during grep, the list of objects
671one can retrieve may not always match the count.
672
674 $model = $db->model('Author');
676This will return an Ace::Model object corresponding to the indicated class.
678
680 $obj = $db->new($class,$name);
682 $obj = $db->new(-class=>$class,
683 -name=>$name);
684Create a new object in the database with the indicated class and name and
686return a pointer to it. Will return undef if the object already exists in the
687database. The object isn't actually written into the database until you call
689
691 $r = $db->raw_query('Model');
693Send a command to the database and return its unprocessed output. This method
695is necessary to gain access to features that are not yet implemented in this
696module, such as model browsing and complex queries.
697
699 @classes = $db->classes();
701 @all_classes = $db->classes(1);
702This method returns a list of all the object classes known to the server. In
704a list context it returns an array of class names. In a scalar context, it
705the number of classes defined in the database.
706Ordinarily classes() will return only those classes that are exposed to the
708user interface for browsing, the so-called "visible" classes. Pass a true
709argument to the call to retrieve non-visible classes as well.
710
712 %classes = $db->class_count()
714This returns a hash in which the keys are the class names and the values are
716the total number of objects in that class. All classes are returned, includ‐
717ing invisible ones. Use this method if you need to count all classes simulta‐
718neously. If you only want to count one or two classes, it may be more effi‐
719cient to call count($class_name) instead.
720This method transiently uses a lot of memory. It should not be used with Ace
7224.5 servers, as they contain a memory leak in the counting routine.
723
725 %status = $db->status;
727 $status = $db->status;
728Returns various bits of status information from the server. In an array con‐
730text, returns a hash of hashes. In a scalar context, returns a reference to a
731hash of hashes. Keys and subkeys are as follows
732 code
734 program name of acedb binary
735 version version of acedb binary
736 build build date of acedb binary in format Jan 25 2003 16:21:24
737 database
739 title name of the database
740 version version of the database
741 dbformat database format version number
742 directory directory in which the database is stored
743 session session number
744 user user under which server is running
745 write whether the server has write access
746 address global address - not known if this is useful
747 resources
749 classes number of classes defined
750 keys number of keys defined
751 memory amount of memory used by acedb objects (bytes)
752For example, to get the program version:
754 my $version = $db->status->{code}{version};
756
758 my $title = $db->title
760Returns the version of the current database, equivalent to $db->status->{data‐
762base}{title};
763
765 my $version = $db->version;
767Returns the version of the current database, equivalent to $db->status->{data‐
769base}{version};
770
772 $style = $db->date_style();
774 $style = $db->date_style('ace');
775 $style = $db->date_style('java');
776For historical reasons, AceDB can display dates using either of two different
778formats. The first format, which I call "ace" style, puts the year first, as
779in "1997-10-01". The second format, which I call "java" style, puts the day
780first, as in "01 Oct 1997 00:00:00" (this is also the style recommended for
781Internet dates). The default is to use the latter notation.
782
784arguments, it returns the current style, which will be one of "ace" or "java."
785Called with an argument, it will set the style to one or the other.
786
788 $timestamps_on = $db->timestamps();
790 $db->timestamps(1);
791Whenever a data object is updated, AceDB records the time and date of the
793update, and the user ID it was running under. Ordinarily, the retrieval of
794timestamp information is suppressed to conserve memory and bandwidth. To turn
795on timestamps, call the timestamps() method with a true value. You can
796retrieve the current value of the setting by calling the method with no argu‐
797ments.
798Note that activating timestamps disables some of the speed optimizations in
800AcePerl. Thus they should only be activated if you really need the informa‐
801tion.
802
804Sets or queries the auto_save variable. If true, the "save" command will be
806issued automatically before the connection to the database is severed. The
807default is true.
808Examples:
810 $db->auto_save(1);
812 $flag = $db->auto_save;
813
815 Ace->error;
817This returns the last error message. Like UNIX errno, this variable is not
819reset between calls, so its contents are only valid after a method call has
820returned a result value indicating a failure.
821For your convenience, you can call error() in any of several ways:
823 print Ace->error();
825 print $db->error(); # $db is an Ace database handle
826 print $obj->error(); # $object is an Ace::Object
827There's also a global named $Ace::Error that you are free to use.
829
831 $datetime = Ace->datetime($time);
833 $today = Ace->datetime();
834 $date = Ace->date($time);
835 $today = Ace->date([$time]);
836These convenience functions convert the UNIX timestamp given by $time (seconds
838since the epoch) into a datetime string in the format that ACEDB requires.
840If not provided, $time defaults to localtime().
842
844 debug()
845 $debug_level = Ace->debug([$new_level])
847 This class method gets or sets the debug level. Higher integers
849 increase verbosity. 0 or undef turns off debug messages.
850 name2db()
852 $db = Ace->name2db($name [,$database])
854 This class method associates a database URL with an Ace database
856 object. This is used internally by the Ace::Object class in order to
857 discover what database they "belong" to.
858 cache()
860 Get or set the Cache::SizeAwareFileCache object, if one has been cre‐
862 ated.
863 memory_cache_fetch()
865 $obj = $db->memory_cache_fetch($class,$name)
867 Given an object class and name return a copy of the object from the in-
869 memory cache. The object will only be cached if a copy of the object
870 already exists in memory space. This is ordinarily called internally.
871 memory_cache_store($obj)
873 Store an object into the memory cache. This is ordinarily called
875 internally.
876 memory_cache_delete($obj)
878 Delete an object from the memory cache. This is ordinarily called
880 internally.
881 memory_cache_clear()
883 Completely clears the memory cache.
885 file_cache_fetch()
887 $obj = $db->file_cache_fetch($class,$name)
889 Given an object class and name return a copy of the object from the
891 file cache. This is ordinarily called internally.
892 file_cache_store($obj)
894 Store an object into the file cache. This is ordinarily called inter‐
896 nally.
897 file_cache_delete($obj)
899 Delete an object from the file cache. This is ordinarily called inter‐
901 nally.
902
904 Internally Ace.pm makes C-language calls to libace to send query
905 strings to the server and to retrieve the results. The class that
906 exports the low-level calls is named Ace::AceDB.
907 The following methods are available in Ace::AceDB:
909 new($host,$port,$query_timeout)
911 Connect to the host $host at port $port. Queries will time out
912 after $query_timeout seconds. If timeout is not specified, it
913 defaults to 120 (two minutes).
914 If successful, this call returns an Ace::AceDB connection object.
916 Otherwise, it returns undef. Example:
917 $acedb = Ace::AceDB->new('localhost',200005,5)
919 ⎪⎪ die "Couldn't connect";
920 The Ace::AceDB object can also be accessed from the high-level Ace
922 interface by calling the ACE::db() method:
923 $db = Ace->new(-host=>'localhost',-port=>200005);
925 $acedb = $db->db();
926 query($request)
928 Send the query string $request to the server and return a true
929 value if successful. You must then call read() repeatedly in order
930 to fetch the query result.
931 read()
933 Read the result from the last query sent to the server and return
934 it as a string. ACE may return the result in pieces, breaking
935 between whole objects. You may need to read repeatedly in order to
936 fetch the entire result. Canonical example:
937 $acedb->query("find Sequence D*");
939 die "Got an error ",$acedb->error() if $acedb->status == STATUS_ERROR;
940 while ($acedb->status == STATUS_PENDING) {
941 $result .= $acedb->read;
942 }
943 status()
945 Return the status code from the last operation. Status codes are
946 exported by default when you use Ace.pm. The status codes you may
947 see are:
948 STATUS_WAITING The server is waiting for a query.
950 STATUS_PENDING A query has been sent and Ace is waiting for
951 you to read() the result.
952 STATUS_ERROR A communications or syntax error has occurred
953 error()
955 Returns a more detailed error code supplied by the Ace server.
956 Check this value when STATUS_ERROR has been returned. These con‐
957 stants are also exported by default. Possible values:
958 ACE_INVALID
960 ACE_OUTOFCONTEXT
961 ACE_SYNTAXERROR
962 ACE_UNRECOGNIZED
963 Please see the ace client library documentation for a full descrip‐
965 tion of these error codes and their significance.
966 encore()
968 This method may return true after you have performed one or more
969 read() operations, and indicates that there is more data to read.
970 You will not ordinarily have to call this method.
971
973 1. The ACE model should be consulted prior to updating the database.
974 2. There is no automatic recovery from connection errors.
976 3. Debugging has only one level of verbosity, despite the best of
978 intentions.
979 4. Performance is poor when fetching big objects, because of many
981 object references that must be created. This could be improved.
982 5. When called in an array context at("tag[0]") should return the cur‐
984 rent tag's entire column. It returns the current subtree instead.
985 6. There is no way to add comments to objects.
987 7. When timestamps are active, many optimizations are disabled.
989 8. Item number eight is still missing.
991
993 Ace::Object, Ace::Local, Ace::Model,
994 Ace::Sequence,Ace::Sequence::Multi.
995
997 Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
998 Mieg <mieg@kaa.crbm.cnrs-mop.fr>
999 Copyright (c) 1997-1998 Cold Spring Harbor Laboratory
1001 This library is free software; you can redistribute it and/or modify it
1003 under the same terms as Perl itself. See DISCLAIMER.txt for dis‐
1004 claimers of warranty.
1005perl v5.8.8 2001-02-20 Ace(3)