DTK_BOUNDS

Enable UI Toolkit bounds checking

The DTK_BOUNDS environment variable enables bounds checking in UI Toolkit.

Value

One of the following values:

0 = Turn off bounds checking.

1 = Generate a fatal error for a level 1 error.

2 = Generate a fatal error for a level 1 error and prompt for level 2 errors (or log them if DTK_BOUNDS_LOG is set).

Discussion

Setting DTK_BOUNDS catches catastrophic failures whereby a reference exceeds the calling routine’s data space, including such failures as data being overwritten and segmentation violations.

On Windows with traditional Synergy, bounds checking is built into both the default Toolkit library, which is built with -qstrict, and tklib_qcheck.elb, which is built with -qcheck. The Synergy .NET compiler automatically includes bounds checking. However, you may still want to use DTK_BOUNDS, as it has the additional W_PROC check mentioned below, and unlike other bounds checking options, it tells you explicitly when a data area passed to a routine is too small, rather than issuing a generic range error. See Bounds checking for more information.

DTK_BOUNDS can be set at any point before calling U_START to turn on bounds checking in UI Toolkit. To control the bounds-checking behavior after U_START is called, modify the value of g_dtkbounds in WND:tkctl.def. See tkctl.def.

If DTK_BOUNDS is set to 1 or 2 (or anything greater than 0), Toolkit generates a fatal Toolkit error if it encounters a level 1 error, which occur under the following conditions:

A record is not large enough for a referenced field for one of the following: I_DISPLAY, I_GETFLD, I_INIT, I_INPFLD, I_INPUT, I_PUTFLD, L_INPFLD, or L_INPUT.
W_PROC(WP_RESIZE) is used on Windows to resize one of Toolkit’s reserved windows (header, footer, or information line) or an input window for a list. If DTK_BOUNDS is set to 1 or 2, Toolkit reports this along with the window ID and the old and new sizes.

If DTK_BOUNDS is set to a value of 2 or greater, a message box opens, enabling you to continue or stop the program for level 2 errors, which occur under the following conditions:

IB_FIELD creates a text field that’s too large for the window.
A record for an argument for one of the following is not exactly the size of the referenced data: I_USER, I_DSPFLD, I_GETFLD, I_INPFLD, or I_PUTFLD. If DTK_BOUNDS is set to 2, you can set the DTK_BOUNDS_LOG environment variable to log level 2 errors to a file.
An integer value is passed for a non-integer field, or vice versa, for I_DSPFLD or I_PUTFLD. Note, however, that no error is generated for user-defined data types.

Setting location

The environment. On Windows, this environment variable can also be set in the [synergy], [dbr], or [myprog] section of synergy.ini (where myprog is any .dbr file).

Used by

UI Toolkit