This standard runtime function performs the entry of a single panel field/control, but when placed in an event loop it allows
entry of all fields/controls on the panel. Use the EXECUTE EVENT standard runtime function as the standard method of allowing
user input with RM/Panels. It provides the power of multiple field entry with the flexibility of field-by-field control. Use
a related standard runtime function, ACCEPT FIELD when only one field/control is to be entered.
There are three ways to specify which field/control receives input focus on each execution of the EXECUTE EVENT standard runtime
- If you want to begin entry on the first field/control of the panel,
RMP--FIRST-FIELD must be set to
- If you want to specify the next input field/control,
RMP--NEXT-FIELD must be set to the field/control name, and
RMP--NEXT-OCCUR must be set to the field/control occurrence number. The RM/Panels runtime system resets these parameters after each execution
of the EXECUTE EVENT standard runtime function, thereby preparing for the next execution.
- If you want to resume entry on the last field/control of the panel that the user entered,
RMP--REPEAT-EVENT must be set to
TRUE. This is useful if multiple panels are in use and the user is returning to a previously accessed panel, or if invalid user
input is detected.
The value entered for each field/control in the panel is stored within
panelname.WS. The field termination code indicating the terminating key is returned in
The values of
RMP--NEXT-OCCUR are also set to the appropriate values for the next event. Occurrence numbers are equivalent to COBOL subscripts and begin
Under modeless operation, the following parameters are also returned:
- RMP--LAST-PANEL contains the name of the panel for which the last EXECUTE EVENT standard runtime function was performed.
- RMP--REQUESTED-PANEL contains the name of the panel that the user requested for the next event. To support modeless behavior, the application
program must be written so that the next EXECUTE EVENT standard runtime function is performed for the panel named by this
Additional Usage Notes
- Before this standard runtime function can be executed, the panel must be displayed.
- User Input Errors. If validation is specified for the field/control and an error is detected, the behavior of RM/Panels depends
on the way in which user input was terminated. If the input was terminated by the auto-exit property or by pressing any of
the keys defined in
RMPANELS.WS as having a special function, the error message is displayed and the user is forced to reenter the field/control. If input
was terminated in any other way, control is returned to the application program and
TRUE. If you want the error message displayed under these circumstances, you must execute the SHOW FIELD ERROR standard runtime
function. This approach differs somewhat from the handling of invalid input during the execution of the ACCEPT FIELD function.
During the execution of the EXECUTE EVENT function, RM/Panels assumes that the auto-exit property and any of the keys defined
RMPANELS.WS indicate a normal termination of input. The user should not be allowed to proceed if the input is invalid. During the ACCEPT
FIELD function, RM/Panels assumes that only the auto-exit property and the Enter key indicate normal termination of input.
- The simplest usage of this standard runtime function is as follows:
PERFORM RMP--EE-PANELNAME WITH TEST AFTER UNTIL F3-KEY.
This allows the user to operate all enabled panel fields/controls until the F3 key is pressed. The WITH TEST AFTER phrase
ensures that the standard runtime function is executed at least once before testing the condition-name F3 KEY, in case the
F3 key has just been pressed in another routine.
- The many parameters provided to interpret and control events make it possible to construct sophisticated input routines. The
following sample demonstrates one such routine and is followed by an explanation of the numbered areas.
1 SET RMP--FIRST-FIELD TO TRUE.
2 PERFORM WITH TEST AFTER UNTIL F3-KEY
3 PERFORM RMP--EE-PANELNAME
4 EVALUATE RMP--LAST-FIELD
5 WHEN "CUSTOMER-NUMBER"
6 SET RMP--REPEAT-EVENT TO TRUE
7 WHEN "CUST-BAL"
IF CUST-BAL = 0
8 MOVE "SHIP-CODE" TO RMP--NEXT-FIELD
9 WHEN "SHIP-CODE"
IF SHIP-CODE NOT = OLD-SHIP-CODE
10 SET RMP--REPEAT-EVENT TO TRUE
12 EVALUATE RMP--NEXT-FIELD
13 WHEN "SHIP-CODE"
MOVE SHIP-CODE TO OLD-SHIP-CODE
TRUE tells RM/Panels to begin user input with the first field/control on the panel.
- This is the loop control, specifying the condition that terminates the event loop.
- This is the execution of the event, the entry of a field/control. It is done with the EXECUTE EVENT standard runtime function.
- This is the first of the event tests. The EVALUATE statement is used to determine the field/control on the panel that was
just entered by the user.
- This statement checks to see if the customer number was just entered. If it was entered, a validation routine contained in
the application program is performed.
TRUE forces the customer number to be reentered as the next event, rather than moving on to the next field/control.
- This statement checks to see if the customer balance was just entered.
RMP--NEXT-FIELD forces the next event to be the entry of the
SHIP-CODE field/control, rather than the next field/control on the panel.
- This statement checks to see whether the
SHIP-CODE field/control was just entered. If so, the statement checks to see if the value changed and validates the new value.
TRUE forces reentry of the
- This statement ends the evaluation of the last field/control entered.
- This statement begins evaluation of the next field/control to be entered.
- This statement checks to see whether the
SHIP-CODE field/control is about to be entered. If so, it saves the current value allowing the operations, described previously in
#9, to detect a change in the value.
- This statement ends the evaluation of the next field/control to be entered.
- This statement ends one iteration of the loop.
This type of flexibility provides limitless possibilities. For more conceptual information on event loops, see the discussion
Event Loop Method.
||The function executed successfully.
||The field/control name is invalid.
||The occurrence number is invalid.
||The panel is not in this library
||The library does not exist.
||The panel does not contain any fields/controls.
||The panel contains no input fields/controls.
||The panel is not displayed.
||A COBOL input/output error was encountered on the panel library during execution of this function. To determine the exact
nature of the I/O error, use the C$RERR subprogram.