Audit
This section describes the audit functional area of the high-level language exits. The 4-character exit name identifier is AUDT.
Select option 8 Audit from the HLL Exit Definition - Function Selection (CMNHLLMM) panel to define exits for the audit job submission and audit process:
CMNHLLMM HLL Exit Definition - Function Selection
Option ===>_________________________________________________________
1 All Full list
2 Build Component checkin, build, recompile, relink, delete
3 Package Create Initial create of a package
4 Package Update Subsequent update of package attributes
5 File Tailoring Define customized ISPF variables for file tailoring
6 Checkout Component Checkout from baseline/promotion
7 Promote/Demote Promotion and demotion of components
8 Audit Audit job submission and audit process
9 Freeze Package freeze and selective unfreeze/refreeze
A Approve/Reject Package approve and reject
R Revert/Backout Package revert and backout
S Specific Package syslib, Standard Language, Query etc.
U Scratch/Rename Utility functions
E ERO ERO functions
M Miscellaneous HLLX procedure name
Z Modify Issue Reload, Detach, or Attach modify commands
In response, the HLL Exit Definition (CMNHLLMN) panel is displayed. Here is how a sample panel might look:
CMNHLLMN HLL Exit Definition Row 1 to 6 of 9
Command ===>_______________________________________________ Scroll ===> CSR
Internal External + Active 1=LE Description +
Name Name 2=REXX Debug Userids +
-------------------------------------------------------------------------------
AUDT00AR NO 2 pre autoresolve job submission
Debug: NO 2
-------------------------------------------------------------------------------
AUDT01JB NO 2 post all audit job processing
Debug: NO 2
-------------------------------------------------------------------------------
AUDT00RC NO 2 pre audit job setting of package RC
Debug: NO 2
-------------------------------------------------------------------------------
AUDT00XM NO 2 pre audit job submission service
Debug: NO 2
-------------------------------------------------------------------------------
AUDT01XM NO 2 post audit job submission service
Debug: NO 2
-------------------------------------------------------------------------------
AUDT0001 NO 2 pre audit submission panel
Debug: NO 2
The audit functional area is a hybrid in that there are the usual panel user-interface exit points around the audit submission process; but, exit points can also be taken from within the audit batch process itself. These exit points allow the administrator to execute external processes from audit results or to alter the return code that is being set for each package. As the environment in which these two different classes of exits execute is quite different, the data supplied to them also varies.
The panels around which the audit exit points can be placed are:
| Panel ID | Description | Exit Name |
|---|---|---|
| CMNAUDIT | Audit submission main panel | AUDT0001/AUDT0101 |
| CMNAUDAP | Applications-in-scope selection panel | AUDT0002/AUDT0102 |
The audit job submission services exits are:
-
AUDT00XM - Audit job submission service pre-exit
-
AUDT01XM - Audit job submission service post-exit
The batch job audit exits are:
-
AUDT00AR - Exit that is taken prior to the submission of each autoresolve job.
-
AUDT00RC - Exit that is taken prior to setting the audit return code for each package.
-
AUDT01JB - Exit that is taken at the end of the audit job.
Sample Exits
Sample exits are provided in the CMNZMF.SAMPLES distribution library. These examples show how to list all the information incoming to these exits. Note that not all information is available to all exit points. The exits that occur early in the dialog will not have as much information as the exits that occur later in the dialog.
The audit exit examples are:
- HXCAUDT - COBOL example
- HXPAUDT - PL/I example
- HXRAUDT - REXX example
- HXRASCP - REXX example of how to set extra applications-in-scope
The majority of the fields are fixed length. (See the data interface below.) However, there are a couple of optional variable length sections. When filled in, these sections contain information about the applications-in-scope for this audit and the participating packages included in the audit.
The format for this variable length data in COBOL is:
***
* VARIABLE BLOCK POINTER
*
* EACH ENTRY IN A VARIABLE LENGTH BLOCK CONSISTS OF THE DATA
* FOLLOWED BY A POINTER TO THE NEXT ENTRY. WHEN THAT POINTER
* IS NULL THEN THERE ARE NO FURTHER ENTRIES IN THE BLOCK.
***
03 AUDTVB1L-PTR USAGE IS POINTER.
03 AUDTVB2L-PTR USAGE IS POINTER.
*
***
* APPLICATIONS IN SCOPE
***
01 AUDTVB1.
03 AUDTASCP PIC X(4).
* APPLICATION
03 PTR-NEXT-AUDTVB1 POINTER.
* POINTER TO NEXT ENTRY
***
* ELEGIBLE PARTICIPATING PACKAGES
***
01 AUDTVB2.
03 AUDTPPKG PIC X(10).
* PPKG NAME
03 AUDTPPLV PIC X(1).
* PPKG LEVEL
03 AUDTPPTY PIC X(1).
* PPKG TYPE
03 AUDTPPST PIC X(3).
* PPKG STATUS
03 AUDTPPDP PIC X(4).
* PPKG DEPARTMENT
03 AUDTPPIN PIC X(8).
* PPKG INSTALL DATE YYYYMMDD
03 PTR-NEXT-AUDTVB2 POINTER.
* POINTER TO NEXT ENTRY
The format for this variable length data in PL/I is:
/*** */
/* VARIABLE BLOCK POINTERS */
/* EACH POINTS TO A DIFFERENT VARIABLE LENGTH SECTION OF DATA. */
/* SECTIONS MAY BE MISSING DEPENDING ON FUNCTION AND PACKAGE */
/* TYPE. IF THEY ARE MISSING THEN THE POINTER WILL BE NULL. */
/* */
/* EACH ENTRY IN A VARIABLE LENGTH BLOCK CONSISTS OF THE DATA */
/* FOLLOWED BY A POINTER TO THE NEXT ENTRY. WHEN THAT POINTER */
/* IS NULL THEN THERE ARE NO FURTHER ENTRIES IN THE BLOCK. */
/*** */
2 AUDTVB1P PTR,
2 AUDTVB2P PTR;
/*** */
/* APPLICATIONS IN SCOPE LIST */
/*** */
DCL 1 AUDTVB1 BASED(WORKVB1P),
2 AUDTASCP CHAR(4), /*APPLICATION */
2 PTR_NEXT_AUDTVB1 PTR; /*PTR TO NEXT ENTRY */
/*** */
/* ELIGIBLE PARTICIPATING PACKAGE LIST */
/*** */
DCL 1 AUDTVB2 BASED(WORKVB2P),
2 AUDTPPKG CHAR(10), /*PPKG NAME */
2 AUDTPPLV CHAR(1), /*PPKG LEVEL */
2 AUDTPPTY CHAR(1), /*PPKG TYPE */
2 AUDTPPST CHAR(3), /*PPKG STATUS */
2 AUDTPPDP CHAR(4), /*PPKG DEPARTMENT */
2 AUDTPPIN CHAR(8), /*PPKG INSTALL DATE */
2 PTR_NEXT_AUDTVB2 PTR; /*PTR TO NEXT ENTRY */
The method for traversing this variable length list is the same as that used in other functions. The anchor pointers (AUDTVB1P and AUDTVB2P) point to the first in the chain of entries (null if no chain exists). Each entry contains a pointer to the next entry (null at end of chain).
REXX makes use of stem variables as usual with a variable number of similar data items.
The availability of the information in these variable sections is:
| Exit Name | Participating Package Info Available? | Applications-in Scope Info Available |
|---|---|---|
| AUDT0001 | NO (NO) | NO (NO) |
| AUDT0101 | NO (NO) | YES (YES) |
| AUDT0002 | NO (NO) | YES (YES) |
| AUDT0102 | NO (NO) | YES (YES) |
| AUDT00XM | NO (NO) | YES (YES) |
| AUDT01XM | NO (NO) | YES (NO) |
| AUDT00RC | YES (NO) | NO (NO) |
| AUDT01JB | YES (NO) | NO (NO) |
| AUDT00AR | YES (NO) | NO (NO) |
Data Interface
A single data structure is passed to all of these exits.
...
| LE-Language Variable Name | REXX Variable Name | Length | Purpose | Modifiable | Cursor Field No. |
|---|---|---|---|---|---|
| AUDTFUNC | function | 8 | Internal exit name | No | |
| AUDTDBUG | debugCall | 1 | Debug exit call (Y/N) | No | |
| AUDTORGN | callOrigin | 3 | ISPF=SPF XML Service=XML ZDD=ZDDZMF4 ECL=ECL | No | |
| AUDTZMFS | zmfSubs | 1 | ZMF subsystem character | No | |
| AUDTPDB2 | db2Subs | 4 | Default Db2 subsystem for this ZM | FNo | |
| AUDTUSER | userid | 8 | Userid for function calling this exit | No | |
| AUDTEXTN | externalName | 256 | External routine namedefined for this exi | tNo | |
| AUDTPKGN | packageId | 10 | The package being acted on | No | 001 |
| AUDTSCOP | auditScope | 1 | Display appls in scope Y/N | Yes | 002 |
| AUDTMODE | auditMode | 1 | Staging libs only Y/N | Yes | 003 |
| AUDTINCH | includeHistory | 1 | Include history Y/N | Yes | 004 |
| AUDTFMTR | printFormat | 1 | Format for printing Y/N | Yes | 005 |
| AUDTAPSP | auditAsSimple | 1 | Audit as simple Y/N | Yes | 006 |
| AUDTAPPP | auditAsPrimary | 1 | Audit as primary Y/N | Yes | 006 |
| AUDTAPDP | auditByDept | 1 | Audit by department Y/N | Yes | 006 |
| AUDTTRUT | restrictRcToTarget | 1 | Update target pkg RC only Y/N | Yes | 007 |
| AUDTTRCO | auditWithTrace | 1 | Audit trace Y/N | Yes | |
| AUDTXHDR | includeXapHeaders | 1 | Show XAP headers T/Y/N | Yes | 008 |
| AUDTSUPM | suppressNotify | 1 | Suppress batch messages Y/N | Yes | 009 |
| AUDTLOCK | lockPackage | 1 | Lock package for audit Y/N | Yes | 010 |
| AUDTMIXC | mixedCase | 1 | Name has mixed case? | Yes | 029 |
| AUDTRPLK | resetPackageLock | 1 | Reset package lock for audit Y/N | Yes Note #1 | 028 |
| AUDTAUTR | autoResolve | 1 | Autoresolve Y/N | Yes | 011 |
| AUDTAUTP | autoResolveParms | 54 | Autoresolve parameter dsn(member) | Yes | 012 |
| AUDTJOB1 | jobCard01 | 72 | Job card line #1 | Yes | 013 |
| AUDTJOB2 | jobCard02 | 72 | Job card line #2 | Yes | 014 |
| AUDTJOB3 | jobCard03 | 72 | Job card line #3 | Yes | 015 |
| AUDTJOB4 | jobCard04 | 72 | Job card line #4 | Yes | 016 |
| AUDTUV01-05 | userVariable01-05 | 8*5 | Set of five 8-byte package user variables | Yes | 018-022 |
| AUDTUV06-10 | userVariable06 | 72*5 | Set of five 72-byte package user variables | Yes | 023-027 |
| AUDTUVAR | userVariables | 1 | Display User variable panel (Y/N) | Yes | |
| AUDTOPRF | optsProfile | 8 | Used to select the ZDDOPTS profile for the display of user options for the ZMF Client Pack | Yes |
Supplied to AUDT00AR Only
| LE-Language Variable Name | REXX Variable Name | Length | Purpose | Modifiable | Cursor Field No. |
|---|---|---|---|---|---|
| AUDTARTN | arsTargetName | 256 | Target component name | No | |
| AUDTAREV | arsEvent | 2 | Autoresolve event | No | |
| AUDTARSY | arsSynchError | 2 | Caused by this synch error | No | |
| AUDTARSL | arsSourceLibtype | 3 | Source component libtype | No | |
| AUDTARSN | arsSourceName | 256 | Source component name | No | |
| AUDTARTP | arsTargetPkg | 10 | Target package for re-build | No | |
| AUDTARTL | arsTargetLibtype | 3 | Target libtype (used by relinks) | No | |
| AUDTARCP | arsCausalPkg | 10 | Package containing error causing this autoresolve action | No | |
| AUDTARCR | arsReplaceCsect | 16 | Csect to be replaced (relink) | No |
Supplied to AUDT00RC Only
| LE-Language Variable Name | REXX Variable Name | Length | Purpose | Modifiable | Cursor Field No. |
|---|---|---|---|---|---|
| AUDTRTCD | auditReturnCode | 2 | Package audit return code | Yes |
Supplied to AUDT01JB Only
| LE-Language Variable Name | REXX Variable Name | Length | Purpose | Modifiable | Cursor Field No. |
|---|---|---|---|---|---|
| AUDTRDSN | reportDsn | 44 | Dataset name allocated to CMNAD500 ddname AUDITRPT | No Note #2 | |
| AUDTRMBR | reportMember | 8 | Member name for same, or blank if dsname is sequential | No Note #2 |
Repeated Group #1 (Variable Length)
| LE-Language Variable Name | REXX Variable Name | Length | Purpose | Modifiable | Cursor Field No. |
|---|---|---|---|---|---|
| AUDTASCP | applInScope.n | 4 | Application | Note #3 |
Repeated Group #2 (Variable Length)
| LE-Language Variable Name | REXX Variable Name | Length | Purpose | Modifiable | Cursor Field No. |
|---|---|---|---|---|---|
| AUDTPPKG | ppkg.name.n | 10 | Participating package | No | |
| AUDTPPLV | ppkg.level.n | 1 | Level | No | |
| AUDTPPTY | ppkg.type.n | 1 | Type | No | |
| AUDTPPST | ppkg.status.n | 3 | Status | No | |
| AUDTPPDP | ppkg.dept.n | 4 | Department | No | |
| AUDTPPIN | ppkg.installDate.n | 8 | Install date | No |
Returned by Exit
| LE-Language Variable Name | REXX Variable Name | Length | Purpose | Modifiable | Cursor Field No. |
|---|---|---|---|---|---|
| AUDTGO | proceed | 3 | Set to 'NO' to stop the file tailoring process | Yes | |
| AUDTLOKD | dataLocked | 3 | Fields locked? (YES/NO) | Yes | |
| AUDTSHRT | shortMsg | 24 | Short error message text | Yes | |
| AUDTLONG | longMsg | 128 | Long error message text | Yes | |
| AUDTCURS | cursorField | 3 | For ISPF to place the cursor on return to the panel display. Field values are in this table | Yes | |
| AUDTCHNG | dataChanged | 3 | This field must be set to YES if you wish to return changed values to ZMF. | Yes |
-
Note #1
The ISPF client forces this value to be NO each time the panel is displayed via the )INIT section of the panel. This is done in order to avoid users accidentally unlocking packages.
-
Note #2
The dsname, and, if stored in a PDS/E, the member name of the file to which the AUDITRPT ddname in the CMNAD500 step is allocated will be passed in these fields.
-
Note #3
A list of applications selected as being in scope are supplied on the call to the exit. Where relevant, the exit may add to, or remove from, this list. If you change the number of entries, ensure that the pointer chains are set up correctly (LE), or ensure the new total number of entries is assigned to applInScope.0 (REXX). If you return an empty list, no updates are made to the applications-in-scope list used by the audit submission function.