Sfairadora

  • Reference Guide

OLE Functions

OLE Automation (or just Automation) is a mechanism built in Windows operating system, which enables to connect different applications. From the technical perspective, it employs the COM model (Component Object Model), which allows one application to use object of another through the IDispatch interface.
The basic element of the OLE mechanism is called an object (an OLE object), for which certain properties and methods are defined. In the Enki language, the type OLE_object is defined, which serves to represent a reference to an OLE object. An OLE object is created either by reading from a file – the function OLE_object_open_file serves this purpose, or by creating a new object with the OLE_object_create function based on a specified name or class identifier. The names and class identifiers and their correspondence with appropriate file types are stored in Windows registry during the installation of an application. Therefore, the names of available object classes, their properties and methods depend on the programs that are installed.
The value of an OLE object property is accessed simply by writing the name of the property next to the name of the object variable separated by a dot:
var String name = ole_obj.Name;
To change the value an OLE object property, any standard assignment operator can be used:
ole_obj.Size += 5;
Calling a method is accomplished by writing the name of the method, just like in the case of properties, followed by the parameters enclosed in parentheses:
var OLE_object winf = ole_obj.GetFolder("C:\Windows");
Note: It should be noted, that Enki does not analyze the types of the parameters expected by a method. Taking into account that a parameter can be passed by reference, too, it is preferable, in order to increase performance, to typecast explicitly the actual parameters specified by an l-value (i.e. a variable or data item reference) to the appropriate type. If not done so, the parameter would be passed by reference, which is much less efficient. Thus, it is preferred to write:
var OLE_object winf = ole_obj.GetFolder([String]folder);
instead of
var OLE_object winf = ole_obj.GetFolder(folder);
The list of all currently existing object (typically documents open in other applications) can be obtained by the OLE_running_object_table function.
Some of OLE objects represent a collection. That means they contain a list of values or other OLE objects. In Enki, collections can be enumerated in a natural way by the for statement, analogically to sequences.
Note: As a variable of the type OLE_object does not contain the object itself, but just a reference to it, and inasmuch there is no mechanism to store a reference to an OLE object to a file, it is not possible to store the state of a computation manipulating with OLE object being in progress. Therefore, on contrary to other cases, when Sfairadora is terminated while a computation manipulating with OLE objects is running, the references to the OLE object are not stored, so, after Sfairadora is re-run and the computation is restored, an attempt at accessing a (not-restored) OLE object will result in an “object lost” error.

Example 1

Listing files in a specific disk folder and storing it to a table together with the file sizes can be accomplished by the following program:
var OLE_object fso = OLE_object_create("Scripting.FileSystemObject");
document.data.table = INIT; // clearing the previous content of the table
for(x = fso.GetFolder(document.data.dir).Files)
(
document.data.table <- insert({x.Name, x.Size})
)
The example assumes a table (named table) with two columns (one of the type String, the other of the type integer (Int)) defined in the document section Data. Further, item dir of the type String is assumed to be defined in the section Data, which contains the path to the folder to be listed.
The object Scripting.FileSystemObject used in the example is a standard Windows component. The documentation to it can be found at the web pages msdn.microsoft.com.

Example 2

The value of a cell from an Excel sheet can be read like follows:
var OLE_object workbook = OLE_object_open_file("C:\wb.xls");
var OLE_object sheet = workbook.Sheets("Sheet1");
var OLE_object range = sheet.Range("A1");
var Union value = range.Value();
The example opens the file “wb.xls” and reads the value of the cell “A1” from the sheet “Sheet1”. The value is stored to a variable of the type Union, so that the original type of the data stored in the cell is preserved. The actual type of the value can be Real, String, or None, if the cell is empty. For the example to work, it is necessary that the application Excel from Microsoft Office be installed.

Overview