ActiveX and COM Events

ActiveX control and COM object 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 or COM object event occurs, the control or object invokes its 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, see Control Events.

MSG-AX-EVENT (value 16436) occurs when an ActiveX control or COM object has "fired" an event. EVENT-DATA-2 contains the control's event type. For COM objects, you can use the C$SETEVENTDATA and C$GETEVENTDATA library routines to set and get event the event parameters for the current event.

For ActiveX controls, however, you can use C$GETEVENTDATA/C$SETEVENTDATA, or you can use the C$GETEVENTPARAM/C$SETEVENTPARAM routines to get and set individual event parameters.

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. For details, see the CalendarBeforeUpdate definition in the control's COPY file.

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 is "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

To use C$GETEVENTPARAM and C$SETEVENTPARAM, 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 file for the ActiveX control.

Note:

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.

An event commonly receives 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. Because 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 the task in our example in a more elegant and readable way. For example:

call "c$seteventparam" using event-control-handle, 
      "param3", param-3.

In the Calendar example, you would use:

call "c$seteventparam" using event-control-handle,
      "cancel", 1

instead of:

call "c$seteventdata" using event-control-handle, 1

And you would use:

call "c$geteventparam" using event-control-handle, 
      "KeyAscii", key-ascii

instead of:

call "c$geteventdata" using event-control-handle, key-ascii

Using these routines can make your code more readable. The object code will be a little larger, and your program will run slightly slower. However, these differences may be unnoticeable and the benefits of readable code can 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 item is 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 has the value zero.

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

For more information on the C$GETEVENTDATA, C$SETEVENTDATA, C$GETEVENTPARAM, and C$SETEVENTPARAM library routines, see Library Routines.