How You Can Use Data Entry Error Handlers

If a user types invalid data into an entry field (for example, typing text into a field that has a numeric data type), an error message appears in a pop-up by default. Because these messages often do not communicate meaningfully to the user, you may want to create a data entry error handler.

A data entry error handler is a global or local procedure written in 4GL that gains control as a result of a user typing invalid data into an entry field. The error condition is detected when the entry field loses input focus, or the GetFieldValue method is executed on the entry field.

In the case of the entry field losing input focus, the following control situations can occur:

• If the data entry error handler was defined for a frame, it gains control when invalid data is detected in any field in either:

– Any frame called or opened (directly or indirectly) by that frame

• If the data entry error handler was defined for an executable object other than a frame (a method or procedure), it gains control when invalid data is detected in any field in any frame called or opened (directly or indirectly) by that executable object.

In the case of the GetFieldValue method being executed on the entry field, the data entry error handler gains control when the GetFieldValue method was invoked either of the following ways:

• The executable object for which the error handler was defined

• Any executable called or opened (directly or indirectly) by that executable object

Defining a 4GL procedure to be the data entry error handler for an executable object requires setting the DataEntryErrorHandler attribute of the executable object to the handle of the error‑processing 4GL procedure. Set this attribute for the current frame using the following syntax:

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

This syntax invokes the GetProcHandle method of the Scope system class to perform the following operations:

• Get the handle for the named procedure in the named scope

• Load the procedure's handle into the DataEntryErrorHandler attribute of the currently active executable object

To set the DataEntryErrorHandler attribute for the current procedure or method, use the CurProcedure and CurMethod variables rather than CurFrame.

To enable you to modify the error message, correct the value entered by the user, and locate the frame containing the error‑triggering field, data entry error handlers are passed the following parameters:

Specifies either a default error message provided by OpenROAD or a user-defined error message provided by a lower handler. It is passed by reference.

Specifies the error-triggering field. The attributes ErrorField.TextValue and ErrorField.StringValue contain the erroneous text that the user typed into the triggering entry field.

Specifies the reference variable pointing to the frame containing the error-triggering field

The first eight characters of the ErrorMessage parameter contain the error number of the triggering data entry error. Currently, the following are the data entry errors:

Indicates an input-masking mandatory position error (mandatory positions of the field are not filled in)

The following sections explain how to create data entry error handlers.