.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Ace::Local 3pm" .TH Ace::Local 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Ace::Local \- use giface, tace or gifaceclient to open a local connection to an Ace database .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 8 \& use Ace::Local \& my $ace = Ace::Local\->connect(\-path=>\*(Aq/usr/local/acedb/elegans\*(Aq); \& $ace\->query(\*(Aqfind author Se*\*(Aq); \& die "Query unsuccessful" unless $ace\->status; \& $ace\->query(\*(Aqshow\*(Aq); \& while ($ace\->encore) { \& print $ace\->read; \& } .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This class is provided for low-level access to local (non-networked) Ace databases via the \fIgiface\fR program. You will generally not need to access it directly. Use Ace.pm instead. .PP For the sake of completeness, the method can also use the \fIaceclient\fR program for its access. However the Ace::AceDB class is more efficient for this purpose. .SH METHODS .IX Header "METHODS" .SS \fBconnect()\fP .IX Subsection "connect()" .Vb 1 \& $accessor = Ace::Local\->connect(\-path=>$path_to_database); .Ve .PP Connect to the database at the indicated path using \fIgiface\fR and return a connection object (an "accessor"). \fIGiface\fR must be on the current search path. Multiple accessors may be open simultaneously. .PP Arguments include: .IP \fB\-path\fR 4 .IX Item "-path" Path to the database (location of the "wspec/" directory). .IP \fB\-program\fR 4 .IX Item "-program" Used to indicate the location of the desired \fIgiface\fR or \&\fIgifaceclient\fR executable. You may also use \fItace\fR or \fIaceclient\fR, but in that case the \fBasGIF()\fR functionality will nog work. Can be used to override the search path. .IP \fB\-host\fR 4 .IX Item "-host" Used when invoking \fIgifaceclient\fR. Indicates the host to connect to. .IP \fB\-port\fR 4 .IX Item "-port" Used when invoking \fIgifaceclient\fR. Indicates the port to connect to. .IP \fB\-nosync\fR 4 .IX Item "-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 \fBlow_read()\fR method until it returns undef in order to synchronize. .SS \fBquery()\fP .IX Subsection "query()" .Vb 1 \& $status = $accessor\->query(\*(Aqquery string\*(Aq); .Ve .PP Send the query string to the server and return a true value if successful. You must then call \fBread()\fR repeatedly in order to fetch the query result. .SS \fBread()\fP .IX Subsection "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: .PP .Vb 5 \& $accessor\->query("find Sequence D*"); \& die "Got an error ",$accessor\->error() if $accessor\->status == STATUS_ERROR; \& while ($accessor\->status == STATUS_PENDING) { \& $result .= $accessor\->read; \& } .Ve .SS \fBlow_read()\fP .IX Subsection "low_read()" Read whatever data's available, or undef if none. This is only used by the ace.pl replacement for giface/tace. .SS \fBstatus()\fP .IX Subsection "status()" Return the status code from the last operation. Status codes are exported by default when you \fBuse\fR Ace.pm. The status codes you may see are: .PP .Vb 4 \& 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 .Ve .SS \fBerror()\fP .IX Subsection "error()" May return a more detailed error code supplied by Ace. Error checking is not fully implemented. .SS \fBencore()\fP .IX Subsection "encore()" This method will return true after you have performed one or more \&\fBread()\fR operations, and indicates that there is more data to read. \&\fBencore()\fR is functionally equivalent to: .PP .Vb 1 \& $encore = $accessor\->status == STATUS_PENDING; .Ve .PP In fact, this is how it's implemented. .SS \fBauto_save()\fP .IX Subsection "auto_save()" Sets or queries the \fIauto_save\fR variable. If true, the "save" command will be issued automatically before the connection to the database is severed. The default is true. .PP Examples: .PP .Vb 2 \& $accessor\->auto_save(1); \& $flag = $accessor\->auto_save; .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Ace, Ace::Object, Ace::Iterator, Ace::Model .SH AUTHOR .IX Header "AUTHOR" Lincoln Stein with extensive help from Jean Thierry-Mieg .PP Copyright (c) 1997\-1998, Lincoln D. Stein .PP 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.