Command Procedures

This chapter describes the components of command procedures.

1. Control Variables

The following is a list of control variables used in command procedures.

Control Variable Description

&LASTCC

Recent return codes. The following describes command procedures' unique return codes and their meanings.

  • 300: Attempted to modify an unmodifiable control variable.

  • 312: Incorrect GLOBAL command.

  • 332: Invalid data set name.

  • 340: Incorrect operand of the OPENFILE command.

  • 348: Unable to open a data set specified in the OPENFILE command.

  • 352: Data set specified in the GETFILE command is not open.

  • 360: Data set specified in the PUTFILE command is not open.

  • 368: Data set specified in the CLOSFILE command is not open.

  • 372: The PUTFILE command was executed before executing the GETFILE command for the data set opened in update mode.

  • 400: Reached the end of file while executing the GETFILE command.

  • 848: Variable other than the integers in arithmetic expressions are described.

  • 900: No keyword is defined after ampersand(&).

  • 912: The "from" value is larger than the "to" value for the &SUBSTR function.

  • 916: Either the "from" or "to" value of the &SUBSTR function is not an integer, or the CODE operand value of the EXIT command is not an integer.

  • 920: Either the "from" or "to" value of the &SUBSTR function is an integer, or the CODE operand value of the EXIT command is an integer.

  • 932: Either the "from" or "to" value of the &SUBSTR function exceeded the range of the string.

  • 936: Incorrect type for the built-in function.

  • 952: Cannot find a branch specified in the GOTO command.

  • 956: No branch is described in the GOTO command.

  • 972: Used the TERMIN command in a batch job.

  • 999: Failed to call a command procedure.

&MAXCC

Maximum value of the return code.

&SYS#CC

Completion code of a completed job. It is set when an ENDJOBNAME event is raised.

&SYS#EVENT

Name of a raised event. This control value has one of the following values.

  • TIME

  • DATE

  • WEEK

  • INTERVAL

  • READYJOBNAME

  • ENDJOBNAME

  • MESSAGE

  • MSGID

  • SYSTEM

  • USEREVENT

  • DATASET

  • MOUNT

  • SYSOUT

  • ONDEVICE

&SYS#EVTNO

Stores the event that corresponds to the event number specified when an event occurs if multiple values are specified in a single operand in the WAIT command.

&SYS#FMSG

Stores the entire outputted message. Set when a MESSAGE event or MSGID event is raised.

&SYS#JN

Job name of the completed job. Set when an ENDJOBNAME event is raised.

&SYS#MSG

Stores the main text of the outputted message. Set when either a MESSAGE event or an MSGID event is raised.

&SYS#PFX

Stores the identifier of the outputted message. Set when either a MESSAGE event or MSGID event is raised.

&SYSASIS

  • ON: Does not convert lower case letters to upper case letters before executing a command.

  • OFF: Converts lower case letters to upper case letters before executing a command.

&SYSCONLIST

  • ON: Displays a command to the terminal after substituting a symbol parameter.

  • OFF: Does not display a command to the terminal after substituting a symbol parameter.

&SYSDATE

Current date in the mm/dd/yy format.

&SYSDVAL

String in which the user recently entered to the terminal.

&SYSENV

  • BACK: Set when a command procedure is being executed as a part of a batch job.

  • FORE: Set when a command procedure is not being executed as a part of a batch job.

&SYSFLUSH

  • ON: Does not execute succeeding command procedures if an error is raised while executing a command procedure.

  • OFF: Executes succeeding command procedures even if an error is raised while executing a command procedure.

&SYSICMD

Name of a command procedure. Used only when a command procedure is not executed explicitly by using the EXEC command in an implicit execution.

&SYSNEST

  • YES: A command procedure is called by another command procedure.

  • NO: A command procedure is not called by another command procedure.

&SYSPCMD

A recently executed TSO command (excluding parameters). The default value is EXEC.

&SYSPREF

Prefix of the data set name.

&SYSSCAN

Specifies the maximum number of times for scanning (the process of substituting a symbol parameter with a value) to be performed before executing each command procedure command.

&SYSSDATE

Current date in the yy-mm-dd format.

&SYSSTIME

Current time in the hh:mm format.

&SYSSTOP

Maximum number of commands that can be executed in a command procedure.

&SYSSYMLIST

  • ON: Displays the command executed before substituting a symbol parameter.

  • OFF: Does not display the command executed before substituting a symbol parameter.

&SYSTIME

Current time in the hh:mm:ss format.

&SYSTMID

Name of the currently connected terminal.

&SYSUID

TSO session user ID.

2. Built-in Functions

The following is a list of the built-in functions used in command procedures.

Built-in Function Description

&DATATYPE (expr)

Returns NUM if the result of the expression expr is a number, and returns CHAR if it is a string.

&EVAL (expr)

Returns the operation result of the formula expr.

&LENGTH (expr)

Returns the character length of the operation result of the expression expr.

&NRSTR (expr)

Substitutes the symbol parameters of expression expr, but returns the results without a superposition substitution. Does not execute mathematical operations.

&STR (expr)

Substitutes the symbol parameters of expression expr and returns the result of processing built-in functions. Does not execute mathematical operations.

&SUBSTR (from:to,str)

Returns the substring extracted from the "from" position to the "to" position of the string str. Only extracts one character from the "from" position if "to" is omitted.

&SYS#EPRM (eprm)

Returns the value of the virtual parameter eprm. For information about virtual parameter configuration, refer to Chapter 1.

&SYSDSN (d)

Checks the status of the data set "d", and returns "OK" if in a usable status and returns an error message if otherwise.

&SYSINDEX (needle,haystack,start)

Returns the position of the string needle in the string haystack. Finds the needle in the entire haystack if "start" is "0" or omitted. If "start" is a positive number, then finds the needle from the starting character of the haystack. Returns 0 if the needle is not found.

&SYSNSUB (level,expr)

Substitutes the symbol parameter of the expression expr, but substitutes it in the maximum level of times.

3. Operators

Expressions can be used in some command procedures such as the IF command. An expression is a concatenation of operands such as integers, strings, symbol parameters, control variables, or built-in functions using operators.

Operators are categorized into arithmetic operators, comparison operators, and logical operators. The following tables describe each type.

  • Arithmetic Operators

    Arithmetic Operators Description

    +

    Addition

    -

    Subtraction

    *

    Multiplication

    /

    Division

    **

    Exponent (if the right side is negative, then the result of the operation is 0)

    //

    Remainder

  • Comparison Operators

    Comparison Operator Description

    EQ or =

    The left side and the right side are the same.

    NE or ^=

    The left side and the right side are not the same.

    LT or <

    The left side is smaller than the right side.

    GT or >

    The left side is greater than the right side.

    LE or <=

    The left side is less than or equal to the right side.

    GE or >=

    The left side is greater than or equal to the right side.

    NG or ^>

    The left side is not greater than the right side.

    NL or ^<

    The left side is not smaller than the right side.

  • Logical Operators

    Logical Operator Description

    AND or &&

    Logical product

    OR or |

    Logical sum

4. Command Procedure Commands

The following table describes the types of command procedure commands and their functions.

Command Procedure Command Description

ATTN

Sets the interrupt handler. For syntax check only.

CLOSFILE

Closes the data set.

CONTROL

Specifies options related to executing command procedures.

DATA-ENDDATA

Separates the TSO command and the screen output data area.

DO-END

Repeatedly executes one or more command procedure commands.

ERROR

Sets the error handler.

EXIT

Stops the execution of a command procedure and returns control to the parent command procedure.

GETFILE

Reads a record from a data set.

GLOBAL

Declares a symbol parameter shared between nested command procedures.

GOTO

Branches to a specified location.

IF-THEN-ELSE

Executes different actions according to specified conditions.

INDATA

Specifies the data set where the screen output data will be stored. For syntax check only.

OPENFILE

Opens a data set.

PROC

Defines the symbol parameter received from the parent command procedure.

PUTFILE

Writes a record in a data set.

READ

Stores the data received from the user through the terminal in the symbol parameter.

READDVAL

Stores the information of the control variable &SYSDVAL in the specified symbol parameter.

RETURN

Returns control to the command procedure command that is after the command procedure command in which an error is raised.

SET

Stores a value in the symbol parameter or a control variable.

TERMIN

Passes control to the terminal in order to receive user input. For syntax check only.

WRITE/WRITENR

Displays a string on the terminal.

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-attn.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-closfile.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-control.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-data-enddata.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-do-end.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-error.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-exit.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-getfile.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-global.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-goto.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-if.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-indata.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-openfile.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-proc.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-putfile.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-read.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-readdval.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-return.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-set.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-termin.adoc[]

Unresolved include directive in modules/tso-guide/pages/chapter-command-procedure.adoc - include::command-procedure/sect-cmd-proc-write.adoc[]