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 to Y, LTDRES is set to Y, and some dependencies cannot be resolved, the ADD command adds the occurrences, resolve the dependencies that can be resolved, and end with RC=4. If
    • If DEPRES is set to Y, LTDRES is set to N, and some dependencies cannot be resolved, the ADD command fails when the application or operation related to a dependency is not defined in the Application Description. 
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)]

The ADD command uses the same keywords used with other PIF and Workload Automation Programming Language commands.

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 keyword UNTIL or EVERY, the ADD command is used in REPEAT mode.

The following list shows the general keywords:
ADID|GROUPDEF
Indicates an application or a group to submit. If you specify GROUPDEF, the ADD command submits every application included in that application group. When operating in REPEAT mode, neither ADID or GROUPDEF 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 or LTDEPR 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 or S are translated to Y.
LTDRES(Y|N|P|S)
Determines whether, when resolving LTP external dependencies according to DEPRES(Y), the ADD command fails or not if the application specified in the dependency is not defined in the Application Description.

When you set LTDRES(N) (default), the ADD command fails with RC=8. When you set LTDRES(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, the ADD 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 behavior is to perform the updates, but you can modify it with OPTIONS UPDATE. If UPDATE is set to NO, the command processes everything and generate the commands to perform the update, but does not run them. If you specify OPTIONS TRACE(1), messages EQQI906A are created to list the commands that would have been performed.
The following list shows keywords for running in ONCE mode:
IA(yymmddhhmm)
A fully qualified input arrival time. This keyword is mutually exclusive with IADATE and IATIME. 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 the IA keyword only if you want to set a specific time.
FINDIA(Y|N)
If you specified IA, IADATE, or IATIME, the ADD command generates an Input Arrival time to use when adding the occurrence to the plan. If FINDIA is set to N and an occurrence already exists with the same Input Arrival, the submission fails. Setting FINDIA to Y causes the ADD command to find the next available Input Arrival time following the one determined by the ADD command. If you specified IA or IATIME, the FINDIA keyword defaults to N; if you specified only IADATE, the FINDIA keyword defaults to Y. If you did not specify any IA, IADATE, or IATIME, the ADD 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 use LINK 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. The LINK keyword can be used only when adding a single application.

LINK cannot be used with GROUPDEF.

HOLD(NO|START|ALL)
Use HOLD to hold the operations in the occurrence being added. Specifying START holds all operations with no predecessors. Specifying ALL 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 command SETSEV 051I prior to the ADD command in the same Workload Automation Programming Language step.
Note: If 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.
The following list shows keywords for running in REPEAT mode:
Note: To select the REPEAT mode behavior, you must specify at least UNTIL or EVERY.
FROM(hhmm)
Sets the earliest Input Arrival time for a repeating cycle to start from. If FROM is specified earlier than UNTIL, UNTIL is considered to be after midnight. For values of RESOLVE other than GAP, the FROM time is used as the base to calculate multiples of EVERY to help chose the next Input Arrival time. If FROM 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 the ORIGIN time.
GAP
Adds the EVERY interval to the ORIGIN time.
BOTH
Adds the EVERY interval to the ORIGIN time and then take the next multiple of the EVERY time.
hhmm
Uses the next multiple of the EVERY time that is at least hhmm time from the ORIGIN time
RESTART(opnum[,FLUSH])
If the FROM, UNTIL, or COUNT keyword are not respected, this keyword restarts the current operation from the specified operation number at the time calculated according the EVERY keyword. To ensure that the JCL is resolved on restart, all the job stream records for this occurrence are deleted.

If the FROM, UNTIL, or COUNT keyword are respected, the FLUSH keyword sets all the remaining operations in the occurrence to NOP. 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 another ADD 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 the ORIGIN 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 the ORIGIN time and the next Input Arrival.
EARLY(ABORT|CONTINUE)
Controls behavior when the ADD command finds an ORIGIN time earlier than the Input Arrival time of the controlling occurrence. By default, the ADD 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 the ADD step with keyword EARLY(CONTINUE) will use the Application Input arrival time as the ORIGIN point if it is later than the chosen ORIGIN.
Note: 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.
Deadline keywords are:
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 without DLDAY, Workload Automation Programming Language assumes the same “logical day”. If DLTIME is earlier than the current time, it is assumed to be post midnight.
  • When DLDAY is set to 0 without DLTIME, HCL Workload Automation for Z sets the deadline by applying normal rules.
  • When DLDAY is set > 0 without DLTIME, Workload Automation Programming Language assumes current time on relative day.
  • If DLDAY is set to 0 and DLTIME 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 without DLDAY, Workload Automation Programming Language assumes the same “logical day”. If DLTIME is earlier than the current time, it is assumed to be post midnight.
  • When DLDAY is set to 0 without DLTIME, Workload Automation Programming Languageuses the EVERY value to calculate the deadline.
  • When DLDAY is set > 0 without DLTIME, Workload Automation Programming Language assumes current time on relative day.
  • When DLDAY and DLTIME are both set, the deadline is the specified time on the relative day.

    If DLDAY is explicitly set to 0 and DLTIME is earlier than the FROM 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.