IPC::XPA - Interface to the XPA messaging system
use IPC::XPA; $xpa = IPC::XPA->Open(); $xpa = IPC::XPA->Open(\%mode); $xpa = IPC::XPA->nullXPA; %res = $xpa->Get( $template, $paramlist ); %res = $xpa->Get( $template, $paramlist, \%attrs ); %res = $xpa->Set( $template, $paramlist ); %res = $xpa->Set( $template, $paramlist, $buf ); %res = $xpa->Set( $template, $paramlist, $buf, \%attrs ); %res = $xpa->Set( $template, $paramlist, \%attrs ); %res = $xpa->Info( $template, $paramlist ); %res = $xpa->Info( $template, $paramlist, \%attrs ); %res = IPC::XPA->Access( $template, $paramlist ); %res = IPC::XPA->Access( $template, $paramlist, \%attrs ); @res = IPC::XPA->NSLookup( $template, $type );
This class provides access to the XPA messaging system library, xpa, developed by the Smithsonian Astrophysical Observatory's High Energy Astrophysics R&D Group. The library provides simple inter-process communication via calls to the xpa library as well as via supplied user land programs.
xpa
The method descriptions below do not duplicate the contents of the documentation provided with the xpa library.
Currently, only the client side routines are accessible.
Unless otherwise specified, the following methods are simple wrappers around the similarly named XPA routines (just prefix the Perl routines with XPA).
XPA
$xpa = IPC::XPA->nullXPA;
This creates an xpa object which is equivalent to a NULL XPA handle as far as the underlying XPA routines are concerned. It can be used to create a default XPA object, as it it guaranteed to succeed (the Open() method may fail).
$xpa = IPC::XPA->Open(); $xpa = IPC::XPA->Open( \%mode );
This creates an XPA object. mode is a hash containing mode keywords and values, which will be translated into the string form used by XPAOpen(). The object will be destroyed when it goes out of scope; the XPAClose() routine will automatically be called. It returns undef upon failure.
mode
For example,
$xpa = IPC::XPA->Open( { verify => 'true' } );
$xpa->Close;
Close the XPA object. This is usually not necessary, as it will automatically be closed upon destruction.
%res = IPC::XPA->Access( $name [, $type] [, \%attr ] )
Returns a hash keyed off of the server names which match the specified name and access type. The hash values are references to hashes, which will have the key name, indicating the server's name (seems a bit redundant).
name
%attr is a hash with the following recognized keys:
%attr
The value for this element should be a hashref which will be flattened to provide the correct format for the actual XPA Access mode parameter.
This should be set to the maximum number of servers to return. It defaults to 1000.
See the XPA docs for more information. This may also be called as an object method.
@res = IPC::XPA->NSLookup( $template, $type )
This calls the XPANSLookup routine. It returns the results of the lookup as a list of references to hashes, one per server. The hashes have the keys name class, and method. For example,
class
method
use Data::Dumper; @res = IPC::XPA->NSLookup( 'ds9', 'ls' ); print Dumper(\@res);
results in
$VAR1 = [ { 'method' => '838e2ab4:46529', 'name' => 'ds9', 'class' => 'DS9' } ];
Note that names returned by NSLookup are different than those returned by the Set and Get methods; the latter return names which are essentially composites of the name and method keys.
This may also be called as an object method. See the XPA docs for more information the template and type specification.
template
type
The Set instance method (see "Instance Methods") can also be called as a class method, which is equivalent to calling XPASet() with a NULL handle to the xpa object.
NULL
%res = IPC::XPA->Set( $template, $paramlist );
The Get instance method (see "Instance Methods") can also be called as a class method, which is equivalent to calling XPAGet() with a NULL handle to the xpa object.
%res = IPC::XPA->Get( $template, $paramlist );
The Info instance method (see "Instance Methods") can also be called as a class method, which is equivalent to calling XPAInfo() with a NULL handle to the xpa object.
%res = IPC::XPA->Info( $template, $paramlist );
%res = $xpa->Set( $template, $paramlist ); %res = $xpa->Set( $template, $paramlist, $buf ); %res = $xpa->Set( $template, $paramlist, $buf, \%attrs ); %res = $xpa->Set( $template, $paramlist, \%attrs );
Send data to the XPA server(s) specified by $template. $xpa is a reference to an XPA object created by Open(). $paramlist specifies the command to be performed. If additional information is to be sent, the $buf parameter should be specified. The %attrs hash specifies optional parameters and values to be sent. The following are available:
Open()
The maximum number of servers to which the request should be sent. This defaults to 1.
1
The number of bytes in the buffer to be sent. If not set, the entire contents will be sent.
The value of this is a hash containing mode keywords and values, which will be translated into the string form used by XPASet().
It returns a hash keyed off of the server names. The hash values are references to hashes, which will contain the key name (duplicating the server name), and if there was an error, the key message. See the XPASet documentation for more information on the name and message values.
message
%res = $xpa->Set( 'ds9', 'mode crosshair' ); use Data::Dumper; %res = $xpa->Set( 'ds9', 'array [dim=100,bitpix=-64]', $buf, { mode => { ack => false } }); print Dumper \%res, "\n";
The latter might result in:
$VAR1 = { 'DS9:ds9 838e2ab4:65223' => { 'name' => 'DS9:ds9 838e2ab4:65223' }, };
%res = $xpa->Get( $template, $paramlist ); %res = $xpa->Get( $template, $paramlist, \%attrs );
Retrieve data from the servers specified by the $template parameter. $xpa is a reference to an XPA object created by Open(). The $paramlist indicates which data to return. The %attrs hash specifies optional parameters and values to be sent. The following are available:
The value of this is a hash containing mode keywords and values, which will be translated into the string form used by XPAGet()
It returns a hash keyed off of the server names. The hash values are references to hashes, which will have the keys name, indicating the server's name, and buf which will contain the returned data. If there was an error, the hashes will also contain the key message. See the XPAGet documentation for more information on the name and message values.
buf
use Data::Dumper; %res = $xpa->Get( 'ds9', '-help quit' ); print Dumper(\%res);
might result in
$VAR1 = { 'DS9:ds9 838e2ab4:46529' => { 'name' => 'DS9:ds9 838e2ab4:46529', 'buf' => 'quit: -- exit application' } };
%res = $xpa->Info( $template, $paramlist); %res = $xpa->Info( $template, $paramlist, \%attrs );
Send a short message (in $paramlist) to the servers specified in the $template parameter. $xpa is a reference to an XPA object created by Open(). The %attrs hash specifies optional parameters and values to be sent. The following are available:
It returns a hash keyed off of the server names. The hash values are references to hashes, which will contain the the key name, indicating the server's name. If there was an error or the server replied with a message, the hashes will also contain the key message. See the XPAGet documentation for more information on the name and message values.
The XPA library is available at http://hea-www.harvard.edu/RD/xpa/.
http://hea-www.harvard.edu/RD/xpa/
This software is released under the GNU General Public License. You may find a copy at
http://www.fsf.org/copyleft/gpl.html
Diab Jerius ( djerius@cfa.harvard.edu )
perl(1).
To install IPC::XPA, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IPC::XPA
CPAN shell
perl -MCPAN -e shell install IPC::XPA
For more information on module installation, please visit the detailed CPAN module installation guide.