The Variant type is capable of storing values that change type dynamically. Variables of any other type (Integer, String, Date, etc) are statically bound to that type but a variable of the Variant type can assume values of differing types at runtime.
You would use a Variant type in situations where the actual type of your data is unknown at compile-time. This is a common situation when writing applications that use COM objects.
Variant is a native type and therefore you can declare a Variant as follows:
Variant vMyData
The above will declare a variable of type Variant called vMyData.
The Variant type can be used to declare global or local variables, properties, function return types, and procedure or function parameters.
Variants have the following characteristics:
Variants can contain Integer, Number, Real, Boolean, Date, Time, TimeSpan, DateTime, String, Handle and IDispatch pointer values.
The special Variant value OLE_VT_EMPTY is used to indicate that a Variant has not yet been assigned any value.
Variants can be combined with other Variants and Integer, String, Boolean etc. values in an expression. The DataFlex expression evaluator will automatically perform the necessary type conversions.
When a Variant contains a reference to a COM Object (IDispatch*), then it automatically performs reference counting for the referenced object.
The use of Variants is very straightforward. The following example demonstrates moving a Variant value into a String variable:
Variant vMyData
String sMyString
Move vMyData to sMyString
The variable sMyString will now hold the same value as vMyData converted to the String type.
Similarly, assigning the contents of another variable into a Variant variable is also very straightforward:
Variant vMyData
String sMyString
Move sMyString to vMyData
The following is an example of invoking a COM method expecting a Variant parameter:
Variant vMyData
Move 01/01/2000 to vMyData
Set ComValue of oCalendar1 to vMyData
Since Variant is a native data type, implicit conversion will automatically be performed if necessary. Therefore you can also pass any other type and it will automatically be converted to the expected type:
Set ComValue of oCalendar1 to 01/01/2000
In the above code the date literal will be implicitly converted to Variant. This is a lot simpler than the code needed in prior revisions of FlexCOM to accomplish the same task.
It is important that COM object references (IDispatch* values) are controlled only by Variant types in order to maintain automatic reference counting of COM objects. Changing a Variant variable that contains a COM object reference or setting it to NULL (using the NullComObject function) automatically releases any reference to the COM object pointed to by the old value.
When Variant variables go out of scope they delete their contents automatically. In the case of a Variant containing an IDispatch*, the referenced COM object is released. Thus the reference count of the COM object is automatically decremented when a variant goes out of scope.
Variant variables containing IDispatch* values can not be converted to any other data type. The DataFlex runtime protects against this and will raise an error ("Illegal type conversion"). Such a conversion is meaningless and, if allowed, could subvert DataFlex's reference counting mechanism for COM objects.
The DataFlex runtime also protects against pointer arithmetic and comparison expressions for variant variables containing an IDispatch*. Doing so would also raise a runtime error. The helper functions IsNullComObject and IsSameComObject can be used to perform any operations that you would normally require on variants containing IDispatch* values.
Programming with COM – General Topics