DEBUGGER system handle

A handle that lets ABL procedures initialize and control the Application Debugger.

To use the DEBUGGER handle, you must have the Application Debugger installed in your OpenEdge environment.

DEBUGGER [ :`attribute` \| :`method` ]

Specifies an attribute of the DEBUGGER handle.

Specifies a method of the DEBUGGER handle.

HANDLE attribute	INSTANTIATING-PROCEDURE attribute	TYPE attribute
VISIBLE attribute	–	–

CANCEL-BREAK( ) method	CLEAR( ) method (Handle)
DEBUG( ) method	DISPLAY-MESSAGE( ) method
INITIATE( ) method	SET-BREAK( ) method

The following example displays Orders for each Customer in the Sports2000 database using two procedure files. The r-cusbug.p file initializes the Debugger and sets a breakpoint at line 6 of the r-ordbug.p file. Thus, each time r-ordbug.p displays an Order, the Debugger takes control before it displays the Order Lines. Just before completing execution, r-cusbug.p clears the debugging session before returning.

r-cusbug.p
DEFINE NEW SHARED BUFFER CustBuf FOR Customer. DEFINE VARIABLE debug AS LOGICAL NO-UNDO. debug = DEBUGGER:INITIATE(). debug = DEBUGGER:SET-BREAK("r-ordbug.p",6). FOR EACH CustBuf NO-LOCK: IF CAN-FIND(Order OF CustBuf) THEN RUN r-ordbug.p. END. debug = DEBUGGER:CLEAR().

r-ordbug.p
DEFINE SHARED BUFFER CustBuf FOR Customer. FOR EACH Order OF CustBuf NO-LOCK: DISPLAY CustBuf.Name CustBuf.CustNum CustBuf.City CustBuf.State CustBuf.PostalCode Order.OrderNum. FOR EACH OrderLine OF Order NO-LOCK, Item OF OrderLine NO-LOCK: DISPLAY Item.ItemName Item.ItemLum LrderLine.Qty. END. /* FOR EACH OrderLine / END. / FOR EACH Order */

You must initialize the Debugger using either the DEBUG( ) or INITIATE( ) method before using any of the remaining methods in a procedure.

The DEBUG( ) and INITIATE( ) methods provide separate means to invoke the Debugger, and do not depend on each other to start a debugging session. The DEBUG( ) method initializes and gives control to the Debugger whether or not the INITIATE( ) method has been executed.

The TYPE attribute returns the widget type, PSEUDO-WIDGET.

The VISIBLE attribute specifies whether the Debugger window is visible on the screen. When set to FALSE, if the Debugger window is currently visible, it is removed from the screen. When set to TRUE, if the Debugger window is currently invisible, it is displayed. Note that making the Debugger window visible does not, in itself, give control to the Debugger.

Note: The ABL code that initiates the Debugger and displays it on the screen is responsible for removing the Debugger from the screen when it is no longer needed by setting the VISIBLE attribute to FALSE.

After invoking the INITIATE method, execution continues in the procedure until it encounters a breakpoint or a statement invoking the DEBUG method. If the procedure encounters a breakpoint, the Debugger takes control running in application mode (with control over the invoking application). If the procedure invokes the DEBUG method, the Debugger takes control running in stand-alone mode (with control only over applications started from the Debugger).

References to line numbers in internal procedures must be relative to the debug listing in which they are contained.

When you set or cancel a breakpoint, you must distinguish between a line number value less than 1 and a value of 1 or greater. Any value for line-number less than 1 (for example, 0 or -1) specifies the first executable line of the main procedure in the file specified by procedure. However, a positive value for line-number specifies the first executable line on or after line-number in the file specified by procedure. For example, suppose procedure specifies a file like this:

1 DEFINE VARIABLE lStart AS LOGICAL NO-UNDO INITIAL TRUE. 2 PROCEDURE ShowStart: 3 IF lStart THEN MESSAGE "Procedure is starting ...". 4 END. 5 6 MESSAGE "Hello World!". 7 RUN ShowStart. 8 lStart = FALSE. . . .

1      DEFINE VARIABLE lStart AS LOGICAL NO-UNDO INITIAL TRUE. 
2      PROCEDURE ShowStart: 
3        IF lStart THEN MESSAGE "Procedure is starting ...". 
4      END. 
5       
6      MESSAGE "Hello World!". 
7      RUN ShowStart. 
8      lStart = FALSE. 
         . . .

If you specify a breakpoint at line 0, -1, or any negative value, the breakpoint actually occurs at line 6, the first line that executes in the main procedure. If you specify a breakpoint at line 1 or 2, the breakpoint occurs at line 3, the first executable line in the file, which happens to be the first executable line of an internal procedure.

This distinction also affects procedures containing the Trigger phrase used to define triggers in widget definitions. For example, suppose procedure specifies this file:


1 DEFINE BUTTON bOK LABEL "OK" 2 TRIGGERS: 3 ON CHOOSE 4 MESSAGE "OK Pressed!". 5 END TRIGGERS. 6 MESSAGE "Hello World!". . . .

Again, if you specify a breakpoint at line -1, the breakpoint occurs on line 6, but if you specify the breakpoint at line 1, it actually occurs at line 4, which is the first executable line of a trigger block.

Note: You cannot set a watchpoint programmatically using the DEBUGGER system handle. A watchpoint is a form of breakpoint which tells the Debugger to interrupt program execution when the value of a variable, buffer field, or attribute reference changes.

For more information on the Debugger, its features and functions, and its modes of execution, see OpenEdge Development: Debugging and Troubleshooting.