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;

Throughout this documentation, the term "task" refers to a scheduled task defined in the scheduler, to avoid confusion with JCL jobs.

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)
ADDEP
  PREOPNO(2)
  PREWSID(CPU1)
ADOP
  OPNO(4)
  JOBN(REPORT_WARN)
  WSID(CPU1)
ADDEP
  PREOPNO(2)
  PREWSID(CPU1)
ADCNC
  CONDID(1)
  COUNT(1)
ADCNS
  CONDID(1)
  PREOPNO(2)
  CHECK(RC)
  LOGIC(EQ)
  RC1(0004)

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

tws-iws.png

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/tasks 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)

PREJOBN / PREOPNO / ADDEP

Dependencies created from predecessor declarations (PREJOBN, PREOPNO in ADOP, or ADDEP blocks) that have no associated ADCNS condition entries are classified as UNCONDITIONAL.

PREJOBN states the predecessor task 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 states the predecessor operation number. It is resolved to a task 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).

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) states the predecessor operation number. It is resolved to a task name using the OPNO-to-JOBN mapping.

PREOPNO (in ADDEP) states the predecessor operation number. It is resolved to a task name using the OPNO-to-JOBN mapping.

PREJOBN (in ADDEP) states the predecessor task name directly.

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.

In the main example above, REPORT declares ADDEP PREOPNO(2) with no ADCNS block. This creates an unconditional "Exec Next Scheduled Task" edge from COMPUTE to REPORT.

The JSON output for an unconditional dependency includes the property schedulerDependencyType set to "UNCONDITIONAL".

{
    "dependencyType": "Exec Next Scheduled Task",
    "name": "PAYROLL-REPORT-payroll.tws",
    "path": "Global:SCHEDULED_TASK:PAYROLL-REPORT-payroll.tws",
    "properties": {
        "schedulerDependencyType": "UNCONDITIONAL"
    },
    "type": "SCHEDULED_TASK"
}

Missing predecessor

When a PREJOBN or PREOPNO references a task that is not found in any job stream, a missing dependency is created with the property schedulerDependencyType set to "UNCONDITIONAL".

ADCNC / ADCNS

TWS supports conditional predecessor dependencies through the ADCNS (condition sub-entry) statement, which allows operations to depend on a predecessor only when a specific return code or status condition is met.

ADCNC groups one or more ADCNS condition sub-entries for the current operation. It does not create a dependency edge by itself.

ADCNC
  CONDID(1)
  COUNT(1)

CONDID states the condition identifier that links ADCNC to its ADCNS sub-entries.

COUNT states the number of ADCNS sub-entries in this condition container.

ADCNS defines the actual condition for a predecessor dependency. It references the predecessor operation and specifies the runtime condition to evaluate.

ADCNS
  CONDID(1)
  PREOPNO(2)
  CHECK(RC)
  LOGIC(EQ)
  RC1(0004)

CONDID states the condition identifier, linking this sub-entry to its parent ADCNC container.

PREOPNO states the predecessor operation number. It is resolved to a task name using the OPNO-to-JOBN mapping within the current job stream.

CHECK states the type of condition to evaluate. Two values are supported:

  • RC: return code check. The comparison value is specified in the RC1 attribute
  • ST: status check. The comparison value is specified in the STATUS attribute.

LOGIC states the comparison operator. The following operators are supported:

  • EQ: equal to
  • NE: not equal to
  • GT: greater than
  • GE: greater than or equal to
  • LT: less than
  • LE: less than or equal to
  • RG: range

RC1 states the return code value to compare against when CHECK(RC) is used. For example: RC1(0004).

STATUS states the job status value to compare against when CHECK(ST) is used. For example: STATUS(E) for ended.

In the main example above, REPORT_WARN declares ADDEP PREOPNO(2) followed by an ADCNC/ADCNS block with CHECK(RC) LOGIC(EQ) RC1(0004). This creates a conditional "Exec Next Scheduled Task" edge from COMPUTE to REPORT_WARN, meaning REPORT_WARN only executes when COMPUTE ends with return code 0004.

The JSON output for a conditional dependency includes the properties schedulerDependencyType set to "CONDITIONAL" and schedulerDependencyDescription describing the condition.

{
    "dependencyType": "Exec Next Scheduled Task",
    "name": "PAYROLL-REPORT_WARN-payroll.tws",
    "path": "Global:SCHEDULED_TASK:PAYROLL-REPORT_WARN-payroll.tws",
    "properties": {
        "schedulerDependencyType": "CONDITIONAL",
        "schedulerDependencyDescription": "ADCNS:RC:EQ:0004"
    },
    "type": "SCHEDULED_TASK"
}

Multiple conditions

When multiple ADCNS sub-entries apply to the same predecessor, their descriptions are joined with semicolons.

Missing conditional dependencies

When an ADCNS references a predecessor operation that is not found in the current job stream, the condition is skipped.

Attributes

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.

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.

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.