Tcl User's Guide for STAF Version 3

Last Updated: June 27, 2014

Table of Contents

1.0 Introduction

2.0 Supported Platforms and Tcl Versions

3.0 Installation

4.0 Tcl Script Example

5.0 Package STAF

1.0 Introduction

STAF Tcl support must be installed in order to submit requests to STAF via a Tcl program.

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

STAF Tcl support is only provided in the STAF installer files for the platforms listed below. STAF Tcl support is not provided in the STAF installer files for other operating systems.

The version of Tcl used to build the STAF Tcl libraries is usually the only Tcl version that will work with those STAF Tcl libraries. STAF currently provides STAF Tcl support on the following platforms:

• Windows (Intel 32-bit)
• Windows (AMD64, aka x64)
• Linux (Intel 32-bit, aka i386 or x86-32)
• Linux (AMD64, aka x86-64)

Section 2.0 provides details about the STAF Tcl support by platform.

• Build STAF Tcl support yourself. See the STAF Developer's Guide for more information on how to build the STAF tcl project.

  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.

• Or, you can submit a Support Request for us to build it for you (but it may take a while until we get a chance to implement your request). Be sure to check the existing STAF Support Requests as we may have already provided STAF Tcl support for the Tcl version and operating system that you want and attached it to an existing STAF Support Request.

2.0 Supported Platforms and Tcl Versions

This section provides more information about the Tcl Versions supported by STAF by operating system.

2.1 Windows (Intel 32-bit)

Supported TCL Version	Built with	TCLSTAF library
8.3	8.3 (ActiveTcl)	{STAF/Config/STAFRoot}/bin/tcl83/TCLSTAF.dll
8.4	8.4.19 (ActiveTcl)	{STAF/Config/STAFRoot}/bin/tcl84/TCLSTAF.dll
8.5	8.5.9 (ActiveTcl)	{STAF/Config/STAFRoot}/bin/tcl85/TCLSTAF.dll
8.6	8.6.0 (ActiveTcl)	{STAF/Config/STAFRoot}/bin/tcl86/TCLSTAF.dll
Note: Support for Tcl Version 8.3 is installed by default to {STAF/Config/STAFRoot}/bin/TCLSTAF.dll during a "Typical" install of STAF for Windows 32-bit (unless another version of Tcl was selected as the default during the install).

2.2 Windows (AMD64, aka x64)

Supported TCL Version	Built with	TCLSTAF library
8.5	8.5.9 (ActiveTcl)	{STAF/Config/STAFRoot}/bin/tcl85/TCLSTAF.dll
8.6	8.6.0 (ActiveTcl)	{STAF/Config/STAFRoot}/bin/tcl86/TCLSTAF.dll
Note: Support for Tcl Version 8.5 is installed by default to {STAF/Config/STAFRoot}/bin/TCLSTAF.dll during a "Typical" install of STAF for Windows x64 (unless another version of Tcl was selected as the default during the install).

2.3 Linux (Intel 32-bit, aka i386 or x86-32)

Supported TCL Version	Built with	TCLSTAF library
8.4	8.5.4.19 (ActiveTcl)	{STAF/Config/STAFRoot}/lib/tcl84/libTCLSTAF.so
8.5	8.5.9 (ActiveTcl)	{STAF/Config/STAFRoot}/lib/tcl85/libTCLSTAF.so
8.6	8.6.0 (ActiveTcl)	{STAF/Config/STAFRoot}/lib/tcl86/libTCLSTAF.so
Note: Support for Tcl Version 8.4 is installed by default to {STAF/Config/STAFRoot}/lib/libTCLSTAF.so during a "Typical" install of STAF for Linux 32-bit (unless another version of Tcl was selected as the default during the install).

2.4 Linux (AMD64, aka x86-64)

>

Supported TCL Version	Built with	TCLSTAF library
8.4	8.5.4.19 (ActiveTcl)	{STAF/Config/STAFRoot}/lib/tcl84/libTCLSTAF.so
8.5	8.5.9 (ActiveTcl)	{STAF/Config/STAFRoot}/lib/tcl85/libTCLSTAF.so
8.6	8.6.0 (ActiveTcl)	{STAF/Config/STAFRoot}/lib/tcl86/libTCLSTAF.so
Note: Support for Tcl Version 8.4 is installed by default to {STAF/Config/STAFRoot}/lib/libTCLSTAF.so during a "Typical" install of STAF for Linux x86-64 (unless another version of Tcl was selected as the default during the install).

3.0 Installation

1. Install STAF's Tcl support by selecting to install "Tcl support" during the install. STAF Tcl support is installed by default for a "typical" install of STAF if using a STAF installer for Windows 32-bit or AMD64, or for Linux 32-bit or AMD64. During the STAF install, you can specify what version of Tcl you will be using as there is a different STAF Tcl library file for each version of Tcl supported by STAF.

   Currently, STAF Tcl support is not provided in the STAF installer files for operating systems other than Windows 32-bit/AMD64 and Linux 32-bit/AMD64 (though you can build STAF Tcl support yourself). See section 1.0 Introduction above for more information on how to build STAF Tcl support yourself.

   Once STAF Tcl support is installed, verify that the STAF Tcl library file exists:

   • On Windows, verify that file TCLSTAF.dll exists in directory C:\STAF\bin, assuming you installed STAF to directory C:\STAF.
   • On Linux, verify that file libTCLSTAF.so exists in directory /usr/local/staf/lib, assuming you installed STAF to directory /usr/local/staf

2. To configure Tcl to find the STAF Tcl support files, you need to set or update your TCLLIBPATH environment variable so that it includes the STAF directory containing the Tcl support files for the version of Tcl that you are using.
   • On Unix, add the <STAF Root>/lib directory to your TCLLIBPATH. For example:

       export TCLLIBPATH=/usr/local/staf/lib

     Or, if you already have set TCLLIBPATH to contain another directory (e.g. /usr/lib), then you would add the STAF lib directory and use a space to separate multiple directories. For example:

       export TCLLIBPATH="/usr/local/staf/lib /usr/lib"

   • On Windows, add the <STAF Root>/bin directory to your TCLLIBPATH.  Note that UNIX style slashes ("/") must be used as the file separator on Windows as well. For example:

       set TCLLIBPATH=C:/STAF/bin

     Or, if you already have set TCLLIBPATH to contain another directory (e.g. C:/Tcl/bin), then you would add the STAF bin directory and use a space to separate multiple directories. For example:

       set TCLLIBPATH="C:/STAF/bin C:/Tcl/bin"

   Note that TCLLIBPATH must contain a Tcl list of directories, using a space to separate multiple directories (unlike the PATH environment variable which uses colons on Unix or semi-colons on Windows to separate multiple directories).

3. Verify that the version of Tcl you have installed matches the STAF Tcl version supported by the TCLSTAF library you specified for the TCLLIBPATH environment variable as there is a different TCLSTAF library for each version of Tcl supported by STAF. See section 2.0 Supported Platforms and Tcl Versions for a list of the Tcl versions supported by STAF by operating system.

4. Finally, you simply need to add a "package require" statement in your Tcl scripts for any of the STAF packages (STAF, STAFLog, STAFMon) that you use in your Tcl script. For example:

     package require STAF
   

4.0 Tcl Script Example

package require STAF

# First, must register with STAF

if {[STAF::Register "Tcl Test"] != $STAF::kOk} {
    puts "Error registering with STAF, RC: $STAF::RC"
    exit $STAF::RC
}

puts "Using handle $STAF::Handle"

# Submit some STAF requests

puts "Testing basic functionality"

STAF::Submit local PING PING

if {$STAF::Result != "PONG"} {
    puts "Wrong output for ping request"
    exit 1
}

if {[STAF::Submit local VAR "RESOLVE STRING {STAF/Config/MachineNickname}"] != $STAF::kOk} {
    puts "Error resolving machine nickname, RC: $STAF::RC, Result: $STAF::Result"
    exit $STAF::RC
}

puts "Machine Nickname: $STAF::Result"

# Unregister with STAF to remove the handle

if {[STAF::UnRegister] != $STAF::kOk} {
    puts "Error unregistering with STAF, RC: $STAF::RC"
    exit $STAF::RC
}

puts "All tests successful"

exit 0

# tcl testTcl.tcl
Using handle 3
Testing basic functionality
Machine Nickname: client1.company.com
All tests successful
#

5.0 Package STAF

• Primary STAF 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
• Data Structure and Marshalling APIs
• STAF::datatype - A procedure that provides subcommands for manipulating various structured data types (i.e. scalar, list, map, marshalling context, None)
• STAF::mapclassdef - A procedure that provides map class definition subcommands that can be used by STAF marshalling contexts
• STAF::mcontext - A procedure that provides STAF marshalling context subcommands used to define structured data
• STAF::marshall - A procedure that converts a data structure into a string-based representation
• STAF::unmarshall - A procedure that converts a string-based marshalled representation back into a data structure. It returns a marshalling context
• STAF::formatObject - A procedure used to convert a data structure into a verbose formatted hierarchical string that can be used when you want a "pretty print" representation of an object
• Private Data Manipulation APIs
  • STAF::AddPrivacyDelimiters - A utility function for adding privacy delimiters to a string for use in protecting private data specified in a STAF command option that supports handling private data
  • STAF::EscapePrivacyDelimiters - A utility function for escaping privacy delimiters in a string
  • STAF::RemovePrivacyDelimiters - A utility function for removing privacy delimiters from a string
  • STAF::MaskPrivateData - A utility function for masking private data

5.1 Primary STAF APIs

These APIs allow you to register/unregister with STAF, submit STAF service requests, and to wrap the values of options used in STAF service requests.

5.1.1 STAF::Register

Description

STAF::Register processName

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.

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"

5.1.2 STAF::Submit

Description

STAF::Submit location service request

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.

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"

5.1.3 STAF::UnRegister

Description

STAF::UnRegister

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.

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.

Examples

if {[STAF::UnRegister] != $STAF::kOk} {
    puts "Error unregistering with STAF, RC: $STAF::RC"
    exit $STAF::RC
}

5.1.4 STAF::WrapData

Description

STAF::WrapData inputString

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

Result

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

Example

set semName {My Synch Sem}
STAF::Submit local sem "event [STAF::WrapData $semName] post"

5.2 Data Structure and Marshalling APIs

These APIs allow you to define, manipulate, and (un)marshall data structures, and print marshalled data in human-readable ("pretty" print) format.

STAF supports the automatic marshalling and unmarshalling of structured data. The act of marshalling takes a data structure and converts it into a string-based representation. The act of unmarshalling reverses this and converts the string-based representation back into a data structure. See Section 6.1, "Marshalling Structured Data" in the STAF User's Guide for more information.

5.2.1 STAF::datatype

Description

STAF::datatype subcommand ?arg ...?

This procedure is used to create structured data type objects (e.g. List, Map, Scalar, Context, None) and to set values for data type objects and to get the value or type for a data type object. Data types are used by STAF to help in marshalling and unmarshalling data.

Since: STAF V3.1.0

The STAF::datatype procedure supports the following subcommands and their arguments:

createNone

Creates a None data type which serves as an empty placeholder.

createScalar ?value?

Creates a Scalar data type which holds a single data item such as a string or number.

The optional argument value specifies the value to assign.

createList ?value?

Creates a List data type which holds a ordered collection of arbitrary objects. Each object in a list can be of data type None, Scalar, List, Map, or a Marshalling Context.

The optional argument value specifies the value to assign.

createMap ?value?

Creates a Map data type which holds a unordered collection of arbitrary objects. Each object in a dictionary is stored and fetched by key.

The optional argument value specifies the value to assign.

createContext ?value?

Creates a Context data type which represents a STAF Marshalling Context which is a container for map class definitions and a root object which is a data structure that may use map class definitions.

The optional argument value specifies the root object to assign to the context.

Generally, you should use the STAF::mcontext create ?rootobject? procedure instead of this one to create a STAF marshalling context.

getType object

Returns the type of the specified object which could be one of the following:

• STAF::NoneType
• STAF::ScalarType
• STAF::ListType
• STAF::MapType
• STAF::ContextType

The required argument object specifies the object.

getValue object

Returns the value of the specified object.

The required argument object specifies the object.

setValue objectVar newValue

Sets the value for the specified object variable name.

The required argument objectVar specifies the variable name of the object to set.

The required argument newValue specified the value to assign to the object.

Examples

# Using data type None

puts "\nUsing data type: None"

set dtNone [STAF::datatype createNone]
puts "dtNone value: [STAF::datatype getValue $dtNone]"

# Check if an object is a None data type
if {[STAF::datatype getType $dtNone] == $STAF::NoneType} {
    puts "Data Type: [STAF::datatype getType $dtNone]"
}

# Using data type Context

puts "\nUsing data type: Context"

# Create a Context data type with None as the root object
set dtContext [STAF::datatype createContext]
puts "dtContext value: [STAF::datatype getValue $dtContext]"

# Create a Context data type with a List data type as the root object
set dtList [STAF::datatype createList [list "List" "Test" "Value"]]
set dtContext [STAF::mcontext create $dtList]
puts "dtContext value: [STAF::datatype getValue $dtContext]"

# Check if an object is a Context data type
if {[STAF::datatype getType $dtContext] == $STAF::ContextType} {
    puts "Data Type: [STAF::datatype getType $dtContext]"
}

# Using data type Scalar

puts "\nUsing data type: Scalar"

# Create a Scalar data type with an empty string value
set dtScalar [STAF::datatype createScalar]
puts "dtScalar value: [STAF::datatype getValue $dtScalar]"

# Set the value for a Scalar data type to a string
set myString  "Testing 123..."
STAF::datatype setValue dtScalar $myString
puts "dtScalar value: [STAF::datatype getValue $dtScalar]"

# Set the value for a Scalar data type to a number
set myRC 99
set dtScalar [STAF::datatype createScalar $myRC]
puts "dtScalar value: [STAF::datatype getValue $dtScalar]"

# Check if an object is a Scalar data type
if {[STAF::datatype getType $dtScalar] == "$STAF::ScalarType"} {
    puts "Data Type: [STAF::datatype getType $dtScalar]"
}

# Using data type List

puts "\nUsing data type: List"

# Create an empty List data type
set dtList [STAF::datatype createList]
puts "dtList value: [STAF::datatype getValue $dtList]"

# Set the value for a List data type
set listTestValue [list "List" "Test" "Value"]
STAF::datatype setValue dtList $listTestValue
puts "dtList value: [STAF::datatype getValue $dtList]"

# Create a List data type assigning an initial value
set listInitValue [list "List" "Init" "Value"]
set dtList [STAF::datatype createList $listInitValue]
puts "dtList value: [STAF::datatype getValue $dtList]"

# Change the value for a List data type
lappend listTestValue "And"
lappend listTestValue "More"
STAF::datatype setValue dtList $listTestValue
puts "dtList value: STAF::datatype getValue $dtList]"

# Append entries to a List data type
lappend dtList "And"
lappend dtList "More"
puts "dtList value: [STAF::datatype getValue $dtList]"

# Check if an object is a List data type
if {[STAF::datatype getType $dtList] == "$STAF::ListType"} {
    puts "Data Type: [STAF::datatype getType $dtList]"
}

# Using data type Map

puts "\nUsing data type: Map"

# Create an empty Map data type
set dtMap [STAF::datatype createMap]
puts "dtMap value: [STAF::datatype getValue $dtMap]"

# Set the value for a Map data type
set mapTest(key1) value1
set mapTest(key2) value2
set mapTestValue [array get mapTest]
STAF::datatype setValue dtMap $mapTestValue
puts "dtMap value: [STAF::datatype getValue $dtMap]"

# Create a Map data type assigning an initial value
set mapInit(key3) value3
set mapInit(key4) value4
set mapInitValue [array get mapInit]
set dtMap [STAF::datatype createMap $mapInitValue]
puts "dtMap value: [STAF::datatype getValue $dtMap]"

# Change the value for a Map data type
STAF::datatype setValue dtMap $mapTestValue
puts "dtMap value: [STAF::datatype getValue $dtMap]"

# Add an additional key/value to a Map data type
set mapAdditionalValue(key5) value5
append mapTestValue " " [array get mapAdditionalValue]
append dtMap        " " [array get mapAdditionalValue]
puts "dtMap value: [STAF::datatype getValue $dtMap]"

# Check if an object is a Map data type 
if {[STAF::datatype getType $dtMap] == "$STAF::MapType"} {
    puts "Data Type: [STAF::datatype getType $dtMap]"
}

# Using data types List and Map to create a list of maps

puts "\nUsing data types List and Map to create a list of maps"
set map1(key1) value1
set map1(key2) value2
set map1Value [array get map1]
set dtMap1 [STAF::datatype createMap $map1Value]

set map2(test1) C:/tests/test1.cmd
set map2(test2) C:/tests/test2.sh
set map2Value [array get map2]
set dtMap2 [STAF::datatype createMap $map2Value]

set listValue [list $dtMap1 $dtMap2]
set dtList [STAF::datatype createList $listValue]
puts "dtList: $dtList"
puts "dtList value: [STAF::datatype getValue $dtList]"

This example prints the following:

Using data type: None
dtNone value: None
Data Type: STAF_DT_NONE

Using data type: Context
dtContext value:
dtContext value: mapClassMap STAF_DT_MAP rootObj {STAF_DT_LIST List Test Value}
Data Type: STAF_DT_CONTEXT

Using data type: Scalar
dtScalar value:
dtScalar value: Testing 123...
dtScalar value: 99
Data Type: STAF_DT_SCALAR

Using data type: List
dtList value:
dtList value: List Test Value
dtList value: List Init Value
dtList value: List Test Value And More
dtList value: List Test Value And More And More
Data Type: STAF_DT_LIST

Using data type: Map
dtMap value:
dtMap value: key1 value1 key2 value2
dtMap value: key3 value3 key4 value4
dtMap value: key1 value1 key2 value2
dtMap value: key1 value1 key2 value2 key5 value5
Data Type: STAF_DT_MAP

Using data types List and Map to create a list of maps
dtList: STAF_DT_LIST {STAF_DT_MAP key1 value1 key2 value2} {STAF_DT_MAP test1 C:
/tests/test1.cmd test2 C:/tests/test2.sh}
dtList value: {STAF_DT_MAP key1 value1 key2 value2} {STAF_DT_MAP test1 C:/tests/
test1.cmd test2 C:/tests/test2.sh}

5.2.2 STAF::mapclassdef

Description

STAF::mapclassdef subcommand ?arg ...?

This procedure is used to create and/or to set/get metadata associated with a STAF map class. A STAF map class definition can be useful if you want to generate a STAF marshalling context with map classes. In particular, a map class definition defines the keys associated with the map class. The map class definition is used to reduce the size of a marshalling map class in comparison to a map containing the same data. It also contains information about how to display instances of the map class, such as the order in which to display the keys and the display names to use for the keys. You get and set map class definitions using the STAF::mcontext procedure's setMapClassDefinition and getMapClassDefinition subcommands.

Since: STAF V3.1.0

The STAF::mapclassdef procedure supports the following subcommands and their arguments:

create mapclassname

Creates a map class definition (with no keys defined) and returns it.

The required argument mapclassname specifies the name of the STAF map class definition.

createInstance mapclassdef

Returns a map containing one entry with a key name of 'staf-map-class-name' with a value set to the name of the map class definition.

The required argument mapclassdef specifies the map class definition.

addKey mapclassdefVar keyName ?displayName?

Adds a key to the map class definition.

The required argument mapclassdefVar specifies the variable name of the map class definition.

The required argument keyName specifies the name of a key.

The optional argument displayName specifies a string to use when displaying the key. The default is None which indicates to use the actual key name when displaying the key.

setKeyProperty mapclassdefVar keyName property value

Sets a property such as a short display name ("display-short-name") for a key in the map class definition.

The required argument mapclassdefVar specifies the variable name of the map class definition.

The required argument keyName specifies the name of a key for which this property is being set.

The required argument property specifies the name of the property being set. The only property name currently recognized is 'display-short-name' which is used by the STAF executable when displaying a result in a tabular format when the length of the values for the fields is less than the length of the 'display-name'.

The required argument value specifies the value for the property being set.

getKeys mapclassdef

Returns a list of all of the keys. Each entry in the list is a map containing a key named 'key', and optionally, a key named 'display-name', and optionally, any key property names such as 'display-short-name'.

The required argument mapclassdef specifies the map class definition.

getName mapclassdef

Returns the name for the map class definition.

The required argument mapclassdef specifies the map class definition.

Example

# Create a map class definition

set myMapClassDef [STAF::mapclassdef create "Test/MyMap"]
STAF::mapclassdef addKey myMapClassDef "name" "Name"
STAF::mapclassdef addKey myMapClassDef "exec" "Executable"
STAF::mapclassdef addKey myMapClassDef "testType" "Test Type"
STAF::mapclassdef setKeyProperty myMapClassDef "testType" "display-short-name" "Test"
STAF::mapclassdef addKey myMapClassDef "outputList" "Outputs"

set mapClassDefName [STAF::mapclassdef getName $myMapClassDef]
puts "The keys for map class definition '$mapClassDefName' are:"
puts "[STAF::formatObject [STAF::mapclassdef getKeys $myMapClassDef]]"

The keys for map class definition 'Test/MyMap' are:
[
  {
    display-name: Name
    key         : name
  }
  {
    display-name: Executable
    key         : exec
  }
  {
    display-name      : Test Type
    key               : testType
    display-short-name: Test
  }
  {
    display-name: Outputs
    key         : outputList
  }
]

5.2.3 STAF::mcontext

Description

STAF::mcontext subcommand ?arg ...?

This procedure is used to create and/or access a STAF marshalling context which is used by STAF to help in marshalling and unmarshalling data. A marshalling context is simply a container for map class definitions and a data structure that uses (or is defined in terms of) them.

In order to use a map class when marshalling data, you must add the map class definition to the marshalling context, set the root object of the marshalling context to the object you want to marshall, and then marshall the marshalling context itself. When you unmarshall a data structure, you will always receive a marshalling context. Any map class definitions referenced by map classes within the data structure will be present in the marshalling context.

The primary use of a STAF marshalling context is to represent multi-valued results that consist of a data structure (e.g. results from a QUERY/LIST service request, etc.) as a string that can also be converted back into the data structure. This string can be assigned to the string result buffer returned from the service request.

Since: STAF V3.1.0

The STAF::mcontext procedure supports the following subcommands and their arguments:

create ?rootObject?

Creates a STAF marshalling context.

The optional argument rootObject specifies the root object to be marshalled. The default is None.

setMapClassDefinition mcVar mapClassDef

Called to add a map class definition to the marshalling context.

The required argument mcVar specifies the variable name of the marshalling context.

The required argument mapClassDef specifies a map class definition object that can be used when marshalling the object. You may call this method any number of times to set multiple map class definition objects for the marshalling context.

getMapClassDefinition mc mapClassName

Returns the map class definition for the specified map class name.

The required argument mc specifies the marshalling context.

The required argument mapClassName specifies a string containing the name of the map class definition object that you want to return.

hasMapClassDefinition mc mapClassName

Called to determine whether the marshalling context contains the specified map class definition. Returns a true value if it exists.

The required argument mc specifies the marshalling context.

The required argument mapClassName specifies a string containing the name of the map class definition. This subcommand will check if it exists in the marshalling context's list of map class definitions.

getMapClassMap mc

Returns a map of the map class definitions for the marshalling context where each key in the map is the name of a map class definition and each value is a map class definition object.

The required argument mc specifies the marshalling context.

getMapClassDefinitionNames mc

Returns a map of the names of the map class definitions in the marshalling context.

The required argument mc specifies the marshalling context.

setRootObject mcVar rootObject

Sets the root object for the marshalling context.

The required argument mcVar specifies the variable name of the marshalling context.

The required argument rootObject can specify any object.

getRootObject mc

Returns the root object for the marshalling context.

The required argument mc specifies the marshalling context.

getPrimaryObject mc

Returns the primary object for the marshalling context which is the marshalling context object itself if the marshalling context contains one or more map class definitions. Otherwise, it returns the root object.

The required argument mc specifies the marshalling context.

marshall mc

This is the marshalling function that creates marshalled data for the marshalling context. Returns a string containing the marshalled data.

The required argument mc specifies the marshalling context.

Note that this is basically shorthand for a STAF::marshall procedure call when specifying a marshalling context as the object to be marshalled.

formatObject mc

Converts a marshalling context's root object into a verbose formatted hierarchical string that can be used when you want a "pretty print" representation of a marshalling context's root object. Returns a string containing the formatted output.

The required argument mc specifies the marshalling context whose root object will be formatted in a verbose, more readable format.

Note that this is basically shorthand for a STAF::formatObject procedure call when specifying a marshalling context as the object to be "pretty printed".

Examples

# Create a map class definition

set myMapClassDef [STAF::mapclassdef create "Test/MyMap"]
STAF::mapclassdef addKey myMapClassDef "name" "Name"
STAF::mapclassdef addKey myMapClassDef "exec" "Executable"

# Create a marshalling context and set the map class definition
# and assign myTestList as the root object

set mc [STAF::mcontext create]
STAF::mcontext setMapClassDefinition mc $myMapClassDef

# From a list of maps, create a list datatype of map class datatypes
# and marshall that data and assign to a message

set testList [list {exec /tests/TestA.py name TestA} \
                   {exec /tests/TestB.sh name TestB} \
                   {exec /tests/TestC.cmd name TestC}]

set myTestList [STAF::datatype createList]

foreach testObj $testList {
   array set test $testObj
   set testMapObj [STAF::mapclassdef createInstance $myMapClassDef]
   array set testMap [STAF::datatype getValue $testMapObj]
   set testMap(name) $test(name)
   set testMap(exec) $test(exec)
   lappend myTestList [STAF::datatype createMap [array get testMap]]
}

STAF::mcontext setRootObject mc $myTestList

puts "\nTest List:\n[STAF::mcontext formatObject $mc]"

# Create a string from the marshalling context
# This string could be a message that you log or send to a queue, etc.

set stringResult [STAF::mcontext marshall $mc]

# Convert the marshalled string representation back into a list

set mc2 [STAF::unmarshall $stringResult]
set theTestList [STAF::mcontext getRootObject $mc2]

puts "\nTest List:\n[STAF::mcontext formatObject $mc2]"

This example prints the following:

Test List:
[
  {
    Name      : TestA
    Executable: /tests/TestA.py
  }
  {
    Name      : TestB
    Executable: /tests/TestB.sh
  }
  {
    Name      : TestC
    Executable: /tests/TestC.cmd
  }
]

Test List:
[
  {
    Name      : TestA
    Executable: /tests/TestA.py
  }
  {
    Name      : TestB
    Executable: /tests/TestB.sh
  }
  {
    Name      : TestC
    Executable: /tests/TestC.cmd
  }
]

5.2.4 STAF::isMarshalledData

Description

STAF::isMarshalledData someData

A procedure used to test if the data specified by argument someData is a string-based marhalled representation.

The required argument someData is the string to be tested.

Since: STAF V3.2.1

Result

Returns a true value (1) if the data a marshalled string or a false value (0) if the data is not a marshalled string.

Examples

if {[STAF::isMarshalledData $message]} {
    # Unmarshall the data
    set mc [STAF::unmarshall $message]
}

5.2.5 STAF::marshall

Description

STAF::marshall ?-context context? object

A procedure used to create a string-based marshalled representation of the object specified by the argument object. Returns a marshalled string.

The optional -context context option specifies a marshalling context to use. The default is None.

The required argument object is the object to be marshalled.

Since: STAF V3.1.0

Note, that the STAF::mcontext procedure also provides a marshall subcommand to marshall a marshalling context's root object.

Result

Returns a string containing the marshalled data.

Examples

set myTestArray(name) "TestA"
set myTestArray(exec) "/tests/TestA.py"
set myTestArray(testType) "FVT"
set myTestArray(outputs) {"TestA.out" "TestA.err"}
set myTestArrayString [array get myTestArray]
set myArrayObject [STAF::datatype createMap $myTestArrayString]

set message [STAF::marshall $myArrayObject]

set request "QUEUE MESSAGE [STAF::WrapData $message]"

if {[STAF::Submit local QUEUE $request] != $STAF::kOk} {
    puts "Error on STAF local QUEUE $request"
    puts "RC=$STAF::RC, Result: $STAF::Result"
    exit $STAF::RC
}

# Another process could obtain the message from the queue and unmarshall
# it to get the original dictionary (map) object

if {[STAF::Submit local QUEUE GET] != $STAF::kOk} {
    puts "Error on STAF local QUEUE GET"
    puts "RC=$STAF::RC, Result: $STAF::Result"
    exit $STAF::RC
}

set mc [STAF::unmarshall $STAF::Result]
set messageMapObj [STAF::mcontext getRootObject $mc]
array set messageMap [STAF::datatype getValue $messageMapObj]
array set yourTestArray [STAF::datatype getValue $messageMap(message)]

puts "Name     : $yourTestArray(name)"
puts "Exec     : $yourTestArray(exec)"
puts "Test Type: $yourTestArray(testType)"
puts "Outputs  : $yourTestArray(outputs)"

This example prints the following:

Name     : TestA
Exec     : /tests/TestA.py
Test Type: FVT
Outputs  : "TestA.out" "TestA.err"

This example creates a marshalling context with one map class definition and a list where each entry is a map. It then creates a string-based marshalled representation of it. Finally, it prints the marshalled data using the STAF::formatObject procedure.

# Create a map class definition

set myMapClassDef [STAF::mapclassdef create "Test/MyMap"]
STAF::mapclassdef addKey myMapClassDef "name" "Name"
STAF::mapclassdef addKey myMapClassDef "exec" "Executable"

# Create a marshalling context and set the map class definition

set mc [STAF::mcontext create]
STAF::mcontext setMapClassDefinition mc $myMapClassDef

# From a list of maps, create a list datatype of map class datatypes
# and marshall that data and assign to a message

set testList [list {exec /tests/TestA.py name TestA} \
                   {exec /tests/TestB.sh name TestB} \
                   {exec /tests/TestC.cmd name TestC}]

set myTestList [STAF::datatype createList]

foreach testObj $testList {
   array set test $testObj
   set testMapObj [STAF::mapclassdef createInstance $myMapClassDef]
   array set testMap [STAF::datatype getValue $testMapObj]
   set testMap(name) $test(name)
   set testMap(exec) $test(exec)
   lappend myTestList [STAF::datatype createMap [array get testMap]]
}

set message [STAF::marshall -context $mc $myTestList]
puts "Formatted Data:\n$[STAF::formatObject -context $mc $myTestList]"

This example prints the folowing:

[
  {
    Name      : TestA
    Executable: /tests/TestA.py
  }
  {
    Name      : TestB
    Executable: /tests/TestB.sh
  }
  {
    Name      : TestC
    Executable: /tests/TestC.cmd
  }
]

5.2.6 STAF::unmarshall

Description

STAF::unmarshall ?-context context? ?-ignoreIndirectObjects? data

A procedure used to convert a string-based marshalled representation specified by argument data back into a data structure. It returns a marshalling context from which you can get the data structure via the STAF::mcontext procedure's subcommand getRootObject.

The optional -context context option specifies the STAF marshalling Context datatype object that should be used when unmarshalling the string. The default is None. Note that a new marshalling context will be returned even if an existing marshalling context is specified for this option.

The optional -ignoreIndirectObjects option can be used to control how to unmarshall the string. When a string is unmarshalled into a data structure, it is possible that one of the string objects that is unmarshalled is itself the string form of another marshalled data structure. The default is to recursively unmarshall these nested objects. Use the -ignoreIndirectObjects option to disable this additional processing.

The required argument data is a string to be unmarshalled.

Since: STAF V3.1.0

Result

Returns a marshalling context from which you can get the data structure via the STAF::mcontext procedure's subcommand getRootObject.

Note that STAF service requests that return multiple values in their result buffer return marshalled data. Refer to the service request's documentation for details on the data structure (e.g. list, map, etc) resulting from unmarshalling the result from a service request that returns marshalled data.

Examples

# Submit a query request to the FS Service to query info about a file

set fileName "{STAF/Config/ConfigFile}"
set request "QUERY ENTRY $fileName"
puts "STAF local FS $request\n"

if {[STAF::Submit local FS $request] != $STAF::kOk} {
    puts "Error on STAF local FS $request"
    puts "RC=$STAF::RC, Result: $STAF::Result"
    exit $STAF::RC
}

set mc [STAF::unmarshall $STAF::Result]
set entryMapObj [STAF::mcontext getRootObject $mc]
array set entryMap [STAF::datatype getValue $entryMapObj]

# Submit a resolve requset to the VAR service to resolve the STAF variable
STAF::Submit local VAR "RESOLVE STRING $fileName"
set resolvedFileName $STAF::Result

if {$entryMap(type) == "F"} {
    puts "File Name    : $resolvedFileName"
    puts "File Size    : $entryMap(lowerSize)"
    puts "Last Modified: $entryMap(lastModifiedTimestamp)"
} else {
    puts "$resolvedFileName is not a file.  Type=$entryMap(type)"
}

This example could print something like the following:

STAF local FS QUERY ENTRY {STAF/Config/ConfigFile}

File Name    : C:\STAF\bin\staf.cfg
File Size    : 7333
Last Modified: 20060913-16:36:48

This example submits a request to the PROCESS service to run a command on a machine and to wait for the command to complete. The request returns marshalled data whose root object is a map that contains keys like 'rc' and 'fileList'. The value for 'fileList' is a list of the returned files. Each entry in the list consists of a map that contains keys 'rc' and 'data'. In our PROCESS START request, we returned one file, stdout (and returned stderr to this same file). (Note that the STAF User's Guide defines the results for each request submitted to an internal STAF service.)

# Submit a PROCESS START request and wait for it to complete

set command "dir {STAF/Config/STAFRoot}"
set request "START SHELL COMMAND [STAF::WrapData $command] RETURNSTDOUT STDERRTOSTDOUT WAIT"
puts "\nSTAF local PROCESS $request"

if {[STAF::Submit local PROCESS $request] != $STAF::kOk} {
    puts "Error on STAF local PROCESS $request"
    puts "Expected RC: 0"
    puts "Received RC: $STAF::RC, Result: $STAF::Result"
    exit $STAF::RC
}

# Unmarshall the result which is a marshalling context whose 
# root object is a map containing keys 'rc', and 'fileList'.
# The value for 'fileList' is a list of the returned files.
# Each entry in the list consists of a map that contains keys
# 'rc' and 'data'.  In our PROCESS START request, we returned
# one file, stdout (and returned stderr to this same file).

set mc [STAF::unmarshall $STAF::Result]
set processMapObj [STAF::mcontext getRootObject $mc]
array set processMap [STAF::datatype getValue $processMapObj]

puts "Process RC: $processMap(rc)"

# Verify that the rc is 0 for returning data for the Stdout file

set fileListObj [STAF::datatype getValue $processMap(fileList)]
set stdoutFileObj [STAF::datatype getValue [lindex $fileListObj 0]]
array set stdoutFileMap [STAF::datatype getValue $stdoutFileObj]

if {$stdoutFileMap(rc) != $STAF::kOk} {
    puts "Error on retrieving process's stdout data."
    puts "Expected RC: 0"
    puts "Received RC: $stdoutFileMap(rc)"
    exit $stdoutFileMap(rc)
}

# Print the data in the stdout file created by the process

puts "\nProcess Stdout file contains:\n$stdoutFileMap(data)"

# Verify that the process rc is 0

if {$processMap(rc) != $STAF::kOk} {
    puts "Process RC: $processMap(rc)"
    puts "Expected Process RC: 0"
    exit $processMap(rc)
}

This example could print something like the following:

STAF local PROCESS START SHELL COMMAND :26:dir {STAF/Config/STAFRoot} RETURNSTDOUT STDERRTOSTDOUT WAIT

Process Stdout file contains:
 Volume in drive C has no label.
 Volume Serial Number is B0B7-F95A

 Directory of C:\STAF

01/26/2006  02:56p                .
01/26/2006  02:56p                ..
01/26/2006  02:56p                lib
01/26/2006  02:56p                codepage
01/26/2006  02:56p                samples
01/26/2006  02:57p                include
01/26/2006  02:57p                bin
02/25/2008  01:30p              17,029 LICENSE.htm
01/26/2006  03:04p                docs
01/26/2006  03:11p                data
02/12/2008  05:05p                  25 STAFReg.inf
06/05/2008  10:17a               8,729 NOTICES.htm
06/24/2008  04:34p                  77 install.properties
               4 File(s)         72,601 bytes
               9 Dir(s)   8,199,012,352 bytes free

5.2.7 STAF::formatObject

Description

STAF::formatObject ?-context context? object

A procedure used to convert a data structure (specified by argument object) into a verbose formatted hierarchical string that can be used when you want a "pretty print" representation of an object. Returns a string containing the formatted output.

The optional -context context option specifies the STAF marshalling Context datatype object that should be used when generating the "pretty print" output. The default is None.

The required argument object specifies the object to be formatted in a verbose, more readable format.

Since: STAF V3.2.1

Note, that the STAF::mcontext procedure also provides a formatObject subcommand to "pretty print" a marshalling context's root object.

Result

Returns a string representing the object in a verbose, more readable format.

Examples

set myTestMap(name) TestA
set myTestMap(exec) "/tests/TestA.tcl"
set myTestMap(testType) FVT

set listValue [list TestA.out TestA.err]
set dtList [STAF::datatype createList $listValue]

set myTestMap(outputs) $dtList
set dtTestMap [STAF::datatype createMap [array get myTestMap]]

puts [STAF::formatObject $dtTestMap]

This example could print the following output:

{
  outputs : [
    TestA.out
    TestA.err
  ]
  name    : TestA
  exec    : /tests/TestA.tcl
  testType: FVT
}

This example prints the result from a FS QUERY ENTRY request in a "pretty" verbose format.

set fileName "{STAF/Config/ConfigFile}"
set request "QUERY ENTRY $fileName"
puts "STAF local FS $request\n"

if {[STAF::Submit local FS $request] != $STAF::kOk} {
    puts "Error on STAF local FS $request"
    puts "RC=$STAF::RC, Result: $STAF::Result"
    exit $STAF::RC
}

set mc [STAF::unmarshall $STAF::Result]
puts "Formatted output:\n[STAF::formatObject $mc]"

If successful, this example could print something like the following output:

STAF local FS QUERY ENTRY {STAF/Config/ConfigFile}

Formatted output:
{
  Name              : c:\staf\bin\STAF.cfg
  Type              : F
  Upper 32-bit Size : 0
  Lower 32-bit Size : 5902
  Modified Date-Time: 20061122-11:07:02
}

5.3 Private Data Manipulation APIs

These APIs allow you to handle private data. See Section 7.3, "Private Data" in the STAF User's Guide for more information about handling private data.

5.3.1 STAF::AddPrivacyDelimiters

Description

STAF::AddPrivacyDelimiters data

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

Result

Returns a String object containing the string with opening and closing privacy delimiters added and escapes any privacy delimiters already contained in the string with a caret (^). If the string has length 0 or already has an unescaped opening privacy delimiter at the beginning and an unescaped closing privacy delimiter at the end, privacy delimiters are not added.

Examples:

• If the data is "passw0rd", this method would return string "!!@passw0rd@!!".
• If the data is "Password: !!@secret@!!", this method would return "!!@Password: ^!!@secret^@!!@!!".

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"

5.3.2 STAF::EscapePrivacyDelimiters

Description

STAF::EscapePrivacyDelimiters data

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

Result

Returns a String object containing the string with privacy delimiters, if any, escaped.

For example, if the data is "passw@!!d", this method would return "passw^@!!d".

Examples

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

5.3.3 STAF::RemovePrivacyDelimiters

Description

STAF::RemovePrivacyDelimiters data ?numLevels?

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

Result

Returns a String containing the string with privacy delimiters, if any, removed.

Examples:

• If the data is "!!@passw0rd@!!", this method would return "passw0rd".
• If the data is "!!@passw^@!!d@!!", this method would return "passw@!!d".
• If the data is "!!@Password=^!!@secret^@!!.@!!" and the numLevels is 0, this method would return "Password=secret".
• If the data is "!!@Password=^!!@secret^@!!.@!!" and the numLevels is 1, this method would return "Password=!!@secret@!!".

Examples

set protectedPw "!!@secret@!!"
set password [STAF::RemovePrivacyDelimiters $protectedPw]

5.3.4 STAF::MaskPrivateData

Description

STAF::MaskPrivateData data

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

Result

Returns a String containing the string with any private data masked.

Examples:

• If the data is "!!@passw0rd@!!", this method would return "**************".
• If the data is "testA -password !!@secret@!!", this method would return "testA -password ************".

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

5.4 STAF Return Codes

5.5 STAF Constants

STAF::NoneType

Set to "STAF_DT_NONE".

STAF::ScalarType

Set to "STAF_DT_SCALAR".

STAF::ListType

Set to "STAF_DT_LIST".

STAF::MapType

Set to "STAF_DT_MAP".

STAF::ContextType

Set to "STAF_DT_CONTEXT".

STAF::CompleteTypeList

Set to a list containing $STAF::NoneType, $STAF::ScalarType, $STAF::ListType, $STAF::MapType, and $STAF::ContextType.

6.0 Package STAFMon

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

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

6.2 STAF::Monitor::Log

Description

STAF::Monitor::Log message ?options?

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.

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.

Examples

if {[STAF::Monitor::Log "Hello World"] != $STAF::kOk} {
    puts "Error logging message to Monitor, RC: $STAF::RC"
    return $STAF::RC
}

7.0 Package STAFLog

7.1 Log Service Variables and Return Codes

• STAF::Log::kInvalidLevel
• STAF::Log::kInvalidLogFileFormat
• STAF::Log::kPurgeFailure

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)

7.2 STAF::Log::Init

Description

STAF::Log::Init logName ?logType? ?monitorMask?

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

Result

This function returns a numeric return code. Return codes are documented in the STAF User's Guide.

Examples

STAF::Log::Init Testcase1 GLOBAL "FATAL ERROR"

7.3 STAF::Log::Log

Description

STAF::Log::Log level message ?options?

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.

Result

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
}