Tcl User's Guide for STAF Version 3

Last Updated: March 3, 2006


Table of Contents

1.0 Introduction

2.0 Installation

3.0 Package STAF

3.1 STAF::Register
3.2 STAF::Submit
3.3 STAF::UnRegister
3.4 Function STAF::WrapData
3.5 Function STAF::AddPrivacyDelimiters
3.6 Function STAF::EscapePrivacyDelimiters
3.7 Function STAF::RemovePrivacyDelimiters
3.8 Function STAF::MaskPrivateData
3.9 STAF Return Codes
4.0 Package STAFMon 4.1 Monitor Service Variables
4.2 STAF::Monitor::Log
5.0 Package STAFLog 5.1 Log Service Return Codes and Variables
5.2 STAF::Log::Init
5.3 STAF::Log::Log


1.0 Introduction

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

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:

2.0 Installation

To install STAF's Tcl support on Windows or Linux 32-bit platforms, select to install "Tcl support" during the install. It is installed by default for a "typical" install of STAF.

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 eight APIs This package also provides variables for the various STAF return codes.

3.1 STAF::Register

Description

Result

Example

3.2 STAF::Submit

Description

Result

Example

3.3 STAF::UnRegister

Description

Result

Examples

3.4 STAF::WrapData

Description

Result

Example

3.5 STAF::AddPrivacyDelimiters

Description

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 STAF::EscapePrivacyDelimiters

Description

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 STAF::RemovePrivacyDelimiters

Description

Result

Examples

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

3.8 STAF::MaskPrivateData

Description

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 STAF Return Codes

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 variables values may be changed to alter the behavior of the STAFMon package.

4.2 STAF::Monitor::Log

Description

Result

Examples

This example logs message "Hello World" to the Monitor service.

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 Variables and Return Codes

The following variables are defined, which represent the numeric return codes generated by the STAF Log service. 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.

5.2 STAF::Log::Init

Description

Result

Examples

This example initializes the utility functions for global log file "Testcase1", setting the monitor mask to logging levels "FATAL ERROR".

5.3 STAF::Log::Log

Description

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

This example logs warning mesage "Unable to find specified file".