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:

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:

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:

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:

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 BreaksToggle 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 BreaksShowSource 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:

To view the contents of the log file:

Choose FileOpenLogFile 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.

File

The operations associated with the File menu are:

Open
Allows you to open a source module, the current source code, or the log file. Information is displayed in the Source Code window. For more information on Source Code window operations, refer to "Viewing JPL."

Close Window
Closes the active window. If you attempt to close the last remaining window, the debugger prompts for a confirmation that you want to quit the debugger.

Save Preferences
Saves window configuration and other debug settings that are in effect at the present time for future debugger sessions. With this option, you can establish overall preferences, but make changes in the present session that will not affect those saved. Contrast with OptionsSave Preferences on Exit, which saves them at the state they are in when you exit. For more information on setting debugger configurations, refer to "Configuring the Debugger."

Resume Application
Puts the debugger to sleep and lets you continue executing your application.

Exit Application
Exits the debugger; terminates execution of your application.

Tools

The Tools menu is only available when running the debugger in expert mode, and includes the following features:

Application Data
View and access any variable displayed in the Source Code window. For information on using the Application Data window, refer to "Modifying and Monitoring Application Data."

Call
Invokes the Call Installed Function window where you can enter the name of any available prototyped function along with any arguments. The return value, if any, is displayed in the status window after the function returns. The function call is logged to the log file if it has been enabled.

Sort Breakpoints
Sorts all breakpoints listed in the Breakpoints window. Activated breakpoints are listed alphabetically, followed by inactive breakpoints.

Sort Watch Data
Sorts all variables and/or expressions listed in the Data Watch window. For further information on this window, refer to page 39-26 .

Write Windows to Log
Writes the contents of debugger windows to the log file. The log file must be enabled; to enable the log file, choose OptionsStatus Log Options and set Enable Status Log on the Status Log Options dialog.

View

The View menu provides several windows to monitor your application's execution. Refer to page 39-4 for a full description of the options available from the View menu.

Windows

Options available from the Windows menu allow you to:

Edit

The Edit menu commands provide standard file editing operations, such as Copy, Paste, and string search commands Find and Find Next, that you can use when accessing text data in the Source Code window. For more information on the Source Code window, refer to page 39-11.

Trace

The Trace options allow you to step through program execution one event or breakpoint at a time. For more information on tracing, refer to page 39-19.

Breaks

Breaks menu commands let you establish and manipulate breakpoints in your application—places where execution will be interrupted and the debugger will assume control. For further information on setting breakpoints, refer to page 39-20.

Options

Provides options for setting debugger preferences. For information on debugger preferences and configuration, refer to page 39-6 .


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-19.

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:

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:
  1. Choose FileOpenSource Module. The Open Source Module Window opens.
  2. Choose the Browse In button and select the location of the module:
  3. 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.

  4. 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 FileOpenSource 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:
  1. Choose OptionsAnimation.
  2. Choose TraceToBreakpoint. 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:

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 BreaksToggleLocationBreak, 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:
  1. Choose ViewBreakpoints. The Breakpoints window is displayed with the predefined events listed.
  2. Select the event from the list. Do either of the following:

To add and modify breakpoints (in export mode):
  1. 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):
  1. From the Edit Breakpoints dialog box, choose the Break at Event radio button.
  2. 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

  3. (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.
  4. 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:

  1. From the Edit Breakpoint dialog box, choose the Break at Location radio button.
  2. 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.

  3. (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.
  4. 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):
  1. Choose BreaksAdd or Edit. The EditBreakpoint dialog box opens.
  2. 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 TraceToBreakpoint was chosen.
  3. 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:
  1. 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.
  2. 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):
  1. Access the desired source module (refer to page 39-12 for details on opening the Source Code window).
  2. Position the cursor in the desired variable.
  3. Choose ToolsApplicationData to open the Application Data window.
  4. From the Application Data window, you can: