3.1 STAFHandle class
Description
This class is the primary class used to communicate with STAF. The primary method of interest is the submit() method, which allows your Python script to call STAF services.
(Pseudo) Definition
class STAFHandle:
# Handle types
Standard = 0
Static = 1
# Submission modes
Synchronous = 0
FireAndForget = 1
Queue = 2
Retain = 3
QueueRetain = 4
def __init__(nameOrHandle, standardOrStatic = STAFHandle.Static)
def submit(location, service, request, mode=STAFHandle.Synchronous)
def unregister()
The __init__() method generates an instance of STAFException if the STAFHandle object could not be created. The submit() method returns an instance of class STAFResult, described below.
Examples
The following is an example of a program which registers with STAF, calls a couple of STAF services, and then unregisters with STAF.
from PySTAF import *
import sys
try:
handle = STAFHandle("MyTest")
except STAFException, e:
print "Error registering with STAF, RC: %d" % e.rc
sys.exit(e.rc)
result = handle.submit("local", "ping", "ping")
if (result.rc != 0):
print "Error submitting request, RC: %d, Result: %s" % (result.rc, result.result)
result = handle.submit("local", "var", "resolve {STAF/Config/OS/Name}")
if (result.rc != 0):
print "Error submitting request, RC: %d, Result: %s" % (result.rc, result.result)
else:
print "OS Name: %s" % result.result
rc = handle.unregister()
sys.exit(rc)
The following is an example which uses a static STAF handle to call STAF asynchronously and then waits for the result of the call to come back. Note, you can obtain more information on standard vs. static handles and the various submission modes in the
C API reference in the STAF User's Guide.
from PySTAF import *
# Other code would be in here that obtains a static handle number from somewhere.
# See section 5.2 of the STAF User's Guide for more information on static handles.
try:
handle = STAFHandle(staticHandleNumber, STAFHandle.Static)
except STAFException, e:
print "Error registering with STAF, RC: %d" % e.rc
sys.exit(e.rc)
result = handle.submit("local", "fs", "copy file /tmp/abc tomachine xyz", STAFHandle.Queue)
if (result.rc != 0):
print "Error submitting request, RC: %d, Result: %s" % (result.rc, result.result)
requestNumber = result.result
# At this point I can do some other work while the file transfer completes
...
# And now, I want to wait until the request has completed
#
result = handle.submit("local", "queue", "get contains %s wait") % \
STAFWrapData("STAF/RequestComplete %s;" % requestNumber))
# result.result now contains a message which includes the result of FS service request.
# I can now check the result and/or continue with the rest of my script
3.2 STAFResult class
Description
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.
(Pseudo) Definition
class STAFResult:
# Exposes two variables:
#
# rc - The numeric return code of the service request
# result - The string result buffer returned from the service request
Ok = 0
InvalidAPI = 1
UnknownService = 2
InvalidHandle = 3
HandleAlreadyExists = 4
HandleDoesNotExist = 5
UnknownError = 6
InvalidRequestString = 7
InvalidServiceResult = 8
REXXError = 9
BaseOSError = 10
ProcessAlreadyComplete = 11
ProcessNotComplete = 12
VariableDoesNotExist = 13
UnResolvableString = 14
InvalidResolveString = 15
NoPathToMachine = 16
FileOpenError = 17
FileReadError = 18
FileWriteError = 19
FileDeleteError = 20
STAFNotRunning = 21
CommunicationError = 22
TrusteeDoesNotExist = 23
InvalidTrustLevel = 24
AccessDenied = 25
STAFRegistrationError = 26
ServiceConfigurationError = 27
QueueFull = 28
NoQueueElement = 29
NotifieeDoesNotExist = 30
InvalidAPILevel = 31
ServiceNotUnregisterable = 32
ServiceNotAvailable = 33
SemaphoreDoesNotExist = 34
NotSemaphoreOwner = 35
SemaphoreHasPendingRequests = 36
Timeout = 37
JavaError = 38
ConverterError = 39
ServiceAlreadyExists = 40
InvalidObject = 41
InvalidParm = 42
RequestNumberNotFound = 43
InvalidAsynchOption = 44
RequestNotComplete = 45
ProcessAuthenticationDenied = 46
InvalidValue = 47
DoesNotExist = 48
AlreadyExists = 49
DirectoryNotEmpty = 50
DirectoryCopyError = 51
def __init__(rc = 0, result = "")
Examples
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: %d" % result.rc
print "Ping request result buffer: %s" % result.result
3.3 STAFException class
Description
This class is the base exception class used by the STAF modules. Currently, this class is only used when trying to register with STAF.
(Pseudo) Definition
class STAFException:
# Exposes two variables:
#
# rc - The numeric return code which is the basis of the exception
# result - A string futher describing the exception
def __init__(rc = 0, result = ""):
Examples
The following is an example of a program which shows how to deal with a STAFException when registering with STAF.
from PySTAF import *
import sys
try:
handle = STAFHandle("MyTest")
except STAFException, e:
print "Error registering with STAF, RC: %d" % e.rc
3.4 STAFWrapData function
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
outputString = STAFWrapData(inputString)
Example
semName = "My Synch Sem"
result = handle.submit("local", "sem", "event %s post" % STAFWrapData(semName))
4.0 Module PySTAFMon
The PySTAFMon module provides a class to ease the use of the Monitor service. To use this module you simply import it like so
from PySTAFMon import *
4.1 STAFMonitor class
Description
This class provides a wrapper around the Monitor service. It also contains a set of constants representing the Monitor service return codes. The primary method of interest is the log() method which allows you to log a message to the STAF Monitor service.
(Pseudo) Definition
class STAFMonitor:
InvalidDirectory = 4005
CreateDirectoryError = 4006
InvalidLogFileFormat = 4007
def __init__(stafHandle, system = "local", service = "Monitor"):
def log(message):
Note: By default, the STAFMonitor class will use the service named "Monitor" on the local system. This can be changed by explicitly specifying the system and/or service when you construct the STAFMonitor object.
Examples
The following example shows the use of the STAFMonitor class to log a status message to the Monitor service.
from PySTAFMon import *
# The variable "handle" is an instance of the STAFHandle class that was
# previously instantiated
monitor = STAFMonitor(handle)
result = monitor.log("Beginning section ABC of test")
5.0 Module PySTAFLog
The PySTAFLog module provides a class to ease the use of the Log service. To use this module you simply import it like so
from PySTAFLog import *
5.1 STAFLog class
Description
This class provides a wrapper around the Log service. It provides a log() method for logging a message to the Log service. It also contains constants for the various log file types and logging levels, as well as the return codes returned by the Log service.
This wrapper also allows you to specify a set of log levels for which the messages logged to the Log service will also be logged to the Monitor service.
(Pseudo) Definition
class STAFLog:
# Log type constants
Global = "GLOBAL"
Machine = "MACHINE"
Handle = "HANDLE"
# Log level constants
Fatal = "Fatal"
Error = "Error"
Warning = "Warning"
Info = "Info"
Trace = "Trace"
Trace2 = "Trace2"
Trace3 = "Trace3"
Debug = "Debug"
Debug2 = "Debug2"
Debug3 = "Debug3"
Start = "Start"
Stop = "Stop"
Pass = "Pass"
Fail = "Fail"
Status = "Status"
User1 = "User1"
User2 = "User2"
User3 = "User3"
User4 = "User4"
User5 = "User5"
User6 = "User6"
User7 = "User7"
User8 = "User8"
# Log service return codes
InvalidNumber = 4001
InvalidDate = 4002
InvalidTime = 4003
InvalidLevel = 4004
InvalidDirectory = 4005
InvalidCreateDirectoryError = 4006
InvalidLogFileFormat = 4007
PurgeFailure = 4008
UnknownRemoteLogServer = 4009
def __init__(handle, type, name, monitorMask = [ "Fatal", "Error",
"Warning", "Start", "Stop", "Pass", "Fail" ],
system = "local", service = "Log"):
def log(level, msg):
Note: By default, the STAFLog class will use the service name "Log" on the local system. This can be changed by explicitly specifying the system and/or service when you construct the STAFLog object.
Examples
The following example shows the use of the STAFLog class to log some messages to the Log service.
from PySTAFLog import *
# The variable "handle" is an instance of the STAFHandle class that was
# previously instantiated
# Let's create a machine based log file that also sends fatal, error, and
# warning messages to the Monitor service
log = STAFLog(handle, STAFLog.Machine, "MyLog",
[STAFLog.Fatal, STAFLog.Error, STAFLog.Warning])
# This message will only go to the log service, since we didn't specify
# that start message get sent to the Monitor service
result = log.log(STAFLog.Start, "Beginning ABC test")
# This message will be sent to the Log and Monitor services
result = log.log(STAFLog.Warning, "Got some ambiguous result")