C$SETEVENTPARAM

C$SETEVENTPARAM is an alternate way to set event parameters for ActiveX controls. Use it to set 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$SETEVENTPARAM allows you to set the values of only the parameters you care about.

Please note that C$SETEVENTPARAM cannot be used to set event parameters for COM objects. You must use C$SETEVENTDATA for COM objects.

Usage

CALL "C$SETEVENTPARAM" 
    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	Source item containing 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$SETEVENTPARAM converts the COBOL-type data in the source item to the named event parameter's type. Using this routine instead of C$SETEVENTDATA 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$SETEVENTDATA. 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 source item you specify is alphabetic, and the event parameter you are setting is a signed integer, C$SETEVENTPARAM tries to read a number from the alphabetic item and move it to the event parameter. This is not a programming error and neither the compiler nor runtime warns you about it.

Example

Suppose you have displayed an ActiveX control that triggers an event called AxEventOne which has three parameters. Then suppose 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 using C$SETEVENTDATA. For example:

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

However, If 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.

See ActiveX and COM Events for more examples of how to set event parameters for ActiveX events.