Using the COM interface to FlashBASIC

This topic describes the COM interface to FlashBASIC. The objective is to allow a FlashBASIC module to act as an Automation Controller. This module can be a main, a trigger, or a rule module.

Methods, property get, and property set are called only by names. These are supported in dispInterface.

For more information on these interfaces, see FlashBASIC automation application interfaces.

FlashBASIC Module Example

include dm,bp,includes nt_util.inc
cFunction fsicli.builtin
include dm,bp,includes flashauto.inc
 
* Initialize the COM library.
hAutoCTRL = 0
code = %CoInitialize( &hAutoCTRL )
if code = 0 then stop
 
* Create a COM object and get the IUnknown interface pointer.
pUnk = 0
code = %CoCreateObject( hAutoCTRL, "Excel.Application.15", &pUnk )
if code = 0 then goto error
 
* Call to Query for the IDispatch interface.
hObjExApplication = 0
code = %CoQueryInterface( pUnk, IID_IDispatch, &hObjExApplication )
if code = 0 then goto error
 
* Call a property Put to make the Excel object visible. 
* Note: b is the format string for the Boolean data type.
true = 1
code = %CoPropertyPut( hObjExApplication, "Visible", "b", TRUE )
if code = 0 then goto error
 
* Call a property get dispatch to get the WorkBook collection. 
* Note: 0 is a NULL format string, * which means no argument to the invoked method.
hObjWorkBooks = 0
code = %CoGetDispatch( hObjExApplication, "WorkBooks", &hObjWorkBooks, 0 )
if code = 0 then goto error
 
* Call a property get dispatch to add a WorkBook into this WorkBooks collection. 
* Note: Add is the method name. 0 is a NULL format string, which means no arguments 
* to the invoked method.
hObjWorkBook = 0
code = %CoGetDispatch( hObjWorkBooks, "Add", &hObjWorkBook, 0 )
if code = 0 then goto error
 
* Call a property get dispatch to get the Worksheet.
hObjActiveSheet = 0
code = %CoGetDispatch( hObjExApplication, "ActiveSheet", &hObjActiveSheet, 0 )
if code = 0 then goto error
 
* Call a property get dispatch to get a Range object in the worksheet. 
* Note: s is the format string for the string data type. A1 is cell A1.
hObjRange = 0
code = %CoGetDispatch( hObjActiveSheet, "Range", &hObjRange, "s", "A1" )
if code = 0 then goto error
 
* Call a property Put to put a string into A1. Note: Value is the property name. 
* s is the format string for the string data type. Company A is the value to put 
* in cell A1.
code = %CoPropertyPut( hObjRange, "Value", "s", "Company A")
if code = 0 then goto error
 
* Call a method to save this Excel Workbook as d:\autoctrl.xls. 
* Note: 0 means not returning a dispatch object.
code = %CoInvoke( hObjWorkBook, "SaveAs", DISPATCH_METHOD, 0, "s",
"c:\temp\autoctrl.xlsx")
if code = 0 then goto error

* Call a method to quit Excel. Note: The first 0 means not returning a dispatch
* object. The second 0 specifies that there is no argument to the invoked method.
code = %CoInvoke( hObjExApplication, "Quit", DISPATCH_METHOD, 0, 0 )
if code = 0 then goto error
goto done
 
error:
ExceptStr = ""
MsgLen = %CoGetException( hAutoCTRL, ExceptStr )
%CoUninitialize( hAutoCTRL )
stop
 
done:
%CoUnInitialize( hAutoCTRL )

The object is an opaque handle to the IDispatch interface of the object.

Note: As an enhancement, a precompiler could read the type library associated to an object and understand the various methods, properties, and arguments to generate the appropriate % function calls.

FlashBASIC Automation Object Handle

The automation object handle is returned to FlashBASIC as an integer. This handle is a pointer to an internal FlashBASIC Automation object that contains the IDispatch interface pointer, exception information, and name cache.

For performance reasons, the FlashBASIC Automation object contains a cache of the methods to associate the name and type to a DISPID.

FlashBASIC Automation Arguments

All FlashBASIC arguments are coerced into VARIANTS.

Flash Automation Reserved Arguments

TRUE and FALSE are reserved for the CoPropertyPut, CoPropertyGet, CoGetDispatch, and CoInvoke. For example:

* Call a property Put to make the Excel object visible.
code = %CoPropertyPut( hObjExApplication, “Visible”, “b”, TRUE )
if code = 0 then goto error

Exceptions

The FlashBASIC Automation object contains an EXCEPINFO structure that can be queried from FlashBASIC by %CoGetException, which returns a string containing the error description.