Working with COM Object

Gentee Programming Language > Documentation > Libraries

The COM library is applied for working with the COM/OLE objects, the IDispatch interface and maintains late binding operations. For using this library, it is required to specify the file olecom.ge (from Lib subfolder) with include command.

This library also contains the support of the VARIANT type, used for data transmitting from/to COM objects.

Variables of the oleobj type are used for working with the COM objects; furthermore, each variable of this type has one appropriate COM object. A COM objects method is called with the help of the ~ late binding operation. There are two ways of binding a COM object with a variable , as follows:
1. The createobj method is used for creating a new COM object:

oleobj excapp
excapp.createobj( "Excel.Application", "" )

2. Binding a variable with the existing COM object (child) is returned by another COM object method call:

oleobj workbooks
workbooks = excapp~WorkBooks

The oleobj object can maintain the following kinds of late binding:

elementary method call excapp~Quit, with/without parameters;

set value excapp~Cells( 3, 2 ) = "Hello World!";

get value vis = uint( excapp~Visible );

call chain excapp~WorkBooks~Add, equals the following expressions
```
oleobj workbooks
workbooks = excapp~WorkBooks
workbooks~Add
```

The method call can return only the VARIANT type, and the appropriate assignment operators and type cast operators are used to convert data to basic Gentee types. Parameters of the COM objects methods call as well as the assigned values are automatically converted to the appropriate VARIANT types. The following Gentee types can be used - uint, int, ulong, long, float, double, str, VARIANT.

Use the release method in order to release the COM object; otherwise, the COM object is released when the variable is deleted; also the object is released when the variable is bound with another COM object.
Have a look at the example of using the COM object

include { "olecom.ge"}
func ole_example 
{
   oleobj excapp   
   excapp.createobj( "Excel.Application", "" )     
   excapp.flgs = $FOLEOBJ_INT
   excapp~Visible = 1   
   excapp~WorkBooks~Add   
   excapp~Cells( 3, 2 ) = "Hello World!"
}

The oleobj object has properties, as follows:

uint flgs are flags. Flags value can be set or obtained; the property can contain the $FOLEOBJ_INT flag, i.e. when transmitting data to the COM object the unsigned Gentee type of uint is automatically converted to the signed type of VARIANT( VT_I4 )

uint errfunc is an error handling function. A function address can be assigned to this property, so using the COM object this function will be called as long as an error occurs; furthermore, this function must have a parameter of the uint type, that contains an error code.

All child objects automatically inherit the flgs property as well as the errfunc property.

VARIANT is a universal type that is used for storing various data and it enables different programs to exchange data properly. This type represents a structure consisted of two main fields: the first field is a type of the stored value, the second field is the stored value or the pointer to a storage area. The VARIANT type is defined as follows:

type VARIANT {
   ushort vt          
   ushort wReserved1     
   ushort wReserved2     
   ushort wReserved3 
   ulong  val
}

vt is a type code of the contained value ( type constants VT_*: $VT_UI4, $VT_I4, $VT_BSTR ... );
val is a field used for storing values
The library provides only some of the operations of the VARIANT type, however, you can use the fields of the given structure
The example illustrates creation of the VARIANT( VT_BOOL ) variable:

VARIANT bool
....
bool.clear()
bool.vt = $VT_BOOL
(&bool.val)->uint = 0xffff// 0xffff - VARIANT_TRUE

There are all possible operations with the VARIANT variable below

Type of the left-hand operand Operator Type of the right-hand operand Result type
VARIANT = ulong VARIANT( VT_UI8 )
VARINAT = long VARIANT( VT_I8 )
VARIANT = uint VARIANT( VT_UI4 )
VARIANT = int VARIANT( VT_I4 )
VARIANT = float VARIANT( VT_R4 )
VARIANT = double VARIANT( VT_R8 )
VARIANT = str VARIANT( VT_BSTR )
VARIANT = VARIANT is equal to the type of the right-hand operand
str = VARIANT( VT_BSTR ) str
oleobj = VARIANT( VT_DISPATCH ) oleobj

There are possible functions used for conversion:

Function name Possible converting types of VARIANT
ulong VT_UI8
long VT_I8
uint VT_UI4, VT_UI2, VT_UI1, VT_I4, VT_I2, VT_I1, VT_BOOL
int VT_UI4, VT_UI2, VT_UI1, VT_I4, VT_I2, VT_I1, VT_BOOL
float VT_R4
double VT_R8
str VT_BSTR

This example shows VARIANT operations

uint val
str  res
oleobj ActWorkSheet
VARIANT vval

....
vval = int( 100 )        //VARIANT( VT_I4 ) is being created
excapp~Cells(1,1) = vval //equals excapp~Cells(1,1) = 100
                        
vval = "Test string"     //VARIANT( VT_BSTR ) is being created
excapp~Cells(2,1) = vval //equals excapp~Cells(1,1) = "Test string"

val = uint( excapp~Cells(1,1)~Value ) //VARIANT( VT_I4 ) is converted to uint 
res = excapp~Cells(2,1)~Value         //VARIANT( VT_BSTR ) is converted to str
ActWorkSheet = excapp~ActiveWorkSheet //VARIANT( VT_DISPATCH ) is converted to oleobj

Methods

VARIANT Methods

Methods

oleobj.createobj Creating COM object
oleobj.getres Result of the last operation
oleobj.iserr Enables to define whether or not an error occurs while working with a COM object
oleobj.release Releasing the COM object

VARIANT Methods

variant.arrcreate Creating the SafeArray array
variant.arrfromg Assigning a value to an element of the SafeArray array
variant.arrgetptr Obtaining a pointer to an element of the SafeArray array
variant.clear Clearing a variable
variant.isnull Enables to define whether or not a variable is NULL

Type of the left-hand operand	Operator	Type of the right-hand operand	Result type
VARIANT	=	ulong	VARIANT( VT_UI8 )
VARINAT	=	long	VARIANT( VT_I8 )
VARIANT	=	uint	VARIANT( VT_UI4 )
VARIANT	=	int	VARIANT( VT_I4 )
VARIANT	=	float	VARIANT( VT_R4 )
VARIANT	=	double	VARIANT( VT_R8 )
VARIANT	=	str	VARIANT( VT_BSTR )
VARIANT	=	VARIANT	is equal to the type of the right-hand operand
str	=	VARIANT( VT_BSTR )	str
oleobj	=	VARIANT( VT_DISPATCH )	oleobj

Function name	Possible converting types of VARIANT
ulong	VT_UI8
long	VT_I8
uint	VT_UI4, VT_UI2, VT_UI1, VT_I4, VT_I2, VT_I1, VT_BOOL
int	VT_UI4, VT_UI2, VT_UI1, VT_I4, VT_I2, VT_I1, VT_BOOL
float	VT_R4
double	VT_R8
str	VT_BSTR

oleobj.createobj	Creating COM object
oleobj.getres	Result of the last operation
oleobj.iserr	Enables to define whether or not an error occurs while working with a COM object
oleobj.release	Releasing the COM object

variant.arrcreate	Creating the SafeArray array
variant.arrfromg	Assigning a value to an element of the SafeArray array
variant.arrgetptr	Obtaining a pointer to an element of the SafeArray array
variant.clear	Clearing a variable
variant.isnull	Enables to define whether or not a variable is NULL