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 File Manager to terminate.

Figure 1. Syntax

Old data set

New data set

Comparison options

Notes:

¹ 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.

XMEMBERS

Provides a way to exclude from processing library members that would otherwise be selected using the MEMSTART, MEMEND, and MEMBER options.

xmem_filter: A member name filter identifying one or more members that are to be excluded from processing. A filter can be a member name pattern representing multiple members.
To specify a member name filter containing lowercase characters, use a character string in the format c'string'. Filter values can also be specified as hexadecimal strings in the format x'hex-digits'.

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 (%).

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.
ATTR: If the program language attributes for each CSECT are available, they are compared.

CSECTS

Provides a way to exclude or include CSECTs from comparison. The XCSECTS option identifies whether the filters are used to exclude or include CSECTs.

csect_filter: A CSECT name filter identifying one or more CSECTs to be either included or excluded from comparison. The wildcard characters * and % can be used to define a CSECT name pattern representing multiple CSECTs.

XCSECTS=NO

Use the CSECTS option to identify CSECTs to be included for comparison.

XCSECTS=YES

Use the CSECTS option to identify CSECTs to be excluded from comparison.

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
//*
//FMBAT PROC
//FMBAT EXEC PGM=FILEMGR
//STEPLIB   DD DSN=FMN.SFMNMOD1,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//  PEND
//*
//STPSSEX EXEC FMBAT
//SYSIN DD *
$$FILEM VER
$$FILEM CLM CMPLVL=CSECT,
$$FILEM LIST=DELTA,
$$FILEM WIDE=YES,
$$FILEM HILIGHT=YES,
$$FILEM DSNOLD=FMN.PROD1.LOAD(FMNLOAD),
$$FILEM DSNNEW=FMN.PROD2.LOAD(FMNLOAD),
$$FILEM LMODC=(SIZE,DATE,ATTR),
$$FILEM CSECTC=(SIZE,ADDR,DATE,ZAP)
$$FILEM EOJ

Note:

Load modules are compared at load module and CSECT level.
Load module size, date and time when load module was linked (bound), and link attributes are compared at load module level.
CSECT address, size, date of compile and IDR ZAP data are compared at CSECT level.