As explained above, Embedded Procedures can be used to handle the most common actions the user can do, such as activating and leaving a control.

The user can interact with controls in a number of ways, however, and creating a new Embedded Procedure for every possible action would be confusing and not efficient at all. Handling events is preferable in most cases.

When EVENT PROCEDURE is declared for the control, the paragraph(s) procedure-1 (thru procedure-2) are executed when the control fires an event.

In a CLASS-ID program the method where the paragraphs are defined must be specified as well; methodName must be written as string literal as it is case sensitive; the referenced method must be without parameters; if the SCREEN SECTION is declared in the FACTORY paragraph, you cannot reference a method declared in the OBJECT paragraph, instead you can do the opposite.

Events are categorized into three groups:

Event names are listed as constant items in the isgui.def copybook.

Just one Event Procedure can be assigned to a control at a time and it is executed each time that control fires an event. Within Event Procedures, the EVENT STATUS special registry can be used to monitor and change the event behavior.

Events cannot be nested, therefore in the event procedure code you shouldn’t:

For the above needs, it’s suggested that you:

Note: Embedded and Event procedures are paragraphs and sections automatically executed by the runtime while the user interacts with the screen. The program jumps to these paragraphs as if a PERFORM statement was issued, then, when the paragraph code has been executed, the program returns to the ACCEPT statement. Therefore, it is strongly suggested that you avoid using GO TO statements into these paragraphs; if the program jumps outside these paragraphs through a GO TO statement, it may not be able to return to the ACCEPT, causing it to hang.

Performance Tuning: In the Thin Client environment, when the focus changes, no information is sent from the client to the server if:

In this case the program will run faster.

The isCOBOL Framework allows you to specify a program that will be automatically invoked when a particular event occurs. By using this feature you don’t need to code a EVENT PROCEDURE for every control, but you can have a centralized event handling performed by an external event handler program.

The association between the event and the event handler program is performed through the following configuration setting:

Where:

You can specify multiple entries of this kind, one for each event handler program. You can also have multiple events managed by the same program, by specifying more event numbers separated by comma. For example, let’s say you wish to handle MSG-BEGIN-ENTRY and MSG-FINISH-ENTRY through an external program named GRIDENTRY and the MSG-BITMAP-CLICKED event through an external program named BMPCLICK. This is the necessary configuration:

The event handler program, automatically invoked by the runtime, receives the EVENT-STATUS group item as parameter.

The event handler program is invoked before executing the EVENT PROCEDURE of the control that generated the event. The EVENT PROCEDURE, if any, will be executed later, unless the event handler program exits with a return code 1.

The event handler program can set the EVENT-ACTION item of EVENT-STATUS to control the runtime response to the event (i.e. fail, terminate ACCEPT, etcetera). EVENT-ACTION may be reset by the control’s EVENT PROCEDURE later, though.

This is the typical structure of an event handler program: