STAF Perl User's Guide
Version 1.1

1.0 Introduction

This document describes STAF's 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.

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

Note: STAF Perl support is provided for Perl 5.0, 5.6, and 5.8 on Linux and Perl 5.6 and 5.8 on Windows.

2.0 Installation

STAF Perl support will be installed by default on Linux and Windows, 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:

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)

3.0 Package PLSTAF

The PLSTAF package provides support for Perl scripts to call into STAF in two different programming styles, procedural or object-oriented. This package externalizes three APIs, and one object with one constructor and two instance 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)

STAF::STAFHandle - Object to call into 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

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.

Example

$rc = STAF::Register("My program");

if ($rc != $STAF::kOk) {
print "Error registering with STAF, RC: $STAF::RC\n";
return $rc;
}

print "My STAF handle: $STAF::Handle\n";

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

$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";
    }
    return $rc;
}

print "STAF Ping result: $STAF::Result\n";

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

$rc = STAF::UnRegister();

if ($rc != $STAF::kOk) {
print "Error unregistering with STAF, RC: $STAF::RC\n";
return $rc;
}

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

$handle = STAF::STAFHandle->new("My program");

if ($handle->{rc} != $STAF::kOk) {
print "Error registering with STAF, RC: $handle->{rc}\n";
return $handle->{rc};
}

print "My STAF handle: $handle->{handle}\n";

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::Result 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";
    }
    return $result->{rc};
}

print "STAF Ping result: $result\n";

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

$rc = $handle->unRegister();

if ($rc != $STAF::kOk) {
print "Error unregistering with STAF, RC: $rc\n";
return $rc;
}

3.3 STAF Return Codes

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::kServiceDefined

For a complete description of these return codes and their meaning, please see the STAF User's Guide.

3.4 STAF::WrapData

Description

This function takes a string and produces the colon-length-colon delimited version of that string. This function is widely used to pass the values of options in STAF requests.

Syntax

STAF::WrapData(INPUTSTRING)

where,

INPUTSTRING is the string for which to create the colon-length-colon delimited version.

Result

This function returns a string in colon-length-colon delimited format.

Example

$option = "Hello World";

$handle->submit("local", "monitor", "log message ".STAF::WrapData($option));

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 return codes

The following variables are defined, which represent the numeric return codes generated by the STAF Monitor service.

STAF::Monitor::kInvalidDirectory

STAF::Monitor::kCreateDirectoryError

STAF::Monitor::kInvalidLogFileFormat

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

$rc = STAF::Monitor::Log("Hello World");

if ($rc != $STAF::kOk) {
print "Error logging message to Monitor, RC: $rc\n";
return $rc;
}

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

$mon = STAF::STAFMonitor->new($handle);

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

$result = $mon->log("Hello World");

if ($result->{rc} != $STAF::kOk) {
print "Error logging message to Monitor, RC: $result->{rc}\n";
return $rc;
}

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

Syntax

STAF::STAFMonitor->getSystemName()

Result

This function returns a string containing the name of the system where the Monitor service resides.

Example

print "Monitor Service System Name: $mon->getSystemName()\n";

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

Syntax

STAF::STAFMonitor->getServiceName()

Result

This function returns a string containing the name that the Monitor service used when it registered.

Example

print "Monitor Service Name: $mon->getServiceName()\n";

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::kInvalidNumber

STAF::Log::kInvalidDate

STAF::Log::kInvalidTime

STAF::Log::kInvalidLevel

STAF::Log::kInvalidDirectory

STAF::Log::kInvalidCreateDirectoryError

STAF::Log::kInvalidLogFileFormat

STAF::Log::kPurgeFailure

STAF::Log::kUnknownRemoteLogServer

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

$rc = STAF::Log::Init("TestCase1", "GLOBAL", "FATAL ERROR");

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

$rc = STAF::Log::Log("WARNING", "Unable to find specified file");

if ($rc != $STAF::kOk) {
print "Error logging message to Log, RC: $rc\n";
return $rc;
}

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

$log = STAF::STAFLog->new("TestCase1", "GLOBAL", "FATAL ERROR");

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

Example

print "Log Service Name: $log->getServiceName()\n";

STAF Perl User's Guide Version 1.1

1.0 Introduction

2.0 Installation

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

3.1 Procedural Style

3.1.1 STAF::Register

Description

Syntax

Result

Example

3.1.2 STAF::Submit

Description

Syntax

Result

Example

3.1.3 STAF::UnRegister

Description

Syntax

Result

Example

3.2 Object-Oriented Style

3.2.1 STAF::STAFHandle::new

Description

Syntax

Result

Example

3.2.2 STAF::STAFHandle::submit

Description

Syntax

Result

Example

3.2.3 STAF::STAFHandle::unRegister

Description

Syntax

Result

Example

3.3 STAF Return Codes

3.4 STAF::WrapData

Description

Syntax

Result

Example

4.0 Package STAFMon

4.1 Monitor service return codes

4.2 Procedural Style

4.2.1 STAF::Monitor::Log

Description

Syntax

Result

Example

4.3 Object-Oriented Style

4.3.1 STAF::STAFMonitor::new

Description

Syntax

Result

Example

4.3.2 STAF::STAFMonitor::log

Description

Syntax

Result

Example

4.3.3 STAF::STAFMonitor::getSystemName

Description

Syntax

Result

Example

4.3.4 STAF::STAFMonitor::getServiceName

Description

Syntax

Result

Example

5.0 Package STAFLog

5.1 Log service return codes

5.2 Procedural Style

5.2.1 STAF::Log::Init

Description

Syntax

Result

Example

STAF Perl User's Guide
Version 1.1