Debugging an application

Sometimes an application doesn’t behave the way you
think it will. Perhaps a variable is not being assigned the value
you expect, or a script doesn’t perform as desired. In
these situations, you can examine your application by running it in
debug mode.

When you run the application in debug mode, PowerBuilder stops
execution before it executes a line containing a breakpoint (stop).
You can then step through the application and examine its state.

To debug an application:

1. Open the debugger.

2. Set breakpoints at places in the application where
   you have a problem.

3. Run the application in debug mode.

4. When execution is suspended at a breakpoint, look
   at the values of variables, examine the properties of objects in
   memory and the call stack, or change the values of variables.

5. Step through the code line by line.

6. As needed, add or modify breakpoints as you run
   the application.

7. When you uncover a problem, fix your code, and
   run in the debugger again.

Debugging distributed applications You can debug a PowerBuilder component deployed to Jaguar CTS.
For more information, see the chapter on troubleshooting distributed
applications in Application Techniques
.

Starting the debugger

If the application you want to debug is not the current application,
select the application you want to debug before you open the debugger.

To open the debugger:

1. Select File>Debug from the menu
   bar.

   or

   Select Debugger from the Tool tab in the New dialog
   box.

   or

   Click the Debug button on the PowerBar.

Views in the debugger

The debugger contains several views. Each view shows a different
kind of information about the current state of your application
or the debugging session. The following table summarizes what each
view shows and what you can do from that view:

View	What it shows	What you can do
Breakpoints	A list of breakpoints with indicators showing whether the breakpoints are currently active or inactive	Set, enable, disable, and clear breakpoints, set a condition for a breakpoint, and show source for a breakpoint in the Source view
Call Stack	The sequence of function calls leading up to the function that was executing at the time of the breakpoint, shown as the script and line number from which the function was called	Examine the context of the application at any line in the call stack
Instances	Instances of remote objects and their current status	Change the context of the debugging session to a different instance. This view is only available if you are debugging a remote component
Objects in Memory	An expandable list of objects currently in memory	View the names and memory locations of instances of each memory object and property values of each instance. This view is not used if you are debugging a remote component
Source	The full text of a script	Go to a specific line in a script, find a string, open another script, including ancestor and descendant scripts, and manage breakpoints
Source Browser	An expandable hierarchy of objects in your application	Select any script in your application and display it in the Source view
Source History	A list of the scripts that have been displayed in the Source view	Select any script in the Source History and display it in the Source view
Variables	An expandable list of all the variables in scope	Select which kinds of variables are shown in the view, change the value of a variable, and set a breakpoint when a variable changes
Watch	A list of variables you have selected to watch as the application proceeds	Change the value of a variable, set a breakpoint when a variable changes, and add an arbitrary expression to the Watch view

Changing Variable views

The default debugger layout contains a separate pane for each
variable type. You can combine two or more Variables views in a
single pane:

To display multiple Variable views in a single
pane:

1. Display the popup menu for a pane that
   contains a Variables view you want to change.

2. Click the names of the variable types you want
   to display.

   A checkmark displays next to selected variable types. The
   popup menu closes each time you select a variable type or clear
   a checkmark so you will need to reopen the menu to select additional
   variable types.

   When you select or clear variable types, the tab for the pane
   changes to show the variable types displayed on that pane.

   

Setting breakpoints

A breakpoint is a point in your application
code where you want to interrupt the normal execution of the application
while you are debugging. If you suspect a problem is occurring in
a particular script or function call, set a breakpoint at the beginning
of the script or at the line where the function is called.

When you close the debugger, any breakpoints you set are written
to your PowerBuilder initialization file and are available when you
reopen the debugger.

Setting a simple breakpoint

This procedure describes setting a breakpoint in the Source
view in the debugger. You can also set a breakpoint by selecting
Add Breakpoint from the popup menu in the Script view when you are
not running the debugger.

To set a breakpoint on a line in a script:

1. Display the script in a Source view and
   place your cursor where you want to set the breakpoint.

   For how to change the script shown in the
   Source view, see “Using the Source
   view”.

2. Double-click the line.

   or

   Select Add Breakpoint from the popup menu.

   PowerBuilder sets a breakpoint and a red circle displays at
   the beginning of the line. If you select a line that doesn’t
   contain executable code, PowerBuilder sets the breakpoint at the beginning
   of the next executable statement.

Setting special breakpoints

Breakpoints can be triggered when a statement has been executed
a specified number of times (an occasional breakpoint), when a specified
expression is true (a conditional breakpoint), or when the value
of a variable changes.

Opening the Edit Breakpoints dialog box You use the Edit Breakpoints dialog box to set and edit occasional
and conditional breakpoints. You can also use it to set a breakpoint
when the value of a variable changes.

To open the Edit Breakpoints dialog box:

1. Click the Edit Stop button on the PainterBar.

   or

   Select Breakpoints from the popup menu in the Source,
   Variables, Watch, or Breakpoints view.

   or

   Select Edit>Breakpoints from the menu bar.

   or

   Double-click a line in the Breakpoints view.

Setting occasional and conditional breakpoints

If you want to check the progress of a loop without interrupting
execution in every iteration, you can set an occasional breakpoint
that is triggered only after a specified number of iterations. To
specify that execution stops only when conditions you specify are
met, set a conditional breakpoint. You can also set both occasional
and conditional breakpoints at the same location.

• If you
  specify an occurrence Each time PowerBuilder passes through the specified location
  it increments a counter by one. When the counter reaches the number
  specified, it triggers the breakpoint and resets the counter to
  zero.
• If you specify a condition Each time PowerBuilder passes through the specified location
  it evaluates the expression. When the expression is true, it triggers
  the breakpoint.
• If you specify both an occurrence and
  a condition Each time PowerBuilder passes through the specified location
  it evaluates the expression. When the expression is true, it increments
  the counter. When the counter reaches the number specified, it triggers
  the breakpoint and resets the counter to zero.
  For example, if you specify an occurrence of 3 and the condition notisNull(val), PowerBuilder checks
  whether val is NULL each time the statement is reached. The breakpoint
  is triggered on the third occurrence of a non-NULL val, then again
  on the sixth occurrence, and so forth.

To set an occasional or conditional breakpoint:

1. On the Location tab in the Edit Breakpoints
   dialog box, specify the script and line number where you want the
   breakpoint.

   You can select an existing location or select New to enter
   a new location.

   Set a simple breakpoint first You must specify a line that contains executable code. Set
   a simple breakpoint on the line before opening the Edit Breakpoints
   dialog box to ensure the format and line number are correct.

2. Specify an integer occurrence, a condition, or
   both.

   The condition must be a valid boolean PowerScript expression
   (if it is not, the breakpoint is always triggered). PowerBuilder displays
   the breakpoint expression in the Edit Breakpoints dialog box and
   in the Breakpoints view. When PowerBuilder reaches the location where
   the breakpoint is set, it evaluates the breakpoint expression and
   triggers the breakpoint only when the expression is true.

Setting a breakpoint when a variable changes

You can interrupt execution every time the value of a variable
changes. The variable must be in scope when you set the breakpoint.

To set a breakpoint when a variable changes:

1. Select the variable in the Variables view
   or Watch view and select Break on Change from the popup menu.

   or

   Drag the variable from the Variables view or Watch view
   to the Breakpoints view.

   or

   Select New on the Variable tab in the Edit Breakpoints
   dialog box and specify the name of a variable in the Variable textbox.

   The new breakpoint displays in the Breakpoints view and in
   the Edit Breakpoints dialog box if it is open. PowerBuilder watches
   the variable during execution and interrupts execution when the
   value of the variable changes.

Disabling and clearing breakpoints

If you want to bypass a breakpoint for a specific debugging
session, you can disable it and then enable it again later. If you
no longer need a breakpoint, you can clear it.

To disable a breakpoint:

1. Click the red circle next to the breakpoint
   in the Breakpoints view or Edit Breakpoints dialog box.

   or

   Select Disable Breakpoint from the popup menu in the
   Source view.

   or

   Select Disable from the popup menu in the Breakpoints
   view.

   The red circle next to the breakpoint is replaced with a white
   circle.

   You can enable a disabled breakpoint from the popup menus
   or by clicking the white circle.

Disabling all breakpoints To disable all breakpoints, select Disable All from the popup
menu in the Breakpoints view.

To clear a breakpoint:

1. Double-click the line containing the breakpoint
   in the Source view.

   or

   Select Clear Breakpoint from the popup menu in the Source
   view.

   or

   Select Clear from the popup menu in the Breakpoints
   view.

   or

   Select the breakpoint in the Edit Breakpoints dialog
   box and select Clear.

   The red circle next to the breakpoint disappears.

Clearing all breakpoints To clear all breakpoints, select Clear All in the Edit Breakpoints
dialog box or from the popup menu in the Breakpoints view.

Running in debug mode

Once you have set your breakpoints, you can run the application
in debug mode. The application executes normally until it hits a
statement containing a breakpoint. After examining your application,
you can single-step through it, continue execution until execution
reaches another breakpoint, or stop the debugging run so that you
can start a new debugging run or close the debugger.

To run an application in debug mode:

1. If necessary, open the debugger by clicking
   the Debug button.

2. Click the Start button in the PainterBar.

   or

   Select Debug>Start from the menu bar.

   The application starts and runs until it hits a breakpoint.
   You return to the debugger, with the line containing the breakpoint
   displayed. The yellow arrow cursor indicates that this line contains
   the next statement to be executed. You can now examine the application
   using debugger views and tools.

   For more information, see “Examining an application
   at a breakpoint” and “Stepping through an application”.

To continue execution from a breakpoint:

1. Click the Continue button in the PainterBar.

   or

   Select Debug>Continue from the menu bar.

   Execution begins at the statement indicated by the yellow
   arrow cursor and continues until the next breakpoint is hit or until
   the application terminates normally.

To terminate a debugging run at a breakpoint:

1. Click the Stop Debugging button in the
   PainterBar.

   or

   Select Debug>Stop from the menu bar.

   PowerBuilder resets the state of the application and all the
   debugger views to their state at the beginning of the debugging
   run. You can now begin another run in debug mode, or close the debugger.

Cleaning up When you terminate a debugging run or close the debugger without terminating
the run, PowerBuilder executes the application’s close event
and destroys any objects, such as autoinstantiated local variables,
that it would have destroyed if the application had continued to
run and exited normally.

Examining an applicationat a breakpoint

When an application is suspended at a breakpoint, use the
Variables, Watch, Call Stack, and Objects in Memory views to examine
its state.

About icons used in debugging views The Variables, Watch, and Objects in Memory views use many
of the icons used in the PowerBuilder Browser as well as some additional
icons: I represents an Instance; F, a field; A, an array; and E,
an expression.

Examining variable values

Each Variables view shows one or more types of variables in
an expandable outline. Double-click the variable names or click
on the plus and minus signs next to them to expand and contract
the hierarchy. If you open a new Variables view, it shows all variable
types.

Variable type	What the Variables view shows
Local	Values of variables that are local to the current script or function
Global	Values of all global variables defined for the application and properties of all objects (such as windows) that are open
Instance	Properties of the current object instance (the object to which the current script belongs) and values of instance variables defined for the current object
Parent	Properties of the parent of the current instance
Shared	Objects, such as application, window, and menu objects, that have been opened and the shared variables associated with them

About Instance and Parent variables In the following illustration, an application has stopped
at a breakpoint in the script for the Clicked event for the Close
menu item on a frame’s File menu. The Instance tab shows
the properties of the current instance of the Close menu item. The
Parent tab shows the properties of its parent, an instance of the
File menu. Navigating through the hierarchy on the Global tab shows
the same objects.

Watching variables and expressions

The Watch view lets you monitor the values of selected variables
and expressions as the application runs.

If the variable or expression is in scope, the Watch view
shows its value. Empty quotes indicate that the variable is in scope
but has not been initialized. An X in the Watch view indicates that
the variable or expression is not in scope.

Setting variables and expressions in the Watch
view

You can select variables you want to watch as the application
runs by copying them from a Variables view. You can also set a watch
on any PowerScript expression. When you close the debugger, any
watch variables and expressions you set are written to your PowerBuilder initialization
file.

To add a variable to the Watch view:

1. Select the variable in the Variables view.

2. Drag it to the Watch view.

   or

   Click the Add Watch button on the PainterBar.

   or

   Select Debug>Add Watch from the menu bar.

   PowerBuilder adds the variable to the watch list.

To add an expression to the Watch view:

1. Select Insert from the popup menu.

2. Type any valid PowerScript expression in the New
   Expression dialog box and click OK.

   PowerBuilder adds the expression to the watch list.

To edit a variable in the Watch view:

1. Select the variable you want to edit.

2. Double-click the variable.

   or

   Select Edit Variable from the popup menu.

3. Type the new value for the variable in the Modify
   Variable dialog box and click OK.

To edit an expression in the Watch view:

1. Select the expression you want to edit.

2. Double-click the expression.

   or

   Select Edit Expression from the popup menu.

3. Type the new expression in the Edit Expression
   dialog box and click OK.

To clear variables and expressions from the Watch
view:

1. Select the variable or expression you want
   to delete.

2. Select Clear from the popup menu.

   or

   Click the Remove Watch button on the PainterBar.

   or

   Select Debug>Remove Watch from the menu bar.

To clear all variables and expressions from the
Watch view:

1. Select Clear All from the popup menu

Monitoring the call stack

The Call Stack view shows the sequence of function calls leading
up to the script or function that was executing at the time of the
breakpoint. Each line displays as the script and line number from
which the call was made. The yellow arrow shows the script and line
where execution was suspended.

You can examine the context of the application at any line
in the call stack.

To show a different context from the Call Stack
view:

1. Select a line in the Call Stack view.

2. Double-click the line.

   or

   Select Set Context from the popup menu.

   or

   Drag the line into the Source view.

   A green arrow indicates the script that you selected. The
   Source view shows the script and line number you selected, and the
   Variables and Watch views show the variables and expressions in
   scope in that context.

   

Examining objects in memory

The Objects in Memory view shows an expandable list of objects
currently in memory. Double-click the name of an object or click
the plus sign next to it to view the names and memory locations
of instances of each object and property values of each instance.

Using the Source
view

The Source view displays the full text of a script. As you
run or step through the application, the Source view is updated
to show the current script with a yellow arrow indicating the next
statement to be executed.

Multiple Source views You can open more than one source view. If there are multiple
source views open, only the first one opened is updated to show
the current script when the context of an application changes.

Changing the Source view From the popup menu, you can navigate backward and forward
through the scripts that have been opened so far, open ancestor
and dependent scripts, and go to a specific line in the current
script. There are several other ways to change the script from other
views or from the menu bar.

To change the script displayed in a Source view:

1. Drag the name of a script to the Source
   view from the Call Stack, Source Browser, or Source History views.

   or

   Select a line and then select Open Source from the popup
   menu in the Breakpoints, Source Browser, or Source History views.

   or

   Select Edit>Select Script from the menu bar.

To find a specified string in the Source view:

1. Select Find from the popup menu.

   or

   Select Edit>Find from the menu bar.

   The Find Text dialog box opens.

2. Type the string in the Find textbox and check
   the search options you want.

Using the Source Browser view

The Source Browser shows all the objects in your application
in an expandable hierarchy. It provides a view of the structure
of the application and a quick way to open any script in the Source
view.

To open a script from the Source Browser:

1. Double-click the object that the script
   belongs to or click the plus sign next to the object to expand it.

2. Double-click the script.

   or

   Select the script and select Open Source from the popup
   menu.

   or

   Drag the script onto a Source view.

   When you double-click or select Open Source, a new Source
   view opens if there was none open. If several Source views are open,
   the script displays in the view that was used last.

Using the Source History view

The Source History view lists all the scripts that have been
opened in the current debugging session. Use the same techniques
as in the Source Browser to display a selected script in the Source
view.

Source History limit The Source History view shows up to 100 scripts and is not
cleared
at the end of each debugging run. It is cleared when you close the
debugger, or you can clear the list from the popup menu.

Stepping through an application

When you have stopped execution at a breakpoint, you can use
several commands to step through your application code and use the
views to examine the effect of each statement. As you step through
your code, the debugger views change to reflect the current context
of your application and a yellow arrow cursor indicates the next
statement to be executed.

Updating the Source view When the context of your application changes to another script,
the Source view is updated with the new context. If you have multiple
Source views open, only the first one opened is updated.

Single-stepping through an application

You can use either Step In or Step Over to step through an
application one statement at a time. They have the same result except
when the next statement contains a call to a function. Use Step
In if you want to step into a function and examine the effects of
each statement in the function. Use Step Over to execute the function
as a single statement.

To step through an application entering functions:

1. Click the Step In button in the PainterBar.

   or

   Select Debug>Step In from the menu bar.

To step through an application without entering
functions:

1. Click the Step Over button in the PainterBar.

   or

   Select Debug>Step Over from the menu bar.

Adding shortcut keys To make it easier to step through your code, select Window>Keyboard Shortcuts
to define shortcuts for Step In, Step Over, and Continue.

Stepping out of a function

If you step into a function that you don’t want to
single step through, use Step Out to continue execution until the
function returns.

To step out of a function:

1. Click the Step Out button in the PainterBar

   or

   Select Debug>Step Out from the menu bar.

Stepping through multiple statements

As you step through an application, you may reach sections
of code that you are not interested in examining closely. The code
may contain a large loop, or it may be well-tested code that you
are confident is free of errors. You can use Run To Cursor to select
a statement further down in a script or in a subsequent script where
you want execution to stop.

To step through multiple statements:

1. Click on the line in the script where you
   want to resume single stepping.

2. Click the Run To Cursor button in the PainterBar.

   or

   Select Debug>Run To Cursor from the menu bar.

   PowerBuilder executes all intermediate statements and the yellow
   arrow cursor displays at the line where you set the cursor.

Bypassing statements

You can use Set Next Statement to bypass a section of code
that contains a bug, or to test part of an application using specific
values for variables. Execution continues from the statement where
you place the cursor. Be cautious when you use Set Next Statement,
because results may be unpredictable if, for example, you skip code
that initializes a variable.

To set the next statement to be executed:

1. Click on the line in the script where you
   want to continue execution.

2. Click the Set Next Statement button in the PainterBar.

   or

   Select Debug>Set Next Statement from the menu
   bar.

3. If necessary, change the values of variables.

4. Continue execution using Continue, Step In, or
   Step Over.

   If you select Continue, PowerBuilder begins execution at the
   statement set and continues to the next breakpoint. If you select
   Step In or Step Over, PowerBuilder sets the next statement and displays
   the yellow arrow cursor at the line where you set the cursor.

Changing a variable’s value

As you step through the application, you can change the values
of variables that are in scope. You may want to do this to examine
different flows through the application, to simulate a condition
that is difficult to reach in normal testing, or if you are skipping
code that sets a variable’s value.

Enumerated variables You cannot change the values of enumerated variables.

To change the value of a variable:

1. Select the variable in the Variables view
   or the Watch view.

2. From the popup menu, select Edit Variable.

3. Type a value for the variable or select the Null
   checkbox and click OK.

   The value you enter must conform to the type of the variable.
   If the variable is a string, do not enclose the string in quotes.
   When you continue execution, the new value is used.

Fixing your code

If you find an error in a script or function during a debugging
session, close the debugger before you fix it. After you have fixed
the problem, you can reopen the debugger and run the application
again in debug mode. The breakpoints and watchpoints set in your
last session are still defined.

Debugging windows opened as local variables

One way to open a window is by declaring a local variable
of type window and opening it through a string. For example:

The problem

Normally, you cannot debug windows opened this way after the
script ends because the local variable (mywin
in
the preceding script) goes out of scope when the script ends.

The solution

If you want to debug windows opened this way, you can declare
a global variable of type window and assign it the local variable.
Suppose GlobalWindow is a global window of type window, you could
add the following line to the end of the preceding script:

You can look at and modify the opened window through the global
variable. When you have finished debugging the window, you can remove
the global variable and the statement assigning the local to the
global.

Just-in-time debugging

If you are running your application in regular mode (using
the Run button) and you notice that the application is behaving
incorrectly, just-in-time debugging lets you switch to debug mode
without terminating the application.

When you open the debugger while running an application, the
application does not
stop executing. The Source,
Variables, Call Stack, and Objects in Memory views are all empty
because the debugger does not have any context. To suspend execution
and examine the context in a problem area, open an appropriate script
and set breakpoints, then initiate the action that calls the script.

If just-in-time debugging is enabled and a system error occurs
while an application is running in regular mode, the debugger opens
automatically, showing the context where the error occurred.

You can also use the DebugBreak function to break into the
debugger.

You must enable just-in-time debugging before you run your
application to take advantage of this feature.

To enable just-in-time debugging:

1. Select Window>System Options.

2. Check the Just In Time Debugging checkbox and
   click OK.

To debug an application while running in regular
mode:

1. Enable just-in-time debugging.

2. Run the application.

3. Click the PowerBuilder button on the Taskbar on
   Windows or the minimized PowerBuilder application icon on UNIX.

4. Click the Debug button in the dialog box that
   displays.

5. Open a script in the Source view and set breakpoints.

   The application is suspended when it hits a breakpoint and
   the Source, Variable, Call Stack, and Objects in Memory views show
   the current context. You can now debug the application.

---