OLE Automation with ClassiX®

ClassiX^® provides external application programming and controlling via OLE automation. Let us take a closer look at the MS Office products. Everyone who has programmed with Visual Basic before will easily work with InstantView^®. The object catalogue provided by Microsoft applications is an important tool. It can be accessed, via Alt+F11 under 'View' > 'object catalogue'. It lists all classes and enumerations for the selected applications in the left window. Clicking on one of them, the right window displays the according methods, attributes and events, as well as a short syntax explanation plus description. The Help function can be accessed via context menu.

Program an external application

When programming an external application, first of all this application needs to be understood. This works best by understanding the application object model. For this, please use the object catalogue or literature, such as [1] as well as the internet, see

[2]. Information on VB programming by Office 2000 under

[3].

To start with the programming, it is necessary to find out the name of an original class. All Office applications provide the class 'application', which serves the application programming itself. Additionally, there are classes for the according documents, such as Word.Document or Excel.Sheet. All these class names can be looked up in the Windows registry under the key 'HKEY_CLASSES_ROOT', which lists all applications and file types registered in the system. All directly accessible Word classes can be found for example under Word.* (here the star represents the class name). For example the class Word.Document is provided to program a Word document. A number behind the class name indicates the equivalent version; no number always means the current version.

COM objects in ClassiX^®

With this information it is now possible to start with the programming. Since all COM objects in ClassiX^® are CX_COM_OBJECTs, at first, a new object of the type CX_COM_OBJECT must be generated. This provides the method CreateFromProgID, to establish the connection to the application. The name of the required class will be passed as a parameter.

Example:

    Var(doc)
    CreateTransObject(CX_COM_OBJECT) -> doc
    "Word.Document" doc Call(CreateFromProgID)

Equivalent code in VB:

Dim doc As Word.Document
Set doc = CreateObject("Word.Document")

The object doc now represents the class Word.Document. All data fields and methods of this class can be used. To use a method, the parameters are put into the stack before the according method gets called via Call(<MethodName>):

Example:

"C:\example.doc" doc Call(Compare)

Equivalent code in VB:

doc.Compare("C:\example.doc")

Data field values are defined and read out in a similar way. Each data field name gets converted into two methods once with 'put' and once with 'get' in front of the data field name. This can now be called just like any other method:

"secret" doc Call(PutPassword)
doc Call(GetPassword)

Equivalent code in VB:

doc.Password = "secret"
doc.Password

The data field 'Password' gets defined with 'PutPassword' and read out straight after with 'GetPassword'. Now, the string "secret" is in the stack.

Collections and objects

Whenever a method or a data field returns an object, this object always a CX_COM_OBJECT, but represents the according VB object and can be used just like every normal ClassiX^® object.
Whenever a collection gets returned, it can be used, just like a collection under ClassiX^®. Here, the 'Iterate' statement is the equivalent for the 'For Each ... Next' loop in VB.

Example:

    Var(Foo)
    1 100 doc Call(Range) Call(Rows)
    Iterate
    {
    Call(GetAlignment) -> Foo
    }

Equivalent code in VB:

    Dim Foo As Byte
    For Each thisRow In doc.Range(1,100).Rows
    Foo = ThisRow.Alignment
    Next

These statements should always be preferred instead of a normal loop manually counting up the index, since they are smaller and much easier to read.

Events

So far, events that are provided by the external application can only be used in ClassiX^® ActiveX Controls, not in normal OLE automation.

Arrays

Arrays are not yet supported by the ClassiX^® COM interface. This means that in Classix it is not possible to pass arrays to COM object methods, nor to call COM object methods if they return arrays.

Constants

Whenever an attribute or a method - according to documentation or object explorer - returns a constant, it cannot be adopted into this form, since there are no constants in InstantView^®. Instead, the constant integer value needs to be used in InstantView^® . The value gets displayed for example in the object explorer. For better readability, it is possible to assign the value to a variable, which will receive the constant name. However, here it is necessary to make sure that the variable is naturally changeable.

Provides document type (document, master, ...) as Enum WdDocumentType. This is a constant in VB, in InstantView^®, there is now an integer value in the stack, which can be assigned to a variable. Setting an attribute is done in the same way. The required constant value can be found out in the object catalogue, and it will be simply set, just like every other attribute.

1 1 100 doc Call(Range) Call(PutCase)

and in VB:

doc.Range(1, 100).Case = wdUpperCase

Here, all letters are converted into capitals for the selected area (the first 100 characters).

Optional parameters

Another difference between VB and InstantView^® is the handling of function parameters. While VB supports optional parameters, which can always be left out, this is only possible for the last optional parameters in InstantView^®. Here it is necessary to make sure, that no old values happen to be in the stack, which could be mistaken for parameters.

"C:\example.doc" doc Call(SaveAs)s)

Although the method SaveAs understands diverse parameters, this InstantView^® statement does work, since the file name is the first expected parameter. Here, it needs to be guaranteed, that the stack is empty, since any eventually existent elements could be mistaken for further parameters. This would either cause an unexpected result or a problem report due to a wrong type. The following VB statement is not possible in InstantView^®:

doc.SaveAs "C:\example.doc" ,,,"secret"

Here, other than a file name, SaveAs also gets a password to open the document. To realize this statement in InstantView^®, it would be necessary to pass default values for all left out parameters:

"C:\example.doc" 0 FALSE "secret" doc Call(SaveAs)

Here, 0 stands for the storage format, which is the Microsoft Word format by default. The FALSE parameter is default value for the setting, whether the document shall be locked for comments.

Performance

Finally some performance information. Every method call, definition or getting a method takes time. This can make longer navigation from one object to the other take quite a while. Now making two calls out of the target object, it is much more efficient to buffer the object once in a variable, instead of completely navigating from the original class every time.

3 1 100 doc Call(Range) Call(Next) Call(Copy)
3 1 100 doc Call(Range) Call(Next) Call(Select)

Is not as efficient as

    Var(next)
    3 1 100 doc Call(Range) Call(Next) -> next
    next Call(Copy)
    next Call(Select)

This works for VB as well as for InstantView^®.
Furthermore, variable access is always faster than an access path to an object attribute or method. This becomes noticeable especially in loops, because of which it is advisable to do without access paths and assign the access path return value to a variable before the loop.

Byte, Integer, Long:	integer
Single, Double:	CX_NUMERIC
Currency:	CX_VALUE
String:	string
Variant:	the according Fix type
Boolean:	CX_BOOLEAN
Date:	CX_DATE/CX_TIME/CX_DATETIME
Object:	CX_COM_OBJECT
Array:	not yet supported by ClassiX^®