Specifying code coverage options in the startup key

When you run code coverage in the Eclipse IDE or in headless mode, code coverage options can be directly specified in the startup key. In the case of the Eclipse IDE, this allows the user to specify code coverage options prior to the creation of an Incoming Debug Session launch configuration. If the launch configuration already exists, then the startup key options override any settings in the launch configuration. In the case of headless mode, specifying startup key options allows the user to override daemon settings.

About this task

You can specify a number of code coverage options from within your JCL by including them in the startup key.

The startup key EQA_STARTUP_KEY contains four parts: EQA_STARTUP_KEY=<PARM1>,<PARM2>,<PARM3>.

Where,

PARM1: To enable code coverage, specify CC. To enable debug, leave blank.
PARM2: Name of the program, usually the main module used to start the application.; Specify PARM2 to allow options to be set in the Eclipse Incoming Debug Session. This parameter can be left blank to have the debugger determine the program.
PARM3: Parameter=value pairs, separated by comma (,). Most of the parameters supported by the CC headless mode can be specified. Values that contain blanks or commas must be enclosed in double quotation marks.

See the following examples for EQA_STARTUP_KEY:

EQA_STARTUP_KEY=CC enables code coverage.
EQA_STARTUP_KEY=CC,PGM1 enables code coverage and uses the Incoming Debug Session launch configuration assigned to program with the name PGM1.
EQA_STARTUP_KEY=CC,,testid=test01 or EQA_STARTUP_KEY=CC,,t=test01 enables code coverage using the debugger detected program and assigns the results to test case test01.
EQA_STARTUP_KEY=CC,,testid=test01,savesource=true or EQA_STARTUP_KEY=CC,,t=test01,s=true enables code coverage using the debugger detected program, assigns the results to testcase test01 and saves source with the results.

When a non-CICS debug profile is enabled in code coverage mode, a default code coverage startup key is included in the profile. Specifying a startup key in JCL is not required when a profile is activated in code coverage mode because the startup key in the debug profile supersedes the one specified in the JCL.

The following list of properties that can be specified on the startup key applies to running with the Eclipse IDE. To get a complete list of properties supported by the headless mode, enter codecov -help from the command line where the headless mode is configured to run. You can use either the single letter parameter or the complete one for each option. All parameters and values are case sensitive.

Parameter	Valid Values	Description
`C,startupcommandlist`	`path`	The path to a file which contains debug startup commands. Commands should be listed one per line within the file.
`E,ignoreerrors`	`TRUE, FALSE`	Results are produced even if errors occur during the session. However, the results might be incomplete.
`e,exportertype`	`CCCOBERTURA,COB`, `CCPDF,PDF`, `CCSONARQUBE,SQ`	`CCCOBERTURA,COB` produces the Cobertura format with the .xml extension. Each test result is contained in a unique sub-directory. `CCPDF,PDF` produces the PDF format with the .pdf extension. `CCSONARQUBE,SQ` produces the SonarQube format with the .xml extension. Each test result is contained in a unique sub-directory. By default, the generated PDF report and sub-directories for Cobertura and SonarQube reports can be found under the CC folder of the user's home directory. You can use `o,output` to specify the directory to generate the report to. The output location is automatically added to the Code Coverage Results view when you collect code coverage with the Eclipse IDE.
`g,tag`	A string of alpha-numeric characters	A list of tags to associate with the code coverage result. Multiple tags should be enclosed in quotes and separated by a comma (,).
`I,moduleincludelist`	`path`	Specifies an optional file that contains a list of module names to be included in code coverage. Module expressions can use an asterisk (*) or question mark (?) to match module names. Module include overrides the module exclude parameter. Deprecated. Use `-R,filter=<filters>` or `-r,filterlist=<path>` instead.
`i,moduleinclude`	`module_list`	Comma separated list of module names or module expressions that will be included in code coverage. Module expressions can use an asterisk (*) or question mark (?) to match module names. Module include overrides the module exclude parameter. Deprecated. Use `-R,filter=<filters>` or `-r,filterlist=<path>` instead.
`l,cclevel`	`FUNCTION, LINE`	Code coverage level
`o,output`	`path`	The directory to save code coverage result files. A result containing the program name and time stamp is created under the output directory for each session. A sub-directory is created when you use an exporter to produce the SonarQube or Cobertura format. Note: This parameter is allowed only in headless code coverage if `-a,allowoutputlocation=TRUE` is specified in the command line when you start the code coverage collector. It is ignored in all other situations.
`s,savesource`	`TRUE, FALSE`	Whether or not source should be saved for the code coverage session.
`T,timeout`	An integer	Number of seconds to wait for a debug engine response before timing out. The default is 120 seconds. The session will terminate and results already captured will be saved. Specifying 0 (zero) will wait indefinitely.
`t,testid`	A string of alpha-numeric characters	Test id
`v,view`	`DEFAULT,SOURCE_LISTING,SOURCE_ONLY,LISTING_ONLY`	Choose the view to use when you save source. DEFAULT uses whatever is the engine preferred view. SOURCE_LISTING uses the source view first. When the source view is not found or is not available, it will default to the LISTING view. SOURCE_ONLY only allows source views to be included in code coverage collection. LISTING_ONLY only allows listing views to be included in code coverage collection. Notes: DEFAULT and SOURCE_ONLY are the only supported view options for Debug Tool compatibility mode. DEFAULT and SOURCE_LISTING are the only supported view options for standard mode. To collect source level code coverage with COBOL 6.2 and later, either SOURCE_LISTING or SOURCE_ONLY must be used.
`X,moduleexcludelist`	`path`	The path to a file which contains the list of modules to exclude from a code coverage report. Modules should be listed one per line, and the file may contain regular expressions. Deprecated. Use `-R,filter=<filters>` or `-r,filterlist=<path>` instead.
`x,moduleexclude`	`module_list`	Comma separated list of module names or module expressions that will be excluded from code coverage. Module expressions can use an asterisk (*) or question mark (?) to match module names. Deprecated. Use `-R,filter=<filters>` or `-r,filterlist=<path>` instead.
`z,zunit`	A string of alpha numeric characters	Indicates that the code coverage session is for a ZUnit test case. The output file name, test ID, and a module include filter will be initialized to match the `zunitName`. If PARM2, a test ID, or a module include filter is also specified, it will override the value provided with `zunitname`.

Notes:

For parameters that specify a path or a file, the path or file format must match the file specification format where collection is running. See the following examples:
- If you run headless code coverage collection on z/OS, the path must be a z/OS UNIX file or path name: output=/u/user1/ccresults
- If you run code coverage collection using the Eclipse UI on Windows, the path must be a Windows file or path name: output=C:\Users\Admin\ccresults or output=C:/Users/Admin/ccresults

Procedure

Edit your JCL and modify the startup key.

For example, to specify function level coverage for the PRTPRIM program:


// PARM.RUN=('/TEST(,,,TCPIP&&<IP_address_for_IDz_client>%<port_for_IDz_debug_UI_daemon>:*)')
//******* ADDITIONAL RUNTIME JCL HERE ******
//CEEOPTS DD *
ENVAR("EQA_STARTUP_KEY=CC,PRTPRIM,cclevel=FUNCTION")
/*

To specify creating a PDF using the short parameter name and have z/OS Debugger determine the program:

// PARM.RUN=('/TEST(,,,DBMDT%user:*)')
//******* ADDITIONAL RUNTIME JCL HERE ******
//CEEOPTS DD *
ENVAR("EQA_STARTUP_KEY=CC,,e=PDF")
/*