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
57 gifaceserver), and local ones.
58 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 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
78 $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
79 -port => 20000100);
80 # local (non-server) database
82 $db = Ace->connect(-path => '/usr/local/acedb);
83 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 $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 The connect() method uses a named argument calling style, and
102 recognizes the following arguments:
103 -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 -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 -user
116 Name of user to log in as (when using socket server only). If not
117 provided, will attempt an anonymous login.
118 -pass
120 Password to log in with (when using socket server).
121 -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 -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 The value of -cache is a hash reference containing the arguments to
136 be passed to Cache::SizeAwareFileCache. For example:
137 -cache => {
139 cache_root => '/usr/tmp/acedb',
140 cache_depth => 4,
141 default_expires_in => '1 hour'
142 }
143 If not otherwise specified, the following cache parameters are
145 assumed:
146 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 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 -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 $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
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 $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
233 message 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
239 connection 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')
251 Ace->connect() also accepts a single argument form using a URL-type
253 syntax. The general syntax is:
254 protocol://hostname:port/path
256 The :port and /path parts are protocol-dependent as described above.
258 Protocols:
260 sace://hostname:port
262 Connect to a socket server at the indicated hostname and port.
263 Example:
264 sace://stein.cshl.org:1880
266 If not provided, the port defaults to 2005.
268 rpcace://hostname:port
270 Connect to an RPC server at the indicated hostname and RPC service
271 number. Example:
272 rpcace://stein.cshl.org:400000
274 If not provided, the port defaults to 200005
276 tace:/path/to/database
278 Open up the local database at /path/to/database using tace.
279 Example:
280 tace:/~acedb/elegans
282 /path/to/database
284 Same as the previous.
285 close() Method
287 You can explicitly close a database by calling its close() method:
288 $db->close();
290 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 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
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 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 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 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 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 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 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 $object = $db->fetch(Sequence => 'D12345');
347 @objects = $db->fetch(Sequence => 'D1234*');
348 $cnt = $db->fetch(Sequence =>'D1234*');
349 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 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 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 @objects = $db->fetch(-name => 'D123*',
373 -class => 'Sequence',
374 -filltag => 'Visible');
375 This will fetch all Sequences named D123* and fill in their Visible
377 trees in a single operation.
378 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 @some_sequences = $db->fetch('Sequence','*',100,500);
389 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 @some_sequences = $db->fetch(-class => 'Sequence',
395 -count => 100,
396 -offset => 500,
397 -total => \$total);
398 Notice that if you leave out the -name argument the "*" wildcard is
400 assumed.
401 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 @ready_dnas= $db->fetch(-query=>
407 'find Annotation Ready_for_submission ; follow gene ;
408 follow derived_sequence ; >DNA');
409 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 get() method
416 $object = $db->get($class,$name [,$fill]);
417 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 Examples:
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');
439 The get() method is equivalent to this form of the fetch() method:
441 $object = $db->fetch($class=>$name);
443 aql() method
445 $count = $db->aql($aql_query);
446 @objects = $db->aql($aql_query);
447 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 If an AQL error is encountered, will return undef or an empty list and
454 set Ace->error to the error message.
455 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 put() method
461 $cnt = $db->put($obj1,$obj2,$obj3);
462 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 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 parse() method
474 $object = $db->parse('data to parse');
475 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 For 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
492 This method can also be used to parse several objects, but only the
494 last object successfully parsed will be returned.
495 parse_longtext() method
497 $object = $db->parse($title,$text);
498 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 For example:
506 $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 parse_file() method
515 @objects = $db->parse_file('/path/to/file');
516 @objects = $db->parse_file('/path/to/file',1);
517 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 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 Any parse error messages are accumulated in Ace->error().
527 new() method
529 $object = $db->new($class => $name);
530 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 $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 $paper = $db->new(Paper => 'wgb%06d');
540 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 See also the Ace::Object->add() and replace() methods.
545 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 This is a deprecated method. Use fetch() instead.
554 count() method
556 $count = $db->count($class,$pattern);
557 $count = $db->count(-query=>$query);
558 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 The class and name pattern are the same as the list() method above.
565 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 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 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 @papers = $db->find('author IS "Thierry-Mieg *" ; >Paper');
582 You can find the full query syntax reference guide plus multiple
584 examples at http://probe.nalusda.gov:8000/acedocs/index.html#query.
585 In the named parameter calling form, -count, -offset, and -fill have
587 the same meanings as in fetch().
588 fetch_many() method
590 $obj = $db->fetch_many($class,$pattern);
591 $obj = $db->fetch_many(-class=>$class,
593 -name =>$pattern,
594 -fill =>$filled,
595 -chunksize=>$chunksize);
596 $obj = $db->fetch_many(-query=>$query);
598 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 $i = $db->fetch_many(Sequence,'*'); # all sequences!!!!
604 while ($obj = $i->next) {
605 print $obj->asTable;
606 }
607 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 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 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 You may provide raw Ace query string with the -query argument. If
625 present the -name and -class arguments will be ignored.
626 find_many() method
628 This is an alias for fetch_many(). It is now deprecated.
629 keyset() method
631 @objects = $db->keyset($keyset_name);
632 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 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 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 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 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 model() method
668 $model = $db->model('Author');
669 This will return an Ace::Model object corresponding to the indicated
671 class.
672 new() method
674 $obj = $db->new($class,$name);
675 $obj = $db->new(-class=>$class,
676 -name=>$name);
677 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 raw_query() method
684 $r = $db->raw_query('Model');
685 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 classes() method
691 @classes = $db->classes();
692 @all_classes = $db->classes(1);
693 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 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 class_count() method
703 %classes = $db->class_count()
704 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 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 status() method
716 %status = $db->status;
717 $status = $db->status;
718 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 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 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 resources
739 classes number of classes defined
740 keys number of keys defined
741 memory amount of memory used by acedb objects (bytes)
742 For example, to get the program version:
744 my $version = $db->status->{code}{version};
746 title() method
748 my $title = $db->title
749 Returns the version of the current database, equivalent to
751 $db->status->{database}{title};
752 version() method
754 my $version = $db->version;
755 Returns the version of the current database, equivalent to
757 $db->status->{database}{version};
758 date_style() method
760 $style = $db->date_style();
761 $style = $db->date_style('ace');
762 $style = $db->date_style('java');
763 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 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 timestamps() method
777 $timestamps_on = $db->timestamps();
778 $db->timestamps(1);
779 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 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 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 Examples:
797 $db->auto_save(1);
799 $flag = $db->auto_save;
800 error() method
802 Ace->error;
803 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 For your convenience, you can call error() in any of several ways:
809 print Ace->error();
811 print $db->error(); # $db is an Ace database handle
812 print $obj->error(); # $object is an Ace::Object
813 There's also a global named $Ace::Error that you are free to use.
815 datetime() and date()
817 $datetime = Ace->datetime($time);
818 $today = Ace->datetime();
819 $date = Ace->date($time);
820 $today = Ace->date([$time]);
821 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 If not provided, $time defaults to localtime().
827
829 debug()
830 $debug_level = Ace->debug([$new_level])
831 This class method gets or sets the debug level. Higher integers
833 increase verbosity. 0 or undef turns off debug messages.
834 name2db()
836 $db = Ace->name2db($name [,$database])
837 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 cache()
843 Get or set the Cache::SizeAwareFileCache object, if one has been
844 created.
845 memory_cache_fetch()
847 $obj = $db->memory_cache_fetch($class,$name)
848 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 memory_cache_store($obj)
854 Store an object into the memory cache. This is ordinarily called
855 internally.
856 memory_cache_delete($obj)
858 Delete an object from the memory cache. This is ordinarily called
859 internally.
860 memory_cache_clear()
862 Completely clears the memory cache.
863 file_cache_fetch()
865 $obj = $db->file_cache_fetch($class,$name)
866 Given an object class and name return a copy of the object from the
868 file cache. This is ordinarily called internally.
869 file_cache_store($obj)
871 Store an object into the file cache. This is ordinarily called
872 internally.
873 file_cache_delete($obj)
875 Delete an object from the file cache. This is ordinarily called
876 internally.
877
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 The following methods are available in Ace::AceDB:
884 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 If successful, this call returns an Ace::AceDB connection object.
891 Otherwise, it returns undef. Example:
892 $acedb = Ace::AceDB->new('localhost',200005,5)
894 || die "Couldn't connect";
895 The Ace::AceDB object can also be accessed from the high-level Ace
897 interface by calling the ACE::db() method:
898 $db = Ace->new(-host=>'localhost',-port=>200005);
900 $acedb = $db->db();
901 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 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 $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 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 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 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 ACE_INVALID
935 ACE_OUTOFCONTEXT
936 ACE_SYNTAXERROR
937 ACE_UNRECOGNIZED
938 Please see the ace client library documentation for a full
940 description of these error codes and their significance.
941 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
948 1. The ACE model should be consulted prior to updating the database.
949 2. There is no automatic recovery from connection errors.
951 3. Debugging has only one level of verbosity, despite the best of
953 intentions.
954 4. Performance is poor when fetching big objects, because of many
956 object references that must be created. This could be improved.
957 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 6. There is no way to add comments to objects.
962 7. When timestamps are active, many optimizations are disabled.
964 8. Item number eight is still missing.
966
968 Ace::Object, Ace::Local, Ace::Model,
969 Ace::Sequence,Ace::Sequence::Multi.
970
972 Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-
973 Mieg <mieg@kaa.crbm.cnrs-mop.fr>
974 Copyright (c) 1997-1998 Cold Spring Harbor Laboratory
976 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
982 Hey! The above document had some coding errors, which are explained
983 below:
984 Around line 1194:
986 '=item' outside of any '=over'
987 Around line 1224:
989 You forgot a '=back' before '=head2'
990perl v5.32.1 2021-01-26 Ace(3)