Automation Server Utility program

The Automation Server Utility program HZAAUTL can be used to extract and modify the contents of the VSAM ASCDS. It can be used as an ad hoc administrative tool or in production jobs to automate retry requirements.

When HZAAUTL is executed in jobs submitted by the Automation Server, the ASACTION and ASKEY symbols can be used to advantage. In particular, the ASKEY symbol can be used to refer to the job’s own ASCDS record, allowing it to be assigned the awaiting-retry status - usually in a step that is executed after it has been determined that the job has not been successful.

Here is an example of JCL used to execute the Automation Server Utility program: 
//ASUTIL  EXEC PGM=HZAAUTL
//STEPLIB  DD  DISP=SHR,DSN=hlq.SHZAMOD1
//ASCDS    DD  DISP=SHR,DSN=opshlq.ASCDS
//SYSPRINT DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//SYSIN    DD  *
  MAKEPEND &ASKEY.
/*

Files used by the Automation Server Utility

Several files must be available for use by the Automation Server Utility.

STEPLIB
Load library containing the product software. Not required if HCL Z Asset Optimizer is installed into the system linklist.
ASCDS
A VSAM KSDS control data set used by the Automation Server.
SYSPRINT
The output report file.
SYSOUT
Specifies the message report file for Language Environment.
SYSIN
The input file containing control statements.

Automation Server Utility control statements

Program HZAAUTL supports the following request types:

  • LISTALL - list records without regard to the progress status.
  • LISTDONE - list records pertaining to completed actions.
  • LISTPEND - list records pertaining to incomplete or pending actions.
  • LISTRC - list a specific record and issue a return code based on its status.
  • MAKEDONE - convert a pending action record to a completed action record.
  • MAKEPEND - convert a completed action record to a pending action record.
The following points apply when encoding requests in the SYSIN file:
  • Blank records are processed as comments.
  • The first non-blank data in a record must be either a request type from the above list or an asterisk.
  • Records where the first non-blank is an asterisk are processed as comments.
  • Requests must be completely encoded in the first 71 data bytes of the input record.
  • Request continuations across multiple records are not supported.
  • Request operands are deemed to start with the first non-blank character after the statement type.
  • Request operands must be separated from the request type by one or more blanks.
  • Request operands are deemed to end with the last non-blank character in the first 71 data bytes of the record.
  • Request operands may contain embedded blanks.
  • For all request types except LISTRC, the supplied operand will be treated as a generic key so that all records with keys that match up to the specified length can be processed by a single request.
  • For LISTRC requests, the operand will be extended with blanks if necessary to form a full-length key.
  • LISTRC requests require an operand.
  • To prevent likely data loss, MAKEDONE and MAKEPEND requests require an operand.
The following points apply when executing Automation Server Utility requests:
  • Valid generic requests do not set a non-zero completion code even if no matching records are found.
  • LISTRC requests result in the following completion codes:
    0
    the record matching the specified key has a completed status.
    4
    the record matching the specified key has pending status.
    8
    there is no record which matches the specified key
  • The HZAAUTL completion code is the highest result of all processed requests.
  • When an invalid request is recognized, HZAAUTL will immediately terminate with a completion code of 12 without processing or reporting subsequent requests.

Each request is processed in isolation in the order supplied by the SYSIN file. Each LIST request will cause the ASCDS to be opened for input, and each MAKE request will cause the ASCDS to be opened for update. The user running the HZAAUTL program will need READ security access to the ASCDS to execute LIST requests and will need UPDATE security access to the ASCDS to execute MAKE requests. The HZAAUTL program does not delete records from or add records to the ASCDS, so CONTROL access is not required.

The ASCDS is serialized by sysplex-wide ENQs using the HZAZNQAS queue name. A shared ENQ is used for LIST requests and an exclusive ENQ is used for MAKE requests. This serialization scheme ensures that requests do not interfere with other execution instances of HZAAUTL or with the cleanup cycle of the Automation Server. The ASCDS shareoptions of (4,3) ensure that the Automation Server references refreshed data when using keyed direct access.

Automation Server Utility report details

Requests that process ASCDS records will report the contents of those records in SYSPRINT output. LIST requests will issue a report line for each matching record. MAKE requests will issue two report lines for each matching record with the first showing the record contents that were read, and the second showing the contents that were written back to the ASCDS. Altered records will be marked with an UPDATED indicator to the right of the record listing in the report.

Column headings used to describe record contents are as follows:

Column Heading Description
ACTION ACTION or template member name.
DATA SET NAME Name of data set triggering this instance of the action.
ADD-DATE The date that this record was added to the ASCDS.
ADD-TM The time that this record was added to the ASCDS.
CAT-DATE The date that the subject data set was last found to be cataloged. Until the subject data set is processed, this is the date of the most recent attempt to process the data set.
PUT-TM The time of the most recent attempt to process the data set. This item is not updated after the subject data set has been processed.
MOV-DATE The date that the subject data set was successfully processed. This item is 8 zeros for pending entries awaiting retry.
MOV-TM The time that the subject data set was successfully processed. This item is initially blank. If this item is not blank when MOV-DATE is 8 zeros, then this record has been processed by a MAKEPEND request.
TRYCT The number of attempts to process the subject data set that have been made. If this item is zero for a record in completed status, the record was either marked complete by a MAKEDONE request or the record was constructed by the Scout Utility.

Local dates and times are used by the Automation Server when setting item values in ASCDS records. Dates are 8 numeric characters formed from a 4-digit year followed by a 2-digit month followed by a 2-digit day-of-month. Times are 6 numeric characters made from a 2-digit hour, a 2-digit minute-of-hour value and a 2-digit seconds-of-minute value, in that order. A blank is left between each display column in the report for readability, but in the ASCDS the data items abut. When forming a key to use as program input, make sure that any leading data set name part of the key starts immediately after the 8-byte action name. Embedded blanks are allowed in the key. For example, to list all records for data sets with names beginning with USER.DATA processed by the JOB1 and IQIMPORT actions, the following 2 input records could be used: 

LISTALL JOB1    USER.DATA
LISTALL IQIMPORTUSER.DATA

Unconditionally scheduled actions

The Automation Server can initiate actions based only on a scheduled time window without first performing a catalog search to find particular data set catalog entries. This is achieved by specifying NULLFILE in the relevant DSN statement in the HZAAPARM member of the PARMLIB library. To track whether such an action has been initiated or not across potential Automation Server stoppages, a record for each such schedule is maintained in the ASCDS. To distinguish between different schedules of the same action the scheduling filters are also encoded within the DATA SET NAME item of the relevant records. For example, if an action was scheduled to occur once between 07:30 and 08:29 every day and once between 20:00 and 20:39 every day from Monday to Friday, the DATA SET NAME values of the two records would be:

NULLFILE 0730_0829 YYYYYYY 01YYYYYYYYYYYY31
NULLFILE 2000_2039 NYYYYYN 01YYYYYYYYYYYY31

You can use MAKEPEND to cause reruns of such actions to occur, but a rerun will only be triggered if the Automation Server processes the updated record before the time window governing that record closes for that day.

Automation Server Utility request type descriptions

LISTALL
Lists all records that match the specified key part. If no key part was specified, then all records in the ASCDS will be listed.
LISTDONE
Lists all records that match the supplied key part with a non-zero MOV-DATE value. If no key part was specified, then all records in the ASCDS with a non-zero MOV-DATE value will be listed.
LISTPEND
Lists all records that match the supplied key part with a zero MOV-DATE value. If no key part was specified, then all records in the ASCDS with a zero MOV-DATE value will be listed.
LISTRC
Lists the record that matches the supplied key and will set a completion code based on its status. A key must be specified for the request to be valid. If the record’s MOV-DATE value is non-zero, a completion code of 0 will be set. If the record’s MOV-DATE value is zero, a completion code of 4 will be set. If no record matching the specified key was found, a completion code of 8 will be set.
MAKEDONE
Sets the MOV-DATE and MOV-TIME items to the current date and time in all records that match the specified key part. The record contents from before and after the change will be listed, with the after-change listing marked with an UPDATED indicator to the right of the record’s data in the report. To reduce the likelihood of accidental data loss, a key part must be specified for the request to be valid.
MAKEPEND
Sets the MOV-DATE to zeros in all records that match the specified key part. MOV-TIME will not be updated. The record contents from before and after the change will be listed, with the after-change listing marked with an UPDATED indicator to the right of the record’s data in the report. To reduce the likelihood of accidental data loss, a key part must be specified for the request to be valid.