3.9.3 Accumulating coverage information
- Organization of this subsection
(1) How to accumulate coverage information and the format of coverage information
When you execute a job definition script, you use an option of the execution command to specify that coverage information is to be accumulated. When this specification is made, coverage information will be accumulated in an asc file.
The option for accumulating coverage information is the -t option. You can also use the -o option to rename the asc file to a name of your choosing. The format of the execution command with the option for accumulating coverage information specified is shown below. If there is conflicting information in the job definition script that is to be executed, an error will result. However, if the -f option is specified, the coverage information will be overwritten without resulting in an error.
adshexec [other-options...] [-t [-f ][-o path-name-of-asc-file]] path-name-of-job-definition-script-file [run-time-parameters]
In UNIX, if the adshexec command is executed with the -d option specified (and not the -t option), coverage information is collected only in memory. In this case, you can use the debugger's info coverage command to display the coverage information. If you exit the debugger by entering the debugger's quit command, the collected coverage information will be discarded and the memory released.
(2) Accumulation methods
The two coverage information accumulation methods are initial accumulation, which is the first accumulation, and continued accumulation, which is any subsequent accumulation. The accumulation method that is used (initial or continued) is determined by whether there is already an asc file.
If a change is made to a job definition script, the changed information will no longer have the same line numbers. Therefore, a backup of the job definition script is stored in the asc file. If there is a difference between the job definition script file and the backup asc file, the command terminates with an error without executing the job definition script.
In the initial accumulation, the command creates an asc file and writes the coverage information into it during execution. In a continued accumulation, the command reads the contents of the asc file and updates it by adding coverage information for the current execution.
(a) Examples of initial accumulation
The following are examples of initial accumulation.
- Example 1:
-
This example collects coverage information when there is no coverage information file (asc file).
- Example 2:
-
If all the following conditions are satisfied, the command performs initial accumulation:
-
There is a coverage information file (asc file).
-
The job definition script file differs from that used when coverage information was collected in the existing coverage information file.
-
A different job definition script file is used and the option for initializing the coverage information file (-f option in the adshexec command) is specified.
-
(b) Examples of continued accumulation
If all the following conditions are all satisfied, the command performs a continued accumulation:
-
A coverage information file (asc file) already exists.
-
The job definition script file is the same as the one used when coverage information was collected in the existing coverage information file.
One of the conditions for performing continued accumulation is that the job definition script is the same as the previous one used to collect coverage information. The command determines that job definition scripts are identical in the following manner:
-
A binary comparison that is performed on the job definition scripts shows that their sizes and contents are the same.
When these conditions are satisfied, the command treats the job definition scripts as being identical even if their file names and paths differ.
(3) File names of job definition scripts that are registered in coverage information files
In a continued accumulation, the file name of the job definition script that was used the first time coverage information was collected takes effect.
- Example:
-
The following files are treated as being the same job definition scripts although their file names differ:
-
/dir1/file1
-
/dir2/file2
If a continued accumulation is performed by using an output asc file named out.asc and the above job definition scripts, the scrip file name in the out.asc will be as follows:
-
If adshexec -t -o out.asc /dir1/file1 is executed, the script file name in out.asc is /dir1/file1.
-
If adshexec -t -o out.asc /dir2/file2 is executed, the script file name in out.asc is /dir2/file2.
-
If adshexec -t -o out.asc /dir1/file1 is re-executed, the script file name in out.asc is /dir1/file1.
-
(4) Extension of coverage information files
The default extension for coverage information files (asc files) is .asc. The extension for coverage information files does not have to be .asc. When coverage information is collected, the command treats a file with any extension that was specified as coverage information as an asc file.
(5) Size of a job definition script
The size of a job definition script file must not exceed 2 gigabytes.