ADD – Add applications or groups to the current plan
Use the ADD
command to add applications or groups of applications
to the current plan. You can add a single occurrence (ONCE mode) or resubmit or restart
the currently running occurrence (REPEAT mode).
When using this command, consider that:
- If the Input Arrival time is later than the end of the current
plan, the
ADD
command adds the occurrence to the long-term plan, not to the current plan. - When adding to the
long-term plan:
- If
DEPRES
is set toY
,LTDRES
is set toY
, and some dependencies cannot be resolved, theADD
command adds the occurrences, resolve the dependencies that can be resolved, and end with RC=4. If - If
DEPRES
is set toY
,LTDRES
is set toN
, and some dependencies cannot be resolved, theADD
command fails when the application or operation related to a dependency is not defined in the Application Description.
- If
ADD ADID(<adid>)|GROUPDEF(<groupdef>) [JCLVTAB(<table>)]
[DEPRES(Y|N|P|S)] [LTDRES(YES|NO)]
[IA(yymmddhhmm) | IADATE(yymmdd) IATIME(hhmm)] [FINDIA(Y|N)]
[FROM(hhmm)] [UNTIL(hhmm)] [EVERY(hhmm)] [COUNT(nnnn)]
[ORIGIN(START|END|IA)] [RESOLVE(NEXT|GAP|BOTH|hhmm)]
[RESTART(opnum[,FLUSH])]
[EARLY(ABORT|CONTINUE)] [NOTIFY(N|W|E)]
[DLDAY(n)] [DLTIME(hhmm)] [LINK(YES|NO)]
[HOLD(NO|START|ALL)] [UPDATE(YES|NO)]
ADD
command uses the same keywords
used with other PIF and Workload Automation Programming Language commands. For consistency with the OCL ADD
command, you can use APPL
as an alternative
to ADID
, GROUP
as
an alternative to GROUPDEF
, VARTAB
as an alternative to JCLVTAB
, and CPDEPR
and GDEPRES
as an alternative to DEPRES
. For
consistency with repeating run cycles in Batch Loader, you can use IATIME
as an alternative to FROM
, RPTEND
as an alternative to UNTIL
, and RPTEVRY
as an alternative
to EVERY
.If you specified the UNTIL
or EVERY
keyword, the
ADD
command is used in REPEAT mode.
ADID|GROUPDEF
- Indicates an application or a group to submit. If you specify
GROUPDEF
, theADD
command submits every application included in that application group. When operating in REPEAT mode, neitherADID
orGROUPDEF
are required, but you specify them they must match the running application or group. JCLVTAB
- Indicates a JCL variable table that can be attached to the occurrence.
DEPRES(Y|N|P|S)
- Determines whether external dependencies are resolved when the
occurrences are added to the current plan. This also affects the setting
of
OPTIONS CPDEPR
orLTDEPR
for the remainder of the Workload Automation Programming Language session, depending on the plan that is used. The default is Y. For additions to the long-term plan,P
orS
are translated toY
. LTDRES(Y|N|P|S)
- Determines
whether, when resolving LTP external dependencies according to
DEPRES(Y)
, theADD
command fails or not if the application specified in the dependency is not defined in the Application Description.When you set
LTDRES(N)
(default), theADD
command fails with RC=8. When you setLTDRES(Y)
and the occurrence is to be added to the LTP, if some dependencies cannot be resolved because the application is not defined in the AD, theADD
command adds the occurrence, resolves the dependencies that can be resolved, and ends with RC=4. UPDATE(YES|NO)
- Determines whether the job actually performs the updates to the
current plan or long-term plan. The default behaviour is to perform
the updates, but you can modify it with
OPTIONS UPDATE
. IfUPDATE
is set toNO
, the command processes everything and generate the commands to perform the update, but does not run them. If you specifyOPTIONS TRACE(1)
, messages EQQI906A are created to list the commands that would have been performed.
IA(yymmddhhmm)
- A fully qualified input arrival time. This keyword is mutually
exclusive with
IADATE
andIATIME
. You can use relative times; for example,IA(+15)
creates an Input Arrival time 15 minutes later, and the date is adjusted if midnight is passed. IADATE(yymmdd)
- An input arrival date. If
IATIME
is not set, the current time is used in conjunction with the date specified. You can use relative dates; for example,IADATE(+1)
uses tomorrowʼs date. IATIME(hhmm)
- An input arrival time to be set independently of the date. You can
use relative times; for example,
IATIME(+15)
creates an Input Arrival time 15 minutes later, however if midnight is passed the date is not adjusted. Use theIA
keyword only if you want to set a specific time. FINDIA(Y|N)
- If you specified
IA
,IADATE
, orIATIME
, theADD
command generates an Input Arrival time to use when adding the occurrence to the plan. IfFINDIA
is set toN
and an occurrence already exists with the same Input Arrival, the submission fails. SettingFINDIA
toY
causes theADD
command to find the next available Input Arrival time following the one determined by theADD
command. If you specifiedIA
orIATIME
, theFINDIA
keyword defaults toN
; if you specified onlyIADATE
, theFINDIA
keyword defaults toY
. If you did not specify anyIA
,IADATE
, orIATIME
, theADD
command does not allocate an Input Arrival time, and is automatically assigned the next available time. LINK(Y|N)
- When you use the
ADD
command within a job controlled by HCL Workload Automation for Z, you can useLINK
to make the newly added occurrence dependent on the submitting job, and become a predecessor to the successors of the submitting job. This ensures the dynamically added occurrence will complete before any successors to the submitting job are able to run. The process automatically finds the start and end points of the application being added. TheLINK
keyword can be used only when adding a single application.LINK
cannot be used withGROUPDEF
. HOLD(NO|START|ALL)
- Use
HOLD
to hold the operations in the occurrence being added. SpecifyingSTART
holds all operations with no predecessors. SpecifyingALL
holds all operations in the new occurrence. If there are operations within the occurrence that are on workstations that cannot be held, such as manual operations, message EQQI051W is issued with RC=4. This warning can be downgraded to information by running commandSETSEV 051I
prior to theADD
command in the same Workload Automation Programming Language step.
FINDIA
appears to have skipped an
Input Arrival minute, this is due to occurrences that have been manually
deleted from the current plan. HCL Workload Automation for Z cannot reuse an input arrival time for an application, even if it
was deleted.UNTIL
or
EVERY
.FROM(hhmm)
- Sets the earliest Input Arrival time for a repeating cycle to
start from. If
FROM
is specified earlier thanUNTIL
,UNTIL
is considered to be after midnight. For values ofRESOLVE
other thanGAP
, theFROM
time is used as the base to calculate multiples ofEVERY
to help chose the next Input Arrival time. IfFROM
is not specified, the current time is used for the first instance and passed to subsequent instances. UNTIL(hhmm)
- Sets the latest Input Arrival time for a repeating cycle to end.
If
UNTIL
is not specified, one minute prior to the current time is used for the first instance and passed to subsequent instances. EVERY(hhmm)
- Sets the interval of hours and minutes to use to calculate the
next Input Arrival time. If
EVERY
is not specified, 1 hour is used. COUNT(nnnn)
- Sets a limit to the number of instances of the occurrence is allowed to repeat.
ORIGIN
- Specifies the time used to base the calculation for the next interval:
END
- The current time (logical end point of the process). This is the default.
START
- The start time of the occurrence (Occurrence Actual Arrival).
IA
- The Input Arrival.
RESOLVE
- Specifies the rules used to calculate the next interval:
NEXT
- Uses the next multiple of the
EVERY
time after theORIGIN
time. GAP
- Adds the
EVERY
interval to theORIGIN
time. BOTH
- Adds the
EVERY
interval to theORIGIN
time and then take the next multiple of theEVERY
time. hhmm
- Uses the next multiple of the
EVERY
time that is at leasthhmm
time from theORIGIN
time
RESTART(opnum[,FLUSH])
- If the
FROM
,UNTIL
, orCOUNT
keyword are not respected, this keyword restarts the current operation from the specified operation number at the time calculated according theEVERY
keyword. To ensure that the JCL is resolved on restart, all the job stream records for this occurrence are deleted.If the
FROM
,UNTIL
, orCOUNT
keyword are respected, theFLUSH
keyword sets all the remaining operations in the occurrence toNOP
. This enables the batch program to repeat until a file is found, and process it.In the following example, operation 005 searches for a file which, if not found, returns RC=4. The command restarts every 5 minutes, if the file is not found. If the file is found, the command continues to the remaining operations that process the file. However, if the repeat limit is reached without finding the requested file, the remaining operations are flushed. If you are expecting more than one file in a day, you might want to set anotherADD
command to restart the operations again and wait for the next file.VARSUB SCAN SELECT CPOPCOM ADID(!OADID) IA(!OYMD1!OHHMM) OPNO(005) OBJECT(CHECKOP) IF '!@CHECKOP-CPOPORIGRC' = '0004' THEN DO ADD FROM(0000) UNTIL(2355) EVERY(005) RESTART(001,FLUSH)
NOTIFY(N|W|E)
- Controls behavior when an
ADD
command has determined that no more occurrences are to be added:N
- Command ends with RC=0 for standard termination causes.
W
- Command ends with RC=4 if next detected Input
Arrival is outside of range, if the
COUNT
limit has been reached or an existing occurrence is detected between theORIGIN
time and the next Input Arrival. E
- Command ends with RC=4 if next detected Input
Arrival is outside of range or if the
COUNT
limit has been reached. It ends with RC=8 if an existing occurrence is detected between theORIGIN
time and the next Input Arrival.
EARLY(ABORT|CONTINUE)
- Controls behavior when the
ADD
command finds anORIGIN
time earlier than the Input Arrival time of the controlling occurrence. By default, theADD
command fails with RC=8 to protect against the eventuality that a Time Dependent flag has not been set in the Application Definition. If however the occurrence has been deliberately released early, restarting theADD
step with keywordEARLY(CONTINUE)
will use the Application Input arrival time as theORIGIN
point if it is later than the chosenORIGIN
.
EARLY(CONTINUE)
must be used only as an option for
restart. It must ever be coded in permanent SYSIN, because it prevents protection
for missing Time Dependencies and might result in many instances of the occurrence
running in close succession.DLDAY(n)
- Specifies the relative day to the current time to set the deadline
for 0 being the same day, 1 being the following day, and so on. The
DLDAY
keyword counts Calendar days, it does not differentiate between Workdays and Freedays. DLTIME(hhmm)
- Specifies the time of the deadline.
The ONCE mode deadline policy is as follows:
- When
DLTIME
is set withoutDLDAY
, Workload Automation Programming Language assumes the same “logical day”. IfDLTIME
is earlier than the current time, it is assumed to be post midnight. - When
DLDAY
is set to 0 withoutDLTIME
, HCL Workload Automation for Z sets the deadline by applying normal rules. - When
DLDAY
is set > 0 withoutDLTIME
, Workload Automation Programming Language assumes current time on relative day. - If
DLDAY
is set to 0 andDLTIME
is earlier than current time, the submission fails. - In all other cases, HCL Workload Automation for Z sets the deadline by applying normal rules.
The REPEAT mode deadline policy is as follows:
- Deadline is always calculated relative to
FROM
and adjusted for current occurrence. - When
DLTIME
is set withoutDLDAY
, Workload Automation Programming Language assumes the same “logical day”. IfDLTIME
is earlier than the current time, it is assumed to be post midnight. - When
DLDAY
is set to 0 withoutDLTIME
, Workload Automation Programming Languageuses theEVERY
value to calculate the deadline. - When
DLDAY
is set > 0 withoutDLTIME
, Workload Automation Programming Language assumes current time on relative day. - When
DLDAY
andDLTIME
are both set, the deadline is the specified time on the relative day.If
DLDAY
is explicitly set to 0 andDLTIME
is earlier than theFROM
time, the submission fails. - In all other cases, the gap between the IA and deadline or the currently running occurrence will be used to calculate new deadline.