RIV::Param Constructor

Constructor

$param = RIV::Param::new([\%paramHash,\@usageStrings, \$helpMessage])

Parameters

\%paramHash

Specifies a reference to a hash used to specify application-specific command line arguments. Each hash key (index) represents a command line switch and its associated hash value is an array with the following elements:

• element 0 — Is a flags element that specifies a bitwise OR that indicates:
  • Whether the command line switch takes an argument.
  • Whether the switch is mandatory

  The flags element makes use of the package constants described in Package Constants.

• element 1 — Is a scalar variable reference or undef value. You initialize the scalar variable reference with the appropriate value (a parameter from the command line or 1).

The \%paramHash parameter is optional.

\$usageStringsRef

This is an array reference that contains an element for each of the non-standard command line argument scenarios. If the application takes only standard arguments, this constructor argument should be set to undef.

By default, the usage message has the standard arguments appended to it (-domain, -debug, -latency, -messageLevel, -help). If the application does not accept all of these, or you do not want to print them, then include an element in the array with the value nostdargs. This element will not be printed, but will prevent the usage message from listing the standard arguments.

\$helpMessage

Specifies a string reference that contains explanatory information that is written to standard output, in addition to standard help information, when the -help command line argument is specified.

The \$helpMessage parameter is optional.

$dieOnUnknownArgs

This is an optional scalar. If present and true, and if the command line (@ARGV) contains any parameters that are not in \%paramHashRef or the default set of accepted parameters, this causes the constructor to fail (return undef). If this parameter is not present or is false, the constructor silently ignores any unrecognized parameters, because some callers prefer to do a part of their own command-line processing.

Package Constants

These constants are bit masks that can be ORed together where appropriate.

For example, RivParamMandatory | RivParamSingleArg specifies a mandatory parameter that requires a single argument.

Description

The RIV::Param constructor creates and initializes a new RIV::Param object from the application-specific command line arguments specified in the \%paramHash parameter. Each new RIV::Param object also encapsulates the supported standard command line arguments. Thus, Network Manager client/server and Agent applications can make use of these standard command line arguments in addition to the application-specific command line arguments.

If you call the RIV::Param constructor without specifying any of the optional parameters, the new RIV::Param object provides access to the standard command line arguments.

Example Usage No Parameters

The following code shows a call to the RIV::Param constructor without specifying any of the optional parameters. The newly created RIV::Param object is then passed to the RIV::Agent constructor, which returns a RIV::Agent object that provides a discovery agent application session. In this example, the discovery agent called PerlDetails (the name specified in the second parameter of the RIV::Agent constructor) can make use of the standard command line arguments.

.
.
.
sub Init{
    my $param=RIV::Param::new();
    $agent=RIV::Agent::new($param,"PerlDetails");
}
.
.
.

Example Usage Three Parameters

The example described in this section shows a call to the RIV::Param constructor that specifies the three optional parameters.

The following code defines a reference to a hash called %CmdLineArgs used to specify application-specific command line arguments. The %CmdLineArgs hash is passed as the first parameter to the RIV::Param constructor:

.
.
.
my $subject;
my $process = 'Model';
my $messageClass = 'NOTIFY';
my $verbose;
my %CmdLineArgs = (
    "-subject"  => [ RivParamSingleArg , \$subject ],
    "-process"  => [ RivParamSingleArg , \$process ],
    "-messageClass"  => [ RivParamSingleArg , \$messageClass ],
    "-verbose"  => [ RivParamNoArg,     \$verbose ]
);
.
.
.

The following list provides brief descriptions of the application-specific command line arguments defined in the %CmdLineArgs hash.

The following code defines a usage string called @Usage that provides information on how to use the command line for this application. The @Usage array is passed as the second parameter to the RIV::Param constructor:

.
.
.
my @Usage = (
    "[-subject <subject> -process [Model|Disco|Ctrl|...] 
     -messageClass [NOTIFY|QUERY|...] "
);
.
.
.

The following code defines a string reference called $helpData that contains explanatory information about the application-specific command line arguments and other pertinent information. The explanatory information also includes descriptions of the standard command line arguments (-domain, -debug, and -help). The $helpData string reference is passed as the third parameter to the RIV::Param constructor:

my $helpData = "\n
The ITListener perl script is intended to listen on the supplied subject
and print out the messages received. 

The arguments are
-domain <domain> = Name of the domain to retrieve data from
-debug [0-4] = Required debug level
-help = This information
-verbose = Explicitly print out details of nested fields
-subject = The specific subject to listen to ( this will not include the domain )
-process = The process to listen to ( e.g. Model, Class, Event, Config, Ctrl , 
           Disco , PingFinder )
-messageClass = The class of messages of interest. Not all processes support 
all classes. The common ones of interest are NOTIFY, QUERY, STATUS

The most common arguments to use are
-process Model -messageClass NOTIFY : ( default ) - Listen for the models 
 updates on topology changes (old style)
-process Model -messageClass TOPOLOGY : ( default ) - Listen for the models 
 updates on topology changes (new style)
-process Disco -messageClass STATUS : - Listen to disco broadcasts on the 
 current state of the discovery.
-process DNCIM2NCIM -messageClase NOTIFY : - Listen to Disco to Model 
 DNCIM2NCIM updates.
-process ITNMSTATUS -messageClass NOTIFY : - Listen to ITNM status events.

The process is capable of listening on any subject on the message broker bus 
but will not decode the output beyond printing out the contents of the message.

The syntax for message broker subjects is 

    /<subject>/<sub-subject>/<sub-sub-subject>/....

All ITNM IP subjects begin \'ITNM/\' and have the domain appended so the
model notify subject for domain TESTDOMAIN is

    /ITNM/MODEL/NOTIFY/TESTDOMAIN



\n";

The following code shows the call to the RIV::Param constructor using the three previously defined parameters: \%CmdLineArgs, \@Usage, and \$helpData. Note the call to the die function to exit the script if the RIV::Param constructor fails to create a new RIV::Param object.

.
.
.
my $param = RIV::Param::new(\%CmdLineArgs, \@Usage, \$helpData);
die "Can't create RIV::Param" unless (defined $param);
.
.
.

Returns

Upon completion, the RIV::Param constructor returns a new RIV::Param object.

See Also

• RIV::Agent Constructor
• RIV::App Constructor
• Usage
• RIV::Param module overview