OLE Server Frequently Asked Questions
Compiled and Written By Richard D. Clark
Contributions by Joel Shafer and Robert Barraza
Last Updated 09/17/1996

This FAQ covers some topics of OLE servers that have caused confusion for new programmers trying to create and use OLE servers and OLE automation. This document is an attempt to clarify some information and to create a single repository of information for this new area of programming. This is by no means an exhaustive compilation, but rather a quick answer to some common questions and pointers to other more detailed information.

1. What is an OLE server and OLE Automation?
2. What is meant by in process and out of process OLE servers?
3. What does the Public property on a class module do?
4. What does the Instancing property on a class module do?
5. What is Remote Automation?
6. What is a pool manager and why would I need one?
7. Does VB OLE support callbacks?
8. How could I create an asynchronous client/server system?
9. What data types can be passed to a remote OLE server?
10. Can I provide automatic failover to another server node, if the current server node fails?
11. Can a VB 3.0 program call a 4.0 OLE server?
12. What is the OLE server search order for 32 and 16 bit OLE servers?
13. How do I create a TLB file for my public OLE server.
14. How do I add help strings to my OLE server methods and properties like I see in the Object Browser for other references?
15. How can I tell if my application was launched as a stand alone program or as an OLE server?
16. How do I hide the Automation manager?
17. How do I pass a user defined type to an OLE server?
18. Why is the terminate event not fired in my OLE server, when I end my application?
19. How do I pass parameters to the Initialize event of a class?
20. Can I call a 16 bit OLE server?
21. How do I set up a remote automation server and client?
22. Should I set properties on a remote OLE server or pass parameters?
23. What is the difference in using ByRef and ByVal calls to a remote OLE server?

1. What is an OLE server?

OLE Automation is the means by which a client accesses the properties and methods of a server. Automation can be both local and remote, depending on the needs of the client application. In the Visual Basic (VB) programming environment, OLE automation is built into the language. Object variables are the foundation by which you can access the OLE server interface. In VB, by instantiating (using the SET statement) an object that references an OLE server, you have access to the published properties and methods of the server. You have created an object in your client application that is directly, or indirectly (via a pool manager of some sort) connected to the OLE server application.

OLE servers and OLE automation are the foundation for the component philosophy of software development. By creating and utilizing OLE servers, a set of reusable components can be created that can be used in a wide variety of programs, including off-the-shelf products.

OLE is also the foundation (for VB as least) of the three-tier method of data access. The concept, greatly simplified, is the idea of encapsulating the business rules in a middle tier of a client/server system in order to facilitate maintaining working applications in a changing environment.

Tier one holds the client side application, tier three holds the database and tier two could be a set of OLE automation servers that broker requests from the client applications to the database. If the business rules change, then theoretically, only the middle tier needs to change. The client doesn’t know or care about the changes and neither does the database. If the database changes, the middle tire may need to change, but no change would be required in the client applications. The client will simply instantiate the server in its application and if the published interface has not changed, no change is necessary in the client.

2. What is meant by in process and out of process OLE servers?

A client application currently cannot access an in process remote automation server (although with Network OLE, we may be able to do this). A client will need to access a remote out of process server which would in turn than access the in process server.

3. What does the Public property on a class module do?

Setting the Public property to FALSE will create a private OLE server that will only be visible within the current project. You would use this setting to modularize a projects with classes, but not need to create a public OLE server.

4. What does the Instancing property on a class module do?

0: Not creatable. This setting is for a private class module.

1: Creatable single use. This setting is for a public OLE server and is used if you want to have an instance of the server running for each application that is accessing the server. That is, if two client application instantiate the OLE server, two copies of the OLE server will be created.

2: Creatable Multiuse. This setting for a public OLE server is used when you want only one instance of the server to be created. The first request to the server will load the server into memory, and subsequent requests will return pointers to the loaded server.

Note on server types: Only one application can use a server at any time. Therefore if two requests are made to a multiuse server, one request will be blocked until the first request has finished processing. If many applications are requesting the services of the server, blocking can become a problem.

On the other hand, by loading multiple instances of the same server, when using single use, resources can be quickly exhausted. See the question 6 (pool manager) in the FAQ for more information.

5. What is Remote Automation?

The client will load the Automation Proxy and the server needs to run the Automation Manager. The client finds the particular server, local or remote by looking at the information that is stored in the registration database. When the server is registered on the client, its location is registered so the client will know where to connect to the server. It is also possible to change the server information in the database with the Client Registration utility (see Client Registration Utility topic in the VB help file) and the Connection Registry utility (see Remote Automation Connection Registry APIs (ReadMe) topic in the VB help file); but there must only be one registry entry. Multiple server entries are not allowed.

You can also catalog all the servers using the included Component Manager.

The Setup Wizard will include the necessary files for both the server and the client and register all the necessary information in the registration databases. See Chapter 7, Implementing OLE Servers in the Building Client/Server Applications with Visual Basic manual.

6. What is a pool manager and why would I need one?

The middle ground is to create a program to manage a collection of previously loaded single use servers and then parcel them out as needed by clients. If the demand is greater than the supply, the pool manager turns down the request. The pool manager is a program you have to create. There is no built in pool manager provided in Visual Basic. Yet, because it is a created program, a great deal of customization can be included into the program. For example, file logging can be done, security can be implemented and resources can be carefully monitored. See question 8 for an asynchronous server discussion.

The enterprise edition of Visual basic includes a pool manager sample program. Look under samples\remauto\poolmngr.

7. Does VB OLE support callbacks?

Remote callbacks can only be done with 32 bit operating system clients. See article Q143259 in the MS Knowledge Base. In a callback situation, the client is acting as the server and the server is acting as the client. In this case, the Automation Manager will need to be installed on the client to broker this request. Since this will only operate under 32 bits, i.e., Windows 95 or Windows NT, you cannot have a 16 bit OS client, therefore the client application should be compiled as a 32 bit application.

8. How could I create an asynchronous client/server system?

9. What data types can be passed to a remote OLE server?

For example, a VB screen is updating a table in a database and passes all the values to the OLE client as strings. The database changes from SQL server to Oracle and the data types of the tables change. This change does not impact the client at all since it is passing the data as strings. The OLE interface doesn’t need to change since it uses a variant data type. The only change to the system then, is the conversion and validation routines in the server to accommodate the new data types. In fact, if the conversion routines are in a separate OLE server, then the overall system doesn’t change at all, only the one OLE server that handles the conversions.

You cannot pass User Defined Types to an OLE server. See question 17 for suggested workarounds.

10. Can I provide automatic failure switching to a different server, if the current server fails?

11. Can a VB 3.0 program call a 4.0 OLE server?

Yes. You must use the CreateObject verb. For example:

Dim obj as Object
Set obj = CreateObject(MyServer.MyClass)

12. What is the OLE server search order for 32 and 16 bit OLE servers?

Search Order for 32 bit Client

1. 32 bit in process server.
2. 32 bit out of process server.
3. 16 bit out of process server.

Search Order for 16 bit Client

1. 32 bit out of process server (on a 32 bit OS).
2. 16 bit out of process server.

13. How do I create a TLB file for my public OLE server?

When you create your OLE server and compile the server into a DLL or EXE, select 'Options' on the file dialog, then make sure the check box labeled 'Remote Server Support Files' is checked. This will create a *.VBR file and a *.TLB file.

14. How do I add help strings to my OLE server methods and properties like I see in the Object Browser for other references?

With the OLE server class module loaded in the VB IDE, select View.Object Browser (F2). This will display the Object Browser Dialog. Select your project name (i.e. Project1) from the Libraries/Projects drop down. The left hand list will show the classes and modules in your project. Click on your OLE server class module. All the methods and properties defined for your class will displayed in the right hand list. Click on a method or property and click the Options button. Enter the description in the Description text box and then click OK. In the Object Browser dialog, the description now appears under the method/property definition along the bottom of the dialog. These strings are saved in the class module file.

15. How can I tell if my application was launched as a stand alone program or as an OLE server?

Use the App.StartMode function. If the function returns vbSModeStandalone, then the application was started as a standalone application, otherwise it was started as an OLE server application.

Example:

If App.StartMode = vbSModeStandalone Then
  Msgbox "Application is running stand alone."
Else
  Msgbox "Application is running as an OLE server."
End If

16. How do I hide the Automation manager?

Once it is hidden you will need to use a system utility like Pview to terminate the program.

17. How do I pass a user defined type (udt) to an OLE server?

You cannot directly pass a udt to an OLE server, so you have indirectly pass the information.

There are two ways to do this: First, pass each element of the UDT as separate elements. Second, you can create an udt class, i.e. a class module that contains properties that replicate the elements of your udt and then use property procedure to reference the individual elements. You could also replicate a udt array by using a class collection, with each object in the collection your class udt.

18. Why is the terminate event not fired in my OLE server, when I end my application?

If you use the END statement in your program, the terminate events of objects will not be fired (except under NT). In order to have the terminate event fire, you need to set the object reference to Nothing.

Set obj = Nothing. This will cause the terminate event to fire.

19. How do I pass parameters to the Initialize event of a class?

You cannot pass parameters to the initialize event, so you have to write your own 'Create' method. You can then call the Create method passing any parameters you need to object. You should add a private Boolean flag so that you can be sure that the Create method has been properly called when the other class methods are referenced.

20. Can I call a 16 bit OLE server?

21. How do I set up a remote automation server and client?

I will be using the two sample programs helo_svr (server) and helo_cli (client) located in samples\remauto\hello of the VB subdirectory. The process described here will be a manual set up for illustrative purposes. The Setup Wizard automates this process when you create distribution disks.

1. Load the OLE server, helo_svr project and select File-Make EXE to compile the program. On the File-Save dialog, click the Option button and make sure the “Remote Server Support Files” check box is checked. This will be needed by the client. Compile the program.
2. Install the program on the server machine along with the Remote Automation Manager. If you are using the Setup Wizard, be sure the 'Install Remote OLE Automation...' check box is checked so that the needed files are included. If you are running the server on the development machine, then setup is not necessary for this demonstration.
3. On the server machine, run the RemAuto Connection Manager. In the left pane select the entry HelloProj.HelloClass. Select the Server Connection tab and enter the appropriate information in the Network Address, Network Protocol and Authentication Level fields. The settings I used were:

   Network Address: \\rclar9 (machine name).

   Network Protocol: Named Pipes.

   Authentication Level: Default.

   Click the Client Access tab and select 'Allow All Remote Creates'. In an actual deployment, this will need to be whatever is required by the business.

   On the Server Connection tab, click the Apply button to set up the server. Run the OLE server and the Automation Manager on the server machine. The OLE server is now ready.

4. Compile the client project, helo_cli.
5. Install the client on the client machine. If you are using the Setup Wizard, on step 4 click the 'Add OLE servers' button and then select the helo_svr.vbr file you created when you compiled the server. An additional dialog will be displayed. Fill out the appropriate information that you entered when you set up the server, and continue.
6. Setup Wizard will register the client on the target machine (if you used Setup Wizard) but I will go over the process to illustrate the necessary steps. You will need the helo_svr.vbr and helo_svr.tlb files that were created when you compiled the server. On the client machine, run the CLIREG16 (16 bit) or CLIREG32 (32 bit), which ever is appropriate, passing the proper parameters. These programs are in \clisvr of the VB subdirectory.

   Page 137 of the 'Building Client/Server Applications with Visual Basic' lists the all the parameters of the registration utility. I found that I needed to pass both the TLB and VBR file in order for the client to work properly. Page 135 in the same manual, lists the network protocols and the representative clireg string. If you don’t specify the server or protocol, the clireg program will prompt you for the information.

7. Run the helo_cli program. On the server machine the Automation manager will indicate 1 connection to 1 object.

Note: I ran this process successfully on one machine, in addition to two separate machine. Obviously, remote means more than one machine, but the concepts still work even if you only have one machine available. You can verify that the system is indeed using the remote automation tools by closing the Automation Manager and running the client program. You should get a 'No more endpoints available...' error.

The difficulty with this process, I found, is the network protocols. You have to be sure that you specify the correct information or the client will not be able to find the server. Also, be sure that the OLE server is running, or you will get an 'OLE Automation server cannot create object' error.

22. Should I set properties on a remote OLE server or pass parameters?

23. What is the difference in using ByRef and ByVal calls to a remote OLE server?

Using ByVal though, the data is copied once to the server, as in a normal Function/Sub call. This reduces the cross-network calls, and improves performance.

Sources Used in this FAQ:

1. OLE Remote Automation: Synopsis and Analysis. The Cushing Group. Copyright 1995, The Cushing Group. http://www.cushing.com/.
2. Creating OLE Servers with Microsoft Visual Basic. Craig Lokken, Mary Anne Kobylka, Microsoft Corporation. Copyright 1995, Microsoft Corporation. http://www.microsoft.com/
3. Building Client/Server Applications with Visual Basic. Microsoft Corporation. Copyright 1995, Microsoft Corporation.
4. Professional Features, Creating OLE Servers. Microsoft Corporation. Copyright 1995, Microsoft Corporation.
5. Visual Basic Help File. Microsoft Corporation. Copyright 1991-1995, Microsoft Corporation.
6. Microsoft Knowledge Base. Microsoft Corporation. Copyright 1995, Microsoft Corporation.

Please contact Richard Clark (clarkr@flash.net) for additions or errors in this document. The document is provided as is, and is used at the risk of the reader.