ADSTART

Purpose

Use the ADSTART control statement to signal the start of an application description. When this statement is found in the input data set, it signals the batch loader to complete the preceding AD or OI being built and write it to the database.

If you have specified OPTIONS ACTION(ADD) and an application description with the same ADID, STATUS, and ADVALFROM already exists, these actions are taken:
  • The processing of the ADSTART is terminated.
  • An error message is issued.
  • The statements that follow are ignored until the next ADSTART or OISTART statement is found in the input data set.

Format


1  ADSTART?  ACTION (
2.1! ADD
2.1 SETDEFAULT
1 )  ADID (
2.1 application ID
1 )?  ADGROUPID (
2.1 group definition ID
1 )?  ADSTAT (
2.1! A
2.1 P
1 )?  ADTYPE (
2.1! A
2.1 G
1 )?  ADVALFROM (
2.1! current date
2.1 yymmdd
1 )?  CALENDAR (
2.1! default calendar
2.1 calendar name
1 )?  DESCR ('
2.1 descriptive text
1 ')?  DLIMFDBK (
2.1 limit for deadline feedback
1 )?  DSMOOTHING (
2.1 deadline smoothing factor
1 )?  GROUP (
2.1 authority group
1 )?  ODESCR ('
2.1 owner description
1 ')  OWNER (
2.1 owner ID
1 )?  PRIORITY (
2.1! 5
2.1 priority
1 )

Restrictions

You cannot use ACTION(SETDEFAULT) to set default values for this keyword: ADID.

Parameters

ACTION (SETDEFAULT | ADD)
If you specify SETDEFAULT, the remaining keyword values that you specify on the ADSTART statement become default values for all ADSTART statements that follow. No application description is updated. Keywords that you do not specify are assigned their standard defaults.

If you specify ADD or use it by default, the statement can result in an update of the database.

ADID (application ID)
The job name or identifier of the new application, in either EBCDIC or DBCS format, as specified on the OPTIONS statement. If you use DBCS characters, you must enter them as a quoted string started by shift-out (X'0E') and ended by shift-in (X'0F').

An ADID must be specified.

ADGROUPID (group definition ID)
The name of the group definition used by this application to generate run cycle information. The name can be in either EBCDIC or DBCS format, as specified on the OPTIONS statement. If you use DBCS characters, you must enter them as a quoted string started by shift-out (X'0E') and ended by shift-in (X'0F').

This keyword is valid only for an ADTYPE of A and should not be specified with CALENDAR.

ADSTAT (A | P)
Application status indicator. A is for active, P is for pending application description.
ADTYPE (A | G)
Application type indicator. A is for applications, G is for group definitions.
ADVALFROM (yymmdd | current date)
Defines the start date of the validity period of the AD. Only the start date can be specified. The end of the validity period is set so that the time up to 31 December 2071 is covered, taking existing application descriptions into account. IBM Z Workload Scheduler interprets the yy part as follows:
YY
Year
72 - 99
1972 - 1999
00 - 71
2000 - 2071
CALENDAR (calendar | default calendar)
The name of the calendar to be used when run days are calculated for this application or group definition. Do not specify this keyword for applications that are members of a group.
DESCR ('descriptive text')
A free-format description of the application up to 24 characters and contained in single quotation marks.
DLIMFDBK (limit for deadline feedback)
The deadline limit for feedback. This keyword determines if the estimated deadline in the application description run cycle or operation is updated when an occurrence of the application reaches the complete status. The DLIMFDBK keyword value you set in this keyword is used only if no value is set in the application description.

Feedback values are in the range 100 through 999. The value 0, meaning that the deadline must always be updated, regardless of the estimated and actual values, cannot be specified at application level in batch loader, PIF, and ISPF panels. It can be specified only in the DLIMFDBK keyword of the JTOPTS statement.

The feedback limits for ADL are calculated as follows:
  • Lower limit = ODL * 100/DLF
  • Upper limit = ODL * DLF/100
Where:
ADL
The actual deadline, considered as the elapsed minutes between the IA and the completion time of the occurrence or operation.
ODL
The old deadline estimated for the run cycle or operation (considered as offset in minutes from the IA) currently stored in the application description database.
DLF
The deadline limit for feedback.

When the deadline feedback limit is set to 100, no new estimated deadline is stored in the application description database. If the actual deadline lies within the feedback limits, a smoothing factor is applied before the application description is updated.

If the completion time occurs before the IA time, the deadline is not updated and a missed feedback record is generated.

When the occurrence is generated, an identifier of the run cycle that generates the occurrence is stored in the occurrence record. This identifier is used to determine which run cycle must be updated. If the application description or the occurrence input arrival was modified, the run cycle might no longer be matchable. In this case, the deadline is not updated and a missed feedback record is generated.

DSMOOTHING (deadline smoothing factor)
The smoothing factor. It determines how much the actual deadline influences the new deadline estimated for a run cycle or operation in the application description database. The smoothing factor is applied only if the actual deadline lies within the deadline feedback limits. The DSMOOTHING keyword value is used only if you did not set a smoothing factor in the application description.

The smoothing factor is in the range 0 through 999. A value of 0 means that the deadline is not updated, a value of 100 means that the actual deadline replaces the existing estimated deadline.

The new deadline is calculated as follows: 
NDL = ODL + ((ADL - ODL) * DSF/100)
Where:
NDL
The new deadline estimated for the run cycle or operation (considered as offset in minutes from the IA) to be stored in the application description database.
ODL
The old deadline estimated for the run cycle or operation (considered as offset in minutes from the IA) currently stored in the application description database.
ADL
The actual deadline, considered as the elapsed minutes between the IA and the completion time of the occurrence or operation.
DSF
The smoothing factor.
GROUP (authority group)
The name of the application authority group to be used for additional authority checking. You can specify up to 8 characters.
ODESCR ('owner description')
A free-format description of the application owner up to 24 characters and contained in single quotation marks.
OWNER (owner ID)
The name of the application owner. You can specify up to 16 characters for EBCDIC, or 7 characters for DBCS. The lowercase alphabetic characters, a–z, are translated to uppercase A–Z. If you use DBCS characters, you must enter the name as a quoted string started by a shift-out and ended by a shift-in. This keyword is required.
PRIORITY (priority | 5)
The scheduling priority of the application. Must be a single digit in the range 1–9. This keyword is valid only for an ADTYPE of A.

Examples

This example sets defaults for all following ADSTART statements:

ADSTART  ACTION(SETDEFAULT) OWNER(PAYGRP) PRIORITY(6)
     ODESCR('PAYROLL GROUP')

In this example, the batch loader will create application REORG7, which is an urgent application. It will be valid for inclusion in IBM Z Workload Scheduler plans on the first day of 1999:

ADSTART  ADID(REORG7) PRIORITY(9) DESCR('Reorganize IMS databases')
         ADVALFROM(990101) OWNER(XDARVOD)