3.9.2 Managing coverage information
The coverage information files (asc files) are used to manage coverage information.
- Organization of this subsection
(1) File name and storage directory for coverage information files
(a) File name
Coverage information is collected for each job definition script and each user. Therefore, the default asc file name consists of a job definition script name and a user name.
In the execution environment, you can specify any asc file name by using a command option.
In the editor, the default asc file names are used. Non-default asc file names cannot be specified.
The following shows the default asc file name:
job-definition-script-name(without-the-extension)_user-name.asc
If the length of an asc file name exceeds the maximum length supported by the OS being used, collection of coverage information will fail. For this reason, you must pay attention to the number of characters in the file name of each job definition script that is to be executed.
(b) Storage directory
In the execution environment, the default asc files are created in the current directory during command execution.
In the development environment, if coverage information is accumulated from a Windows's editor, the asc files are created in the directory that contains the job definition script file.
(2) Updating asc files
The asc files are updated whenever coverage information is accumulated or merged.
An asc file cannot be shared among multiple users at the same time. If an attempt is made to use an asc file that is in use by another user, the command issues the KNAX6211-E message and results in an error.
(3) asc file output processing
If a coverage information write operation on an asc file fails for a reason such as insufficient disk capacity, that coverage information is lost.
To prevent loss of collected coverage information, if a specified asc file (including a file with the default asc file name when specification is omitted) already exists, JP1/Advanced Shell updates the asc file as described below. JP1/Advanced Shell does not directly update the specified asc file (including a file with the default asc file name when specification is omitted).
-
Outputs new coverage information to a temporary asc file.
-
Renames the existing asc file to be the backup asc file.
-
Renames the temporary asc file to be the specified asc file (including a file with the default asc file name when specification is omitted).
-
Deletes the backup asc file.
Therefore, if a process to output coverage information to an asc file terminates prematurely and the command is re-executed, JP1/Advanced Shell recovers the coverage information and then resumes command processing.
When command processing terminates successfully, there will be no temporary asc file or backup asc file. If a process to output coverage information to an asc file terminates prematurely, the temporary and backup asc files might remain. These files will be deleted if the command is re-executed or when the command is processed and terminates normally.
You can delete temporary asc files manually. Do not delete any backup asc file. If a backup asc file is deleted, the coverage information accumulated up to the point of a command's error termination will be lost.
Normally, when you use the coverage functionality, you need not know the above details.
You can determine whether a specified asc file (including a file with the default asc file name when specification is omitted) has been updated by new coverage information because the KNAX6242-I message will have been output during the previous command execution.
If the KNAX6242-I has been output, the contents of the specified asc file (including a file with the default asc file name when specification is omitted) have been updated by new coverage information.
(4) File names associated with asc files
When coverage information is collected in an asc file, a temporary file is created. This file is called a temporary coverage information file (temporary asc file). The file name, which always begins with a fixed character string, is as shown in the following:
- Name of a temporary asc file
-
The file name always begins with a fixed character string as follows:
-
For the adshexec command: adshexec_temp_any-character-string
Name of a backup asc file
When an asc file is renamed temporarily (backup asc file), the following file name is used:
-
For the adshexec command: adshexec_backup_any-character-string
When you specify an asc file name (including the default asc file name) in an argument of a command, you must make sure that the specified file name does not exceed the maximum length (in bytes) permitted for a path name by the OS being used.
If processing is cancelled during command execution, temporary and backup asc files might remain. The remaining files are handled as follows:
-
You can re-execute the command with the temporary asc file remaining in the system. Alternatively, you can manually delete the temporary asc file and then re-execute the command.
-
If a backup asc file remains in the system, do not delete it. The adshexec command automatically restores the original asc file name from the remaining backup asc file name and then collects coverage information. Alternatively, you can manually restore the original asc file name and then re-execute the command.
Do not create a user file that has the same name as a temporary asc file or backup asc file. If a file with the same name as a temporary asc file for an asc file exists in the same directory, that user file will be deleted. If a file with the same name as a backup asc file for an asc file exists in the same directory, that user file might be treated as an asc file and deleted.
(5) Using temporary and backup asc files
In the execution environment, whether temporary and backup asc files are used depends on the specification of the -t and -d options in the adshexec command. The following table shows whether temporary and backup asc files are used in the execution environment.
|
adshexec command's option |
Windows |
UNIX |
|||
|---|---|---|---|---|---|
|
-t |
-d |
Temporary asc file |
Backup asc file |
Temporary asc file |
Backup asc file |
|
Omitted |
Omitted |
N |
N |
N |
N |
|
Omitted |
Specified |
-- |
-- |
Y |
N |
|
Specified |
Omitted |
Y |
Y |
Y |
Y |
|
Specified |
Specified |
-- |
-- |
Y |
Y |
- Legend:
-
Y: File is used.
N: File is not used.
--: The debugging option is not supported in Windows.
In the Windows development environment, whether temporary and backup asc files are used depends on the specification of Coverage information in the Runtime Environment Settings dialog box. The following table shows whether temporary and backup asc files are used in the development environment.
|
Specification of Coverage information |
Windows development environment (editor) |
|
|---|---|---|
|
Temporary asc file |
Backup asc file |
|
|
Do not accumulate |
N |
N |
|
Accumulate |
Y |
Y |
|
Accumulate (and overwrite on update) |
Y |
Y |
- Legend:
-
Y: File is used.
N: File is not used.
(6) Commands and temporary asc files
Temporary asc files are used as work files during command execution. If a file with the same name as a temporary asc file exists before command execution, that file will be deleted.
(7) Processing of asc files during execution of the adshexec command
The following table explains how asc files are processed during execution of the adshexec command.
|
Status when the command starts |
Command processing |
|||
|---|---|---|---|---|
|
job.asc |
adshexec_backup_job.asc |
job.asc |
adshexec_backup_job.asc |
Status of asc file and how it is processed |
|
N |
N |
Created |
None |
There is neither a new nor an old asc file. An asc file is created. |
|
N |
Y |
None |
Renamed to job.asc |
The old asc file job.asc has been renamed as backup file adshexec_backup_job.asc. The asc file job.asc is restored from backup asc file adshexec_backup_job.asc. |
|
Y |
N |
Used |
None |
job.asc is either the old or the new asc file. If job.asc is the new asc file, the KNAX6242-I message was issued during the previous execution. |
|
Y |
Y |
Used |
Deleted |
job.asc is the new asc file and adshexec_backup_job.asc is the old asc file. The old asc file adshexec_backup_job.asc is deleted. The new asc file job.asc is used. |
- Legend:
-
Y: The file exists.
N: The file does not exist.
job.asc: Name of asc file
adshexec_backup_job.asc: Name of backup asc file