Chapter 7: Debugging Open PL/I Programs

This chapter describes CodeWatch features that relate to debugging PL/I programs and contains a sample command-line debugging session of an Open PL/I program. At the end of this chapter, the listing of the program used in the sample debugging session is provided. The source of the sample program is also available on the release media.

Program Blocks

Program blocks are units of code that provide scope and context for the debugger. An Open PL/I program block is a procedure block or a BEGIN block.

Block Names

A procedure block is referred to by the name of that procedure. A begin block is referred to by its label (if present) or by the string %BEGIN followed immediately by the line number on which the block begins. For example, an unlabeled begin block that starts on line 119 of the source file is referred to as %BEGIN119.

Referencing Nested Blocks

Open PL/I program blocks may be nested. Rules for naming nested blocks are as follows:

1. If a block defined within the compilation unit is contained within or contains the debugger's current evaluation environment, the block may be referred to simply by its name. The name may need to be qualified to make it unique within the external procedure.

   If the block contains the debugger's current evaluation environment, the search for the referenced block begins from the current environment and continues through each successive containing (parent) block until the referenced block is found.

2. If a block is in some other external procedure, it must be qualified with at least the external procedure name, and it may require further qualification. Furthermore, a fully qualified name to a block in some other external procedure may be the same as a partially qualified block name in the current procedure. To force the debugger to search outside the current procedure, qualify the block name with %EXTERN. (This is seldom necessary if ambiguous naming is avoided.)

   For example:

   A: proc;        /* 1 */        B: proc;             /* 8 */
     B: proc;      /* 2 */          C: proc;           /* 9 */
       C: proc;    /* 3 */            D: proc;         /* 10 */
         D: proc;  /* 4 */            end D;
         end D;                     end C;
       end C;                         B: proc;         /* 11 */
     end B;                             A: proc;       /* 12 */
     C: proc:      /* 5 */                A: proc      /* 13 */
       B: proc;    /* 6 */                  B: proc;   /* 14 */
         C:proc;   /* 7 */                  end B;
         end C;                           end A;
       end B;                           end A;
     end C;                           end B;
   end A;                          end B;

The following describes how each block can be referenced given the current evaluation environment in the external procedure %EXTERN.A (block 1).

If the current evaluation environment is in the internal procedure block %EXTERN.A.B.C.D (block 4), the following is true in the debugger:

If the current evaluation environment is in the external procedure block %EXTERN.B (block 8), the following is true in the debugger:

Built-in Function Support

The following PL/I built-in functions are supported by CodeWatch:

The following abbreviations for PL/I built-in functions are recognized:

• BIN for BINARY
• CHAR for CHARACTER
• DEC for DECIMAL
• DIM for DIMENSION

Referencing Arrays and Aggregate Structures

Arrays and aggregate structures can be referenced in their entirety by referring to them by their array or structure name, or individual subfields or members can be referenced using the conventional PL/I syntax, as in REC_NAME.FIELD. A subfield can be referenced directly as long as its name is unique.

A specified range of an array can be evaluated using the following command-line syntax:

EVALUATE array-name [m:n]

or

EVALUATE array-name (m:n)

where m is the starting point of the array range and n is the ending point of the array range.

An asterisk (*) specifies that all elements of a dimension are to be evaluated. For example:

EVALUATE array-name[*,3:5]

or

EVALUATE array-name(*,3:5)

displays the third through fifth columns of all the rows in a two-dimensional array.

Specifying only the array name for PL/I will cause the evaluation of every element of every dimension of the array. Similarly, specifying a structure, record, or group name will cause the evaluation of every member of the group.

Support for Open PL/I Include Files

The following list describes the rules applying to CodeWatch support for Open PL/I include files. This support applies to include files that contain executable code. The rules are as follows:

• Stepping into an include file, for example, when the next statement is a %INCLUDE directive, will cause the screen display to switch to the specified include file.
• Commands that deal with the source file, such as PRINT and POINT, work as expected when using the current include file.
• Stepping through an include file is allowed.
• Setting breakpoints within an include file is NOT allowed. The setting of a breakpoint unambiguously refers to the original containing source file.
• Stepping over an include file, for example, when the next statement is a %INCLUDE directive, is not explicitly allowed. This may may be accomplished by setting a breakpoint in the containing source file followed by the CONTINUE command.
• Stepping out of an include file before its last statement is accomplished similarly to stepping over, that is, by setting a breakpoint in the containing source file followed by the CONTINUE command.

Using CodeWatch with the Open PL/I Macro Preprocessor

CodeWatch can be used with PL/I programs to which the Open PL/I macro preprocessor mfpp has been applied. CodeWatch uses the original source file (rather than the expanded preprocessed output of mfpp). Stepping through macros works similarly to the include file support described for include files.

Sample CodeWatch Session Using Open PL/I

This debugging session illustrates how to use the commands and features of CodeWatch when debugging programs compiled with Open PL/I. Following the session is the source listing of the sample PL/I program. The source file for this program is also available on the CodeWatch installation media.

The sample program, primes.pl1, calculates the number of prime numbers within a given range, but it doesn't do it very well. There is a bug somewhere that causes the program to print out too many values. Observe the following output:

*** Sieve of Eratosthenes ***

Input maximum prime boundary: 
10
Number of primes found was     6
1      2      3      5      7      11

The program had been compiled using the -deb option to produce the necessary information for the debugger and the -l option to produce a listing file. It was then linked using Ipild. For example,

mfpli primes.pl1 -deb -l 
ldpli primes.o -o primes

In this sample session, comments (which are not part of the session) are the bullet items. The system prompt is $. Note that user-supplied text is in bold typewriter font. For clarity, the abbreviated form of the command is used only after the command has been previously spelled out in its entirety.

• Invoke CodeWatch at the system prompt.

  $ cwcmd primes
  
  ******************************************************************************
  * CodeWatch, 08.00                                                           *
  * ----------------                                                           *
  * Copyright 2009 Micro Focus (IP) Limited                                    *
  ******************************************************************************
  Initial evaluation environment is PRIMES:(inactive)

• Find the string "main".

  CodeWatch> FIND main
    109:    /* main procedure */

• Print 20 lines.

  CodeWatch> PRINT 15
  109       /* main procedure */
  110
  111       declare n fixed binary(31);
  112
  113       put skip;
  114       put list (' *** Sieve of Eratosthenes ***');
  115       put skip (2);
  116
  117       call read_input(n);
  118
  119       do while (n > 1);
  120          call sift(n);
  121          call read_input(n);
  122       end;
  123   
  124   end;

• The program calls read_input on line 117 to get user input, so set a break at line 119 to see if things are still working correctly.

  CodeWatch> BREAK 119

• Continue to the breakpoint. The program will request input; enter 10.

  CodeWatch> CONTINUE
  
  *** Sieve of Eratosthenes ***
  
  Input maximum prime boundary: 
  10
  Break at PRIMES\119

• Print a line of text. Evaluate n, which is the variable read in on line 117.

  CodeWatch> P
    119: do while (n > 1);
  CodeWatch> EVALUATE n
  N = 10 {fixed binary (31)}

• Access the declaration type of n.

  CodeWatch> TYPE n
  N fixed binary (31) automatic

• Everything seems to be fine. Set the default stepping action list to print one line and Step.

  CodeWatch> DSTEP [P]
  CodeWatch> STEP
  Step at PRIMES\120
    120:      call sift(n);

• Step into sift and see what's happening there.

  CodeWatch> S IN
  Step at PRIMES.SIFT\%ENTRY 
     77: sift: procedure (n);

• Use the ARGUMENTS command to see the arguments to this routine.

  CodeWatch> ARGUMENTS
  N = 10 {fixed binary (31)}

• Do a stack traceback.

  CodeWatch> STACK /ALL
  
  Stack contains 5 frame(s).
  Current execution point is PRIMES.SIFT\%ENTRY
  
  5: Owner is "PRIMES.SIFT" 
        Called from PRIMES\120
  4: Owner is "PRIMES" 
        Main program

• To demonstrate statement tracing, set the source file pointer to line 98 and print five lines.

  CodeWatch> POINT 98
     98:         do while (k < n);
  CodeWatch> P 5
     98:         do while (k < n);
     99:           /* cancel all multiples */
    100:           flags(k) = FALSE;
    101:           k = k + this_prime;
    102:         end;

• Set a break at line 100, which will put you in the middle of this small loop. Continue.

  CodeWatch> B 100
  CodeWatch> C
  Break at PRIMES.SIFT\100

• Set statement tracing and continue twice. Each statement is reported as it is executed.

  CodeWatch> TRACE STATEMENT
  CodeWatch> C
  **** PRIMES.SIFT\101 
  **** PRIMES.SIFT\102 
  **** PRIMES.SIFT\98 
  Break at PRIMES.SIFT\100 
  CodeWatch> C
  **** PRIMES.SIFT\101 
  **** PRIMES.SIFT\102 
  **** PRIMES.SIFT\98 
  Break at PRIMES.SIFT\100

• Set a macro "fig" to do FIND/IGNORE. This will be useful; by default, the FIND command is case-sensitive. The /IGNORE option ignores case.

  CodeWatch> MACRO fig.=[FIND /IGNORE]
  CodeWatch> fig PRINT_OUT
    105:    call print_out(primes,count);  /* should be count - 1 */

• Break at line 105 (the call to print_out). Turn off statement tracing and delete the breakpoint at the current line (NBREAK with no parameter deletes the breakpoint at the current line). Continue to the call to print_out.

  CodeWatch> B 105
  CodeWatch> NTRACE S
  CodeWatch> NBREAK
  CodeWatch> C
  Break at PRIMES.SIFT\105

• Evaluate count, which you are about to pass to print_out.

  CodeWatch> E count
  COUNT = 6 {fixed binary (31)}

• Six prime numbers are found. That's not right. Only five should have been found: 1, 2, 3, 5, and 7. Set a break at the entry point of sift, reload the program and continue execution (twice) to get back to the entry of sift. (Enter 10 again for input.)

  CodeWatch> B sift\%ENTRY
  CodeWatch> RELOAD
  Command line : "primes"
  Reloading..ok
  Initial evaluation environment is PRIMES:(inactive) 
  CodeWatch> C
  
  *** Sieve of Eratosthenes ***
  
  Input maximum prime boundary: 
  10
  Break at PRIMES\119
  CodeWatch> C
  Break at PRIMES.SIFT\%ENTRY

• Step once and print 15 lines.

  CodeWatch> S
  Step at PRIMES.SIFT\85
     85:    do I = 1 to n;
  CodeWatch> P 15
     85:    do I = 1 to n;
     86:      flags(I) = TRUE;
     87:    end;
     88:
     89:    count = 1;
     90:    primes(1) = 1;
     91:
     92:    do I = 1 to n;
     93:      if flags(I) = TRUE then do;
     94:        this_prime = I + 1;
     95:        count = count + 1;
     96:        primes(count) = this_prime;
     97:        k = I + this_prime;
     98:        do while (k < n);
     99:          /* cancel all multiples */

• Set a break at line 95. This is a conditional breakpoint with an ELSE action list. The debugger will not break at line 95 unless count > 4. It will instead evaluate count and continue on. Continue.

  CodeWatch> B 95 /IF {count > 4} /ELSE [E count]
  CodeWatch> C
  COUNT = 1 {fixed binary (31)} 
  COUNT = 2 {fixed binary (31)} 
  COUNT = 3 {fixed binary (31)} 
  COUNT = 4 {fixed binary (31)} 
  Break at PRIMES.SIFT\95

• Delete this breakpoint. Continue and print one line.

  CodeWatch> NB
  CodeWatch> C;P
  Break at PRIMES.SIFT\105
   105: call print_out(primes,count); /* should be count - 1 */

• Back at the call to print_out. Evaluate count. Assign count-1 to count and continue. (Enter 10 again for input.)

  CodeWatch> E count
  COUNT 6 {fixed binary (31)}
  CodeWatch> LET count=count-1
  CodeWatch> C
  Number of primes found was            (prime itself)    5
  
  1      2      3      5      7
  
  Input maximum prime boundary: 
  10
  Break at PRIMES\119

• This appears to be the solution. Reload the program and delete all breakpoints.

  CodeWatch> R
  Command line : "primes"
  Reloading..ok
  Initial evaluation environment is PRIMES:(inactive) 
  CodeWatch> NBREAK /ALL

• You can do a run-time patch to the program, without even exiting the debugger. This is a temporary fix to see what source changes you may need to make. This breakpoint will not report itself (/SILENT); it will simply execute its action list and continue. Continue program execution. Try 10 and 100 for user input. Exit the program by entering 0.

  CodeWatch> B 105 /SILENT [LET count=count-1;C] 
  CodeWatch> C
  
  *** Sieve of Eratosthenes ***
  
  Input maximum prime boundary:
  10
  Number of primes found was      (prime itself)     5
  
  1      2      3      5      7
  
  
  Input maximum prime boundary: 
  100
  Number of primes found was   26
  1      2      3      5      7      11     13     17     19     23
  29     31     37     41     43     47     53     59     61     67
  71     73     79     83     89     97
  
  Input maximum prime boundary:
  0
  Program exited with status 0
  Reloading..ok
  Initial evaluation environment is PRIMES:(inactive)

• So now you know that if you change line 105 of primes. pl1 from:

  call print_out(primes,count);

  to:

  call print_out(primes,count-1);

  the program will work just fine! Quit out of the debugger session.

  CodeWatch> QUIT 
  CodeWatch Quit...Bye!

Program Listing

Compiler:  Open PL/I 08.00.B2 - Copyright (c) 2009 Micro Focus (IP) Limited
Date/Time: December 11, 2009 (15:35:27)
File:      primes.pl1
Directory: C:\Program Files\Micro Focus\Open PLI 8.0\EXAMPLES\OPEN-PLI
Options:   deb l noopt Pentium obj primes.obj list primes.lst
       1   /* Sieve of Eratosthenes: Copyright (c) 2009 Micro Focus (IP) Limited */
       2   
       3   primes: procedure options (main);
       4   
       5   %replace FALSE      by '0'B;
       6   %replace TRUE       by '1'B;
       7   
       8   %replace MAX_VALUE  by 1000;
       9   %replace MAX_PRIMES by  500;
      10   
      11   
      12   read_input: procedure (maxv);
      13   
      14       declare maxv fixed binary(31);
      15       declare instring char(4) varying;
      16   
      17       declare ok bit(1);
      18   
      19       ok = FALSE;
      20   
      21       do while (^ok);
      22           put list ('Input maximum prime boundary:');
      23           put skip;
      24           get list (instring);
      25           maxv = decimal(instring);
      26           if maxv > MAX_VALUE then do;
      27               put list ('Value too big.  Try again.');
      28               put skip;
      29           end;
      30           else do;
      31               ok = TRUE;
      32           end;
      33       end;
      34           
      35   end read_input;
      36   
      37   isprime: procedure (number,values,total) returns (fixed binary(31));
      38   
      39       declare number                fixed binary(31),
      40                   values(1:MAX_PRIMES)  fixed binary(31),
      41           total                 fixed binary(31);
      42       declare n                     fixed binary(31);
      43   
      44           do n = 1 to total;
      45           if number = values(n) then
      46                  return (number);
      47           end; 
      48   
      49           return(-1);
      50   
      51   end isprime;
      52   
      53   print_out: procedure (values,total);
      54   
      55       declare values(1:MAX_PRIMES) fixed binary(31),
      56           total                fixed binary(31);
      57   
      58       declare i fixed binary(15);
      59   
      60       put list ('Number of primes found was');
      61       if isprime (total,values,total) >= 0 then
      62           put list(' (prime itself)');
      63       put edit (total) (F(4));
      64       put skip (2);
      65   
      66       do i = 1 to total;
      67           put edit (values(i)) (F(7));
      68           if mod(i,10) = 0 then do;
      69               put skip;
      70           end;
      71       end;
      72   
      73       put skip (2);
      74   
      75   end print_out;
      76   
      77   sift: procedure (n);
      78   
      79       declare n fixed binary(31);
      80   
      81       declare (i, k, count, this_prime) fixed binary(31),
      82           flags(1:MAX_VALUE) bit(1),
      83           primes(1:MAX_PRIMES) fixed binary(31);
      84   
      85       do i = 1 to n;
      86           flags(i) = TRUE;
      87       end;
      88   
      89       count = 1;
      90       primes(1) = 1;
      91   
      92       do i = 1 to n;
      93           if flags(i) = TRUE then do;
      94               this_prime = i + 1;
      95               count = count + 1;
      96               primes(count) = this_prime;
      97               k = i + this_prime;
      98               do while (k < n);
      99                   /* cancel all multiples */
     100                   flags(k) = FALSE;
     101                   k = k + this_prime;
     102               end;
     103           end;
     104       end;
     105       call print_out(primes,count);  /* should be count - 1 */
     106   
     107   end sift;
     108   
     109       /* main procedure */
     110   
     111       declare n fixed binary(31);
     112   
     113       put skip;
     114       put list ('*** Sieve of Eratosthenes ***');
     115       put skip (2);
     116   
     117       call read_input(n);
     118   
     119       do while (n > 1);
     120           call sift(n);
     121           call read_input(n);
     122       end;
     123   
     124   end;

Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.