Designing Interactive Panels (Panel Services) › Handle Errors

Handle Errors

NCL procedures that use Panel Services usually contain processing to validate operator input. If an error is detected, the procedure must be able to notify you about the field in error and the nature of the error.

Errors can be identified by taking advantage of the variable substitution performed for panel control statements, setting appropriate variables for the #OPT control statement CURSOR and ALARM operands, moving suitable text into an error message variable, and redisplaying the panel.

This technique works well, but places additional responsibility on your NCL procedure to ensure that the correct variables are set and cleared later if no errors are detected. (The situation is compounded as the number of fields on the panel increases.)

It also helps the end-user if you highlight those fields in error by switching them to another color, or by using facilities such as blinking or reverse-video on terminals that support these facilities. This can also be achieved by substituting variables in control statements, but becomes unwieldy.

Panel Services facilities are provided to simplify the notification of errors. These facilities assume that error reporting includes additional attention-getting operations such as:

• Ringing the terminal alarm
• Placing the cursor on the field in error
• Displaying error message text
• Changing the field in error to high-intensity
• Switching the field in error to a different color
• Displaying the field in error in reverse-video

The #ERR control statement lets you design a common environment (that is, a common set of attributes) for error conditions. This environment is then applied whenever an input field is nominated as being in error by one of the following methods:

• Using the &ASSIGN verb. (For more information about the syntax and usage of the &ASSIGN verb, see the Network Control Language Reference Guide. Note especially the OPT=SETERR and OPT=RESETERR options.) This method lets you set the error attribute for multiple fields
• By nominating the field name in the ERRFLD operand of the panel services #OPT statement. This method allows the error attribute to be set for a single field. The ERRFLD operand normally specifies a variable (for example, ERRFLD=&SYSFLD). When the NCL procedure wants to mark a field as being in error, it places the name of the field in error into the variable (for example, &SYSFLD = FIELD1).

The following sample panel shows the ERRFLD operand in use.

#OPT ERRFLD=&SYSFLD 
#ERR ALARM=YES INTENS=HIGH COLOR=RED HLIGHT=REVERSE
%--------------------  Name and Address  ---------------------------- 
%&SYSMSG 
+ENTER NAME%===_NAME                     + 
+ENTER ADDR%===_ADDR1                    + 
+ENTER ADDR%===_ADDR2                    + 
+ENTER ADDR%===_ADDR3                    + 
+ENTER ADDR%===_ADDR4                    + 
+ENTER ADDR%===_ADDR5                    +

This sample panel illustrates the use of the #OPT ERRFLD method. This method requires two items in the panel control statements: a #OPT ERRFLD statement and a #ERR statement.

Assume the ADDR5 field data must be XYZ; initially the panel is displayed with the &SYSFLD variable set to null. Because the ERRFLD operand does not nominate a field, the #ERR statement is ignored and the panel is displayed normally.

On subsequent entry, the validation procedure checks the ADDR5 field and determines that it is wrong. The &SYSFLD variable is set to the name of the incorrect field (ADDR5), the appropriate error text is assigned to the &SYSMSG variable, and the panel is redisplayed.

.DISPLAY
   &PANEL MYPANEL
  
   &IF .&ADDR5 NE .XYZ &THEN &GOTO  .ERROR
   .
   .  other processing
   .
.ERROR
   &SYSFLD = ADDR5
   &SYSMSG = &STR DATA MUST BE XYZ, RE-ENTER
   &GOTO .DISPLAY

When the panel is redisplayed, the cursor is positioned on the last address field, ADDR5. This field is displayed in high-intensity and the terminal alarm rings (on a color terminal, the field is displayed in reverse-video and red.)

To achieve the same result using &ASSIGN verb instead, remove the #OPT statement from the panel definition and replace the line:

&SYSFLD = ADDR5

with

&ASSIGN OPT=SETERR VARS=ADDR5

This method lets you use the #ERR attributes for more than one field.

If the ADDR5 field is corrected and the panel redisplayed, the ADDR5 field returns to its original attributes.

If the erroneous field is a non-display field (such as those used to enter passwords), the overriding attributes that force the entered data to be displayed are ignored and the field remains a non-displayed field.

Note: The variable &SYSFLD is a special variable, which is cleared by Panel Services after the panel is displayed. If you use another variable such as &ERROR, you should clear it after all error conditions are corrected. This ensures that if another panel that uses the same variable is displayed, it does not incorrectly signal an error. The &SYSMSG variable need not be cleared by the NCL procedure because it is always reset to null by Panel Services before returning to the NCL procedure.