Skip to content

Package Validation Tasks

Package validation tasks identify dependencies among package components, verify the integrity of package components, or check for versioning differences and out-of-synch errors across components in different stages of development. Typical commands include list, check, and audit.

Serena XML supports the following package validation tasks:

  • List Source-to-Load Dependencies - CMPONENT PKG_LOD LIST

  • Check Component Integrity - PACKAGE CMPONENT INTEGRTY

  • Audit a Package - PACKAGE SERVICE AUDIT

List Source-to-Load Dependencies - CMPONENT PKG_LOD LIST

Source-to-load relationship (ILOD) records track dependencies between "like-source" components and any "like-load" or "like-other" components generated from a source component by compilation, DB2 precompile, or similar transformation process. These are the records returned by the Serena XML function listing source-to-load dependencies.

Not included in these source-to-load dependency records are "like-load" components staged to development, but not generated from a "like-source" component while in staging. Also omitted from the scope of this function are source-to-include relationships involving copybooks, macros, subroutines, skeletons, ISPF panels, or JCL procedures.

The Serena XML service/scope/message tags for a source-to-load dependency list are:

<service name="CMPONENT">
<scope name="PKG_LOD">
<message name="LIST">

These tags appear in both request and reply messages.

The service name is "cmponent", not "package", because XML Services calls the lowlevel component service in ChangeMan ZMF to perform most tasks associated with this function. The scope name, "pkg_lod", identifies this message as a package-level component service.

Note

The spelling of "cmponent" in the service name attribute is condensed to eight bytes for legacy compatibility on the mainframe.

CMPONENT PKG_LOD LIST — Requests

Serena XML supports the following options for source-to-load dependency lists:

  • All Dependencies in Package — Name the desired package in the <package> package tag. The <component> and <targetComponent> tags should be omitted from the request. The function returns all source-to-load dependencies involving "likeload" components generated during the life of the named package.

  • Load Dependencies for a Source Component — Name the desired package in the <package> tag and the desired "like-source" component in the <component> tag.

Include the library type for the like-source component in <componentType>. Omit the <targetComponent> tag from the request. The function lists all "like-load" components affiliated with the named like-source component.

  • Source Dependencies for a Load Component — Name the desired package in the <package> tag and the desired "like-load" component in the <targetComponent> tag. Include the library type for the like-load component in <targetComponentType>. Omit the <component> tag from the request. The function lists all "like-source" components affiliated with the named like-load component.

To further customize your request, specify a library type, modification date range, updater ID, or component status of interest. Choose component status options using appropriate yes/no flag tags.

Note

Yes/no flags for component status filtering take default values as a group. The default changes based on whether or not you enter explicit values in these tags, as follows:

  • If no status flag has an explicitly typed value, the default for all tags is "Y".

  • If any status flag has an explicitly typed value, the default for the remaining tags is "N".

The following example shows how you might code a request to list all "like-load" dependencies for a given "like-source" component in a package.

Example XML — CMPONENT PKG_LOD LIST Request

<?xml version="1.0"?>
<service name="CMPONET">
    <scope name="PKG_LOD">
        <message name="LIST">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>CISQ000030</package>
            </request>
        </message>
    </scope>
</service>

Data structure details for the tag appear in Exhibit 4-31.

Exhibit 4-31. CMPONENT PKG_LOD LIST <request>

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended to replace <package>. Use <package> instead of <applName> & <packageId>.
<component> Optional 0 - 1 String (256), variable Name of "like-source" component for which "like-load" dependencies are wanted. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<componentType> Optional 0 - 1 String (3), variable Library type of "like-source" component for which "like-load" dependencies are wanted.
NOTE: Omit to include all.
<filterActiveStatus> Optional 0 - 1 String (1)
Y = Include active components
N = Omit active components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterFrozenStatus> Optional 0 - 1 String (1)
Y = Include frozen components
N = Omit frozen components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<filterHfsDirectory> Optional 0 - 1 String (256), variable Name of HFS directory containing components to be listed, prefixed by path from installation root (that is, path as stored in baseline library). If present, only files in this directory are listed. If absent, all HFS files meeting other criteria are listed.
NOTE: Applies to z/OS Unix HFS components only. Irrelevant for native z/OS PDS library members.
<filterUnfrozenStatus> Optional 0 - 1 String (1)
Y = Include unfrozen components
N = Omit unfrozen components
NOTE: Part of component status flag group. If no tag in group has explicit value, default is Y. If any tag in group has explicit value, default is N.
<fromdateLastModified> Optional 0 -1 Date, yyyymmdd Start date in desired range of component modification dates.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<targetComponent> Optional 0 - 1 String (256), variable Name of "like-load" component for which "like-source" dependencies are wanted. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
NOTE: Omit to include all.
<targetComponentType> Optional 0 - 1 String (3), variable Library type of "like-load" component.
<toDateLastModified> Optional 0 -1 Date, yyyymmdd End date in desired range of component modification dates.
<updater> Optional 0 -1 String (8), variable TSO user ID of last person to update component.

...

CMPONENT PKG_LOD LIST — Replies

The Serena XML source-to-load dependency list returns zero to many <result> data structures, each of which lists one source-to-load relationship for a package. Status information for the "like-source" component in the pair is also returned. If no compilations, submissions for JCL install job build, or other transformation processes have occurred for components in the package, no <result> tags are returned.

The reply message returns a standard <response> data structure to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. Because the <response> tag follows the last <result> tag, it also serves as an end-of-list marker.

The example below shows how a reply for this function might appear in Serena XML. Data structure details for the <result> tag appear in Exhibit 4-32.

...

Example XML — CMPONENT PKG_LOD LIST Reply

<?xml version="1.0"?>
<service name="CMPONENT">
    <scope name="PKG_LOD">
        <message name="LIST">
            <result>
                <package>CISQ000030</package>
                <applName>CISQ</applName>
                <packageId>000030</packageId>
                <component>APPSTATS</component>
                <componentType>SRS</componentType>
                <targetComponent>APPSTATS</targetComponent> <targetComponentType>DBR</targetComponentType>
                <updater>USER24</updater>
                <dateLastModified>20081126</dateLastModified>
                <timeLastModified>094711</timeLastModified>
                <setssi>5BFD1269</setssi>
                <componentStatus>4</componentStatus>
                <rebuildFromBaseline>N</rebuildFromBaseline>
            </result>
            <result>
                <package>CISQ000030</package>
                <applName>CISQ</applName>
                <packageId>000030</packageId>
                <component>APPSTATS</component>
                <componentType>SRS</componentType>
                <targetComponent>APPSTATS</targetComponent>
                <targetComponentType>LOS</targetComponentType>
                <updater>USER24</updater>
                <dateLastModified>20081126</dateLastModified>
                <timeLastModified>094711</timeLastModified>
                <setssi>5BFD1269</setssi>
                <componentStatus>4</componentStatus>
                <rebuildFromBaseline>N</rebuildFromBaseline>
            </result> 
            .
            .
            .
            <response>
                <statusMessage>CMN8700I - LIST service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode>
            </response>
        </message>
    </scope>
</service>
...

Exhibit 4-32. CMPONENT PKG_LOD LIST <result>

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), fixed ZMF application name. Same as first 4 bytes of package name.
<component> Optional 0 - 1 String (256), variable Name of "like-source" component. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<componentStatus> Optional 0 - 1 String (1) Code for original component status. Values: = Active = Approved = Checked Out = Demoted = Frozen = Inactive = Incomplete = Promoted = Refrozen = Rejected = Remote Promoted = Submitted = Unfrozen
<componentType> Optional 0 - 1 String (3), variable Library type of "like-source" component.
<dateLastModified> Optional 0 - 1 Date, yyyymmdd Date source component was last modified.
<hashToken> Optional 0 - 1 String (16), variable Hash token for HFS.
<package> Optional 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), fixed ZMF package ID number. Same as last 6 bytes of package name.
<rebuildFromBaseline> Optional 0 - 1 String (1)
Y = Recompile/relink from baseline, not package component
N = Recompile/relink from package component, not baseline
<setssi> Optional 0 - 1 String (8), fixed Staged component SETSSI date (seconds since 1/1/1960).
<targetComponent> Optional 0 - 1 String (256), variable Name of "like-load" component generated from "like-source" component.
<targetComponentType> Optional 0 - 1 String (3), variable Library type of "like-load" component.
<timeLastModified> Optional 0 - 1 Time, hhmmss Time source component was last modified, 24-hr format.
<updater> Optional 0 - 1 String (8), variable TSO user ID of last person to update source component.

...

Check Component Integrity - PACKAGE CMPONENT INTEGRTY

The package-level component integrity check verifies that all package component records in the package master database have corresponding physical components in the staging libraries, and vice versa. A component integrity check can be made only against simple or participating packages.

Tip

To verify that all independently queued batch jobs have completed in ChangeMan ZMF before a dependent job step executes, use the Serena XML component integrity check.

The Serena XML service/scope/message tags for a package-level component integrity check message are:

<service name="PACKAGE"> 
<scope name="CMPONENT">
<message name="INTEGRTY">

These tags appear in both request and reply messages.

PACKAGE CMPONENT INTEGRTY Requests

The following example shows how you might code a Serena XML request for a package-level component integrity check.

Example XML — PACKAGE CMPONENT INTEGRTY Request

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="CMPONENT">
        <message name="INTEGRTY">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>IMSQ000012</package>
            </request>
        </message>
    </scope>
</service>

Data structure details for the package cmponent integrity check tag appear in Exhibit 4-33.

Exhibit 4-33. PACKAGE CMPONENT INTEGRTY <request>

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 - 1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended to replace <package>. Use <package> instead of <applName> & <packageId>.
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<processLstStagingLibs> Optional 0 - 1 String (1) Option to include listings (library type LST) in check. Values:
Y = Yes, include listing libraries
N = No, omit listing libraries

...

PACKAGE CMPONENT INTEGRTY Replies

The Serena XML reply message to a package-level request to check component integrity returns zero to many <result> tags. Each <result> tag contains information about a package component that failed the component integrity check. If all components pass the check, no <result> tag is returned.

A standard <response> data structure always follows the <result> tags, if any, to indicate the overall success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.

An example of a Serena XML reply to a component integrity check reply message follows. In this example, multiple package components fail the integrity check. No other errors occur. Data structure details for the component integrity check <result> appear in Exhibit 4-34.

Note that the <component> subtag of the component integrity check <result> tag represents a simple data element containing the component name only. It differs from the <component> tag used in the selective package promote and demote messages, in selective unfreeze and refreeze messages, and others where <component> is a complex data element containing subtags of its own. Serena XML distinguishes the two by service/scope/message context.

Example XML — PACKAGE CMPONENT INTEGRTY Reply

<?xml version="1.0"?>
<service name="PACKAGE">
    <scope name="CMPONENT">
        <message name="INTEGRTY">  
            <response>
                <statusMessage>CMN8700I - Package Integrity service completed</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>8700</statusReasonCode> 
                </response>
            </message>  
        </scope>
</service>

...

Exhibit 4-34. PACKAGE CMPONENT INTEGRTY <result>

Subtag Use Occurs Data Type & Length Values & Dependencies
<componentName> Optional 0 - 1 String (256), variable ZMF component name. If component is PDS member, this is member name (max 8 bytes, no qualifiers). If component is HFS file, this is Unix-style long file name, optionally prefixed by path from installation root.
<componentType> Optional 0 - 1 String (3), variable Must be valid ZMF library type.
<message> Optional 0 - 1 String (255), variable Component integrity error message for named component.

Audit a Package - PACKAGE SERVICE AUDIT

The package audit function checks for out-of-synch conditions in package components. The package(s) to be audited must be in development status, with all components at promotion level 00, prior to running the audit request. The outcome of the audit is an audit report, which the package audit function spools to your system’s output utility (e.g., Spool Display and Search Facility, or SDSF) for later interactive access and printing.

The Serena XML service/scope/message tags for a package audit message are:

<service name="PACKAGE">
<scope name="SERVICE">
<message name="AUDIT">

These tags appear in both requests and replies.

PACKAGE SERVICE AUDIT Requests

Serena XML supports package audit options of narrow to broad scope. A set of yes/no audit flag tags lets you tailor the scope of your audit to the following:

  • Staging Libraries Only, No Cross-Package Dependencies — Performs an audit against staging libraries but not baseline libraries for a simple package. To select this option, set the <auditLite> tag flag to "Y".

  • Staging and Baseline Libraries, No Cross-Package Dependencies — Performs an audit against both staging and baseline libraries for a simple package. To select this option, set the <auditLite> tag flag to "N".

  • Staging Libraries Only, Check Cross-Package Dependencies — Performs an audit against staging libraries for non-baselined participating packages in a complex package. To select this option for a participating package, set the <auditPartAsPrimary/> tag flag to "Y". To select this option for a complex package, set the <auditLite> tag flag to "Y".

  • Staging and Baseline Libraries, Check Cross-Package Dependencies — Performs an audit against staging libraries and baseline libraries for all participating packages in a complex package. To select this option, enter the name of the complex package in the <package/> tag and set the <auditLite> tag flag to "N".

  • Cross-Application Audit — Performs an audit against both staging and baseline libraries for all applications identified in the request message. Cross-application dependencies are audited across applications defined in the package master for complex packages and participating packages not otherwise excluded from this option. You can also request that cross-application dependencies be checked for the applications you name. To do this, list the desired applications using the repeating <scopeAppl/> tag and provide the number of those applications in <listCount/>.

The following example shows how you might code a package audit request using Serena XML. Data structure details for the package audit tag appear in Exhibit 4-35.

Example XML — PACKAGE SERVICE AUDIT Request

<?xml version="1.0"?> 
<service name="PACKAGE"> 
    <scope name="SERVICE">
        <message name="AUDIT">
            <header>
                <subsys>8</subsys>
                <product>CMN</product>
            </header>
            <request>
                <package>ACTP000013</package>
                <jobCards01>//XMLX126 JOB (AMW,000),'DEFINE UCAT',MSGCLASS=Y,</jobCards01>
                <jobCards02>// TIME=(,10),NOTIFY=USER24</jobCards02>
            </request>
        </message>
    </scope>
</service>

Exhibit 4-35. PACKAGE SERVICE AUDIT <request> Data Structure

Subtag Use Occurs Data Type & Length Values & Dependencies
<applName> Optional 0 -1 String (4), variable ZMF application name. Same as first 4 bytes of package name.
NOTE: OK to omit trailing blanks.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<auditAutoParms> Optional 0 - 1 String (44), variable The name of a data set containing the auto resolve parameters. See the ChangeMan ZMF User’s Guide, Using Auto Resolve.
<auditAutoResolve> Optional 0 - 1 String (1) Option to automatically resolve out-of-synch conditions. Values:
Y = Yes, turn on auto-resolve
N = No, don’t auto-resolve errors
<auditFormatReport> Optional 0 - 1 String (1) Option to include printer control characters in output file. Values:
Y = Yes, include control chars
N = No, don’t use control chars
<auditIncludeHistory> Optional 0 - 1 String (1) Option to include component history in audit report. Values:
Y = Yes, include history
N = No, omit history
<auditLite> Optional 0 - 1 String (1) Option to omit baseline libraries from audit. Values:
Y = Yes, omit baseline libraries
N = No, don’t omit baseline libs
<auditPartAsPrimary> Optional 0 - 1 String (1) Option to include cross-package dependencies for all but previously installed packages from audit of participating package. Values:
Y = Yes, audit as primary pkg
N = No, don’t change audit scope
<auditPartAsSimple> Optional 0 - 1 String (1) Option to omit cross-package dependencies from audit of a participating package & follow rules for simple packages concerning baseline libraries. Values:
Y = Yes, audit as simple package
N = No, don’t change audit scope
<auditPartByDept> Optional 0 - 1 String (1) Option to limit cross-package dependency check to department of target package. Values:
Y = Yes, audit within department
N = No, don’t change audit scope
<auditRCUpdateRestrictToTarget> Optional 0 - 1 String (1) Option for cross-package & crossapplication audits to update audit return code only in the package named in <package> tag, rather than all packages audited. Values:
Y = Yes, restrict audit return code
N = No, don’t restrict return code
<auditTraceOption> Optional 0 - 1 String (1) Option to turn on trace option for audit function. Values:
Y = Yes, turn on trace option
N = No, don’t trace audit job
<includeXAPheaders> Optional 0 - 1 String (1) Include cross application common baseline headers:
Y = Yes
N = No
<jobCard01> Optional 0 - 1 String (72), fixed length First of up to 4 JCL statements needed to execute the audit in batch mode.
<jobCard02> Optional 0 - 1 String (72), fixed length Second of up to 4 JCL statements needed to execute the audit in batch mode.
<jobCard03> Optional 0 - 1 String (72), fixed length Third of up to 4 JCL statements needed to execute the audit in batch mode.
<jobCard04> Optional 0 - 1 String (72), fixed length Fourth of up to 4 JCL statements needed to execute the audit in batch mode.
<listCount> Optional 0 - 1 Integer (3), variable Count of <scopeAppl> tags to include in cross-application audit.
NOTE: Required if value is Y in <auditCrossApplication> tag.
<lockPackage> Optional 0 - 1 String (1) Lock package during audit.:
Y = Yes
N = No
<package> Required 1 String (10), fixed Fixed-format ZMF package name.
NOTE: May be simple, complex, or participating.
<packageId> Optional 0 - 1 Integer (6), variable ZMF package ID number. Same as last 6 bytes of package name.
NOTE: Leading zeroes required.
NOTE: Not recommended. Use <package> instead of <applName> & <packageId>.
<scopeAppl> Optional 0 - ∞ Complex Name of application to include in scope of cross-application audit. Repeatable to accommodate multiple applications.
NOTE: Required if value is Y in <auditCrossApplication> tag.
NOTE: If used, <listCount> tag also required.
<suppressNotify> Optional 0 - 1 String (1) Suppress Batch Messages:
Y = Yes
N = No
<userVariable01> . . . <userVariable05> Optional 0 - 1 each String (8), variable Up to five user-defined variables of 8 bytes each, used to pass parameters to JCL interpreter.
<userVariable06> . . . <userVariable10> Optional 0 - 1 each String (72), variable Up to five user-defined variables of 72 bytes each, used to pass parameters to JCL interpreter.

...

Tip

Tags: <userVariable01> to <userVariable10>: See topic "Custom V01-V10 Variables" in the ChangeMan ZMF Customization Guide.

PACKAGE SERVICE AUDIT Replies

Because the ZMF audit report is spooled to SDSF, Serena XML replies to a package audit request do not return a <result> data structure. They do, however, return a standard <response> data structure to indicate the success or failure of the audit request.

Example XML — PACKAGE SERVICE AUDIT Reply

<?xml version="1.0"?> 
<service name="PACKAGE">
    <scope name="SERVICE">
        <message name="AUDIT">
            <response>
                <statusMessage>CMN2600I - The job to audit this package has been submitted.</statusMessage>
                <statusReturnCode>00</statusReturnCode>
                <statusReasonCode>2600</statusReasonCode>
            </response>
        </message>
    </scope>
</service>

A job with output similar to the following is submitted:

//* JOB TO AUDIT PACKAGE ACTP000013
                                                Legend and Summary Report
The local level of audit chosen at this point;      0
    0 - Audit is recommended but entirely optional
Out-of-synch messages (hint - search for "!" marks)
    DUPLIC! (Staging duplicates baseline)        ===> 9
    SYNCH0! (Not in scope of audit or unknown)   ===> 1
    SYNCH1! (ISPF statistics not available)      ===> 0
    SYNCH2! (Compile/designated proc differ)     ===> 0
    SYNCH3! (Unparsable load module)             ===> 0
    SYNCH4! (CPY problem in staging)             ===> 0
    SYNCH5! (CPY high-date problem in baseline)  ===> 17
    SYNCH6! (Activity file not checked out)      ===> 0
    SYNCH7! (Called subroutine in staging)       ===> 0
    SYNCH8! (Called subroutine in baseline)      ===> 0
    SYNCH9! (Source and load discrepancy)        ===> 0
    SYNCH10! (Version regression problem)        ===> 0
    SYNCH11! (Component hash discrepancy)        ===> 0
    SYNCH12! (Orphan module in staging)          ===> 0
    SYNCH13! (Baseline/staging discrepancy)      ===> 0
    SYNCH14! (Components not in active status)   ===> 0
    SYNCH15! (Source to relationship problem)    ===> 0
    SYNCH16! (CPY low-date problem in baseline)  ===> 0
    SYNCH17! (CPY deleted problem in staging)    ===> 0
    SYNCH18! (LOD deleted problem in staging)    ===> 0

Highest return code encountered                  ===> 8
CMN2678I - AUDIT RETURN CODE NOT UPDATED.

...

Serena XML audit return codes are the same as those for audits requested through the ISPF interface. Successful audits — i.e. those that find no out-of-synch conditions — have a return code of 00. Unsuccessful audit requests have a return code of 04 or higher.