HCL Workload Automation, Version 9.4

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.

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 [workstation#]jobstreamname
    # comment
    [validfrom date]
    [timezone|tz tzname]
    [description ”text”]
    [draft]
    [vartable table_name]
    [freedays calendarname [-sa] [-su]]
    [on [runcycle name
       [validfrom date] [validto date]
       [description ”text”]
       [vartable table_name]]
      {date|day|calendar|request|”icalendar”|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]]])]]
    [,...]]
startcond filecreated | filemodified workstation_name#file_name user username
interval
seconds [(alias startcond_jobname rerun batch outfile outputfilename
params "filemonitor additional parameters")] |
startcond job workstation_name#job_name outcond joboutputcondition interval
seconds [(alias startcond_jobname rerun)]
:
    [except [runcycle name]
          [validfrom date] [validto date]
          [description ”text”]
          {date|day|calendar|request|”icalendar”|runcyclegroup} [,...]
          [fdignore|fdnext|fdprev]
          [{(at time [+n day[s]])] |
          (schedtime time [+n day[s]])}]
    [,...]
    [{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] [workstation#]resourcename } [,...] ] [...]
    [opens { [workstation#]"filename" [ (qualifier) ] [,...] }]  [...]
    [priority number | hi | go]
    [prompt {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] [workstation#]resourcename } [,...] ] [...]
    [opens { [workstation#]"filename" [ (qualifier) ] [,...] }]  [...]
    [priority number | hi | go]
    [prompt {promptname|"[:|!]text"} [,...] ] [...]
    [nop]
    [statistictype custom]

[job-statement...]
end

Arguments

Table 1 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
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
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 for monitoring by applications, such as IBM® Tivoli® Business Systems Manager or IBM Tivoli Enterprise Console®.	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.	except on
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
statisticstype custom	Flags a job for the use of SPSS-based statistical analysis to forecast its estimated duration.	statisticstype custom
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
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.	vartable

Note:

Job streams scheduled to run on workstations marked as ignored are not added to the production plan when the plan is created or extended.
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.
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.

Example

This is an example of job stream definition: