Last Updated: March 3, 2006
Note: All of STAF's Tcl APIs are provided in the STAF namespace.
STAF's Tcl support is provided only with the Windows and Linux 32-bit STAF builds and only works with Tcl 8.0 - 8.3. If you want to use higher version of Tcl (e.g. Tcl 8.4), or if you want STAF Tcl support for a different operating system, you can either:
If you build STAF Tcl support for a different operating system and/or different Tcl 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 Tcl support for this operating system and Tcl version combination. If not, open a STAF Support Request with the "Summary" containing "STAF V3 Support for Tcl x.x.x (Platform)", replacing x.x.x with the Tcl version and replacing Platform with the operating system on which you built the support. Attach the necessary files to the Support Request.
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.
This function allows you to register with STAF. You must register with STAF before you can use any of the other STAF related APIs.
Required argument processName is a String that contains the name by which your Tcl program will be known.
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.
if {[STAF::Register "My program"] != $STAF::kOk} { puts "Error registering with STAF, RC: $STAF::RC" exit $STAF::RC } puts "My STAF handle: $STAF::Handle"
This function allows you to submit requests to STAF. This is the primary API that you will use when working with STAF.
Required argument location is a String that contains the endpoint for 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.
Required argument service is a String that contains the name of the service to which the request should be submitted.
Required argument request is a String that contains the actual request string itself.
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.
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"
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.
This function has no arguments.
The variable STAF::RC will also contain the return code from this function.
The variable STAF::Handle will be deleted when this function returns.
if {[STAF::UnRegister] != $STAF::kOk} { puts "Error unregistering with STAF, RC: $STAF::RC" exit $STAF::RC }
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.
Required argument inputString is a String
set semName {My Synch Sem} STAF::Submit local sem "event [STAF::WrapData $semName] post"
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
Examples:
set password "passw0rd" set protectedPw [STAF::AddPrivacyDelimiters $password] set request "START COMMAND C:/tests/TestA USERNAME Test1 PASSWORD $protectedPw" if {[STAF::Submit local PROCESS $request] != $STAF::kOk} puts "Error submitting process, RC: $STAF::RC, Result: $STAF::Result" }
set password "secret" set command "C:/tests/admin -password [STAF::AddPrivacyDelimiters $password]" set request "START COMMAND [STAF::WrapData $command]" if {[STAF::Submit local PROCESS $request] != $STAF::kOk} puts "Error submitting process, RC: $STAF::RC, Result: $STAF::Result"
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
For example, if the data is "passw@!!d", this method would return "passw^@!!d".
set password "passw@!!d" set protectedPw [STAF::AddPrivacyDelimiters [STAF::EscapePrivacyDelimiters $password]] set request "START COMMAND C:/tests/TestA USERNAME Test1 PASSWORD $protectedPw" if {[STAF::Submit local PROCESS $request] != $STAF::kOk} puts "Error submitting process, RC: $STAF::RC, Result: $STAF::Result" }
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
Examples:
set protectedPw "!!@secret@!!" set password [STAF::RemovePrivacyDelimiters $protectedPw]
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
Examples:
set password "passw0rd" set protectedPw [STAF::AddPrivacyDelimiters $password] set request "START COMMAND C:/tests/TestA.exe USERNAME Test1 PASSWORD $protectedPw" puts "[STAF::MaskPrivateData $request]"
The following variables affect the behavior of the STAFMon package. These variables values may be changed to alter the behavior of the STAFMon package.
This function logs a message to the Monitor service.
Required argument message is a String that contains the message to log.
Optional argument options is a String that contains any additional option(s) that should be passed on to the LOG request, e.g. RESOLVEMESSAGE.
The variables STAF::RC and STAF::Result will also be set based on the underlying STAF::Submit call.
if {[STAF::Monitor::Log "Hello World"] != $STAF::kOk} { puts "Error logging message to Monitor, RC: $STAF::RC" return $STAF::RC }
The following variables affect the behavior of the STAFLog package. These variables values may be changed to alter the behavior of the STAFLog package.
This function initializes the utility functions for a specific log file.
Required argument logName is a String that contains the name of the log.
Optional argument logType is a String that contains the type of log to be created: "GLOBAL", "MACHINE", or "HANDLE". The default is "MACHINE".
Optional argument monitorMask is a String that contains the logging level(s) which will also be sent to the Monitor service. The default is "FATAL ERROR WARNING INFO STATUS".
STAF::Log::Init Testcase1 GLOBAL "FATAL ERROR"
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).
Required argument level is a String that contains the level of the message to log, e.g., WARNING or DEBUG.
Required argument message is a String that contains the message to log.
Optional argument options is a String that contains any additional options that should be passed on the the LOG request, e.g., RESOLVEMESSAGE.
The variables STAF::RC and STAF::Result will also be set based on the underlying STAF::Submit call.
if {[STAF::Log::Log WARNING "Unable to find specified file"] != $STAF::kOk} { puts "Error logging message to Log, RC: $STAF::RC" return $STAF::RC }