The USE FOR DEBUGGING statement identifies the user items that are to be
monitored by the associated debugging section.
- Automatic execution of a debugging section is not caused by a statement appearing
in a debugging section.
- When file-name-1 is specified in a USE FOR DEBUGGING statement , that debugging
section is executed:
- After the execution of any OPEN or CLOSE statement that references file-name-1,
and:
- After the execution of any READ statement (after any other specified USE
procedure) not resulting in the execution of an associated AT END or INVALID
KEY imperative statement, and:
- After the execution of any DELETE or START statement that references file-name-1.
- When procedure-name-1 is specified in a USE FOR DEBUGGING statement that
debugging section is executed:
- Immediately before each execution of the named procedure.
- Immediately after the execution of an ALTER statement which references procedure-name-1.
- The ALL PROCEDURES phrase causes the effects described in General Rule 3
to occur for every procedure-name in the program, except those appearing in
a debugging section.
- When the phrase,
ALL REFERENCES OF identifier
, is specified, that debugging section is executed for every statement that
explicitly references identifier-1 at each of the following times:
- In the case of a WRITE or REWRITE statement immediately before the execution
of that WRITE or REWRITE statement and after the execution of any implicit
move resulting from the presence of the FROM phrase.
- In the case of a GO TO statement with a DEPENDING ON phrase, immediately
before control is transferred and prior to the execution of any debugging
section associated with the procedure-name to which control is to be transferred.
- In the case of a PERFORM statement in which a VARYING, AFTER, or UNTIL phrase
references identifier-1, immediately after each initialization, modification
or evaluation of the contents of the data item referenced by identifier-1.
- In the case of any other COBOL statement, immediately after execution of
that statement.
If identifier-1 is specified in a phrase that is not executed or evaluated,
the associated debugging section is not executed.
- When identifier-1 is specified without the ALL REFERENCES OF phrase , that
debugging section is executed at each of the following times:
- In the case of a WRITE or REWRITE statement that explicitly references identifier-1,
immediately before the execution of that WRITE or REWRITE statement and after
the execution of any implicit move resulting from the presence of the FROM
phrase.
- In the case of a PERFORM statement in which a VARYING, AFTER or UNTIL phrase
references identifier-1, immediately after each initialization, modification
or evaluation of the contents of the data item referenced by identifier-1.
- Immediately after the execution of any other COBOL statement that explicitly
references and causes the contents of the data item referenced by identifier-1
to be changed.
If identifier-1 is specified in a phrase that is not executed or evaluated,
the associated debugging section is not executed.
- The associated debugging section is not executed for a specific operand more
than once as a result of the execution of a single statement, regardless of
the number of times that operand is explicitly specified. In the case of a
PERFORM statement which caused iterative execution of a referenced procedure,
the associated debugging section is executed once for each iteration.
Within an imperative statement, each individual occurrence of an imperative
verb identifies a separate statement for the purpose of debugging.
- A reference to file-name-1, identifier-1, or procedure-name-1 as a qualifier
does not constitute reference to that item for the debugging described in
the General Rules above.
- Associated with each execution of a debugging section is the special register
DEBUG-ITEM , which provides information about
the conditions that caused the execution of a debugging section . DEBUG-ITEM
has the following implicit description:
01 debug-item.
02 debug-line pic x(6).
02 filler pic x value space.
02 debug-name pic x(30).
02 filler pic x value space.
02 debug-sub-1 pic s9999 sign is leading separate character.
02 filler pic x value space
02 debug-sub-2 pic s9999 sign is leading separate character.
02 filler pic x value space.
02 debug-sub-3 pic s9999 sign is leading separate character.
02 filler pic x value space.
02 debug-contents pic x(n).
- Prior to each execution of a debugging section, the contents of the data
item referenced by DEBUG-ITEM are space-filled. The contents of data items
subordinate to DEBUG-ITEM are then updated, according to the following general
rules, immediately before control is passed to that debugging section. The
contents of any data item not specified in the following general rules remains
spaces.
Updating is accomplished in accordance with the rules for the MOVE statement,
the sole exception being the move to DEBUG-CONTENTS when the move is treated
exactly as if it was an alphanumeric to alphanumeric elementary move with
no conversion of data from one form of internal representation to another.
- The contents of DEBUG-LINE is the relevant COBOL source line number. This
provides the means of identifying a particular source statement.
- DEBUG-NAME contains the first 30 characters of the name that caused the debugging
section to be executed.
All qualifiers of the name are separated in DEBUG-NAME by the word IN or
OF.
Subscripts/indices, if any, are not entered into DEBUG-NAME.
- If the reference to a data item that causes the debugging section to be executed
is subscripted or indexed, the occurrence number of each level is entered
in DEBUG-SUB-1, DEBUG-SUB-2, DEBUG-SUB-3, respectively, as necessary.
- DEBUG-CONTENTS is a data item that is large enough to contain the data required
by the following General Rules.
- If the first execution of the first nondeclarative procedure in the program
causes the debugging section to be executed, the following conditions exist:
- DEBUG-LINE identifies the first statement of that procedure.
- DEBUG-NAME contains the name of that procedure.
- DEBUG-CONTENTS contains "START PROGRAM".
- If a reference to procedure-name-1 in an ALTER statement causes the debugging
section to be executed, the following conditions exist:
- DEBUG-LINE identifies the ALTER statement that references procedure-name-1.
- DEBUG-NAME contains procedure-name-1.
- DEBUG-CONTENTS contains the applicable procedure-name associated with the
TO phrase of the ALTER statement.
- If the transfer of control associated with the execution of a GO TO statement
causes the debugging section to be executed, the following conditions exist:
- DEBUG-LINE identifies the GO TO statement whose execution transfers control
to procedure-name-1.
- DEBUG-NAME contains procedure-name-1.
- If reference to procedure-name-1 in the INPUT or OUTPUT phrase of a SORT
or MERGE statement causes the debugging section to be executed, the following
conditions exist:
- DEBUG-LINE identifies the SORT or MERGE statement that references procedure-name-1.
- DEBUG-NAME contains procedure-name-1.
- DEBUG-CONTENTS contains:
- If the reference to procedure-name-1 is the INPUT phrase of a SORT statement,
"SORT INPUT".
- If the reference to procedure-name-1 is in the OUTPUT phrase of a SORT statement,
"SORT OUTPUT".
- If the reference to procedure-name-1 is in the OUTPUT phrase of a MERGE statement,
"MERGE OUTPUT".
- If the transfer to control from the control mechanism associated with a PERFORM
statement causes the debugging section associated with procedure-name-1 to
be executed, the following conditions exist:
- DEBUG-LINE identifies the PERFORM statement that references procedure-name-1.
- DEBUG-NAME contains procedure-name-1.
- DEBUG-CONTENTS contains "PERFORM LOOP".
- If procedure-name-1 is a USE procedure that is to be executed, the following
conditions exist:
- DEBUG-LINE identifies the statement that causes execution of the USE procedure.
- DEBUG-NAME contains procedure-name-1.
- DEBUG-CONTENTS contains "USE PROCEDURE".
- If an implicit transfer of control from the previous sequential paragraph
to procedure-name-1 causes the debugging section to be executed, the following
conditions exist:
- DEBUG-LINE identifies the previous statement.
- DEBUG-NAME contains procedure-name-1.
- DEBUG-CONTENTS contains "FALL THROUGH".
- If references to file-name-1 cause the debugging section to be executed,
then:
- DEBUG-LINE identifies the source statement that references file-name-1 .
- DEBUG-NAME contains the name of file-name-1 .
- For READ, DEBUG-CONTENTS contains the entire record read.
- For all other references to file-name-1, DEBUG-CONTENTS contains spaces.
- If a reference to identifier-1 causes the debugging section to be executed,
then:
- DEBUG-LINE identifies the source statement that references identifier-1,
- DEBUG-NAME contains the name of identifier-1, and:
- DEBUG-CONTENTS contains the contents of the data item referenced by identifier-1
at the time that control passes to the debugging section (see General Rules
5 and 6).