OLE Server Frequently Asked Questions
I have added some new info to the FAQ. Please let me know if this is helpful information, or am I just wasting bandwidth and your time. Thanks.Author: Rick Clark
OLE Server Frequently Asked Questions
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.
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.An in-process OLE server is a Dynamic Link Library (DLL) that runs in the same process space as the client application. Out of process servers are EXE files that run in their own address space. In process servers are usually faster than out of process servers. In process servers are created by selecting the Make DLL function from the File menu in the VB IDE. Out of process servers are created using the Make Exe menu item. In process servers can only be created with the 32 bit version of Visual Basic. Furthermore, you cannot access a 32 bit in process server from a 16 bit VB program (see VB help file topic: OLE Controls Interoperability for 16- and 32 bit Platforms).
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.Setting a class module’s Public property to TRUE, enables the class properties and methods to be visible to any program. You would set this property to TRUE if your server will need to be visible to other applications; as in the three-tier example.
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.This class module property has three settings:
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.Remote automation is simply an OLE server that does not reside on the client application’s computer. It is located on another machine accessible via a network. As far as building the server, there is nothing special that needs to be done. A local OLE server can also function as a remote OLE server. No code changes are necessary. (Of course, since the server machine needs to have the Automation Manager running, and this will only run under Windows 95 or Windows NT, then the OLE server should be compiled as a 32 bit application). As far as the client application is concerned, it does not know or care that the OLE server is being accessed remotely.
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.
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.Pool managers are used to manage a collection of single-use OLE servers. As previously stated, multiuse OLE servers are loaded once into memory and then shared among many applications. When the work load increases, the blocking of clients can progressively become a problem. On the other hand, creating an unlimited amount of single user OLE servers can exhaust system resources. It also takes time to load the servers into memory, so there is some startup performance penalties.
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.Yes. There is an example of this in the VB samples subdirectory: samples\remauto\callback. To set up a callback system, not only does the client have to create a server object, but the server must create a client object to provide a channel for the callbacks. Simply provide in the server, a method that creates a client object so that the exposed methods of the client are available to the server. Whenever the server needs to notify the client, the server uses the client’s exposed methods to return information back to the client. This can be a straight code method, or as in the case of the above example, a control on the client system.
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.This could be easily done via the Pool Manager concept (see question 6). Add to your pool manager a queuing scheme that could receive a request from a client, add the request to its work queue, notify the client of the queued item and let the client disconnect. The pool manager than would run the request at a predetermined time, for example, or when resources permit . The data types accepted via the Remote Automation’s marshaling support are byte, boolean, integer, long, single (real), double, currency, date, object, string, variant and arrays of the mentioned types. However, using variants as the OLE data types will keep your public interface stable and not impact your client applications, if they were written correctly.
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.No, since a server has to be registered on the client. There is no automatic switching to another server if a node happens to fail. However, since you can dynamically change a server location using the Remote Automation Connection Registration Utility, you could possibly create a monitor that could switch a server if necessary. The validity of this idea depends on the various factors of the system and the type of network that is installed. MS Knowledge Base Q138139
Yes. You must use the CreateObject verb. For example:
Dim obj as Object Set obj = CreateObject(MyServer.MyClass)You cannot call an in process server (see question 2). You cannot return an array data type to VB 3.0 nor can you use the rich error information (see VB 4.0 Err.Raise), since these are not supported in VB 3.0. MS Knowledge Base Q138064
Search Order for 32 bit Client
Search Order for 16 bit Client
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?MS Knowledge Base Q149047
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.MS Knowledge Base Q129739
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.
If App.StartMode = vbSModeStandalone Then Msgbox "Application is running stand alone." Else Msgbox "Application is running as an OLE server." End IfThis information can be found in article Q138067 in the MS Knowledge Base. You will have to modify the registration database in order to specify a 'Hidden' run mode so that the manager will run without a visible interface. MS Knowledge Base Q129868
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.MS Knowledge Base Q129885
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.MS Knowledge Base Q138065
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.This is a confusing point, since terminology here gets in the way. As previously stated, the server machine must be running a 32 bit environment: Windows 95 or more probably, Windows NT. The sever machine must have the Automation Manager running, and this program is 32 bits only. The OLE server, that is the program, can be compiled as 16 or 32 bits. (I have tested the scenario of 16 client to 16 server with no problems). However, it is silly to compile a 16 bit application that will only be able to run in a 32 bit environment. Therefore, the OLE server should be a 32 bit application. The following is a step by step tutorial on setting 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.
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.It is always faster to pass parameters than it is to set individual properties. Use optional parameters and set the necessary properties in the beginning of the code module. This will reduce the number of calls needed to server and improve performance, at the cost of some additional code in the module. Using a ByRef actually passes a data pointer to a Function/Sub, so it is much faster for in-process subroutines. It is slower though, on remote servers, since the data must be copied twice. Since a pointer cannot span across machines, OLE must copy the value to the target machine, and then copy the value back to client, since it has no way to know if the data was changed.
Please contact Richard Clark (firstname.lastname@example.org) for additions or errors in this document. The document is provided as is, and is used at the risk of the reader.
Editor: Rick Clark
Last update: 2007-09-25
Copyright 1995-2007 VBI