Rational Developer for System z
PL/I for Windows, Version 8.0, Programming Guide

Using dumps for debugging

When you are debugging your programs, it is often useful to obtain a printout (a dump) of all or part of the storage used by your program. You can also use a dump to provide trace information. Trace information helps you locate the sources of errors in your program.

Two types of dumps are useful:

Use of the IMPRECISE compile-time option might lead to incomplete trace information. For additional information on the IMPRECISE option, see IMPRECISE.

Formatted PL/I dumps--PLIDUMP

You use PLIDUMP to obtain:

To get a formatted PL/I dump, you must include a call to PLIDUMP in your program. The statement CALL PLIDUMP can appear wherever a CALL statement appears. It has the following form:

  call plidump('dump options string', 'dump title string');
dump options string
An expression specifying a string consisting of any of the following dump option characters:
T-Trace
PL/I generates a calling trace.
NT-No trace
The dump does not give a calling trace.
F-File information
The dump gives a complete set of attributes for all open files, plus the contents of all accessible I/O buffers.
NF-No file information
The dump does not give file information.
S-Stop
The program ends after the dump.
E-Exit
The current thread or the program (if it is the main thread) ends after the dump.
K
Ignored.
NK
Ignored.
C-Continue
The program continues after the dump.

PL/I reads options from left to right. It ignores invalid options and, if contradictory options exist, takes the rightmost options.

dump title string
An expression that is converted to character if necessary and printed as a header on the dump. The string has no practical length limit. PL/I prints this string as a header to the dump. If the character string is omitted, PL/I does not print a header.

If the program calls PLIDUMP a number of times, the program should use a different user-identifier character string on each occasion. This simplifies identifying the point at which each dump occurs. In addition to this header, each new invocation of PLIDUMP prints another heading above the user-identifier showing the date, time, and page number 1.

PLIDUMP defaults

The default dump options are T, F, and C with a null dump title string:

  plidump('TFC', ' ');
Suggested PLIDUMP coding

A program can call PLIDUMP from anywhere in the program, but the normal method of debugging is to call PLIDUMP from an ON-unit. Because continuation after the dump is optional, the program can use PLIDUMP to get a series of dumps while the program is running.

You can use the DD:plidump environment variable to specify where the PLIDUMP output should be located, for example:

  set dd:plidump = d:\mydump;

In your PLIDUMP specification, you cannot override other options such as RECSIZE. The default device association for the file is stderr:.

PLIDUMP example

When you run the program shown in Figure 5, a formatted dump is produced as shown in Figure 6.

Figure 5. PL/I code that produces a formatted dump
  TestDump: proc options(main);
     declare
        Sysin input file,
        Sysprint stream print file;
     open file(Sysprint);
     open file(Sysin);
     put skip list('AbCdEfGhIjKlMnOpQrStUvWxYz');
     call IssueDump;

     IssueDump: proc;
        call plidump( ' ', 'Testing PLIDUMP');
     end IssueDump;

  end TestDump;

The call to PLIDUMP in the IssueDump procedure does not specify any PLIDUMP options (they appear as the first of the two character strings), so the defaults are used. Also note that the PL/I default files SYSIN and SYSPRINT have been explicitly opened so that the formatted dump displays the contents of their portions of the I/O buffer.

Figure 6. Example of PLIDUMP output
 1     * * * PLIDUMP * * *  Date = 910623  Time = 142249090                   Page 0001

 2   User identifier: Testing PLIDUMP


 3                                           * * * Calling trace * * *
     IBM0092I The PL/I PLIDUMP Service was called with Traceback (T) option
     At offset +00000024 in procedure with entry ISSUEDUMP
     From offset +0000010B in procedure with entry TESTDUMP
                                             * * * End of calling trace * * *

                                         * * * File Information * * *
                         Attributes of file SYSIN
 4   STREAM INPUT EXTERNAL
 5   ENVIRONMENT( CONSECUTIVE RECSIZE(80) LINESIZE(0) )
 6   I/O Built-in functions:  COUNT(0) ENDFILE(0)
 7   I/O Buffer:          000D9008  00000000 00000000 00000000 00000000   '................'
                          000D9018  00000000 00000000 00000000 00000000   '................'
                          000D9028  00000000 00000000 00000000 00000000   '................'
                          000D9038  00000000 00000000 00000000 00000000   '................'
                          000D9048  00000000 00000000 00000000 00000000   '................'
                          000D9058  0000                                  '..'

                         Attributes of file SYSPRINT
     STREAM OUTPUT PRINT EXTERNAL
     ENVIRONMENT( CONSECUTIVE RECSIZE(124) LINESIZE(120) PAGESIZE(60) )
     I/O Built-in functions:  PAGENO(1) COUNT(1) LINENO(1)
 8   I/O Buffer:          000D8008  20416243 64456647 68496A4B 6C4D6E4F   ' AbCdEfGhIjKlMnO'
                          000D8018  70517253 74557657 78597A20 0D0A0000   'pQrStUvWxYz ....'
                          000D8028  00000000 00000000 00000000 00000000   '................'
                          000D8038  00000000 00000000 00000000 00000000   '................'
                          000D8048  00000000 00000000 00000000 00000000   '................'
                          000D8058  00000000 00000000 00000000 00000000   '................'
                          000D8068  00000000 00000000 00000000 00000000   '................'
                          000D8078  00000000 00000000 00000000            '............'

                                     * * * End of File Information * * *
                                           * * * End of Dump * * * * * *

 1 
Time and date when PLIDUMP is called. Each separate PLIDUMP call has this information.
 2 
Character string specified in the PLIDUMP call (the second of the two strings provided to PLIDUMP) that is useful in helping to identify the dump if a number of dumps are produced.
 3 
Trace information, delineated by * * * Calling trace * * * and * * * End of calling trace * * *. This information allows you to trace back through the procedures from which PLIDUMP was called. In the example above, PLIDUMP was called from the procedure ISSUEDUMP which is nested in the TESTDUMP procedure. The hexadecimal offsets of each procedure are also provided in the trace information.

The trace information is provided by default as the T option and can be suppressed by specifying the NT option for PLIDUMP.

 4 
File attributes of SYSIN (opened explicitly in the program).
 5 
ENVIRONMENT options for the file SYSIN.
 6 
Values of relevant I/O built-in functions for the file SYSIN.
 7 
Contents of the I/O buffer for the SYSIN file. The first column is the hexadecimal address, the following columns are the hexadecimal contents of memory.
 8 
Contents of the I/O buffer for SYSPRINT. Notice that the second character string supplied to PLIDUMP (AbCd...) is contained in the I/O buffer, as seen by the text representation of the I/O buffer at the right-hand side of the row.

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)