Perl User's Guide for STAF Version 3
Last Updated: March 3, 2006
Table of Contents
1.0 Introduction
2.0 Installation
3.0 Package PLSTAF
4.0 Package STAFMon
4.1 Monitor Service Variables
4.2 Procedural Style
4.2.1 STAF::Monitor::Log
4.3 Object-Oriented Style
4.3.1 STAF::STAFMonitor::new
4.3.2 STAF::STAFMonitor::log
4.3.3 STAF::STAFMonitor::getSystemName
4.3.4 STAF::STAFMonitor::getServiceName
5.0 Package STAFLog
5.1 Log Service Return Codes
5.2 Procedural Style
5.2.1 STAF::Log::Init
5.2.2 STAF::Log::Log
5.3 Object-Oriented Style
5.3.1 STAF::STAFLog::new
5.3.2 STAF::STAFLog::log
5.3.3 STAF::STAFLog::getName
5.3.4 STAF::STAFLog::getLogType
5.3.5 STAF::STAFLog::getMonitorMask
5.3.6 STAF::STAFLog::getSystemName
5.3.7 STAF::STAFLog::getServiceName
This document describes STAF's V3 support for the Perl language. It
includes information on the core STAF Perl APIs as well as the wrappers
provided for the Monitor and Log services.
Notes:
- All of STAF's Perl APIs are provided in the STAF namespace.
- STAF Perl support is provided for Perl 5.0, 5.6, and 5.8
on Linux 32-bit and Perl 5.6 and 5.8 on Windows 32-bit platforms.
Note:
If you want to use a different version of Perl or if you want STAF Perl
support for a different operating system, you can either:
- Build STAF Perl support yourself. See the
STAF Developer's Guide
for more information on how to build the STAF perl project.
If you build STAF Perl support for a different operating system
and/or different Perl version, please contribute it to the STAF project.
To contribute it, browse the STAF Support Requests to see if someone else
has already provided STAF Perl support for this operating system and
Perl version combination. If not, open a STAF Support Request with
the "Summary" containing "STAF V3 Support for Perl x.x.x (Platform)",
replacing x.x.x with the Perl version and replacing Platform with the
operating system on which you built the support. Attach the necessary
files to the Support Request.
- Or, you can submit a
Support Request for us to build it for you (but it may take a while until we get a
chance to implement your request).
Be sure to check the existing STAF Support Requests as we may have already
provided STAF Perl support for the Perl version and operating system
that you want and attached it to an existing STAF Support Request.
To install STAF's Perl support on Windows or Linux 32-bit platforms,
select to install "Perl support" during the install.
It is installed by default for a "typical" install of STAF in the
following directories:
Linux:
{STAF/Config/STAFRoot}/bin/PLSTAF.pm
{STAF/Config/STAFRoot}/bin/STAF.pl
{STAF/Config/STAFRoot}/bin/STAF2.pl
{STAF/Config/STAFRoot}/bin/STAFMon.pm
{STAF/Config/STAFRoot}/bin/STAFLog.pm
{STAF/Config/STAFRoot}/docs/STAFPerl.htm
{STAF/Config/STAFRoot}/lib/perl50/libPLSTAF.so
{STAF/Config/STAFRoot}/lib/perl56/libPLSTAF.so
{STAF/Config/STAFRoot}/lib/perl58/libPLSTAF.so
Windows:
{STAF/Config/STAFRoot}/bin/PLSTAF.pm
{STAF/Config/STAFRoot}/bin/STAF.pl
{STAF/Config/STAFRoot}/bin/STAF2.pl
{STAF/Config/STAFRoot}/bin/STAFMon.pm
{STAF/Config/STAFRoot}/bin/STAFLog.pm
{STAF/Config/STAFRoot}/docs/STAFPerl.htm
{STAF/Config/STAFRoot}/bin/perl56/PLSTAF.dll
{STAF/Config/STAFRoot}/bin/perl58/PLSTAF.dll
The library file for the version of Perl that was selected as the default
Perl version during the
STAF installation (when using the Installshield installer) will either have
a link in {STAF/Config/STAFRoot}/lib (on Linux)
or a copy in {STAF/Config/STAFRoot}/bin on Windows.
Note:You need to add a "use" or "require"
statement in your Perl scripts for any of the STAF packages described below
(use loads modules at compile time whereas require loads modules
at run time).
Note: In order to have your Perl script find the specified module,
you may need to follow one, and only one, of these steps:
- Set environment variable PERLLIB to the directory containing the STAF Perl
modules (PLSTAF.pm, STAFMon.pm, STAFLog.pm). For example: C:\STAF\bin on
Windows or /usr/local/staf/lib for Unix.
- Copy your modules (PLSTAF.pm, STAFMon.pm, STAFLog.pm) to a standard Perl
directory such as /usr/local/lib/perl5 or
/usr/local/lib/perl5/site_perl.
- Run your Perl script using the -I <path/to/module> option
(e.g. perl -I /usr/local/staf/lib MyTest.pl)
- Add the line use lib 'path/to/module' before using the desired
module.
- Run your Perl script from the directory where your modules where installed
(e.g. from /usr/local/staf/lib or C:\STAF\bin)
The PLSTAF package provides the based level of support for Perl scripts
to call into STAF in two different programming styles, procedural or
object-oriented. This package externalizes the following classes,
functions, and constants.
The procedural style of communicating with STAF uses the following methods:
- STAF::Register - Allows you to register with STAF
(procedural)
- STAF::Submit - Allows you to submit requests to STAF
(procedural)
- STAF::UnRegister - Allows you to unregister with STAF
(procedural)
The object-oriented style of communicating with STAF uses the following
class:
- STAF::STAFHandle - The primary class for communicating
with STAF (object-oriented)
- new - Creates a handle that registers with STAF
- submit - Same as STAF::Submit but different calling convention
- unRegister - Same as STAF::UnRegister but different calling convention
Other STAF Perl classes that it externalizes are:
- STAF::STAFResult - A class representing the result
of a STAF request
- STAF::STAFMapClassDefinition - A class representing a map class definition
that can be used by STAF marshalling contexts
- STAF::STAFMarshallingContext - A class representing a STAF marshalling
context which is used to define structured data
Other STAF Perl functions that it externalizes are:
- STAF::WrapData (aka STAF::STAFUtil::WrapData)
- A method for creating colon-length-colon delimited strings for use in
STAF requests
- STAF::AddPrivacyDelimiters) -
A utility function for adding privacy delimiters to a string for use in
protecting private data specified in a STAF command option that supports
handling private data
- STAF::EscapePrivacyDelimiters -
A utility function for escaping privacy delimiters in a string
- STAF::RemovePrivacyDelimiters) -
A utility function for removing privacy delimiters from a string
- STAF::MaskPrivateData -
A utility function for masking private data
- STAF::STAFUnmarshall - A method for converting the string-based
marshalled representation back into a data structure
It returns a marshalling context
- STAF::STAFIsMarshalledData - A method that tests if a string
is a marshalled data string
Note that following two Perl functions are not yet available:
- A STAF::STAFMarshall method for converting a data structure into
a string-based representation is not yet provided.
- A STAF::STAFFormatObject method for "pretty printing"
an object such that it returns a string containing a verbose hierarchical
format.
Description
This function allows you to register with STAF. You must register
with STAF before you can use any of the other STAF related APIs. After
calling this function, 2 magic variables, $STAF::Handle and $STAF::RC
are created and set. These variables should not be modified directly. $STAF::Handle
contains the handle that will allow your program to interact with STAF.
$STAF::RC
is equivalent to the value returned by the API itself.
Syntax
STAF::Register(PROCESSNAME)
where,
PROCESSNAME is the name by which your Perl program will be
known
Result
The function returns a numeric return code. Zero indicates that you
registered successfully. Non-zero return codes are documented in
the STAF User's Guide.
Examples
$rc = STAF::Register("My program");
if ($rc != $STAF::kOk) {
print "Error registering with STAF, RC: $STAF::RC\n";
exit $rc;
}
print "My STAF handle: $STAF::Handle\n";
Description
This function allows you to submit requests to STAF. This is the
primary API that you will use when working with STAF. After calling this
function, 2 magic variables, $STAF::Result and $STAF::RC
are created and set. These variables should not be modified directly. $STAF::Result
contains the string-based result for this request. $STAF::RC is
equivalent to the value returned by the API itself.
Syntax
STAF::Submit(LOCATION, SERVICE, REQUEST)
where,
LOCATION is the system to which the request should be submitted.
"Local" may be used to represent the local system, i.e., the system on
which the Perl program is running.
SERVICE is the name of the service to which the request should
be submitted.
REQUEST is the actual request string itself.
Result
The function returns a numeric return code. Return codes are documented
in the STAF User's Guide.
Example
$rc = STAF::Submit("local", "ping", "ping");
if ($rc != $STAF::kOk) {
print "Error submitting ping request, RC: $STAF::RC\n";
if (length($STAF::Result) != 0) {
print "Additional info:
$STAF::Result\n";
}
exit $rc;
}
print "STAF Ping result: $STAF::Result\n";
Description
This function allows you to unregister with STAF. This allows STAF
to free up the information associated with your handle. This should
be the last STAF related API that you call in your program. After
calling this function, 1 magic variable, $STAF::RC is created
and set. This variables should not be modified directly. $STAF::RC
is equivalent to the value returned by the API itself.
Syntax
STAF::UnRegister()
Result
This function returns a numeric return code. Zero indicates that
you unregistered successfully. Non-zero return codes are documented
in the STAF User's Guide.
Example
Description
This method constructs a STAF::STAFHandle object that allows you to call
into STAF. You must create a STAF::STAFHandle object before you can
use any of its STAF related methods.
Syntax
STAF::STAFHandle->new(PROCESSNAME)
where,
PROCESSNAME is the name by which your Perl program will be
known.
Result
The method returns a STAF::STAFHandle object that contains a numeric
return code and a numeric handle (both scalar values). These 2 fields should
not be manipulated directly. A return code of zero indicates that you registered
successfully. Non-zero return codes are documented in the STAF User's
Guide.
Example
$handle = STAF::STAFHandle->new("My program");
if ($handle->{rc} != $STAF::kOk) {
print "Error registering with STAF, RC: $handle->{rc}\n";
exit $handle->{rc};
}
print "My STAF handle: $handle->{handle}\n";
Description
This method allows you to submit requests to STAF. This is the primary
method that you will use when working with STAF.
Syntax
STAF::STAFHandle->submit(LOCATION, SERVICE, REQUEST)
where,
LOCATION is the system to which the request should be submitted.
"Local" may be used to represent the local system, i.e., the system on
which the Perl program is running.
SERVICE is the name of the service to which the request should
be submitted.
REQUEST is the actual request string itself.
Result
The function returns a STAF::STAFResult object that contains a numeric
return code and a string-based result. Return codes are documented
in the STAF User's Guide.
The string-based result will contain the textual result buffer from
this request. See the individual service documentation for information
on the contents of this buffer.
Example
$result = $handle->submit("local", "ping", "ping");
if ($result->{rc} != $STAF::kOk) {
print "Error submitting ping request, RC: $result->{rc}\n";
if (length($result->{result}) != 0) {
print "Additional info:
$result->{result}\n";
}
exit $result->{rc};
}
print "STAF Ping result: $result->{result}\n";
Description
This method allows you to unregister with STAF. This allows STAF
to free up the information associated with your handle. This should
be the last STAF related API that you call in your program.
Syntax
STAF::STAFHandle->unRegister()
Result
This method returns a numeric return code. Zero indicates that you
unregistered successfully. Non-zero return codes are documented in
the STAF User's Guide.
Example
Definition
- class STAF::STAFResult
- This class encapsulates the result of a STAF service request (made via
the STAFHandle.submit() method). This class also contains a set of
constants representing the various common STAF return codes.
Class STAF::STAFResult defines the following methods:
- new(rc, result)
- Creates a new STAF::STAFResult object.
The required argument rc specifies the numeric return code
of the service request.
The required argument result specifies a string result buffer
returned from the service request.
Class STAF::STAFResult defines the following member variables. They are
initialized by the constructor, and should not be modified directly.
- rc
- An integer identifying the return code of the service request.
- result
- A string containing the result buffer returned from the service request.
Examples
You can create a new STAF::STAFResult object with an RC of 0 and
a result of "Successful" as follows:
The following example shows the use of the STAFResult class in calling
a STAF service.
# The variable "handle" is an instance of the STAFHandle class that was
# previously instantiated
$result = $handle->submit("local", "ping", "ping");
print "Ping request RC: $handle->{rc}\n";
print "Ping request result buffer: $result->{result}\n";
Definition
- STAF::WrapData(inputString)
- Returns a colon-length-colon delimited version of the input string.
This function is widely used to pass the values of options in STAF requests.
Note that STAF::STAFUtil::WrapData is an alias for the
STAF::wrapData function and can be used instead to call this
function.
Result
This function returns a string in colon-length-colon delimited format.
Example
my $message = "Hello World";
$result = $handle->submit(
"local", "monitor", "log message ".STAF::WrapData($message));
if ($result->{rc} == $STAF::kOk) {
print "Error logging message to Monitor,".
" RC: $result->{rc} Result: $result->{result}\n";
exit $result->{rc};
}
Definition
- STAF::AddPrivacyDelimiters(data)
- Adds privacy delimiters to a string and returns the updated string.
See
Section 7.3, "Private Data" in the STAF User's Guide for more
information about handling private data.
This method should be used by anyone who wants to protect private
data specified in a STAF command option that supports handling
private data.
Required argument data is a String that contains
data you want to protect.
Since: STAF V3.1.0
Result
Returns a String object containing the string with opening and
closing privacy delimiters added and escapes any privacy delimiters
already contained in the string with a caret (^).
If the string has length 0 or already has an unescaped opening privacy
delimiter at the beginning and an unescaped closing privacy delimiter
at the end, privacy delimiters are not added.
Examples:
- If the data is "passw0rd", this method
would return string "!!@passw0rd@!!".
- If the data is "Password: !!@secret@!!", this
method would return "!!@Password: ^!!@secret^@!!@!!".
Examples
This example adds privacy delimiters to "passw0rd" used in the
PASSWORD option when starting a process as another user.
This example adds privacy delimiters to password "secret" used in the
COMMAND option when starting a process.
my $password = "secret";
my $command = "C:/tests/admin -password ".STAF::AddPrivacyDelimiters($password);
my $request = "START COMMAND ".STAF::WrapData($command);
$result = $handle->submit("local", "PROCESS", request);
Definition
- STAF::EscapePrivacyDelimiters(data)
- Escapes all privacy delimiters (!!@ and @!!)
found in the data with a caret (^) and returns the updated string.
See
Section 7.3, "Private Data" in the STAF User's Guide for more
information about handling private data.
This method should be used before calling the addPrivacyDelimiters
method for data that needs to be protected but may contain
substrings !!@ and/or @!! that should not be
mistaken for privacy delimiters .
Required argument data is a String.
Since: STAF V3.1.0
Result
Returns a String object containing the string with privacy
delimiters, if any, escaped.
For example, if the data is "passw@!!d", this method
would return "passw^@!!d".
Examples
This example escapes privacy delimiters in password "passw@!!d"
before adding privacy delimiters to it and then uses the password
in the PASSWORD option when starting a process as another user.
my $password = "passw@!!d";
my $request = "START COMMAND C:/tests/TestA USERNAME Test1 PASSWORD".STAF::AddPrivacyDelimiters(STAF::EscapePrivacyDelimiters($password));
$result = $handle->submit("local", "PROCESS", request);
Definition
- removePrivacyDelimiters(data[,
numLevels])
- Removes privacy delimiters found in the data and returns the updated string.
See
Section 7.3, "Private Data" in the STAF User's Guide for more
information about handling private data.
Required argument data is a String that may contain
privacy delimiters (e.g. !!@, @!!).
Optional argument numLevels in an int that specifies
the number of levels of privacy data to remove. The default is 0
which indicates to remove all levels of privacy data.
Note that, generally, you'll want to remove all levels of privacy
delimiters.
Since: STAF V3.1.0
Result
Returns a String object containing the string with privacy
delimiters, if any, removed.
Examples:
- If the data is "!!@passw0rd@!!", this method
would return "passw0rd".
- If the data is "!!@passw^@!!d@!!", this method
would return "passw@!!d".
- If the data is "!!@Password=^!!@secret^@!!.@!!" and
the numLevels is 0, this method would return
"Password=secret".
- If the data is "!!@Password=^!!@secret^@!!.@!!" and
the numLevels is 1, this method would return
"Password=!!@secret@!!".
Examples
This example removes privacy delimiters from protected password
'!!@secret@!!' and assigns 'secret' as the password.
Definition
- STAF::MaskPrivateData(data)
- Masks any private data (enclosed between opening, !!@,
and closing, @!!, privacy delimiters) by replacing the
private data with asterisks.
See
Section 7.3, "Private Data" in the STAF User's Guide for more
information about handling private data.
Required argument data is a String that may contain
privacy delimiters (e.g. !!@, @!!).
Since: STAF V3.1.0
Result
Returns a String object containing the string with any private
data masked.
Examples:
- If the data is "!!@passw0rd@!!", this method
would return "**************".
- If the data is "testA -password !!@secret@!!",
this method would return "testA -password ************".
Examples
This example masks any private data indicated by privacy delimiters
in a request string before displaying it.
This example prints:
START COMMAND C:/tests/TestA.exe USERNAME Test1 PASSWORD **************
Definition
- STAF::STAFUnmarshall(data[,
context][,
flags])
- A function used to convert a string-based marshalled representation
specified by the keyword argument data back into a data structure.
It returns a marshalling context (from which you can get the data structure
via the STAF::STAFMarshallingContext class getRootObject()
function).
The required keyword argument data is a string to be unmarshalled.
The optional keyword argument context specifies the
STAF::STAFMarshallingContext object that should be used when
generating when unmarshalling the string. The default is None.
The optional keyword argument flags can be used to control
how to unmarshall the string.
When a string is unmarshalled into a data structure, it is possible
that one of the string objects that is unmarshalled is itself the
string form of another marshalled data structure.
The default is UNMARSHALLING_DEFAULTS which will recursively
unmarshall these nested objects.
Use IGNORE_INDIRECT_OBJECTS to disable this additional processing.
Example
This example submits a request to the FS service to query information
about a file. The request returns a marshalled data whose root object
is a map that contains keys like 'type', 'lowerSize', and
'lastModifiedTimestamp'. (Note that the STAF User's Guide defines
the results for each request submitted to an internal STAF service.)
my $fileName = "C:/temp/STAFDemo.zip";
$result = $handle->submit("local", "FS", "QUERY ENTRY $fileName");
if ($handle->{rc} != $STAF::kOk) {
print "FS QUERY ENTRY $fileName failed\n";
print "RC=$handle->{rc} Result=$result->{result}\n";
exit $handle->{rc};
}
my $mc = STAF::STAFUnmarshall($result->{result});
my $entryMap = $mc->getRootObject();
if ($entryMap->{type} eq "F") {
print "File $fileName has size $entryMap->{lowerSize} and " .
"was modified on $entryMap->{lastModifiedTimestamp}\n";
}
else {
print "$fileName is not a file. Type=$entryMap->{type}\n";
}
This example could print something like the following:
This example submits a request to the PROCESS service to run a command
on a machine and to wait for the command to complete. The request
returns a marshalled data whose root object
is a map that contains keys like 'rc' and 'fileList'.
The value for 'fileList' is a list of the returned files.
Each entry in the list consists of a map that contains keys 'rc' and
'data'. In our PROCESS START request, we returned one file, stdout
(and returned stderr to this same file).
(Note that the STAF User's Guide defines the results for each
request submitted to an internal STAF service.)
# Submit a PROCESS START request and wait for it to complete
my $command = 'dir {STAF/Config/STAFRoot}';
my $request = "START COMMAND ".STAF::WrapData($command).
" RETURNSTDOUT STDERRTOSTDOUT WAIT";
print "\nSTAF local PROCESS $request\n";
$result = $handle->submit("local", "PROCESS", $request);
if ($handle->{rc} != $STAF::kOk) {
print "Error on STAF local PROCESS $request\n";
print "Expected RC: 0\n";
print "Received RC: $handle->{rc}, Result: $result->{result}\n";
exit $handle->{rc};
}
# Unmarshall the result which is a marshalling context whose
# root object is a map containing keys 'rc', and 'fileList'.
# The value for 'fileList' is a list of the returned files.
# Each entry in the list consists of a map that contains keys
# 'rc' and 'data'. In our PROCESS START request, we returned
# one file, stdout (and returned stderr to this same file).
my $mc = STAF::STAFUnmarshall($result->{result});
my $mcRootObject = $mc->getRootObject();
# Verify that the process rc is 0
my $processRC = $mcRootObject->{rc};
if ($processRC != $STAF::kOk) {
print "Process RC: $processRC\n";
exit $processRC;
}
# Verify that the rc is 0 for returning data for the Stdout file
my $stdoutRC = $mcRootObject->{fileList}[0]{rc};
if ($stdoutRC != $STAF::kOk) {
print "Error on retrieving process's stdout data.\n";
print "Expected RC: 0\n";
print "Received RC: $stdoutRC\n";
exit $stdoutRC;
}
# Print the data in the stdout file created by the process
my $stdoutData = $mcRootObject->{fileList}[0]{data};
print "\nProcess Stdout File Contains:\n";
print "$stdoutData\n";
This example could print something like the following:
Definition
- STAF::STAFIsMarshalledData(someData)
- A function used to test if the keyword argument someData
is a string-based marshalled representation.
Returns a true value if it is a marshalled string.
Example
Definition
-
class STAF::STAFMapClassDefinition
- A class which provides the metadata associated with a map class.
In particular, it defines the keys associated with the map class.
This class is used to create and/or access a STAF map class definition which can
be useful if you want to generate a STAF marshalling context with map classes.
The map class definition is used to reduce the size of a
marshalling map class in comparison to a map containing the same data.
It also contains information about how to display instances of the map class,
such as the order in which to display the keys and the display names to
use for the keys. You get and set map class definitions using the
STAF::STAFMarshallingContext class setMapClassDefinition and
getMapClassDefinition methods.
Class STAF::STAFMapClassDefinition defines the following methods:
- new([name])
- Creates a new STAF::STAFMapClassDefinition object.
The optional keyword argument name specifies the name of the STAF
map class definition. The default is an empty string.
- addKey(keyName[,
displayName])
- Adds a key to the map class definition.
The required keyword argument keyName specifies the name of a key.
The optional keyword argument displayName specifies a string to
use when displaying the key. The default is None which indicates to
use the actual key name when displaying the key.
- setKeyProperty(keyName, property, value)
- Sets a property such as a short display name ("display-short-name")
for a key in the map class definition.
The required keyword argument keyName specifies the name of
a key for which this property is being set.
The required keyword argument property specifies the name of
the property being set. The only property name currently recognized isropery name currently recognized is
'display-short-name'.
The required keyword argument value specifies the value for
the property being set.
- keys()
- Returns a list of all of the keys. Each entry in the list is a
map containing a key named 'key', and optionally, a key named
'display-name', and optionally, any key property names such as
'display-short-name'.
- name()
- Returns the name for the map class definition.
Example
The following is an example of how to create a map class definition
named 'Test/MyMap' containing four keys, each with a display name,
and one with a short display name.
my $myMapClassDef = STAF::STAFMapClassDefinition->new('Test/MyMap');
$myMapClassDef->addKey('name', 'Name');
$myMapClassDef->addKey('exec', "Executable");
$myMapClassDef->addKey('testType', 'Test Type');
$myMapClassDef->setKeyProperty('testType', 'display-short-name', 'Test');
$myMapClassDef->addKey('outputList', 'Outputs');
my $myMapClassName = $myMapClassDef->name();
print "The keys for map class definition $myMapClassName are:\n";
# Note: We will be providing a STAF::STAFFormatObject() method to
# nicely print maps, lists, etc. that will produce similar
# output as the following code does.
print "[\n";
for my $key ($myMapClassDef->keys()) {
print " {\n";
print " key : $key->{'key'}\n";
print " display-name: $key->{'display-name'}\n";
if (exists($key->{'display-short-name'})) {
print " display-short-name: $key->{'display-short-name'}\n";
}
print " }\n"
}
print "]\n";
This example prints the following:
Definition
-
class STAF::STAFMarshallingContext
- A class is used to create and/or access a STAF marshalling context which
is used by STAF to help in marshalling and unmarshalling data.
A marshalling context is simply a container for map class definitions
and a data structure that uses (or is defined in terms of) them.
In order to use a map class when marshalling data, you must add the
map class definition to the marshalling context, set the root object
of the marshalling context to the object you want to marshall,
and then marshall the marshalling context itself.
When you unmarshall a data structure, you will always receive a
marshalling context. Any map class definitions referenced by map
classes within the data structure will be present in the marshalling context.
The primary use of this class is to represent multi-valued results
that consist of a data structure (e.g. results from a QUERY/LIST
service request, etc.) as a string that can also
be converted back into the data structure. This string can be
assigned to the string result buffer returned from the service request.
Class STAFMarshallingContext defines the following methods:
-
- new([obj])
- Creates a new STAF::STAFMarshallingContext object.
The optional keyword argument obj specifies the root object to be marshalled.
The default is an empty string.
- setMapClassDefinition(mapClassDef)
- Called to add a map class definition to the marshalling context's
mapClassMap.
- getMapClassDefinition(mapClassName)
- Returns the map class definition for the specified map class name
from the mapClassMap.
- hasMapClassDefinition(mapClassName)
- Called to determine whether the marshalling context mapClassMap contains
the specified map class definition.
- mapClassDefinitionList()
- Returns a map of the keys in mapClassMap.
- setRootObject(rootObject)
- Sets the root object for the marshalling context.
- getRootObject()
- Returns the root object for the marshalling context.
- getPrimaryObject()
- Returns the primary object for the marshalling context which is
the marshalling context object itself if the mapClassMap contains
one or more map class definitions. Otherwise, it returns the
root object.
Examples
The following is an example of how to create a marshalling context
containing one map class definition named 'Test/MyMap' and a root object
which is a string. Then it gets the map class definition and root object
from the marshalling context.
# Create a map class definition
$myMapClassDef = STAF::STAFMapClassDefinition->new('Test/MyMap');
$myMapClassDef->addKey('name', 'Name');
$myMapClassDef->addKey('exec', 'Executable');
# Create a marshalling context and assign a map class definition to it
my $mc = STAF::STAFMarshallingContext->new();
$mc->setMapClassDefinition($myMapClassDef);
if (!$mc->hasMapClassDefinition('Test/MyMap'))
{
print "Oops, map class 'Test/MyMap' doesn't exist\n";
}
# Get the map class definition from the marshalling context
my $mapClassDef = $mc->getMapClassDefinition('Test/MyMap');
print "The keys for map class definition $myMapClassName are:\n";
print "[\n";
for my $key ($mapClassDef->keys()) {
print " {\n";
print " key : $key->{'key'}\n";
print " display-name: $key->{'display-name'}\n";
print " }\n"
}
print "]\n";
# Set the root object for a marshalling context to be a string
# and get the root object.
$data = "This is a string\n";
$mc->setRootObject($data);
my $rootObj = $mc->getRootObject($myTestList);
print "\nRoot object: $rootObj\n";
This example prints the following:
In addition to the described APIs, the following variables are defined,
which represent the numeric return codes generated by STAF.
- STAF::kOk
- STAF::kInvalidAPI
- STAF::kUnknownService
- STAF::kInvalidHandle
- STAF::kHandleAlreadyExists
- STAF::kHandleDoesNotExist
- STAF::kUnknownError
- STAF::kInvalidRequestString
- STAF::kInvalidServiceResult
- STAF::kREXXError
- STAF::kBaseOSError
- STAF::kProcessAlreadyComplete
- STAF::kProcessNotComplete
- STAF::kVariableDoesNotExist
- STAF::kUnResolvableString
- STAF::kInvalidResolveString
- STAF::kNoPathToMachine
- STAF::kFileOpenError
- STAF::kFileReadError
- STAF::kFileWriteError
- STAF::kFileDeleteError
- STAF::kSTAFNotRunning
- STAF::kCommunicationError
- STAF::kTrusteeDoesNotExist
- STAF::kInvalidTrustLevel
- STAF::kAccessDenied
- STAF::kSTAFRegistrationError
- STAF::kServiceConfigurationError
- STAF::kQueueFull
- STAF::kNoQueueElement
- STAF::kNotifieeDoesNotExist
- STAF::kInvalidAPILevel
- STAF::kServiceNotUnregisterable
- STAF::kServiceNotAvailable
- STAF::kSemaphoreDoesNotExist
- STAF::kNotSemaphoreOwner
- STAF::kSemaphoreHasPendingRequests
- STAF::kTimeout
- STAF::kJavaError
- STAF::kConverterError
- STAF::kInvalidObject
- STAF::kInvalidParm
- STAF::kRequestNumberNotFound
- STAF::kInvalidAsynchOption
- STAF::kRequestNotComplete
- STAF::kProcessAuthenticationDenied
- STAF::kInvalidValue
- STAF::kDoesNotExist
- STAF::kAlreadyExists
- STAF::kDirectoryNotEmpty
- STAF::kDirectoryCopyError
- STAF::kDiagnosticsNotEnabled
- STAF::kHandleAuthenticationDenied
- STAF::kHandleAlreadyAuthenticated
- STAF::kInvalidSTAFVersion
- STAF::kRequestCancelled
For a complete description of these return codes and their meaning, please
see the STAF User's Guide.
The STAFMon package provides a function to ease the use of
the Monitor service, as well as, variables which define the return codes
from the Monitor service and variables which affect the operation of the
utility function provided.
The following variables affect the behavior of the STAFMon package.
These variable values may be changed to alter the behavior of the STAFMon
package.
STAF::Monitor::SystemName - The system name to which Monitor service requests
should be sent (default = local)
STAF::Monitor::ServiceName - The service name to which Monitor service
requests should be sent (default = monitor)
Description
This function logs a message to the Monitor service.
Syntax
STAF::Monitor::Log(MESSAGE, [OPTIONS])
where,
MESSAGE is the message to log.
OPTIONS are any additional options that should be passed on
the LOG request, e.g., RESOLVEMESSAGE. The default is "".
Result
This function returns a numeric return code. Return codes are documented
in the STAF User's Guide.
Example
Description
This method constructs a new STAF::STAFMonitor object to log messages to
the Monitor service.
Syntax
STAF::STAFMonitor->new(HANDLE, [SYSTEMNAME], [SERVICENAME])
where,
HANDLE is a STAF::STAFHandle object obtained at registration
time.
SYSTEMNAME is the name of the system where the Monitor service
is installed. The default is "LOCAL".
SERVICENAME is the name by which the Monitor service is identified.
The default is "MONITOR".
Result
This method returns STAF::Monitor object to log messages to the Monitor
service.
Example
$mon = STAF::STAFMonitor->new($handle);
Description
This method logs a message to the Monitor service.
Syntax
STAF::STAFMonitor->log(MESSAGE, [OPTIONS])
where,
MESSAGE is the message to log.
OPTIONS are any additional options that should be passed on
the LOG request, e.g., RESOLVEMESSAGE. The default is "".
Result
This function returns a STAF::STAFResult object that contains a numeric
return code and a string-based result.
Example
Description
This method returns the name of the system where the Monitor resides (defaults
to "LOCAL"). This value can be changed at construction time.
See 4.3.1 STAF::STAFMonitor::new.
Syntax
STAF::STAFMonitor->getSystemName()
Result
This function returns a string containing the name of the system where
the Monitor service resides.
Example
$system = $mon->getSystemName();
print "Monitor Service System Name: $system\n";
Description
This method returns the name that the Monitor service used when it registered
with STAF (defaults to "MONITOR"). This value can be changed at construction
time. See 4.3.1 STAF::STAFMonitor::new.
Syntax
STAF::STAFMonitor->getServiceName()
Result
This function returns a string containing the name that the Monitor service
used when it registered.
Example
$service = $mon->getServiceName();
print "Monitor Service Name: $service\n";
The STAFLog package provides a set of functions to ease the
use of the Log service, as well as, variables which define the return codes
from the Log service and variables which affect the operation of the utility
functions provided. These functions also interface with the Monitor service
to allow messages which are logged to also be monitored.
The following variables are defined, which represent the numeric return
codes generated by the STAF Monitor service.
STAF::Log::kInvalidLevel
STAF::Log::kInvalidLogFileFormat
STAF::Log::kPurgeFailure
For a complete description of these return codes and their meaning, please
see the STAF User's Guide.
The following variables affect the behavior of the STAFLog package.
These variable values may be changed to alter the behavior of the STAFLog
package.
STAF::Log::SystemName - The system name to which Log service requests should
be sent (default = local)
STAF::Log::ServiceName - The service name to which Log service requests
should be sent (default = log)
Description
This function initializes the utility functions for a specific log file.
Syntax
STAF::Log::Init(LOGNAME, [LOGTYPE], [MONITORMASK])
where,
LOGNAME is the name of the log.
LOGTYPE is the type of log to be created, "GLOBAL", "MACHINE",
or "HANDLE". The default is "MACHINE".
MONITORMASK is the set of logging levels which will also be
sent to the Monitor service. The default is "FATAL ERROR WARNING INFO STATUS".
Result
This function returns a numeric return code. Return codes are documented
in the STAF User's Guide.
Example
$rc = STAF::Log::Init("TestCase1", "GLOBAL", "FATAL ERROR");
Description
This function logs a message to the Log service. This function will also
log the message to the Monitor service if the specified logging level is
one of the levels defined in the Monitor Mask (set in STAF::Log::Init,
above).
Syntax
STAF::Log::Log(LEVEL, MESSAGE, [OPTIONS])
where,
LEVEL is the level of the message to log, e.g., "WARNING" or
"DEBUG".
MESSAGE is the message to log.
OPTIONS are any additional options that should be passed on
the LOG request, e.g., "RESOLVEMESSAGE". The default is "".
Result
This function returns a numeric return code. Return codes are documented
in the STAF User's Guide.
Example
Description
This method constructs a STAF::STAFLog object to log messages to the Log
service.
Syntax
STAF::STAFLog->new(HANDLE, LOGNAME, [LOGTYPE], [MONITORMASK], [SYSTEMNAME],
[SERVICENAME])
where,
HANDLE is a STAF::STAFHandle object obtained at registration
time.
LOGNAME is the name of the log.
LOGTYPE is the type of log to be created, "GLOBAL", "MACHINE",
or "HANDLE". The default is "MACHINE".
MONITORMASK is the set of logging levels which will also be
sent to the Monitor service. The default is "FATAL ERROR WARNING INFO STATUS".
SYSTEMNAME is the name of the system where the Log service
is installed. The default is "LOCAL".
SERVICENAME is the name by which the Log service is identified.
The default is "LOG".
Result
This method returns STAF::Log object to log messages to the Log service.
Example
$log = STAF::STAFLog->new($handle, "TestCase1", "GLOBAL", "FATAL
ERROR");
Description
This method logs a message to the Log service. This method will also log
the message to the Monitor service if the specified logging level is one
of the levels defined in the Monitor Mask (set in STAF::STAFLog::new, above).
Syntax
STAF::STAFLog->log(LEVEL, MESSAGE, [OPTIONS])
where,
LEVEL is the level of the message to log, e.g., "WARNING" or
"DEBUG".
MESSAGE is the message to log.
OPTIONS are any additional options that should be passed on
the LOG request, e.g., "RESOLVEMESSAGE". The default is "".
Result
This function returns a STAF::STAFResult object that contains a numeric
return code and a string-based result.
Example
Description
This method returns the name that uniquely identifies your constructed
log.
Syntax
STAF::STAFLog->getName()
Result
This function returns a string containing the name of the log being used.
This value is set at construction time.
See 5.3.1 STAF::STAFLog::new.
Example
$logname = $log->getName();
print "Log Name: $logname\n";
Description
This method returns the log type (either "MACHINE", "HANDLE", or "GLOBAL").
Syntax
STAF::STAFLog->getLogType()
Result
This function returns a string representing the log type. This value is
set at constructions time, and is one of "MACHINE", "GLOBAL", or "HANDLE".
See 5.3.1 STAF::STAFLog::new.
Example
$logtype = $log->getLogType();
print "Log Type: $logtype\n";
Description
This method returns the monitor mask.
Syntax
STAF::STAFLog->getMonitorMask()
Result
This function returns a string containing the monitor mask. This value
is set at construction time.
See 5.3.1 STAF::STAFLog::new.
Example
$logmask = $log->getMonitorMask();
print "Log's Monitor Mask: $logmask\n";
Description
This method returns the name of the system where the Log resides (defaults
to "LOCAL"). This value can be changed at construction time.
See 5.3.1 STAF::STAFLog::new.
Syntax
STAF::STAFLog->getSystemName()
Result
This function returns a string containing the name of the system where
the Log service resides.
Example
$system = $log->getSystemName();
print "Log Service System Name: $system\n";
Description
This method returns the name that the Log service used when it registered
with STAF (defaults to "LOG"). This value can be changed at construction
time. See 5.3.1 STAF::STAFLog::new.
Syntax
STAF::STAFLog->getServiceName()
Result
This function returns a string containing the name that the Log service
used when it registered.
Example
$service = $log->getServiceName();
print "Log Service Name: $service\n";