Error processing in the windowing system

This topic describes how to detect and prevent runtime errors in a program that uses the windowing routines.

Trapping errors

The windowing system does not trap runtime errors in the same way standard Synergy programs trap errors. Most window errors are considered fatal unless you precede the faulty function with the function W_RETERR. (Exceptions are errors generated by functions such as WD_READS, WD_GETS, and WD_WAIT, which do return normal, trappable Language errors.) If the function that causes an error is preceded by a W_RETERR function in a subroutine’s argument list, your program continues to run. However, once you’ve trapped an error with W_RETERR, the rest of the functions in that subroutine are not executed.

W_RETERR

W_RETERR, errfield

The W_RETERR function traps an error and returns error information in errfield, which is a record with this layout:

record errfield
    error_number        ,d2
    routine_name        ,a6
    arg_number          ,d2
    error_text          ,a50

You can use W_RETERR in any windowing subroutine that uses regular functions. For example, you can use W_RETERR to trap errors in the following subroutines:

xcall w_disp(id, W_RETERR, errfield, ...)
xcall w_area(id, W_RETERR, errfield, ...)
xcall w_proc(W_RETERR, errfield, ...)

To detect an error, you must test the contents of the error_number field. If the field contains a value of zero (in other words, the field tests “false”), no error has occurred. If the field contains any number other than zero, an error has occurred. The error number, routine name, argument number, and error text that are returned identify the error.

Examples

If you wanted to prevent a fatal error on a WD_READS function, use the following code, which shows the argument definitions necessary to store the returned information. We use the W_RETERR function to avoid the fatal window error #11, “Input field not completely visible.” This error occurs when you attempt to obtain input from a portion of the window that is partially or completely occluded. To avoid this problem, simply move the window to the top of the pile with the WP_MOVE function.

.define WNDCHNL,        1
.define MAXWINS,        10
.include "WND:windows.def"
record wnd_ids
    wndw_1              ,i4
    wndw_3              ,i4
record input
    selection           ,a1
record errfield
    error_number        ,d2
    routine_name        ,a6
    arg_number          ,d2
    error_text          ,a50
proc
    open(WNDCHNL, o, "tt:")
    xcall w_init(0, WNDCHNL, MAXWINS)
;Create window1 (menu)
    xcall w_proc(WP_CREATE, wndw_1, "menu", 12, 30)
    xcall w_brdr(wndw_1, WB_ATTR, ATTR_SET + ATTR_RVRS,
  &       WB_TITLE, "Record Maintenance", 
  &       WB_TPOS, WBT_TOP, WBT_CENTER)
    xcall w_disp(wndw_1, WD_POS, 2, 2, "1. Display",
  &       WD_POS, 4, 2, "2. Enter",
  &       WD_POS, 6, 2, "3. Update",
  &       WD_POS, 8, 2, "4. Delete",
  &       WD_POS, 10, 2, "Selection? ")
    xcall w_proc(WP_PLACE, wndw_1, 1, 1)
;Create window3 (error window)
    xcall w_proc(WP_CREATE, wndw_3, "error", 10, 35)
    xcall w_disp(wndw_3, WD_POS, 2, 2,
  &       "Invalid selection", WD_POS, 3, 2,
  &       "Please press the number", WD_POS, 4, 2,
  &       "corresponding to your", WD_POS, 5, 2,
  &       "menu selection.")
    xcall w_proc(WP_PLACE, wndw_3, 5, 10)
    xcall w_disp(wndw_1, W_RETERR, errfield, WD_READS, selection)
    if (error_number .eq. 11)
      begin
        xcall w_proc(WP_REMOVE, wndw_1, WP_MOVE, wndw_1, 0, 0)
        xcall w_disp(wndw_1, WD_READS, selection)
      end
done,
    xcall w_exit
    stop
end

Window errors

All window errors are first categorized as a Synergy DBL “Window Manager error” ($ERR_WNDERR).

If a window error occurs, you’ll first receive the Window Manager error. Then you’ll receive two lines of informational errors to give you more details. The informational messages tell you the routine name, the number of the argument that triggered the error, and the window error number. The next line gives you the window error message that describes the problem. Finally, a fourth line indicates the line number and the routine in which the error occurred.

See $ERR_WNDERR for a list of window error numbers and their accompanying error text.