Designing Interactive Panels (Panel Services) › Handle Errors › Internal Validation › Advanced Internal Validation

Advanced Internal Validation

While the automatic internal validation greatly simplifies an NCL procedure, sometimes you might want a procedure to continue processing when a validation error is detected, bypassing the automatic reshow normally performed. For example, if a field is specified as mandatory (REQ=YES), automatic internal validation forces the field to be entered and issues this message:

REQUIRED FIELD OMITTED

Alternatively, you might want a system where a field is mandatory unless F1 is pressed to display a Help panel, or where F12 indicates the entry is to be bypassed. You might also want to change the text of the messages supplied by internal validation.

An &CONTROL PANELRC statement issued before an &PANEL statement tells Panel Services processing that the NCL procedure is designed to cater for a range of &PANEL return codes. These return codes accommodate a variety of conditions possible when processing a panel, and signify there is no automatic reshow performed after an error is detected.

If &CONTROL PANELRC is used, the procedure receives control if internal validation detects that a required field has been omitted (or some other error). The name of the field in error is supplied in a variable called &SYSFLD and the text of the error message registered by internal validation is supplied in the &SYSMSG variable.

In the previous example, where F1 and F12 require special processing, the procedure tests &INKEY for PF01 or PF12, ignores the error, and reacts as required. If F1 or F12 is not pressed, the procedure redisplays the panel with the error message.

When redisplaying the panel, the &SYSFLD variable containing the name of the field in error can be referenced on the #OPT statement ERRFLD operand (ERRFLD=&SYSFLD). This initiates the processing which positions the cursor on the field in error (and possibly a #ERR statement designating special attributes to be applied to the field in error). The text in the &SYSMSG variable can be modified if required, or assigned into another variable.

If a procedure uses this technique, it must be written to handle all return codes possible from the &PANEL statement.

If no internal validation is performed or no internal validation error is detected, &SYSMSG and &SYSFLD are set to a null value when control is returned to the NCL procedure after the &PANEL statement. This ensures that the NCL procedure does not have to explicitly clear variables if an error is not found.

Like &SYSMSG, the &SYSFLD variable is not limited to internal validation uses. It can also be used by the NCL procedure for its own error indications:

• Once a procedure has detected an error it can assign error message text into the &SYSMSG variable, place the name of the field in error in &SYSFLD, and redisplay the panel.
• If the panel uses the ERRFLD option on the #OPT statement, the error message is displayed and the cursor positioned at the field in question. Any other error processing defined on the #ERR statement is also performed.

Like other user variables, the &SYSFLD variable does not span different NCL procedure nesting levels and is unique to each level unless shared under &CONTROL SHRVARS. Regardless of other uses, &SYSFLD resets to null after the &PANEL verb unless an error is detected by internal validation.