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>.
- 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.
- 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.
- 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
|
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,exportencoding |
encoding | Specifies an encoding for source when you export in the SonarQube format. By default, UTF-8
is specified. This parameter is valid only when e,exportertype=CCSONARQUBE is
specified. |
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:
|
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_ONLY,LISTING_ONLY |
Chooses the view to use when you save source.
Notes:
|
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.
Note: ZUnit is not available with
IBM® Debug for z/OS®.
|
- 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
oroutput=C:/Users/Admin/ccresults
- If you run headless code coverage collection on z/OS, the path must be a z/OS UNIX file or path
name:
// 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")
/*