Debugging provides a means by
which the user can describe the conditions under which procedures are to be
monitored during the execution of the object program.
The ANSI Debug Module is classed as an obsolete
element in the ANSI'85 standard and is scheduled to be deleted from the next
full revision of the ANSI Standard.
All dialects in this COBOL implementation fully
support this syntax. The FLAGSTD directive can be used to detect all
occurrences of this syntax.
Although it is a part of the standard COBOL
definition, this module is explicitly excluded from the X/Open COBOL language
definitions and should not be used in a conforming X/Open COBOL source program.
The decisions of what to monitor and what information to display are
explicitly in the domain of the user. The COBOL debug facility simply provides
a convenient access to pertinent information.
The features of the language that support the COBOL debug module are:
- a WITH DEBUGGING MODE Switch – used at object code creation
time
- a run-time switch
- a USE FOR DEBUGGING statement
- a special register – DEBUG-ITEM
- debugging lines.
The reserved word DEBUG-ITEM is the name for a special register
generated automatically by your COBOL system that supports the debugging
facility. Only one DEBUG-ITEM is allocated per program. The names of the
subordinate data items in DEBUG-ITEM are also reserved words.
The DEBUGGING MODE clause is written as part of the SOURCE-COMPUTER
paragraph in the Environment Division. It serves as an object-time switch over
debugging statements written in the program.
When the WITH DEBUGGING MODE clause is specified in a program, all
debugging sections and all debugging lines are handled as specified in this
section of the document.
When the DEBUGGING MODE clause is not specified in a program, all the
debugging sections and debugging lines are treated as if they were comment
lines and their syntax is not checked.
A run-time switch dynamically activates the debugging code inserted by
your COBOL system. This switch cannot be addressed in the program; it is
controlled outside the COBOL environment. If the switch is on, the effects of
any USE FOR DEBUGGING statements written in the source program are permitted.
If the switch is off, all the effects described in the USE FOR DEBUGGING
statement are inhibited. Re-creation of the object code is not required to
provide or take away this facility.
The object time switch has no effect on the execution of the object
program if the WITH DEBUGGING MODE clause was not specified in the source
program.
The WITH DEBUGGING MODE clause indicates that all debugging sections and
all debugging lines are to be included in the object code. If this clause is
not specified, all debugging lines and sections are treated as if they were
comment lines.
The WITH DEBUGGING MODE clause is not an obsolete feature in ANSI'85 as
it can also be used in the Nucleus.
General Format
General Rules
- If the WITH DEBUGGING MODE clause is specified in the SOURCE-COMPUTER
paragraph of the Configuration Section of a program, all USE FOR DEBUGGING
statements and all debugging lines are included in the object code.
- If the WITH DEBUGGING MODE clause is not specified in the
SOURCE-COMPUTER paragraph of the Configuration Section of a program, any USE
FOR DEBUGGING statements and all associated debugging sections, and any
debugging lines are treated as if they were comment statements.
Note: The WITH DEBUGGING MODE clause is part of the ANSI Nucleus
as well as the ANSI Debug module. It is not obsolete and is not scheduled to be
deleted from the next full revision of the ANSI Standard.
The READY TRACE statement is a debugging feature which causes each
section and paragraph name subsequently reached to appear on the screen in
order of execution.
General Format
General Rules
- The
COBOL Compiler directive TRACE must be set to on to allow execution of the
statement. When the directive is not set, READY TRACE is documentary only.
-
READY TRACE is accepted, but is treated as
documentary only.
The RESET TRACE statement disables the tracing of section and paragraph
names on the screen.
General Format
General Rules
- The COBOL Compiler directive TRACE
must be set to on to allow execution of the statement. When the directive is
not set or when no previous READY TRACE is in effect, RESET TRACE is
documentary only.
-
RESET TRACE is accepted, but is treated as
documentary only.
The USE FOR DEBUGGING statement identifies the user items that are to be
monitored by the associated debugging section.
General Format
Run-time Switches
- The following run-time switch may impact either the syntax or
semantics described in this section.
- D – Activates ANSI Debug facilities
Syntax Rules
- Debugging section(s), if specified, must appear together immediately
after the DECLARATIVES header.
- Except in the USE FOR DEBUGGING statement itself, there must be no
reference to any non-declarative procedure in the debugging section.
This restriction is not enforced.
- Statements appearing outside of the set of debugging sections must
not reference procedure-names defined in the set of debugging sections.
- Except for the USE FOR DEBUGGING statement itself, statements
appearing in a given debugging section can reference procedure-names defined in
a different USE procedure only with a PERFORM statement.
- Procedure-names defined in debugging sections must not appear in USE
FOR DEBUGGING statements.
- Any given identifier,
file-name, or procedure-name can appear in only one USE FOR DEBUGGING
statement and can appear only once in that statement.
- The ALL PROCEDURES
phrase can appear only once in a program.
- When the ALL PROCEDURES phrase is specified, procedure-name-1 must
not be specified in any USE FOR DEBUGGING statement.
- If the data description entry of the data item referenced by
identifier-1 contains an OCCURS clause or is subordinate to a data description
entry that contains an OCCURS clause, identifier-1 must be specified without
the subscripting or indexing normally required.
- References to the special register DEBUG-ITEM
are restricted to references from within a debugging section.
General Rules
- 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).
A debugging line is any line with a "D" or "d" in
the indicator area of the line. Any debugging line that consists solely of
spaces from margin A to margin R is considered the same as a blank line.
The contents of a debugging line must be such that a syntactically
correct program is formed with or without the debugging lines being considered
as comment lines.
A debugging line will be considered to have all the characteristics of a
comment line, if the WITH DEBUGGING MODE clause is not specified in the
SOURCE-COMPUTER paragraph.
Successive debugging lines are allowed. Continuation of debugging lines
is permitted, except that each continuation line must contain a "D"
or "d" in the indicator area, and character-strings can not be broken
across two lines.
A
debugging line is permitted in the program only after theOBJECT-COMPUTER
paragraph .
Note: Debugging lines are part of the ANSI Nucleus and not the
ANSI Debug module. Therefore, they are not obsolete and are not scheduled to be
deleted from the next full revision of the ANSI Standard.
Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.