Designing request control statements

Syntax rules

Statement syntax

Action statement

Each statement requests that an action is performed for a data set when it matches an associated data set name mask, and is detected for the first time. An action is performed once for each match, but the presence of a data set triggers the action for each specified data set name mask it matches.

Action statements have several optional operands to provide control over when Automation Server processing is to occur.

These operands can specify:

• time-of-day window
• day-of-week control string
• day-of-month window
• month-of-year control string

When all these constraints have been satisfied, the Automation Server searches the catalog for data sets with names that match the masks associated with an action.

Data set name mask statement

Each data set name mask statement associates the specified data set name mask with the preceding action statement. It is invalid for the HZAAPARM member to begin with a data set name mask statement. When a data set with a name matching the specified mask is first located, the action specified in the preceding action statement is triggered.

The data set name mask of NULLFILE is an exception. When a data set name mask with this exact value is processed by the Automation Server, a catalog search is not performed, but the associated action is triggered as if a new cataloged data set matching the mask has been located. Automation Server symbols for the data set name, and for the first qualifier of the data set name have values of the 8-byte string NULLFILE. Use the data set name mask of NULLFILE to trigger scheduled actions which do not depend on the creation of a particular data set.

action

FTP or JOB

template

Name of a member in the HZAACNTL file.

TIME

This operand is optional, and the default is TIME(0000-2400), which specifies no time-of-day constraint.

hhmm-hhmm

Specifies a time-of-day range. Each hhmm value is four contiguous decimal digits that specify a time-of-day using the 24-hour clock. The minimum value is 0000 and the maximum value is 2400; the last two digits must not exceed 59. The two values are separated by a hyphen. Zero or more additional blanks are also permitted. The first hhmm specifies the time-of-day window start, while the second specifies the time-of-day window end. The window includes times which are after the window start and before the window end. However, if the second hhmm value is lower than the first, the window includes times which are after the window start or before the window end.

WEEK

This operand is optional. The default is WEEK(YYYYYYY), which specifies that the action can be run on every day of the week.

wkflags

Specifies a single contiguous 7-byte string, consisting of the uppercase characters Y or N. Each Y or N corresponds to a day of the week depending on its position in the string; the first corresponding to Sunday, the last to Saturday. If the character corresponding to a day of the week is N, the action is not processed on that day.

NOTB

This operand is optional. The default NOTB(1) specifies that the monthly window starts on the first possible day of the month. NOTB means "not before".

d1

Specifies a one or two digit decimal number in the 1-31 range. This number denotes the first possible day of the month on which the action is permitted.

NOTA

This operand is optional. The default NOTA(31) specifies that the monthly window extends to the last day of the month. NOTA means "not after".

d2

Specifies a one or two digit decimal number in the 1-31 range. This number denotes the last possible day of the month on which the action is permitted.

MNTH

This operand is optional. The default value enables processing in every month of the year.

mthflags

Specifies a single contiguous 12-byte string, consisting of the uppercase characters Y or N. Each Y or N corresponds to a month of the year depending on its position in the string; the first corresponding to January, the last to December. If the character corresponding to a month of the year is N, the action is not processed in that month.

DSN

Data set name.

data-set-name-mask

Specifies a data set name mask pattern which does not exceed 44 characters in length, and is used by the Catalog Search Interface. The generic match mask for a single character is the percent sign. The generic match mask variable number of characters is the asterisk. A double asterisk can be used to match a variable number of data set name qualifiers. The catalog search is restricted to entry type A non-VSAM data sets and entry type H generation data sets.

Control statement examples

Example 1:

Files created by the Usage Monitor undergo two independent processes, both within the 8:00 p.m. to 11:30 p.m. window. They are processed by a job based on the JCL contained in member HZASJOB1, and are separately transferred to a z/OS® system using the FTP commands in member HZASFTP1. All members are pointed to by the HZAACNTL ddname.

* TRANSFER USAGE MONITOR FILES TO Z/OS SYSTEM
   JOB(HZASJOB1)  TIME(2000-2330)
   DSN(USER.OMU*.D*.T*)
   FTP(HZASFTP1)  TIME(2000-2330)
   DSN(USER.OMU*.D*.T*)                                   

Example 2:

Files created by the Usage Monitor are to be imported to the appropriate database.

* PERFORM USAGE MONITOR IMPORT
JOB(HZASUIMP)
DSN(USER.UMON.*.*) 

In this example HZASUIMP contains the necessary JCL to run Usage Import on a z/OS® system.

Note: The JCL can route the job to any connected NJE node, or specify an affinity to any system sharing the SPOOL. You do not need to run the job on the z/OS® system where the Automation Server is running. The template name, HZASUIMP in this example, does not need to match the job name submitted by the Automation Server action.

Example 3:

A job stream stored in member WED2MNTH is to be submitted unconditionally on the second Wednesday of every month.

* RUN MONTHLY JOBSTREAM ON THE SECOND WEDNESDAY OF EVERY MONTH 
 JOB ( WED2MNTH )   WEEK ( NNNYNNN )   NOTB ( 8 )   NOTA ( 14 )
 DSN ( NULLFILE )

Example 4:

A job stream stored in member NEWSHIFT is to run every day at 6:00 a.m, 2:00 p.m., and 10:00 p.m.

* RUN SHIFT TASK LIST REPORT AT THE START OF EACH SHIFT
 JOB(NEWSHIFT) TIME(0600-0630) 
 DSN(NULLFILE)
 JOB(NEWSHIFT) TIME(1400-1430)
 DSN(NULLFILE)
 JOB(NEWSHIFT) TIME(2200-2230)
 DSN(NULLFILE)

Automation Server symbol processing

Whenever an action is performed, the contents of the template member are written to an appropriate output file. Each 80-byte record is written unchanged, unless symbol substitution is required. If an ampersand character is present in a record from the template member, the system symbol substitution routine ASASYMBM is called to process the record before it is written. You can use more than one symbol in a record. If an ampersand character does not denote the start of a recognized symbol, then that part of the data remains unchanged. Symbols available for use in template members include all z/OS® system symbols and symbols defined locally by the Automation Server. Most Automation Server local symbols are derived from the catalog entry data set name which, when discovered, triggers the instance of the action.

System symbols supplied by the operating system, as well as the &SMF and &SYSLPAR symbols supplied by the Automation Server, are available for use in the HZAAPARM member. The &SYSLPAR symbol might resolve to a null string if the system is running in a virtual machine.

Example:

The data set triggering a JOB action is EXPUSER.IQ.ZIP. As a result, JCL DD statements referencing the data set in a template member can be represented as shown in this example:

//*------------------------------------------------------------***
//* Sample JCL demonstrating the use of Automation Server local***
//* symbols derived from the data set name.                    ***
//*------------------------------------------------------------***
//BR14      EXEC  PGM=IEFBR14
//DD1       DD    DSN=&DATASETNAME.,DISP=SHR
//DD2       DD    DSN=&QUAL1..&QUAL2..&QUAL3.,DISP=SHR     

Both JCL DD statements would be resolved by symbol substitution to:

DSN=EXPUSER.IQ.ZIP,DISP=SHR

This is the DSN= JCL statement output to the internal reader.

As symbol substitution is performed before the job is submitted, z/OS® system symbols that cannot be used in batch job JCL, can be used in the Automation Server templates. The symbols are resolved using the system executing the Automation Server, which may not be the system where the submitted job executes.