PeopleCode | Displaying an error in non-standard events
A. The Error Function
Forcing an error in online PeopleCode is usually a case of calling the ‘Error’ function with the appropriate message. The ‘Error’ function causes all processing to terminate and returns control back to the user. Because of its ability to halt all processing of the code, the ‘Error’ function is restricted to only a few events, the most common two being ‘FieldEdit’ and ‘SaveEdit’. An ‘Error’ statement can also be used in ‘RowDelete’ and ‘RowSelect’, but these events are typically limited to a very narrow scope of operation.
B. Non-Standard Errors
You may still have a situation however in which you may want to present the user with an error-like condition from one of the non-standard PeopleCode events. I can think of two instances where this has happened on projects I’ve worked on:
- We wanted to pre-validate some data upon entering a page, and immediately flag an error to the user.
- We already had extensive and complex code on the ‘FieldChange’ event. A new requirement came up that required us to display an error based on one of the calculations in the existing ‘FieldChange’ code. Rather, than trying to pick-and-choose the correct code and copy it back to ‘FieldEdit’ (in which case we would have been duplicating the code… another problem again), we decided to continue using the ‘FieldChange’ event, but generating our own error-like condition.
Below is one approach for generating an error from a non-standard event. This sets the field style to ‘PSERROR’ and uses the ‘SetCursorPos’ method to resume user control on the field in question. Finally, the code displays a message using the ‘MessageBox’ function.
C. To Terminate or Not To Terminate?
When generating a non-standard error, you also need to give some thought as to whether you want the code to immediately terminate at the point the error is encountered, or whether you want the remaining code to run. Keep in mind that you adding error-like validation to an event that doesn’t normally have to deal with early termination. For instance, you may have code in a ‘RowInit’ event that sets page field properties (say, to visible or invisible), so if you terminate this code early, the page may not appear in a useable form. In this case, a ‘MessageBox’ statement could be used to display the ‘error’, while still allowing the remaining code to continue as normal:
RECORD_NAME.FIELD_NAME.Style = "PSERROR"; RECORD_NAME.FIELD_NAME.SetCursorPos(%Page); MessageBox(0, "", 99999, 9, "ERROR XYZ");
If for some reason you really do want to terminate the code at the error condition, you could add an ‘Exit’ statement to halt all processing. However, this is generally seen as a last resort. ‘Exit’ should only be used if you are certain it will have no adverse flow-on effect:
RECORD_NAME.FIELD_NAME.Style = "PSERROR"; RECORD_NAME.FIELD_NAME.SetCursorPos(%Page); MessageBox(0, "", 99999, 9, "ERROR XYZ"); Exit;
Incidentally, by using the %Page construct to specify the page name, the above code is assuming that there is only one page in the component. If there happened to be more than one page, you should specify the exact page name when calling the ‘SetCursorPos’ method.
D. Business as Usual
Once the error is displayed and control is passed back to the user, the field style should be reset to its default as soon as the user changes the field value. Otherwise, you will be left with a page containing a permanently red field, which is likely to be confusing. Furthermore, a normal system error (such as a ‘Required’ field left blank) will automatically remove the red formatting as soon as a value is entered. Therefore if you’ve just set the field style to ‘PSERROR’, remove the formatting by including this code in the ‘FieldChange’ event:
RECORD_NAME.FIELD_NAME.Style = "";
Setting a style to a blank string causes the object to go back to its default style.
See Also:
Tip 041: MessageBox Function