Time restriction keywords

In this topic you can find the list of time restriction keywords.

This topic lists all the keywords that you can use when defining a time restriction. You can find the syntax of the scheduling keywords and related examples.

In this topic you can find the following time restriction keywords:

at

Using this keyword, you can define the earliest time in which workflows or tasks can run. When you define it in a run cycle, the keyword specifies the earliest time workflows 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 workflow or task 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 workflow or a task, 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 workflow definition, the task or workflow instance is placed in the plan at midnight.

The workflow 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 WORKFLOW_1 is America/New_York. The workflow contains two task definitions, TASKDEF1 that runs on Friday at 10.00 a.m., and TASKDEF2that runs on Friday at 5.00 p.m. and has the time zone America/Los_Angeles.
    SCHEDULE WS_AGT_1#WORKFLOW_1
TZ AMERICA/NEW_YORK
ON FR AT 1000:
WS_AGT_1#TASKDEF1
WS_AGT_1#TASKDEF2 AT 1700 TZ AMERICA/LOS_ANGELES 
END
  • In the following example, the WORKFLOW_2 workflow 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#WORKFLOW_2 TIMEZONE Australia/Sydney
AT 0530 +22 DAYS 
:
WS_AGT_0#TASKDEF1

END

deadline

Using this keyword, you can specify the time within which workflows or tasks should complete. When you define it in a run cycle, the keyword specifies the time within which a workflow or task should complete in that specific run cycle.

When workflows or tasks have not started running or are still running when the deadline time is reached, they are displayed as late in ocli plan and a task 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 workflow or task 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 WORKFLOW_3 workflow 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#WORKFLOW_3 TIMEZONE Canada/Central
SCHEDTIME 0530 +5 DAYS DEADLINE 2045 +2 DAYS 
:
WS_AGT_0#TASKDEF3

END

every

You can use every option to schedule a task to run multiple times at a specified interval. You can use this scenario to automate repetitive operations, that ensures the task runs consistently at defined intervals without manual intervention. Specify the repetition rate in hhmm format. You must set the value for every option with UNTIL parameter. The tasks are run till the time specified as UNTIL. You must edit the respective workflow of the task to set up the repetition rate. You can set the parameters and values as follows:
latestStartTime = HHMM
        repeatInterval = hhmm
        [skipLateAction = None | overlap | immediate]
When the server or agent experiences downtime, you can control the behaviour of tasks that are missed using the SKIPLATE parameter. This parameter provides flexibility in managing how missed tasks are handled when the system becomes available again. It determines whether tasks that were scheduled to run during a downtime period should be submitted or skipped when the system comes back online. You can provide any one of the following options:
  • None:
    The default value. All the tasks that are delayed are run when the server comes back online.
  • overlap
    The delayed run is skipped if its already time for the next run as per the schedule set by every option or else all the delayed tasks are submitted.
  • immediate
    You can use this option to set a specific time period to skip or submit delayed tasks. You can specify a time period in minutes (mm format) and the maximum supported value is 59 minutes. In addition to specifying the value for the SKIPLATE parameter, you must also customize the UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES parameter. When the system comes back online, the agent calculates the time as follows:
    (nextPlannedTime - currentTime) > UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES
    Where the nextPlannedTime = the next occurrence of task run as per the schedule set by every option and currentTime = the time when the server or agent is back online.

    It then calculates, and then proceed as follows:

    If (nextPlannedTime - currentTime) > UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES, the delayed tasks are submitted immediately. For this scenario you must always set a value lower than every option for UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES.

    If (nextPlannedTime - currentTime) < UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES, the delayed tasks are skipped. For this scenario you must always set a value higher than every option for UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES.

Examples

  1. Add the following details to set a repetition rate of 01:30 for the task TASKA until 21:30:
    SCHEDULE WS_AGT_0#WORKFLOW
:
WS_AGT_0#TASKA
EVERY 0130
UNTIL 2130

END
  2. The following example shows how to skip or submit tasks for a particular time period. The task TASKA starts at 14:00 and runs until 15:00. The every option is set for 10 minutes and the SKIPLATE option is set to immediate. The value for UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES is set by 5 minutes, a value less than every option. The task runs every 10 minutes from 14:00 till 15:00.
    SCHEDULE WS_AGT_0#WORKFLOW
:
WS_AGT_0#TASKA
AT 1400
EVERY 0010 SKIPLATE IMMEDIATE
UNTIL 1500

END
    If the server goes down at 14:35 and comes back at 14:51, two instances of rerun at 14:40 and 14:50 are missed. Now the delayed task are submitted, only if
    (nextPlannedTime - currentTime) > UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES.
    For this scenario, if we replace the variables with values where, nextPlannedTime = 15:00, currentTime = 14:51, and UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES = 5 minutes.

    Then (nextPlannedTime - currentTime) is 15:00 - 14:51 = 9 minutes, which is greater than the value of UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES (5 minutes). So all the delayed task are submitted Until 15:00.

    To skip the delayed task for the same scenario, you can provide a value higher than every option for UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES.

    For example, if the value for UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES is set by 11 minutes, and the server is down for the same time period (14:35 and comes back at 14:51).

    Then (nextPlannedTime - currentTime) is 15:00 - 14:51 = 9 minutes, which is less than the value of UNO_EVERY_IMMEDIATE_INTERVAL_IN_MINUTES (11 minutes). So all the delayed task are skipped.

jsuntil

Using this keyword, you can specify the latest start time of a workflow. You can use this keyword to specify that a workflow that has started running before its latest start time must complete even if one of the tasks contained in the workflow 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 workflow have been satisfied and its status changes to READY. If jsuntil time has not expired when the first task of the workflow starts running, the workflow continues running even after the jsuntil time has been reached.

By default, the workflow 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 workflow 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 workflow or task 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 workflow when the defined until time has expired, but the workflow has not completed in SUCC status.
In the following table, you can find the supported onuntil action values:
Action Description
hold The task or workflow and any dependent tasks or workflows do not run. This is the default action. When the until time has expired, the workflow status that is displayed is based on the status of the tasks included in the workflow. The suppressed task or workflow keeps its status in READY. The successors keep the HOLD status.
cont The task or workflow 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 task or workflow must be cancelled and all the dependencies of the successors are released.
Example
  • The following example launches WORKFLOW_2 workflow 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 workflow contains the TASKDEF1 task 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#WORKFLOW_2 TIMEZONE Europe/Zurich
SCHEDTIME 0530 JSUNTIL 0000 +1 DAYS ONUNTIL CONT 
:
WS_AGT_0#TASKDEF1
 SCHEDTIME 1100 +23 DAYS DEADLINE 1900 

END
  • In the following example, the WORKFLOW_2 workflow 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 workflow also contains the TASKDEF1 task 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#WORKFLOW_2 TIMEZONE Europe/Zurich
SCHEDTIME 0530 JSUNTIL 0000 +1 DAYS ONUNTIL CANC DEADLINE 0700 +3 DAYS 
:
WS_AGT_0#TASKDEF1
 AT 2000 TIMEZONE Etc/UCT +1 DAYS UNTIL 0700 TIMEZONE Etc/UCT +2 DAYS DEADLINE 1900 TIMEZONE Etc/UCT +8 DAYS 

END

maxdur

This keyword only applies to tasks. Using maxdur keyword, you can specify the maximum length of time a task can run. Time is expressed in minutes. If the maximum duration time has expired while the task 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 task properties in the UI.
  • 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 task 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 task must stop running. The task goes in ABEND status and can be rerun. tasks or workflows that are dependent on a task that has been affected by kill are not released.
Continue
Using this keyword, you can specify that the task 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 task if the task runs longer than 2 hours.
    MAXDUR 2 onmaxdur kill
  • The following example specifies to continue a running task if the task runs longer than 4 hours.
    MAXDUR 4 onmaxdur continue

mindur

This keyword only applies to tasks. Using the mindur keyword, you can specify the shortest length of time a task should normally run and complete. If a task completes before the minimum amount of time has been reached, either Abend, Confirm or Continue action is triggered. If the task 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 task properties in the UI.
  • 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 task 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 task must be set to ABEND status.
Confirm
Using this keyword, you can specify that the task 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 task does not reach a minimum duration of at least 1 minute.
    MINDUR 1 ONMINDUR CONT
  • The following example specifies to set the task status to Error if the task does not run for at least 8 minutes: 
    MINDUR 8 ONMINDUR ABEND

onlate

Using this keyword, you can specify to kill a task in the workflow when the deadline of the task has expired. You can apply this keyword only to tasks defined in workflows.

Syntax

onlate action

Arguments

action
Using this keyword, you can specify to take a kill action on a task when it is still running even if the deadline has expired. The task is then put in the ABEND status. Workflows and tasks are not released if they are dependent on an ABEND task. If the dependency on the task completing in ABEND status is of conditional type, the dependency is released.
Example
In the following example WORKFLOW_2 workflow is scheduled at 5.30 a.m., and TASKDEF1 task is scheduled to run in 23 days at 11.00 a.m. If the TASKDEF1 task does not complete by 7.00 p.m., it is planned to stop running.
SCHEDULE WS_AGT_0#WORKFLOW_2 TIMEZONE Asia/Shanghai
SCHEDTIME 0530
:
WS_AGT_0#TASKDEF1
SCHEDTIME 1100 +23 DAYS DEADLINE 1900 ONLATE KILL



END

schedtime

Using this keyword, you can specify the time of the workflow in the plan to determine predecessors and successors. The schedtime value is not considered as a dependency for the workflow. This keyword is mutually exclusive with the at keyword. Differently from the at keyword, task or workflow 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 workflow or task 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 workflow or a task, 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 workflow definition, the task or workflow instance is placed in the plan at midnight.

When you schedule a workflow within a run cycle, the workflow instance is created:
  • with the schedtime value specified within the run cycle or, if missing, within the workflow definition
  • at midnight, if the schedtime value is not specified neither in the workflow definition nor in the run cycle.
When you submit a workflow, 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 workflow at 9.30 a.m., UTC time zone. The TASKDEF1 task defined in the workflow is set by 8 p.m.
SCHEDULE WS_AGT_0#WORKFLOW_2 TIMEZONE UTC
SCHEDTIME 0930 
:
WS_AGT_0#TASKDEF1
 AT 2000 

END

timezone

Using this keyword, you can specify the time zone to use at workflow 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 workflow 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 workflow or task runs.

See Managing time zones for time zone names.

until and onuntil

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

Each time a task in the workflow is about to start running, the until time defined in the workflow is verified. The task 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 task 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 workflow or task 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 task that has not yet started or on a workflow that has not completed.
In the following table, you can find the supported onuntil action values:
Action Description
hold The task or workflow and any dependent tasks or workflows do not run. This is the default action. When the until time has expired, the workflow status that is displayed is based on the status of the tasks included in the workflow. The suppressed task or workflow keeps its status in READY. The successors keep the HOLD status.
cont The task or workflow 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 task or workflow must be cancelled and all the dependencies of the successors are released.

If you do not specify an until time for the task 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 task has not yet started, it does not run.

Example
In the following example, the WORKFLOW_2 workflow contains the TASKDEF1 task 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 task is set to be completed by 7:00 p.m.
SCHEDULE WS_AGT_0#WORKFLOW_2 TIMEZONE Europe/Zurich
:
WS_AGT_0#TASKDEF1
 AT 0600 UNTIL 0700 ONUNTIL CANC DEADLINE 1900 

END