OLE Explanation

Database Search

If you can't find the information using the categories below, post a question over in our WinBatch Tech Support Forum.

TechHome

OLE COM ADO CDO ADSI LDAP

	ADO DAO
	Collections
	Constants
	Crystal Reports
	DSOFILE
	Errors
	ImageMagick
	IMAPI
	LogParser
	Lotus Notes
	MDAC
	Netscape
	OLE and Outlook
	OLE TUTORIAL
	OLE with Access
	OLE with Acrobat Viewer
	OLE with Excel
	OLE with Google Earth
	OLE with MSIE
	OLE with PowerPoint
	OLE with Word
	OLE with XML
	OpenOffice
	PDF Conversion
	RegExp
	Samples from Users
	SAPI
	Shell
	SQLite
	Task Scheduler
	Textract
	UDFs
	WIA
	WIL Type Viewer
	WindowsInstaller
	WinHttpRequest
	Winsock
	WSH
	Zip

Can't find the information you are looking for here? Then leave a message over on our WinBatch Tech Support Forum.

OLE Explanation

Concept of OLE

OLE stands for "Object Linking and Embedding" and is a way for programmers to manipulate a given application by using its objects, properties and methods exposed by OLE in their own programs. It's a great way for Winbatch coders to control an application, much safer than using Sendkeys or SendMenus. Not all applications offer OLE access, so you need to check a particular application's documentation for information. Most Microsoft applications offer OLE access (usually through Visual Basic or VBScript) but other languages such as Winbatch, can also make use of this feature.

Make sure you read the OLE /COM section of the Winbatch Interface Language help file to familiarize yourself with OLE via Winbatch.

ObjectGet and Friends

If you refer to your Winbatch help file, you'll find the main functions for working with OLE through Winbatch are the ObjectGet, ObjectCreate.

ObjectCreate vs. ObjectGet: What's the Difference?

Besides minor differences in the syntax, the ObjectCreate and ObjectGet functions are used in different contexts. The differences can be summarized as follows:

ObjectCreate is used to create an interface to a new instance of an application. Use ObjectCreate when it's not certain whether the application to integrate is running. For example: Set xl = ObjectCreate ("Excel.Application") starts Microsoft Excel. The object returned in xl is a reference to the Excel.Application object just created.
ObjectGet is used with an application that's already running, or to start an application with a file already loaded. For example: Set xlBook = ObjectGet ("C:\TEST.XLS") would start Microsoft Excel with the file Test.xls already loaded. The object returned would be a reference to the Workbook object representing the just opened Test.xls file.

There is another Winbatch OLE function, namely ForEach. It is useful for opening certain types of sub-objects called Collections. For example, a Microsoft Access database is a collection of Tables, Queries, Forms, Reports and Modules. In Excel, a workbook is a collection of worksheets and so on. You'll receive more information on this later in the example code.

Helpful Resources

WWWBatch.ini File -- another big help for programmers is this file, usually located in the your PC's windows directory. If you can't find it, open Explorer and do a Search for it. Then place a shortcut to it on your Desktop. Also make sure you can open it with Notepad or WinStudio. This file stores OLE error messages and their text. Many times when your code errors-out, you'll look here to get a "english answer" to your dilemma, which is very handy. If you don't empty the file periodically, "old" error message information can build up, so once you understand the error, empty the file. You can always re-run your code and check it again.

IntControl 77 -- options 60 & 62 show the number of OLE objects open, and the number of OLE object slots available, respectively. These are helpful to know if you get the following error, 3157 OleInitiate: Too many open channels. If you receive this error then you'll need to go back and use ObjectClose to close object references you are no longer using and free up slots.

Reference -- you'll see the terms "Object Reference" or "Reference" in this work. They can almost be used interchangeably. An "Object Reference" refers to an object, while a reference may refer to an object and it properties, such as:

MyObject = MyWorksheet.name (refers to the name property of the worksheet)

You'll have to set up references to access lower-level objects and their properties. It also means a "variable name."

Re-Using Objects -- Winbatch tries to replace object references when you reassign them without closing them first. It's best to simply close on an object by setting it equal to zero before reusing it.

;Closes an object
objectname = 0

use...

MyObject = MyWorksheet.cell("A2")	;  set up the reference
MyObject=0					; <-- close the original
MyObject = MyWorksheet.cell("A26")	;  set up a new reference

rather than...

MyObject = MyWorksheet.cell("A2")
MyObject = MyWorksheet.cell("A26")

thinking that it'll eliminate the first with the second assignment.

What Do Objects Look Like? -- when you create an object, you can "look" at it via the Message function.

MyObject = MyWorksheet.cell("A2")
Message("Debug", MyObject)

You'll notice it takes the form of something like 33334. If you're working in Excel, and inspect the application object, it should look like 33333. Any objects opened after it, should be larger like 33334, or 33335. Obviously these aren't very intuitive, so the reference (variable name) you give it makes it easier for you the programmer to deal with.

Occasionally, you'll inspect object values and find that they equal zero. If you get no error, this means the object doesn't exist (called a NULL object), which means you can't work with it any further. I'll try and provide an example of testing the object's value, to make sure it doesn't equal zero, before continuing in your Winbatch script.

The zero value is different than not being able to create the object, as in: 1129 Ole Initiate Failed. The error message means the object or property doesn't exist in the application and can't be created.

Finding Documentation

VBA editor -- if you're PC has Microsoft Office installed on it, the first thing you should do if you're not familiar with VB is try the Visual Basic for Applications editor. Without getting into specifics, VB, VBA and VBScript are almost interchangeable, but do have differences. As you learn more and more from VB, VBA and VBScript example code, you'll notice they can't all do the same thing or do things the same way. Likewise, just about anything done in VB can be done in Winbatch. This isn't always the case and the Advanced Information Section will give more details.

In almost all of the Microsoft Office applications, you access the VBA editor by hitting ALT-F11. In MS Access it's slightly different, you have to have an open a Module (VBA module) and that puts you in the VBA editor. You'll also find them in Outlook 2000 and even some non-Microsoft applications, like Visio and others.

The VBA editor is helpful mainly for the VBA Help (F1) and the Object Browser (F2), and for examining macros you record. Exiting the VBA editor is done by menus or ALT-Q.

Recording Macros -- almost anything you do by hand in an application can be recorded into a VBA macro by the application you're working with. Look on the TOOLS menu of the application (not the VBA editor), look for MACROS and RECORD A NEW MACRO. This will enable the application to "record" your steps, building a VBA script of commands. Once you're done turn off the recording, then go back and EDIT it. You'll see the steps you performed as a list of commands, which you then can translate into Winbatch. The Advanced Information section has more information.

WWW.Microsoft.Com -- during your programming session, you may need to find additional information, or see an example of code concerning what you're doing. Use the Microsoft web site and get to know it. You can enter commands or the error text you get from the wwwbatch.ini file into the site's Search box and get more information on them.

The Registry -- another valuable source is the Windows Registry. Here you can find the types of objects installed on the PC as well as the versions, which is critical in OLE coding. As mentioned above about Recording Macros, you have to translate VBA code into Winbatch, and there are differences, some subtle, some not. If an example VB code doesn't give you the answers, you may need to search the registry. For example, a VB code may use New Access Application. Winbatch can't use the VB convention, so you'll have to find that New Access Application means ObjectOpen("Access.Application.8").

Using Object Browsers

Once you're in the VBA editor mentioned above, you can get a list of what objects, properties and methods are available for what application you're working with using the Object Browser, brought up by the F2 key.

After the Object Browser is opened, you'll notice an edit box in the top called . If you're using Excel, you should see an entry for Excel (the same with Access, Word, or whatever application you've got open). Click on the one you want and you'll notice the CLASSES pane below fills up. These are CLASSES within the main object. Click on a class an you'll see the MEMBERS pane fill up on the right. These are all the MEMBERS of that class. These may be methods or properties which allow you to perform actions (like saving a file) and set options (like font size or color) depending on what you selected. When you click on the right hand side of the pane, the status bar at the bottom will display the information for what you've highlighted. This is handy because it not only gives you detail, but is selectable and can be copied to the clipboard, great when its something long and complex.

You can also see other OLE object references installed on the PC. Frequently your scripts will "cross-boundaries" and you'll want to take data from one application (like MS Access) and move it into another (like MS Excel). VBA allows this and lets you look at additional objects besides the current one, as long as you specify which ones you need. Remain inside the VBA editor, go up to TOOLS menu and click REFERENCES. This will provide you with a list of Libraries (or references) to choose from. In most cases their naming convention is straight forward, but some are more cryptic (MS Internet Explorer is Microsoft Internet Controls). Others have more than one entry and a version number after them. In most cases select the highest (latest) version of what you need. If you can't find something you may need to check that application's documentation or make some queries on the Winbatch BBS. If you're working on an application that uses other OLE apps, you may find the need to save this, so that you're not constantly having to go into References and check the Libraries you need. I use Excel and simply save the VBA project and workbook, so that I can re-use them to look up object references in the future.

Finding Other OLE Information -- Some applications like Adobe Acrobat Reader, Crystal Reports don't have a VBA editor built-in. While you can still use the VBA Object Browser in your favorite Microsoft app to view their Library, you'll often find you need to see examples with more detail? What do you do when you've followed the above suggestions and still can't find anything? Often times a vendor will supply a Software Development Kit (SDK) for their application. These provide wealth of information and examples. In most cases you can get one by logging onto their website and downloading it, or purchasing it.

The WWW -- finally, using the www.google.com search engine may also help you find information, such as web site URLs, and other BBS and web forums that discuss the application you're working with.

Parentheses -- Winbatch requires the use of () around its function parameters, even if VB doesn't. Get used to using it.

Functions/Methods in OLE usually take parameters or data supplied by the program to make things happen.

Positional Parameters -- Winbatch programmers should already be familiar with these: data in a certain position within the function. For instance the Winbatch function, looks like this in the help file: ItemExtract (index, list, delimiter). The index is the first position, the list the second and the delimiter is the third. If you omit one you'll get an error. You'll see several OLE methods and functions that use this format. In some cases you don't need to supply a value but still need to preserve the position of it, such as: MyFile.SaveAs(filename, , @false). The second parameter's value was omitted but it's position was preserved and the application will know what to do.

Named Parameters -- If we look at the insert function for Excel in the Object Browser, we'll see:

Function Insert([Shift], [CopyOrigin]) Member of Excel.Range

The parameters are in brackets, which means they are optional. In this instance it means you could just use Insert() or any combination of the parameters specified. This is handy when you're only interested in one option and can let the application handle any others by default.

This is common in MS Excel. The function reads what you've input and assigns the values. This is where VB and Winbatch differ slightly. For example, in MS Excel, you may be required to supply a value for how Excel is to handle the other rows when you insert a row of data.

MyRange.Insert Shift:=xlDown			; VBA sample
MyRange.Insert(::Shift=xlDown)		; Winbatch sample

First, notice the parentheses (as mentioned earlier). Next the double-colon (::) This informs Winbatch to treat the information after the double-colon as Named Parameters and pass them to Ole. Also notice the := assignment token has been changed to just the = sign. Had the function required both positional and named parameters it would look like: MyRange.Insert(postional :: named)

Constants -- another thing you'll notice, especially in MS Excel are Constants. Just like Winbatch which has @True and @False the application you're dealing with has its own constants. In Excel, you may see something like xlCenter (which has a value of -4108). Naturally when coding it's much more intuitive to use @True instead of 1, same with xlCenter. However, even though you are accessing the Excel application through OLE, you're still working in Winbatch, which doesn't have the foggiest idea of what xlCenter is. In order to use the constants specified by the application's object browser, you'll need to define them, so before you use xlCenter in your script, you need to code: xlCenter = -4108. Only define the ones you're going to use.

The naming conventions used are arbitrary (you can use just about anything you want) but try to make them descriptive. This is important when debugging. When you go to do an operation with MyCell and you get an error, you may have to backtrack and see that you're using the correct reference. The nice thing is that once you have an object reference you can keep it open and use it in other places, so that once you create the reference to MyWorksheet, you can now re-use it to set references to other cells.

In some cases VB code will be much shorter. When you code in VBA (using Excel or Access) the VBA environment sets up all the Constants for you, and knows that xlCenter = -4108. It also does this for objects, so that you'll see:

Workbooks("MyWorkbook").Worksheets("Sheet One").Cell("A2")

instead of

Application.Workbooks("MyWorkbook").Worksheets("Sheet One").Cell("A2")

Again, due to the fact that when you open Excel and use the VBA editor it already knows you're working with the application object. When you use an external programming language, like Winbatch, you have to make specific references. Another example of this is in MSIE, where you can see JScript references like:

this.backgroundColor = 'Blue'

which is not possible in Winbatch. Same with the "me" object: me.font.color = "Black". Since Winbatch is external to MSIE or Excel, it cannot use the program defaults.

Article ID:   W16558

File Created: 2005:02:18:12:21:26

Last Updated: 2005:02:18:12:21:26