Generating information about procedures

You can use the USE FOR DEBUGGING declarative to include COBOL statements in a COBOL program and specify when they should run. Use these statements to generate information about your program and how it is running. Code each USE FOR DEBUGGING declarative in a separate section in the DECLARATIVES SECTION of the PROCEDURE DIVISION.

For example, to check how many times a procedure is run, include a special procedure for debugging (in the USE FOR DEBUGGING declarative) that adds 1 to a counter each time control passes to that procedure. The adding-to-a-counter technique can be used as a check for:

How many times a PERFORM ran. This shows you whether the control flow you are using is correct.
How many times a loop routine actually runs. This tells you whether the loop is running and whether the number you have used for the loop is accurate.

You can use debugging lines, debugging statements, or both in your program. Debugging lines are placed in your program, and are identified by a D in position 7. Debugging statements are coded in the DECLARATIVES SECTION of the PROCEDURE DIVISION.

The USE FOR DEBUGGING declaratives must:
- Be only in the DECLARATIVES SECTION
- Follow a DECLARATIVES header USE FOR DEBUGGING
With USE FOR DEBUGGING, the TEST compiler option must have the NONE hook-location suboption specified or the NOTEST compiler option must be specified. The TEST compiler option and the DEBUG runtime option are mutually exclusive, with DEBUG taking precedence.
Debugging lines must have a D in position 7 to identify them.

To use debugging lines and statements in your declarative procedures, you must include both:

WITH DEBUGGING MODE in the SOURCE-COMPUTER paragraph in the ENVIRONMENT DIVISION
The DEBUG runtime option

Figure 1 shows how to use the DISPLAY statement and the USE FOR DEBUGGING declarative to debug a program.

Figure 1. Example of using the WITH DEBUGGING MODE clause

Environment Division
Source Computer . . . With Debugging Mode.
   ⋮
Data Division.
   ⋮
  File Section.

  Working-Storage Section.

 *(among other entries you would need:)

  01  Trace-Msg    PIC X(30)
                   Value "  Trace for Procedure-Name : ".
  01  Total        PIC 99  Value Zeros.

 *(balance of Working-Storage Section)

Procedure Division.
Declaratives.
Debug-Declar Section.
    Use For Debugging On 501-Some-Routine.
Debug-Declar-Paragraph.
    Display Trace-Msg, Debug-Name, Total.
Debug-Declar-End.
    Exit.

End Declaratives.

Begin-Program Section.
⋮
    Perform 501-Some-Routine.

   *(within the module where you want to test, place:)

    Add 1 To Total

  * (whether you put a period at the end depends on
  * where you put this statement.)

In the example in Figure 1, portions of a program are shown to illustrate the kind of statements needed to use the USE FOR DEBUGGING declarative. The DISPLAY statement specified in the DECLARATIVES SECTION issues the following message every time the PERFORM 501-SOME-ROUTINE runs. The total shown, nn, is the value accumulated in the data item named TOTAL:

Trace For Procedure-Name : 501-Some-Routine nn

Another use for the DISPLAY statement technique shown above is to show the flow through your program. You do this by changing the USE FOR DEBUGGING declarative in the DECLARATIVES SECTION to the following value and dropping the word TOTAL from the DISPLAY statement.

USE FOR DEBUGGING ON ALL PROCEDURES.