Getting listings

Get the information that you need for debugging by requesting the appropriate compiler listing with the use of compiler options.

Attention: The listings produced by the compiler are not a programming interface and are subject to change.

Table 1. Using compiler options to get listings
Use Listing Contents Compiler option
To check a list of the options in effect for the program, statistics about the content of the program, and diagnostic messages about the compilation Short listing
  • List of options in effect for the program
  • Statistics about the content of the program
  • Diagnostic messages about the compilation1
To aid in testing and debugging your program; to have a record after the program has been debugged Source listing Copy of your source SOURCE
To find certain data items in a storage dump; to see the final storage allocation after reentrancy or optimization has been accounted for; to see where programs are defined and check their attributes Map of DATA DIVISION items All DATA DIVISION items and all implicitly declared items

Embedded map summary (in the right margin of the listing for lines in the DATA DIVISION that contain data declarations)

Nested program map (if the program contains nested programs)

To find where a name is defined, referenced, or modified; to determine the context (such as whether a statement was used in a PERFORM block) in which a procedure is referenced; to determine the data set or file from which a copybook was obtained Sorted cross-reference listing of names; sorted cross-reference listing of COPY/BASIS statements and copybook data sets or files Data-names, procedure-names, and program-names; references to these names

COPY/BASIS text-names and library names, and the data sets or files from which associated copybooks were obtained

Embedded modified cross-reference provides line numbers where data-names and procedure-names were defined

To find the failing statement in a program or the address in storage of a data item that is moved while the program is running PROCEDURE DIVISION code and assembler code produced by the compiler3 Generated code LIST2,4
To verify you still have a valid logic path after you move or add PROCEDURE DIVISION sections Condensed PROCEDURE DIVISION listing Condensed statement listing, global tables, WORKING-STORAGE information, and literals OFFSET
To find an instance of a certain statement Alphabetic listing of statements Each statement used, number of times each statement was used, line numbers where each statement was used VBREF
  1. To eliminate messages, turn off the options (such as FLAG) that govern the level of compile diagnostic information. You can also selectively suppress messages by using the MSGEXIT suboption of the EXIT compiler option.
  2. To use your line numbers in the compiled program, use the NUMBER compiler option. The compiler checks the sequence of your source statement line numbers in columns 1 through 6 as the statements are read in. When it finds a line number out of sequence, the compiler assigns to it a number with a value one higher than the line number of the preceding statement. The new value is flagged with two asterisks. A diagnostic message indicating an out-of-sequence error is included in the compilation listing.
  3. The context of the procedure reference is indicated by the characters preceding the line number.
  4. You can control the listing of generated object code by selectively placing *CONTROL LIST and *CONTROL NOLIST (or equivalently, *CBL LIST and *CBL NOLIST) statements in your source. Note that the *CONTROL statement is different than the PROCESS (or CBL) statement.

    The output is generated if:

    • You specify the COMPILE option (or the NOCOMPILE(x) option is in effect and an error level x or higher does not occur).
    • You do not specify the OFFSET option. OFFSET and LIST are mutually exclusive options with OFFSET taking precedence.

Related tasks  
Generating a list of compiler messages  
Reading LIST output  
Language Environment® Debugging Guide (Debugging COBOL programs)