/ 
Spectrum-CLI-1.016
River stage zero No dependents
/ Spectrum::CLI

NAME

Spectrum::CLI - wrapper class for the Spectrum Command Line Interface

SYNOPSIS

use Spectrum::CLI;

see METHODS section below

DESCRIPTION

Spectrum::CLI is class which intends to provide a convenient way to invoke the various CLI commands of Spectrum Enterprise Manager from within perl scripts.

In the author's estimation, the two primary benefits of Spectrum::CLI are:

  • the parsing of "show" command results

    Spectrum::CLI intelligently parses of the output of CLI "show" commands. That is, it will split apart the columnar values for you, and return them as an array of hashes, each element representing one line of output.

  • the elimination of "SpecHex" numbers in scripts

    Because of the aforementioned results parsing, it is now easy to mention spectrum data objects by name rather than by their hexadecimal Handle or Id. For instance, the following one=liner will create a hash of models by model name:

    map { $Model{$_->{MName}} = $_ } Spectrum::CLI->new->show_models;

    This would subsequently enable one to refer to a model's handle like this:

    my $handle = $Model{Universe}{MHandle};

    In this way, scripts can be written which discover all SpecHex magic numbers, and are, therefore, more readable and potentially more portable/reusable amongst Spectrum installations.

METHODS

new - create a new Spectrum::CLI object
 $obj = Spectrum::CLI->new([VNM_Name,]
                           [SPECROOT,]
                           [ {
                              [verbose => 1,]
                              [Verbose => 1,]
                              [CLISESSID => $sessid,]
                              [CLIMNAMEWIDTH => $width,]
                              [VNMSHRCPATH => $path,]
                              [localhostname => $localname,]
                              [timeout => $seconds,]
                           } ]);

my $cli = new Spectrum::CLI;

This is the class' constructor - it returns a Spectrum::CLI object upon success or undef on failure. Its arguments are optional, and may occur in any order. In general, it can be called with no arguments unless the SPECROOT environment variable is not set, or one wishes to connect to a SpectroSERVER on another host (i.e. the script is not running on the VNM host).

The optional constructor arguments are:

VNM name

You may pass a string specifying the name of the VNM machine where the SpectroSERVER to which you'd like to connect resides. (This is passed to the as the first argument to the "connect" command.)

SPECROOT value

You may pass a string specifying the absolute path to the "vnmsh" directory. It should point to a directory which contains the "vnmsh" sub-directory. (It is not necessary to pass this argument if either the SPECROOT or SPEC_ROOT environment variables are set.)

options hashref

A hash reference may also be passed as an argument. The hash can be used to specify a number of options. These include:

verbose

Passing { verbose => 1 } will cause the package to report errors from the CLI commands to STDERR. This feature can also be enabled by calling the "verbose" object method with a non-zero argument after the constructor returns successfully with that object.

Verbose

Primarily for use while debugging, passing { Verbose => 1 } will cause the package to report what it is doing, such as which CLI command it is about to execute. This feature can also be enabled by calling the "Verbose" object method with a non-zero argument after the constructor returns successfully with that object.

CLISESSID

Passing { CLISESSID => value } will cause Spectrum::CLI to use that value as the session id. Normally, in the absence of this option, the perl script's process id is used. Use of this option is discouraged unless the default value is somehow problematic.

CLIMNAMEWIDTH

Passing { CLIMNAMEWIDTH => value } will cause Spectrum::CLI to use that value as the model name width for CLI "show" commands. Normally, in the absence of this option, the value 1024 is used. Use of this option is discouraged unless the default value is somehow problematic.

VNMSHRCPATH

Passing { VNMSHRCPATH => value } will cause Spectrum::CLI to use that value as the full path to the configuration file for the CLI. Normally, in the absence of this option, the value "$SPECROOT/vnmsh/.vnmshrc" is used. Use of this option is discouraged unless the default value is somehow problematic.

localhostname

Passing { localhostname => value } will cause Spectrum::CLI to use that value as the IP address or resolvable hostname to determine whether or not the local VnmShd is running. (If VnmShd is not running, the constructor will attempt to launch it.) Normally, in the absence of this option, the return value from Sys::Hostname::hostname is used. Use of this option is discouraged unless the default value is somehow problematic. (That should probably never happen as currently VnmShd seems to bind(2) and listen(2) at the address associated with the system's hostname.)

timeout

Passing { timeout => value } will cause Spectrum::CLI to use that value as the number of seconds to sleep before attempting to connect to the VnmShd that it just launched. If the VnmShd is already running (when the constructor is called) this timeout is not used. Perhaps in the future this timeout will be use for other things as well. Normally, in the absence of this option, the value of 5 seconds will be used. Use of this option is discouraged unless the default value is somehow problematic.

show_*
# show_types:
map { $Type{$_->{Name}} = $_ } $cli->show_types;

# show_attributes:
map {
   $UserAttr{$_->{Name}} = $_
} $cli->show_attributes("mth=$Type{User}{Handle}");

# ...

These methods invoke the CLI "show" command. They return an array of hashes where the hash keys are the column headings from the first line of output of the corresponding CLI command, and the values are the corresponding value in that column for the given row.

seek
   @results = $obj->seek("attr=attribute_id,val=value",
			 [lh=landscape_handle]);

This method invokes the CLI "seek" command. It returns values in a like the "show" methods.

create_*, destroy_*, etc.
# create_model:
$cli->create_model("mth=$Type{User}{Handle}",
         "attr=$UserAttr{Model_Name}{Id},val=joe",
         "attr=$UserAttr{User_Full_Name}{Id},val='Joe User'");

ALL of the other CLI commands are available as methods. The return value(s) of these methods differs markedly from that of the aforementioned show_* or seek methods. This is because these methods do not normally produce columnar output, but instead produce messages which sometimes include some useful piece of information. For instance, "create model" produces a message upon success, which indicates the model handle of the create model. The caller will nearly always want to obtain that handle, which can be done by parsing the returned values. (See the results method for a hint at how to do this.)

In an array context these methods return an array in which the first element is the exit status (i.e. zero indication success) of the underlying CLI command. The subsequent elements of the returned array are the standard output and standard error (if any) lines produced by the underlying CLI command.

In a scalar context these methods return non-zero if the command succeeds, zero otherwise.

Regardless of the context in which they are invoked, these methods cause the objects internal status and results to be set. If it is more convenient, these values can be retrieved using the status and results methods rather than having to collect them as return values.

dir
print $obj->dir;

this method returns the absolute path to the directory containing the vnmsh commands.

verbose
$obj->verbose(1);
print $obj->verbose;

This method returns a boolean value indicating whether or not verbose behavior is currently turned on.

If a zero or non-zero argument is passed it will either clear or set this feature, respectively.

Verbose
$obj->Verbose(1);
print $obj->Verbose;

This method returns a boolean value indicating whether or not "very verbose" behavior is currently turned on.

If a zero or non-zero argument is passed it will either clear or set this feature, respectively.

results
@results = $obj->results;

This method returns an array containing the results (standard output and standard error) of the last vnmsh command that was executed.

The results method is extremely useful to determine things such as the model handle of the model that was created by a call to create_model. For instance:

if ($obj->create_model("mth=$T{User}{Handle}",
             "attr=$A{Model_Name}{Id},val=joe",
             "attr=$A{User_Full_Name}{Id},val='Joe User'")) {
   printf "created model: %s\n", model_handle($obj->results)
}

sub model_handle {
   my $mh;
   grep { m/(0x[0-9A-Fa-f]+)$/ && ($mh = $&)} @_;
   return $mh
}
status
if (0 != ($status = $obj->status)) {
   printf("the previous vnmsh command failed: %d\n", $status)
}

This method returns the exit status of the last vnmsh command that was executed.

IMPLEMENTATION

Spectrum::CLI is a perl AutoLoader. As such, there is no explicit definition of each method that corresponds to a CLI command. Instead, this module "discovers" which commands are available in the vnmsh directory, and invokes them based on the called method name as determined at run time.

Theoretically, this has at least two advantages:

  • If new CLI commands or options are ever introduced, they will magically appear as part of this API and perhaps even behave as expected. This is especially likely if the output and return values are like those of the current commands.

  • This module is relatively terse. It would have been much more work to create and maintain if a seperate method needed to be written for each and command and argument combination.

AUTHOR

Dave Plonka <plonka@doit.wisc.edu>

Copyright (C) 1999-2003 Dave Plonka. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

SEE ALSO

perl(1).