Craig Lokken
Mary Anne Kobylka
Microsoft Corporation
October 1995
The Microsoft® Visual Basic® 4.0 programming system includes a powerful new feature: the ability to create OLE servers. An OLE server is an application that exposes functionality that can be used and reused by other applications through OLE Automation. For example, using Visual Basic 4.0 a developer can create an OLE server that displays reusable forms, implements business rules, or packages a complex routine into a simple component that other programmers can use.
The Enterprise Edition of Visual Basic version 4.0 includes an additional new feature, Remote Automation. Remote Automation enables developers to run an OLE server on one machine and the client application on a separate machine on the network. This feature is extremely useful for implementing a three-tier client/server, asynchronous processing; offloading work to underused machines; and reducing client maintenance.
Together these new features provide the foundation for building sophisticated reusable application components and distributing those components throughout a company's entire computing universe, or enterprise.
This document provides an overview of OLE servers and explains how to use Visual Basic 4.0 to create an OLE server.
An OLE server is an application that exposes objects that can be used by other applications. An OLE server provides code that you do not have to write. Any application that supports OLE Automation can control an OLE server.
For example, Microsoft Excel is an OLE server. Microsoft Excel exposes objects such as worksheets, charts, and so forth. From a Visual Basic 4.0 application, you can send data to Microsoft Excel and create a chart. You need not know the details of creating a chart; instead, you simply create an instance of the object you want, set properties, and execute a method to create the chart.
The following figure shows how an OLE server created with Visual Basic 4.0 can be used by any number of other applications.
Figure 1. An OLE server available for use by various applications
When you are creating OLE servers in Visual Basic 4.0, the first step is to define objects within your Visual Basic 4.0 project. These objects can then be used within your Visual Basic 4.0 project or exposed to other applications.
Visual Basic 4.0 includes a new type of code module called a class module. Each class module defines a blueprint for an object. After you have added a class module to your project, you can define custom methods and properties for that class. To define methods for a class, you simply create Public Sub and Function procedures within the class module. To define a property for the class, you either create Property procedures or define public variables. Property procedures enable you to execute code when a property is set or retrieved. Public variables simply hold the property value.
For example, suppose you want to create an Employee object with the following characteristics:
Create a class module as follows:
Figure 2. Using a class module to create an Employee object
Once you have created your class, you programmatically create instances of that class. The instance of the class is the object. You can create multiple objects of the same class. You use the Dim statement to create an instance of the class. For example:
Dim Employee1 As New Class1
Dim Employee2 As New Class1
Employee1.EmployeeName = "Joe"
Employee2.EmployeeName = "Mary"
Employee1.Hours = 45
Employee2.Hours = 50
Employee1.HourlyWage = 10
Employee2.HourlyWage = 12
MsgBox Employee1.ComputeSalary
MsgBox Employee2.ComputeSalary
Once you have objects defined in your Visual Basic 4.0 application, you can easily turn your application into an OLE server and make those objects available to other applications.
To create an OLE server, you must set some project options and some properties of the class modules that you want to expose.
The first step in creating an OLE server is to set the project options. You can do this from the Project tab in the Options dialog box.
Figure 3. Setting the project options for an OLE server in the Options dialog box
For most OLE servers, you set the startup form to Sub Main. The code in the Sub Main procedure executes when the OLE server starts. Define the Sub Main procedure in a Standard module.
The project name is the name that the client application programmatically uses to refer to your server. The following example shows the code from a client application to create an instance of a class named EmployeeClass in a server named MyServer.
Dim x As Object
Set x = CreateObject ("MyServer.EmployeeClass")
You can run multiple instances of Visual Basic 4.0. This is very useful for debugging OLE servers. You can run a client in one instance and a server in another.
To test your OLE Server, set StartMode to OLE server. This causes Visual Basic 4.0 to keep the project running even though no code is executing. This enables you to start a client application to test your OLE server application in the Visual Basic 4.0 development environment.
To make your objects available to other applications, set the class module Public property and Instancing property.
Figure 4. Setting properties of class module
The Public property determines whether the class is visible to other applications. If Public is False, the class is unavailable to other applications and the Instancing property is ignored.
If Public is True and Instancing is 1 or 2, the class can be created and controlled by other applications. If Public is True and Instancing is 0 (Not Creatable), other applications can control an existing instance of the class but cannot create new instances.
The Instancing property determines whether applications outside your project can declare new instances of your class.
If you set Instancing to 1, Creatable SingleUse, a separate OLE server executable is started for each instance of this class. For example, if a client application creates two instances of Class1, Visual Basic 4.0 starts two separate server executables.
If you set Instancing to 2, Creatable MultiUse, one OLE server executable can service multiple clients. For example, if a client application creates two instances of Class1, Visual Basic 4.0 starts one server executable. That executable creates two instances of Class1.
Setting Instancing to Creatable MultiUse minimizes resource use because you run only one copy of the OLE server. However, all requests from client applications are processed serially; that is, the server will not execute a second request until it has completed the first request. If you set Instancing to Creatable SingleUse, each OLE server executable can process requests independently. This is especially important with Remote Automation where many clients may be making requests at the same time.
The Name property is the name the client application uses to create an instance of the class.
Once you have created your OLE server, you can use the objects your server exposes from any application that supports OLE automation. For example, from Microsoft Excel you can make a reference to the OLE server and then use any of the objects exposed by that server.
To make a reference in Microsoft Excel you must have a module active. From the Tools menu, choose References to display the References dialog box. The following figure illustrates the References dialog box.
Figure 5. Activating a module sheet through the References dialog box
Making a reference to the OLE server enables you to use the Object Browser to display the objects that the server provides. To open the Object Browser in Microsoft Excel, choose Object Browser from the View menu. For example, the server created previously would appear as follows in the Object Browser.
Figure 6. An OLE server as shown in the Object Browser
After you have made a reference to the OLE server, you can begin to work with the server’s objects. The following example illustrates using the server’s objects from Microsoft Excel. Note that this same code can be run in Microsoft Access, Microsoft Project, or another instance of Microsoft Visual Basic 4.0.
Figure 7. Using an OLE server from within Microsoft Excel
Once you have tested your OLE server, you are ready to compile it. You can compile your OLE server as an executable file (.EXE) or as an OLE dynamic-link library (.DLL).
If you choose Make EXE File from the Visual Basic File menu, the OLE Server is created as an out-of-process server. When a client application uses an out-of-process server, the server runs in its own process space (a separate application). Calls between a client and the server pass through the OLE interface.
If you choose Make OLE DLL from the File menu, the OLE server is created as an in-process OLE server (a DLL). When a client application uses an in-process server, the server runs in the same address space as the client application and is significantly faster than calling an out-of process server.
When choosing between an OLE executable file and an OLE DLL, your main consideration is speed versus flexibility. An OLE DLL is usually much faster than an OLE executable because the OLE DLL runs in the same process space as the client application.
There are times, however, when you need an OLE executable in order to achieve a desired result. For example, you might want to run an OLE server asynchronously (asynchronous operations must execute in a separate process), to run an OLE server on a different machine, or to display modeless forms from an OLE server.
You can store sets of related objects in a Collection object. A Collection object is a predefined object in Visual Basic 4.0 and is created in the same way as other objects. For example:
Dim Employees As New Collection
Once you have created a Collection object, you can add items to the Collection using the Add method. For example:
Private Function AddEmployee(x, y, z)
Dim Employee As New EmployeeClass
Employee.EmployeeName = x
Employee.Hours = y
Employee.HourlyWage = z
Employees.Add Employee
End Function
Storing groups of related objects in a collection enables you to easily work with those objects as a group. For example, you can use the Employees Collection created in the preceding code example to print a list of all Employees:
Private Sub cmdPrintEmployees_Click()
For Each x In Employees
Print x.EmployeeName, x.ComputeSalary
Next
End Sub
Remote Automation enables you to run your OLE server on one machine and your client application on a separate machine. With Remote Automation you can easily create applications that divide their processing across the network, thereby increasing scalability and improving client maintenance and performance.
As shown in the following diagram, Remote Automation takes OLE Automation requests from the client, sends them across the network using Remote Procedure Calls (RPCs), and receives them on the server. The components necessary for Remote Automation are available in the Enterprise Edition of Visual Basic 4.0.
Figure 8. How Remote Automation works
Neither the client nor the server knows that the connection is remote. No special coding is required in the server. Even though a client application is accessing an OLE server on another machine, Remote Automation makes the transaction “look like” local OLE Automation to both the client application and the OLE server.
Remote Automation is a key enabling technology for building distributed three-tier client/server applications, as well as for offloading processing and decreasing client-maintenance costs.
You may want to enable your users to start a long procedure on an OLE server and continue working without waiting for the procedure to finish. This can be done by running your OLE server application asynchronously with your OLE client application. The server sends a message to the client application when the process finishes.
For example, if you have a lengthy report-generation task to do, you can have it execute in the background, freeing up the client application to perform other tasks.
To enable an asynchronous method, do the following:
The client application invokes a server method to start a background process. The client passes an object to the server that the server can use to notify the client when the process has finished.
When the process is finished, the server application invokes a method on the object received from the client application.
The following code provides an example of calling an OLE server asynchronously. The first procedure is from the client application. It creates an instance of the object it will pass to the OLE server (to receive notification back from the server when it is finished processing) as well as an instance of the server itself. It then calls a method in the server. The second procedure is the method being called in the OLE server application. Note that the last line in this procedure enables a Timer control. The code in the Timer control does the actual processing in the server application. This allows the method in the server to complete processing and return control to the client application.
Private Sub cmdGetDirectoryInfo_Click()
Dim AsyncObject As New Async
Set MyDrive = CreateObject("Server2.Drive")
MyDrive.GetDirectoryInfo StartingPath:="C:\", _
CallerObject:=AsyncObject
End Sub
Public Sub GetDirectoryInfo(StartPath As String, CallerObject As Object)
Dim MyForm As New Form1 'create an instance of form1
gStartingPath = StartPath
Set gCallerObject = CallerObject
gCallerObject.Status "Starting..."
' Kick off timer with code to get the directory info
' so the timer knows what object to callback.
Set MyForm.CallBack = Me
MyForm.Timer1.Enabled = True
End Sub
The ability to create OLE servers is one of the most exciting new features of Visual Basic 4.0. Sharing code with other programmers no longer requires copying actual source code into several projects. Now, you can simply invoke methods and set properties of your OLE server objects to achieve the desired result. You can update the OLE server without changing the client application. Using Remote Automation enables you to distribute your applications throughout the network.
For more information on building OLE servers, see Microsoft Visual Basic Professional Features: Creating OLE Servers. Also see Chapter 7, “Implementing OLE Servers,” in Building Client/Server Applications with Visual Basic guide, which comes with the Enterprise Edition of Microsoft Visual Basic version 4.0.