CLM (Compare Load Module)

Purpose
Use the CLM function to:
  • Perform a load module comparison. Load module and CSECT information from both the "Old" and "New" versions of the module is extracted and compared. By specifying compare criteria, you can see differences between specific properties of the load modules such as load module size, link date, CSECT name, and compilers used.
  • Produce a comparison report, showing information such as where insertions, deletions, or changes have occurred in the "New" load module. The content and structure of the report reflect the comparison options used.
Usage notes
Specify the way in which the comparison is performed, using:
  • The compare level
  • The compare criteria

Specify the type of output produced and the way in which the output is displayed, using:

  • The listing type
  • The listing options

You can use Data Set Compare (DSM) instead of CLM to compare load modules, by specifying SYNCH=LMOD.

Return codes
The default return codes from the CLM function have the following modified meanings:
0
The function completed successfully and the compare sets match.
1
The function completed successfully and the compare sets do not match.
2
One of the compare sets was empty, so no comparison was performed.
4
Both of the compare sets were empty, so no comparison was performed.
16
Data set or member in use.
16
Data set or member open error.
16
Data set or member not found.
16
Other input or output error occurred.
16
Member name required and not specified.
16
Insufficient storage available.
16
CLM abended.
16
Other serious error that stops processing occurred.
16
A severe error occurred, causing Z Data Tools to terminate.
Read syntax diagramSkip visual syntax diagram
Syntax

>>---CLM----+------------------+--+------------------+---------->
            '-| Old data set |-'  '-| New data set |-'   

>--+------------------------+----------------------------------><
   '-| Comparison options |-'   

Old data set

   .-INPUT=DDOLD---------------------------.   
|--+---------------------------------------+-------------------->
   +-INPUT=ddold---------------------------+   
   '-DSNOLD=dsnold-+---------------------+-'   
                   '-VOLSEROLD=volserold-'     

>--+-+----------------------+-+------------------+-+------------>
   | '-MEMSTART=startstring-' '-MEMEND=endstring-' |   
   '-MEMOLD=memold---------------------------------'   

                                 .-SKIPOLD=0-------.   
>--+--------------------------+--+-----------------+------------>
   |           .-,--------.   |  '-SKIPOLD=skipold-'   
   |           V          |   |                        
   '-MEMLIST=(---comp_mem-+-)-'                        

   .-CMPOLD=ALL----.   
>--+---------------+--------------------------------------------|
   '-CMPOLD=cmpold-'   

New data set

   .-DDNEW=DDNEW---------------------------------------------.   
|--+---------------------------------------------------------+-->
   +-DDNEW=ddnew---------------------------------------------+   
   '-DSNNEW=dsnnew-+---------------+-+---------------------+-'   
                   '-MEMNEW=memnew-' '-VOLSERNEW=volsernew-'     

   .-SKIPNEW=0-------.  .-CMPNEW=ALL----.   
>--+-----------------+--+---------------+-----------------------|
   '-SKIPNEW=skipnew-'  '-CMPNEW=cmpnew-'   

Comparison options

   .-CMPLVL=LMOD--.  .-DATEFORM=YYYYDDD-.   
|--+--------------+--+------------------+----------------------->
   '-CMPLVL=CSECT-'  '-DATEFORM=YYMMDD--'   

>--+----------------------------------------------+------------->
   |                .-,--------------.            |   
   |                V                |            |   
   '-LMODC=--+---+----+-SIZE-------+-+--+-------+-'   
             '-(-'    +-ADDRESS----+    |   (1) |     
                      +-+-LINKER-+-+    '-)-----'     
                      | '-BINDER-' |                  
                      +-+-DATE-+---+                  
                      | '-TIME-'   |                  
                      +-MODE-------+                  
                      +-+-AC---+---+                  
                      | '-AUTH-'   |                  
                      '-ATTR-------'                  

>--+-----------------------------------------------+------------>
   |                 .-,--------------.            |   
   |                 V                |            |   
   '-CSECTC=--+---+----+-SIZE-------+-+--+-------+-'   
              '-(-'    +-ADDRESS----+    |   (1) |     
                       +-COMPILER---+    '-)-----'     
                       +-DATE-------+                  
                       +-MODE-------+                  
                       +-+-IDRZAP-+-+                  
                       | '-ZAP----' |                  
                       +-TEXT-------+                  
                       '-COPT-------'                  

   .-LIST=SUMMARY--.                                     
>--+---------------+--+------------------------------+---------->
   +-LIST=DELTA----+  |           .-,------------.   |   
   +-LIST=MATCHING-+  |           V              |   |   
   +-LIST=LONG-----+  '-EXCLUDE=(---exclude_type-+-)-'   
   '-LIST=NONE-----'                                     

   .-NUMDIFF=ALL-----.  .-WIDE=NO--.  .-HILIGHT=NO--.   
>--+-----------------+--+----------+--+-------------+----------->
   '-NUMDIFF=numdiff-'  '-WIDE=YES-'  '-HILIGHT=YES-'   

   .-CHNGDFLD=NO--.   
>--+--------------+---------------------------------------------|
   '-CHNGDFLD=YES-'   

Notes:
  1. Provide closing bracket when opening bracket has been used.
Old data set specifications
The “Old” data set can be specified as follows:
DDOLD=ddold
Defines a reference to a DD or TSO ALLOC statement for the "Old" load library. The default is DDOLD.
DSNOLD=dsnold
Defines the name of the "Old" load library (PDS). If specified, any DD statements provided are not used. The name may include a member name in parenthesis. If the member is specified here, the associated MEMOLD parameter must be empty. To further describe the data set, use the following:
VOLSEROLD=volserold
The VOLUME serial number for a non-cataloged "Old" data set.
MEMOLD=memold
The name of a single member in a PDS, or a member name pattern representing one or more members in a load library. You may specify this parameter, or a member name in the DD statement for ddname, or specify a member or members in the MEMLIST parameter, or specify a range of member names with the MEMSTART and MEMEND keywords.

A member name pattern can consist of any characters that are valid in a member name and two special pattern characters: the asterisk (*) and the percent symbol (%).

An * represents any number of characters. As many asterisks as required can appear anywhere in a member name pattern. For example, if you enter a member name pattern of *d*, all members in the PDS whose name contains "d" are processed.

A % is a place-holding character that means a single character. As many percent symbols as necessary can appear anywhere in a member name pattern. For example, if you enter a member name pattern of %%%%, all members in the PDS with a 4-character name are processed.

MEMSTART=startstring
Is used to specify the start of a range of member names to be included in the compare. If MEMSTART is specified but MEMEND is omitted, all members of the PDS(E) from the startstring value onwards are included. startstring can have the same values, including wild cards, as for the memold parameter of the MEMOLD keyword.
MEMEND=endstring
Is used to specify the end of a range of member names to be included in the compare. If MEMEND is specified but MEMSTART is omitted, all members of the PDS(E) up to the endstring value onwards are included. endstring can have the same values, including wild cards, as for the memold parameter of the MEMOLD keyword.
MEMLIST
Provides a means of selecting members from a load library where no generic name pattern and no member name range has been specified. If the MEMLIST keyword is specified, only those members included in the MEMLIST arguments are compared with the corresponding members in the output data set. Members selected by the MEMBER=memold that are not included in the MEMLIST arguments are not compared.
comp_mem
The name of the member to be compared. Generic name masks are not allowed.
SKIPOLD=skipold
Number of logical records to be skipped from the beginning of the "Old" data set. The default is 0. Note that the number of logical records describing a load module is equal to the number of CSECTs plus 1 (one record describes the load module itself).
CMPOLD=cmpold
Number of records from the "Old" data set to be compared. The maximum number is 99 999 999. If you specify ALL or omit the parameter, all the remaining records are compared. Note that the number of logical records describing a load module is equal to the number of CSECTs plus 1 (one record describes the load module itself).
New data set specifications
The “New” data set can be specified as follows:
DDNEW=ddnew
Defines a reference to a DD or TSO ALLOC statement for the "New" load module library. The default is DDNEW.
DSNNEW=dsnnew
Defines the name of the "New" load module library (PDS). If specified, any DD statement provided are not used. The name can include a member name in parenthesis. If the member is specified here, the associated MEMNEW parameter must be empty. To further describe the data set, use:
VOLSERNEW=volsernew
The VOLUME serial number for a non-cataloged "New" data set.
MEMNEW=memnew
The name of a single member in a load library, or a member name pattern representing one or more members in the library. You can specify this parameter, or a member name in the DD statement for ddname.

A member name pattern can consist of any characters that are valid in a member name and two special pattern characters: the asterisk (*) and the percent symbol (%).

An * represents any number of characters. As many asterisks as required can appear anywhere in a member name pattern. For example, if you enter a member name pattern of *d*, all members in the library whose name contains "d" are processed.

A % is a place holding character that means a single character. As many percent symbols as necessary can appear anywhere in a member name pattern. For example, if you enter a member name pattern of %%%%, all members in the library with a 4-character name are processed.

Specification of MEMNEW (or a member in DSNNEW) depends on parameters used in MEMOLD (or member used in DSNOLD). If MEMOLD (member in DSNOLD) specifies one member, MEMNEW (member in DSNNEW) must also point to one member. If MEMOLD (member in DSNOLD) contains a member name pattern, specification of MEMNEW (member in DSNNEW) must use the same pattern or an "*".

SKIPNEW=skipnew
Number of logical records to be skipped from the beginning of the 'New' data set. The default is 0. Note that the number of logical records describing a load module is equal to the number of CSECTs plus 1 (one record describes the load module itself).
CMPNEW=cmpnew
Number of records from the "New" data set to be compared. The maximum number is 99 999 999. If you specify ALL or omit the parameter, all the remaining records are compared. Note that the number of logical records describing a load module is equal to the number of CSECTs plus 1 (one record describes the load module itself).
Compare options
CMPLVL
Determines the level of the load module comparison.
LMOD
Only information on the load module level is extracted and compared. CSECT information (and differences on CSECT level) are ignored. This results in a less detailed comparison.
CSECT
Information on both the load module and CSECT levels is extracted and compared. This results in a detailed comparison.
LMODC
Determines what information at the load module level is to be included in the compare. The criteria correspond with the load module properties; only those specified are compared and displayed. Each of the options below can be specified in any sequence, enclosed in parenthesis:
SIZE
The load module size is compared.
ADDRESS
The entry point address of the load module is compared.
LINKER | BINDER
The version of the linkage editor or the binder used to prepare the load module is compared. LINKER and BINDER are mutually exclusive.
DATE | TIME
The load module link (bind) date and time are compared. DATE and TIME are mutually exclusive.
MODE
The AMODE and RMODE of the load module are compared.
AC | AUTH
The load module authorization code is compared. AC and AUTH are mutually exclusive.
ATTR
The load module link (bind) attributes are compared.
CSECTC
Determines what information at the CSECT level is to be included in the compare. The criteria correspond with the CSECT properties; only those specified are compared and displayed. Each of the options below can be specified in any sequence, enclosed in parenthesis.
Note: If you specify CMPLVL=LMOD, this parameter is ignored.
SIZE
The CSECT size is compared.
ADDRESS
The address of the CSECT is compared.
COMPILER
The versions of the language compilers used to compile the CSECT are compared
DATE
The date of the CSECT compile is compared.
MODE
The AMODE and RMODE of the CSECT are compared.
IDRZAP | ZAP
The AMSPZAP IDR data is compared. The IDR ZAP data is an extension of the CSECT information, but is formatted into separate records. ISRZAP and ZAP are mutually exclusive.
TEXT
The CSECT content is compared. The CSECT content is an extension of the CSECT information, but is formatted into separate, 32-byte records and shown in "memory dump" format (hexadecimal and character).
Note: If you specify TEXT, the listing option is set to WIDE=YES to accommodate the dump format comparison.
COPT
The compiler options for each CSECT are compared if they can be determined.
LIST=SUMMARY
Summary listing.
LIST=DELTA
Delta listing.
LIST=MATCHING
Matching listing.
LIST=LONG
Long listing.
LIST=NONE
No listing.
Listing Options
The following option takes effect if the LIST=LONG parameter is specified:
EXCLUDE=exclude_type
The specified compare result types are not reported. exclude_type can have the following values:
INSERTED
Excludes inserted records from the report.
DELETED
Excludes deleted records from the report.
CHANGED
Excludes changed records from the report.
MATCHED
Excludes matched records from the report.

The following options take effect if the LIST keyword is not specified (that is, it defaults to SUMMARY) or is set to anything other than NONE:

NUMDIFF=numdiff
The number of differences after which the Compare Utility stops processing the data sets.
WIDE=NO
Narrow listing.
WIDE=YES
Wide listing.
HILIGHT=NO
No highlighting of changed fields.
HILIGHT=YES
Highlight changed fields.
CHNGDFLD=NO
Show all fields in the formatted comparison reports.
CHNGDFLD=YES
Show only changed fields in formatted comparison reports. This option has no effect if the 'Wide listing' (WIDE=YES) option has been selected
DATEFORM=YYYYDDD
Reported dates (link and compile dates) shown in YYYY.DDD format.
DATEFORM=YYMMDD
Reported dates (link and compile dates) shown in YY/MM/DD format.

A batch example: Comparison of two versions of a module.

//CLM JOB (ACCT),'NAME'
//* COMPARE LOAD MODULES
//*
//HFMBAT PROC
//HFMBAT EXEC PGM=HFMMAIN
//STEPLIB   DD DSN=HFM.SHFMMOD1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//  PEND
//*
//STPSSEX EXEC HFMBAT
//SYSIN DD *
$$FILEM VER
$$FILEM CLM CMPLVL=CSECT,
$$FILEM LIST=DELTA,
$$FILEM WIDE=YES,
$$FILEM HILIGHT=YES,
$$FILEM DSNOLD=HFM.PROD1.LOAD(HFMLOAD),
$$FILEM DSNNEW=HFM.PROD2.LOAD(HFMLOAD),
$$FILEM LMODC=(SIZE,DATE,ATTR),
$$FILEM CSECTC=(SIZE,ADDR,DATE,ZAP)
$$FILEM EOJ
Note:
  1. Load modules are compared at load module and CSECT level.
  2. Load module size, date and time when load module was linked (bound), and link attributes are compared at load module level.
  3. CSECT address, size, date of compile and IDR ZAP data are compared at CSECT level.