Starting and stopping the headless code coverage collector

Headless mode runs code coverage without a UI. Headless mode is ideal for environments in which a UI workbench is not installed or from the command line or as part of a script.

About this task

Notes:

Headless code coverage is not available on macOS.

The headless code coverage collector runs a daemon that listens for an incoming connection in the same way that the UI uses a debug daemon. Start or run your application like you do for code coverage capture in the UI but use the IP/Host:port of the headless code coverage collector. For more information, see Generating code coverage in headless mode using the collector.

Note: By default the results are stored in the root of the user's home directory under the CC folder. You can use the -output parameter to change the default setting.

The syntax diagram for the codecov command is shown below. You can use either the single letter parameter or the complete one for each option. All parameters and values are case-sensitive.

Options list

Format: codecov [options]

-a,allowoutputlocation=<TRUE|FALSE>

Indicates whether -o,output is allowed in the startup key. The default is FALSE.

-A,applid=<applid>

The APPLID parameter used in bearer authentication generates and authenticates bearer tokens on headless code coverage service on z/OS.

-b, enablebasicauth=<TRUE|FALSE>

Enables basic authentication on headless code coverage service on z/OS. The default is FALSE.

-C,startupcommandlist=<path>

Specifies a file that contains commands that will be sent to the debug engine at startup.

-c,singleconnect

Exits after a single daemon connection (must use with -startDaemon).

-D,stopdaemon=<port>

Stops the daemon that is listening on the port.

-d,startdaemon

Starts in daemon mode and wait for connections. If -port is not specified, the next available port is used. The port number used is displayed in the console.

-E,ignoreerrors

Results will be produced even if errors occur during the session. The results may be incomplete.

-e,exportertype=<CCSONARQUBE|SQ|CCPDF|PDF|CCCOBERTURA|COB>

Specifies the export format for code coverage data. You can specify multiple export types by using a comma between export formats.

-e,exportertype=CCSONARQUBE or -e,exportertype=SQ produces the SonarQube format with the .xml extension. Each test result is contained in a unique subdirectory.
-e,exportertype=CCPDF or -e,exportertype=PDF produces the PDF format with the .pdf extension. By default, source is included in the PDF report. To exclude source from the report, specify -s,savesource=false.
-e,exportertype=CCCOBERTURA or -e,exportertype=COB produces the Cobertura format with the .xml extension. Each test result is contained in a unique subdirectory.

-f,optionsfile=<path>

Reads command arguments from the specified options file.

-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="text"

Specifies a tag that is associated with the CC results. e.g., test ID.

-h,help

Prints the help screen.

-I,moduleincludelist=<path>

Deprecated. Use -R,filter=<filters> or -r,filterlist=<path> instead.

Specifies a file that contains a list of module names or regular expressions that will cause matching module names to be included in code coverage. The module include parameter overrides the module exclude parameter.

-i,moduleinclude=<module_list>

Deprecated. Use -R,filter=<filters> or -r,filterlist=<path> instead.

Comma-separated list of module names or regular expressions that will include modules in code coverage. The module include parameter overrides the module exclude parameter.

-k,ccskeystoreproperties=<path>

Starts CCS in secure mode with the settings provided in the keystore properties file. The keystore properties file must contain the path to a valid keystore file (ccskeystorefile) and the password (ccskeystorepassword).

On Windows and Linux, you can find a sample file in <install_location>/headless-cc/ccskeystoreinfo.properties

On z/OS, you can find a sample file in /usr/lpp/IBM/debug/headless-code-coverage/ccskeystoreinfo.properties

-L,localonly

The daemon will only accept connections from the localhost.

-l,cclevel=<LINE|FUNCTION>

The code coverage level (either "LINE" or "FUNCTION").

-o,output=<path>

The directory to save code coverage result files. A result containing the program name and timestamp is created under the output directory for each session. A subdirectory is created when you export the result in the SonarQube or Cobertura format.

-P,printparms

Prints a summary of the parameters specified.

-p,port=<port list>

The port number, port list(port,port) or port range(port-port) used by the debug daemon.

-R,filter=<filters>

Specifies a list of filters that are enclosed in single or double quotation marks. Use commas to separate the filters. The filters allow strings or regular expressions to include or exclude modules, parts, and files.

For more information, see Filtering code coverage results during collection.

-r,filterlist=<path>

Specifies a file that contains a list of filters to include or exclude module, parts, and files. Each filter appears on a separate line.

For more information, see Filtering results during collection in headless mode.

-S,ccsport=<port>

Starts Code Coverage Service (CCS) on the specified port. The code coverage collector and CCS will not start if the port is already in use.

When you run CCS with headless code coverage on z/OS, bearer of basic authentication is enabled. z/OS credentials are required to access the CCS REST API and authentication prompts will appear when you view the results in the Code Coverage Results view. Code coverage results are stored in user subdirectories and users only have access to their own results.

CCS uses the Jetty server to deliver REST API. By default, CCS configures the Jetty denial of service filter at 25 requests per second. You can override the default setting in one of the following ways:

For the Windows and Linux versions of the headless code coverage collector, modify the <install_location>/headless-cc/codecov.ini file and define the following system property in the -vmargs section:
```
-DCCSmaxRequestsPerSec=<desired_value>
```
For the z/OS headless code coverage collector, or when you use CCS with Remote Debug Service, you must set the environment variable OPENJ9_JAVA_OPTIONS with the java argument before you start headless code coverage:
```
export OPENJ9_JAVA_OPTIONS="$OPENJ9_JAVA_OPTIONS -DCCSmaxRequestsPerSec=<desired_value>"
```
For Remote Debug Service, see Customizing with the sample job EQARMTSU.

CCS also configures a QoS (quality of service) file with 20 concurrent requests. You can override the default setting in one of the following ways:

For the Windows and Linux versions of the headless code coverage collector, modify the <install_location>/headless-cc/codecov.ini file and define the following system property in the -vmargs section:
```
-DCCSmaxConcurRequests=<desired_value>
```
For the z/OS headless code coverage collector, you must set the environment variable OPENJ9_JAVA_OPTIONS with the java argument before you start headless code coverage:
```
export OPENJ9_JAVA_OPTIONS="$OPENJ9_JAVA_OPTIONS -DCCSmaxConcurRequests=<desired_value>"
```
For Remote Debug Service, see Customizing with the sample job EQARMTSU.

On Linux and Windows, Jetty expands web files to the temp directory. On z/OS, the files are stored in a hidden directory in the user's home directory. To override this, you can set the CCSworkdir environment value before you start the headless code coverage collector.

For example, on Linux and z/OS:

export CCSworkdir=/u/user/jettyfiles

In Windows command shell:

SET CCSworkdir=C:\jettyfiles

-s,savesource=<TRUE|FALSE>

Saves the source with the results. The default is TRUE. The value for this parameter also controls whether source appears with the PDF exporter. For example, if -savesource=TRUE is specified with -exportertype=CCPDF, source is included in the PDF report.

-T,timeout=<seconds>

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=<testid>

Results will be associated with the specified testid.

-v,view=<DEFAULT|SOURCE_ONLY|LISTING_ONLY>

Chooses the view to use when you save source.

DEFAULT uses whatever is the engine preferred 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. The SOURCE_ONLY support is available with z/OS Debugger 15.0.3 or later, with PTF UI77786 applied.
To collect source level code coverage with COBOL 6.2 and later, SOURCE_ONLY must be used.

-X,moduleexludelist=<path>

Deprecated. Use -R,filter=<filters> or -r,filterlist=<path> instead.

Specifies a file that contains a list of regular expressions that will cause matching module names to be excluded from code coverage.

-x,moduleexclude=<module_list>

Deprecated. Use -R,filter=<filters> or -r,filterlist=<path> instead.

Comma-separated list of module names or regular expressions that will exclude modules from code coverage.

-z,zunit=<zunitname>

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 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®.