Ace::Local(3pm)

💖 Ace::Local 💖

okay so this is the Ace::Local page from the User Contributed Perl Documentation, and bestie, it's literally the low-level plumbing that opens a local connection to an Ace database using giface, tace or gifaceclient. she's niche but she's iconic. 🫶

---

✨ NAME ✨

Ace::Local — use giface, tace or gifaceclient to open a local connection to an Ace database. no cap, that's the whole vibe. 💅

---

🌸 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 💜

So this class exists for low-level access to local (aka non-networked) Ace databases, and it does that through the giface program. tbh you will generally not need to touch it directly — use Ace.pm instead, she's the main character here. 👑

For the sake of completeness (and because we're thorough like that), this method can also use the aceclient program for its access. Buuut the Ace::AceDB class is more efficient for that purpose, so like… noted. 📝

---

🦋 METHODS 🦋

🌟 connect()

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

Connects to the database at the path you gave, using giface, and hands you back a connection object (an "accessor" ✨). Giface must be on the current search path. And yes, you can have multiple accessors open at the same time — the more the merrier, she's polyamorous with connections. 🎀

Arguments include:

• -path — the path to the database (i.e. where the wspec/ directory lives). 📁
• -program — use this to point at the location of the giface or gifaceclient executable you want. You can 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. Says which host to connect to. 🌐
• -port — used when invoking gifaceclient. Says which port to connect to. 🔌
• -nosync — ordinarily Ace::Local synchronizes with the tace/giface prompt, yeeting all the warnings and copyright messages. If this is set, Ace::Local just won't do that. In that case you must call the low_read() method until it returns undef in order to synchronize. 😤

🌟 query()

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

Sends the query string off to the server and returns a true value if it worked. Then you have to call read() over and over to actually fetch the query result — she doesn't hand it all over at once, that's just not her style. 💁

🌟 read()

Reads the result from the last query you sent to the server and returns it as a string. ACE may return the result in pieces, breaking between whole objects, so you may need to read repeatedly to fetch the entire result. Canonical example, bestie, memorise it:

  $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()

Reads whatever data's available, or returns undef if there's none. This one is only used by the ace.pl replacement for giface/tace, so it's giving very much background-character energy. 🧚

🌟 status()

Returns 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 — lowkey a work in progress, we don't talk about it. 😭

🌟 encore()

This method returns true after you've done one or more read() operations, and it signals that there's more data to read. encore() is functionally equivalent to:

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

In fact, that's literally how it's implemented. fr fr. 💯

🌟 auto_save()

Sets or queries the auto_save variable. If it's true, the "save" command gets issued automatically before the connection to the database is severed. The default is true. periodt.

Examples:

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

---

🌈 SEE ALSO 🌈

Ace, Ace::Object, Ace::Iterator, Ace::Model — go read those too, they're the supporting cast and they ate. 👑

---

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

---

ok that's the whole page, bestie, you're officially educated 💖

and finally, the cute lil sign-off: this was perl v5.42.3, dated 2026-08-19, and yes, the page is Ace::Local(3pm). slay, go write some queries. ⭐