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:
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.
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.
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.
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:
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.
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.)
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: