With the %TRACE command you switch on the AID tracing function and start the program or continue it at the interrupt point or the point specified in the %JUMP command.
With number you can specify the maximum number of COBOL statements to be traced, to be logged before execution.
With continue you can can control whether the program should stop or continue to run without logging, after %TRACE terminates.
With criterion you select different types of COBOL statements which AID is to log. Logging takes place prior to execution of the statements selected.
With trace-area you define the program area in which the criterion is to be taken into consideration.
Command | Operand |
%T[RACE] | [number] [continue] [criterion][,...] [IN trace-area] |
If the program is interrupted during a %TRACE, the %TRACE can be continued with %CONTINUE. This applies to the following cases:
A subcommand containing a %STOP command has been executed.
An %INSERT command ends with a program interrupt because the control operand is K or S.
The K2 key has been used (see section “Commands at the start of a debugging session”).
The %TRACE command is terminated, on the other hand, by the following events:
The maximum number of statements to be traced has been reached.
A subcommand containing a %RESUME or %TRACE command has been executed.
After one of the program interrupts described above, the program continues with %RESUME.
The operand values of a %TRACE command apply until they are overwritten by the entries in a subsequent %TRACE command, or until the program is terminated. In a new %TRACE command, AID therefore assumes the value from the previous %TRACE command if an operand has not been specified. In the case of the trace-area operand, this only happens if the current interrupt point is within the trace-area to be assumed. If there are no values to be taken over, AID assumes the default values 10 (for number) and the program containing the current interrupt point (for trace-area).
With the aid of the %OUT command, you can control the information to be contained in a line of the log and the output medium to which the log is to be written.
If the %TRACE is contained in a command sequence or subcommand, any commands which follow will not be executed.
The %TRACE command alters the program state.
number |
specifies the maximum number of COBOL statements of type criterion which are to be executed and logged.
number
is an integer 1 ≤ number ≤ 231-1. The default value is 10. If there is no value from a previous %TRACE command, AID inserts the default value in a %TRACE command without the number operand.
After the specified number of statements has been traced, AID outputs a message via SYSOUT, the program is halted and the user can enter AID or BS2000 commands. The message tells you at which statement and in which program the current interrupt point is located.
continue |
specifies whether AID should stop or continue the program after %TRACE terminates.
The operand applies until a different operand value for it is entered in a new %TRACE or until the program terminates.
continue-OPERAND - - - - - - - - - - - - - - - - - - - - - - - -
{S | R}
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
| S | The program is stopped. AID outputs a STOP message containing localization information about the interrupt point. The default value is S. |
R | The program continues without outputting a message. |
criterion |
is a keyword which defines the type of statements to be traced during program execution. Several keywords can be specified at a time; they take effect simultaneously. A comma must be used to separate any two keywords.
If no criterion is declared, AID uses the default value %STMT unless a criterion declaration from an earlier %TRACE command is still valid.
criterion | subcmd is processed prior to |
| Every COBOL statement |
| COBOL statements which modify the contents of a data item: ADD [CORRESPONDING], COMPUTE, DIVIDE, INITIALIZE, INSPECT, MOVE [CORRESPONDING], MULTIPLY, SET, STRING, SUBTRACT [CORRESPONDING], UNSTRING |
| CALL-, CANCEL-, INVOKE-, PERFORM statements as well as prior to SORT/MERGE statements, since these may call an INPUT or OUTPUT procedure. |
| EVALUATE, IF and SEARCH statements and the conditional THEN, ELSE and WHEN statement branches. |
| COBOL statements for calling a database: CONNECT, DISCONNECT, ERASE, FETCH, FIND, FINISH, FREE, GET, KEEP, MODIFY, READY, STORE |
| The conditional statement branches and their admissible negations: AT END, AT END OF PAGE, INVALID KEY, ON SIZE ERROR, ON OVERFLOW, ON EXCEPTION, the RAISE statement as well as prior to the execution of a USE PROCEDURE. |
| ALTER, CONTINUE, GOTO, RESUME statements. |
| COBOL statements which initiate I/O operations: ACCEPT, DISPLAY, OPEN, CLOSE, DELETE, READ, REWRITE, START, WRITE, GENERATE, INITIATE, TERMINATE |
| COBOL statements which have a section or paragraph name or which directly follow such a name. |
| Program or module start at the beginning of the PROCEDURE-DIVISION or at ENTRY. Program or module end by the statement STOP RUN, GOBACK, EXIT METHOD or EXIT PROGRAM |
| MERGE and SORT statements, RELEASE and RETURN statements |
Table 3: criterion declaration for the processing of subcmd
trace-area |
defines the program area in which tracing is to take place, i.e. only within this area can monitoring and logging of the statements selected by means of the criterion operand be effected. The %TRACE command is inactive outside of this area and is activated again only on returning to this area. trace-area can only be located within the loaded program, and the program that is specified must be loaded at the time when the %TRACE command is entered or the subcommand containing the %TRACE command is processed.
trace-area is limited to a compilation unit in programs without segmentation, and to a segment in programs with segmentation. The limitation to one segment applies only for independent segments (segment No.≥50).
A trace-area remains effective until a new %TRACE command with its own trace-area operand is entered, until a %TRACE command is issued outside of this area or until the program ends. If the trace-area operand has been omitted, the area definition from an earlier %TRACE command is assumed if the current interrupt point is located in this area. Otherwise AID uses the default value, i.e. the program unit or segment containing the current interrupt point.
The continuation address for program execution cannot be influenced by the %TRACE command; such is only possible by means of the %JUMP command.
trace-area-OPERAND - - - - - - - - - - - - - - - - - - - - - - - - - - - - IN [•][E=VM•] { [S=srcname][[•]PROC=program-id] | [S=srcname•] { [PROC=program-id•] statement-name | (source-reference:source-reference) } | C=segmentname | C=sharename } - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
•
If the period is in the leading position it denotes a prequalification, which must have been defined with a preceding %QUALIFY command. Consecutive qualifications must be separated by a period. In addition, there must be a period between the final qualification and the following operand part.
E=VM
As trace-area may only be located in the virtual memory of the program which has been loaded, enter E=VM only if a dump file has been declared as the current base qualification (see also %BASE command).
S=srcname
This must be specified if trace-area is not to be included in the current compilation unit.
PROC=program-id
This need only be specified if trace-area is not to be contained in the current program, if it is to be defined with statement-name and this is not unique within the compilation unit, or in order to overwrite a previously valid trace-area definition.
If trace-area ends with a PROC/PROG qualification, it comprises the whole of the specified program. The program must be loaded at the time when the %TRACE command is entered or the subcommand containing the %TRACE command is processed.
If the name in the S qualification is the same as program-id, only the PROG qualification need be written.
Although the following C qualifications have the effect of switching to machine code level, they can only be followed by a criterion selected from the preceding table or by the default value %STMT inserted by AID.
C=segmentname
This specification defines the designated segment as the trace-area. It is only necessary if the interrupt point is not contained in this segment or if a previously applicable area restriction applying to parts of the segment is to be removed.
C=sharename
This specification defines the designated object module as the trace-area. It is only necessary if the interrupt point is not located in the specified object module or if an area restriction applying to the object module is to be removed.
statement-name
The trace-area is defined by a statement name and comprises a section or paragraph in the PROCEDURE DIVISION.
{ L'section' | L'paragraph' [IN L'section'] }
An alphanumeric section or paragraph name can be specified without L’...’ since
this name cannot be confused with a data name in this command.
If a paragraph name is not unambiguous within a program, it must be identified by the section name of the section in which it was defined: L'paragraph' IN L'section'
(source-reference:source-reference)
The trace-area is defined by specifying a start address and an end address. The start and end addresses must both be within the same compilation unit and the following must apply:
start address ≤ end address.
If the trace-area is to cover only one statement line, the start address and the end address must be identical. It is not possible to limit trace-area to individual COBOL verbs within a line.
source-reference
designates the address of the first instruction generated for a statement in the PROCEDURE DIVISION and must be specified in one of the following formats:
S’n’
for lines with paragraph or section names in which no COBOL verb occurs.
This specification is not possible for programs which have been compiled with STMT-REFERENCE=COLUMN1-TO-6.
S’nverb[m]’ | S’xverb[m]’
for lines containing a COBOL verb.
Output of the %TRACE listing
The %TRACE listing is output in full format via SYSOUT as a standard procedure (%OUT operand value T=MAX). With the %OUT command, you can define the output media and the scope of information to be output (see AID Core Manual (Related publications) [1]).
A %TRACE listing with additional information (T=MAX) contains the number and type of the statement that was executed. If a statement label exists, it will be output as well.
A %TRACE listing without additional information (T=MIN) does not show the statement type.
Examples
1.
|
With the aid of the %OUT command, output is switched back to the terminal and the maximum range of information is defined for output.
The %TRACE command is to trace three COBOL statements. After the third statement the termination message for this %TRACE command follows, to the effect that statement 51 is in the program unit EXAMPLE and that the load module has the same name.
2.
|
With the %OUT command the range of information for the %TRACE command is reduced. A subsequently entered %TRACE command outputs the log without additional information.
3.
%TRACE 5 R %INSTR
5 program commands are executed and logged. After this, the program continues without logging.
4.
%C1 %CALL IN S=TESTPROG <%TRACE 1 R>
All subroutine calls by the TESTPROG module are logged. The program continues after each respective CALL instruction is executed and logged.