/ 
AcePerl-1.54
River stage one • 1 direct dependent • 1 total dependent
/ Ace::Local

NAME

Ace::Local - use tace or aceclient to open a local connection to an Ace database

SYNOPSIS

use Ace::Local
my $ace = Ace::Local->connect(-path=>'/usr/local/acedb/elegans');
$ace->query('find author Se*');
die "Query unsuccessful" unless $ace->status;
$ace->query('show');
while ($ace->encore) {
  print $ace->read;
}

DESCRIPTION

This class is provided for low-level access to local (non-networked) Ace databases via the tace program. You will generally not need to access it directly. Use Ace.pm instead.

For the sake of completeness, the method can also use the aceclient program for its access. However the Ace::AceDB class is more efficient for this purpose.

METHODS

connect()

$accessor = Ace::Local->connect(-path=>$path_to_database);

Connect to the database at the indicated path using tace and return a connection object (an "accessor"). Tace must be on the current search path. Multiple accessors may be open simultaneously.

Arguments include:

-path

Path to the database (location of the "wspec/" directory).

-program

Used to indicate the location of the desired tace or aceclient executable. Can be used to override the search path.

-host

Used when invoking aceclient. Indicates the host to connect to.

-port

Used when invoking aceclient. Indicates the port to connect to.

query()

$status = $accessor->query('query string');

Send the query string to the server and return a true value if successful. You must then call read() repeatedly in order to fetch the query result.

read()

Read the result from the last query sent to the server and return it as a string. ACE may return the result in pieces, breaking between whole objects. You may need to read repeatedly in order to fetch the entire result. Canonical example:

$accessor->query("find Sequence D*");
die "Got an error ",$accessor->error() if $accessor->status == STATUS_ERROR;
while ($accessor->status == STATUS_PENDING) {
   $result .= $accessor->read;
}

status()

Return the status code from the last operation. Status codes are exported by default when you use Ace.pm. The status codes you may see are:

STATUS_WAITING    The server is waiting for a query.
STATUS_PENDING    A query has been sent and Ace is waiting for
                  you to read() the result.
STATUS_ERROR      A communications or syntax error has occurred

error()

May return a more detailed error code supplied by Ace. Error checking is not fully implemented.

encore()

This method will return true after you have performed one or more read() operations, and indicates that there is more data to read. encore() is functionally equivalent to:

$encore = $accessor->status == STATUS_PENDING;

In fact, this is how it's implemented.

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:

$accessor->auto_save(1);
$flag = $accessor->auto_save;

SEE ALSO

Ace, Ace::Object, Ace::Iterator, Ace::Model

AUTHOR

Lincoln Stein <lstein@w3.org> with extensive help from Jean Thierry-Mieg <mieg@kaa.crbm.cnrs-mop.fr>

Copyright (c) 1997-1998, Lincoln D. Stein

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.