Toolkit Debugger

Toolkit’s window debugger enables you to look into the windowing environment and determine what is really happening in the windows you’ve created. Before you can run the debugger, you must enable it. There are three ways to do this:

Once DTKDBG is set, if Toolkit generates an error, a window displays asking if you want to examine the window system. Answer Y to open the debugger. Note that when DTKDBG is set, the debugger checks for any %M_SIGNAL call that supersedes a pending menu entry, and it makes sure that a method passed to U_START can be invoked.

In addition, when DTKDBG is set, you can explicitly enter debug mode by pressing ctrl+r while performing any Toolkit input. Neither the environment nor window system resources are affected while you are in debug mode.

On OpenVMS, if your application is linked against TKLIB_SH.EXE, you must invoke OPENELB for the shared image in your application before the Toolkit window debugger is enabled. We do not perform this OPENELB automatically because it slows every XSUBR call. Your program should include it only if needed. For example, if the name of the logical symbol assigned to Toolkit’s shared image file is “TKLIB_SH”, you would execute this statement:

XCALL OPENELB("TKLIB_SH") 
Note

On Windows, the debugger runs in a separate application window. The initial size and location of this window is user-definable. See the environment variables DBG_X, DBG_Y, and DBG_WIDTH.

Debugger commands

The debugger supports the following commands:

The commands and their arguments are not case sensitive and can be abbreviated. To place more than one command on a line, separate them with commas. For online help on a particular command, type help followed by the command name. For example:

help examine
Tip

If you need to repaint the screen while you are in debug mode, press ctrl+r, ctrl+d on Windows and UNIX or ctrl+r, ctrl+z on OpenVMS.

CLEAR or CLS

The CLEAR or CLS command clears the display screen and redisplays the debugger command prompt.

DISPLAY

The DISPLAY command shows the screen displays for components of the UI Toolkit environment.

display environment [level] 
display windows [n, ...] 
display lists n [, n,...]

where level is the environment to be displayed and n is the ID of a window or list to be displayed.

DISPLAY ENVIRONMENT shows the screen display of the specified environment. Displaying an environment level re-creates that level’s display. If level is not specified, the current environment level is displayed.

DISPLAY WINDOWS shows the screen display of the specified window(s), placed on the screen in the order that you’ve specified them. If no windows are specified, the current list of windows is redisplayed.

DISPLAY LISTS shows the screen display of the specified list(s), placed on the screen in the order you’ve specified them. You must specify at least one list ID for this command.

Once a display of any kind has been generated, you can press any key to continue. All windows are removed and the debugger command prompt displays.

EXAMINE or SHOW

The EXAMINE or SHOW command provides status information about components of the Toolkit environment. Information in this section applies to both EXAMINE and SHOW.

examine defines
examine environment [level] 
examine system
examine window n [fields] [user] 
examine list n

where level is the environment level to be examined and n is the ID of the window or list to be examined.

EXAMINE DEFINES outputs status information about the following system definitions:

EXAMINE ENVIRONMENT outputs status information about the specified environment level. If level is not specified, the debugger examines the current environment level. The environment status includes the following:

EXAMINE SYSTEM outputs status information about the current system state. The system-wide information includes a list of all loaded columns and windows, channels in use, all lists, and all file stacks.

EXAMINE WINDOW (which is identical to WINDOW) outputs status information about the specified window. If fields is specified, the “raw” information about the window’s fields is also be output. If user is specified, the contents of the window’s user data set are also output.

EXAMINE LIST (which is identical to LIST) outputs status information about the specified list.

EXAMINE FILESTACK (which is identical to FILESTACK ) outputs status information about a file stack.

QUIT

The QUIT command exits the window debugger. If you entered the debugger from a screen input field, that field’s input will be redisplayed. If you entered the debugger after a fatal error was generated, the program will terminate.

REDRAW

On Windows, by default you can access 300 lines of output by scrolling. You can change the number of available lines by setting the DBG_BUFFER environment variable in synergy.ini or synuser.ini to a different value.

On UNIX and OpenVMS, the REDRAW command redisplays the last full screen (24 lines) of output produced by the debugger system.

WINDOW

The WINDOW command displays detailed windowing system information for a specific window.

window n [environment level] [fields] [user] 

where level is the environment level at which the window should be examined and n is the ID of the window for which information should be displayed. If level is not specified, the window is examined at the current level. Fields specifies that the parameters of all window fields are to be displayed. User specifies that information in any user data set is to be displayed.

The WINDOW command always displays the following information about the window:

If fields is specified, the following is displayed for each field:

fld = (row : col : len)

where fld is the field number, row and col are the window-relative placement coordinates for the field, and len is the field’s length.

If user is specified, for each user-data entry, the entry number followed by the data itself is displayed. Up to 50 characters per line are displayed and, if needed, continued on subsequent lines. Any non-printable character in the data is replaced by a period (.).

LIST

The LIST command displays information for a specific list.

list n

where n is the ID of the list for which you want information. This command displays the following:

FILESTACK

The FILESTACK command displays information for a file stack.

filestack [n] [level level] [record record] 

where n is the file-stack channel, level is the level of the file stack, and record is a record within that level. If the channel (n) is not specified, the default file stack is accessed. If level is not specified, the highest level on the file stack is used. If record is not specified, none is assumed.

The following information is always displayed: file-stack channel, level, record size, highest record written at that level.

If record is specified, the contents of that record are also displayed. Any non-printable character is replaced by a period (.).