1Ace(3) User Contributed Perl Documentation Ace(3)
2
3
4
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
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
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
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
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
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
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
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
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
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
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.30.0 2019-07-26 Ace(3)