This section describes the events that can be generated when you are using graphical windows and controls in an event-driven environment.
Events are categorized into command events, notify events, and messages. Generally speaking, command events correspond to actions taken by the user that the program needs to act on (for example, closing a window or pushing a button). Notify events generally correspond to informational events that the program may not have to act on. Messages pass information to a screen control's event procedure. This division is somewhat arbitrary, but corresponds to the most common situations.
When a command or notify event occurs, the run-time system assigns a value to the EVENT STATUS data item and then terminates the current ACCEPT with an exception value of 96. Note that the termination occurs even if the particular ACCEPT statement does not normally allow exceptions. The program should examine the EVENT STATUS data item to determine what happened.
Messages are different from other events, because they do not terminate the current ACCEPT. Messages are sent only to a control's event procedure. See PROCEDURE Clause for a detailed discussion of event procedures.
The EVENT STATUS phrase is described in Special-Names Paragraph. The EVENT STATUS data item should be defined as follows:
01 EVENT-STATUS. 03 EVENT-TYPE PIC X(4) COMP-X. 03 EVENT-WINDOW-HANDLE USAGE HANDLE OF WINDOW. 03 EVENT-CONTROL-HANDLE USAGE HANDLE. 03 EVENT-CONTROL-ID PIC XX COMP-X. 03 EVENT-DATA-1 USAGE SIGNED-SHORT. 03 EVENT-DATA-2 USAGE SIGNED-LONG. 03 EVENT-ACTION PIC X COMP-X.
A copy of this data item appears in the COPY file crtvars.def.
In the Screen Section, notification events are treated slightly differently from command events. Normally, when an event triggers an EXCEPTION procedure, the ACCEPT-CONTROL field of the SCREEN CONTROL status item is initialized to 0. This causes the ACCEPT statement to terminate after the EXCEPTION procedure completes. You can cause the ACCEPT statement to continue processing fields by moving alternate values to the ACCEPT-CONTROL data item. When a notification event triggers an EXCEPTION procedure, the ACCEPT-CONTROL field is initialized to 1 instead. This causes the ACCEPT statement to continue processing the current field when the EXCEPTION procedure terminates. This is done as a convenience. Most notification events can be handled entirely within the EXCEPTION procedure and should not terminate ACCEPT processing. If you need to terminate the controlling ACCEPT, simply move a 0 to ACCEPT-CONTROL inside the EXCEPTION procedure.
Event values can be found in the file acugui.def. The names given in the next section are the level 78 data items found in that file.