OLE automation

We use an OLE object by assigning it to a module in Full BASIC.
An OCX such as ActiveX can be used if the following conditions are sufficed.
Nondisplay (it needs no parent window)
It supports dispatch interface

Assigning an OLE object to a module

The module name can be arbitrary.
There are two ways how to assign an OLE object to a module.
Ordinarily, an OLE CREATEOBJECT statement that has the ProgID or the string expression of ClassID quoted by bouble quotation marks as the argument is written in the module body. The OLE object shall be created on compiling.
Example. Assignment with the ProgID
OLE CreateObject "Word.BASIC"
Example. Assignment with ClassID
OLE CreateObject "{000209FE-0000-0000-C000-000000000046}"

Another way is used when we assign an object that is a property of an OLE object, to be described below.

Assignment of an OLE method to an external procedure.

We assign an OLE method to an external procedure of the module.
We assign a method that has a result value to an external function to write an OLE METHOD statement between the EXTERNAL FUNCTION line and the END FUNCTION line. When the result type is numeric or boolean, the function shall be defined as a numeric function, and when the result type is string, defined as string.
We assign a method with no result value to an external subprogram to write an OLE METHOD statement between the EXTERNAL SUB line and the END SUB line.
In an OLE METHOD statement, the method name is written quoted by double quotation marks.
The number of the arguments and the types of them should agree with those of the method.
The method name shall be checked on compiling. The number of the arguments and the types of them shall be checked on executing.

Example.
When MS-Word is installed, the following can be run.
The module Word mounts an OLE object Word.BASIC. The Prog ID "Word.BASIC" is registered in the registry of Window.
We write a PUBLIC statement as in 170 line ot use external functions outside the module.
We write a DECLARE EXTERNAL statement as in 100 line to use external functions defined within a module. External procedures that are written in the DECLARE EXTERNAL line can be written with or without the module name. ( When we write with the module name, 110 line is as CALL Word.FileNew("") ）

100 DECLARE EXTERNAL SUB Word.Filenew, Word.Insert, Word.FileSaveAs
110 CALL FileNew("")
120 CALL Insert("This string shall be inserted to the document")
130 CALL FileSaveAs("A:\TEST01.DOC")
140 END
150
160 MODULE Word
170 PUBLIC SUB FileNew, Insert, FileSaveAS
180 OLE CREATEOBJECT "Word.Basic"
190 EXTERNAL SUB FileNew(s$)
200 OLE METHOD "FileNew"
210 END SUB
220 EXTERNAL SUB Insert(s$)
230 OLE METHOD "Insert"
240 END SUB
250 EXTERNAL SUB FileSaveAs(s$)
260 OLE METHOD "FileSaveAs"
270 END SUB
280 END MODULE

Assignment of an OLE property to an external procedure

We assign a property assignment to an external subprogram.
We write an OLE propertyPUT statement between the EXTERANL SUB line and the END SUB line. We write the property name quoted as its argument. The argument of the subprogram shall be value that should be put.
When the property is an array type, we write indices and the value to be set last as the arguments.

We assign readout of a property to an external function.
We write an OLE propertyGET statement with the property name quoted between the EXTERNAL FUNCTION line and the END FUNCTION Line.
When the property is an array type, the indices become the parameters of the function.

Available data types

Available data types are only numeric an string. Complex type or array type are not available.
The truth values are available when they are assigned as numeric values. In OLE, 'true' is -1, and 'false' is 0.

Assignment of an object that is an OLE property to a module

When we write an OLE ASSIGN statement instead of an OLE CREATEOBJECT statement, it assigns an object to the module through the numeric value that refers to the object. That value shall be gotten by reading from a property of the parent object. These shall be done on executing.
When we read a property of which value is an object, it shall be the number that refers to the object. This value must be assigned with just one execution of a OLE ASSIGN statement. That is, this value must not be never assigned nor assigned to more than one OLE ASSIGN statements.
An OLE ASSIGN statement is an imperative statement, unlike an OLE CREATEOBJECT statement. In a module to which an object is assigned by an OLE ASSIGN statement, check on the method or property name is postponed until the first execution of the procedure to which it is assigned.

Example
This example can be executed when Word 2002 is installed (untested about other versions of Word).
100 DECLARE EXTERNAL FUNCTION Word.Documents
110 DECLARE EXTERNAL FUNCTION Word.Caption$
120 DECLARE EXTERNAL SUB Word.SetVisiBle
130 DECLARE EXTERNAL SUB Documents.SetDocuments, Documents.Open
140 DECLARE EXTERNAL SUB Selection.SetSelection, Selection.EndKey
150 CALL SetDocuments(Word.Documents)
160 CALL Open("C:\BASICw32\README.TXT")
170 CALL SetSelection(Word.Selection)
180 CALL SetVisible(-1)
190 WAIT DELAY 10
200 PRINT Caption$
210 CALL EndKey
220 END
230
240 MODULE Word
250 OLE CREATEOBJECT "Word.Application"
260 PUBLIC FUNCTION Selection,Caption$,Documents
270 PUBLIC SUB SetVisible
280 EXTERNAL FUNCTION Selection
290 OLE propertyGET "Selection"
300 END FUNCTION
310 EXTERNAL FUNCTION Caption$
320 OLE propertyGet "Caption"
330 END FUNCTION
340 EXTERNAL SUB SetVisible(n)
350 OLE propertyPut "Visible"
360 END SUB
370 EXTERNAL FUNCTION Documents
380 OLE propertyGet "Documents"
390 END FUNCTION
400 END MODULE
410
420 MODULE Documents
430 PUBLIC SUB Open, setDocuments
440 EXTERNAL SUB setDocuments(n)
450 OLE ASSIGN n
460 END SUB
470 EXTERNAL SUB OPEN(s$)
480 OLE METHOD "Open"
490 END SUB
500 END MODULE
510
520 MODULE Selection
530 PUBLIC SUB SetSelection, EndKey
540 EXTERNAL SUB SetSelection(n)
550 OLE ASSIGN n
560 END SUB
570 EXTERNAL SUB EndKey
580 OLE METHOD "EndKey"
590 END SUB
600 END MODULE

（Note）
When a method is assigned to an external function, even if the method might alter the variable that is written as an argument, the result does not reflect the variable of BASIC (the value shall not change).
As BASIC erases the object immediately after the execution of the program, the execution of the program must not terminate until the OCX terminates if that OCX runs asynchronously.

Event Handling

When we do event handling, we write a comma and a ProgID or string representation of a ClassID quoted by double quotation marks following the argument in an OLE CREATEOBJECT statement.
Examples. We write as either of the following.
OLE CREATEOBJECT "xxxxx.xxxx","{1234567A-1234-1234-89AB-0123456789AB}"
OLE CREATEOBJECT "{12345678-1234-1234-89AB-0123456789AB}","{1234567A-1234-1234-89AB-0123456789AB}"

And then we write an external subprogram that shall be called for the event handling by the OCX, and write a comma, DispID and the number that indicates the DispId of that event at the tail of the EXTERNAL SUB line.
EXAMPLE EXTERNAL SUB OnEvnet(s$),DispID 2

<Notice> Decimal BASIC does not allow a procedure to be called by multiple threads asynchronously. When an OCX invokes the event handling asynchronously, BASIC proper thread must be substantively halt executing a WAIT statement or a PAUSE statement.

<Notice> STOP statement that is executed in a procedure called by an OCX does not terminate the execution of the BASIC program, but interrupt the execution of the program and notify the OCX to raise an exception. The behavior afterward depends on the OCX. This is similar in the case when Cancel is selected on the Debug Windows.

Signals

An event handling procedure that is asynchronously invoked can use a signal to notify the completion of the handling.
A signal is identified by a name that begins an alphabet. A signal name need not be quoted.

SIGNAL signal_name
Issues a signal identified by signal_name.
WAIT SIGNAL signal_name
Waits for the signal indentified by signal_name.
WAIT SIGNAL signal_name TIMEOUT numeric_exp
Waits until the signal is issued or the time ellapses for numeric_exp (in seconds).
Available values are between 0.01 and 429496729.5
If a WAIT SIGNAL has TIMEOUT, pressing Ctrl-B does not break while standing by.