Debugging

8. Debugging COBOL code

So you've written your program, finally got it to compile after sorting out all those syntax errors and undefined variables and the rest. So you execute the program and Hey Presto! ... nothing happens, you get a runtime error, or worst of all, your computer locks up and you're reaching for CTRL+ALT+DEL. So what went wrong?

Don't worry. The next thing to do after writing your wonderfully crafted program is to fix all the bugs, that is, all the errors in the code that lie hidden in the logic beyond the reach of the compiler. Here are a few personal hints and tips of mine to set about debugging your program (and avoiding errors in the first place), or at least how I go about getting my code to do what I want it to do.

  1. Before a line of code is written...preparation
  2. Commenting
  3. Variable names
  4. Break it up
  5. "Stubs"
  6. Watching variables
  7. Debugging tools

&nbsp

(i) Before a line of code is written...preparation

The best way to avoid spending hours trying to untangle a mass of complex code (that you brilliantly typed into the computer straight from the top of your head) is PREPARATION. By that I mean: (1) be absolutely clear about what you want the program to do - know what the inputs and outputs are, (2) write a very broad algorithm and gradually refine as far as you can using pseudo-code, (3) draw a flow chart or structure chart that matches the pseudo-code, and (4) translate the flow chart into actual COBOL.

One issue is: Do I write the PROCEDURE DIVISION first and then go back and write the DATA DIVISION? This would seem a fairly sensible thing to do except that in practise you find you will forget to declare a whole slew of variables. A further point is that a good deal of COBOL involves doing things to the data that rely on what's been declared in the DATA DIVISION. Again, I would suggest preparing a fair proportion of the data definitions on paper first. When I write a program I write as much DATA DIVISION as possible before starting on the PROCEDURE DIVISION. Then, as I proceed through the code I keep going back to the DATA DIVISION to update it as soon as possible.

&nbsp

(ii) Commenting

Liberally sprinkle you code with comments that explain exactly what each fragment of code is meant to do. This really helps when trying figure out what's going on.

&nbsp

(iii) Variable names

Use variable names that are meaningful and stick to a standard format. For example, some people use a prefix before variable names to indicated the general function of the variable, such as printing variables:

  01   PRINT-OUTPUT.
      03  P-NAME     PIC X(20).
      03  P-ADDRESS  PIC X(50).
      03  P-CUS-CODE PIC 9(6).
      03  P-PAGE-COUNT PIC 999.

This example uses "P-" before each name to indicate a member of the print output group. Sometimes the prefix "WS-" is used to indicate WORKING-STORAGE, "L-" for LINKAGE SECTION variables. Notice that the names are also meaningful. While you may spend longer typing out longer names you'll thank youself when it comes to fixing bugs.

Care should be taken when deciding names that you spell them correctly (PAGE-COUNTRE) and/or consistantly (RECORD-NUM and RECORD-NO) and that you don't try to use singular and plural names (CUSTOMER-TOTAL and CUSTOMER-TOTALS).

&nbsp

(iv) Break it up

Breaking your code into smaller procedures (i.e. paragraphs) not only makes the program easier to read, but easier spot where problems are arising.

&nbsp

(v) "Stubs"

One way to monitor what is going on when you run your program is to place "stubs" at important points in the logic. By stubs I mean a DISPLAY statement that tells you the that certain position in the logic has been executed:

   MAIN-PARAGRAPH.
        DISPLAY 'IN MAIN PARAGRAPH'
        PERFORM INIT-PARAGRAPH.
        PERFORM RECORD-READ-PARAGRAPH
            UNTIL NO-MORE-RECORDS
        PEFORM TERMINATE-RUN
        DISPLAY 'PROGRAM ENDING' 
        STOP RUN.

If you have a DISPLAY at the beginning of each paragraph then the console window might look something like this:
IN MAIN PARAGRAPH
IN INIT-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN RECORD-READ-PARAGRAPH
IN TERMINATE-PARAGRAPH
PROGRAM ENDING

You must remember to remove all of the stubs when the program is fully debugged.

&nbsp

(vi) Watching variables
Of course, just putting little flags say "IN PARAGRAPH XYZ" can be extended further to display the value of certain important variables:

DISPLAY "P-COUNTER = " P-COUNTER 

Again, don't forget to remove them (or comment them out) when your done.

&nbsp

(vii) Debugging tools
Both the Fujitsu COBOL85 and Microfocus Personal COBOL compilers (and presumably other too) have debugging utilities. Most significant are the ability to animate the program and set breakpoints throughout your code. Animating your code allows you to view each line of code as the debugger steps through the program. You can pause the run at any point and check the value of variables. During this process you can specify variables that you want to watch throughout the run. Animating a program run can prove a bit tedious if large amounts of iterations are involved.

An alternative is to set breakpoints. By doing so the program run will pause at defined breakpoints (wherever you want them) to allow you to check the value of variables.

You should check your compiler documentation to find out how to use debugging utilites: for large programs they are well worth the effort.

*       *       *

When it comes to actually fixing errors try to avoid "hacks", that is, adding bits of code to correct erroneous data values rather than trying to find out why the data was wrong in the first place. You may find yourself getting bound up in ever more complex arrays of Boolean flags to allow certain conditions: e.g.

IF (X = Y) AND (Z >= W) AND ((A = B) OR (A  C)) AND (D 

This being the case, see if your logic couldn't be better designed. Sometimes going back to the drawing board (more than once) is the best strategy in the long run. Like a famous chess grandmaster once said (I don't know who) "If you see a good move, look for a better one" : if you think of a good way of coding something, look for a better alternative (not as snappy ?!).

Something to keep in mind at all times is that one day someone other than yourself may have to read and understand (and perhaps modify) your code. Whether this is true or not it is a good habit to get into because it makes you write better code. And, as a software professional, this will almost certainly be the case.