Ingres::Utility::IINamu - API to C<iinamu> Ingres RDBMS utility

Ingres-Utility-IINamu documentation Contained in the Ingres-Utility-IINamu distribution.

Index

Code Index:

NAME

Top

Ingres::Utility::IINamu - API to iinamu Ingres RDBMS utility

VERSION

Top

Version 0.07

SYNOPSIS

Top

List registered INGRES (IIDBMS) services:

    use Ingres::Utility::IINamu;

    my $foo = Ingres::Utility::IINamu->new();

    # list all INGRES-type servers (iidbms)
    print $foo->show('INGRES');

    # process each server separately
    while (my @server = $foo->getServer()) {

	print "Server type: $server[0]\tname:$server[1]\tid:$server[2]";

	if (defined($server[3])) {

		print "\t$server[3]";

	}

	print "\n";

    }

    # stop IIGCN server (no more connections to all of Ingres services)
    $ret = $foo->stop();

    ...

DESCRIPTION

Top

This module provides an API to the iinamu utility for Ingres RDBMS, which provides local interaction and control of IIGCN server, in charge of registering all Ingres services.

Through this interface, it is possible to obtain a list of all registered services, for later processing (eg. iimonitor), and also stopping the IIGCN server (EXTREME CAUTION: Ingres may need to be restarted!).

FUNCTIONS

Top

new()

Create a new instance, checking environment prerequisites and preparing for interfacing with iinamu utility.

    $namu = Ingres::Utility::IINamu->new();
show(;$serverType)

Returns the output of SHOW command, and prepares for parsing the servers sequentially with getServer().

Takes one optional argument for the service: 'INGRES'(IIDBMS, default), 'COMSVR' (IIGCC), etc.

    print $namu->show('COMSVR'); # show IIGCN servers
getServer()

Returns sequentially (call-after-call) each server reported by show() as an array of 3~4 elements:

    # getServer()[0]: server type (INGRES, COMSVR, etc.)
    # getServer()[1]: server name (as registered with IINAMU or add() method)
    # getServer()[2]: server GCA address (given by INGSTART)
    # getServer()[3]: extra info

    $namu->show('INGRES'); # prepare to show all INGRES (IIDBMS ) servers

    while (@svrs = $namu->getServer()) {
        print "Server name: $svrs[1]\t address: $svrs[2]";
        print "\t($svrs[3])" if (defined $svrs[3]);
        print "\n"
    }
stop()

Shuts down the IIGCN daemon, making it no longer possible to stablish new connections to any Ingres service. After this, a total restart of Ingres will most probably be necessary.

    $namu->stop(); # no more connections (local remote, etc...)
add($serverType,$serverName,$serverAddr)

Register another server with IIGCN, so that it can be available to clients.

Parameters:

    # serverType: type of server (INGRES, COMSVR, etc.)
    # serverName: '*' or a name to individualize the server from the others
    # serverAddr: GCA address attributed during ingstart utility

    print $namu->add('COMSVR', '*', '123456'); # register IIGCN server
del($serverType,$serverName,$serverAddr)

Unregister another server with IIGCN, so that it will not be available to clients.

A server can be registered later again.

Parameters:

    # serverType: type of server (INGRES, COMSVR, etc.)
    # serverName: '*' or a name to individualize the server from the others
    # serverAddr: GCA address attributed during ingstart utility

    print $namu->del('COMSVR', '*', '123456'); # this one is not seen anymore.

DIAGNOSTICS

Top

Ingres environment variable II_SYSTEM not set

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

Ingres utility cannot be executed: _COMMAND_FULL_PATH_

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

Module Expect::Simple cannot be instanciated.

The Expect::Simple module could not be instanciated. The module is reponsible for interections with iinamu utility. Debugging will be required.

CONFIGURATION AND ENVIRONMENT

Top

Requires Ingres environment variables, such as II_SYSTEM and LD_LIBRARY_PATH.

See Ingres RDBMS documentation.

DEPENDENCIES

Top

Expect::Simple

INCOMPATIBILITIES

Top

None reported.

BUGS AND LIMITATIONS

Top

No bugs have been reported.

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

SUPPORT

Top

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

    perldoc Ingres::Utility::IINamu

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Ingres-Utility-IINamu

* CPAN Ratings

http://cpanratings.perl.org/d/Ingres-Utility-IINamu

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Ingres-Utility-IINamu

* Search CPAN

http://search.cpan.org/dist/Ingres-Utility-IINamu

ACKNOWLEDGEMENTS

Top

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

AUTHOR

Top

Joner Cyrre Worm <FAJCNLXLLXIH at spammotel.com>

LICENSE AND COPYRIGHT

Top

Copyright (c) 2006, Joner Cyrre Worm <FAJCNLXLLXIH at spammotel.com>. All rights reserved.

Ingres is a registered brand of Ingres Corporation.

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

DISCLAIMER OF WARRANTY

Top

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.

Ingres-Utility-IINamu documentation Contained in the Ingres-Utility-IINamu distribution. 
package Ingres::Utility::IINamu;

use warnings;
use strict;
use Expect::Simple;
use Carp;


our $VERSION = '0.07';


sub new() {
	my $class = shift;
	my $this = {};
	$class = ref($class) || $class;
	bless $this, $class;
	if (! defined($ENV{'II_SYSTEM'})) {
		carp "Ingres environment variable II_SYSTEM not set";
        return {};
	}
	my $iigcn_file = $ENV{'II_SYSTEM'} . '/ingres/bin/iinamu';
	
	if (! -x $iigcn_file) {
		carp "Ingres utility cannot be executed: $iigcn_file";
        return {};
	}
	$this->{cmd} = $iigcn_file;
	$this->{xpct} = new Expect::Simple {
				Cmd => $iigcn_file,
				Prompt => [ -re => 'IINAMU>\s+' ],
				DisconnectCmd => 'QUIT',
				Verbose => 0,
				Debug => 0,
				Timeout => 10
                } or do {
                    carp "Module Expect::Simple cannot be instanciated.";
                    return {};
                };
	$this->{stream}    = '';
	$this->{streamPtr} = 0;
	$this->{svrType}   = '';
	return $this;
}


sub show(;$) {
	my $this = shift;
	my $server_type = uc (@_ ? shift : 'INGRES');
	#print $this . ": cmd = $cmd";
	my $obj = $this->{xpct};
	my $cmd = 'SHOW ' . $server_type;
	$obj->send($cmd);
	my $before = $obj->before;
	while ($before =~ /\ \ /) {
		$before =~ s/\ \ /\ /g;
	}
	my @antes = split(/\r\n/,$before);
	if ($#antes >= 0) {
		if ($antes[0] eq $cmd) {
			shift @antes;
		}
	}
	$this->{stream}    = join($/,@antes);
	$this->{streamPtr} = 0;
	$this->{svrType}   = $server_type;
	return $this->{stream};
}


sub getServer() {
	my $this = shift;
	if (! $this->{stream}) {
		return ();
	}
	my @antes = split($/,$this->{stream});
	if ($#antes < $this->{streamPtr}) {
		$this->{streamPtr} = 0;
		return ();
	}
	my $line = $antes[$this->{streamPtr}++];
	return split(/\ /, $line);
}


sub stop() {
	my $this = shift;
	my $obj = $this->{xpct};
	$obj->send( 'STOP');
	my $before = $obj->before;
	while ($before =~ /\ \ /) {
		$before =~ s/\ \ /\ /g;
	}
	my @antes = split(/\r\n/,$before);
	return;
}


sub add($$$) {
	my $this = shift;
	my $server_type = uc (@_ ? shift : '');
	my $server_name = @_ ? shift : '';
	my $server_addr = @_ ? shift : '';
	my $obj = $this->{xpct};
    my $cmd = "ADD $server_type $server_name $server_addr";
	$obj->send($cmd);
	my $before = $obj->before;
	while ($before =~ /\ \ /) {
		$before =~ s/\ \ /\ /g;
	}
	my @antes = split(/\r\n/,$before);
	return $before;
}


sub del($$$) {
	my $this = shift;
	my $server_type = uc (@_ ? shift : '');
	my $server_name = @_ ? shift : '';
	my $server_addr = @_ ? shift : '';
	my $obj = $this->{xpct};
    my $cmd = "DEL $server_type $server_name $server_addr";
	$obj->send($cmd);
	my $before = $obj->before;
	while ($before =~ /\ \ /) {
		$before =~ s/\ \ /\ /g;
	}
	my @antes = split(/\r\n/,$before);
	return $before;
}


1; # End of Ingres::Utility::IINamu
__END__