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

3.1 Procedural Style 3.1.1 STAF::Register
3.1.2 STAF::Submit
3.1.3 STAF::UnRegister
3.2 Object-Oriented Style 3.2.1 STAF::STAFHandle::new
3.2.2 STAF::STAFHandle::submit
3.2.3 STAF::STAFHandle::unRegister
3.3 Class STAF::STAFResult
3.4 Function STAF::WrapData (or STAF::STAFUtil::WrapData)
3.5 Function STAF::AddPrivacyDelimiters
3.6 Function STAF::EscapePrivacyDelimiters
3.7 Function STAF::RemovePrivacyDelimiters
3.8 Function STAF::MaskPrivateData
3.9 Function STAF::STAFUnmarshall
3.10 Function STAF::STAFIsMarshalledData
3.11 Class STAF::STAFMapClassDefinition
3.12 Class STAF::STAFMarshallingContext
3.13 STAF Return Codes
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


1.0 Introduction

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:

  1. All of STAF's Perl APIs are provided in the STAF namespace.

  2. 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:


2.0 Installation

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:


3.0 Package PLSTAF

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:

The object-oriented style of communicating with STAF uses the following class:

Other STAF Perl classes that it externalizes are:

Other STAF Perl functions that it externalizes are:

Note that following two Perl functions are not yet available:

3.1 Procedural Style

3.1.1 STAF::Register

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

3.1.2 STAF::Submit

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

3.1.3 STAF::UnRegister

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

3.2 Object-Oriented Style

3.2.1 STAF::STAFHandle::new

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

3.2.2 STAF::STAFHandle::submit

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

3.2.3 STAF::STAFHandle::unRegister

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

3.3 Class STAF::STAFResult

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:

Class STAF::STAFResult defines the following member variables. They are initialized by the constructor, and should not be modified directly.

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.

3.4 Function STAF::WrapData (or STAF::STAFUtil::WrapData)

Definition

Result

Example

3.5 Function STAF::AddPrivacyDelimiters

Definition

Result

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.

3.6 Function STAF::EscapePrivacyDelimiters

Definition

Result

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.

3.7 Function STAF::RemovePrivacyDelimiters

Definition

Result

Examples

This example removes privacy delimiters from protected password '!!@secret@!!' and assigns 'secret' as the password.

3.8 Function STAF::MaskPrivateData

Definition

Result

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 **************

3.9 Function STAF::STAFUnmarshall

Definition

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.)

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.)

This example could print something like the following:

3.10 Function STAF::STAFIsMarshalledData

Definition

Example

3.11 Class STAF::STAFMapClassDefinition

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:

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. This example prints the following:

3.12 Class STAF::STAFMarshallingContext

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:

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. This example prints the following:

3.13 STAF Return Codes

In addition to the described APIs, the following variables are defined, which represent the numeric return codes generated by STAF. For a complete description of these return codes and their meaning, please see the STAF User's Guide.


4.0 Package STAFMon

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.

4.1 Monitor Service Variables

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)
  • 4.2 Procedural Style

    4.2.1 STAF::Monitor::Log

    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

    4.3 Object-Oriented Style

    4.3.1 STAF::STAFMonitor::new

    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

    4.3.2 STAF::STAFMonitor::log

    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

    4.3.3 STAF::STAFMonitor::getSystemName

    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

    4.3.4 STAF::STAFMonitor::getServiceName

    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


    5.0 Package STAFLog

    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.

    5.1 Log Service Return Codes

    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)
  • 5.2 Procedural Style

    5.2.1 STAF::Log::Init

    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

    5.2.2 STAF::Log::Log

    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

    5.3 Object-Oriented Style

    5.3.1 STAF::STAFLog::new

    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

    5.3.2 STAF::STAFLog::log

    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

    5.3.3 STAF::STAFLog::getName

    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

    5.3.4 STAF::STAFLog::getLogType

    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

    5.3.5 STAF::STAFLog::getMonitorMask

    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

    5.3.6 STAF::STAFLog::getSystemName

    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

    5.3.7 STAF::STAFLog::getServiceName

    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