Headless collector installation and startup

The blog How to Capture Code Coverage without starting IDz discussed installation of the headless collector and how to start it. The instructions still apply to the latest version of IDz.

The latest help for the codecov command in IDz 14.2 can be found at this link Starting and stopping the headless code coverage daemon


There are different terms for the settings that control the headless collector. For the rest of this article they fall into 2 types:

  1. Parameters/arguments – the values passed when starting the headless collector.
  2. Properties/settings/options – property/value pairs that are used to control the headless collector and in some cases can be read from a file.

For the rest of this article a code coverage session involves launching the application under debug control and the debugger establishing a connection with the headless code coverage collector to produce results.

Design rationale

There are a couple of key design requirements that influenced how settings were implemented.

  1. With few exceptions the settings should be modifiable without requiring a restart of the headless collector.
  2. Each connection should be able to specify settings.
  3. Settings should have scope so that individual sessions can be controlled without affecting other sessions.
  4. Related to #3 the processing of settings should support multiple simultaneous connections to the headless collector.
  5. Settings are consistent on all platforms where the headless collector runs. (Windows, Linux and z/OS)

By design there are many ways to specify the settings used by the headless collector. In some cases these can affect all code coverage sessions. There are also times when the settings will only affect a single code coverage session. This article will help identify the different methods and the scope of their effect.

How to print settings

To help determine which settings are in use specify “printparms” or “printparms=true” in the global settings file (see Global settings). This is not required but it helps to determine where settings are being loaded from collector startup.

This will print out informational messages at startup and on each connection.

Example of the output:

  1. Initial settings loaded from the global file (printparms is in this file).
    NOTE: by adding printparms to the global file all parms are listed right from the start.
  2. Command line arguments are loaded and override any previous settings.
  3. When the headless collector is fully started it prints out the current settings.
  4. An incoming session that has settings on the startupkey are now processed and shown.

Details of how settings are loaded in the order they are processed

1) Defaults

All settings have a default that will be used if it is not explicitly specified. Defaults can be found in the online documentation.

NOTE: In IDz 14.2 the default for “savesource” was changed from false to true. It was determined that code coverage results were more useful if the default was to save the source/listing with the result.

2) Global settings file (CC.ini)

At startup the headless collector looks for the file CC.ini in <home directory>/CC of the user that started the collector. Any errors in processing the contents of this file will issue a message but processing will continue and the invalid entries are ignored.

The CC.ini file adheres to the java definition of a property file. Each line can have one property/value pair. There are several formats that can be used:

  • savesource (same as setting it to true)
  • savesource=true
  • savesource:true
  • savesource = true
  • savesource true
  • output=”long path with blanks”

This format applies to the user options file later in this article.

Documentation for the property file format can be found in the javadoc for the java.util.Properties class.

Recommendation: Place settings that are always used by the headless collector in this file.


  1. port is set in the global settings file to 8005
  2. Command line overrides the port to 8006
  3. The final set of parameters shows that port 8006 is used
    NOTE: port is one of the few settings that can not be changed after the headless collector has been started since the port must be allocated on startup.

3) Command line parameters

Command line parameters are processed next and will override any parameters loaded from the global file.

Entering “codecov -help” will print out help for parameters. This will force the help to be display no matter the settings in the global file.

4) User settings file (-optionsfile=<path>)

The user settings file is the same format as the global settings file. It is loaded after the command line arguments are processed and therefore will override any of the previous settings.

These files can be used to share settings with a team. It can also make long values easier to enter than specifying them on the command line.

5) Startupkey properties (EQA_STARTUP_KEY environment variable)

This one is especially powerful because it can be used to set unique settings for each collection. If JCL is being used to run the job the EQA_STARTUP_KEY environment variable can contain the property value pairs to set a specific setting. Settings specified this way override any previous values but will not affect any other connection.

NOTE: IDz running as the collector can also process this way of setting options.

An example of a setting that can take advantage of this is “testid=<testid>”. While it is possible to specify this on the startup of the headless collector, this would result in all code coverage sessions getting the same testid.

JCL example:

Property value pairs must appear after the 2nd comma. Property/value pairs are separated by commas.
Use double quotes if a value has blanks.

ENVAR("EQZ_STARTUP_KEY=CC,,testid=FIRST,tag=""hello there"",output=c:/temp")

When JCL is too long for the line it must be split after column 72

Results in…

If there are many common settings between jobs, and the testid is the only one different then an option file can be used. This makes it much easier to change the settings without having to change the JCL of many jobs.

  1. Create an option file c:\temp\options.ini
  2. Enter the common settings into that file.
  3. Modify the JCL to pass the optionsfile setting
  4. When the headless collector processes the connection it will use the options file for that session only.
  5. One advantage to using an option file on the startupkey is that by changing 1 file all JCL that references it get the changed settings.


  • By design the headless code coverage collector supports many ways to pass the settings.
  • These settings can be global and affect every connection to the collector.
  • The settings can also be set on each connection.
  • printparms is your friend and will help to show where settings are coming from.

Join The Discussion

Your email address will not be published. Required fields are marked *