Auditing a Package
The ChangeMan ZMF audit function validates the synchronization between changed components in a change package and any related components in:
- The staging and baseline libraries of those components.
- The staging and baseline libraries of components in other participating packages.
- The staging and baseline libraries of components in other applications.
Related components are tracked by ZMF in the impact analysis table. This table identifies relationships between source programs and copybooks, between source programs and load modules, and between statically link-edited load modules and the modules that call them. Many other relationships are also tracked. Audit ensures that the set of changed components in a package invoke modules that actually exist and are mutually consistent.
Refer to the ChangeMan ZMF User’s Guide for more information about the audit function.
Invoking Audit and Viewing the Audit Report
To invoke the Audit function
The Audit function for a package in the ChangeMan ZMF repository is invoked from the following workbench menus:
-
Serena perspective — In the Serena Explorer view, expand the ZMF Applications node, then expand the Packages node below it. Right-click on the name of the package to be audited. When the contextual menu displays, select the Audit menu option. See Working with ZMF Packages for more information.
-
Java perspective — In the Package Explorer view, right-click on a project that you have shared with a ZMF change package. When the contextual menu displays, open the Team submenu, then select the ZMF Package Audit option. See Project-Level ZMF Functions for more information.
A package must be in development (DEV) or frozen (FRZ) status to be eligible for audit.
To view the Audit report
The resulting audit report can be viewed in the workbench from the following menus:
-
Serena perspective — In the Serena Explorer view, find the node for the system or site where the relevant ZMF repository resides. Expand the z/OS Jobs node under that repository. Then expand the node for the job filter associated with your user ID and/or the application to which the audited package belongs. The audit job will be listed by job name and the output can be viewed in a workbench editor. See Working with z/OS Jobs for more information.
-
Remote System Explorer perspective (IDz only) — In the Remote Systems navigation view (at right in default layout), find the node for the z/OS system where the relevant ZMF repository resides. Expand the JES node under the system name, then expand the My Jobs node to see a list of job filters. Expand the node for the job filter associated with your user ID and/or the application to which the audited package belongs. The audit job will be listed by job name and the output can be viewed in a workbench editor. See z/OS Projects Perspective Overview for more information.
-
z/OS Projects perspective (IDz only) — In the Remote Systems navigation view (at left in default layout), find the node for the z/OS system where the relevant ZMF repository resides. Expand the JES node under the system name, then expand the My Jobs node to see a list of job filters. Expand the node for the job filter associated with your user ID and/or the application to which the audited package belongs. The audit job will be listed by job name and the output can be viewed in a workbench editor.See z/OS Projects Perspective Overview for more information.
Preparing and Submitting the Audit Job
To audit a ZMF change package, perform the following steps.
-
Invoke the Audit function from a package contextual menu in Serena Explorer or from the Team submenu of a a project contextual menu in Package Explorer.
-
When the Audit Package - Specify Audit Parameters wizard screen displays, select any desired General Options that apply to all package levels and types.
-
If auditing a participating package, also select any desired options from the Participating Packages section of the Specify Audit Parameters screen.
-
If this is a cross-application audit, also do the following:
-
Choose a report header format for cross-application audit reporting.
Choose which supplemental applications to include in the audit by clicking the Select Applications button on the Specify Audit Parameters screen. This will pop up the Select Applications wizard screen.
-
Edit the default JCL of the audit job card as needed on the Specify Audit Parameters screen.
-
If the Next button is enabled, user-defined variables have been specified as editable in the AUDIT member of ZDDOPTS. Click the Next button to display the Audit Package - Variables wizard screen and provide the required values.
-
Click the Finish button to submit the audit job.
For more information, see:
Audit Wizard Windows
The following wizard windows are displayed for the Audit function. Click on the window title to see detailed data entry instructions for that window.
| Window | Description |
|---|---|
| Audit Package - Specify Audit Parameters | Always displayed first. Allows you to select parameters that determine the focus and scope of the audit. |
| Select Applications | Displayed only if you click the Select Applications button on the Specify Audit Parameters wizard screen. Allows you to select additional applications to be included in the audit synchronization check. |
| Audit Package - Specify User Variables | Displayed only if user-defined package variables are enabled in the AUDIT member of ZDDOPTS. Allows you to update the values of these variables for the audit. |
Specify Audit Parameters
When you invoke the Audit function, the Audit Package - Specify Audit Parameters screen displays. Values default to those entered the last time you used this screen.
General options
The General Options section provides audit scope controls and reporting options that apply to all package types and levels. These are always enabled for selection.
Click on a checkbox to select the adjacent option. Click it again to deselect it. Any combination of options in the following table may be chosen.
| Option | Description |
|---|---|
| Audit staging libraries only | Optionally limits the scope of the audit to the package’s staging libraries only. |
| Check this box to audit only staging libraries for this package. | |
| Leave unchecked to perform a normal package audit that includes staging and baseline libraries. | |
| Auto resolve out-of-synchs | Certain out-of-synch conditions involving copybooks and load modules can generally be resolved automatically, without human review. These include ZMF SYNCH2, SYNCH4, SYNCH5, SYNCH7, SYNCH8, SYNCH9, SYNCH15, and SYNCH16 conditions. (Refer to the ChangeMan ZMF User’s Guide for details.) |
| Check this box to report the above out-of-synch conditions and automatically submit recompile/relink jobs to resolve them. | |
| Leave unchecked to report out-of-synch conditions and leave them unresolved pending human review | |
| Include history records | ZMF maintains a historical record of component changes. History records identify all packages in which a component was changed. |
| Check this box to extract component history for each staged component and include it in the audit report. | |
| Leave unchecked to omit component history information from the audit report. | |
| Format report for printing | By default, the audit report is formatted for online browsing. However, you can optionally format the audit report for printing. |
| Check this box to format the audit report for printing. Printer control characters are included to manage report appearance. | |
| Leave unchecked to browse the report online. | |
| Lock package | Locks all package components to prevent changes while the audit is running. Package lock is preferred on the final audit run prior to approval and installation. However, it is often not desirable to halt all work on a package during early audits. |
| Check this box to lock the package and prevent component changes during audit. | |
| Leave unchecked to allow component changes during audit. |
Participating packages
When auditing a participating package, the options in the Participating Packages section are enabled for selection on the Select Audit Parameters screen. These options are described in the following table. Some options are mutually incompatible.
| Option | Description |
|---|---|
| As a simple package | Limits the scope of the audit to the staging and baseline libraries that are normally audited for a simple package. The audit return code is updated for this package only. Useful for early auditing passes on participating packages. |
| Check the box to audit the current package only. | |
| Leave unchecked to perform a normal participating package audit. The audit includes all relationships between this package and the other packages with which it participates in a complex or super package. | |
| Note: If checked, no other Participating Packages options may be selected. | |
| As a primary package | Audits the participating package with reference to all other packages with which it participates in a complex or super package, but limits the scope of reporting to this package. Useful in early audit passes when a participating package contains the primary functional components of a complex or super package. |
| Check this box to audit the libraries of all participating packages in the same complex/super package as this one, but report out-of-sync conditions and update the audit return code only for the target participating package. | |
| Leave unchecked to perform a normal participating package audit. The audit includes all relationships between this package and the other packages with which it participates in a complex or super package. The audit return code will be updated for all packages sharing the same complex/super package as this one. | |
| Note:This option may NOT be checked if you choose to audit As a simple package or By department number. | |
| By department number | Limits the scope of the audit to only those participating packages that share the same department number as the target participating package. Useful for early audits when department codes are used to identify functions that must work together at all stages of development. |
| Check this box to restrict the audit to participating packages that share the same department number. | |
| Leave unchecked to perform a normal participating package audit. The audit includes all relationships between this package and the other packages with which it participates in a complex or super package. The audit return code will be updated for all packages sharing the same complex/super package as this one. | |
| Note: This option may NOT be checked if you choose to audit As a simple package or As a primary package. | |
| Update only this package return code | Reports the full set of out-of-synch conditions for all participating packages associated with the target package though a complex/super package, but updates the audit return code for the target participating package only. |
| Check this box to limit audit return code updates to the target participating package only. | |
| Leave unchecked to perform a normal participating package audit that updates the audit return code for all participating packages. | |
| Note: This option may NOT be checked if you choose to audit As a simple package. |
Cross application audit options
For cross-application audits, two audit options are available. The first turns on cross-application report headings in the audit report. The second allows you to bring up the Select Applications wizard screen and shows the selections currently in effect.
| Option or Field | Description |
|---|---|
| Cross-application headings | From the pull-down menu, select the desired option: |
| YES - Turn on cross-application headings and print them at the bottom of the audit report (default). This option uses the most report space. | |
| NO - Turn off cross-application headings to save space. | |
| TOP - Turn on cross-application headings but move them to the top of the audit report. | |
| Application scope | The Application Scope box displays the application directly associated with this package at creation. It also lists any supplemental applications you want to include in the audit. Supplemental applications are audited in addition to the applications already selected for audit. Those applications vary by package level and the audit options already selected, as follows: |
| Simple package — The application directly associated with this package at creation is the only application audited. | |
| Participating package — Varies with audit option. If Audit as simple package or Audit as primary package is selected, only the application directly associated with this package at creation is audited. Otherwise, all applications associated with all packages participating in the same complex or super package as this one are audited. | |
| Complex or super package — All applications associated with all packages participating in this complex or super package are audited. | |
| Select Applications | To add or remove supplemental applications to the audit, click the Select Applications button. This action brings up the Select Applications wizard screen. The supplemental applications checked on that screen are added to the application list in the Application Scope box. |
| See Select Applications for Audit for a description of the Select Applications wizard screen. |
Edit Job Card
The Job Card field at the bottom of the window displays the JCL JOB statement that will be used to run the audit job on the mainframe. Modify it as necessary.
By default, your TSO user ID is appended with an alphabetic character to create the job name. Each time this dialog displays, the last character of the default job name is incremented alphabetically.
If you change the displayed values, your changes will be saved and used as defaults the next time a job card is displayed.
The following syntax conventions apply:
- A maximum of four lines are allowed.
- Lines must begin with double slashes and may not exceed 71 characters in length.
- An asterisk in position three marks a comment.
- A blank in position three continues the JCL command from the previous line. The content of a continuation line must begin in positions 4 to 16. Parameters may not be broken across continuation lines.
Select Applications for Audit
The Select Applications screen enables you to add any supplemental applications you wish to those already included in the audit. This screen displays when you click the Select Applications button on the Audit Package - Specify Audit Parameters screen.
The applications listed are all those defined for the ChangeMan instance. However, they are filtered through your currently active application filter in ZMF for Eclipse. For more information about filters, see Filtering Views in Serena Explorer.
Adding supplemental applications to the audit
-
Click the checkboxes to add any desired supplemental applications to the audit.
-
Uncheck any previously selected applications that you wish to omit from the audit. You may deselect any application except the one in which the package is defined.
-
Click OK to save the information and return to the Audit Package wizard screen.
Audit Package - User Variables
The Audit Package - User Variables screen allows you to enter values for user-defined package variables at audit time. This screen is enabled only if user-defined variables have been specified as editable in the AUDIT member of the ZDDOPTS configuration library in ChangeMan ZMF. When the user variables screen is enabled, the Next button is active on the Audit Package - Specify Audit Parameters wizard screen.
Entering user variables for the audit
-
On the the Audit Package - Specify Audit Parameters wizard screen, click Next button to display the Audit Package - Variables wizard screen.
-
Enter or update the variables as needed for this audit, following the validation rules specified in the AUDIT member of ZDDOPTS.
-
Click Finish to submit the audit job for execution.