STAF Tcl User's Guide
Version 1.0
1.0 Introduction
This document describes STAF's support for the Tcl language. It includes
information on the core STAF Tcl APIs as well as the wrappers provided
for the Monitor and Log services.
Note: All of STAF's Tcl APIs are provided in the STAF namespace.
Note: STAF's Tcl support requires Tcl version 8.0 or higher.
2.0 Installation
To install STAF's Tcl support, simply uncompress the downloaded package
into your STAF installation directory, e.g. c:\STAF or /usr/local/staf.
Then, you need to set/update your TCLLIBPATH environment variable.
On unix, add the <STAF Root>/lib directory to your TCLLIBPATH.
On Win32, add the <STAF Root>/bin directory to your TCLLIBPATH.
Finally, you simply need to add a "package require" statement in your Tcl
scripts for any of the STAF packages described below.
3.0 Package STAF
The STAF package provides support for Tcl scripts to call into STAF.
This package externalizes four APIs
-
STAF::Register - Allows you to register with STAF
-
STAF::Submit - Allows you to submit requests to STAF
-
STAF::UnRegister - Allows you to unregister with STAF
-
STAF::WrapData - Generates the colon-length-colon delimited version of
a string
This package also provides variables for the various STAF return codes.
3.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.
Syntax
STAF::Register processName
where,
processsName is the name by which your Tcl program will be
known
Result
This function returns a numeric return code. Zero indicates that
you registered successfully. Non-zero return codes are documented
in the STAF User's Guide.
The variable STAF::RC will also contain the return code from this function.
The variable STAF::Handle will contain this program's STAF handle on
a successful return. This variable should not be altered.
Example
if {[STAF::Register "My program"] != $STAF::kOk} {
puts "Error registering with STAF, RC: $STAF::RC"
exit $STAF::RC
}
puts "My STAF handle: $STAF::Handle"
3.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.
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 Tcl 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
This function returns a numeric return code. Return codes are documented
in the STAF User's Guide.
The variable STAF::RC will also contain the return code from this function.
The variable STAF::Result will contain the textual result buffer from
this request. See the individual service documentation for information
on the contents of this buffer.
Example
if {[STAF::Submit local ping ping] != $STAF::kOk} {
puts "Error submitting ping request, RC: $STAF::RC"
if {[string length $STAF::Result] != 0} {
puts "Additional info:
$STAF::Result"
}
exit $STAF::RC
}
puts "STAF Ping result: $STAF::Result"
3.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.
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.
The variable STAF::RC will also contain the return code from this function.
The variable STAF::Handle will be deleted when this function returns.
Example
if {[STAF::UnRegister] != $STAF::kOk} {
puts "Error unregistering with STAF, RC: $STAF::RC"
exit $STAF::RC
}
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
set semName {My Synch Sem}
STAF::Submit local sem "event [STAF::WrapData $semName] post"
3.5 STAF return codes
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.
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 and variables
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 variables 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 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.
?option? are any additional option that should be passed on
the LOG request, e.g., RESOLVEMESSAGE.
Result
This function returns a numeric return code. Return codes are documented
in the STAF User's Guide.
The variables STAF::RC and STAF::Result will also be set based on the
underlying STAF::Submit call.
Example
if {[STAF::Monitor::Log "Hello World"] != $STAF::kOk} {
puts "Error logging message to Monitor, RC:
$STAF::RC"
return $STAF::RC
}
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 and variables
The following variables are defined, which represent the numeric return
codes generated by the STAF Log service.
-
STAF::Log::kInvalidNumber
-
STAF::Log::kInvalidDate
-
STAF::Log::kInvalidTime
-
STAF::Log::kInvalidLevel
-
STAF::Log::kInvalidDirectory
-
STAF::Log::kCreateDirectoryError
-
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 variables 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 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
STAF::Log::Init Testcase1 GLOBAL "FATAL ERROR"
5.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.
?option? are any additional option that should be passed on
the LOG request, e.g., RESOLVEMESSAGE.
Result
This function returns a numeric return code. Return codes are documented
in the STAF User's Guide.
The variables STAF::RC and STAF::Result will also be set based on the
underlying STAF::Submit call.
Example
if {[STAF::Log::Log WARNING "Unable to find specified file"] != $STAF::kOk}
{
puts "Error logging message to Log, RC: $STAF::RC"
return $STAF::RC
}