Job stream definition

A job stream consists of a sequence of jobs to be run, together with times, priorities, and other dependencies that determine the order of processing. You can define job streams related to the same line of business in a specified folder. You can also use the composer rename command to rename and move job streams in batch mode that use a naming convention to specified folders where the folder names are taken from the job stream name.

A job stream begins with a schedule keyword followed by attributes and dependencies. The colon delimiter introduces the jobs invoked by the job stream. Each job has its own attributes and dependencies.

Syntax

schedule [[folder/]workstation#][folder/]jobstreamname
    # comment
    [validfrom date]
    [timezone|tz tzname]
    [description ”text”]
    [draft]
      [isservice
       servicename service_name
       servicedescription service_description
       servicetags "|service_tag|service_tag|"
       servicevariables "{var: \"value\"}"]
    [vartable [folder/]table_name]
    [freedays [folder/]calendarname [-sa] [-su]]
    [on [runcycle name
       [validfrom date] [validto date]
       [description ”text”]
       [vartable [folder/]table_name]]
      {date|day|[folder/]calendar|request|”icalendar”[folder/]|runcyclegroup} [,...]
       [fdignore|fdnext|fdprev]
       [({at time [+n day[s]] |
       schedtime time [+n day[s]]}
       [until | jsuntil time [+n day[s]] [onuntil action]]
       [every rate {everyendtime time[+n day[s]]}
       [deadline time [+n day[s]]])]]
    [,...]]

    [except [runcycle name]
          [validfrom date] [validto date]
          [description ”text”]
          {date|day|[folder/]calendar|request|”icalendar”[folder/]|runcyclegroup} [,...]
          [fdignore|fdnext|fdprev]  
          [{(at time [+n day[s]])] |
          (schedtime time [+n day[s]])}]
    [,...]
    [startcond filecreated | filemodified [folder/]workstation_name#file_name
          user username
          interval seconds
          [(alias startcond_jobname
          rerun batch outfile outputfilename
          params "filemonitor additional parameters")] |
   startcond job [folder/]workstation_name#[folder/]job_name
          outcond joboutputcondition
          interval seconds
          [(alias startcond_jobname rerun)]]  
    [{at time [timezone|tz tzname] [+n day[s]] |
    schedtime time [timezone|tz tzname] [+n day[s]]}]
    [until | jsuntil time [timezone|tz tzname] [+n day[s]] [onuntil action]]
    [deadline time [timezone|tz tzname] [+n day[s]]]
    [carryforward]
    [matching {previous|sameday|relative from [+ | -] time to [+ | -] time|
      from time [+ | -n day[s]] to time [+ n day[s]] [,...]}]
    [follows {[netagent::][workstation#]jobstreamname[.jobname |
      @] [previous|
      sameday|relative from [+|-] time to [+|-] time|
      from time [+|-n day[s]] to time [+|-n day[s]]
    ][if <condition> [| <condition>...]]
       } ] [,...]] [...]
   [join condition_name [number | numconditions | all] of  
      description "..."]
      .....
      endjoin

         [keysched]
    [limit joblimit]
    [needs { [n] [[folder/]workstation#][folder/]resourcename } [,...] ] [...]
    [opens { [[folder/]workstation#]"filename" [ (qualifier) ] [,...] }]  [...]
    [priority number | hi | go]
    [prompt {[folder/]promptname|"[:|!]text"} [,...] ] [...]
    [onoverlap {parallel|enqueue|donotstart}]
   :
job-statement
    # comment
job_name [job_alias]
[outcond joboutputcondition interval seconds]
    [{at time [timezone|tz tzname] [+n day[s]] |
    schedtime time [timezone|tz tzname] [+n day[s]]}][,...]
    [until time [timezone|tz tzname] [+n day[s]] [onuntil action]
    [deadline time [timezone|tz tzname] [+n day[s]] [onlate action] ]
    [maxdur time | percentage % onmaxdur action]
    [mindur time | percentage % onmindur action]
    [every rate]
    [follows {[netagent::][workstation#]jobstreamname{.jobname @} [previous|
      sameday|relative from [+|-] time to [+|-] time |
      from time [+|-n day[s]] to time [+|-n day[s]]
       ]} ][if <condition> [| <condition>...]] [,...]] [...]
    [join condition_name [number | numconditions | all] of  
      description "..."]
       .....
      endjoin

         [confirmed]
    [critical]
    [keyjob]
    [needs { [n] [[folder/]workstation#][folder/]resourcename } [,...] ] [...]
    [opens { [[folder/]workstation#]"filename" [ (qualifier) ] [,...] }]  [...]
    [priority number | hi | go]
    [prompt {[folder/]promptname|"[:|!]text"} [,...] ] [...]
    [nop]
    [statistictype custom]
  
[job-statement...]
end

Arguments

List of scheduling keywords contains a brief description of the job stream definition keywords. A detailed description of each scheduling keyword is provided in the next subsections.

Table 1. List of scheduling keywords
Keyword Description Page
at Defines the earliest time a job stream or a job run can be launched. When defined in a run cycle specifies the earliest time a job or a job stream can be launched for that specific run cycle. at
carryforward Carries the job stream forward if it is not completed. carryforward
comment Includes comments in the definition of a job stream or in a job contained in the job stream. comment
confirmed Specifies that the completion of this job requires confirmation. confirmed
critical Specifies that the job is mission critical and must therefore be managed preferentially. critical
deadline Specifies the time within which a job or job stream should complete. When defined in a run cycle specifies the time within which a job or a job stream must complete in that specific run cycle. deadline
description Contains a description of the job stream. The maximum length of this field is 120 characters. description
draft Specifies that the plan generation process must ignore this job stream. draft
end Marks the end of a job stream. end
every Launches a job stream or a job repeatedly at a specified rate. every
except Specifies dates that are exceptions to the on dates the job stream is selected to run. It can be followed by a run cycle definition. except
fdignore | fdnext | fdprev Specifies a rule that must be applied when the date selected for exclusion falls on a non-working day. except
folder|fol Specifies the folder where the scheduling object is stored. If you generally work from a precise folder, then you can use the chfolder command to navigate to folders and sub-folders. The chfolder command changes the working directory or current folder, which is set to root ("/") by default, so that you can use relative folder paths when submitting commands. If no folder path is specified, then the object definition is created in the current folder and not in the root. If a relative path is specified, the path is relative to the current folder. See chfolder for more information about changing folder paths. folder
follows Specifies jobs or job streams that must complete successfully or must satisfy one or more output conditions before the job or the job stream that is being defined is launched. follows
freedays Specifies a freeday calendar for calculating workdays for the job stream. It can also set Saturdays and Sundays as workdays. freedays
interval How often HCL Workload Automation checks whether the condition is met. startcond
job statement Defines a job and its dependencies. job statement
isservice Specifies that a job stream can be submitted as a service toSelf-Service Catalog. When creating and editing SSC-ready job streams, it is recommended you use the Dynamic Workload Console. isservice
join Defines a set of conditional dependencies on a job or job stream. join
jsuntil Specifies that the job stream continues running also if one of its jobs starts running right before the time specified in the jsuntil keyword. This keyword is enabled by default starting from version 9.4, Fix Pack 1. It is mutually exclusive with the until keyword. For more information about the until keyword, see until. jsuntil
keyjob Marks a job as key in both the database and in the plan . keyjob
keysched Marks a job stream as key in both the database and in the plan for monitoring by applications, such as IBM® Tivoli® Business Systems Manager or IBM® Tivoli Enterprise Console®. keysched
limit Sets a limit on the number of jobs that can be launched concurrently from the job stream. limit
matching Defines the matching criteria used when a matching criteria is not specified in the follows specifications in the job stream definition or in the job definition within the job stream. matching
maxdur Specifies the maximum length of time a job can run. You can express this time in either minutes, or as a percentage of the latest estimated duration for the job. maxdur
mindur Specifies the shortest amount of time within which a job normally runs and completes. mindur
needs Defines the number of units of a resource required by the job or job stream before it can be launched. The highest number of resources the job stream can be dependent from is 1024. needs
nop Specifies that a job is not to be run when the plan executes. The job is included in the plan but, as the plan runs, it is placed in Cancel Pending status and is not executed. nop
on Defines the dates on which the job stream is selected to run. It can be followed by a run cycle definition. on
onlate Defines the action to be taken on a job in the job stream when the job's deadline expires. onlate
onoverlap Specifies how to handle a job stream instance that is scheduled to start although the preceding instance has not yet completed. onoverlap
opens Defines files that must be accessible before the job or job stream is launched. opens
onuntil Specifies the action to take on a job or job stream whose until time has been reached. until
outcond The output condition which, when met, releases the remaining part of the job stream or the job where it is specified. startcond
priority Defines the priority for a job or job stream. priority
prompt Defines prompts that must be replied to before the job or job stream is launched. prompt
runcycle Specifies a label with a friendly name for the run cycle. It is used in conjunction with the following keywords:
except
For exclusive run cycles, that define when the job stream is not to run.
on
For inclusive run cycles, that define when the job stream will run.
schedule Assigns a name to the job stream. schedule
schedtime Specifies the time used to set the job stream in the time line within the plan to determine successors and predecessors. schedtime
startcond Builds into the job stream a mechanism which checks for specific events and conditions and releases the job stream when the specified events or conditions take place. startcond
servicename Specifies the service name to be used for the job stream in Self-Service Catalog. Required if you enable the isservice keyword. When creating and editing SSC-ready job streams, it is recommended you use the Dynamic Workload Console. servicename
servicedescription Specifies the service description to be used for the job stream in Self-Service Catalog. When creating and editing SSC-ready job streams, it is recommended you use the Dynamic Workload Console. servicedescription
servicetags Specifies the service tags to be used to identify the job stream in Self-Service Catalog. When creating and editing SSC-ready job streams, it is recommended you use the Dynamic Workload Console. servicetags
servicevariables Specifies the service variables to be used for the job stream in Self-Service Catalog. When creating and editing SSC-ready job streams, it is recommended you use the Dynamic Workload Console. servicevariables
timezone | tz Specifies the time zone to be used when computing the start time. timezone
until Defines the latest time a job or a job stream can be launched. When defined in a run cycle specifies the latest time a job or a job stream can be launched for that specific run cycle. It is mutually exclusive with the jsuntil keyword. For more information about the jsuntil keyword, see jsuntil. until
validfrom Defines the date from which the job stream instance starts. validfrom/validto
validto Indicates the date on which the job stream instance ends. validfrom/validto
vartable Defines the variable table to be used by the job stream and the run cycle. Variable table
Note:
  1. Job streams scheduled to run on workstations marked as ignored are not added to the production plan when the plan is created or extended.
  2. Wrongly typed keywords used in job definitions lead to truncated job definitions stored in the database. In fact the wrong keyword is considered extraneous to the job definition and so it is interpreted as the job name of an additional job definition. Usually this misinterpretation causes also a syntax error or an inexistent job definition error for the additional job definition.
  3. Granting access to a workstation class or a domain means to give access just to the object itself, and grant no access to the workstations in the object.

Time zone specification rules

You can specify a time zone at several keyword levels within a job stream definition; that is:
  • For the whole job stream (inclusive of all its keyword specifications)
  • At time restriction level (with the at, deadline, schedtime, and until keywords)
  • For each included job statement
The following rules apply when resolving the time zones specified within a job stream definition:
  • When you specify the time zone at job stream level, this applies to the time definitions of the run cycle (defined with the on keyword) as well as to those in the time restrictions.
  • If you specify a time zone both at job stream level and at time restriction level, they must be the same. If you specify no time zone, either at job stream and time restriction levels, the time zone specified on the workstation is used.
  • The time zone specified at job level can differ from the one specified at job stream level and overrides it. If you specify no time zone, either at job stream and job levels, the time zone specified on the workstation running the job is used.

Time restriction specification rules

Within a job stream definition you can specify time restrictions (with the at, deadline, schedtime, and until keywords) at both job stream and run cycle levels. When both are specified, the time restrictions specified at run cycle level override the ones specified at job stream level.

This is an example of job stream definition: 
SCHEDULE M235062_99#TEST/SCHED_FIRST1 VALIDFROM 06/30/2018
ON RUNCYCLE SCHED1_PREDSIMPLE VALIDFROM 07/18/2018 "FREQ=DAILY;INTERVAL=1" 
   ( AT 1010 )
ON RUNCYCLE SCHED1_PRED_SIMPLE VALIDFROM 07/18/2018 "FREQ=DAILY;INTERVAL=1"
CARRYFORWARD
PROMPT "Do you want the job to start?"
PRIORITY 55
:
M235062_99#MYFOLDER/JOBMDM
 PRIORITY 30
 NEEDS 16 M235062_99#JOBSLOTS
 PROMPT PRMT3

B236153_00#JOB_FTA
 FOLLOWS MYFOLDER/JOBMDM
END

See also

From the Dynamic Workload Console you can perform the same task as described in:

Creating job stream definitions.