This is Info file pm.info, produced by Makeinfo version 1.68 from the
input file bigpm.texi.


File: pm.info,  Node: AI/Perceptron,  Next: AO,  Prev: AI/Gene/AI/Gene/Simple,  Up: Module List

An implementation of a Perceptron
*********************************

NAME
====

   AI::Perceptron - An implementation of a Perceptron

SYNOPSIS
========

   use AI::Perceptron;

DESCRIPTION
===========

   This module is meant to show how a single node of a neural network
works to beginners in the field.

   The only mode of training the weights supported at this point in time
is the Stochastic Approximation of the Gradient-Descent model.

CONSTRUCTOR
===========

new( [%args] )
     Creates a new perceptron with the following properties:

          Inputs => number of inputs (scalar)
          N      => learning rate    (scalar)
          W      => array ref of weights (applied to the inputs)

     The Number of elements in W must be equal to the number of inputs
     *plus one*.  This is because W[0] is the Perceptron's threshold (so
     W[1] corresponds to the first input's weight).

     Default values are: 1, 0.05, and [random], respectively.

METHODS
=======

weights( [@W] )
     Sets/gets the perceptron's weights.  This is useful between training
     sessions to see if the weights are actually changing.  Note again that
     W[0] is the Perceptron's threshold.

train( $n, $training_examples )
     This uses the Stochastic Approximation of the Gradient-Descent model
     to adjust the perceptron's weights in such a way to achieve the
     desired outputs given in the training examples.

     Note that this training method may undo previous trainings!

SEE ALSO
========

   `Statistics::LTU', the ASCII model contained in Perceptron.pm.

REFERENCES
==========

   U<Machine Learning>, by Tom M. Mitchell

AUTHOR
======

   Steve Purkis <`spurkis@epn.nu'>

COPYRIGHT
=========

   Copyright (c) 1999, 2000 Steve Purkis.  All rights reserved.  This
package is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.


File: pm.info,  Node: AO,  Next: AOL/TOC,  Prev: AI/Perceptron,  Up: Module List

A Perl servlet engine
*********************

NAME
====

   AO - A Perl servlet engine

SYNOPSIS
========

   For an Apache deployment, add the following to httpd.conf:

     # load Apache 'adapter' and start up engine
     PerlModule Apache::AO

     # tell Apache to delegate handling
     <Location />
       SetHandler perl-script
       PerlHandler Apache::AO
     </Location>

DESCRIPTION
===========

   AO is a servlet engine for Perl. In other words, it provides an
environment in which web components (servlets) written in Perl can be
executed.

   While the servlet concept originated with Java, its component model is
quite natural for Perl as well. By writing servlet applications and
deploying them in a servlet engine, application authors can spare
themselves the effort of writing commonly needed web application
infrastructure components for each new project. Furthermore, servlet
applications can be made more portable between deployment environments;
applications written to the Servlet API should be deployable in any
servlet engine using any process model with only a few configuration
changes and no application code changes.

Servlet API
-----------

   The Servlet API is the key to writing portable web applications. This
'seam' provides decoupling between the deployment environment
(Apache/mod_perl web server, multiprocess/single thread) and the
application environment (handle request, generate response). Furthermore,
it provides access to the web environment portably between web servers.
Applications written to the Servlet API are insulated from changes in
vendor or platform and are able to portably take advantage of standard web
infrastructure services offered by any servlet engine.

Servlet Engine
--------------

   The servlet engine itself works with a web server to negotiate network
services, HTTP/S protocol handling, and MIME formatting. It also manages
web applications and servlets throughout their lifecycles. Perhaps most
importantly, it provides web infrastructure services such as security,
session management, configuration, and logging to servlet applications.
The servlet engine may also provide an environment in which web
applications can be distributed over processes and machines.

FEATURES
========

   AO provides a Perl web application environment with several standard
infrastructure services:

Configuration
     The servlet engine is configured via an XML file, server.xml. The
     main controller of the engine is represented as a *ContextManager*,
     and each web application deployed into the engine is represented as a
     Context. Various Interceptors and *Loggers* can be configured
     globally and per-context to provide infrastructure and application
     services.

     Web applications themselves are configured by their own XML files,
     web.xml, as described in the Servlet Specification. Application
     attributes, security, servlets, and the mapping of servlets to the
     application's URI namespace are described here on a per-application
     basis.

     See `AO::Config::Server' in this node and `AO::Config::Context' in
     this node for more information on configuration.

Session Management
     AO establishes a session for each web client interacting with the
     engine and maps each HTTP request to a session. Information of a
     transitory nature can be persisted for the life of a session using the
     session persistence framework; DBI and filesystem implementations are
     provided.

     See `AO::Interceptor::SessionManager' in this node,
     `AO::SessionManager::BaseSessionManager' in this node and
     `AO::Interceptor::Session' in this node for more information on
     session management.

Security
     AO provides security for web applications by implementing both
     authentication and authorization checks. The security administrator
     can define security policy domains (realms) in which various security
     roles are granted access to parts of the URI namespace, and security
     technology domains which each use a specific mechanism for
     authenticating users and verifying their assignment to a particular
     role via the access control framework; a DBI implementation is
     provided.

     See `AO::Interceptor::Access' in this node and
     `AO::Interceptor::RealmBase' in this node for more information on
     security.

Logging
     AO provides a flexible logging interface based on that of syslog;
     given a base log level, the servlet engine will log only events of
     that severity or greater. Syslog and Apache implementations are
     provided, and others can be created using the logging framework.

     See `AO::Logger::BaseLogger' in this node for more information on
     logging.

An Example
----------

   A client program, such as a web browser, makes an HTTP request of a web
server. The request is handed off to the servlet engine, which creates or
restores the session corresponding to the client program, performs
security checks if appropriate, determines which servlet to invoke and
calls the servlet, passing objects representing the request and response.
The servlet engine may run within the web server process, in another
process on the same host, or on a different host altogether.

   The servlet extracts data from the request object, performs its
application logic, and sends data back to the engine via the response
object. The engine passes the response data back to the web server and
performs any necessary cleanup operations (persisting session state, for
example). The web server sends an HTTP response to the client to conclude
the transaction.

INSTALLATION
============

   AO has only been tested under Linux. The AO code itself is all Perl and
thus should work in any environment with a working perl interpreter. The
framework requires a small number of CPAN modules, and the standard and
extended set of interceptors require several more.

   At this time, AO only provides a web server adapter for
Apache/mod_perl. It is anticipated that a FastCGI adapter will be
implemented in the near future.

   AO is installed in the standard MakeMaker fashion:

     perl Makefile.PL
     make
     make test
     make install

   No scripts or config files are installed, just the AO libraries. You'll
need to place server.xml manually (see below).

CONFIGURATION
=============

   The servlet engine and each web application are configured with XML
files. Furthermore, the web server must be configured to communicate with
the servlet engine as appropriate.

   The following points of configuration are common to all AO deployments:

base directory
     By default, the AO base directory will be web-server specific.
     However, `$ENV{AO_HOME}' can always be used to specify an alternate
     base directory (for example, `/home/bcm/work/ao').

server.xml
     AO will search for server.xml inside its base directory, in the
     following order: `./conf/server.xml', `./etc/server.xml',
     `./server.xml'. $ENV{AO_CONFIG} can be used to specify an exact
     location (for example, `/home/bcm/work/server.xml'); in this case, AO
     will not search through the above subdirectories.

     See `AO::Config::Server' in this node for a complete description of
     configuring server.xml. An example can be found at `etc/server.xml'.

web.xml
     For each context configured within server.xml, AO will look for
     web.xml inside `<context doc_base>/WEB-INF'.

     See `AO::Config' in this node for a complete description of
     configuring web.xml. Examples can be found at
     `share/examples/WEB-INF/web.xml' and `share/admin/WEB-INF/web.xml'.

Apache/mod_perl
---------------

   The following points of configuration are specific to the
Apache/mod_perl environment:

base directory
     By default, the AO base directory is the Apache server root.
     `$ENV{AO_HOME}' can be used to specify an alternate base directory as
     described above.

httpd.conf
     Apache has to be told to load the `Apache::AO' adapter module and to
     use it as the handler for all relevant Location/Directory/Files
     blocks. `WEB-INF' directories should be protected by denying access
     to them.

     If environment variables are to be used to influence AO's
     configuration, they must be set before `Apache::AO' is loaded. Either
     set them in the shell before starting the web server, or use a BEGIN
     block before loading the module.

     See `etc/ao.conf' for an example snippet of Apache configuration code.

ARCHITECTURE
============

   The architecture of the AO servlet engine is actually quite
straightforward. On a per-request basis, a controller accepts normalized
requests from a web server adapter, identifies the appropriate servlet and
delegates service to it, and routes the servlet's response back to the web
server adapter. The servlet itself is the gateway to the logic of the
application layer. Furthermore, event handlers are given the opportunity
to react at various points during the service process and during the
lifecycle of the engine and its web applications.

Adapters
--------

   These are the components that communicate between the web server and
the servlet engine. There is no actual adapter class, since each web
server and/or process model may require vastly different strategies for
adapting. If similarities appear as more adapters are developed, this
decision may be revisited.

   The responsibilities of an adapter are to instantiate a context
manager; process the engine's configuration; and to drive the context
manager's lifecycle.

   See `Apache::AO' in this node for more information on the Apache
adapter.

Context Manager
---------------

   The control and sequencing functions of the engine are allocated to the
*ContextManager*. Its responsibilities are to maintain the list of web
applications (Contexts) deployed into the engine, and add, reload or
remove web applications as necessary; to provide a starting point for the
engine itself; and to shepherd the various internal objects through the
process of servicing an individual request.

   See `AO::ContextManager' in this node for more information.

Contexts
--------

   Each web application is represented internally by a Context. These
objects aren't terribly interesting in their own right; they are basically
bundles of attributes and associations to other objects. It is using the
context that the engine and interceptors can execute context-specific
behavior during lifecycle and requext servicing (security constraints are
a good example), and it is from the context that servlets get all their
knowledge of the servlet environment.

   See `AO::Context' in this node for more information.

Interceptors
------------

   The processes of startup, request servicing and shutdown offer a lot of
room for customization of the engine's behavior. The AO architecture is
built around the notion of Interceptors that modify the behavior of the
core engine. Each Interceptor has the opportunity to respond to engine
lifecycle and/or request handling events.

   The standard behavior of the engine is implemented with Interceptors as
well. This allows an additional level of flexibility beyond the 'plug in
your own session persistence implementation' level. The session management
framework can be removed or replaced with a completely custom framework,
as desired.

   Note: the order in which interceptors are declared in server.xml is
very important. Since there is no way for an interceptor to signal that no
more interceptors should be given the ability to handle a particular
event, a later interceptor can possibly undo or overwrite an earlier
interceptor's work. It's yet to be seen if this is a liability or a
simplification.

   See `AO::BaseInterceptor' in this node for more information.

Lifecycle Events
----------------

   A *ContextInterceptor* acts on events in the lifecycle of the engine
and of each context. Each of the following events is called on each
context interceptor:

engine_init
     Called when the context manager is initialized by the adapter.
     Typically where global resources are initialized, such as database
     connections, etc.

context_init
     Called after the instantiation of a context, in order to prepare it
     for service. Typically where the context configuration is processed,
     servlets are preloaded, etc.

add_context
     Called when a context is added to the context manager's list.

remove_context
     Called when a context is removed from the context manager's list.

context_shutdown
     Called when a context is removed from service. Typically used to
     release resources used by that context only; for instance, to remove
     all active sessions for the context.

engine_shutdown
     Called when the context manager is about to end service. Typically
     used to release global resources, such as database connections.

   See `AO::Interceptor::ContextInterceptor' in this node for more
information about interceptors that act on lifecycle events.

Service Events
--------------

   A *RequestInterceptor* acts on events during the servicing of each
request. Each of the following events is called on each reequest
interceptor:

context_map
     Called to determine to which context the request was directed.

request_map
     Called to determine which servlet will service the request. Also used
     by the standard security mechanism to determine if the request must be
     authenticated.

authenticate
     Called to check the validity of submitted credentials.

authorize
     Called to check if the previously authenticated user is in the
     security role specified by the context's security configuration.

pre_service
     Called just before the servlet takes control of the request.

post_service
     Called just after the servlet has serviced the request.

   See `AO::Interceptor::RequestInterceptor' in this node for more
information about interceptors that act on service events.

Service
-------

   This is the actual point at which the servlet engine relinquishes
control and the servlet takes over; in other words, it is the entry point
for the servlet application.

   See `AO::Servlet::BaseServlet' in this node for more information about
servlets.

AUTHOR
======

   Brian Moseley, bcm@maz.org


File: pm.info,  Node: AOL/TOC,  Next: ASP,  Prev: AO,  Up: Module List

Perl extension for interfacing with AOL's AIM service
*****************************************************

NAME
====

   AOL::TOC - Perl extension for interfacing with AOL's AIM service

SYNOPSIS
========

     use AOL::TOC;
     $toc = AOL::TOC::new($toc_server, $login_server, $port,
            $screenname, $password);
     $toc->connect();

DESCRIPTION
===========

   This module implements SFLAP, which I presume to be AOL's
authenticiation protocol, and TOC, which is the actual "meat" of the AIM
protocol.

INTERFACE
=========

connect
-------

   connects to the AIM server

register_callback
-----------------

   This function takes two arguments, the EVENT and the subroutine
reference.  Callbacks are similar to the ones found in Net::IRC. The
module defines several AIM "events": ERROR, CLOSED, SIGN_ON, IM_IN,
CHAT_IN, UPDATE_BUDDY.  These events can be bound to subroutines.

dispatch
--------

   This flushes all messages to the server, and retreives all current
messages.

add_buddy
---------

   Takes one arguement, the nick of the buddy.  This adds a buddy to your
buddy list.

send_im
-------

   Takes two arguments, the name of the buddy and the name of the message,
and sends the IM.

get_info
--------

   Takes one argument, the name of the buddy, and returns the info.

chat_join
---------

   Takes one argument, the name of the chat room to join

chat_send
---------

   Takes two arguments, the name of the chat room, and the message.

AUTHOR
======

   xjharding@newbedford.k12.ma.us cleaned it up and added DOC
james@foo.org was the original author

SEE ALSO
========

   Net::AIM, a new module, but it doesn't have the features of this one


File: pm.info,  Node: ASP,  Next: ASP/NextLink,  Prev: AOL/TOC,  Up: Module List

a Module for ASP (PerlScript) Programming
*****************************************

NAME
====

   ASP - a Module for ASP (PerlScript) Programming

SYNOPSIS
========

     use strict;
     use ASP qw(:strict);

     print "Testing, testing.<BR><BR>";
     my $item = param('item');

     if($item eq 'Select one...') {
         die "Please select a value from the list.";
     }

     print "You selected $item.";
     exit;

DESCRIPTION
===========

   This module is based on Matt Sergeant's excellent Win32::ASP module,
which can be found at <`http://www.fastnetltd.ndirect.co.uk/Perl'>.  After
using Mr. Sergeant's module, I took on the task of customizing and
optimizing it for my own purposes. Feel free to use it if you find it
useful.

NOTES
=====

   This module is designed to work with both ASP PerlScript on IIS4, as
well as mod_perl/Apache::ASP on *nix platforms. Apache::ASP already
provides some of the functionality provided by this module; because of
this (and to avoid redundancy), ASP.pm attempts to detect its environment.
Differences between Apache and MS ASP are noted.

   Both of the print() and warn() standard perl funcs are overloaded to
output to the browser. print() is also available via the
$ASP::ASPOUT->print() method call.

   $Request->ServerVariables are only stuffed into %ENV on Win32
platforms, as Apache::ASP already provides this.

   ASP.pm also exports the $ScriptingNamespace symbol (Win32 only).  This
symbol allows PerlScript to call subs/functions written in another script
language. For example:

     <%@ language=PerlScript %>
     <%
         use ASP qw(:strict);
         print $ScriptingNamespace->SomeSub("arg1");
     %>
     <SCRIPT language=VBScript runat=server>
     Function SomeSub (str)
         SomeSub = SomethingThatReturnsSomething()
     End Function
     </SCRIPT>

USE
===

use ASP qw(:basic);
-------------------

   Exports basic subs: Print, Warn, die, exit, param, param_count. Same as
`use ASP;'

use ASP qw(:strict);
--------------------

   Allows the use of the ASP objects under `use strict;'.

   NOTE: This is not the only way to accomplish this, but I think it's the
cleanest, most convenient way.

use ASP qw(:all);
-----------------

   Exports all subs except those marked 'not exported'.

use ASP ();
-----------

   Overloads print() and warn() and provides the $ASP::ASPOUT object.

FUNCTION REFERENCE
==================

warn LIST
---------

   warn (or more specifically, the __WARN__ signal) has been re-routed to
output to the browser.

   FYI: When implemented, this tweak led to the removal of the prototypes
Matt placed on his subs.

Warn LIST
---------

   `Warn' is an alias for the ASP::Print method described below. The
overloading of warn as described above does not currently work in
Apache::ASP, so this is provided.

print LIST
----------

   print is overloaded to write to the browser by default. The inherent
behavior of print has not been altered and you can still use an alternate
filehandle as you normally would. This allows you to use print just as you
would in CGI scripts. The following statement would need no modification
between CGI and ASP PerlScript:

     print param('URL'), " was requested by ", $ENV{REMOTE_HOST}, "\n";

Print LIST
----------

   Prints a string or comma separated list of strings to the browser. Use
as if you were using print in a CGI application. Print gets around ASP's
limitations of 128k in a single $Response->Write() call.

   NB: print calls Print, so you could use either, but print more closely
resembles perl.

DebugPrint LIST
---------------

   Output is displayed between HTML comments so the output doesn't
interfere with page aesthetics.

HTMLPrint LIST
--------------

   The same as Print except the output is HTML-encoded so that any HTML
tags appear as sent, i.e. < becomes &lt;, > becomes &gt; etc.

die LIST
--------

   Prints the contents of LIST to the browser and then exits. die
automatically calls $Response->End for you, it also executes any cleanup
code you have added with `AddDeathHook'.

exit
----

   Exits the current script. $Response->End is called automatically for
you.  Any cleanup code added with `AddDeathHook' is also called.

escape LIST
-----------

   Escapes (URL-encodes) a list. Uses ASP object method
$Server->URLEncode().

unescape LIST
-------------

   Unescapes a URL-encoded list. Algorithms ripped from CGI.pm method of
the same name.

escapeHTML LIST
---------------

   Escapes a list of HTML. Uses ASP object method $Server->HTMLEncode().

   If passed an array reference, escapeHTML will return a reference to the
escaped array.

unescapeHTML LIST
-----------------

   Unescapes an HTML-encoded list.

   If passed an array reference, unescapeHTML will return a reference to
the un-escaped array.

param EXPR [, EXPR]
-------------------

   Simplifies parameter access and makes switch from GET to POST
transparent.

   Given the following querystring:

     myscript.asp?x=a&x=b&y=c

     param()      returns ('x', 'y')
     param('y')   returns 'c'
     param('x')   returns ('a', 'b')
     param('x',1) returns 'a'
     param('x',2) returns 'b'

   NOTE: Under Apache::ASP, param() simply passes the arguments to
CGI::param() because Apache::ASP doesn't support the $obj->{Count}
property used in this function.

param_count EXPR
----------------

   Returns the number of times EXPR appears in the request (Form or
QueryString).

   For example, if URL is

     myscript.asp?x=a&x=b&y=c

   then

     param_count('x');

   returns 2.

   NOTE: Under Apache::ASP, param_count() performs some manipulation using
CGI::param() because Apache::ASP doesn't support the $obj->{Count}
property used in this function.


AddDeathHook LIST
-----------------

   Allows cleanup code to be executed when you die or exit.  Useful for
closing database connections in the event of a fatal error.

     <%
     my $conn = Win32::OLE-new('ADODB.Connection');
     $conn->Open("MyDSN");
     $conn->BeginTrans();
     ASP::AddDeathHook( sub { $Conn->Close if $Conn; } );
     %>

   Death hooks are not executed except by explicitly calling the die() or
exit() methods provided by ASP.pm.

   AddDeathHook is not exported.

AUTHOR
======

   Tim Hammerquist <`tim@dichosoft.com'>

HISTORY
=======

Version 1.07
     Added Warn() because warn() overloading doesn't appear to work under
     Apache::ASP.

     Was forced to clear @DeathHooks array after calling _END() because of
     the persistent state of Apache::ASP holding over contents across
     executions.

     Removed BinaryWrite(), SetCookie(), and Autoload functionality.

Version 1.00
     The escapeHTML() and unescapeHTML() functions now accept array refs
     as well as lists, as Win32::ASP::HTMLEncode() was supposed to.
     Thanks to Matt Sergeant for the fix.

Version 0.97
     Optimized and debugged.

Version 0.77
     Overloaded warn() and subsequently removed prototypes.

     Exported $ScriptingNamespace object.

     Added methods escape(), unescape(), escapeHTML(), unescapeHTML().
     Thanks to Bill Odom for pointing these out!

     Re-implemented SetCookie and BinaryWrite functions.

Version 0.11
     Optimized and debugged.

SEE ALSO
========

   ASP::NextLink(3)


File: pm.info,  Node: ASP/NextLink,  Next: Ace,  Prev: ASP,  Up: Module List

Perl implementation of the NextLink ASP component
*************************************************

NAME
====

   ASP::NextLink - Perl implementation of the NextLink ASP component

SYNOPSIS
========

     require ASP::NextLink;
     $nl = new ASP::NextLink('linkfile.ext');

     $current = $nl->GetListIndex;
     for $idx (1..$nl->GetListCount) {
     	my $url =	$nl->GetNthURL($idx);
     	my $desc =	$nl->GetNthDescription($idx);
     	if ($idx == $current) {
     		print qq(<A href="$url">$desc</A><BR>);
     	}
     	else {
     		print qq(<B>$desc</B>);
     	}
     }

DESCRIPTION
===========

   ASP::NextLink is a Perl implementation of MSWC.NextLink, ASP's
content-linking component for use with Apache::ASP.

NOTES
=====

   ASP::NextLink is NOT functionally equivalent to MSWC.NextLink.  Whereas
each method of MSWC.NextLink takes a file argument, ASP::NextLink takes a
file argument ONLY in the constructor ( ASP::NextLink->new("linkfile") ).
new() parses the linkfile given; the information derived from this
linkfile is subsequently available only through the object returned by
new().

   Attempts to call object methods on a class and attempts to call class
methods on an object will both trigger an exception.

   However, in the interest of portability of algorithms to ASP::NextLink,
indexes passed to the GetNth*() methods remain 1-based, as they are in
MSWC.NextLink.

USE
===

require ASP::NextLink;
----------------------

METHOD REFERENCE
================

new( linkfile )
---------------

   The new() class method accepts a virtual or relative path.  (Paths
handed to new() are run through the $Server->MapPath() method.)  new()
returns a reference to an ASP::NextLink object.

     my $linkfile = "/links.txt";
     my $nl = ASP::NextLink->new( $linkfile );

   From now we will refer to the object returned by new() as $nl.

GetListCount()
--------------

   Returns the number of links (lines containing tab-separated fields) in
link file.

     my $count = $nl->GetListCount();

GetListIndex()
--------------

   Index of the current page in the link file.

GetPreviousURL()
----------------

   URL of the previous page in the link file.

GetPreviousDescription()
------------------------

   Description of the previous page in the link file.

GetNextURL()
------------

   URL of the next page in the link file.

GetNextDescription()
--------------------

   Description of the next page in the link file.

GetNthURL( n )
--------------

   URL of the nth page in the link file.  NOTE: Index is 1-based, NOT
zero-based.

GetNthDescription( n )
----------------------

   Description of the nth page in the link file.  NOTE: Index is 1-based,
NOT zero-based.

AUTHOR
======

   Tim Hammerquist <`cafall@voffice.net'>

HISTORY
=======

Version 0.11
     First functional release

SEE ALSO
========

   ASP(3)


File: pm.info,  Node: Ace,  Next: Ace/Browser/AceSubs,  Prev: ASP/NextLink,  Up: Module List

Object-Oriented Access to ACEDB Databases
*****************************************

NAME
====

   Ace - Object-Oriented Access to ACEDB Databases

SYNOPSIS
========

     use Ace;
     # open a remote database connection
     $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                        -port => 20000100);

     # open a local database connection
     $local = Ace->connect(-path=>'~acedb/my_ace');

     # simple queries
     $sequence  = $db->fetch(Sequence => 'D12345');
     $count     = $db->count(Sequence => 'D*');
     @sequences = $db->fetch(Sequence => 'D*');
     $i         = $db->fetch_many(Sequence=>'*');  # fetch a cursor
     while ($obj = $i->next) {
        print $obj->asTable;
     }

     # complex queries
     $query = <<END;
     find Annotation Ready_for_submission ; follow gene ;
     follow derived_sequence ; >DNA
     END
     @ready_dnas= $db->fetch(-query=>$query);

     $ready = $db->fetch_many(-query=>$query);
     while ($obj = $ready->next) {
         # do something with obj
     }

     # database cut and paste
     $sequence = $db->fetch(Sequence => 'D12345');
     $local_db->put($sequence);
     @sequences = $db->fetch(Sequence => 'D*');
     $local_db->put(@sequences);

     # Get errors
     print Ace->error;
     print $db->error;

DESCRIPTION
===========

   AcePerl provides an interface to the ACEDB object-oriented database.
Both read and write access is provided, and ACE objects are returned as
similarly-structured Perl objects.  Multiple databases can be opened
simultaneously.

   You will interact with several Perl classes: *Ace*, *Ace::Object*,
*Ace::Iterator*, *Ace::Model*.  *Ace* is the database accessor, and can be
used to open both remote Ace databases (running aceserver or
gifaceserver), and local ones.

   *Ace::Object* is the superclass for all objects returned from the
database.  *Ace* and *Ace::Object* are linked: if you retrieve an
Ace::Object from a particular database, it will store a reference to the
database and use it to fetch any subobjects contained within it.  You may
make changes to the *Ace::Object* and have those changes written into the
database.  You may also create *Ace::Object*s from scratch and store them
in the database.

   *Ace::Iterator* is a utility class that acts as a database cursor for
long-running ACEDB queries.  *Ace::Model* provides object-oriented access
to ACEDB's schema.

   Internally, *Ace* uses the *Ace::Local* class for access to local
databases and *Ace::AceDB* for access to remote databases.  Ordinarily you
will not need to interact directly with either of these classes.

CREATING NEW DATABASE CONNECTIONS
=================================

connect() - multiple argument form
----------------------------------

     # remote database
     $db = Ace->connect(-host  =>  'beta.crbm.cnrs-mop.fr',
                        -port  =>  20000100);
     
     # local (non-server) database
     $db = Ace->connect(-path  =>  '/usr/local/acedb);

   Use Ace::connect() to establish a connection to a networked or local
AceDB database.  To establish a connection to an AceDB server, use the
*-host* and/or *-port* arguments.  For a local server, use the *-port*
argument.  The database must be up and running on the indicated host and
port prior to connecting to an AceDB server.  The full syntax is as
follows:

     $db = Ace->connect(-host  =>  $host,
                        -port  =>  $port,
     		       -path  =>  $database_path,
     		       -program =>$local_connection_program
                        -class =>  $object_class,
     		       -timeout => $timeout,
     		       -query_timeout => $query_timeout);

   The connect() method uses a named argument calling style, and
recognizes the following arguments:

*-host*, *-port*
     These arguments point to the host and port of an AceDB server.
     AcePerl will use its internal compiled code to establish a connection
     to the server unless explicitly overridden with the *-program*
     argument.

*-path*
     This argument indicates the path of an AceDB directory on the local
     system.  It should point to the directory that contains the *wspec*
     subdirectory.  User name interpolations (~acedb) are OK.

*-user*
     Name of user to log in as (when using socket server *only*).  If not
     provided, will attempt an anonymous login.

*-pass*
     Password to log in with (when using socket server).

*-program*
     By default AcePerl will use its internal compiled code calls to
     establish a connection to Ace servers, and will launch a *tace*
     subprocess to communicate with local Ace databases.  The *-program*
     argument allows you to customize this behavior by forcing AcePerl to
     use a local program to communicate with the database.  This argument
     should point to an executable on your system.  You may use either a
     complete path or a bare command name, in which case the PATH
     environment variable will be consulted.  For example, you could force
     AcePerl to use the *aceclient* program to connect to the remote host
     by connecting this way:

          $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                             -port => 20000100,
                             -program=>'aceclient');

*-class*
     The optional *-class* argument points to the class you would like to
     return from database queries.  It is provided for your use if you
     subclass Ace::Object.  For example, if you have created a subclass of
     Ace::Object called Ace::Object::Graphics, you can have the database
     return this subclass by default by connecting this way:

          $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                             -port => 20000100,
          	             -class=>'Ace::Object::Graphics');

*-timeout*
     If no response from the server is received within $timeout seconds,
     the call will return an undefined value.  Internally timeout sets an
     alarm and temporarily intercepts the ALRM signal.  You should be aware
     of this if you use ALRM for your own purposes.

     NOTE: this feature is temporarily disabled (as of version 1.40)
     because it is generating unpredictable results when used with
     Apache/mod_perl.

*-query_timeout*
     If any query takes longer than $query_timeout seconds, will return an
     undefined value.  This value can only be set at connect time, and
     cannot be changed once set.

   If arguments are omitted, they will default to the following values:

     -host          localhost
     -port          200005;
     -path          no default
     -program       tace
     -class         Ace::Object
     -timeout       25
     -query_timeout 120

   If you prefer to use a more Smalltalk-like message-passing syntax, you
can open a connection this way too:

     $db = connect Ace -host=>'beta.crbm.cnrs-mop.fr',-port=>20000100;

   The return value is an Ace handle to use to access the database, or
undef if the connection fails.  If the connection fails, an error message
can be retrieved by calling Ace->error.

   You may check the status of a connection at any time with ping().  It
will return a true value if the database is still connected.  Note that
Ace will timeout clients that have been inactive for any length of time.
Long-running clients should attempt to reestablish their connection if
ping() returns false.

     $db->ping() || die "not connected";

   You may perform low-level calls using the Ace client C API by calling
db().  This fetches an Ace::AceDB object.  See THE LOW LEVEL C API for
details on using this object.

   $low_level = $db->db();

connect() - single argument form
--------------------------------

     $db = Ace->connect('sace://stein.cshl.org:1880')

   Ace->connect() also accepts a single argument form using a URL-type
syntax.  The general syntax is:

     protocol://hostname:port/path

   The *:port* and */path* parts are protocol-dependent as described above.

   Protocols:

sace://hostname:port
     Connect to a socket server at the indicated hostname and port.
     Example:

          sace://stein.cshl.org:1880

     If not provided, the port defaults to 2005.

rpcace://hostname:port
     Connect to an RPC server at the indicated hostname and RPC service
     number.  Example:

          rpcace://stein.cshl.org:400000

     If not provided, the port defaults to 200005

tace:/path/to/database
     Open up the local database at /path/to/database using tace.  Example:

          tace:/~acedb/elegans

/path/to/database
     Same as the previous.

close() Method
--------------

   You can explicitly close a database by calling its close() method:

     $db->close();

   This is not ordinarily necessary because the database will be
automatically close when it - and all objects retrieved from it - go out
of scope.

RETRIEVING ACEDB OBJECTS
========================

   Once you have established a connection and have an Ace databaes handle,
several methods can be used to query the ACE database to retrieve objects.
You can then explore the objects, retrieve specific fields from them, or
update them using the *Ace::Object* methods.  Please see *Note Ace/Object:
Ace/Object,.

fetch() method
--------------

     $count   = $db->fetch($class,$name_pattern);
     $object  = $db->fetch($class,$name);
     @objects = $db->fetch($class,$name_pattern,[$count,$offset]);
     @objects = $db->fetch(-name=>$name_pattern,
                           -class=>$class
     			  -count=>$count,
     			  -offset=>$offset,
                           -fill=>$fill,
     			  -filltag=>$tag,
     	                  -total=>\$total);
     @objects = $db->fetch(-query=>$query);

   Ace::fetch() retrieves objects from the database based on their class
and name.  You may retrieve a single object by requesting its name, or a
group of objects by fetching a name pattern.  A pattern contains one or
more wildcard characters, where "*" stands for zero or more characters,
and "?" stands for any single character.

   This method behaves differently depending on whether it is called in a
scalar or a list context, and whether it is asked to search for a name
pattern or a simple name.

   When called with a class and a simple name, it returns the object
referenced by that time, or undef, if no such object exists.  In an array
context, it will return an empty list.

   When called with a class and a name pattern in a list context, fetch()
returns the list of objects that match the name.  When called with a
pattern in a scalar context, fetch() returns the number of objects that
match without actually retrieving them from the database.  Thus, it is
similar to count().

   In the examples below, the first line of code will fetch the Sequence
object whose database ID is *D12345*.  The second line will retrieve all
objects matching the pattern *D1234**.  The third line will return the
count of objects that match the same pattern.

     $object =  $db->fetch(Sequence => 'D12345');
     @objects = $db->fetch(Sequence => 'D1234*');
     $cnt =     $db->fetch(Sequence =>'D1234*');

   A variety of communications and database errors may occur while
processing the request.  When this happens, undef or an empty list will be
returned, and a string describing the error can be retrieved by calling
Ace->error.

   When retrieving database objects, it is possible to retrieve a "filled"
or an "unfilled" object.  A filled object contains the entire contents of
the object, including all tags and subtags.  In the case of certain
Sequence objects, this may be a significant amount of data.  Unfilled
objects consist just of the object name.  They are filled in from the
database a little bit at a time as tags are requested.  By default,
fetch() returns the unfilled object.  This is usually a performance win,
but if you know in advance that you will be needing the full contents of
the retrieved object (for example, to display them in a tree browser) it
can be more efficient to fetch them in filled mode. You do this by calling
fetch() with the argument of *-fill* set to a true value.

   The *-filltag* argument, if provided, asks the database to fill in the
subtree anchored at the indicated tag.  This will improve performance for
frequently-accessed subtrees.  For example:

     @objects = $db->fetch(-name    => 'D123*',
                           -class   => 'Sequence',
                           -filltag => 'Visible');

   This will fetch all Sequences named D123* and fill in their Visible
trees in a single operation.

   Other arguments in the named parameter calling form are *-count*, to
retrieve a certain maximum number of objects, and *-offset*, to retrieve
objects beginning at the indicated offset into the list.  If you want to
limit the number of objects returned, but wish to learn how many objects
might have been retrieved, pass a reference to a scalar variable in the
*-total* argument.  This will return the object count.  This example shows
how to fetch 100 Sequence objects, starting at Sequence number 500:

     @some_sequences = $db->fetch('Sequence','*',100,500);

   The next example uses the named argument form to fetch 100 Sequence
objects starting at Sequence number 500, and leave the total number of
Sequences in $total:

     @some_sequences = $db->fetch(-class  => 'Sequence',
     	                       -count  => 100,
     	                       -offset => 500,
     	                       -total  => \$total);

   Notice that if you leave out the *-name* argument the "*" wildcard is
assumed.

   You may also pass an arbitrary Ace query string with the *-query*
argument.  This will supersede any name and class you provide.  Example:

     @ready_dnas= $db->fetch(-query=>
         'find Annotation Ready_for_submission ; follow gene ;
          follow derived_sequence ; >DNA');

   If your request is likely to retrieve very many objects, fetch() many
consume a lot of memory, even if *-fill* is false.  Consider using
*fetch_many()* instead (see below).

aql() method
------------

     $count   = $db->aql($aql_query);
     @objects = $db->aql($aql_query);

   Ace::aql() will perform an AQL query on the database.  In a scalar
context it returns the number of rows returned.  In an array context it
returns a list of rows.  Each row is an anonymous array containing the
columns returned by the query as an Ace::Object.

   If an AQL error is encountered, will return undef or an empty list and
set Ace->error to the error message.

   Note that this routine is not optimized - there is no iterator defined.
All results are returned synchronously, leading to large memory
consumption for certain queries.

put() method
------------

     $cnt = $db->put($obj1,$obj2,$obj3);

   This method will put the list of objects into the database, overwriting
like-named objects if they are already there.  This can be used to copy an
object from one database to another, provided that the models are
compatible.

   The method returns the count of objects successfully written into the
database.  In case of an error, processing will stop at the last object
successfully written and an error message will be placed in Ace->error();

parse() method
--------------

     $object = $db->parse('data to parse');

   This will parse the Ace tags contained within the "data to parse"
string, convert it into an object in the databse, and return the resulting
Ace::Object.  In case of a parse error, the undefined value will be
returned and a (hopefully informative) description of the error will be
returned by Ace->error().

   For example:

     $author = $db->parse(<<END);
     Author : "Glimitz JR"
     Full_name "Jonathan R. Glimitz"
     Mail	"128 Boylston Street"
     Mail	"Boston, MA"
     Mail	"USA"
     Laboratory GM
     END

   This method can also be used to parse several objects, but only the
last object successfully parsed will be returned.

parse_longtext() method
-----------------------

     $object = $db->parse($title,$text);

   This will parse the long text (which may contain carriage returns and
other funny characters) and place it into the database with the given
title.  In case of a parse error, the undefined value will be returned and
a (hopefully informative) description of the error will be returned by
Ace->error(); otherwise, a LongText object will be returned.

   For example:

     $author = $db->parse_longtext('A Novel Inhibitory Domain',<<END);
     We have discovered a novel inhibitory domain that inhibits
     many classes of proteases, including metallothioproteins.
     This inhibitory domain appears in three different gene families studied
     to date...
     END

parse_file() method
-------------------

     @objects = $db->parse_file('/path/to/file');
     @objects = $db->parse_file('/path/to/file',1);

   This will call parse() to parse each of the objects found in the
indicated .ace file, returning the list of objects successfully loaded
into the database.

   By default, parsing will stop at the first object that causes a parse
error.  If you wish to forge on after an error, pass a true value as the
second argument to this method.

   Any parse error messages are accumulated in Ace->error().

list() method
-------------

     @objects = $db->list(class,pattern,[count,offset]);
     @objects = $db->list(-class=>$class,
                          -name=>$name_pattern,
                          -count=>$count,
                          -offset=>$offset);

   This is a deprecated method.  Use fetch() instead.

count() method
--------------

     $count = $db->count($class,$pattern);
     $count = $db->count(-query=>$query);

   This function queries the database for a list of objects matching the
specified class and pattern, and returns the object count.  For large sets
of objects this is much more time and memory effective than fetching the
entire list.

   The class and name pattern are the same as the list() method above.

   You may also provide a *-query* argument to instead specify an
arbitrary ACE query such as "find Author COUNT Paper > 80".  See find()
below.

find() method
-------------

     @objects = $db->find($query_string);
     @objects = $db->find(-query => $query_string,
                          -offset=> $offset,
                          -count => $count
                          -fill  => $fill);

   This allows you to pass arbitrary Ace query strings to the server and
retrieve all objects that are returned as a result.  For example, this
code fragment retrieves all papers written by Jean and Danielle
Thierry-Mieg.

     @papers = $db->find('author IS "Thierry-Mieg *" ; >Paper');

   You can find the full query syntax reference guide plus multiple
examples at http://probe.nalusda.gov:8000/acedocs/index.html#query.

   In the named parameter calling form, *-count*, *-offset*, and *-fill*
have the same meanings as in fetch().

fetch_many() method
-------------------

     $obj = $db->fetch_many($class,$pattern);

     $obj = $db->fetch_many(-class=>$class,
                            -name =>$pattern,
                            -fill =>$filled,
                            -chunksize=>$chunksize);

     $obj = $db->fetch_many(-query=>$query);

   If you expect to retrieve many objects, you can fetch an iterator
across the data set.  This is friendly both in terms of network bandwidth
and memory consumption.  It is simple to use:

     $i = $db->fetch_many(Sequence,'*');  # all sequences!!!!
     while ($obj = $i->next) {
        print $obj->asTable;
     }

   The iterator will return undef when it has finished iterating, and
cannot be used again.  You can have multiple iterators open at once and
they will operate independently of each other.

   Like fetch(), *fetch_many()* takes an optional *-fill* (or *-filled*)
argument which retrieves the entire object rather than just its name.
This is efficient on a network with high latency if you expect to be
touching many parts of the object (rather than just retrieving the value
of a few tags).

   *fetch_many()* retrieves objects from the database in groups of a
certain maximum size, 40 by default.  This can be tuned using the optional
*-chunksize* argument.  Chunksize is only a hint to the database.  It may
return fewer objects per transaction, particularly if the objects are
large.

   You may provide raw Ace query string with the *-query* argument.  If
present the *-name* and *-class* arguments will be ignored.

find_many() method
------------------

   This is an alias for fetch_many().  It is now deprecated.

keyset() method
---------------

     @objects = $db->keyset($keyset_name);

   This method returns all objects in a named keyset.  Wildcard characters
are accepted, in which case all keysets that match the pattern will be
retrieved and merged into a single list of unique objects.

grep() method
-------------

     @objects = $db->grep($grep_string);
     $count   = $db->grep($grep_string);
     @objects = $db->grep(-pattern => $grep_string,
                          -offset=> $offset,
                          -count => $count,
                          -fill  => $fill,
     			 -total => \$total,
                          -long  => 1,
     			);

   This performs a "grep" on the database, returning all object names or
text that contain the indicated grep pattern.  In a scalar context this
call will return the number of matching objects.  In an array context, the
list of matching objects are retrieved.  There is also a named-parameter
form of the call, which allows you to specify the number of objects to
retrieve, the offset from the beginning of the list to retrieve from,
whether the retrieved objects should be filled initially.  You can use
*-total* to discover the total number of objects that match, while only
retrieving a portion of the list.

   By default, grep uses a fast search that only examines class names and
lexiques.  By providing a true value to the *-long* parameter, you can
search inside LongText and other places that are not usually touched on,
at the expense of much more CPU time.

   Due to "not listable" objects that may match during grep, the list of
objects one can retrieve may not always match the count.

model() method
--------------

     $model = $db->model('Author');

   This will return an *Ace::Model* object corresponding to the indicated
class.

new() method
------------

     $obj = $db->new($class,$name);
     $obj = $db->new(-class=>$class,
                     -name=>$name);

   Create a new object in the database with the indicated class and name
and return a pointer to it.  Will return undef if the object already
exists in the database.  The object isn't actually written into the
database until you call Ace::Object::commit().

raw_query() method
------------------

     $r = $db->raw_query('Model');

   Send a command to the database and return its unprocessed output.  This
method is necessary to gain access to features that are not yet
implemented in this module, such as model browsing and complex queries.

classes() method
----------------

     @classes = $db->classes();
     @all_classes = $db->classes(1);

   This method returns a list of all the object classes known to the
server.  In a list context it returns an array of class names.  In a
scalar context, it the number of classes defined in the database.

   Ordinarily *classes()* will return only those classes that are exposed
to the user interface for browsing, the so-called "visible" classes.  Pass
a true argument to the call to retrieve non-visible classes as well.

class_count() method
--------------------

     %classes = $db->class_count()

   This returns a hash in which the keys are the class names and the
values are the total number of objects in that class.  All classes are
returned, including invisible ones.  Use this method if you need to count
all classes simultaneously.  If you only want to count one or two classes,
it may be more efficient to call *count($class_name)* instead.

   This method transiently uses a lot of memory.  It should not be used
with Ace 4.5 servers, as they contain a memory leak in the counting
routine.

status() method
---------------

     %status = $db->status;
     $status = $db->status;

   Returns various bits of status information from the server.  In an
array context, returns a hash.  In a scalar context, returns a hash
reference.  The keys in the hash are as follows:

     version       Ace server version number
     date          Ace server link date
     directory     Path to database directory
     blocks        Number of disk blocks used by database
     classes       Number of defined classes
     keys          Number of defined keys
     memory        Memory usage, in kb
     write         Whether write access has been granted

date_style() method
-------------------

     $style = $db->date_style();
     $style = $db->date_style('ace');
     $style = $db->date_style('java');

   For historical reasons, AceDB can display dates using either of two
different formats.  The first format, which I call "ace" style, puts the
year first, as in "1997-10-01".  The second format, which I call "java"
style, puts the day first, as in "01 Oct 1997 00:00:00" (this is also the
style recommended for Internet dates).  The default is to use the latter
notation.

   *date_style()* can be used to set or retrieve the current style.
Called with no arguments, it returns the current style, which will be one
of "ace" or "java."  Called with an argument, it will set the style to one
or the other.

timestamps() method
-------------------

     $timestamps_on = $db->timestamps();
     $db->timestamps(1);

   Whenever a data object is updated, AceDB records the time and date of
the update, and the user ID it was running under.  Ordinarily, the
retrieval of timestamp information is suppressed to conserve memory and
bandwidth.  To turn on timestamps, call the *timestamps()* method with a
true value.  You can retrieve the current value of the setting by calling
the method with no arguments.

   Note that activating timestamps disables some of the speed
optimizations in AcePerl.  Thus they should only be activated if you
really need the information.

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:

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

error() method
--------------

     Ace->error;

   This returns the last error message.  Like UNIX errno, this variable is
not reset between calls, so its contents are only valid after a method
call has returned a result value indicating a failure.

   For your convenience, you can call error() in any of several ways:

     print Ace->error();
     print $db->error();  # $db is an Ace database handle
     print $obj->error(); # $object is an Ace::Object

   There's also a global named $Ace::Error that you are free to use.

THE LOW LEVEL C API
===================

   Internally Ace.pm makes C-language calls to libace to send query
strings to the server and to retrieve the results.  The class that exports
the low-level calls is named Ace::AceDB.

   The following methods are available in Ace::AceDB:

new($host,$port,$query_timeout)
     Connect to the host $host at port $port. Queries will time out after
     $query_timeout seconds.  If timeout is not specified, it defaults to
     120 (two minutes).

     If successful, this call returns an Ace::AceDB connection object.
     Otherwise, it returns undef.  Example:

          $acedb = Ace::AceDB->new('localhost',200005,5)
                   || die "Couldn't connect";

     The Ace::AceDB object can also be accessed from the high-level Ace
     interface by calling the ACE::db() method:

          $db = Ace->new(-host=>'localhost',-port=>200005);
          $acedb = $db->db();

query($request)
     Send the query string $request 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:

          $acedb->query("find Sequence D*");
          die "Got an error ",$acedb->error() if $acedb->status == STATUS_ERROR;
          while ($acedb->status == STATUS_PENDING) {
             $result .= $acedb->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()
     Returns a more detailed error code supplied by the Ace server.  Check
     this value when STATUS_ERROR has been returned.  These constants are
     also exported by default.  Possible values:

          ACE_INVALID
          ACE_OUTOFCONTEXT
          ACE_SYNTAXERROR
          ACE_UNRECOGNIZED

     Please see the ace client library documentation for a full description
     of these error codes and their significance.

encore()
     This method may return true after you have performed one or more
     read() operations, and indicates that there is more data to read.  You
     will not ordinarily have to call this method.

BUGS
====

   1. The ACE model should be consulted prior to updating the database.

   2. There is no automatic recovery from connection errors.

   3. Debugging has only one level of verbosity, despite the best of
intentions.

   4. Performance is poor when fetching big objects, because of many
object references that must be created.  This could be improved.

   5. When called in an array context at("tag[0]") should return the
current tag's entire column.  It returns the current subtree instead.

   6. There is no way to add comments to objects.

   7. When timestamps are active, many optimizations are disabled.

   8. Item number eight is still missing.

SEE ALSO
========

   *Note Ace/Object: Ace/Object,, *Note Ace/Local: Ace/Local,, *Note
Ace/Model: Ace/Model,, *Note Ace/Sequence: Ace/Sequence,,*Note
Ace/Sequence/Multi: Ace/Sequence/Multi,.

AUTHOR
======

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

   Copyright (c) 1997-1998 Cold Spring Harbor Laboratory

   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.