ANNOUNCE: new module: Ingres::Utility::IIMonitor

Ingres::Utility::IIMonitor (apdOp) API to IIMONITOR Ingres RDBMS
utility

This module has been accepted in CPAN's Official Module List and is the
second module of a framework to interact with and administrate local
services of Ingres RDBMS through an object-oriented API.

The API implements as similar as possible all commands accepted by each
of Ingres' utilities.

Together with Ingres::Utility::IINamu
(http://search.cpan.org/~WORM/Ingres-Utility-IIMonitor-0.13/ ),
it provides the basis for most daily sysadmin tasks for Ingres
services.

A very handy feature is the parsing of user and system sessions (SHOW
SESSIONS) into hashes, what makes it very easy to inspect and control
those sessions.

The whole framework will provide the basis to develop powerful and
friendly tools, but each module can be easily employed by simple Perl
scripts to automate sysadmin daily tasks.

The project is hosted at Sourceforge.net:
http://www.sourceforge.net/projects/ingres-utility/

The module is hosted also on CPAN:
http://search.cpan.org/~WORM/Ingres-Utility-IIMonitor-0.13/

Here is the POD (abriged):

NAME
Ingres::Utility::IIMonitor - API to "iimonitor" Ingres RDBMS
utility

VERSION
Version 0.13

SYNOPSIS
use Ingres::Utility::IIMonitor;

# create a connection to an IIDBMS server
# (server id can be obtained through Ingres::Utility::IINamu)
$foo = Ingres::Utility::IIMonitor->new($serverid);

# showServer() - shows server status
#
# is the server listening to new connections? (OPEN/CLOSED)
$status =$foo->showServer('LISTEN');
#
# is the server being shut down?
$status =$foo->showServer('SHUTDOWN');

# setServer() - sets server status
#
# stop listening to new connections
$status =$foo->setServer('CLOSED');
#
# start shutting down (wait for connections to close)
$status =$foo->setServer('SHUT');

# stop() - stops IIDBMS server (transactions rolled back)
#
$ret = $foo->stop();

# showSessions($target,$mode) - prepares to get sessions info
print $foo->showSessions('SYSTEM','FORMATTED');

# getSession() - get sessions call-after-call from previous
showSessions()
while (%session = $foo->getSession()) {
print "Session ". $session{'SESSION_ID'} . ":\n"
foreach $label, $value (%session) {
print "\t$label:\t$value\n" if ($label ne
'SESSION_ID');
}
}

DESCRIPTION
This module provides an API to the iimonitor utility for Ingres
RDBMS,
which provides local control of IIDBMS servers and sessions (system
and
user conections).

METHODS
"new($serverId)"
Constructor, connects to an IIDBMS server through iimonitor
utility.

Takes the server id as argument to identify which server to
control.

$iimonitor = Ingres::Utility::IIMonitor->new(12345);

The server id can be obtained through Ingres::Utility::IINamu
module.

"showServer($serverStatus)"
Returns the server status.

Takes the server status to query:

LISTEN = server listening to new connections

SHUTDOWN = server waiting for connections to close to end
process.

Returns 'OPEN', 'CLOSED' or 'PENDING' (for shutdown).

"setServer($serverStatus)"
Changes the server status to the state indicated by the
argument:

SHUT = server will shutdown after all connections are closed

CLOSED = stops listening to new connections

OPEN = reestablishes listening to new connections

"stopServer()"
Stops server immediatly, rolling back transactions and closing
all
connections.

"showSessions(;$target,$mode)"
Prepares to show info on sessions on IIDBMS server, for being
fetched later by getNextSession().

Returns the output from iimonitor.

Takes the following parameters: [], []

TARGET = Which session type: USER (default), SYSTEM or ALL
MODE = Which server info: FORMATTED, STATS. Default is a
short format.

"getSession()"
Returns sequentially (call-after-call) each session reported by
showSessions() as a hash of as many elements as returned by
each
session target and mode, where the key is the name showed on
labels
of iimonitor's output, all uppercase and spaces translated into
underscores (_).

Unlabeled info gets its key from the previously labeled field
appended by '_#', where index is the sequential order
(starting by 0) on which the info appeared.

This way, all info is in pairs of (LABEL,VALUE), whithout
parenthesis or trailing spaces.

UFO - Unidentified Format Output - will be translated into
words
forming pairs of labels and values, PLEASE REPORT THIS, because
this
is not expected to happen. Meanwhile see what you can do with
these
pairs, and will probably need extra parsing. If you report
this,
there's hope they will be properly handled on the next version.

DEPENDENCIES
Expect::Simple

SUPPORT
You can find documentation for this module with the perldoc
command.

perldoc Ingres::Utility::IIMonitor

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation


* CPAN Ratings


* RT: CPAN's request tracker



* Search CPAN


ACKNOWLEDGEMENTS
Thanks to Computer Associates (CA) for licensing Ingres as open
source,
and let us hope for Ingres Corp to keep it that way.

AUTHOR
Joner Cyrre Worm ""

LICENSE AND COPYRIGHT
Copyright (c) 2006, Joner Cyrre Worm " spammotel.com>".
All rights reserved.

Ingres is a registered brand of Ingres Corporation.

This module is free software; you can redistribute it and/or modify
it
under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS
WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
LIABLE
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR
A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN
IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH
DAMAGES.