CMNWRITE - Copy And Include Management

CMNWRITE is executed as a step in a ChangeMan ZMF stage (compile or build) job. It parses source code and selectively expands copybooks into the source. The expanded source is written to the file at DD statement SYSOFILE, which is then used as input into a precompiler or compiler.

CMNWRITE attempts to resolve copybook names by searching PDS(E) libraries concatenated at the SYSLIB DD statement. After searching SYSLIB libraries, CMNWRITE searches any CA Panvalet and CA Librarian libraries that are named in SYSIN keyword control statements.

CMNWRITE can process copybooks nested up to 99 levels.

For copybooks that are resolved, including nested copybooks, CMNWRITE writes source-to-copy relationship records to the package master. Audit uses these records to find SYNCH5, SYNCH15, and SYNCH16 errors in package components. These records are also used to create relationship records used by impact analysis.

Caution

If you omit CMNWRITE from a custom build process for like-source

components that use copybooks, audit will be unable to detect some out-of-synch conditions.

If a copybook name is successfully resolved, but in-line expansion is either not required or not possible, CMNWRITE writes the copybook to a separate PDS at DD statement SYSUT3, which is included at the bottom of the SYSLIB concatenation in the subsequent precompile or compile step.

If a copybook is expanded in the source, CMNWRITE can generate comment box at the top of the expanded code that displays its level of nesting and member information from the library where it was found.

CMNWRITE Input

Execution parameters in the program PARM statement
Keyword parameters in the SYSIN DD statement
Source code in a PDS or sequential file
PDS libraries to be searched for copybooks
CA Panvalet libraries to be searched for copybooks
CA Librarian files to be searched for copybooks

Output

Source code with copybooks expanded in-line
Source code comments for every expanded copybook showing ISPF statistics for the copybook, the level of nesting under the source member, and the number of lines in the copybook
A PDS library containing copybooks that have not been expanded in-line
SYSPRINT output displaying the library search order and a report of copybooks detected

Sample JCL

This is a fragment from a stage job submitted by ChangeMan ZMF. This JCL was created by file tailoring skeleton CMN$$WRT.

//*)IM CMN$$WRT
//WRITE  EXEC   PGM=CMNWRITE,  *** PARSE/EXPAND COMPONENT CTST
//              COND=(4,LT),
//              PARM=('SUBSYS=6,USER=USER015',
//              '')
//*)IM CMN$$SPR
//SER#PARM  DD DISP=SHR,DSN=CMNTP.SER814.C6.TCPIPORT
//SYSPRINT  DD DISP=(,PASS),DSN=&&LIST10W1,
//          UNIT=SYSDA,SPACE=(CYL,(5,5),RLSE)
//*)IM CMN$$SYC
//SYSLIB    DD DISP=SHR,DSN=CMNTP.S6.ACTP.STG6.#000081.CPY
//          DD DISP=SHR,DSN=CMNTP.S6.V810.BASE.ACTP.CPY
//          DD DISP=SHR,DSN=CMNTP.S6.V810.BASE.ACTP.CP2
//SYSIFILE  DD DISP=(OLD,PASS),DSN=&&SOURCE(CTST)
//SYSOFILE  DD DISP=(,PASS),DSN=&&WRITE,
//          UNIT=SYSDA,SPACE=(CYL,(1,1)),
//          DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
//SYSUT3    DD DISP=(,PASS),DSN=&&CPYLIB,
//          UNIT=SYSDA,SPACE=(CYL,(1,1,20),RLSE),
//          DCB=(DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=0)
//ABNLIGNR  DD DUMMY
//SYSUDUMP  DD SYSOUT=*
//SYSIN     DD *
TYP=CPY/CMNTP.S6.ACTP.STG6.#000081.CPY
TYP=CPY/CMNTP.S6.V810.BASE.ACTP.CPY
TYP=CP2/CMNTP.S6.V810.BASE.ACTP.CP2
CMP=CTST.SRC
LNG=COBOL2
PKG=ACTP000081
//*)IM CMN$$CND
//*)IM CMN$$CO2

...

DD Statements

This table describes DD statements for CMNWRITE.

DDNAME	I/O	Purpose
SER#PARM	Input	PDS(E) library containing information used to connect to the ChangeMan ZMF server through TCP/IP. This library must contain a member named #SERx, where x is the one-character subsystem ID of the ChangeMan ZMF instance.
SYSIFILE	Input	File containing source code. This DD statement must point to a sequential file or a PDS(E) member.
SYSIN	Input	File containing 80-byte keyword control records.
SYSLIB	Input	PDS libraries containing copybook members. The library concatenation for this DD statement is usually built by skeleton CMN$$SYC.
SYSOFILE	Output	Sequential file containing source code with expanded copybooks. The file written by this DD statement is passed to precompile or compile steps.
SYSPRINT	Output	Report file that displays information from the execution of CMNWRITE: See Reporting.
SYSUT3	Output	PDS containing copybook members that could be detected in the input source code but were not expanded in the source written to SYSOFILE.

...

CA Panvalet and CA Librarian libraries are specified in SYSIN keyword control statements and are dynamically allocated. See SYSIN Parameters. These libraries are searched after the SYSLIB concatenation is exhausted.

PARM Options

The PARM parameter is required in the EXEC statement for CMNWRITE. This table describes CMNWRITE options that are input through the PARM parameter.

Parameter	Use	Description
SUBSYS=	Required	Specifies the one-character subsystem ID of the ChangeMan ZMF instance.
USER=	Required	Userid of the person or entity that executes CMNWRITE. A userid is required for CMNWRITE to connect to ChangeMan ZMF server programs. This userid is not used to determine security authorization.
EXPAND	Optional	Indicates whether or not to expand copybooks in source code output to SYSOFILE. EXPAND Expand detected copybooks in output source and write unexpanded copybooks to SYSUT3. This is the default value. NOEXPAND Do not expand detected copybooks in output source and write all detected copybooks to SYSUT3.

...

SYSIN Parameters

CMNWRITE keyword parameters are input to CMNWRITE through the SYSIN ddname.

Keyword parameters must start in positions 1-60.
A SYSIN record should contain only one keyword parameter.
Blank SYSIN records are permitted.
Comment records are designated by * in position 1.

This list describes keyword parameters input to CMNWRITE through the SYSIN ddname.

`*` in Position 1

Optional. Denotes a comment

CMP=

Optional. Specifies a component name and library type. Format: CMP=cccccccc.ttt where

cccccccc    Component name
ttt         Library type

If the component cannot be found in the component master, the return code is set to at least 4. See CMNWRITE and Audit.

COBSYN=

Optional. Defines a synonym for COBOL or Assembler COPY verb. Multiple synonyms are allowed. Code a separate COBSYN= for each synonym.

Note

Copybooks resolved using this parameter are not expanded in-line. These copybooks are written to the PDS at the SYSUT3 DD statement for input to the compile step in the SYSLIB concatenation.

EOSPERIOD=

Optional. This parameter was introduced for backward compatibility when the default function of CMNWRITE was modified to require an end-of -sentence period for COBOL COPY statements so that the COPY REPLACING statement could be correctly parsed.

OPTIONAL    Do not require end-of-sentence periods for COBOL COPY statements. Using this parameter may affect detection of the COPY REPLACING phrase.

EXPAND=

Options. Provides finer control over the copy and include structures that CMNWRITE detects and expands.

ALL         Default - Expand all types of copy
PANVALET    Only expand CA Panvalet ++INCLUDE
LIBRARIAN   Only expand CA Librarian -INC
COPY        Only expand COBOL/Assembler COPY
PLI         Only expand PL/1 %INCLUDE
CEE         Only expand C #include
SQL         Only expand EXEC SQL INCLUDE
NONE        No expansion (like the NOEXPAND program parameter)

...

Notes

Any combination of the above is valid.
ALL overrides everything but NONE.
NONE overrides everything.
PARM=NOEXPAND overrides all EXPAND keyword parameters.

FAPIW=

Optional. Specifies a substitution character for FIS Systematics EXEC API PROC member name processing that is enabled by SYSIN parameter SITE=FIDE.

LIB=

Optional. Specifies the DSN of a CA Librarian baseline library to be searched for copybooks.

Up to ten PAN= and LIB= keyword parameters may be input in any combination.
These libraries are searched in the order the LIB= and PAN= records are read in SYSIN.
Libraries specified in LIB= and PAN= keyword parameters are searched after the SYSLIB concatenation is exhausted.

LIBSYN=

Optional. Defines a synonym for CA Librarian -INC verb. Multiple synonyms are allowed. Code a separate LIBSYN= for each synonym.

Note

Copybooks resolved using this parameter are not expanded in-line. These copybooks are written to the PDS at the SYSUT3 DD statement for input to the compile step in the SYSLIB concatenation.

LNG=

Optional. Determines how CMNPARSE analyzes source code to find copy and include statements:

Value   Source Parsed As Language...
AS      Assembler
BAL     Assembler
C       (C followed by a blank)
C+      (C+ followed by a blank)
EZ      Easytrieve
FORT    FORTRAN
MFS     IMS MFS
PL      PL/I
blank   CMNPARSE attempts to differentiate between Assembler and COBOL

...

Notes

If PL, then source will be searched for %INCLUDE.
If C, then source will be searched for #INCLUDE.
In all languages, source is searched for CA Panvalet ++INCLUDEs and CA Librarian -INC.
Any characters coded after those listed above are ignored. However, if the codes above are not complete, the language may be incorrectly identified. For example, CPLUS would be considered COBOL since it is not followed by a blank or plus sign and blank. However, PL2 would still be considered PL/I.

OPT=

Optional. Output formatting option


FLOWER	Default - Add a comment "flower box" at the top of each copybook that is expanded in the source and written to SYSOFILE.
NOFLOWER	Suppress the comment flower box in expanded copybooks.
CONTINUE	Specifies that existing ISIC records for this component are NOT deleted. Use this subparameter in the second CMNWRITE step of a dual compile scenario where the first CMNWRITE step creates ISIC records and the second CMNWRITE step creates more. Existing ISIC entries are cached. Duplicate entries in the second CMNWRITE step are not added. The existing entries with possibly older copybook data are retained. This may be needed to ensure that certain SYNCH conditions are not missed

PAN=

Optional. Specifies the DSN of a CA Panvalet baseline library to be searched for copybooks.

Up to ten PAN= and LIB= keyword parameters may be input in any combination.
These libraries will be searched in the order the LIB= and PAN= records are read in SYSIN.
Libraries specified in LIB= and PAN= keyword parameters are searched after the SYSLIB concatenation is exhausted.

PKG=

Optional. Specifies the change package ID. If the package cannot be found in the package master, the return code is set to at least 4. See CMNWRITE and Audit.

PLISYN=

Optional. Defines a synonym for PL/1 %INCLUDE verb. Multiple synonyms are allowed. Code a separate PLISYN= for each synonym.

Note

Copybooks resolved using this parameter are not expanded in-line. These copybooks are written to the PDS at the SYSUT3 DD statement for input to the compile step in the SYSLIB concatenation.

PVSYN=

Optional. Defines a synonym for CA Panvalet ++INCLUDE verb. Multiple synonyms are allowed. Code a separate PVSYN= for each synonym.

Note

Copybooks resolved using this parameter are not expanded in-line. These copybooks are written to the PDS at the SYSUT3 DD statement for input to the compile step in the SYSLIB concatenation.

SITE=FIDE

Optional. Enables wild card substitution in FIS Systematics EXEC API PROC member name before the member is expanded.

TYP=

Optional but Recommended. Specifies the library type, data set name, and origin of a like-copy library. You can use metadata to define the origin of the library as follows.

If the library is from a simple package staging library, use:

TYP=<libtype>/<library name>/S

If it is from a participating package staging library, use:

TYP=<libtype>/<library name>/<package id>/S

If it is from a promotion library, use:

TYP=<libtype>/<library name>/P/<promo site>/<promo name>

If it is from the baseline, use:

TYP=<libtype>/<library name>/B

If it is from a release area library, use:

TYP=<libtype>/<library name>/R/<release name>/<area name>

TYP= parameters are created in skeleton file tailoring (CMN$$WRT) to identify which application and library type supplied each copybook that is processed. This information is stored in the package master and is used by package audit to discover SYNCH15 errors.
If you omit TYP= parameters, CMNWRITE does not fail, but audit does not detect SYNCH15 errors.
TYP= parameters have no effect on the library search order of CMNWRITE.

Return Codes and Error Messages

Return Code	Description
0	Successful execution.
4	Refer to the short and long messages displayed within the job.
6	Unable to connect to ChangeMan ZMF instance; resubmit job under an active ChangeMan ZMF instance.
8	Package master I/O error; check all messages displayed within job.
12	System error; see messages.

...

Caution

A non-zero return code from CMNWRITE can lead to invalid SYNCH5, SYNCH15, and SYNCH16 audit errors. See CMNWRITE and Audit.

Reporting

The SYSPRINT DD statement for CMNWRITE displays the following information:

Program version.
PARM input.
Keyword parameters input to SYSIN.
Copybook library search order.
Summary report of copybook members and hierarchy.

The summary report from the sample CMNWRITE JCL above might look like this:

********************************************************************************
* DDNAME: WRITE.SYSPRINT *
********************************************************************************
ChangeMan(R) ZMF CMNWRITE - 8.1.4 SUNDAY NOVEMBER 26, 2017 21:51:24
PARM='SUBSYS=6,USER=USER015,'
PARM interpretation: ChangeMan ZMF subsystem "6"
Expansion of uncovered COPY/Include variations

SYSIN: TYP=CPY/CMNTP.S6.ACTP.STG6.#000081.CPY
SYSIN: TYP=CPY/CMNTP.S6.V810.BASE.ACTP.CPY
SYSIN: TYP=CP2/CMNTP.S6.V810.BASE.ACTP.CP2
SYSIN: CMP=CTST.SRC
SYSIN: LNG=COBOL2
SYSIN: PKG=ACTP000081
CMN7500I - Attempting to initiate dialog with started task.
CMN1400I - Session established with ChangeMan ZMF started task.
Library search order: PDS/CMNTP.S6.ACTP.STG6.#000081.CPY (CPY)
PDS/CMNTP.S6.V810.BASE.ACTP.CPY (CPY)
PDS/CMNTP.S6.V810.BASE.ACTP.CP2 (CP2)
LV -MEMBER--- VV.MM --CREATE-- --LAST CHANGED-- SIZE INIT -USERID- -- L I B R A R Y N A M E ----------------- ---FINGERPRINT---
--- C O M P O N E N T D E S C R I P T I O N ---(IF ANY)---------------

00 CTST 01.02 2012/07/01 2017/11/26 21:51 7 7 USER015 SYS17330.T215123.RA000.USER0157.SOURCE.H09 AF94653D-000000CD
01 COPYHELO 01.03 2012/07/01 2017/11/26 21:50 1 1 USER015 CMNTP.S6.ACTP.STG6.#000081.CPY 7A3EDE59-00000023
CMN1410I -  Session terminated with ChangeMan ZMF started task.
CMN5400I -  Time of day at end of job: 21:51:24 - Condition Code on exit: 0
            Record count in ====> 00007
            Record count out ===> 00014

...

In this report, the hierarchy of nested components is indicated by the LV column. If a copybook is not expanded inline into the source and is written to SYSUT3 instead, the LV number is preceded by "N," and message CMN5420I is printed beneath the component list.

Notes

COPY and INCLUDE Variations

This table displays examples of source code COPY and INCLUDE statements that CMNWRITE can detect. This is not an exhaustive list of statements that CMNWRITE can process.

Format	Action	Comment
01	COPY ABC. Expanded	COBOL variation
COPY “ABC”.	Expanded	COBOL variation
COPY ABC	Expanded	Assembler format
COPY ABC	Noted as resolved but not expanded	COBOL format
COPY ABC REPLACING...	Noted as resolved but not expanded	COBOL variation
01 FIELD-NAME. COPY ABC.	Noted as resolved but not expanded	COBOL variation
#INCLUDE	Expanded	“C” variation
#INCLUDE “abc”	Expanded	“C” variation
+INCLUDE abc	Expanded	PL/1 variation
++INCLUDE ABC	Expanded	CA Panvalet, any language
%INCLUDE DDNAME(MEMBERNAME)	Expanded	PL/1 variation
%XINCLUDE DDNAME(MEMBERNAME)	See NOTE 1	PL/I variation
-INC ABC	Expanded	CA Librarian, any language
EXEC SQL INCLUDE ABC END-EXEC	Expanded	Any language, can cross up to three lines. EXEC and the SQL must appear on the same line.
EXEC API PROC APIC?PRC (PARM1, PARM2, PARM3) END EXEC	? set to value in SYSIN parameter FAPIW=	FIS Systematics COBOL

...

Note 1

When PL/I source contains %XINCLUDE statements, you must suppress copybook expansion in CMNWRITE with one of the following:

NOEXPAND subparameter of the PARM= statement
SYSIN keyword parameter EXPAND=NONE

CMNWRITE and Audit

CMNWRITE writes ISIC records to the package master. ISIC records contain source-to-copy information from stage that is used by audit to evaluate source-to-copy relationships in package components to find SYNCH5, SYNCH15, and SYNCH16s errors.

Audit may report invalid SYNCH5, SYNCH15, and SYNCH16 errors if CMNWRITE does not write ISIC records because:

CMNWRITE yields a non-zero return code.
The package specified in the PKG= keyword parameter cannot be found.
The component specified in the CMP= keyword parameter cannot be found.
The stage process does not contain CMNWRITE.

Keyword Option OPT=NOFLOWER

By default, CMNWRITE adds a comment "flower box" at the top of each copybook that is expanded in the source and written to SYSOFILE. This comment box displays ISPF statistics from directory of the library where the copybook member was found. A typical flower box looks like this:

000006  *#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#
000007  * COPY COPYHELO
000008  * 1 COPYHELO 01.03 2012/07/01 2017/11/26 21:50     1   1   USER015
000009  *#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#=#

...

You can suppress this comment flower box by specifying OPT=NOFLOWER in SYSIN.

Skeleton Variable COPYLIBA

CMNWRITE writes copybooks that can be detected and resolved but not expanded to DD statement SYSUT3. Skeleton CMN$$WRT builds the SYSUT3 library to temporary data set &&CPYLIBA.

Skeleton CMN$$WRT also sets variable CPYLIBA to YES. Skeleton CMN$$SYC adds the &&CPYLIBA data set to the SYSLIB concatenation if variable CPYLIBA is YES. In skeletons delivered with ChangeMan ZMF, variable CPYLIBA is not reset to NO until the end of procedures where CMN$$SYC might be imbedded multiple times.

Do not customize skeletons to reset variable CPYLIBA to NO until after all imbeds of CMN$$SYC that must include &&CPYLIBA in the SYSLIB concatenation.

Recursive Nesting and C++ Headers

Programming language C++ implicitly allows recursive copy structures by requiring each programmed function to include all headers it will use. Compiler directives #ifndef and #define prevent looping in the resulting definitions. It is beyond the scope of CMNWRITE to interpret these compiler directives, so the NOEXPAND program parameter or the EXPAND=NONE SYSIN parameter should be used with C++ source to allow the C++ compiler to resolve these potentially recursive structures.

CMNWRITE must still analyze source and copybooks to provide source/copy information for audit, so beginning with ChangeMan ZMF 5.2, it records the names of all copybooks it encounters in a nest structure. As it begins a new level of a nest, it checks the new copybook name against those that have previously been encountered in this chain. If the name is found, then CMNWRITE assumes that a recursion has been discovered, and it will not search this copybook for copy or include commands.

Modifying Copybook Records With CMNEX016

CMNWRITE processes source code containing CA Librarian -INC statements where the source and copybooks reside in PDS(E) libraries rather than CA Librarian libraries. Exit program CMNEX016 mimics a CA Librarian exit that modifies copybook records included in source with the -INC command.

If CMNEX016 is enabled, it is called by CMNWRITE before each copybook record is written to the file at DD statement SYSOFILE. You can add logic to CMNEX016 to modify or skip copybook records before they are written to SYSOFILE.

The source for CMNEX016 is delivered in the CMNZMF ASMSRC library. See the program comments for more information.

CMNWRITE - Copy And Include Management

CMNWRITE Input

Output

Sample JCL

DD Statements

PARM Options

SYSIN Parameters

* in Position 1

CMP=

COBSYN=

EOSPERIOD=

EXPAND=

FAPIW=

LIB=

LIBSYN=

LNG=

OPT=

PAN=

PKG=

PLISYN=

PVSYN=

SITE=FIDE

TYP=

Return Codes and Error Messages

Reporting

Notes

COPY and INCLUDE Variations

Note 1

CMNWRITE and Audit

Keyword Option OPT=NOFLOWER

Skeleton Variable COPYLIBA

Recursive Nesting and C++ Headers

Modifying Copybook Records With CMNEX016

`*` in Position 1