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:
- Set the logical or environment variable DTKDBG to any value.
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.
- Explicitly invoke the debugger without setting DTKDBG by using the U_DEBUG subroutine.
- Call the Toolkit window debugger from a Synergy debugger prompt by typing “windbg”. If Toolkit is not initialized (for example, before U_START or after U_FINISH), the command simply returns without doing anything. If the program was not linked with Toolkit, a “Cannot access external routine” error is generated. Otherwise, the Toolkit debugger takes over input until a QUIT command is issued, at which point, the Synergy debugger resumes control with a new prompt.
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")
|
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:
- CLEAR or CLS—Clear the display screen.
- DISPLAY—Display windows or lists.
- EXAMINE or SHOW—Provide status information.
- QUIT—Exit the debugger.
- REDRAW—Redisplay debugger system output lines.
- WINDOW—Display information about a window.
- LIST—Display information about a list.
- FILESTACK —Display information about a file stack.
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
|
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. |
The CLEAR or CLS command clears the display screen and redisplays the debugger command prompt.
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.
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:
- Toolkit version being used
- Maximum allowable number of the following items:
- Channels
- Windows
- Header and footer lines
- Lists
- Environment levels
- Placed windows in all environments
- Entries per column
- Fields per input window
- Sets per input window
- Information text per window field
- Characters per text row
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:
- Lists of local channels
- Windows, lists, and columns
- Placed windows, lists, and columns
- Terminal states (echo, cursor, lowercase, interrupt)
- Program states (wait on lock, wait on message)
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.
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.
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.
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:
- Name
- Size
- Placement
- Title
- Cursor position
- Display area
- Processing area
- Characteristics (whether or not it is placed, occluded, border is on or off, title is displayed)
- Renditions (for window, border, and title)
- Number of fields
- Current field
- Number of user-data entries
- Size of user-data entries
- Current user-data entry
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 (.).
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:
- Current item number
- Last item number (highest loaded)
- Current row (ordinal item number in visible portion of the list)
- Current item status (whether or not it is null or if it is at the top or bottom of list)
- Associated input window ID
- List status (enabled or disabled)
- Current find parameters (case sensitivity, direction, search type, area of the optional data to be searched, the search string, and the length of the string)
- Find status (whether the last find was successful)
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 (.).
