NAME

       Ace::Local - use giface, tace or gifaceclient 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 giface
       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 giface and return a connection object (an
       "accessor").  Giface 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 giface or gifaceclient executable.  You may also use
           tace or aceclient, but in that case the asGIF() functionality will nog work.  Can be used to override
           the search path.

       -host
           Used when invoking gifaceclient.  Indicates the host to connect to.

       -port
           Used when invoking gifaceclient.  Indicates the port to connect to.

       -nosync
           Ordinarily Ace::Local synchronizes with  the  tace/giface  prompt,  throwing  out  all  warnings  and
           copyright  messages.   If  this  is  set,  Ace::Local will not do so.  In this case you must call the
           low_read() method until it returns undef in order to synchronize.

   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;
         }

   low_read()
       Read  whatever  data's  available,  or  undef  if  none.  This is only used by the ace.pl replacement for
       giface/tace.

   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.

perl v5.38.2                                       2024-03-31                                    Ace::Local(3pm)