Designing Interactive Panels (Panel Services) › Monitor Panel Return Codes

Monitor Panel Return Codes

An NCL procedure can enhance the available synchronous panel processing options by issuing an &CONTROL PANELRC statement before displaying a panel. If this option is used, then:

• After panel processing has completed (that is, following execution of an &PANEL statement) the &RETCODE variable is set to indicate a particular processing condition and control passes to the NCL statement immediately following the &PANEL statement.
• The NCL procedure is responsible for testing the value of &RETCODE immediately after the associated &PANEL statement and processing accordingly.

Note: Failure to test &RETCODE can result in unexpected results.

Asynchronous &PANEL statements always set an &RETCODE completion code, even if &CONTROL PANELRC has not been issued.

The return codes 0, 4, and 8 are set as a result of a process called internal validation, which automatically edits input fields according to rules prescribed in the panel definition. The internal validation process is described fully in subsequent sections.

&RETCODE = 0

For synchronous panel operations: One or more panel input fields have been modified. This return code indicates if any field data have been changed. You could use this to decide if any further validation is required. If data has been overtyped but not altered, it is not considered to have been modified. If internal validation detects an error, return code 8 is set.

If &CONTROL FLDCTL is set and any input field on the panel has MODIFIED attribute, the panel returns &RETCODE 0, even if the user did not physically change the field.

For asynchronous panel operations: The panel has not been updated but input has been received for an earlier display of the same panel. In this case, you can now process the input, but you must reissue the &PANEL statement to update the panel display.

&RETCODE = 4

The same as for return code 0, except that no input fields on the panel have been modified. This return code can be used with return code 0 to decide whether further data processing is required.

Important! Take care when using this return code if multiple interactions with the panel can occur.

If internal validation detects an error, return code 8 is set. Return codes 0 and 4 apply only to the last input from the screen; if the procedure accepts input from a screen where some data is changed and redisplays the panel, which is then not modified, any earlier indications of data modification are lost. Your procedures must allow for this situation.

This return code can be produced for both synchronous and asynchronous panel operations.

&RETCODE = 8

An internal validation error has been detected. When &CONTROL PANELRC is in effect, automatic error condition processing is suppressed so the procedure is notified by this return code. The &SYSMSG variable contains the text of the error message (for example, NOT WITHIN RANGE). The &SYSFLD variable contains the name of the input field in error; this is the name of the variable (minus the & prefix) which receives data entered into that field. When this return code is set, the procedure can ignore the error and take alternative action. For example:

• Displaying a Help panel
• Altering the error message text by assigning a new message to the &SYSMSG variable
• Redisplaying the panel by having the #OPT ERRFLD facility display the error message unchanged and putting the cursor on the field in error. In this case, the ERRFLD operand can be defined on the #OPT statement as ERRFLD=&SYSFLD to simplify processing.

Using &RETCODE = 8 is an ideal way of providing an escape mechanism (such as F3), even though the panel has been defined as having mandatory fields REQUIRED=YES.

&RETCODE = 12

For synchronous panel operations: The panel display time-out limit specified by the #OPT INWAIT operand has elapsed without any data entry. The &INKEY system variable is null.

For asynchronous panel operations: This return code means that the panel has been displayed and has returned to the issuing procedure. Successive updates of the panel can be made by repeating the &PANEL statement; &RETCODE = 12 indicates the panel will be redisplayed and that no input has been received from earlier displays of the same panel. (The availability of input from a previous display of the panel is indicated by return codes 0 or 4.)

&RETCODE = 16

The panel requested is not defined in the current panel library path, or else some other serious error has occurred which prevents the panel displaying. The &SYSMSG system variable contains a message describing the error condition.

If &CONTROL PANELRC is not in effect, the following processing occurs:

• If required, the NCL procedure determines whether any input fields have been modified
• Internal validation handles all error processing automatically and redisplays the panel if errors occur.
• The NCL procedure can only determine whether the INWAIT interval has expired by testing the &INKEY variable for a null value.
• If a requested panel does not exist in the current panel library path, or some other serious error occurs, the NCL procedure terminates with an error message.