OpenVMS DEBUG Session Logs

OpenVMS developers often start with the basic DEBUG command set:

• EXAMINE;
• DEPOSIT and;
• SET BREAK.

One can productively debug programs with those basic commands. That said, the OpenVMS Debugger, known as DEBUG, is a far more powerful tool for identifying and exploring program execution than its most fundamental commands. Beyond the introductory command set, there are many powerful, often underutilized capabilities. These more advanced capabilities enable a developer to rise above the mechanics of line-by-line tactical debugging to where debugging a large program can be done strategically. Thinking at higher levels offers substantial leverage. Small amounts of effort spent learning these facilities improves productivity when debugging. This first installment will focus on DEBUG’s logging facility. DEBUG’s logging facility creates a log of the commands and outputs from the DEBUG session to an output file separate from that being displayed in a terminal window.

I will not go into the details of debugging before the OpenVMS Symbolic Debugger. The VAX-11/780 first shipped while I working as a Research Assistant at New York University’s Courant Institute of Mathematical Sciences. My primary focus was building a PDP-11 code generator and optimizer for LITTLE, a locally-developed machine-independent high-level language. I spent a significant amount of time sitting in the RSX-11M ODT (Octal Debugging Tool). I was constantly referencing multiple compiler and linker listings in addition to keeping careful written notes as I debugged the object code and supporting libraries produced by my code generator and the associated optimizer. I was debugging both the generated assembly code for sample programs and the underlying execution-time library.

The contrast could not have been starker. Debugging using ODT was a never-ending cycle of looking up octal address information from a compiler listing; finding the octal base address for relevant program section in the map produced by the linker; adding the two values; then entering the display command to retrieve the information. DEBUG allowed me to just enter the variable name. Debugging became dramatically more productive. That was version 1.0.^[1] By VAX/VMS Version 2.0, DEBUG included additional features beyond those available in the initial Version 1.0 release.^[2]

One feature that appeared after DEBUG Version 1.0 is the ability to direct debugging session output to a file separately from the output to the present terminal. ^[3] A session log file keeps one’s fingers on the keyboard; is easier to read; and eliminates transcription errors. Logs are not complete replacements for handwritten notes, but logs eliminate the need to keep line-by-line detailed notes while debugging. Having an automatic log improves concentration by removing the distraction imposed by notetaking. One’s fingers stay on the keyboard. Debug logs can be annotated inline using comment commands (lines prefaced by a !), the entered comment will appear in the DEBUG session log.

OpenVMS DEBUG’s starts with logging disabled. The documentation (and HELP text) states that the default log filename is SYS$DISK:[]DEBUG.LOG. The phrasing can be misread.

The word default when used in OpenVMS documentation has two, slightly different meanings. The first, common in general computing usage, is the initial value of a string/variable. The second, OpenVMS-specific meaning is the string supplied to the RMS $PARSE directive as a default filename string.^[4] In this case, the latter is the accurate interpretation. (The default in the first sense might as well be described as .) The DEBUG manual states:

The default filename SYS$DISK:[]DEBUG.LOG is used as the default string for the RMS $PARSE library call, so the individual filename elements, e.g., device and directory, can use the default values, e.g., SYS$DISK, [], filetype, while changing other values.

The SHOW LOG command shows the filename as test. However, the directory listing for the current directory demonstrates that the filename test produced a merging of the supplied filename, test, with the default string SYS$DISK:[]DEBUG.LOG, producing an actual filename of SYS$DISK:[]test.LOG, Figure 1. The underlying default name SYS$DISK:[]DEBUG.LOG remains unchanged, only the filename (DEBUG) was replaced with test.

The SET LOG command does not enable logging to the log file; it defines the name of the log file created when the log file is enabled. A subsequent SET OUTPUT LOG closes the active session log and opens a new session log with the specified name. To avoid confusion, take care when switching session logs during a single debugging session.

Figure 1 – Results of Partial File Name Defaulting

A subsequent SET LOG command, e.g., SET LOG [.SESSION] changes does not propagate the previous filename. SET LOG [.SESSION] is parsed using the original SYS$DISK:[]DEBUG.LOG base, generating SYS$DISK:[GEZELTER.SESSION]DEBUG.LOG in the current directory. Figure 2.

Figure 2 – Examples of merging of filename strings with SET OUTPUT

Enabling file logging is done with the SET OUTPUT LOG command. The simplest case of using a DEBUG session log is to set the log file name and enable output to the log is reproduced as Figure 3.

Figure 3 - Simple use of DEBUG log

A small program together with a simple DEBUG session is illustrative, Figure 4. The directory listing shows the original C source file; the compiled object file; the executable image; and the LOG file created from the admittedly simple DEBUG session.

Figure 4 - Create sample C program and executable

Displaying the contents of the DEBUG log file test.LOG shows both the DEBUG commands issued as well as the output resulting from those commands, Figure 5.

Figure 5 - Sample C program DEBUG Session

All DEBUG output is preceded by a !, marking that line as a comment when the log file is used as a command file input into DEBUG.

Also note that the log file from the sample session only starts following the SET OUTPUT LOG command. Until that point, output appears only on the user’s terminal window, not in the debug log file.

This sample session is admittedly extremely modest. However, it demonstrates that the output log file can substitute for hand-written notes. This saves developers significant time and effort, allowing better concentration on the actual work, rather than the clerical work of keeping hand-written notes.

Future installments in this series will address additional OpenVMS DEBUG features and capabilities.

Notes

[1]	Digital Equipment Corporation (1978, August) VAX-11 Symbolic Debugger Reference Manual, Order Number AA-D026A-TE
[2]	Digital Equipment Corporation (1980, March) VAX-11 Symbolic Debugger Reference Manual, Order Number AA-D026B-TEy
[3]	VMS Software Inc. (2026) VSI OpenVMS Debugger Manual Section 13.3 Logging a Debugging Session into a File, pp 269, et seq.
[4]	VMS Software Inc. (2026) VSI OpenVMS Debugger Manual Section 13.3 Logging a Debugging Session into a File, pp 273
[5]	R Gezelter (2010, October 18) The OpenVMS Consultant &endash; Filename Alchemy - F$PARSE Defaulting

References

URLs for referencing this entry

• Home
• Services
  • OpenVMS
  • Windows
  • Printers
  • PostScript
  • Architectures
  • Networks
  • Embedded Systems
• Speaking
• Upcoming Events
• TechnicalCounsel^SM News Archive
• Ruminations – An IT Blog 
• The OpenVMS Consultant 
• Presentations
• Publications
• Technology Demonstrations
• Bookstore
• Contact Us

http://www.rlgsc.com

+1 (718) 463 1079