Application Development

Chapter 39. Using the Debugger

Panther's debugger provides you with the ability to view and analyze all application components. You can view the application's execution from various perspectives with varying degrees of detail. You can examine and debug client and server components. You can:

Step through events, stopping to examine data.
Set breakpoints at events or JPL code on which to interrupt program execution. Breakpoints can be set on screen and widget events, program execution events such as database and transaction manager events, as well as source code locations. Breakpoints on screen, widget, group, and grid events can be further restricted to specific subevents.

Note: Events in the JetNet middleware API are not recognized in the debugger.
Examine application data in Panther variables and arrays, screen and service component properties, widget properties, and JPL variables or expressions
Step through your JPL code. You can view source code modules from open libraries, memory resident modules, public JPL modules, the window stack, and the program stack—as well as set breakpoints on their contents.
Call installed functions and JPL procedures and evaluate a JPL expressions.
Stop at a change in a variable or expression.
Review debugger activity in the log file. Debugger messages can be written to a user-specified log file.

This chapter describes the features of the Panther debugger and how to use it. If you are developing a two-tier application, the debugger is already linked in with your development executable (prodev) so you can debug client screens. If you are developing a JetNet or a Oracle Tuxedo application, you need to run a standard server in debug mode to debug service components and services.

Debugging Services and Service Components

If you are developing a JetNet or Oracle Tuxedo application, you can run a debuggable server so that you can monitor what the server is doing while it is processing service requests. Running the debugger on a server lets you see the service components that are on the server machine.

You can run the debugger on a server provided the following two conditions are true:

A standard server is initialized in debug mode. For information on initializing a debuggable server in JetNet, refer to "Server Details" in JetNet/Oracle Tuxedo Guide; if you are using Oracle Tuxedo, refer to "Initializing Servers" in JetNet/Oracle Tuxedo Guide.
The server environment file sets the DISPLAY variable to tell the X server where to display debuggable service components. For example:
```
DISPLAY=mimosa:0.0
```

When running a debuggable server, your client might timeout waiting for a response from the server while you are in debugging mode.

To ensure that the client does not timeout while debugging the server:

Set the appropriate timeout options in your client code. For example:

For xa_begin, set the TIMEOUT parameter to specify a large or infinite timeout.
For service_call, use the NOTIMEOUT option to prevent blocking timeouts.
For wait, set the TIMEOUT parameter to specify a large or infinite timeout.

The application's default blocking timeout is established for the application as part of the server configuration. For information on setting the Default Blocking Timeout parameter, refer to "Default Blocking Timeout" in JetNet/Oracle Tuxedo Guide. For Oracle Tuxedo users, refer to your Oracle Tuxedo documentation for information on SCANUNIT and BLOCKTIME configuration parameters.

How the Debugger Works

Many debuggers do their work by invoking the applications they analyze. The Panther debugger is invoked by your application, that is, by Panther itself. Panther notifies the debugger of each significant event in the application, as it occurs. Each time it is called in this way, the debugger analyzes the event and saves any information it needs. In most cases, the debugger then immediately returns control to the application. Some events, however, cause it to emerge or awaken from the background to halt the application and display its state.

Panther is shipped with the debugger already linked in for client executables. To enable debugging for server executables, your standard server (refer to "Server Details" in JetNet/Oracle Tuxedo Guide) must be initialized as a debuggable server.

Starting and Stopping the Debugger

The debugger runs in the background during test and application modes, you can direct the debugger to run automatically, or you can manually break execution. The debugger follows the directions you give it and awakens accordingly—for instance, if an event triggers a breakpoint you have defined, or if the value of an expression you are monitoring has changed. The debugger comes to the foreground and awaits your action: provide additional analysis of the application, modify data, set breakpoints, or put it back to sleep and return control to your application.

To enable the debugger from the screen editor:

Choose OptionsEnable Debugger. This instructs the debugger to awaken immediately upon entry into test mode.

To enable and access the debugger in test or application mode:

Choose OptionsDebugger, or press the DBUG key. To put the debugger to sleep and return to test mode, choose FileResume Application.

If your application's menu bar is displayed, you can enter the debugger by pressing the DBUG key or switch menu bar scope by pressing the SFTS logical key, from where you will have access to OptionsDebugger.

To end a debugger session

Do either of the following:

Choose FileResume Application to put the debugger to sleep and continue running/testing your application. Panther preserves the debugger state; if the debugger is reentered, all breakpoints and configuration preferences remain unchanged. Moreover, all breakpoints and break events are ignored until you explicitly reactivated the debugger.
Choose FileExit Application to about the current JPL execution and quit the debugger. If you entered the debugger from application mode, you can choose to resume in application mode or exit Panther to the operating system. If you were in test mode, you return to the screen editor. Use this option to break out of infinite loops.

Views into Your Application

The debugger provides several windows to monitor application execution, each offering a different view into the application. The windows can be opened and closed from the debugger's View menu by choosing from these options:

Status

Displays the current debugger operation or event being traced.

Source Code

Displays screen- or widget-level JPL, library or external module JPL in the Source Code window. You can set or unset a breakpoint at the current line in the displayed code (at the cursor position) by choosing Breaks

Toggle Location Break or by double clicking anywhere in the line. Breakpoints are identified by an asterisk following the line number. For more information on using the Source Code window, refer to "Viewing JPL."

Breakpoints

Lists all breakpoints. In normal mode, predefined breakpoints are listed: screen events, LDB events, control strings, JPL trace, field events, group events, installed functions, database events, TM events and grid events. Location breakpoints that are set as well as breakpoints you create in expert mode are also listed. In expert mode, the predefined list of breakpoints are not displayed. A plus sign (+) preceding a breakpoint indicates active, and a minus sign indicates inactive.

Figure 39-1 The Breakpoints window shows currently identified breakpoints.

Activate or deactivate a selected breakpoint by choosing BreaksEnable or BreaksDisable or by double clicking on the item. Use BreaksSelect All if you want to enable or disable all listed breakpoints.

Choose BreaksShow Source to view the source code associated with a location breakpoint.

For more information on setting breakpoints, refer to "Setting Breakpoints."

Data Watch

Monitor the values of any variables, JPL expressions, or values of properties. Enter the name of the variable or the expression. The values are updated and displayed as execution proceeds.

Event Stack

Displays the hierarchy of nested calls to procedures and/or control strings during JPL or control string execution.

Figure 39-2 View the call hierarchy in the Event Stack window.

Pending Keys

Displays which keys are pushed onto the input queue.

Configuring the Debugger

You set debugger operation preferences via the Options menu, and they are saved in the file prodebug.cfg in the current working directory. You should not manually modify this file.

Setting Log File Preferences

Debugger activity can be logged to a user-specified file.

To access the log file preferences:

Choose OptionsStatus Log. The Status Log Options dialog box opens.

Figure 39-3 The Status Log Options dialog allows you to specify your log file preferences.

From the Status Log options dialog, you can:

Enable the log file—from the start of the session, all events are logged.
Specify the log file to which debugger activity messages should be logged. The default file is prodebug.log in the current working directory.
Specify whether or not to append to the existing log file or overwrite it.
Specify whether to log a date/time stamp to each new entry in the log file. Setting a date/timestamps can affect performance on some platforms.

To view the contents of the log file:

Choose FileOpenLog File anytime while using the debugger.

Setting Debugger Preferences

The following debugger preferences are available from the Options menu:

Save Preferences on Exit

Saves window configurations and other debug settings that are in effect when you exit this session. This option also saves the contents of any Data Watch and Breakpoints settings.

Expert Mode

Runs the debugger in expert mode.

Auto Raise/Close

Provides automatic window management. When set, the debugger determines which windows contain any relevant data at the moment, and raises them accordingly. It also closes those that were open during the last debugger invocation if they do not have any relevant data.

When this option is disabled, the debugger, when awakened, restores its windows exactly as you left them.

Animation

Executes the debugger in animation mode. The debugger shows changes to its windows as they occur, while waiting for a breakpoint to be executed.

Trace Database Warnings

Includes all warnings in database events tracked by the debugger.

Trace TM Warnings

Includes all warnings in transaction manager events tracked by the debugger.

Debugger Menu Bar

The debugger menu bar provides easy access to debugging operations. Following is a brief overview of the File, View and Tools menu options. The features controlled by the remaining menu options are described in their own task-defined sections; a cross-reference is defined for these options.

Figure 39-4 The debugger menu bar includes a Tools menu option when the debugger is run in expert mode.

Viewing JPL

To access JPL in libraries, the module must be in binary format and must also include the JPL source code. For information on compiling JPL source code, refer to page A-20.

To view screen- and widget-level JPL validation, or library JPL modules:

Choose ViewSource Code. The Source Code Window opens.

Figure 39-5 The Source Code window displays a JPL module with a breakpoint set at line 48.

The Source Code window can display any JPL code contained within your application. It can be:

Current source code — Source currently being executed. Current source code is automatically displayed when the debugger is stepping through it.
Active source code — Code that is on the program stack, where it might be waiting for current or intermediate JPL or some other event to complete.
Inactive source code — JPL procedures that are part of the application but have not yet been called or have already returned. If inactive source code is read into the Source Code window, it is referred to as called-up source code. To read called-up source code into the Source Code window, choose FileOpen Source Module. The debugger's file browsing mechanism is displayed. In this way you can also view any text files in the Source Code Window (including C source code files), but you cannot set breakpoints in them.

You can set breakpoints on any line of code that is displayed in the window. The Edit menu provides string search capabilities.

Opening a Source Module

From the Open Source Module dialog box you can specify a module to read into the Source Code window. You can also select a module from which to establish a location breakpoint.

Figure 39-6 Specify a module to read into the Source Code window or select a module for the Edit Breakpoint window in Location mode.

To read a JPL module into the Source Code window:

Choose FileOpenSource Module. The Open Source Module Window opens.
Choose the Browse In button and select the location of the module:
Select the JPL module from the library or the browser and choose OK. The type of the module selected is displayed set in the Load Module As option menu, and indicates one of the following types: JPL file, screen JPL, field (widget) JPL, grid JPL, or text file.
If a request to open a screen contains JPL modules of more than one type, for instance screen- and widget-level JPL, the choices are listed in the Load Module As option menu. Select the desired type of JPL module.

Figure 39-9 Screen JPL associated with a screen or service component can be selected for viewing.
Choose OK. The Source Code window displays the contents of the specified module.

Figure 39-10 The Source Code window displays screen JPL code from a specific screen.

on page 39-24To set breakpoints in the Source Code window:

Choose BreaksToggle Location Break, or double-click anywhere in the line. This option toggles a breakpoint on or off on the current line of code. Breakpoints are identified by an asterisk following the line number.

Viewing Application Screen Information

The debugger provides access to the programmatic components of your application, such as screens and service components. To view the programmatic details, choose WindowsApplication and select the desired item from the list. The selected item comes to the foreground and you can access details for the following options from the Application Window menu:

Screen JPL

Displays JPL in the Source Code window. This is an alternative to using File

Open

Source Module (refer to page 39-12).

Screen Information

Displays screen information in the Screen Inquire window. If the screen has its own JPL, the Show JPL button is enabled.

Figure 39-11 The Screen Inquire window displays useful information about the selected screen.

Field Information

Displays information related to widgets on your screen in the Field Inquire window. If the widget has its own JPL, the Show JPL button is enabled.

Figure 39-12 The Field Inquire window displays useful information about widgets on a screen.

Group Information

Displays information related to groups on the screen in the Group Inquire window.

Figure 39-13 The Group Information window.

Control Strings

Invokes the Control Strings window, which shows all function keys and Panther logical keys that are assigned control strings at the application- and screen-levels.

Figure 39-14 The Control Strings window shows that Ctrl+E is mapped to the Esc key.

Done

Returns to the debugger menu bar.

Notes: To see additional properties or attributes of any screen or widget you can use the JPL properties syntax to define an expression in the Data Watch or Application Data windows.

Refer to page 39-26 for information on using the Application Data window.

Refer to page 39-27 for information on using the Data Watch window. For information on JPL properties syntax, refer to page 19-33.

You can use Data Watch to inspect a property of the application, a screen, or widget, with an expression using the JPL properties syntax.

Stepping through Program Execution

When the debugger breaks program execution and comes to the foreground, you can step through the execution of your application with the options provided by Trace menu (or via the debugger toolbar):

To Any Event: If the current context is a JPL procedure or control string, the debugger steps to the next executable statement or string and stops. Otherwise, the debugger stops at the next event.
To Breakpoint: Program execution resumes until the next breakpoint is reached.

If you run the debugger in expert mode you can fine tune tracing to differentiate between parent, child, and same-level events. Choose the appropriate level:

To EventAny Level

If the current context is a JPL procedure or control string, the debugger steps to the next executable statement or string and stops. Otherwise, the debugger stops at the next event. This option is the same as TraceTo Any Event in normal mode.

To EventThis Level

If the current context is a JPL procedure call, the debugger "steps over" that procedure's statements, and breaks on the next statement at the same level, if any. If the context is a control string, the debugger steps over any strings embedded within it. Otherwise, the debugger breaks at the next event ignoring sub-events.

To EventHigher Level

Breaks only at the next level up in the event stack. If execution is already at the topmost level, program execution resumes, breaking only for JPL breakpoints.

Using Animation

You can set the debugger to run on automatic pilot, where application execution events can be observed hands-off in the various View windows.

To enable automatic stepping:

Choose OptionsAnimation.
Choose TraceTo Breakpoint. The debugger refreshes all open windows on each execution event until the next breakpoint occurs.
For example, if the Source Code window is open, the debugger scrolls through each line in the current JPL procedure as it executes; if the Data Watch window is open, variable values are refreshed whenever they change.

Animation proceeds until you toggled it off from the Options menu or interrupt it with the EXIT key.

Setting Breakpoints

The debugger recognizes all major execution events in a Panther application as potential breakpoints, with the exception of request broker events.

Breakpoints can be set at:

Locations in code: JPL statements (screen- and widget-level as well as in library modules).
Program execution events and subevents.
Value changes in a variable or expression.

The debugger gets control at every execution event and potential breakpoint. It then decides whether or not to awaken, and whether or not to break execution. The decision is based on your Trace choice, and whether breakpoint conditions are satisfied.

If you are not running the debugger in normal mode, you can set location breakpoints in the Source Code window and modify the predefined execution events in the Breakpoints window. In expert mode, you can you can add and modify breakpoints of both types via the Edit Breakpoint window.

Setting Location Breakpoints

Location breakpoints are JPL statements that are marked in order to stop program execution. The debugger comes to the foreground whenever Panther encounters them. You can set breakpoints on any JPL code that is displayed in the Source Code window—on both called-up source code as well as current (active) source code.

Refer to page 39-11 for information on viewing JPL.

To set or clear a location breakpoint:: Select a line of code in the Source Code window and choose BreaksToggle Location Break, or double click on the line. The breakpoint is toggled on or off. Breakpoints are indicated with an asterisk (*).

Setting Breakpoints on Execution Events

You can set breakpoints at a variety of execution events. A finer control of event filtering is available for certain GUI events when running the debugger in expert mode. Request broker events are not recognized by the debugger.

Table 39-1 list the types of execution events on which you can set breakpoints

**Table 39-1 Predefined execute events on which to set breakpoints**
Event type	Description
Screen events	Breaks on all screen entry and exit events. Screen events have subevents defined, which you can selectively enable in expert mode.
LDB events	Breaks on each LDB read or write operation.
Control strings	Breaks on execution of each control string. If you have em bedded control strings, the debugger breaks on each depending on the current step level.
JPL trace	Breaks on every line of JPL execution. To step through each line of code, choose TraceBreakpoint. To break at a specific line, toggle break on the line in the Source Code window and turn off JPL Trace in the Breakpoints window. Trace to Breakpoint continues execution and breaks at the specific line of code.
Field events	Breaks on all widget entry, validation, and exit events. Field events have subevents defined, which can be accessed in expert mode.
Group events	Breaks on all group entry and exit events. Group events have subevents defined.
Installed functions	Breaks when Panther is about to call any C function (installed by calling `sm_install` or identified in fun `clist.c`). The debugger recognizes calls to automatic functions, for example, the automatic screen function that is called on all screen entry and exit events, as well as other contexts where a C function can be called, such as in a control string with a JPL call statement, or upon field entry.
Database events	Breaks on any database interface event, including DBMS commands and SQL statements.
TM events	Breaks on any transaction manager event: transaction manager commands, requests, and slices.
Grid events	Breaks on any grid widget events. Grid events have subevents defined, which can be accessed in expert mode.

To set a breakpoint on a specific event type:

Choose ViewBreakpoints. The Breakpoints window is displayed with the predefined events listed.
Select the event from the list. Do either of the following:
- Choose BreaksEnable.
- Double-click on the item.
  
  Disable a breakpoint by double-clicking on it or choose BreaksDisable. An activated event breakpoint is indicated by a plus sign (+) prefix; an inactivate breakpoint is prefixed with a minus sign (-).

To add and modify breakpoints (in export mode):

Choose OptionsExpert Mode. Choose BreaksAdd or Edit. The Edit Breakpoint dialog opens.

You can add and edit both location and event breakpoints, and perform other actions. There are two modes: Event and Location. Select the appropriate check box: Break At Event for events (the default setting), and Break At Location to edit source code breakpoints.

Figure 39-15 In expert mode, use the Edit Breakpoints dialog to add or modify breakpoints of all types.

To break on specific events or subevents (in expert mode):

From the Edit Breakpoints dialog box, choose the Break at Event radio button.

Select the event from the At option menu. If the selected event has subevents defined, a subevent option menu is available. The events and their subevents are listed in Table 39-2.

**Table 39-2 Events and corresponding subevents available for breakpoints**
Screen events	Field events	Group events	Grid events
Any subevent	Any subevent	Any subevent	Any subevent
Entry	Entry	Entry	Grid entry
Exit	Exit	Exit	Grid exit
	Validation	Validation	Row entry
	Calculation		Row exit
			Validation

(Optional) Indicate by checking or unchecking the Active Breakpoint check box if the item should be added to the list of breakpoints in an active or inactive state.
Choose OK. The event is added to the list of breakpoints (in the Breakpoints window).

To set a breakpoint at a specific location (in expert mode):

In general, it is easier to set location breakpoints by reading the code into the Source Code dialog box and double-click directly on the specific line of code to set the breakpoint.

Refer to page 39-16 for details on setting breakpoints in the Source Code window. Or, you can set a breakpoint from the Edit Breakpoint dialog box:

From the Edit Breakpoint dialog box, choose the Break at Location radio button.
Enter a line number and module at which to establish a breakpoint in the Line and Module fields, or choose Browse to select the module from the Open Source Module.
For instruction on how to identify source code from the Open Source Module, refer to page 39-12. Once you choose the module from Open Source Module, the Edit Breakpoint dialog box redisplays.

Figure 39-16 Use the Edit Breakpoint dialog box in Location mode to set a code location breakpoint.
(Optional) Indicate by checking or unchecking the Active Breakpoint check box if the item should be added to the list of breakpoints in an active or inactive state.
Choose OK. The location breakpoint is added to the list of breakpoints (in the Breakpoints dialog).

Break on Change in Expression

You can direct the debugger, in expert mode, to make activation of a breakpoint dependent upon the value of an expression.

To create a breakpoint on an expression value (in expert mode):

Choose BreaksAdd or Edit. The Edit Breakpoint dialog box opens.
Enter a valid JPL expression in the On Change in Expression field. This causes the debugger to only stop at the event/location breakpoint (assuming it has been activated) if the value of the expression changes, that is, if the value changes from what it was when TraceTo Breakpoint was chosen.
Set break at Any Event if you want the debugger to awaken as soon as the change occurs.

To call a specified function (in expert mode):

From the Edit Breakpoints dialog box, enter the JPL or installed function to be executed in the Call on Break field. The debugger calls the specified function each time the breakpoint is reached.

To instruct the debugger to call the function without stopping execution, check Continue After Call.

Monitoring Variables and JPL Expressions

When running the debugger you can examine the contents of variables or expressions and observe runtime changes. Use the Data Watch window to inspect a property of the application, a screen, or widget, with a JPL expression. For more information on referencing Panther objects and properties, refer to page 19-33 .

To view data changes:

Choose ViewData Watch. The Data Watch window opens and displays the names of variables and expressions along with their current values (if defined).
If variable is an array and you have defined as a range of values to watch, the variable is represented as
```
@range("
```
```
variable
```
```
",
```
```
 startOcc
```
```
, 
```
```
endOcc). For example, 
```
```
@range("title_id",2,4)
```
```
displays the title_id values associated with the second through fourth occurrence of an array.
```
Enter the names of the variables or expressions you want to observe.
The debugger displays the values of the variables/expressions in the Data Watch window, updating them as execution proceeds. The location of any variables specified is also identified.

To clear a variable/expression, delete it from the list. To clear all variables/expression, press CLR.

Modifying and Monitoring Application Data

Run the debugger in expert mode to take advantage of the data watching abilities available with the Application Data window.

To view and access data from any variable used in source code (in expert mode):

Access the desired source module (refer to page 39-12 for details on opening the Source Code window).
Position the cursor in the desired variable.
Choose ToolsApplication Data to open the Application Data window.
From the Application Data window, you can: