Using Program inventory utility
Related Topics
Under CICS, programs to be monitored by Code Coverage must reside in a Program Inventory file. The Program Inventory Utility allows you to manipulate your Program Inventory by:
- formatting a Program Inventory file for use
- copying members from one Program Inventory file to another Program Inventory file
- deleting members
- exporting or importing members
- altering the collection status of members
- listing the contents of a Program Inventory file directory
In conjunction with Code Debug CICS, the population and maintenance of the CICS Program Inventory file has 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 CICS Populater, 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.
This following topics describes the statements to use the CICS Program Inventory Utility (XVTCUTIL):
Job control statements for program inventory utility
Sample JCL to run the Utility is provided in Code Debug CICS SMXDSAMP member JCLCUTIL. This JCL is shown in the following figure and includes detailed parameter descriptions.
Program Inventory Utility JCL (JCLCUTIL)
.
.
.
.
.
.
//*
//STEP1 EXEC PGM=XVTCUTIL
//STEPLIB DD DISP=SHR,DSN=COMPWARE.CMXDNNN.SMXDOCCL <== CHECK DSN
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//*
//XVTPGINV DD DISP=SHR,DSN=XPEDITER.CICS.PGMINV <== CHECK DSN
//CONTROL DD *
/*
EXEC statement
The EXEC statement must run PGM=XVTCUTIL. Coding PARM=FULL on your EXEC statement will cause XVTCUTIL to provide messages with more detail. This parameter is optional.
DD statements
A series of DD statements are used to specify parameters for the execution of Program Inventory Utility.
Statement | Description |
|---|---|
SYSPRINT | SYSPRINT represents the report style output from XVTCUTIL. 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. |
XVTPGINV | This DD names the primary Program Inventory file, which is the main object of all Program Inventory Utility commands. |
XVTPGCPY | This DD names the target of the COPY command used to copy from one Program Inventory to another. An example would be: |
XVTPGEXP | This DD names the target of the EXPORT command used to extract program members from a Program Inventory file. An example would be: JCLCDEFE Sample JCL //* YOUR JOB CARD HERE //* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //* //* CODE COVERAGE INSTALL STEP: JCLCDEFE //* //* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //* //* JCLCDEFE - IEFBR14 JCL TO ALLOCATE THE XPEDITER/CICS CODE COVERAGE //* - PROGRAM INVENTORY EXPORT FILE. //* //* THE FOLLOWING JCL WILL ALLOCATE AN XPEDITER/CICS CODE COVERAGE //* PROGRAM INVENTORY EXPORT FILE. SUPPLY THE STEPCAT, VOLSER, UNIT, //* DSN, AND SPACE PARAMETERS. THIS JCL IS INTENDED AS AN EXAMPLE. //* PLEASE CONSULT THE INSTALLATION GUIDE BEFORE RUNNING. //* //EXPORT EXEC PGM=IEFBR14 //EXPORT DD DSN=XV.PGMINV.EXPORT, <== CHECK DSN // SPACE=(CYL,(5,5),RLSE), <== CHECK SPACE // DCB=(RECFM=FB,LRECL=4160,BLKSIZE=24960), // UNIT=SYSDA, <== CHECK VOLUME // DISP=(NEW,CATLG) // |
XVTPGIMP | This DD names the source of the IMPORT command used to load program members into a Program Inventory file. An example would be: |
CCCARDS | Insert this optional DD to name the data set to be used as output from the GENERATE command. For example: |
CONTROL | This DD contains one or more Code Coverage Program Inventory Utility commands (control statements). See to Program Inventory Utility Commands for descriptions of the available commands. Each command is honored individually, which means an error in one command will have no direct affect on a subsequent command. |
Program inventory utility commands
The following sections explain the various commands available when running the Code Coverage Program Inventory Utility. These commands are coded as control statements in the data set named by the CONTROL DD statement.
CONTROL statement parsing
The FORMAT command requires keyword parameters. All other Program Inventory Utility commands accept positional parameters. All parameters must fit in the first 72 columns of a single 80-byte record. Continuations are not supported.
Keyword parameters are coded keyword=value. The keyword may be a full or abbreviated name.
Positional parameters can 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.
The primary positional values are for LMOD, CSECT, and date and time stamp. Some commands may require, or allow for, additional positional parameters. For example, the COLLECT command allows for a value of ON or OFF as a fourth positional parameter.
FORMAT command
A Program Inventory data set must be formatted before it can be used by the CICS component of Code Coverage. Its DCB attributes are RECFM=FBS, and the LRECL and BLKSIZE must be equal. The BLKSIZE determines the size of a physical record and will default to half-track blocking. The space allocation must allow enough primary and secondary extents to cover the number of blocks to be formatted. The number of blocks to be formatted is specified on a FORMAT command using the keyword parameters described as follows.
Once you have formatted a Program Inventory, you cannot alter its space allocation (number of TRKS or CYLS) or DCB attributes (RECFM, LRECL, or BLKSIZE). In order to change DCB attributes, a Program Inventory must be re-allocated and formatted. If an existing Program Inventory is reformatted, the data set's secondary allocation can be utilized. Formatting an existing Program Inventory will erase all data in the data set.
GROUPCNT
The GROUPCNT keyword parameter, abbreviated GC, is used to specify the number of blocks which comprise an extent. For example, if GROUPCNT is 7, then space for each program inventory member will be allocated in increments of 7 blocks. This number must be between 7 and 31 (inclusive). The default is 7.
BLOCKS
The BLOCKS keyword parameter, abbreviated BLK, represents the number of physical records to be formatted. The size of a physical record is specified by the DCB BLKSIZE attribute. Regardless of the JCL SPACE allocation, only this number of BLKSIZE records will be formatted. The default is 3000. When using a half-track blocking factor, this default equates to 1500 tracks or 100 cylinders.
DIRENTS
DIRENTS (abbreviated DENT) specifies the minimum number of directory entries to be allowed. The value specified should be greater than the maximum number of programs to be tested with Code Coverage. The Program Inventory directory is a pre-allocated, contiguous area within the Program Inventory file. This number cannot be changed after the Program Inventory file has been formatted. The default is 1500. Any reasonable value for the number of entries (i.e., a value not exceeding the available blocks) can be specified.
AUTODELETE
AUTODELETE (abbreviated ADEL) optionally specifies that old members may be deleted by the Populate Utility if space is needed to add a new member. If NO is specified for AUTODELETE, the attempt to add the new member will fail. If YES is specified for AUTODELETE, old members will be deleted until sufficient space is available for the new member. All deletes are logged by the Populate Utility. The default is YES.
COLLECT
Use the COLLECT command or the COLLECT control card in the Code Coverage CICS Populater to set the collection status for your CICS programs.
Before Code Coverage can be used, the COLLECT command — or the COLLECT control card in the Code Coverage Populater — must be used to designate which programs you want Code Coverage to monitor. The COLLECT command sets the collection status for one or more programs to either ON or OFF. When the Code Coverage CICS Populater adds a program to the Program Inventory, the collection status for that program is initially set to OFF by default.
The COLLECT command can include up to four optional positional parameters.
lmod csect
For lmod specify the name of the desired load module or an asterisk ( * ) wildcard character.
csect
For csect specify the name of the desired CSECT within the specified load module or an asterisk ( * ) wildcard character.
date/time stamp
Specify the desired compile date/time stamp in the format CCYYMMDDHHMMSS.
ON/OFF
The fourth positional parameter is used to specify collection status. Valid values are ON and OFF. The default is ON.
COPY
The COPY command allows program entries to be copied from one Program Inventory file to another. The source Program Inventory file is named by the XVTPGINV DD statement. The target file for the COPY command is named by the XVTPGCPY DD statement. The COPY command can include up to four optional positional parameters, but must include at least one.
lmod
Specify the name of the desired load module or an asterisk ( * ) wildcard character.
csect
Specify the name of the desired CSECT within the specified load module or an asterisk ( * ) wildcard character.
date/time stamp
Specify the desired compile date/time stamp in the format CCYYMMDDHHMMSS.
REPLACE
The fourth positional parameter, REPLACE, is used to specify whether an existing duplicate program entry in the target file is to be overwritten. It can be abbreviated REP. The default is to not overwrite an existing duplicate program entry.
DELETE command
The DELETE command allows program entries to be removed from the Program Inventory file. The DELETE command can include up to three optional positional parameters, but must include at least one.
lmod
Specify the name of the desired load module or an asterisk ( * ) wildcard character.
csect
Specify the name of the desired CSECT within the specified load module or an asterisk ( * ) wildcard character.
date/time stamp
Specify the desired compile date/time stamp in the format CCYYMMDDHHMMSS.
DIR command
The DIR command builds a report of each program entry within a Program Inventory file and writes it to the specified SYSPRINT location. The DIR command can include up to three optional positional parameters.
lmod
Specify the name of the desired load module or an asterisk ( * ) wildcard character.
csect
Specify the name of the desired CSECT within the specified load module or an asterisk ( * ) wildcard character.
date/time stamp
Specify the desired compile date/time stamp in the format CCYYMMDDHHMMSS.
GENERATE command
The GENERATE command writes a series of COLLECT control statements to the data set named by the optional CCCARDS DD statement. The CCCARDS data set may be used as input to subsequent executions of the Program Inventory Utility by specifying it in the CONTROL DD statement. The COLLECT control statements output by the GENERATE command have no wildcards values and their collection status is ON. The GENERATE command can include up to three optional positional parameters.
lmod
Specify the name of the desired load module or an asterisk ( * ) wildcard character.
csect
Specify the name of the desired CSECT within the specified load module or an asterisk ( * ) wildcard character.
date/time stamp
Specify the desired compile date/time stamp in the format CCYYMMDDHHMMSS.
EXPORT
The EXPORT command allows program entries to be extracted from a Program Inventory file into a sequential data set. The source Program Inventory file is named by the XVTPGINV DD statement. The XVTPGEXP DD statement names the target file for the EXPORT command. The EXPORT command can include up to three optional positional parameters, but must include at least one.
lmod
Specify the name of the desired load module or an asterisk ( * ) wildcard character.
csect
Specify the name of the desired CSECT within the specified load module or an asterisk ( * ) wildcard character.
date/time stamp
Specify the desired compile date/time stamp in the format CCYYMMDDHHMMSS or an asterisk ( * ) wildcard character.
IMPORT
The IMPORT command allows program entries to be loaded into a Program Inventory file from an EXPORT sequential data set. The XVTPGIMP DD statement names the source file for the IMPORT command. The XVTPGINV DD statement names the destination Program Inventory file. The IMPORT command can include up to four optional positional parameters, but must include at least one.
lmod
Specify the name of the desired load module or an asterisk ( * ) wildcard character.
csect
Specify the name of the desired CSECT within the specified load module or an asterisk ( * ) wildcard character.
date/time stamp
Specify the desired compile date/time stamp in the format CCYYMMDDHHMMSS or an asterisk ( * ) wildcard character.
REPLACE
Specify whether an existing duplicate program entry in the target file is to be overwritten. The default is to not overwrite an existing duplicate program entry.