# 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](https://d3codex.com/pickbasic-flashbasic/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.

---
Source: https://d3codex.com/pickbasic-flashbasic/using-the-com-interface-to-flashbasic/ - part of the D3Codex reference.