text: NAME¶Ace - Object-Oriented Access to ACEDB Databases
  SYNOPSIS¶;
  DESCRIPTION¶Ace.
  CREATING NEW DATABASE CONNECTIONS¶
  connect() -- multiple argument form¶
  #mapper => $object_class, -timeout => $timeout, -query_timeout => $query_timeout -cache => {cache parameters}, );
  The connect() method uses a named argument calling style, and recognizes the following arguments:
  - -host, -port
  - These arguments point to the host and port of an AceDB server. AcePerl will use its internal compiled code to establish a connection to the server unless explicitly overridden with the -program argument.
  - -path
  - This argument indicates the path of an AceDB directory on the local system. It should point to the directory that contains the wspec subdirectory. User name interpolations (~acedb) are OK.
  - -user
  - Name of user to log in as (when using socket server only). If not provided, will attempt an anonymous login.
  - -pass
  - Password to log in with (when using socket server).
  - -url
  - An Acedb URL that combines the server type, host, port, user and password in a single string. See the connect() method's "single argument form" description.
  - -cache
  - AcePerl can use the Cache::SizeAwareFileCache module to cache objects to disk. This can result in dramatically increased performance in environments such as web servers in which the same Acedb objects are frequently reused. To activate this mechanism, the Cache::SizeAwareFileCache module must be installed, and you must pass the -cache argument during the connect() call.
  The value of -cache is a hash reference containing the arguments to be passed to Cache::SizeAwareFileCache. For example:
  -cache => { cache_root => '/usr/tmp/acedb', cache_depth => 4, default_expires_in => '1 hour' }
  If not otherwise specified, the following cache parameters are assumed:
  Parameter Default Value --------- ------------- namespace Server URL (e.g. sace://localhost:2005) cache_root /tmp/FileCache (dependent on system temp directory) default_expires_in 1 day auto_purge_interval 12 hours
  By default, the cache is not size limited (the "max_size" property is set to $NO_MAX_SIZE). To adjust the size you may consider calling the Ace object's cache() method to retrieve the physical cache and then calling the cache object's limit_size($max_size) method from time to time. See Cache::SizeAwareFileCache for more details.
  - -program
  -');
  - -classmapper
  - The optional -classmapper argument (alias -class)');
  The value of -class can be a hash reference consisting of AceDB class names as keys and Perl class names as values. If a class name does not exist in the hash, a key named _DEFAULT_ will be looked for. If that does not exist, then Ace will default to Ace::Object.
  The value of -class can also be an object or a classname that implements a class_for() method. This method will receive three arguments containing the AceDB class name, object ID and database handle. It should return a string indicating the perl class to create.
  - -timeout
  -.
  - -query_timeout
  -();
  connect() -- single argument form¶
  $db = Ace->connect('sace://stein.cshl.org:1880')
  Ace->connect() also accepts a single argument form using a URL-type syntax. The general syntax is:
  protocol://hostname:port/path
  The :port and /path parts are protocol-dependent as described above.
  Protocols:
  - sace://hostname:port
  - Connect to a socket server at the indicated hostname and port. Example:
  sace://stein.cshl.org:1880
  If not provided, the port defaults to 2005.
  - rpcace://hostname:port
  - Connect to an RPC server at the indicated hostname and RPC service number. Example:
  rpcace://stein.cshl.org:400000
  If not provided, the port defaults to 200005
  - tace:/path/to/database
  - Open up the local database at /path/to/database using tace. Example:
  tace:/~acedb/elegans
  - /path/to/database
  - Same as the previous.
  close() Method¶You can explicitly close a database by calling its close() method:
  $db->close();
  This is not ordinarily necessary because the database will be automatically close when it -- and all objects retrieved from it -- go out of scope.
  reopen() Method¶The ACeDB socket server can time out. The reopen() method will ping the server and if it is not answering will reopen the connection. If the database is live (or could be resurrected), this method returns true.
  RETRIEVING ACEDB OBJECTS¶Once you have established a connection and have an Ace databaes handle, several methods can be used to query the ACE database to retrieve objects. You can then explore the objects, retrieve specific fields from them, or update them using the Ace::Object methods. Please see Ace::Object.
  fetch() method¶
  ). Also see the get() method, which is equivalent to the simple two-argument form of fetch().
  - get() method
  $object = $db->get($class,$name [,$fill]);
  The get() method will return one and only one AceDB object identified by its class and name. The optional $fill argument can be used to control how much data is retrieved from the database. If $fill is absent or undefined, then the method will return a lightweight "stub" object that is filled with information as requested in a lazy fashion. If $fill is the number "1" then the retrieved object contains all the relevant information contained within the database. Any other true value of $fill will be treated as a tag name: the returned object will be prefilled with the subtree to the right of that tag.
  Examples:
  # return lightweight stub for Author object "Sulston JE." $author = $db->get(Author=>'Sulston JE'); # return heavyweight object $author = $db->get(Author=>'Sulston JE',1); # return object containing the Address subtree $author = $db->get(Author=>'Sulston JE','Address');
  The get() method is equivalent to this form of the fetch() method:
  $object = $db->fetch($class=>$name);
  aql() method¶
  .
  put() method¶
  ();
  parse() method¶
  $object = $db->parse('data to parse');
  This will parse the Ace tags contained within the "data to parse" string, convert it into an object in the database,.
  parse_longtext() method¶
  
  parse_file() method¶
  ().
  new() method¶
  $object = $db->new(.
  list() method¶
  @objects = $db->list(class,pattern,[count,offset]); @objects = $db->list(-class=>$class, -name=>$name_pattern, -count=>$count, -offset=>$offset);
  This is a deprecated method. Use fetch() instead.
  count() method¶
  .
  find() method¶
  ().
  fetch_many() method¶
  .
  find_many() method¶This is an alias for fetch_many(). It is now deprecated.
  keyset() method¶
  @objects = $db->keyset($keyset_name);
  This method returns all objects in a named keyset. Wildcard characters are accepted, in which case all keysets that match the pattern will be retrieved and merged into a single list of unique objects.
  grep() method¶
  @objects = $db->grep($grep_string); $count = $db->grep($grep_string); @objects = $db->grep(-pattern => $grep_string, -offset=> $offset, -count => $count, -fill => $fill, -filltag => $filltag, () method¶
  $model = $db->model('Author');
  This will return an Ace::Model object corresponding to the indicated class.
  new() method¶
  ().
  raw_query() method¶
  $r = $db->raw_query('Model');
  Send a command to the database and return its unprocessed output. This method is necessary to gain access to features that are not yet implemented in this module, such as model browsing and complex queries.
  classes() method¶
  .
  class_count() method¶
  () method¶
  %status = $db->status; $status = $db->status;
  Returns various bits of status information from the server. In an array context, returns a hash of hashes. In a scalar context, returns a reference to a hash of hashes. Keys and subkeys are as follows
  code program name of acedb binary version version of acedb binary build build date of acedb binary in format Jan 25 2003 16:21:24 database title name of the database version version of the database dbformat database format version number directory directory in which the database is stored session session number user user under which server is running write whether the server has write access address global address - not known if this is useful resources classes number of classes defined keys number of keys defined memory amount of memory used by acedb objects (bytes)
  For example, to get the program version:
  my $version = $db->status->{code}{version};
  title() method¶
  my $title = $db->title
  Returns the version of the current database, equivalent to $db->status->{database}{title};
  version() method¶
  my $version = $db->version;
  Returns the version of the current database, equivalent to $db->status->{database}{version};
  date_style() method¶
  () method¶
  .
  auto_save()¶Sets or queries the auto_save variable. If true, the "save" command will be issued automatically before the connection to the database is severed. The default is true.
  Examples:
  $db->auto_save(1); $flag = $db->auto_save;
  error() method¶() and date()¶
  ().
  OTHER METHODS¶
  debug()¶
  $debug_level = Ace->debug([$new_level])
  This class method gets or sets the debug level. Higher integers increase verbosity. 0 or undef turns off debug messages.
  name2db()¶
  $db = Ace->name2db($name [,$database])
  This class method associates a database URL with an Ace database object. This is used internally by the Ace::Object class in order to discover what database they "belong" to.
  cache()¶Get or set the Cache::SizeAwareFileCache object, if one has been created.
  memory_cache_fetch()¶
  $obj = $db->memory_cache_fetch($class,$name)
  Given an object class and name return a copy of the object from the in-memory cache. The object will only be cached if a copy of the object already exists in memory space. This is ordinarily called internally.
  memory_cache_store($obj)¶Store an object into the memory cache. This is ordinarily called internally.
  memory_cache_delete($obj)¶Delete an object from the memory cache. This is ordinarily called internally.
  memory_cache_clear()¶Completely clears the memory cache.
  file_cache_fetch()¶
  $obj = $db->file_cache_fetch($class,$name)
  Given an object class and name return a copy of the object from the file cache. This is ordinarily called internally.
  file_cache_store($obj)¶Store an object into the file cache. This is ordinarily called internally.
  file_cache_delete($obj)¶Delete an object from the file cache. This is ordinarily called internally.
  THE LOW LEVEL C API¶Internally Ace.pm makes C-language calls to libace to send query strings to the server and to retrieve the results. The class that exports the low-level calls is named Ace::AceDB.
  The following methods are available in Ace::AceDB:
  - new($host,$port,$query_timeout)
  -();
  - query($request)
  - Send the query string $request to the server and return a true value if successful. You must then call read() repeatedly in order to fetch the query result.
  -; }
  - status()
  -
  - error()
  - Returns a more detailed error code supplied by the Ace server. Check this value when STATUS_ERROR has been returned. These constants are also exported by default. Possible values:
  ACE_INVALID ACE_OUTOFCONTEXT ACE_SYNTAXERROR ACE_UNRECOGNIZED
  Please see the ace client library documentation for a full description of these error codes and their significance.
  - encore()
  - This method may return true after you have performed one or more read() operations, and indicates that there is more data to read. You will not ordinarily have to call this method.
  BUGS¶1. The ACE model should be consulted prior to updating the database.
  2. There is no automatic recovery from connection errors.
  3. Debugging has only one level of verbosity, despite the best of intentions.
  4. Performance is poor when fetching big objects, because of many object references that must be created. This could be improved.
  5. When called in an array context at("tag[0]") should return the current tag's entire column. It returns the current subtree instead.
  6. There is no way to add comments to objects.
  7. When timestamps are active, many optimizations are disabled.
  8. Item number eight is still missing.
  SEE ALSO¶Ace::Object, Ace::Local, Ace::Model, Ace::Sequence,Ace::Sequence::Multi.
  AUTHOR¶L.
  POD ERRORS¶Hey! The above document had some coding errors, which are explained below:
  - Around line 1194:
  - '=item' outside of any '=over'
  - Around line 1224:
  - You forgot a '=back' before '=head2'