Using Errors and Warnings
For the most part, errors and warnings display messages to users informing them about invalid data. For this reason, they are almost always placed in FieldEdit or SaveEdit PeopleCode, or in SearchSave PeopleCode for validation during search processing. In conjunction with edits, errors stop processing, while warnings allow processing to continue. When errors and warnings appear in places other than FieldEdit or SaveEdit, their effects vary.
This section discusses how to:
Use errors and warning syntax.
Use errors and warnings in edit events.
Use errors and warnings in RowSelect events.
Use errors and warnings in RowDelete events.
Use errors and warnings in other events.
Errors and warnings require only a message that the Component Processor displays to users. You can code the message into the error or warning statement, or you can use the message catalog. Use the message catalog with the MsgGet, MsgGetExplainText, and similar functions.
Errors and warnings use the same syntax. For example:
Error MsgGet(11100, 180, "Message not found."); Warning MsgGet(11100, 180, "Message not found.");
You can use the following PeopleCode events for validation edits: FieldEdit and SaveEdit. The Component Processor applies FieldEdit when the user changes a field, and SaveEdit when the user saves a component. Errors and warnings in these events display a message. Most errors and warnings appear in these event types, although you can use errors and warnings elsewhere.
FieldEdit Event Errors
You can use either the record field or component record field event. The record field event for each record runs before the component record field event for that record.
An error in FieldEdit prevents the system from accepting the new value of a field. The Component Processor highlights the problem field. The user must either change the field back to its original value or to something else which does not trigger the error. A warning enables the Component Processor to accept the new data. The Component Processor does not highlight a field that has warnings.
SaveEdit Event Errors
You can use the record field or the component record event. All record field events for a record run before the component record events.
An error in SaveEdit prevents the system from saving any row of data. The Component Processor does not update the database for any field if one field has an error. Although the Component Processor displays an error message, it does not turn any field red. Unlike FieldEdit errors, SaveEdit errors can happen anywhere on a page or component, for any row of data. The data causing the error may appear on a different page within the same group, or a row of data not currently displayed. If this is the case, the field in error is brought into view by the system.
A warning in SaveEdit also is applied to all data in the page or component, but the Component Processor will accept the data, if told to by the user. In a FieldEdit warning, the Component Processor displays a message box with the text and two buttons: OK and the standard Explain (the Explain button returns an explanation for the last message retrieved with the MsgGet function). In a SaveEdit warning, the message box contains an additional button, Cancel. OK accepts the data, overriding the warning and continuing the save process. Cancel ends the save process.
Because errors and warnings apply to all rows of data and all pages in a group, you must provide the user explicit information about what caused the error. Typically, you use the message catalog function to store messages and substitute variables into them. However, you can also facilitate this by concatenating in a field value. For example, if you have a stack of historical data on the page, you could use the following error statement:
Error ("The value exceeds the maximum on "|effdt|".");
RowSelect PeopleCode filters out rows of data after the system applies search record criteria. It also can stop the Component Processor from reading additional rows of data.
Note: Errors and warnings should no longer be used in RowSelect processing; instead, use DiscardRow and StopFetching. The behavior of errors and warnings in RowSelect PeopleCode is retained for compatibility with previous releases of PeopleTools.
A warning causes the Component Processor to reject the current row, but the Component Processor continues reading more data. An error prevents more data coming into the page or component. The Component Processor accepts the row that causes the error, but does not read any more data. To reject the current row and stop loading additional rows, issue a warning and an error.
You must specify text for an error or warning, but the Component Processor does not display messages from RowSelect. You can still use the message text as a way of documenting the program.
When you delete a row of data, the system prompts you to confirm. If you confirm, any record field RowDelete PeopleCode runs, and any component record RowDelete PeopleCode also runs. Errors and warnings in RowDelete display a message box.
A warning from RowDelete presents two choices: accept the RowDelete (the OK button), or cancel the RowDelete (the Cancel button). An error from RowDelete PeopleCode prevents the Component Processor from removing that row of data from the page.
Do not put errors or warning in PeopleCode attached to the FieldDefault, FieldFormula, RowInit, FieldChange, RowInsert, SavePreChange, WorkFlow, and SavePostChange events. These event types activate processing that a user has no direct control over. However, the Component Processor may issue its own errors and warnings when it runs PeopleCode and encounters an unrecoverable error. The Component Processor cancels the transaction to avoid unpredictable results.