z/OS Jobs

The following topics describe job attributes for z/OS mainframe operating system jobs:

Job:zOS:Member

The following example shows how to define a Job:zOS:Member job:

Copy 
"ZF_DOCS" : 
{
   "Type" : "Folder",
   "ControlmServer" : "M2MTROLM",
   "FolderLibrary" : "IOAA.CCIDM2.CTM.OPR.SCHEDULE",
   "RunAs" : "emuser",
   "CreatedBy" : "emuser",
   "When" : 
   {
      "RuleBasedCalendars" : 
      {
         "Included" : [ "EVERYDAY" ],
         "EVERYDAY" : 
         {
            "Type" : "Calendar:RuleBased",
            "When" : 
            {
               "DaysRelation" : "OR",
               "WeekDays" : [ "NONE" ],
               "MonthDays" : [ "ALL" ]
            }
         }
      }
   },
   "ZJ_DATA" : 
   {
      "Type" : "Job:zOS:Member",
      "SystemAffinity" : "ABCD",
      "SchedulingEnvironment" : "PLEX8ALL",
      "ControlDCategory" : "SEQL_FILE",
      "PreventNCT2" : "Yes",
      "MemberLibrary" : "IOA.WORK.JCL",
      "SAC" : "Prev",
      "CreatedBy" : "emuser",
      "RequestNJENode" : "NODE3",
      "RunAs" : "emuser",
      "StatisticsCalendar": "CALPERIO",
      "TaskInformation" : 
      {
         "EmergencyJob" : true,
         "RunAsStartedTask" : true,
      },
      "OutputHandling" : 
      {
         "Operation" : "Copy"
         "FromClass" : "X",
         "Destination" : "NODE3",
      },
      "History" : 
      {
         "RetentionDays": "05",
         "RetentionGenerations" : "07"
      },
      "Archiving" : 
      {
         "JobRunsToRetainData" : "4",
         "DaysToRetainData" : "1",
         "ArchiveSysData" : true
      },
      "Scheduling" : 
      {
         "MinimumNumberOfTracks" : "5",
         "PartitionDataSet" : "fgf"
      },
      "RerunLimit" : 
      {
         "RerunMember" : "JOBRETRY",
         "Units" : "Minutes",
         "Every" : "7"
      },
      "MustEnd" : 
      {
         "Minutes" : "16",
         "Hours" : "17",
         "Days" : "0"
      },
      "When" : 
      {
         "WeekDays" : [ "NONE" ],
         "Months" : [ "NONE" ],
         "MonthDays" : [ "NONE" ],
         "DaysRelation" : "OR"
      },
      "CRS" : 
      {
         "Type" : "Resource:Lock",
         "IfFail" : "Keep",
         "LockType" : "Shared"
      },
      "QRS" : 
      {
         "Type" : "Resource:Pool",
         "IfFail" : "Keep",
         "IfOk" : "Discard",
          "Quantity" : "1"
      },
      "Demo" : 
      {
          "Type" : "StepRange",
          "FromProgram" : "STEP1",
          "FromProcedure" : "SMPIOA",
          "ToProgram" : "STEP8",
          "ToProcedure" : "CTBTROLB"
      },
      "IfCollection:zOS_0" : 
      {
          "Type" : "IfCollection:zOS",
          "Ifs" : [ 
          {
             "Type" : "If:zOS:AnyProgramStep",
             "ReturnCodes" : [ "OK" ],
             "Procedure" : "SMPIOA"
          }, 
          "OR", 
          {
             "Type" : "If:zOS:EveryProgramStep",
             "ReturnCodes" : [ "*$EJ", ">S002" ],
             "Procedure" : "SMPIOA"
          } ],
         "CtbRuleData_2" : 
          {
             "Type" : "Action:ControlMAnalyzerRule",
             "Name" : "RULEDEMO",
             "Arg" : "3"
          }
      },
      "IfCollection:zOS_1" : 
      {
         "Type" : "IfCollection:zOS",
         "Ifs" : [ 
         {
            "Type" : "If:zOS:SpecificProgramStep",
            "Program" : "Demo",
            "ReturnCodes" : [ "*****" ],
            "Procedure" : "SMPIOA"
         }, 
         "OR", 
         {
            "Type" : "If:zOS:SpecificProgramStep",
            "Program" : "STEP5",
            "ReturnCodes" : [ ">U0002" ],
            "Procedure" : "SMPIOA"
          } ],
         "IfRerun_2" : 
         {
            "Type" : "Action:Restart",
            "FromProgram" : "STEP1",
            "FromProcedure" : "SMPIOA",
            "ToProgram" : "STEP5",
            "ToProcedure" : "CTBTROLB"
            "Confirm" : false,           
         }
      }
   }
}

The following table describes the Job:zOS:Member job parameters.

Parameter

Description

FolderLibrary

Defines the location of the Member that contains the job folder.

Rules:

  • Characters: 1–44

  • Built of Qualifiers: 1–8 characters, separated by ., must have at least one character, and cannot begin with a digit character.

  • Invalid Characters: Non-English characters, and begins with ..

  • Valid Characters: A–Z, 0–9, @, #, $.

SystemAffinity

Defines the identity of the system in which the job must be initiated and executed (in JES2).

Rules:

  • Alphanumeric Characters: 1–5

  • Invalid Characters: Non-English characters.

You must type /, followed by the remaining 1–4 characters to define a non-JES3 system.

SchedulingEnvironment

Defines the JES2 workload management scheduling environment that is to be associated with the job.

Rules:

  • Characters: 1–16

  • Case Sensitive: Yes

  • Invalid Characters: Non-English characters, blanks.

ControlDCategory

Defines the name of the Control-D Report Decollating Mission Category. If specified, the report-decollating mission is scheduled whenever the job is scheduled under Control-M.

Rules:

  • Characters: 1–20

  • Invalid Characters: Blanks.

PreventNCT2

Determines whether to perform data set cleanup before the original job runs.

Valid Values:

  • yes

  • no

MemberLibrary

Defines the location of the Member that contains the JCL, started task procedure, or warning message.

Rules:

  • Characters: 1–44

  • Built of Qualifiers: 1–8 characters, separated by ., must have at least one character minimum, and cannot begin with a digit character.

  • Invalid Characters: Non-English characters.

  • Valid Characters: A–Z, 0–9, @, #, $.

SAC

(Optional) Determines whether to adjust the logical date for a job converted from a scheduling product other than Control-M.

Valid Values:

  • Blank: No adjustment is made. The SMART folder and its jobs are scheduled according to the regular criteria. This is the default.

  • Prev

    • SMART folder: The SMART folder is scheduled on the day indicated by the regular scheduling criteria and the preceding day.

    • Job: The job is scheduled on the day that precedes the day indicated by the regular scheduling criteria.

  • Next

    • SMART folder: The SMART folder is scheduled on the day indicated by the regular scheduling criteria and the following day.

    • Job: The job is scheduled on the day that follows the day indicated by the regular scheduling criteria.

RequestNJENode

Defines the node in the JES network where the job executes.

Rules:

  • Characters: 1–8

  • Invalid Characters: ', $, /, *, ?, and blank spaces.

StatisticsCalendar

(Optional) Defines the Control-M periodic calendar used to collect statistics relating to the job. This provides more precise statistical information about the job execution. If the StatisticsCalendar parameter is not defined, the statistics are based on all run times of the job.

Rules:

  • Alphanumeric Characters: 1–8

  • Case Sensitive: Yes

  • Invalid Characters: Blanks and non-English characters

TaskInformation

Defines additional optional settings for the job.

EmergencyJob

Determines whether to run the job as an emergency job.

Valid Values:

  • true

  • false

RunAsStartedTask

Determines whether to run the job as a started task.

Valid Values:

  • true

  • false

OutputHandling

Defines how the job output is handled.

Operation

Determines the output handling action.

Valid Values:

  • None: Default.

  • Delete: Deletes the output.

  • Copy: Copies the output to a selected filename.

  • Move: Moves the output to a new selected path.

  • ChangeJobClass: Changes the class of the job output.

FromClass

Defines the previous class name.

Destination

Defines the output name and full pathname to move the output.

Do not use an internal Control-M directory or subdirectory.

Mandatory if the value for Operation is Copy, Move, or ChangeJobClass.

An * indicates the original MSGCLASS for the job output.

History

(Optional) Determines how long to retain the job in the History Jobs file.

Retention Days and Retention Generations are mutually exclusive. A value can be specified for either, but not both.

RetentionDays

Determines the number of days, in DDD format, such as 002.

Valid Values: 001–999

RetentionGenerations

Determines the number of generations, in ### format, such as 051.

Valid Values: 000–999

Archiving

Determines how long Control-M Workload Archiving retains the job output.

JobRunsToRetainData

Determines the number of times the job run data is retained in the job output.

DaysToRetainData

Determines the number of days the job run data is retained in the job output.

ArchiveSysData

Determines whether to archive the job SYSDATA.

Valid Values:

  • true

  • false

Scheduling

Defines the scheduling parameters when or how often the job is scheduled for submission.

MinimumNumberOfTracks

Determines the minimum number of free partitioned data set tracks required by the library specified for the PartitionDataSet parameter.

PartitionDataSet

Defines the name of a partitioned data set to check for free space. If PartitionDataSet has fewer than the minimum number of required free tracks specified in the MinimumNumberOfTracks parameter, the job executes.

RerunLimit

Determines the maximum number of reruns that can be performed for the job. 

When a z/OS job reruns, the job status is set to Not OK, even if it was previously specified as OK.

RerunMember

Defines the name of the JCL member to use when the job automatically reruns. 

Rules:

  • Characters: 1–8

  • Case Sensitive: Yes

  • Invalid Characters: Blanks and non-English characters.

Units

Determines the unit of measurement to wait between reruns.

Valid Values:

  • Seconds

  • Minutes

  • Hours

Every

Determines the number of Units to wait between reruns.

MustEnd

Determines the time of day and days offset when the folder must finish executing.

Hours

Determines the hour of the day, in HH format, such as 20.

Valid Values: 00–23

Minutes

Determines the minute of the hour of the day, in MM format, such as 18.

Format: MM

Valid Values: 00–59

Days

Determines the number of days, in DDD format, such as 002.

Format: DDD

Valid Values: 000–120

LockType

Determines whether a lock resource is shared or exclusive. For more information, see Resources.

IfFail

Determines what happens to the lock or pool resource if the job fails to use the resource. For more information, see Resources.

Valid Values:

  • Release

  • Keep

IfOk

Determines what happens to a pool resource if the job successfully uses the resource. For more information, see Resources.

Valid Values:

  • Discard

  • Release

Quantity

Determines the number of lock or pool resources to allocate to the job. For more information, see Resources.

StepRange

Determines the job steps to execute during restart of a job.

Parameters:

  • FromProgram: First program step within the job stream.

  • FromProcedure: First procedure step in the range.

  • ToProgram: Last program step within the job stream.

  • ToProcedure: Last procedure step in the range.

Rules:

  • Characters: 1–8

  • Invalid Characters: Blanks and non-English characters.

IfCollection:zOS - Ifs

Defines the following unique If objects that apply to a z/OS job:

  • If:zOS:AnyProgramStep:  Indicates that the Do Statements must be performed if the specified codes are found in any program step.

    • Procedure: Defines the name of the procedure step.

    • ReturnCodes: Assigns a completion code for the entire job that are based on the steps completion codes. Enter more than one ReturnCode in an array separated by commas.

      [ "<value1", "value2" ]

      Valid Completion Codes:

      • *****: Job ended.

      • OK: Job ended OK. 

      • NOTOK: Job ended not OK. 

      • Cnnnn: Condition return code, which might be preceded by any of the following characters: <, >, =, ! .

      • Sxxx: System abend code, which might be preceded by any of the following characters: <, >, =, !.

      • Unnnn: User abend code, which might be preceded by any of the following characters: <, >, =, !.

      • $EJ: Job queued for execution.

      • *NCT2: File allocation problem. 

      • *REC0: Maximum reruns number reached. 

      • *TERM: Job terminated by CMEM.

      • *UNKW: Unknown error occurred.

      • FLUSH: Step not executed.

      • FORCE: Job was forced OK.

      • JFAIL: Job failed due to JCL error.

      • JNSUB: Job not submitted.

      • JSECU: Job failed due to security requirements.

      • JLOST: Job output was lost.

      • JNRUN: Job was canceled during execution.

  • If:zOS:EveryProgramStep: Indicates that the Do Statements must be performed if the specified codes are found in any program step.

  • If:zOS:NumberOfFailures: Determines whether the accompanying DO statements are performed if the job's number of failures is satisfied.

    • NumberOfFailures: Determines the number of times a job can fail before an action is taken.

  • If:zOS:SpecificRangeName: Specifies a range of steps in the steps of an PGMST statement.

    • Program: Defines the name of a specific program step.

  • If:zOS:SpecificProgramStep: Name of a specific program step. If a specific program step is specified, only program steps from the invoked program are checked to see if they satisfy the code criteria. Program steps directly from the job are not checked.

    • Program: Defines the name of a specific program step.

  • If:zOS:JOBRCCodes: Assigns a completion code for the entire job based on the completion codes of its steps.

  • If:zOS:OutputPattern: Indicates that the DO statements must be performed if the specified pattern is found in the output.

    • OutputPattern: Defines a string in the output, in 1–40 characters.

    • FromColumn: Defines the first column to look for the patter, in three-digit numbers.

    • ToColumn: Defines the last column to look for the pattern, in three-digit numbers.

IfCollection:zOS - Actions

Defines the following unique Action objects that apply to a z/OS job:

  • Action:Restart: An object that determines whether to automatically restart the job if it fails, the step to start from, and the step to end at.

    • Confirm: Determines whether the job restarts automatically.

      Valid Values:

      • true

      • false

      Default: false

  • Action:ControlMAnalyzerRule: An object that defines the Control-M/Analyzer rule that Control-M executes.

    • Name: (Mandatory) Defines the name of the Control-M/Analyzer rule or mission.

    • Arg: (Optional) Defines the arguments to be passed to the Control-M/Analyzer step.

Job:zOS:InStreamJCL

The following example shows how to define a Job:zOS:InStreamJCL job:

Copy 
"ZF_ROBOT" : 
{
   "Type" : "SimpleFolder",
   "ControlmServer" : "R2MTROLM",
   "FolderLibrary" : "CTMP.V900.SCHEDULE",
   "OrderMethod" : "Manual",
   "Z_R1" : 
   {
      "Type" : "Job:zOS:InStreamJCL", 
      "JCL" : "//ROASMCL JOB ,ASM,CLASS=A,REGION=0M\\n//JCLLIB ORDER=IOAP.V900.PROCLIB\\n//INCLUDE MEMBER=IOASET\\n//S1 EXEC IOATEST,PARM='TERM=C0000'\\n//S2 EXEC IOATEST,PARM='TERM=C0000'",
      "CreatedBy" : "emuser",
      "RunAs" : "emuser",
      "When" : 
      {
         "WeekDays" : [ "NONE" ],
         "MonthDays" : [ "ALL" ],
         "DaysRelation" : "OR"
      },
      "Archiving" : 
      {
         "ArchiveSysData" : true
      }
   }
}

For descriptions of parameters, see the list of parameters available for Job:zOS:Member (except for MemberLibrary, which is not relevant here).

The following additional parameter is required for a Job:zOS:InStreamJCL job.

Parameter

Description

JCL

Defines a script as it would be specified in a terminal for the specific computer and is part of the job definition. Each line begins with // and ends with \\n.