6.10.3 ActiveX Events

ActiveX control events can have any number and type of associated parameters or no parameters. The event parameters are used to provide information about the event to the program. They can also be used to get information from the program in response to the event.

When an ActiveX control event occurs, the control invokes it's event procedure. The EVENT-STATUS data item reflects the invoking event. EVENT-TYPE is either CMD-GOTO, CMD-HELP, MSG-VALIDATE, or MSG-AX-EVENT. For a description of these events, refer to section 6.2 of Book 2, "User Interface Programming Guide."

MSG-AX-EVENT (value 16436) occurs when an ActiveX control has "fired" an event. EVENT-DATA-2 contains the ActiveX control's event type. Two pairs of library routines, C$GETEVENTDATA/C$SETEVENTDATA and C$GETEVENTPARAM/C$SETEVENTPARAM are used to get and set the event parameters for the current event. For example,

01 DATE-1
    03 MONTH PIC 99.
    03 FILLER PIC X VALUE '/'.
    03 DAY PIC 99.
    03 FILLER PIC X VALUE '/'.
    03 YEAR PIC 99.
77 KEY-ASCII PIC X USAGE COMP-X.
77 KEY-CHAR PIC X REDEFINES KEY-ASCII.
...

* Handle events
...
 CALENDAR-EVENT-HANDLER.
      EVALUATE EVENT-TYPE
         WHEN MSG-AX-EVENT
              EVALUATE EVENT-DATA-2
                 WHEN CalendarBeforeUpdate
* Don't allow years >= 2020
                     INQUIRE EVENT-CONTROL-HANDLE Value IN DATE-1
                     IF YEAR OF DATE-1 >= 2020
* Cancel the update (set the 'Cancel' parameter to 1)
                         CALL "C$SETEVENTPARAM" USING
                          EVENT-CONTROL-HANDLE, "Cancel", 1
                    END-IF
                  WHEN CalendarKeyPress
* Stop run if the user presses 'X'
                     CALL "C$GETEVENTPARAM" USING
                          EVENT-CONTROL-HANDLE, "KeyAscii", KEY-ASCII
                     IF KEY-CHAR = 'X' STOP RUN END-IF
...

Note that the CalendarBeforeUpdate event has one parameter, "Cancel." (See the 'CalendarBeforeUpdate' definition in the control's copybook.)

In this example, EVENT-CONTROL-HANDLE contains the handle of the control that fired the event (e.g., CALENDAR-1). C$SETEVENTPARAM is used to set the Cancel parameter to "1" in response to a CalendarBeforeUpdate event when the year is 2020 or later. C$GETEVENTPARAM is used in the handling of the CalendarKeyPress event to get the key value and stop the runtime if it 'X'.

For another example, suppose you have displayed an ActiveX control called "AX" whose handle is in AX-1. Further suppose that this control fires an event called AxEventOne which has three parameters. You would use the following COBOL syntax to get the event parameters, add "2" to each one and set the event parameters to their new values:

EVALUATE EVENT-TYPE
    WHEN W-EVENT
        EVALUATE EVENT-DATA-2
            WHEN AxEventOne
              CALL "C$GETEVENTDATA" USING EVENT-CONTROL-HANDLE,
                   PARAM-1, PARAM-2, PARAM-3
              ADD 2 TO PARAM-1
              ADD 2 TO PARAM-2
              ADD 2 TO PARAM-3
              CALL "C$SETEVENTDATA" USING EVENT-CONTROL-HANDLE,
                   PARAM-1, PARAM-2, PARAM-3

C$GETEVENTPARAM and C$SETEVENTPARAM are an alternate way to get and set individual event parameters. To use these routines, you must know the actual names of the parameters. You can determine these names by reading the ActiveX control's documentation or by looking at the definitions in the copy book for the ActiveX control.

Note that using the C$SETEVENTPARAM approach, you do not need to pass all of the event parameters. You need to specify only the name of the particular parameter you want to set. With C$SETEVENTDATA you don't need to specify parameter names, but you must pass an ordered parameter list up to the parameter you want to set.

It is common for an event to receive many parameters. C$GETEVENTPARAM and C$SETEVENTPARAM allow you to get and set the values of only the parameters you care about. Suppose in the above example that PARAM-1 and PARAM-2 contain information about the event and that only PARAM-3 is meant to be set by the event procedure. Since PARAM-3 is the third parameter, to set it you would have to pass two "dummy" parameters to C$SETEVENTDATA. For example,

CALL "C$SETEVENTDATA" USING EVENT-CONTROL-HANDLE,
      0, 0, PARAM-3.

Suppose you determined that the name of PARAM-3 in the ActiveX control was "Param3". You could then use C$SETEVENTPARAM to accomplish this task in a more elegant and readable way. For example:

CALL "C$SETEVENTPARAM" USING EVENT-CONTROL-HANDLE,
      "Param3", PARAM-3.

In the Calendar example above you would use:

CALL "C$SETEVENTPARAM" USING EVENT-CONTROL-HANDLE, "Cancel", 1

instead of:

CALL "C$SETEVENTDATA" USING EVENT-CONTROL-HANDLE, 1

And:

CALL "C$GETEVENTPARAM" USING EVENT-CONTROL-HANDLE,
      "KeyAscii", KEY-ASCII

instead of:

CALL "C$GETEVENTDATA" USING EVENT-CONTROL-HANDLE, KEY-ASCII

Using these routines will make your code more readable. The object code will be a little larger and your program will run slightly slower. However, these differences will probably be unnoticeable and the benefits of readable code probably outweigh the performance and size considerations.

To determine in which specific window and control the event occurred, you can use the EVENT-WINDOW-HANDLE, EVENT-CONTROL-HANDLE, and/or EVENT-CONTROL-ID fields in the event procedure.

EVENT-WINDOW-HANDLE holds the handle of the floating window in which the event occurred. If the event occurred in a control, this will be the handle of the floating window that contains the control.
EVENT-CONTROL-HANDLE holds the handle of the control in which the event occurred. If the event did not occur in a control, this item is set to NULL.
EVENT-CONTROL-ID holds the ID of the control in which the event occurred. IDs are assigned by the application when each control is created. If the event did not occur in a control, this item will have the value zero.

During an ActiveX event, you can refer to the control which "fired" the event using the EVENT-CONTROL-HANDLE item.