ChangeMan ZMF – IBM AD Validation Process

This feature is relevant only for ChangeMan ZMF users and has as prerequisites: IBM® AD Validation Server and IBM AD Connect for Mainframe.

Introduction

IBM AD Validation Server is installed on a Windows machine, and it requires to have installed ChangeMan ZMF on the Mainframe. However, the CHANGEMAN PACKAGE processing does not require IBM AD Validation Server to be installed since ChangeMan ZMF information can still be retrieved for analysis without IBM AD Validation Server.

IBM AD Validation Server is required only if ChangeMan ZMF is installed and you need to automatically validate the COBOL source code's conformance to a certain set of coding rules, when staging a package in ChangeMan ZMF. IBM AD Validation Server receives notifications from ChangeMan ZMF to validate the provided COBOL source files, when ChangeMan ZMF is configured to notify the IBM AD Mainframe Connect for Mainframe agents.

In the context of IBM AD Validation Server, validation is the process of assessing the degree to which a COBOL source file conforms to a set of configured coding-rules, and then generates a .pdf report and then sends back to ChangeMan ZMF a return code together with any resulting messages that describe the error for the COBOL source file that was validated. If the ChangeMan ZMF administrator requires this automatic verification before staging COBOL sources, to prevent packages from being staged, it represents also a delayed staging and an initial effort to configure ChangeMan ZMF, IBM AD Mainframe Connect for Mainframe agents, IBM AD Validation Server, and a java reporting component that checks the coding-rules conformance and generates the .pdf report.

Currently there are 161 coding rules in the CodingRuleIndex DB table, with a self-explanatory Description column that can help you decide whether the configuration effort and eventually the delayed staging suits your needs.

How it works

To have this feature up and running, IBM AD Validation Server must be installed and configured. For more information, see STEP 3. (Optional) Configuring IBM AD Validation Service.

If only downloading or synchronizing the mainframe members from ChangeMan ZMF is needed, IBM AD Validation Server is not required. IBM AD Validation Server provides coding rule enforcement via synchronization with ChangeMan ZMF when a member is staged. Before a source file is staged, you can automatically validate the source code to a certain set of coding rules.

The validation process works as follows.
  1. A member is compiled in ChangeMan ZMF (Cobol Program, Assembler Program for example).
  2. IBM AD Validation Service receives an indication that a certain program, part of a package within an application is compiled.
  3. IBM AD Validation Service triggers IBM AD Build Client in background mode for the following actions: Synchronize and Build selection.
  4. The Synchronization process is described as follows:

    A ChangeMan ZMF validation request, after it is processed by IBM AD Connect for Mainframe, contains the program name to be validated and all its include files. It contains also the PDS library names and their corresponding members of the staged ChangeMan ZMF package. The required mainframe members are downloaded from the PDS libraries in batches and contain multiple validation requests.

    In the synchronization process, the ProjectsMapping.txt configuration file is used. However, the projects that are present in this configuration file must have a valid z/OS® connection, with IP/hostname, and port number, that is attached and configured. These projects must be used exclusively for validation purposes. For more information about the ProjectsMapping.txt file, see Step 1, in STEP 3. (Optional) Configuring IBM AD Validation Service.

    Some projects can be used only for validation purposes and they are not supposed to be used in IBM AD Analyze Client analysis. It is recommended to add the project names in the projects.blacklist=<Project> parameter of the IBM® AD Batch Server's project.properties configuration file.

  5. The Build Selection process is described as follows:

    Build Selection process is optimized in the validation context, by allowing multiple instances of IBM AD Build Client to be launched in parallel so that the validation of large batches of files will be faster. The degree of parallelism is configurable in the ParallelValidationParameters.txt configuration file. The project names that are used exclusively in the validation context for Build Selection must be entered in ProjectsMappingParallelBuild.txt configuration file. Based on the load and the two configuration files, several programs are built on a certain instance of IBM AD Build Client.

    To build the programs that are added to the project, the include search paths needs to contain the paths of the include files that are detected in the previous step.

    Note:
    • On a certain IBM AD Build Client instance the programs are built sequentially, while IBM AD Build Client is launched in parallel on different projects.
    • Before the build starts, the project's repository is cleared so these projects cannot be used for analysis. Compiled data that is added in the repository is only needed to generate a validation report on the built programs.
    • The Build Selection projects do not have the requirements of the Validation projects, but it is required to have the virtual folders from FoldersMapping.txt configuration file, as the programs are added in the virtual folders based on their types.
  6. After the Build Selection process finishes, IBM AD Validation Service starts to generate Rules Based reports for the program that was previously staged. IBM AD Validation Service is configured to have different weights for the rules, each rule that is infringed has a value that is defined by the user in the IBM AD Validation Service configuration.
  7. Return of the max weight value to ChangeMan ZMF. After the report is generated and the maximum weight value is calculated, it is returned to the IBM AD Connect for Mainframe that further passes this information as follows:
    • To ChangeMan ZMF in user option 0401.
    • In the user’s terminal as a message (where user is the one that initially staged the Cobol Program in ChangeMan ZMF). The messages sent to the terminal can be configured in IBM AD Validation Server in the CompletionCodeVsMessage.txt configuration file (Refer to IBM AD Installation and Configuration Guide for details). In the situation when there’s a weight that is not configured in the previous configuration file, then the user sees in the terminal the message error in flow and IBM AD Validation Server logs must be investigated for further details.

    The enforcement part is developed by the ChangeMan ZMF admin. ChangeMan ZMF can be configured, based on the returned code, to prevent a package with programs that are violating the coding rules from being staged.

  8. Default max weight values and return codes that are currently supported by IBM AD Validation process and IBM AD Connect for Mainframe when you send the information to ChangeManIBM ZMF:
    • 0 - converted to VPAS and sent to ChangeMan ZMF in user option 0401.
    • 4 - converted to VWRG and sent to ChangeMan ZMF in user option 0401.
    • 8 – converted to VFAL and sent to ChangeMan ZMF in user option 0401.

    Any other values (except 99) – converted to NA and sent to ChangeMan ZMF in user option 0401.

    Return Code 99 – converted to DISS and sent to ChangeMan ZMF in user option 0401. This code is a special return code that is sent only for the situation when something went wrong in the Validation Process flow (such as synchronize failed, Build Selection that failed, or the report cannot be generated).