Procedure Information for wsUtil.tcl:

  1. argParse
  2. nsJoin
  3. qualifyNS
  4. alias
  5. nsExist
  6. bomb
  7. execCgi
  8. fileCurrent
  9. fileUsable
  10. createTags
  11. reqList
  12. tclGrep
  13. tclTouch
  14. trimSplit
  15. compSplit
  16. getEnv
  17. compareEnv
  18. writeLog
  19. remLogMsg
  20. errLogMsg
  21. jobLogMsg
  22. mkPathAbs
  23. buildString
  24. header
  25. padString
  26. initVars
  27. serialize
  28. loadSerial
  29. readOnly
  30. readOnlyArray
  31. undoChange
  32. undoArrChange
  33. checkChangeScope
  34. ascii2hex
  35. tclChmod
  36. trimWhite


    Procedure: argParse

    Generalized argument parser / tokenizer. The parser recognizes three types of tokens: (1) Key-value pairs: '-key value' (2) Switches: '--switchName' (3) Regular arguments: Strings that don't fit either (1) or (2)


    Procedure Data

    • Name: argParse
    • Parent Namespace: webSubmit::util
    • Arglist: args
    • Return: None


    Argument definitions:

    • args : Arguments to parse


    Procedure: nsJoin

    Procedure to join a group of strings into a namespace name (either fully- or partially-qualified)


    Procedure Data

    • Name: nsJoin
    • Parent Namespace: webSubmit::util
    • Arglist: args
    • Return: Fully- or partially-qualified namespace name corresponding to the concatenation of $NSnames with "::" between each element


    Argument definitions:

    • args : [-partial] NSnames. Specifies whether qualification is partial and then list of names to be joined


    Procedure: qualifyNS

    Procedure to resolve a namespace name into one that is fully-qualified. If the name is already fully-qualified, nothing is done. If partially-qualified, then the name for the calling scope is prepended. The syntax is as follows: qualifyNS scope NSname Scope: wsRoot: Name is qualified wrt webSubmit root namespace global: Name is qualified wrt global namespace (::) someNamespaceName: Name is qualified wrt specified name


    Procedure Data

    • Name: qualifyNS
    • Parent Namespace: webSubmit::util
    • Arglist: scope NS
    • Return: Fully-qualified namespace


    Argument definitions:

    • scope : Scope in which qualification will be made
    • NS : Namespace name to qualify


    Procedure: alias

    Procedure to declare a group of variables within a namespace and to associate these variables with variables of the same name in the calling scope. This is equivalent to a global statement, with the global namespace being replaced by the namespace specified in the argument.


    Procedure Data

    • Name: alias
    • Parent Namespace: webSubmit::util
    • Arglist: args
    • Return: Status (Error = 1)


    Argument definitions:

    • args : List of variable names to be declared


    Procedure: nsExist

    Procedure to check to see if a namespace is defined


    Procedure Data

    • Name: nsExist
    • Parent Namespace: webSubmit::util
    • Arglist: args
    • Return: Status (Error = 1)


    Argument definitions:

    • args : Argument list (passed on to qualifyNS)


    Procedure: bomb

    Procedure to handle bombs gracefully and send output through CGI


    Procedure Data

    • Name: bomb
    • Parent Namespace: webSubmit::util
    • Arglist: proc string
    • Return: None


    Argument definitions:

    • proc : Name of procedure in which bomb occurred
    • string : String to return in bomb error message


    Procedure: execCgi

    Procedure to trap bogus errors generated by exec when performed in a CGI context. Error is stripped from output of exec and returned, unless a real error is generated


    Procedure Data

    • Name: execCgi
    • Parent Namespace: webSubmit::util
    • Arglist: cmd
    • Return: Output from exec if normal, or 'ERROR' if real error detected


    Argument definitions:

    • cmd : Command to evaluate in exec


    Procedure: fileCurrent

    Determine whether thatFile is current with respect to than thisFile. If thatFile does not exist, it is not current. ThisFile must exist.


    Procedure Data

    • Name: fileCurrent
    • Parent Namespace: webSubmit::util
    • Arglist: thisFile thatFile
    • Return: False (0) if thisFile exists and is newer than thatFile, or thatFile does not exist. True (1) if thisFile exists and is older than thatFile. Exception if thisFile does not exist.


    Argument definitions:

    • thisFile : UNDEFINED
    • thatFile : UNDEFINED


    Procedure: fileUsable

    Determine whether a file exists and is readable.


    Procedure Data

    • Name: fileUsable
    • Parent Namespace: webSubmit::util
    • Arglist: theFile
    • Return: True (1) if the file exists and is readable, false (0) otherwise.


    Argument definitions:

    • theFile : UNDEFINED


    Procedure: createTags

    Procedure to create link tags and variables


    Procedure Data

    • Name: createTags
    • Parent Namespace: webSubmit::util
    • Arglist: tagList titleList urlList
    • Return: Status (Error = Error code)


    Argument definitions:

    • tagList : List of tags for links
    • titleList : List of titles for links
    • urlList : List of URL's for tags


    Procedure: reqList

    Procedure to check whether one list possesses at least the elements contained in another list


    Procedure Data

    • Name: reqList
    • Parent Namespace: webSubmit::util
    • Arglist: varList reqList
    • Return: 1 - List contains required elements, 0 - otherwise


    Argument definitions:

    • varList : List of existing elements
    • reqList : List of required elements


    Procedure: tclGrep

    Procedure to perform the equivalent of UNIX 'grep' on a file. The purpose of writing such a routine is to provide for platform independence.


    Procedure Data

    • Name: tclGrep
    • Parent Namespace: webSubmit::util
    • Arglist: string file
    • Return: List of lines containing string (Empty if no match), Error


    Argument definitions:

    • string : String to search for in file
    • file : File to search


    Procedure: tclTouch

    Procedure to create a zero-size file. Equivalent to the UNIX 'touch' command. Provided for platform independence.


    Procedure Data

    • Name: tclTouch
    • Parent Namespace: webSubmit::util
    • Arglist: fileName
    • Return: Error Status


    Argument definitions:

    • fileName : Name of file to create (either absolute or relative path)


    Procedure: trimSplit

    Procedure to split a string into a list and remove any whitespace around entries in the list. This is to deal with situations due to spaces in a list with non-whitespace separators. In addition, and separator characters char are ignored if they fall within quotation marks (").


    Procedure Data

    • Name: trimSplit
    • Parent Namespace: webSubmit::util
    • Arglist: string char
    • Return: List corresponding to string with internal white space removed


    Argument definitions:

    • string : UNDEFINED
    • char : UNDEFINED


    Procedure: compSplit

    Procedure to split a string into a list and remove all empty entries from the list. This is to deal with situations where the string that is being split contains sections of white-space that need to be compressed


    Procedure Data

    • Name: compSplit
    • Parent Namespace: webSubmit::util
    • Arglist: string
    • Return: List corresponding to string with internal white space removed


    Argument definitions:

    • string : String to be split into list


    Procedure: getEnv

    Procedure to find and return the value of a specified environment variable (global). If the variable does not exist, an error is raised


    Procedure Data

    • Name: getEnv
    • Parent Namespace: webSubmit::util
    • Arglist: varName
    • Return: Value of varaibel or error


    Argument definitions:

    • varName : Name of the environment variable to check


    Procedure: compareEnv

    Procedure to compare the value of an environment variable with a specified value. This can be used, for example, to determine if the REMOTE_HOST IP address corresponds to the WebSubmit server.


    Procedure Data

    • Name: compareEnv
    • Parent Namespace: webSubmit::util
    • Arglist: varName envValue
    • Return: 1 = Equal, 0 = Unequal, Error if undefined


    Argument definitions:

    • varName : Environment variable to compare
    • envValue : Value to compare against


    Procedure: writeLog

    Procedure to write a message to a WebSubmit log file. The procedure provides for multiple log files and an arbitrary message. CURRENT STATUS: Unused


    Procedure Data

    • Name: writeLog
    • Parent Namespace: webSubmit::util
    • Arglist: logFile msg
    • Return: Error status


    Argument definitions:

    • logFile : Name of the logfile to be written (Absolute or relative path)
    • msg : UNDEFINED


    Procedure: remLogMsg

    Procedure to build up an access log message. This message is the one printed in the log files when the main WebSubmit page is accessed from a remote location (i.e., a URL outside the WS hierarchy. CURRENT STATUS: Unused


    Procedure Data

    • Name: remLogMsg
    • Parent Namespace: webSubmit::util
    • Arglist:
    • Return: Log message


    Argument definitions:



    Procedure: errLogMsg

    Procedure to build up an error log message. This message is the one printed in the log files when a WebSubmit error occurs. CURRENT STATUS: Unused


    Procedure Data

    • Name: errLogMsg
    • Parent Namespace: webSubmit::util
    • Arglist: status module string
    • Return: Log message


    Argument definitions:

    • status : Error status code
    • module : Module from which error was generated
    • string : Text string to print with error message


    Procedure: jobLogMsg

    Procedure to build up job submission log message. This message is the one printed in the log files when jobs are submitted via WebSubmit. CURRENT STATUS: Unused


    Procedure Data

    • Name: jobLogMsg
    • Parent Namespace: webSubmit::util
    • Arglist: userId target module
    • Return: Log message


    Argument definitions:

    • userId : WebSubmit userId
    • target : Target machine to which job was submitted
    • module : Name of module used to submit job


    Procedure: mkPathAbs

    Procedure to make a relative pathname absolute


    Procedure Data

    • Name: mkPathAbs
    • Parent Namespace: webSubmit::util
    • Arglist: path root
    • Return: Absolute path corresponding to input


    Argument definitions:

    • path : Path to fix
    • root : Root to prepend to path if it is relative


    Procedure: buildString

    Procedure to build a string of repeated characters


    Procedure Data

    • Name: buildString
    • Parent Namespace: webSubmit::util
    • Arglist: len char
    • Return: String of length 'len' containing only 'char'


    Argument definitions:

    • len : Length of string to create
    • char : Character to use in string


    Procedure: header

    Procedure to build a simple text header for output (debugging)


    Procedure Data

    • Name: header
    • Parent Namespace: webSubmit::util
    • Arglist: stringList topchar botchar
    • Return: Header text as string value


    Argument definitions:

    • stringList : String to enclose in header
    • topchar : Character across top of header
    • botchar : Character across bottom of header


    Procedure: padString

    Procedure to pad a string on the left and right with blanks


    Procedure Data

    • Name: padString
    • Parent Namespace: webSubmit::util
    • Arglist: str char totLen
    • Return: The padded string


    Argument definitions:

    • str : String to pad
    • char : Padding character
    • totLen : Length to pad to


    Procedure: initVars

    Procedure to initialize a list of scalars in the *calling scope* to empty strings. If the variable already exists, its value is not changed.


    Procedure Data

    • Name: initVars
    • Parent Namespace: webSubmit::util
    • Arglist: varList
    • Return: None


    Argument definitions:

    • varList : List of variables to initialize


    Procedure: serialize

    Procedure to write a collection of data to a Tcl file. In this fashion, the data structure can be reproduced simply by source-ing the file. In an attempt to preserve list structures, it is assumed that any variable that has a name of the form "*List" is in fact a list. Arrays are written element by element; strings are simply 'set'.


    Procedure Data

    • Name: serialize
    • Parent Namespace: webSubmit::util
    • Arglist: ns varList file
    • Return: None


    Argument definitions:

    • ns : Namespace (absolute) in which variables exist
    • varList : List of variable *names* to serialize
    • file : Name of file to create


    Procedure: loadSerial

    Procedure to source a serialized version of a collection of data.


    Procedure Data

    • Name: loadSerial
    • Parent Namespace: webSubmit::util
    • Arglist: fileName
    • Return: 0 = Success, 1 = Error


    Argument definitions:

    • fileName : Name of the file to source


    Procedure: readOnly

    Procedure to store read-only variable values and to place variable traces on these variables


    Procedure Data

    • Name: readOnly
    • Parent Namespace: webSubmit::util
    • Arglist: varName value {scope ""}
    • Return: None


    Argument definitions:

    • varName : Name of the variable to protect
    • value : Value of variable
    • scope (Optional): Scope in which variable is to be defined (Default = "")


    Procedure: readOnlyArray

    Procedure to store read-only array variable values and to place variable traces on these variables


    Procedure Data

    • Name: readOnlyArray
    • Parent Namespace: webSubmit::util
    • Arglist: arrName index value {scope ""}
    • Return: None


    Argument definitions:

    • arrName : Name of the array variable to protect
    • index : Array index
    • value : Value of variable
    • scope (Optional): Scope in which variable is to be defined (Default = "")


    Procedure: undoChange

    Implements a read-only variable scheme. Any time a variable's value is written or unset, it is reset to its original value as stored in webSubmit::VARSAFE


    Procedure Data

    • Name: undoChange
    • Parent Namespace: webSubmit::util
    • Arglist: varName callName index op
    • Return: None


    Argument definitions:

    • varName : Name of variable
    • callName : Name of variable used in call
    • index : Index if varName is an array name
    • op : Operation occurring on variable (r=read,w=write,u=unset)


    Procedure: undoArrChange

    Implements a read-only array scheme. Any time a variable's value is written or unset, it is reset to its original value as stored in webSubmit::VARSAFE


    Procedure Data

    • Name: undoArrChange
    • Parent Namespace: webSubmit::util
    • Arglist: arrName callName index op
    • Return: None


    Argument definitions:

    • arrName : Name of variable
    • callName : Name of variable used in call
    • index : Index if varName is an array name
    • op : Operation occurring on variable (r=read,w=write,u=unset)


    Procedure: checkChangeScope

    Trace procedure to determine the environment from which a variable change was invoked. If invoked from a valid environment, no action is taken. If invoked from an insecure location (i.e., the global environment), then the trace generates a securityBomb and exits


    Procedure Data

    • Name: checkChangeScope
    • Parent Namespace: webSubmit::util
    • Arglist: varName index op
    • Return: None


    Argument definitions:

    • varName : Name of variable
    • index : Index if varName is an array name
    • op : Operation occurring on variable (r=read,w=write,u=unset)


    Procedure: ascii2hex

    Procedure to convert an ASCII character into a hex representation suitable for a URL. Optional argument is a kludge to handle newline replacements


    Procedure Data

    • Name: ascii2hex
    • Parent Namespace: webSubmit::util
    • Arglist: {char ""}
    • Return: Hex value of character, preceded by '%'


    Argument definitions:

    • char (Optional): Character to convert (Default = "")


    Procedure: tclChmod

    Prcoedure to change file permissions (interface to UNIX chmod)


    Procedure Data

    • Name: tclChmod
    • Parent Namespace: webSubmit::util
    • Arglist: mode fileList
    • Return: Status


    Argument definitions:

    • mode : Mode for file(s)
    • fileList : List of files to change modes


    Procedure: trimWhite

    Procedure to trim white space from a list of variables


    Procedure Data

    • Name: trimWhite
    • Parent Namespace: webSubmit::util
    • Arglist: varList
    • Return: None


    Argument definitions:

    • varList : List of variables from which white space should be trimmed