NAME

Net::Z3950::Manager - State manager for multiple Z39.50 connections.

SYNOPSIS

        $mgr = new Net::Z3950::Manager(async => 1);
        $conn = $mgr->connect($hostname, $port);
        # Set up some more connections, then:
        while ($conn = $mgr->wait()) {
                # Handle message on $conn
        }

DESCRIPTION

A manager object encapsulates the Net::Z3950 module's global state - preferences for search parsing, preferred record syntaxes, compiled configuration files, etc. - as well as a list of references to all the open connections. It main role is to handle multiplexing between the connections that are opened on it.

We would normally expect there to be just one manager object in a program, but I suppose there's no reason why you shouldn't make more if you want.

Simple programs - those which therefore have no requirement for multiplexing, perhaps because they connect only to a single server - do not need explicitly to create a manager at all: an anonymous manager is implicitly created along with the connection.

METHODS

`new()`

        $mgr = new Net::Z3950::Manager();

Creates and returns a new manager. Any of the standard options may be specified as arguments; in addition, the following manager-specific options are recognised:

async: This is 0 (false) by default, and may be set to 1 (true). The mode affects various details of subsequent behaviour - for example, see the description of the Net::Z3950::Connection class's new() method.

`option()`

        $value = $mgr->option($type);
        $value = $mgr->option($type, $newval);

Returns $mgr's value of the standard option $type, as registered in $mgr or in the global defaults.

If $newval is specified, then it is set as the new value of that option in $mgr, and the option's old value is returned.

`connect()`

        $conn = $mgr->connect($hostname, $port);

Creates a new connection under the control of the manager $mgr. The connection will be forged to the server on the specified $port of <$hostname>.

Additional standard options may be specified after the $port argument.

(This is simply a sugar function to Net::Z3950::Connection-new()>)

`wait()`

        $conn = $mgr->wait();

Waits for an event to occur on one of the connections under the control of $mgr, yielding control to any other event handlers that may have been registered with the underlying event loop.

When a suitable event occurs - typically, a response is received to an earlier INIT, SEARCH or PRESENT - the handle of the connection on which it occurred is returned: the handle can be further interrogated with its op() and related methods.

If the wait times out (only possible if the manager's timeout option has been set), then wait() returns an undefined value.

`connections()`

        @conn = $mgr->connections();

Returns a list of all the connections that have been opened under the control of the manager $mgr and have not subsequently been closed.

`resultSets()`

        @rs = $mgr->resultSets();

Returns a list of all the result sets that have been created across the connections associated with the manager $mgr and have not subsequently been deleted.

AUTHOR

Mike Taylor <mike@indexdata.com>

First version Tuesday 23rd May 2000.