CHAPTER 9: Source Debugger

The Empress 4GL Source Debugger is a programming tool that is used to determine where and why runtime errors are occurring. Other types of software errors are normally detected when a program is compiled and/or linked.

Debuggers work by allowing the execution of a program to be stopped at various times. The current location within the program is available in the form of a stack trace. The values of variables can then be viewed or changed or the source code examined. The execution can then be continued or even single stepped. This allows you to determine where the variables are set to the wrong values or when the wrong branch of code is executed.

The Source Debugger is menu driven and uses windows to display information for the programmer. It behaves as a normal Empress 4GL application so it is very easy to learn and use.

There are several windows which allow you to look at different parts of the application that is being debugged. The applications, windows, key contexts, fields and scripts can all be examined. The table instances involved may be looked at as well as the attribute values of the current record for any instance. All system and application variables, fields and attributes can be displayed and/or modified. A window may be set up to display the values of variables, fields or attributes as the application progresses.

To control the application execution, there are breakpoints which can be set upon entry of a procedure, reaching a certain line in a script or changing the value of a variable. Also, single stepping is available to execute the application one line at a time and the <Interrupt> key can be used to halt the application and enter the debugging windows.

There is even a setup feature which allows the display of windows to be tailored to meet your specific needs. This setup can be saved in a file for future use.

Errors that cause the application to enter the debug environment include all Empress error conditions as well as any conditions that cause an error_message call to be executed.

There are several types of breakpoints which can be used in the Empress 4GL Source Debugger.

1. The first of these is the procedure breakpoint. This is simply a breakpoint that is set at the beginning of a script. This can include the application enter and exit scripts, field and key scripts as well as subscripts. As soon as the application calls the procedure, it is halted and the debug environment is entered.
2. The line breakpoint is similar to the procedure breakpoint, except it allows you to specify which line number the execution is to halt at. Rather than stopping at the very beginning of the procedure the Source Debugger waits until it is just about to execute the line of code that the breakpoint is set at. This is useful if a procedure is long or if you only want to break out while a certain branch of an IF/ELSE or SWITCH statement is executed.
3. A third type of breakpoint is the variable breakpoint. This breakpoint is set to enter the debug environment when the variable specified changes values or assumes a certain value. If a variable has an invalid value at the time of the error condition this can be a useful tool in determining when that value is being set.

9.3 General Functions

One of the most important functions is the Help function which will display a list of the functions that are being described in this section. This function replaces the normal Empress 4GL Help function with Source Debugger specific help.
 
Figure 9-1 Debugger Help Window

There will be a list of items within most of the windows in the application. Only one of them is current and it will usually be highlighted, but, the Select Next Item and Select Previous Item keys can be used to move through the list.

The functions relating to breakpoints will be discussed in detail in the next section.

For any window that is available in the Source Debugger, it is possible to alter the size and/or position of the window to suit your needs. When you issue the Zoom/Move Window function, the following menu is displayed. This menu outlines the functions for zooming a window. The functions for moving the window are on another menu which is displayed by the Move Window function.
 
Figure 9-3

In order to zoom (re-size) a window, one of the sides of the window that is being zoomed will have the cursor on the middle of it. The Select Edge function keys can be used to move the cursor to the other edges of the window. Once the edge that is to be moved is selected, the Move Edge keys can be used to determine where that edge will be placed. Note the edge is not actually moved, only the cursor. The Quit function key is used to tell the Source Debugger where the edge is to be made. At this time the window will be re-sized.

Keep in mind that you cannot make the window larger than the physical screen and it cannot be placed outside the boundaries of the screen.

The functions used to move a window are simple. The top left hand corner of the window will have the cursor on it. Use the Move Window keys to move the cursor to the position at which the upper left hand corner of the window will be. Pressing the Quit key will then move the window. Note once again that the window cannot be moved off the screen.
 
Figure 9-4

Both the Leave Current Window and Current Window Showing functions will return to the previous window. However, the first function will remove the window before passing control back. The second function will leave the window visible. The Current Window Showing is intended to be used for the View window so that it can be left visible while the application is single stepped or continued.

The Remove Debugger Window function will remove all the Source Debugger windows from the screen. They will still be active, but not visible. This allows you to see what the application windows look like while in the Source Debugger. Pressing the same key will bring the windows back.

This section will describe each of the screens which are available as well as the functions that can be performed in each. Note that all the windows in the figures are in their normal default locations unless otherwise specified.

The names in parentheses are used in the Setup function to refer to each window.

When first entering the Source Debugger environment the Status window and Main Menu are displayed.

The field name is in the standard Empress 4GL format for a field, i.e., `window'@`field'.

The script may either be blank or it may have the name of the script present. For key scripts the key label is used as the name. Field enter and exit scripts are named by the field name. For the application enter and exit scripts the name of the application is used. The script name will also have the current line number.

For example, if the application was halted in the AP_5 key script at line 7 the script would be "AP_5 line 7".

If in the enter or exit script of field_test, the script line reads field_test line 3. This indicates that it was halted on line 3 of the enter or exit script of field_test.

The Status field indicates why the application was halted. It can have one of four different values.

1. The first of these is *** Interrupt ***. This value indicates that the application was halted by the <Interrupt> key.
2. When single stepping through part of an application the status will be "Single Step".
3. If an error condition is the cause of the halt the status will be:** Error Condition **.
4. Finally, a breakpoint could be the cause of the halt. The status line will indicate the number and description of the breakpoint. For example, if a breakpoint number 2 is set to halt the application when var_1 is modified the status line would say:

[2] - variable `var_1'.

9.4.2 Main Menu (menu)

The Main Menu is displayed as soon as you enter the Source Debugger environment. It displays the functions that are available to you. These functions are described in the following sections.

The Quit function is used to exit from the application as well as the Source Debugger. It will return to the Empress Application Development environment. To exit from the Source Debugger back to the application that is being debugged you should use the normal Empress 4GL Quit key.

The top of the list will be the current script with the one that called it being underneath it and so on.

The Stack window also gives detailed information about each script. Along with the line number, it explicitly defines the procedure.

For the application enter and exit scripts the keyword APPLICATION is used as well as ENTER or EXIT. The actual application name is in quotes. For example:

application 'timelog' enter line 15

The key scripts are identified by the key context and key label which are separated by a dash, such as:

`key_context'-`AP_1' line 7

`window'@`field' format

`form1'@`name' exit line 1

`hypotenuse' (8, 4) line 3

** `timelog' ()

The menu will also be changed to reflect the options available. There is only one option, Source, which will display the Source window with the currently highlighted script in it. Note that although the Stack Trace window is initially displayed with the current script highlighted, the Select Next Item and Select Previous Item keys can be used to move throughout the list. Keep in mind that the actual application itself has no source to be displayed.

The menu for the View window contains only one function, the Delete function. This will remove the currently highlighted variable from the display. To add a variable to the View window see the sections on the Attributes window, Variables window and Fields window.

To return to the Main Menu without removing the View window, use the Current Window Showing function.

9.4.2.5 Step

The Source Debugger windows (except for the View window if it is visible) will be removed while the line of code is executed so that the entire screen is visible during the execution.

The windows that are available in the Source Debugger environment are listed along the right hand side of the Setup window. There will be an asterisk beside each of the windows that will be visible upon entry into the Source Debugger environment. Note that the Main Menu and Status window are the default windows. This can be changed for any of the windows using the No/Show function key when the name of the window is highlighted.

It is also possible to display any of the windows in order to see how they will appear on the screen using the Remove/Show function. You can then use the Move/Zoom function to move and/or re-size the window. This will cause the window to be displayed in that position and size from that point on in the debugging session.

You may also save a Definition for future sessions. The Dump function is used to accomplish this. All the information regarding the window setup will be stored in a file which will be used each time the Source Debugger environment is entered.

The setting of breakpoints is an important function of any Source Debugger. The Empress Source Debugger has several windows that allow the setting and unsetting of breakpoints. To enter these windows you must use the Set Breakpoint function.

A breakpoint can be set directly from this window by typing in the appropriate Definition and Condition. When these fields are appropriately filled in, the Set function can be used to put the breakpoint into place.
 
Figure 9-10

However, if you do not wish to type in the extra information required for each type of breakpoint then you may use the line, procedure or variable functions to call up windows in which to enter the values. These windows will then put the appropriate data into the Definition and Condition fields.

Note

You must remember to set the breakpoint after it has been defined.

The final function that is available from the Set window is the List Breakpoint. It will call up the Breakpoint List window described in a later section.

The Condition field on this window allows you to specify that the breakpoint is only to be used if a certain condition is true. For example, if a breakpoint is set on a line within a loop, you do not want the execution to halt for every iteration within the loop, therefore you would enter a condition such as i 80 to indicate that the breakpoint is to be ignored otherwise. (This example assumes that i is incremented at some point within the loop and will eventually exceed 80).

line 5 script `test1'

Notice that the script name is in quotes. The format for a subscript name is always:

`<subscript>'

`<window>'@`<field>' enter (or exit)

`<key context>-<key label>'

application `<name>' enter (or exit)

The Set Line window allows you to enter in the name of the procedure and the line number. When the Quit function is pressed the Definition field will be filled in with the appropriate definition.
 
Figure 9-11 Set Line Window

9.4.3.3 Set Procedure (set_proc)

call <proc>

This can be entered directly into the Definition field on the Set window or you can access the Set Procedure window and enter just the name of the script there. When you press the Quit key the definition will be placed into the Definition field.
 
Figure 9-12

For both the procedure and line breakpoints it is possible to have the information filled in automatically by the Source Debugger. You can list the source for the appropriate script and then enter the breakpoint windows by using the Set Breakpoint function. When the Line or Procedure functions are executed, appropriate information such as the script name will be automatically entered. Quit will then create the appropriate Definition field and the Set function will set the breakpoint.

variable <var>

9.4.4 Breakpoints List Window (bplist)

9.4.5 Variables Window (variables)

One of the variables will be highlighted and you can move through the list using the Select Next Item and Select Previous Item keys.
 
Figure 9-15 Variable Window

The value of the highlighted variable can be edited using the Edit function. This will place the value of the variable in a small window where it can be edited using the normal Empress 4GL editing functions. Once the value is changed the normal Quit function will update the variable. This can be used to determine how an application will react to certain values or to bypass an error caused by an incorrect value.

As well, the highlighted variable may be placed in the View window by using the View function. The value of the variable will then be tracked as the debugging session continues.

There is also a menu associated with the Tables window which allows you to call up the Attributes window for the currently highlighted table instance.
 
Figure 9-16 Tables Window

9.4.7 Attributes Window (attributes)

The value of the highlighted attribute may be changed by using the Edit function. This will provide a small window in which the current value is placed and can be edited using the normal Empress 4GL editing functions.

The View function will place the highlighted attribute into the View window so that its value may be monitored as the application continues.

There are two options on the menu which are associated with the Applications window. The Enter Script function displays the Source window with the application enter script in it. Similarly, the Exit Script function displays the source of the application exit script.

Within a window there are two items which can be displayed. The first is a list of the fields on the window (use the List Fields key). The second is a list of key contexts (use the List Contexts key) that are on the key context stack for the window. The windows that are brought up by these functions are described in more detail in the following sections.
 
Figure 9-19 Windows Window

9.4.10 Fields Window (fields)

The enter and exit scripts of each field can be displayed in the Source window, the Enter Script or Exit Script functions. The field can be selected using the Select Next Item and Select Previous Item keys.

As well, the View function can be used to put the field into the View window so that it can be tracked.

The Edit function allows you to change the value of the current field in the same way that variables and attributes can be edited.
 
Figure 9-20 Fields Window

9.4.11 Contexts Window (contexts)

From the Contexts window you may call up the Keys window for the highlighted context using the List Keys function. The Keys window will be described in the next section.
 
Figure 9-21 Context Window

You have the option of pushing on or popping off key contexts from the stack by using the Push Context and Pop Context functions.

Using the Select Next Item and Select Previous Item keys, you can select one of the keys. Its source can then be displayed in the Source window by using the Source function.
 
Figure 9-22 Keys Window

9.4.13 Scripts Window (scripts)

9.4.14 Source Window (source)

9.4.15 Edit Window (edit)

9.4.16 Help Window (help)