The daily edition.

Scope: Rocket Enterprise Developer 12.0 for Eclipse (UNIX), Open PL/I diagnostics, from bundle enterprisedevelopereclux_ug_120. I did not blend in other releases or platforms. Where the manual describes Windows-only or 32-bit Windows behavior, I say so and leave it out of the recommendations.

What PLIDUMP does

PLIDUMP is a built-in subroutine that, in the manual's words, creates a formatted dump of selected parts of the storage your program uses. It reports the calling path to the current location plus other data. See PLIDUMP Subroutine. Because you call it from your own code, it fits two situations: an ON-unit that captures state at the moment of an error, and a deliberate checkpoint during troubleshooting.

The syntax takes two character-string expressions:

CALL PLIDUMP (character-string-expression 1, character-string-expression 2);

The first is the dump options string. The second is a user-identified string of up to 80 characters that is printed as the dump header.

The options

The manual says that for compatibility any valid IBM PL/I character string is accepted, but only the following options are honored:

• C: Continue. The routine continues after the dump.
• F: Add key information in the dump for KSDS files accessed by the run-time system.
• H: Display heap data in the dump.
• S: Stop. The enclave terminates with a dump.
• T: Traceback.

T and C are the defaults. This distinction matters for error handling. The manual's example calls PLIDUMP('FS') inside an ON ERROR unit, which dumps with file key information and then stops, and calls PLIDUMP('FC') inside an ON KEY unit, which dumps and lets the program carry on:

on error
  begin;
    on error system;
    call PLIDUMP('FS');
  end;

on key(KSDSFILE)
  begin;
    good_record = '0'b;
    put skip list('KSDSFILE record not found');
    call PLIDUMP('FC');
  end;

Note that the manual's first example also passes 'TBFC'. Since only the options listed above are honored, treat any other letter in such a string as accepted for IBM compatibility rather than as a documented Open PL/I feature.

The documented example uses file statuses of 9/13 (bad filename) and 23 (record not found on a read) to illustrate that the dump shows each file's last operation along with its File Status bytes, which equate to COBOL File Status bytes. A status starting with 9 corresponds to a run-time error.

Making the dump readable: -debug and .stb files

Using PLIDUMP is explicit that a dump without symbol support is much less useful:

1. Compile with the -debug option so the program unit name, address and offset appear correctly in the traceback table. -debug can be combined with -opt or -opt3. To get symbols and line information in the dump you must compile with -debug, which generates the .stb files.
2. Keep the generated .stb files in the same location as the .exe, .dll or .so, or in a location named by the CODEWATCH_STBPATH environment variable. Otherwise the dump contains much less useful information.
3. To locate variables, compile with the MAP option. Finding Variables in PLIDUMP Output says this adds a table to the listing showing the offset within AUTOMATIC and STATIC storage of all level-1 variables that are AUTOMATIC or STATIC.

The same page also says that on Windows platforms an additional .pdb file is needed. That is Windows-specific and does not apply to this UNIX scope.

Choosing the output form: PLIDUMP_CONFIG

The PLIDUMP_CONFIG environment variable controls whether a core file is produced in addition to, or instead of, the default Program Environment dump:

• NONE: no output is produced.
• CORE: a core file only.
• BOTH: a core file in addition to the Program Environment dump.

If PLIDUMP_CONFIG is unset, or set to anything else, only the default Program Environment dump is produced. A misspelled value therefore silently falls back to the default rather than raising an error.

Where dumps go, and the QSAM caveat

You can define a dump data set with a DD statement whose ddname is PLIDUMP. The manual advises an LRECL of at least 300/304 to prevent dump records from wrapping, and, if you target SYSOUT, specifying MSGFILE(SYSOUT,FBA,300,0) or MSGFILE(SYSOUT,VBA,304,0) to prevent line wrapping. When you call PLIDUMP several times in one routine, use a unique user identifier for each call so the start of each dump is easy to find.

One nuance from the subroutine page: VSAM file buffers contain the results of the last I/O operation, but QSAM buffers may not be reliable. A QSAM buffer address might point at an automatic variable that is no longer valid or at storage that has since been freed. The manual's advice is to read into or write from STATIC variables if you always want a reliable QSAM buffer display.

Troubleshooting a disappointing dump

Common Problems Reported in a PLIDUMP lists the usual causes:

• No symbol information present: the code was not compiled for debugging; recompile with -deb.
• .STB file not found: the directory containing the .dll or .so is checked first, then the current directory or CODEWATCH_STBPATH. Copy the file there or extend the variable.
• .STB file out of date: a PLIDUMP can be truncated or even cause an abend in the application if the .stb files do not match the object code in the .dll or .so. Make sure they correspond.
• Line number appears one statement early: this is expected in most cases, because the PC points at the next line at the time of the abend.
• Compile listing is out of date: this can cause reported line numbers not to match actual source.

Takeaway

Treat PLIDUMP as a two-part setup: add PLIDUMP('FC') or PLIDUMP('FS') calls where you need state, and build with -debug (plus MAP) while keeping the matching .stb files beside the .so or on CODEWATCH_STBPATH. A stale or missing .stb file degrades the dump or can even abend the application, and PLIDUMP_CONFIG (NONE, CORE, BOTH) is the documented switch for adding a core file.