[For WinBatch 2004A and older versions of WinBatch]
 

Object101, Ole 2.0, and Applications

The ability to control and assist the movement of data between applications is one of the key strengths of WIL.  In early versions of WIL, the Clipboard, dynamic data exchange (DDE), and SendKey functions were the only way to share data.

Now, with support for OLE Automation, you can do much more than share data. From within your WIL script, you can access and manipulate OLE objects that are supplied by other applications. With OLE Automation, you can use WIL to produce custom solutions that utilize data and features from applications that support OLE Automation.

What Is OLE Automation?

OLE Automation is an industry standard that applications use to expose their OLE objects to development tools, macro languages, and container applications that support OLE Automation. For example, a spreadsheet application may expose a worksheet, chart, cell, or range of cells -- all as different types of objects. A word processor might expose objects such as applications, paragraphs, sentences. bookmarks, or selections.

When an application supports OLE Automation, the objects it exposes can be accessed by WIL. You use WIL scripts to manipulate these objects by invoking methods (subroutines) on the objects, or by getting and setting the objects' properties (values).

Accessing OLE Objects

You can manipulate other applications' OLE objects directly by first opening the object with the ObjectOpenWILLZ.O__001 function.  The ObjectOpen function is used to open the object.  This function requires a single parameter -- a string that indicates the application name and the type of object you want to create. Use the following syntax to specify an object to create:

Application.ObjectType

For example, let's say there is a orgchart application named ORGCHART.EXE that supports a single object: an orgchart.   Furthermore, the OrgChart object supports two sub-objects:  a box and a line.  The object might be defined as:

OrgChart.Chart

Once you know the type of object you want to create, you use the ObjectOpen function to create the object.  Set the value returned by the ObjectOpen function to a variable. Here's an example:

MyChart = ObjectOpen("OrgChart.Chart")

Once you have the primary object in hand - in the MyChart variable in this case, you can create the sub-objects and assign then to their own variables.

TopBox = MyChart.NewBox
BottomBox = MyChart.NewBox
TheLine = MyChart.NewLine

When this code executes, the application providing the object is started (if it is not already running) and an object is created.  The object belongs to the application that created it.  This object can be referenced in WIL scripts using the variable you placed the return value of the ObjectOpen function into.  For example, after creating the object, you could write code such as this to open sub-objects, change the background color, set a default font, set a title, and save the object to a file:

MyChart.Color = "White"
MyChart.FontName = "Arial"
MyChart.FontSize = 12
MyChart.Title = "Tina’s Org Chart"
TopBox.Position(2,2)
TopBox.Text = "The Boss"
BottomBox.Position(2,8)
BottomBox.Text = "Tina"

TheLine.Begin(2,2)
TheLine.End(2,8)

MyChart.SaveAs("C:\ORGCHART\TINA.ORG")

When you are through with an object, use ObjectCloseWILLZ.O__002 to tell the WIL processor that you are done with the object.

ObjectClose(TheLine)
ObjectClose(TopBox)
ObjectClose(BottomBox)
ObjectClose(MyChart)

Note:  To get a list of objects that an application supports, you must consult that application's documentation.  It may also help to poke around in the Windows registration database. For example check out the HKEY_CLASSES_ROOT key. Be aware, though, that intentional, unintentional, or accidental changes to the registration database may completely destroy a Windows installation and require a complete re-installation of ALL your software to recover.

Note:  When creating an object, some applications require that the application providing the object is either active or on the system's path.

Accessing an Object's Properties

To assign a value to a property of an object, put the object variable and property name on the left side of an equation and the desired property setting on the right side. For example:

MyChart.Title = "Tina’s Org Chart"

You can also retrieve property values from an object:

TheTitle = MyChart.Title

Note: In the case of OLE methods or properties that return byte arrays (variant type = VT_UI1 | VT_ARRAY), it will copy the data to a newly-allocated binary buffer of the required size, with the binary EOD properly set, and the return value will be the binary buffer handle. The user is responsible for freeing this binary buffer.

Performing Object Methods

In addition to getting and setting properties, you can manipulate an object using the methods it supports. Some methods may return a value.  Methods that do not return a value, return 0.

MyChart.Position(2,2)
TheLine.End(2,8)
MyChart.SaveAs("C:\ORGCHART\TINA.ORG")
a= MyChart.Print( )
If a == @FALSE
     Message("Error", "Print of MyChart failed")
endif

Note: In the case of OLE methods or properties that return byte arrays (variant type = VT_UI1 | VT_ARRAY), it will copy the data to a newly-allocated binary buffer of the required size, with the binary EOD properly set, and the return value will be the binary buffer handle. The user is responsible for freeing this binary buffer.

Dealing with Sub-Objects

Some objects contain sub-objects.  For example, a box is a sub-object of an orgchart object.

Note: You cannot include multiple objects, properties. and methods on the same line of code.  Each object must have its own variable.  For example:

TopBox = MyChart.NewBox

Closing an Object

All OLE Automation objects support some method that closes the object and the application that created it. Since OLE objects can use a significant amount of memory, it is a good idea to explicitly close an object when you no longer need it. To close an object. use the appropriate method (most objects support the Close method or the Quit method). For example:

;Closes the object.
MyChart.Close
;Closes the application that created the object.
MyChart.Quit

When WIL processing for an object is complete, use the ObjectClose function to free WIL processor memory.

ObjectClose("MyChart")

Note:  The ObjectClose function will suggest to the application that owns the object, that its services are no longer required, and that, if it has nothing better to do, it might as well close up shop and exit.  For these applications, the "MyChart.Quit" as shown above is not required.

Omitted Optional Positional Parameters

OLE functions support 'omitted optional positional parameters', using commas as placeholders. 'Required parameters' are those that must always be specified. 'Optional parameters' are those that can be skipped using a comma as a placeholder (when using positional parameters), or simply omitted (when using named parameters).

For example:

Application.Display("Hello", 100, 100, , 1)

Named Parameters

OLE functions support 'named parameters'.  The syntax structure is:

Object.Method(p1, p2 :: n3 = v3, n4 = v4)

Positional Parameters

Positional parameters (shown above as p1 and p2), if any, come first, followed by a double colon ("::"), and then any named parameters (n3 and n4).  Each named parameter is followed by an equals sign ("=") and then the value for the parameter (v3 and v4). Whitespace is ignored.  Here are some examples:

; 2 positional parameters

Application.InputBox("My Prompt", "My Title")

; 2 positional parameters and 2 named parameters
Application.InputBox("My Prompt", "My Title" :: Left = 40, Top = 300)

; no positional parameters and 2 named parameters
;(note the leading colon)

Application.InputBox(:: Prompt = "My Prompt", Title = "My Title")

OLE Types

OLE functions allow you to specify a type for integer parameters. Normally, when you specify an integer value as a parameter to an OLE function, WIL passes it as a type VT_I4 (4-byte integer value).  If the OLE application was expecting the parameter to be a different type of numeric value, in most cases it will automatically convert it to the desired type.  However, there are some OLE applications which don't do this, and return an error instead. 

In such cases, You can first specify the type using the function ObjectTypeWILLZ.O__008.

OR

You can specify the type, using the following syntax:

Object.Method(p1, type:p2 :: name = value, type:name = value)

The parameter type (shown as 'type') is followed by a single colon (":"), and then the parameter itself.  This can be done for both positional parameters and named parameters. Whitespace is ignored, and the type names are not case-sensitive.

Integer types which may be specified:

Note: The default type for integer values is "I4" (VT_I4).

Other types which may be specified:

Note: There are some additional types that are supported, by using the BinaryOleType function. See the BinaryOleTypeWILAK.B__021 function for details.

Here are some examples:

; this function requires a parameter of type VT_I2
Application.CreateImageViewerObject(I2:1)

; this function requires a (named) parameter of type VT_DATE

Application.CreateLog("access.log" :: DATE:startdate="97:11:01")

OLE 2.0 Limitations in WIL

Some OLE objects support features that can't be accessed using WIL.  This section discusses known limitations.

OLE functions support up to 20 parameters.

OLE object names can be up to 30 characters long.

OLE method and property names can be 256 characters long.