---
name: "Ace::Local"
section: "3pm"
platform: "linux"
package: "libace-perl"
version: "1.92-12+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Ace::Local"
---

# Ace::Local(3pm)

use giface, tace or gifaceclient to open a local connection to an Ace database

## 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.