Defining a Command with an Automation Workstation

The TWS application description panels allow the TWS user to specify a free-format SA z/OS or NetView command (of up to 255 characters) that is passed to SA z/OS for execution.

The command must be pipeable.

The workstation destination can optionally be defined. It is the NetView domain where the command should be executed.

This then leads to a panel similar to Figure 1.

Figure 1. TWS Operations Interface Panel to Define Commands
 ---------------- MODIFYING AUTOMATION INFO IN THE APPLICATION -----------------

 Application            :
 Input Arrival          :
 Operation              :
 Jobname                :

 Enter/change text below:

 Command Text:
                                                                  
                                                                  
                                                                  
                                                                 

 Automated Function:                 Security Element:
                                               

 Completion Info:
Use this panel to enter the following:
Command Text
The complete free-format command. This can also contain TWS variables: Before the operation is passed to SA z/OS, TWS performs variable substitution processing.
Note: MVS commands must be issued within a NetView PIPE command to ensure that the command output is correlated.
Automated Function
The name of the automated function (optional). If specified, it causes the specified command to be executed on the NetView task that is assigned to the automated operator. This allows an installation to serialize the execution of commands—they are executed sequentially in the order they arrive in SA z/OS. If omitted, the command is processed by one of the tasks that is designated for handling the command received via the TWS request interface.
Security Element
This name is passed to the AOFEXC20 exit so that the installation can perform any security-related checking.
Completion Info
This includes:

  • The maximum wait time in NetView notation (mm, :ss, mm:ss, hh:mm:ss). If specified, it causes SA z/OS to wait for the completion of the command for the specified time interval. If the command does not complete within the specified time interval, SA z/OS posts the operation in error.

    You can also prefix the maximum wait time with the letter 'I' (for example, I00:00:10). If prefixed with the letter 'I', the result checking is invoked immediately after the command finished if the command processing has not reached the maximum wait time.

    For an INGREQ or INGMOVE command, the following applies:
    • The command is considered to be complete when the specified resource has reached or is already in the requested state.
    • If more than one resource is specified in the INGREQ or INGMOVE command, all resources must be in the requested state before the command is considered complete.
    • The timer value that is specified should be large enough to accommodate the longest interval of time that the requested function may take under normal operating conditions.
    • If the wait time is omitted, the installation default value is used. This default is set using the AOF_AAO_TWS_MAX_WAIT_TIME advanced automation option. If neither of these values is set, the SA z/OS default of 5 minutes is used.
  • The maximum return code that is acceptable. The default is 0.
  • The name of the user-supplied completion checking routine (optional). If specified, the completion checking routine is responsible for ensuring that the command achieved the expected results before posting the operation as complete. This allows a TWS user to perform commands that are independent of an SA z/OS-controlled resource, for example the activation of the VTAM® major node.
For example, 05,4,MYRTN sets a maximum wait time of 5 minutes, a maximum tolerated return code of 4 and the completion checking routine is MYRTN. The parameters must be separated by a comma.