Time restriction keywords

at

Using this keyword, you can define the earliest time in which job streams or jobs can run. When you define it in a run cycle, the keyword specifies the earliest time job streams can run for that specific run cycle. This keyword is mutually exclusive with the schedtime keyword. For more information about schedtime keyword, see schedtime.

Syntax

at time [timezone|tz tzname][+n day[s]]

Arguments

time: Using this keyword, you can specify a time of the day from 0000 to 2359.
tzname: Using this keyword, you can specify the time zone to use. The default time zone is the one on the workstation on which the job stream or job runs.
Time zones must be the same if at time and until or deadline time have been specified.
n: Using this keyword, you can extend the value of time, specifying a number of days.

Comments

If you do not specify an at time for a job stream or a job, the launch time is based on its dependencies. The position in the plan depends on the value specified for the schedtime keyword. By default, if you do not specify neither at nor schedtime keywords in the job stream definition, the job or job stream instance is placed in the plan at midnight.

The job stream start time is used as default for the run cycles that do not have a start time.

Example

In the following example, the time zone of JOB_STREAM_1 is America/New_York. The job stream contains two job definitions, JOBDEF1 that runs on Friday at 10.00 a.m., and JOBDEF2that runs on Friday at 5.00 p.m. and has the time zone America/Los_Angeles.
```
SCHEDULE WS_AGT_1#JOB_STREAM_1
TZ AMERICA/NEW_YORK
ON FR AT 1000:
WS_AGT_1#JOBDEF1
WS_AGT_1#JOBDEF2 AT 1700 TZ AMERICA/LOS_ANGELES 
END	
```
In the following example, the JOB_STREAM_2 job stream runs on WS_AGT_0 workstation and has Australia/Sydney time zone. It is scheduled to run 22 days later at 5.30 a.m.
```
SCHEDULE WS_AGT_0#JOB_STREAM_2 TIMEZONE Australia/Sydney
AT 0530 +22 DAYS 
:
WS_AGT_0#JOBDEF1

END
```

schedtime

Using this keyword, you can specify the time of the job stream in the plan to determine predecessors and successors. The schedtime value is not considered as a dependency for the job stream. This keyword is mutually exclusive with the at keyword. Differently from the at keyword, job or job stream instances can start running before the time defined with the schedtime keyword , if all the schedtime dependencies have been resolved. For more information about at keyword, see at.

Syntax

schedtime time [timezone|tz tzname][+n day[s]]

Arguments

time: Using this keyword, you can specify a time of the day in the HHHHmm format. Possible values are from 0000 to 2359, or 0000 + <number of days>, where the value of the number of days can be from 1 to 100 days.
tzname: Using this keyword, you can specify the time zone to use. The default time zone is the one on the workstation on which the job stream or job runs.
See Managing time zones for time zone names.
n: Using this keyword, you can extend the value of time, specifying a number of days.

Comments

If you do not specify an at time for a job stream or a job, the launch time is based on its dependencies. The position in the plan depends on the value specified for the schedtime keyword. By default, if you do not specify neither at nor schedtime keywords in the job stream definition, the job or job stream instance is placed in the plan at midnight.

When you schedule a job stream within a run cycle, the job stream instance is created:

with the schedtime value specified within the run cycle or, if missing, within the job stream definition
at midnight, if the schedtime value is not specified neither in the job stream definition nor in the run cycle.

When you submit a job stream, the schedtime value of the instance is the submission time.

For an explanation on how the schedtime keyword is used to identify predecessors in the plan, refer to Managing matching criteria.

Example

The following example schedules the job stream at 9.30 a.m., UTC time zone. The JOBDEF1 job defined in the job stream is set by 8 p.m.

SCHEDULE WS_AGT_0#JOB_STREAM_2 TIMEZONE UTC
SCHEDTIME 0930 
:
WS_AGT_0#JOBDEF1
 AT 2000 

END

deadline

Using this keyword, you can specify the time within which job streams or jobs should complete. When you define it in a run cycle, the keyword specifies the time within which a job stream or job should complete in that specific run cycle.

When job streams or jobs have not started running or are still running when the deadline time is reached, they are displayed as late in ocli plan and a job event is generated.

Syntax

deadline time [timezone|tz tzname][+nday[s]

Arguments

time: Using this keyword, you can specify a time of the day from 0000 to 2359.
tzname: Using this keyword, you can specify the time zone to use. The default time zone is the one on the workstation on which the job stream or job runs.
Time zones must be the same if deadline time and at or until time have been specified.; See Managing time zones for time zone names.
n: Using this keyword, you can extend the value of time, specifying a number of days.

Example

The following example launches JOB_STREAM_3 job stream in 5 days at 5.30 a.m. and it set to be completed in 2 days, by 8.45 p.m.

SCHEDULE WS_AGT_0#JOB_STREAM_3 TIMEZONE Canada/Central
SCHEDTIME 0530 +5 DAYS DEADLINE 2045 +2 DAYS 
:
WS_AGT_0#JOBDEF3

END

until and onuntil

Using this keyword, you can define the latest start time of a job stream or job. It is mutually exclusive with jsuntil, which is the default value. For more information about the jsuntil keyword, see jsuntil.

Each time a job in the job stream is about to start running, the until time defined in the job stream is verified. The job can run only if the until time has not been reached, otherwise the onuntil action is applied.

When the until time expires, an event is generated.

Note: When the time specified as until expires, the until tag is displayed in a job definition.

Syntax

[until time [timezone|tz tzname][+n day[s]][onuntil action]]

Arguments

time

Using this keyword, you can specify a time of the day from 0000 to 2359.

tzname

Using this keyword, you can specify the time zone to use. The default time zone is the one on the workstation on which the job stream or job runs.

Time zones must be the same if until time and at or deadline time have been specified. See Managing time zones for time zone names.

n

Using this keyword, you can extend the value of time, specifying a number of days.

action

Using this keyword, you can specify the action to take when the until time has expired, either on a job that has not yet started or on a job stream that has not completed.

In the following table, you can find the supported onuntil action values:


Action	Description
hold	The job or job stream and any dependent jobs or job streams do not run. This is the default action. When the until time has expired, the job stream status that is displayed is based on the status of the jobs included in the job stream. The suppressed job or job stream keeps its status in READY. The successors keep the HOLD status.
cont	The job or job stream can start running when all the dependencies have been satisfied, even if the until time has expired. When the until time elapses, an event is generated.
canc	A job or job stream must be cancelled and all the dependencies of the successors are released.

If you do not specify an until time for the job and specify a deadline time with an onlate kill action, the until keyword is automatically set to the same time as the deadline keyword. As a result, if the job has not yet started, it does not run.

Example

In the following example, the JOB_STREAM_2 job stream contains the JOBDEF1 job which is scheduled to run at 6:00 a.m. and has to run no later than 7:00 a.m., otherwise it is set to be canceled. The job is set to be completed by 7:00 p.m.

SCHEDULE WS_AGT_0#JOB_STREAM_2 TIMEZONE Europe/Zurich
:
WS_AGT_0#JOBDEF1
 AT 0600 UNTIL 0700 ONUNTIL CANC DEADLINE 1900 

END

jsuntil

Using this keyword, you can specify the latest start time of a job stream. You can use this keyword to specify that a job stream that has started running before its latest start time must complete even if one of the jobs contained in the job stream starts running after that latest start time. It is mutually exclusive with the until keyword. For more information, see until and onuntil.

The jsuntil keyword is verified only once, when all the dependencies of the job stream have been satisfied and its status changes to READY. If jsuntil time has not expired when the first job of the job stream starts running, the job stream continues running even after the jsuntil time has been reached.

By default, the job stream is suppressed two days after the jsuntil time has expired.

Note: When the time specified as until expires, the until tag is displayed in a job stream definition.

Syntax

[jsuntil time [timezone|tz tzname][+n day[s]] [onuntilaction]]

Arguments

time: Using this keyword, you can specify a time of the day from 0000 to 2359.
tzname: Using this keyword, you can specify the time zone to use. The default time zone is the one on the workstation on which the job stream or job runs.
n: Using this keyword, you can extend the value of time, specifying a number of days.

action

Using this keyword, you can specify the action to take on a job stream when the defined until time has expired, but the job stream has not completed in SUCC status.

In the following table, you can find the supported onuntil action values:


Action	Description
hold	The job or job stream and any dependent jobs or job streams do not run. This is the default action. When the until time has expired, the job stream status that is displayed is based on the status of the jobs included in the job stream. The suppressed job or job stream keeps its status in READY. The successors keep the HOLD status.
cont	The job or job stream can start running when all the dependencies have been satisfied, even if the until time has expired. When the until time elapses, an event is generated.
canc	A job or job stream must be cancelled and all the dependencies of the successors are released.

Example

The following example launches JOB_STREAM_2 job stream at 5:30 a.m. and it must run no later than the following day at 0.00 a.m., otherwise the planned action is continue. The job stream contains the JOBDEF1 job definition, that is scheduled to run by 11.00 a.m. 23 days after and that has to complete by 7 p.m.
```
SCHEDULE WS_AGT_0#JOB_STREAM_2 TIMEZONE Europe/Zurich
SCHEDTIME 0530 JSUNTIL 0000 +1 DAYS ONUNTIL CONT 
:
WS_AGT_0#JOBDEF1
 SCHEDTIME 1100 +23 DAYS DEADLINE 1900 

END
```
In the following example, the JOB_STREAM_2 job stream is scheduled by 5.30 a.m. and it completes by 7:00 a.m. 3 days later. It must run no later than the following day at 00.00, otherwise it will be canceled. The job stream also contains the JOBDEF1 job definition, which runs on the next day at 8 p.m. (Etc/UCT time zone) and completes by 7:00 a.m. two days later. It must run no later than 7 p.m. 8 days later, with Ect/UCT time zone.
```
SCHEDULE WS_AGT_0#JOB_STREAM_2 TIMEZONE Europe/Zurich
SCHEDTIME 0530 JSUNTIL 0000 +1 DAYS ONUNTIL CANC DEADLINE 0700 +3 DAYS 
:
WS_AGT_0#JOBDEF1
 AT 2000 TIMEZONE Etc/UCT +1 DAYS UNTIL 0700 TIMEZONE Etc/UCT +2 DAYS DEADLINE 1900 TIMEZONE Etc/UCT +8 DAYS 

END
```

timezone

Using this keyword, you can specify the time zone to use at job stream level for the start time. It applies to the time definitions for run cycles and for time restrictions.

Note: When you define a time zone both for a job stream and a time restriction keyword, you must specify the same time zone.

Syntax

timezone|tz tzname

Arguments

tzname: Using this keyword, you can specify the time zone to use. The default time zone is the one on the workstation on which the job stream or job runs.
See Managing time zones for time zone names.

onlate

Using this keyword, you can specify to kill a job in the job stream when the deadline of the job has expired. You can apply this keyword only to jobs defined in job streams.

Syntax

onlate action

Arguments

action: Using this keyword, you can specify to take a kill action on a job when it is still running even if the deadline has expired. The job is then put in the ABEND status. Job streams and jobs are not released if they are dependent on an ABEND job. If the dependency on the job completing in ABEND status is of conditional type, the dependency is released.

Example

In the following example JOB_STREAM_2 job stream is scheduled at 5.30 a.m., and JOBDEF1 job is scheduled to run in 23 days at 11.00 a.m. If the JOBDEF1 job does not complete by 7.00 p.m., it is planned to stop running.

SCHEDULE WS_AGT_0#JOB_STREAM_2 TIMEZONE Asia/Shanghai
SCHEDTIME 0530
:
WS_AGT_0#JOBDEF1
SCHEDTIME 1100 +23 DAYS DEADLINE 1900 ONLATE KILL



END

maxdur

This keyword only applies to jobs. Using maxdur keyword, you can specify the maximum length of time a job can run. Time is expressed in minutes. If the maximum duration time has expired while the job is still running, either kill action or continue action is triggered. You can see if the maximum duration has expired from:

The ocli plan. MaxDurationExceeded is displayed when running the showjob command.
The job properties in the Dynamic Workload Console.
The log file. A message is written in the TWS_home/stdlist/logs/yyyymmdd_TWSMERGE.log file.

Syntax

maxdur time onmaxdur action

Arguments

time

Using this keyword, you can specify a length of time in HHHMM format, where:

HHH: Expresses the hours in a range of numbers from 000 to 500.
MM: Expresses the minutes in a range of numbers from 00 to 59.

onmaxdur action

Using this keyword, you can specify the action to be triggered on a job that is still running when the maxdur value has been exceeded. You can specify one of the following actions:

Kill: Using this keyword, you can specify that the job must stop running. The job goes in ABEND status and can be rerun. Jobs or job streams that are dependent on a job that has been affected by kill are not released.
Continue: Using this keyword, you can specify that the job must continue running.

When you submit a ocli plan command to define or change the onmaxdur action, the maxdur keyword must be specified together with the onmaxdur argument.

Example

The following example specifies to stop a running job if the job runs longer than 2 hours.
```
MAXDUR 2 onmaxdur kill
```
The following example specifies to continue a running job if the job runs longer than 4 hours.
```
MAXDUR 4 onmaxdur continue
```

mindur

This keyword only applies to jobs. Using the mindur keyword, you can specify the shortest length of time a job should normally run and complete. If a job completes before the minimum amount of time has been reached, either Abend, Confirm or Continue action is triggered. If the job completes with SUCCESS, you can see if the minimum duration has not been reached from:

The ocli plan. MinDurationNotReached is displayed when running the showjob and showjobs ;props commands.
The job properties in the Dynamic Workload Console.
The log file. A message is written in the TWS_home/stdlist/logs/yyyymmdd_TWSMERGE.log file.

Syntax

mindur time onmindur action

Arguments

time

Using this keyword, you can specify a length of time in HHHMM format, where:

HHH: Expresses the hours in a range of numbers from 000 to 500.
MM: Expresses the minutes in a range of numbers from 00 to 59.

onmindur action

Using this keyword, you can specify the action to be triggered on a job that has completed before the defined minimum duration. You can specify one of the following actions:

Abend: Using this keyword, you can specify that the job must be set to ABEND status.
Confirm: Using this keyword, you can specify that the job must be set to CONFIRM status. The user must confirm to let the workload proceed.
Continue: Using this keyword, you can specify that the workload must continue running.

Example

The following example specifies to continue a running workload even if the job does not reach a minimum duration of at least 1 minute.
```
MINDUR 1 ONMINDUR CONT
```
The following example specifies to set the job status to Error if the job does not run for at least 8 minutes:
```
MINDUR 8 ONMINDUR ABEND
```