Micro Focus Visual COBOL 2.3 Update 2 for Eclipse (Windows) > Programming > Compatibility > Compatibility with RM/COBOL > RM/Panels > Writing Programs > Standard Runtime Functions > EXECUTE EVENT

EXECUTE EVENT

Execution

PERFORM RMP--EE-PANELNAME

Description

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.

Required Parameters

There are three ways to specify which field/control receives input focus on each execution of the EXECUTE EVENT standard runtime function:

If you want to begin entry on the first field/control of the panel, RMP--FIRST-FIELD must be set to TRUE.
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.

Returned Values

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 RMP--EXCEPTION- NUMBER.

The values of RMP--LAST-FIELD, RMP--LAST-OCCUR, RMP--NEXT-FIELD, and RMP--NEXT-OCCUR are also set to the appropriate values for the next event. Occurrence numbers are equivalent to COBOL subscripts and begin at 1.

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 parameter.

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 RMP--INVALID-INPUT is 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 in 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.

Example

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"
             PERFORM CUSTOMER-VALIDATION
             IF CUST-NOT-VALID
6               SET RMP--REPEAT-EVENT TO TRUE
             END-IF
7         WHEN "CUST-BAL"
             IF CUST-BAL = 0
8               MOVE "SHIP-CODE" TO RMP--NEXT-FIELD
             END-IF
9         WHEN "SHIP-CODE"
             IF SHIP-CODE NOT = OLD-SHIP-CODE
                PERFORM VALIDATE-SHIP-CODE
                IF SHIP-CODE-NOT-VALID
10                 SET RMP--REPEAT-EVENT TO TRUE
                END-IF
             END-IF
11     END-EVALUATE
12     EVALUATE RMP--NEXT-FIELD
13        WHEN "SHIP-CODE"
             MOVE SHIP-CODE TO OLD-SHIP-CODE
14     END-EVALUATE
15 END-PERFORM.

Setting RMP--FIRST-FIELD to 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.
Setting RMP--REPEAT-EVENT to 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.
Moving SHIP-CODE to 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.
Setting RMP--REPEAT-EVENT to TRUE forces reentry of the SHIP-CODE field/control.
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 of Event Loop Method.

RMP--STATUS Values

Status value	Description
0	The function executed successfully.
1	The field/control name is invalid.
2	The occurrence number is invalid.
5	The panel is not in this library
6	The library does not exist.
8	The panel does not contain any fields/controls.
9	The panel contains no input fields/controls.
10	The panel is not displayed.
14	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.