Coding event parameter definitions

As for any procedure definition, you code event procedure parameters using the DEFINE PARAMETER statement. When you create an event procedure as an OCX trigger in the AppBuilder, the AppBuilder provides default definitions for all required parameters. These default definitions attempt to specify an ABL data type that is compatible with the COM data type of the corresponding OCX event parameter. This data type generally follows the data type mappings shown in the following table.

Table 64. Data type mappings for OCX event parameters
COM data type	ABL data type
Array	ABL array variable
Array of bytes	RAW
Boolean	LOGICAL
Byte	INTEGER
Currency	DECIMAL
Date Double	DATE DATETIME DATETIME-TZ
Double	DECIMAL
Integer (2-byte integer)	INTEGER
Long (4-byte integer)	INTEGER
Object (COM)	COM-HANDLE
Single (float)	DECIMAL
String	CHARACTER LONGCHAR
Unsigned byte	INTEGER
Unsigned long (4-byte integer)	INTEGER
Unsigned short (2-byte integer)	INTEGER
Variant	ANYTYPE¹
VT-ARRAY (if single-dimensional array of bytes)	RAW

¹ You must replace ANYTYPE, provided by the AppBuilder in some OCX event trigger templates, with a valid ABL data type.

For event procedures you write yourself, you can also find the suggested ABL data type for each parameter displayed in the OpenEdge COM Object Viewer for each selected control event. For more information on this viewer, see UsingCOM Objects in ABL.

In the AppBuilder, ABL uses data type mappings from the COM data type specified in the Type Library for the ActiveX control. If ABL cannot determine a data type mapping, the AppBuilder specifies ANYTYPE as a place holder. You must change ANYTYPE to the data type that most closely matches the expected value. ABL does its best to convert the COM data type to the ABL data type you specify. For more information on a COM data type, see the available documentation on the Microsoft Component Object Model and the event parameter you want to convert, see COMObject Data Type Mapping. For information on Type Libraries and ABL, see UsingCOM Objects in ABL.

The AppBuilder also provides a default mode option (INPUT, OUTPUT, or INPUT-OUTPUT) for each parameter definition. Here, although ABL does its best to interpret the information in the Type Library for the ActiveX control, this is not a direct mapping. You might have to modify the mode option. If the option chosen by ABL is incorrect, this generates a run-time error. If the event parameter is passed as read-only, define it as an INPUT parameter. If you can change its initial value and must pass it back to the ActiveX control, define it as an INPUT-OUTPUT parameter. If only the value you return to the ActiveX control has any meaning, define it as an OUTPUT parameter.

Caution: If an INPUT parameter passes in a COM-HANDLE value, use the RELEASE OBJECT statement to release the specified COM object when you no longer need it (usually before the event procedure returns). Otherwise, the component handle might become unavailable and the COM object might never be released. Also, not releasing the COM object in the event procedure can cause unpredictable behavior with some controls.

Caution: In most contexts, OCX event procedures behave as expected. However, if an event procedure has any INPUT-OUTPUT or OUTPUT parameters, and the event procedure executes while blocking on non-modal .NET forms, if the procedure directly or indirectly executes an additional ABL input-blocking or event processing statement (such as UPDATE or WAIT-FOR) that blocks on a non-modal ABL window, the output parameters are not returned to the control. For more information about restrictions when input-blocking on both .NET forms and ABL windows, see OpenEdge Development: GUI for .NET Programming.