How You Can Access a Hierarchy of Data Entry Error Handlers

OpenROAD lets a called or opened executable object override the handler specified by its parent by setting its own data entry error handler. The locally invoked error handler can:

When a data entry error handler returns control, the error handler can cause OpenROAD to search parent executable objects for other data entry error handlers defined at higher levels. OpenROAD calls each handler it finds, passing to it all modifications made by previous handlers. If no handler is found, execution resumes as if no search for other handlers was performed.

The integer value returned by a data entry error handler determines whether OpenROAD searches for other error handlers defined by parents. There are two integer values that error handlers return:

Causes normal execution to be resumed, displaying non-blank messages in a pop-up; the message can be revised by the code

Causes the search for handlers to be resumed, starting with the parent of the executable object in which the current handler was found

If none of the handlers removes the error condition by resetting the field's value, the field triggering the error condition retains input focus and the cursor remains on the error field.

If one of the handlers removes an error condition that was detected when the field attempted to give up input focus, the input focus is changed. Events (such as SetValue) are generated as if the user had entered valid data.

Error handlers that remove an error condition should not return EH_NEXT_HANDLER.

The search for other handlers defined by parent executable objects stops when either no handler is found, or the current handler returns EH_RESUME.

The top frame (main_control) of the Videos application defines a local error-handling procedure that it establishes as a data entry error handler. Because all frames in the application are called from the main_control frame, every frame in the application calls this handlerproc procedure implicitly whenever users type invalid values into entry fields.

The following code is the entire error-handling procedure defined in the main_control frame:

procedure handlerproc(
    errorfield = entryfield;
    errorframe = frameexec;
    errormessage = varchar(2000)
    not null) /* b yref() */=
begin
    CurProcedure.beep();
    if errorfield.DataType = 'date' then
        errormessage = 'You must enter a valid
            date in this field';
    else
        errormessage = '';
    endif;
    return EH_RESUME;
end;

Typing incorrect data in any entry field on any frame called by the main_control frame causes the monitor to beep.

When invalid data (such as an integer or Feb 31) is typed into a field with a date data type, the handlerproc procedure displays a pop-up message specific to date fields. Similar messages can be customized for other fields, but this procedure only beeps when invalid data is entered into a field other than a date field. No error message is displayed for other fields because the error message is changed to an empty string.

Because the handlerproc procedure returns EH_RESUME, control returns to the calling frame without searching for other data entry error handlers.

The following code from the main_control frame declares handlerproc as a procedure and establishes it to handle data entry errors:

initialize =
declare
    handlerproc = procedure returning integer
    not null; /* local procedure */
enddeclare
begin
    CurFrame.DataEntryErrorHandler =
    CurFrame.Scope.GetProcHandle
    (name = 'handlerproc');
    ...
end;

The another_handlerproc procedure returns EH_NEXT_HANDLER, causing OpenROAD to search the parents of this frame for other data entry error handlers. Because the frame that defines the handlerproc procedure is the parent frame, control passes to the handlerproc procedure.

The following is the complete code for the another_handlerproc procedure:

procedure another_handlerproc(
    errorfield = entryfield;
    errorframe = frameexec;
    errormessage = varchar(2000) not null) =
declare
    str = varchar(100) not null;
enddeclare

begin
    message 'Error in field' + errorfield.Name +
    HC_NEWLINE +
    errormessage;
    return EH_NEXT_HANDLER;
end;

Although this procedure uses the message statement to compose the error information, the text of the message is written to the w4gl.log file rather than displayed in a pop-up frame. Statements that usually cause display of a pop-up frame (such as the message statement and the ConfirmPopup method) perform differently when executed from within a data entry error handler. For a discussion of other restrictions, see Restrictions on Data Entry Error Handlers.

The following statement from the frame's initialize block establishes the another_handlerproc procedure as its error handler:

CurFrame.DataEntryErrorHandler =
CurFrame.Scope.GetProcHandle(name =
'another_handlerproc');

Because this frame is called by the parent frame that defined the handlerproc procedure, the following process occurs if a user enters an erroneous value in an entry field in the child frame:

1. The another_handlerproc procedure is called and it writes the name of the error-triggering field, and the standard error message, into the log file or trace window.

2. The handlerproc procedure is called (because the another_handlerproc procedure returns EH_NEXT_HANDLER), and it does the following:

A data entry error handler is subject to the following restrictions that are imposed on the handler and on any procedures or methods it calls:

• Handlers cannot invoke a frame; the callframe, gotoframe, and openframe statements are all illegal.

• Handlers cannot wait for user events or database events, but they can issue database queries and do file I/O.

• The OpenROAD Debugger does not stop at breakpoints or for any other condition during the execution of the handler.

Statements that usually cause display of a pop-up frame (when executed outside a data entry error handler), such as the message statement and the ConfirmPopup method, are written to the trace window and the w4gl.log file.

Except for message statements, such statements cause the entire OpenROAD process to wait for a response, even if there are other threads that could run.

A handler can be in a thread different from that of the frame that encountered the error, even if the handler is a local procedure.

Note: The error handlers described in this section do not apply to database errors. For more information about handling database errors, see Data Entry Error Handling.