Chapter 2: Debugging PL/I Applications

Mainframe Express uses the IBM VisualAge PL/I debugger to debug PL/I applications. This chapter introduces the main functions of the PL/I debugger. More details are provided in the chapter Getting Started with PL/I Applications, and comprehensive online help is provided from the Help menu within the PL/I debugger or from the Windows desktop by clicking Start>Programs>Micro Focus Mainframe Express 2.0>IBM VisualAge PLI Help.

When you debug a PL/I application, the source code is displayed as execution proceeds. You can step through the source code and set breakpoints to interrupt execution. When execution stops, the current line is highlighted. You can then, for example, examine and change data items and continue execution.

2.1 Starting the Debugger

You start the PL/I debugger in the usual way, by clicking Start Debugging on the Debug menu. Make sure that Enable PL/I debugging is checked on the Start Debugging dialog box or the PL/I debugger will not be invoked.

The PL/I debugger uses its own windows, outside of the Mainframe Express IDE, to display debugging information and to let you interact with it. If your application contains COBOL or Assembler programs as well as PL/I, the debuggers for these languages could also be invoked during the debugging session.

You can pass parameters to the application in the usual way, which depends on the system environment that is being used.

The PL/I debugger is attached when the first PL/I module is loaded. At this point, execution of the application stops and the PL/I debugger displays two windows:

• The Disassembly window, which displays the Assembler code for the module that was executing when the PL/I module was loaded. This will probably not be a module in your application. The PL/I debugger displays the Disassembly window for system routines and for any PL/I programs for which debug information was not generated during compilation.

• The Session Control window, which has two panes:
  • The left-hand pane shows the active threads; these are not relevant in a mainframe context, but you should ensure that Thread 1 is selected.

  • The right-hand pane lists the PL/I components that have been loaded by the application. This lets you select the components that you want to work with. At the highest level are the executable modules generated by the linker. You can use the normal Windows convention to expand and contract the list; that is, by clicking the + and - signs. The next level shows the object modules generated by the compiler, the next level shows the source modules, and the lowest level shows the source procedures.

Initially, the Disassembly window is on top, but the Session Control window is more useful as a starting point for debugging.

In the Session Control window, if you double-click the name of a module, a Source window is displayed, showing the source code for that module. You can display a separate Source window for each module on the list.

The Source window is also displayed automatically when execution stops within a PL/I module. The current statement is highlighted. You can use the View menu to switch between the Source, Disassembly, and Mixed views. The latter combines the information from the other two so that you can see the Assembler code that was generated by the PL/I compiler for each PL/I statement.

You cannot edit the source code directly in the Source window. If you want to change a PL/I program, you should stop debugging, edit the source module, rebuild it and restart debugging.

2.2 Debugger Functions

This section introduces the basic debugging functions that are available with the PL/I debugger. You must control these functions from the PL/I debugger windows and not the Mainframe Express window. The following description assumes that debug information has been generated for all the PL/I modules during compilation.

To begin with, you will probably find it easiest to control the PL/I debugger functions from the Breakpoints, Monitors, and Run menus on the Source window. In fact, several of the functions are available only from these menus on the Source window. Later, you can use pushbuttons or shortcut commands.

Please note the following:

• Irrespective of any other debug commands, execution stops at an exception condition that is not handled by the application. You can also ask it to stop at specific exceptions, even if they are handled, by clicking Debugger settings>Exception filtering on the Options menu and selecting the exceptions you want to stop at.

• The PL/I debugger recognizes a variable name only after it has been defined in the program, so you might need to continue execution beyond the corresponding DECLARE statement before using a variable name.

• If you want to stop a PL/I debugging session, you should do so by clicking Close debugger on the PL/I debugger's File menu. If you click Stop Debugging on the Mainframe Express Debug menu, the debugging session ends but the PL/I debuggertask is left running.

2.2.1 Breakpoints

A breakpoint causes the debugger to stop execution so that you can monitor the application's activity, change data items and control the subsequent execution. On the Breakpoints menu, you can define the following types of breakpoint:

• Line - to stop at a specified line in the source program. This is similar to the Statement breakpoint in the Mainframe Express COBOL debugger but the PL/I debugger recognizes only lines, not separate statements within a line. The easiest way to set or delete a line breakpoint is to double-click the line number.

• Entry - to stop when a specified entry point in a PL/I program is invoked. It is similar to the Program breakpoint in the Mainframe Express COBOL debugger.

• Address - to stop at a specified execution address. You can use a PL/I pointer variable to specify the address.

• Storage change - to stop when a specified storage area changes. You can specify an area of one, two or four bytes.

• Load occurrence - to stop when a specified PL/I program is loaded. You can then set up monitors and other breakpoints for the program.

The Breakpoints List window shows all the breakpoints that have been set. To see this window, click List on the Breakpoints menu. You can also modify the breakpoints from this window.

If the application will execute a breakpoint more than once, you might not want execution to stop every time. The Frequency option lets you specify which instances of the breakpoint will stop execution. The Expression option lets you specify a conditional expression which must be true if the breakpoint is to stop execution.

If you want to temporarily disable a line breakpoint without deleting it, right-click the line in the source code and click Disable on the popup menu.

To disable any type of breakpoint, select the breakpoint on the Breakpoints List window then click Disable on the Edit menu.

If you use Close debugger on the File menu to terminate a PL/I debugging session, the breakpoints are retained. In other cases, all breakpoints are deleted at the end of the debugging session.

2.2.2 Monitors

You can request the following windows from the Monitors menu in order to see information about the current status of active procedures and make changes:

• The Call Stack window shows the list of active subroutine calls. This list includes system routines as well as your application's routines.

• The Registers window shows the current contents of the registers.

• The Storage window shows the current contents of your application's processor storage. You can then change the storage by double-clicking a field and overtyping it.

• The Monitor Expression windows allow you to monitor and change the values of your application's variables and storage. To set up these windows, click Monitor Expression on the Monitors menu. You can then select which type of monitor you want and which variable or storage area is to be monitored.
  • The Popup Monitor monitors a single variable for the active program shown in the Source window. You can have more than one popup monitor active at the same time.

  • The Private Monitor monitors a list of variables for the active program. It can be useful if the same name is used for different variables in separately-compiled modules.

  • The Program Monitor monitors a list of variables for all PL/I programs in the application. Another way to add a variable to the program monitor is to double-click the variable name on the Source window.

  • The Storage Monitor monitors a storage area for all PL/I programs in the application.

  • Local Variables displays the variables that are in scope within the current thread or routine.

  The existence of a monitor does not cause execution to stop when its variable or storage area changes (except in the case of a storage monitor where you can use a PL/I pointer variable to specify the address and ask to see the new storage area each time the variable changes). However, when execution stops at a breakpoint, for example, you can look at the monitor to see the current value of the variable or the contents of the storage area. You can then change the value or contents before continuing execution.

  To change a value, double-click the value in the monitor window. You can replace it with any expression that is valid for the data type. The expression can include any currently active variables.

  Note that execution speed is reduced in direct proportion to the number of variables and conditions that are monitored.

2.2.3 Run Commands

When you have defined any breakpoints and monitors that you want, you can use the following commands on the Run menu to continue execution of the application:

• Step over - to execute the current line. If the line calls another routine (including a system routine - to perform I/O, for example) the called routine is executed and execution stops at the next statement in the calling routine. It is equivalent to Run Thru in the Mainframe Express COBOL debugger.

• Step into - to execute the current line. If the line calls another routine, execution stops at the first line in the called routine. It is equivalent to Step in the Mainframe Express COBOL debugger. If a called routine was not compiled with debug information, it is displayed in Disassembly view.

• Step return - to complete the execution of a routine up to and including the Return statement. Execution stops in the calling routine at the statement after the statement that called the routine. It is equivalent to Run Return in the Mainframe Express COBOL debugger. If you specify Step return in a main procedure, the application runs through to completion. If you accidentally step into an unwanted PL/I program or system routine, you can use Step return to continue to the calling point.

• Step debug - to execute the current line. If the line calls a routine that was not compiled with debug information, execution continues until the next line in a routine that was compiled with debug information. This line might be when execution returns to the first routine or in a routine called by the second routine. The extra checking required for this command significantly degrades performance.

• Run - to continue execution to the next breakpoint, exception, or the end of the application. It is equivalent to Run in the Mainframe Express COBOL debugger.

• Run to location - to continue execution to the next breakpoint, exception or a line that you have selected in the Source window. It is equivalent to Run to Cursor in the Mainframe Express COBOL debugger. The target cannot be a DECLARE statement.

• Jump to location - move to a line you have selected in the Source window without executing any code. Obviously you need to use this command with some caution. It can be used, for example, to skip the normal assignment of a control variable for an IF statement in order to test a different path. It is equivalent to Skip to Cursor in the Mainframe Express COBOL debugger. The target cannot be a DECLARE statement.

2.2.4 Limitation of Step Over and Step Into Commands

When a PL/I program transfers control to another PL/I program (for example, in CICS, by a LINK or XCTL statement) or to another point in the same program (for example, by a GOTO, HANDLE CONDITION, or ABEND statement), the debugger does not stop in response to a Step over or Step into command as you might expect. If you want to continue debugging at the first statement that you might reach in these circumstances, you must place a line breakpoint at that statement. If you do not, and there are no other breakpoints in the execution path, the program runs through to completion. In the case of a CICS transaction, you will need to restart the CICS session in order to resume debugging.