AWS Transform for mainframe refactor

TWS/IWS - IBM Tivoli Workload Scheduler

IBM Tivoli Workload Scheduler (TWS), also known as IBM Workload Automation (IWA), is an enterprise job scheduling platform that automates the scheduling, monitoring, and management of batch processing workflows on IBM z/OS mainframe systems. TWS files use a batch loader format with keyword-based statements such as ADDEF, ADSTART, ADOP, ADDEP, and JOBREC.

The extracted TWS scheduler follows a batch loader text format with a structured layout as the following example.

ADDEF
  ADID(PAYROLL)
  GROUP(FINANCE)
ADOP
  OPNO(1)
  JOBN(EXTRACT)
  WSID(CPU1)
ADOP
  OPNO(2)
  JOBN(COMPUTE)
  WSID(CPU1)
  PREJOBN(EXTRACT)
ADOP
  OPNO(3)
  JOBN(REPORT)
  WSID(CPU1)
  PREJOBN(COMPUTE)

Based on the example above, job dependencies are as follows:

Job stream definition

ADDEF (short form) or ADSTART (full form) defines a job stream header. A job stream is an organizational structure that groups related operations together.

ADID

Attribute ADID states the unique identifier of the job stream. All subsequent ADOP and ADDEP statements belong to this job stream until the next ADDEF or ADSTART is encountered.

ADDEF
  ADID(PAYROLL)
  GROUP(FINANCE)

A single TWS file can contain multiple job streams.

Operation definition

ADOP defines an operation (a scheduled task) within the current job stream. Each operation represents a unit of work to be executed. On z/OS computer workstations, the JOBN value implicitly identifies the JCL member to be submitted.

ADOP
  OPNO(2)
  JOBN(COMPUTE)
  WSID(CPU1)
  PREJOBN(EXTRACT)

JOBN

Attribute JOBN states the job name of the operation. On z/OS, this is also the JCL member name that the scheduler submits. To make it unique throughout the dependency analysis, the scheduled task name is a combination of the job stream name (ADID), the job name (JOBN), and the scheduler file name.  
For example, assuming the TWS scheduler file name is: payroll.tws and the content is shown above, then the first scheduled task name is: PAYROLL-EXTRACT-payroll.tws.

OPNO

Attribute OPNO states the operation number within the job stream (range 1 to 255). Each operation within a job stream must have a unique number. Operation numbers are used for predecessor resolution via PREOPNO.

WSID

Attribute WSID states the workstation identifier where the operation runs. Sentinel operations with WSID(ON) or WSID(OFF) mark the start and end of a job stream and are excluded from JCL linking.

PREJOBN

Attribute PREJOBN states the predecessor job name. It builds a link between the predecessor operation and the current operation. When the predecessor exists in the file, an "Exec Next Scheduled Task" edge is created from the predecessor to the current operation. When the predecessor is not found, a "Missing Scheduled Task" edge is created.

ADOP
  OPNO(2)
  JOBN(COMPUTE)
  WSID(CPU1)
  PREJOBN(EXTRACT)

In the example above, operation EXTRACT triggers operation COMPUTE.

PREOPNO

Attribute PREOPNO states the predecessor operation number. It is resolved to a job name within the current job stream.

ADOP
  OPNO(010)
  JOBN(STEP1)
  WSID(CPU1)
ADOP
  OPNO(020)
  JOBN(STEP2)
  WSID(CPU1)
  PREOPNO(010)

In the example above, STEP2 depends on STEP1 because PREOPNO(010) resolves to JOBN(STEP1).

For every ADOP operation on a non-sentinel workstation (WSID is not ON or OFF), the JOBN value creates an implicit Exec JCL dependency edge. This reflects the z/OS behavior where the scheduler submits the JCL member matching the job name.

Dependency declaration

ADDEP declares a predecessor dependency for the most recently defined operation (the last ADOP). It is used in the full-form batch loader format as a separate block after ADOP.

ADOP
  OPNO(010)
  JOBN(JOBSTEP1)
  WSID(CPU1)
ADDEP
  PREOPNO(001)
  PREWSID(ON)

PREOPNO (in ADDEP)

Attribute PREOPNO states the predecessor operation number. It is resolved to a job name using the OPNO-to-JOBN mapping.

PREJOBN (in ADDEP)

Attribute PREJOBN states the predecessor job name directly.

PREADID

Attribute PREADID states the job stream of the predecessor, enabling cross-stream dependency declarations. When absent, the current job stream is assumed.

ADDEP
  PREJOBN(STEP_A1)
  PREADID(STREAM_A)
  PREWSID(CPU1)

In the example above, the current operation depends on STEP_A1 from job stream STREAM_A.

End-to-end agent jobs

JOBREC defines an end-to-end agent job record, used for operations running on distributed (non-z/OS) workstations. SCRIPTNAME, DOCOMMAND, and JOBCMD are valid only within JOBREC blocks, not in ADOP.

//JOBREC
  JOBCMD(MYPGM)
  SCRIPTNAME(MYSCRIPT)

JOBCMD

Attribute JOBCMD specifies the job command type and implies a link from the current operation to a program. It creates an "Exec Program" dependency edge.

DOCOMMAND

Attribute DOCOMMAND specifies the command or program to execute on a distributed agent. It creates an "Exec Program" dependency edge.

SCRIPTNAME

Attribute SCRIPTNAME specifies the script file to execute on a distributed agent. It creates an "Exec JCL" dependency edge.

Cross-stream dependencies

Predecessor references are resolved across all job streams in the file. If PREJOBN references a job name defined in a different job stream, the dependency is correctly linked.

ADDEF
  ADID(BATCH1)
ADOP
  OPNO(1)
  JOBN(LOAD)
  WSID(CPU1)
ADDEF
  ADID(BATCH2)
ADOP
  OPNO(1)
  JOBN(VALIDATE)
  WSID(CPU2)
  PREJOBN(LOAD)

In the example above, LOAD (from BATCH1) triggers VALIDATE (from BATCH2) as a cross-stream "Exec Next Scheduled Task" edge.