/ 
Ingres-Utility-IIMonitor-0.13
River stage zero No dependents
/ Ingres::Utility::IIMonitor

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>], [<MODE>]

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 '_#<index>', 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.

DIAGNOSTICS

parameter missing: serverId

Call to method new() is missing the serverId argument to indicate the IIDBMS to connect to.

Ingres environment variable II_SYSTEM not set

Ingres environment variables should be set in the user session running this module. II_SYSTEM provides the root install dir (the one before 'ingres' dir). LD_LIBRARY_PATH too. See Ingres RDBMS docs.

Ingres utility cannot be executed: _COMMAND_FULL_PATH_

The IIMONITOR command could not be found or does not permits execution for the current user.

parameter missing: serverStatus

Call to method setServer() is missing the serverStatus argument.

invalid status: (_SERVER_STATUS_PARAM_)

The showServer() or setServer() methods received an invalid argument.

invalid target: (_TARGET_)

The showServer() takes the first argument only as USER/SYSTEM/ALL.

invalid mode: (_MODE_)

The showServer() takes the second or only one argument only as FORMATTED/STATS.

invalid paramter after _TARGET_: (_PARAMETER_)

If showServer() takes the first as FORMATTED/STATS then no other parameter is accepted.

CONFIGURATION AND ENVIRONMENT

Requires Ingres environment variables, such as II_SYSTEM and LD_LIBRARY_PATH.

See Ingres RDBMS documentation.

DEPENDENCIES

Expect::Simple

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-ingres-utility-iimonitor at rt.cpan.org, or through the web interface at http://rt.cpan.org.

SUPPORT

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

perldoc Ingres::Utility::IIMonitor

You can also look for information at:

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 <FAJCNLXLLXIH at spammotel.com>

LICENSE AND COPYRIGHT

Copyright (c) 2006, Joner Cyrre Worm <FAJCNLXLLXIH at 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.