CICS populater

Related Topics

Testing with Code Coverage

Using-Code-Coverage-with-Code-Debug-TSO-and-Code-Debug-IMS

Using-system-flow-with-Code-Debug-CICS

Program inventory utility

Code Coverage monitors the execution flow of a program or series of programs. To improve performance in a CICS environment, a member for each program to be monitored must be added to the Program Inventory file each time a program is compiled. This populating of the Program Inventory file is performed by the CICS Populater.

In conjunction with Code Debug CICS, the population and maintenance of the CICS Program Inventory file have been extended to run as ISPF dialogs. The ISPF Program Inventory Maintenance screen can be used in one of two modes: batch or foreground. In batch mode, discussed in both this section and Program Inventory Utility, the JCL is created by the screen and can optionally be edited prior to being submitted by the user. The user has the option of creating their own JCL or using the JCL generated by this utility. In foreground mode, the functions requested are performed interactively and the results returned to the user. For more information, see CICS Program Inventory Maintenance Screen.

Job control statements

Sample JCL to run the Populater is provided in Code Debug CICS SMXDSAMP member JCLCPOP. This JCL is shown in the following figure and includes detailed parameter descriptions.

Tip

The Populater Utility can be included as a step within your site's standard Compile/Shared Services Processor/Link JCL to automatically populate the Program Inventory file. BMC recommends this as a best practice in order to ensure that the Program Inventory is always up to date and Code Coverage is available when needed. 

CICS Populater JCL (JCLCPOP)

//* YOUR JOB CARD HERE
.
.
.
.
.
.
//*
//STEP1    EXEC PGM=XVTCPOP
//STEPLIB  DD   DISP=SHR,DSN=COMPWARE.cMXDnnn.SMXDOccL   <== CHECK DSN
//         DD   DISP=SHR,DSN=COMPWARE.LCXnnn.SLCXLOAD    <== CSS 8.0.0+
//*
//SYSPRINT DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//XVTPGINV DD   DISP=SHR,DSN=XPEDITER.CICS.PGMINV        <== CHECK DSN
//*
//DFHRPL   DD   DISP=SHR,DSN=...   <== LOAD LIBRARIES TO BE SEARCHED
//         DD   DISP=SHR,DSN=...
//*
//SLSF001  DD   DISP=SHR,DSN=...   <== FROM 1-99 SLS DDIO FILE(S)
//SLSF002  DD   DISP=SHR,DSN=...
//*
//EXCLUDES DD   DISP=SHR,DSN=COMPWARE.cMXDnnn.SMXDSAMP(POPEXCL)
//*
//CONTROL  DD   *             <= DESIRED CONTROL STATEMENTS
/*

EXEC statement

The EXEC statement must run PGM=XVTCPOP. Coding PARM=FULL on your EXEC statement will cause XVTCPOP to provide messages for every LMOD/CSECT in the DFHRPL concatenation. If this parameter is not specified, only LMOD/CSECTs covered by the DEFINE statements will result in messages being issued. This parameter is optional.

The DEFINE, REPLACE, or COLLECT control statements discussed in CONTROL Card Format can also be entered directly in the CICS Populater JCL by coding a PARM= statement on your EXEC statement. There are two advantages to this approach. First, it provides for JCL symbolic substitution. Second, it enables you to append an XVTCPOP step to your standard compiler procedure. Because normal JCL syntax rules apply and the DEFINE, REPLACE, or COLLECT statements contain imbedded spaces, the statement must be enclosed in apostrophes.

Example

//STEP 1 EXEC PGM=XVTXPOP
// PARM='DEFINE &LMOD,REPLACE ALL,COLLECT ON'

When the DEFINE, REPLACE, or COLLECT statements are supplied via JCL, the following restrictions apply:

  • The DEFINE statement is required but REPLACE and COLLECT are optional.
  • No asterisk ( * ) wildcard characters can be included in the LMOD parameter.
  • If REPLACE is not supplied, the value for REPLACE is forced to YES.
  • If COLLECT is not supplied, the value for COLLECT is forced to ON.
  • Only one DEFINE statement should be used. If multiple DEFINE statements are coded, only the last one will be honored.
  • The CONTROL data set is ignored.

DD Statements

A series of DD statements are used to specify parameters for the execution of the CICS Populater.

Statements

Description

SYSPRINT

SYSPRINT represents the report style output from XVTCPOP. It will contain informational, warning, and error type messages. In some cases, error messages may be written to the JES message log. Both output locations should be checked when determining an error condition. SYSPRINT will generally be a JES SYSOUT data set, however to record SYSPRINT to a permanent data set, use a 133-byte record length, a fixed or fixed blocked record format, and ANSI carriage control. For example, DCB=(RECFM=FBA,LRECL=133). Data set blocksize (BLKSIZE) can be set to any desired value.

DFHRPL

The DFHRPL concatenation contains the load modules that may be selected for Code Coverage. This concatenation of data sets is normally a copy of the DFHRPL of a working CICS region. It could also be coded manually or copied from some other JCL jobstream.

SLSF001 through SLSF099

These data sets are valid source listing data sets containing output from the BMC AMI Common Shared Services Language Processor. When selected, a member from these data sets will be matched to a program found in the DFHRPL concatenation.

Important

XVTCPOP supports Embedded Source Support (ESS) to process source listings. If ESS is used for all programs to be processed by XVTCPOP, SLSFnnn files are not required.

XVTPGINV

This DD names the Program Inventory file, which holds entries for eligible Code Covered programs. This file is the primary output of XVTCPOP and the primary input to the CICS Code Coverage collection process. XVTCPOP populates this data set with program entries.

Before the Program Inventory data set is populated, it must be formatted using the FORMAT command in the Code Coverage Program Inventory Utility (XVTCUTIL).

EXCLUDES

This DD lists a series of load modules (LMODs) and CSECTs which are to be bypassed by the XVTCPOP process. These LMODs and CSECTs may be programs with no associated source listing
members. A more typical use is to list IBM and OEM LMODs and CSECTs for which Code Coverage does not need to be activated. This data set must have an 80-byte record length and a fixed or fixed blocked record format. For example, DCB=(RECFM=FB,LRECL=80). Data set blocksize (BLKSIZE) can be set to any desired value.

EXCLUDES card format

The LMOD statement controls exclusion at the load module level. For example, LMOD DFH* would exclude all CICS modules from processing by XVTCPOP. The CSECT statement controls exclusion at the CSECT level. For example, CSECT CEE* would exclude all LE CSECTs from XVTCPOP processing.

CONTROL

This DD is used to list a series of LMODs and CSECTs to be included or limited in Code Coverage monitoring. It serves as a positive selection criteria, as opposed to the negative selection represented by the EXCLUDES data set. Typically, you would identify by one or more statements in this data set the LMODs and CSECTs you want monitored by Code Coverage. This data set must have an 80-byte record length and a fixed or fixed blocked record format. For example, DCB=(RECFM=FB,LRECL=80). Data set blocksize (BLKSIZE) can be set to any desired value.

CONTROL card format

The REPLACE statement is used to control whether existing Program Inventory members should be overwritten. Valid parameters for this statement are YES, ALL, or NO. NO is the default.

  • YES means only existing inventory members will be replaced if their COMPILE DATETIME stamp is the same as the current member being processed.
  • ALL means all existing inventory members will be replaced regardless of their COMPILE DATETIME stamp.
  • NO means existing inventory members will not be replaced.

The DEFINE statement is used to control processing at the LMOD/CSECT level. This statement may also be used to specify an source listing member name. There are three positional parameters that can be used with the DEFINE statement. In positional order, they are:

  • LMOD name
  • CSECT name
  • source listing member name
Example

To set up Code Coverage monitoring of all load modules starting with PAY, simply code DEFINE PAY* * in the CONTROL card data set.

When a DEFINE statement names a specific source listing member, no wildcards are allowed for any positional parameter. Specific LMOD and CSECT names must be supplied.
The COLLECT control statement is used to control the initial collection status of a program already added to the Program Inventory File. Valid values are ON and OFF. The default is ON. OFF would result in no Code Coverage statistics being gathered for the program. Setting initial collection status to ON causes immediate eligibility for Code Coverage monitoring of the specified program.

Process flow

The following sections describe the general flow of XVTCPOP:

EXCLUDES and CONTROL card processing

These two DD statements control the overall processing of XVTCPOP. This is where individual LMODs and CSECTs may be excluded from or defined for further processing.

Items in the EXCLUDE data set are bypassed entirely. Items may be excluded at the LMOD or CSECT level. Typically, you would exclude IBM and OEM LMODs and CSECTs that might be found in the DFHRPL concatenation of your load libraries. For example, you can exclude all LMODs or CSECTs that start with CEE, DFH, DSH, IGZ, IKF, and others.

The CONTROL card data set is used to specify items to be processed. This data set also controls whether or not existing Program Inventory members are to be overwritten. This data set is used to control the LMODs and CSECTs which are selected for Code Coverage monitoring. In the following example of the use of the CONTROL DD, assume that PROGRAM1, PROGRAM2, PROGRAM3, and PROGRAM4 were recently compiled, and the new changes for these programs need to be populated to the Program Inventory:

COLLECT OFF
DEFINE PROGRAM1
REPLACE ALL
DEFINE PROGRAM2
DEFINE PROGRAM3
COLLECT ON
DEFINE PROGRAM4

Each member of the Control Card is processed independently. Before the process begins, COLLECT is set to ON and REPLACE is set to NO. In the example, PROGRAM1 is set to COLLECT OFF, and no previous Versions of the program will be deleted. This enables you to use Code Coverage on the older versions of the program and, if desired, delete those versions later. All previous versions of PROGRAM2 and PROGRAM3 will be deleted, and COLLECT will remain set to OFF for both programs. Only the new versions of the programs will be populated, and Code Coverage collection can be turned ON later. PROGRAM4 is set to ON for collection, and all older versions of the program will be deleted.

Positional parameters — as opposed to keyword — are used by both the EXCLUDE and CONTROL data sets. These positional parameters may include an asterisk ( * ) wildcard character. This wildcard can be used as a suffix to a value or as the entire value. For example, DFH* would apply to all values which begin with DFH, but * alone would match any value.

Additional Processing

When the EXCLUDES and CONTROL cards have been processed, the Populater (XVTCPOP) will then perform the following processing:

  • Scan the DFHRPL concatenation to determine which load modules are to be processed
  • Build a CSECT structure for each load module
  • Interrogate the source listing files
  • Add programs to the Program Inventory file. 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*