C$GETEVENTPARAM

C$GETEVENTPARAM is an alternate way to get event parameters for ActiveX controls. Use it to get a single event parameter when there are several for an event. To use this routine you must know the actual name of the parameter. You may determine these names by reading the ActiveX control's documentation or by looking at the definitions in the copy book for the ActiveX control.

It is common for an ActiveX event to receive many parameters. C$GETEVENTPARAM allows you to get the values of only the parameters you care about.

Note that C$GETEVENTPARAM cannot be used to get event parameters for COM objects. You must use C$GETEVENTDATA for COM objects.

Usage

CALL "C$GETEVENTPARAM" 
    USING EVENT-CONTROL-HANDLE, PARAM-NAME, PARAM-VALUE
    GIVING RESULT-CODE

Parameters

EVENT-CONTROL-HANDLE USAGE HANDLE	Handle to the control that generated the event.
PARAM-NAME PIC X(n)	The symbolic name of the event parameter.
PARAM-VALUE Any COBOL data type	Destination item to receive the event parameter's value.
RESULT-CODE Signed numeric value	Receives the result-code for the operation. This will be 0 to indicate success or a negative value to indicate failure. (Microsoft defines many standard result codes in their documentation. Note that these are usually in hexadecimal notation.)

Comments

C$GETEVENTPARAM converts the named event parameter's value to COBOL-type data in the destination item. Using this routine instead of C$GETEVENTDATA will make your code more readable. The object code will be a little larger and calls to this routine will take a little longer than calls to C$GETEVENTDATA. However, these differences will probably be unnoticeable and the benefits of readable code outweigh the performance and size considerations.

You are responsible for specifying a compatible types. For example, if the event parameter is a character string and you specify a numeric item to receive its value, C$GETEVENTPARAM will try to read a number from the string and move it to your numeric item. This is not a programming error and neither the compiler nor runtime will warn you about it.

Example

Suppose you have displayed an ActiveX control that triggers an event called AxEventOne which has three parameters. Then suppose that you only need to know the value of PARAM-2. Since PARAM-2 is the second parameter, to get its value you would have to pass a "dummy" first parameter using C$GETEVENTDATA. For example:

CALL "C$GETEVENTDATA" USING EVENT-CONTROL-HANDLE, 0, PARAM-2.

However, if you determined that the name of PARAM-2 in the ActiveX control was Param2. You could then use C$GETEVENTPARAM to accomplish this task in a more elegant and readable way. For example:

CALL "C$GETEVENTPARAM" 
    USING EVENT-CONTROL-HANDLE, "Param2", PARAM-2.

For more examples of how to get event parameters for ActiveX events, see ActiveX and COM Events.