Craig Lokken
Mary Anne Kobylka
Microsoft Corporation
August 18, 1995
Microsoft® Visual Basic® 4.0 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, you can create an OLE server that displays reuseable forms, implements business rules, or packages a complex routine into a simple component that other programmers can use.
The Enterprise Edition of Visual Basic includes an additional new feature, Remote Automation. Remote Automation enables you to run an OLE server on one machine and the client application on a separate machine on the network. This is extremely useful for: 3-tier client/server, asynchronous processing, offloading work to underutilized machines, and reducing client maintenance.
Together these new features provide the foundation for building sophisticated reusable application components and distributing those components throughout the 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 a Worksheet, a Chart, and so forth. From a Visual Basic application, you can send data to Microsoft Excel and create a chart. You don't need to know the details of creating a chart, you simply create an instance of the objects you need, set properties and execute a method to create the chart.
The figure below shows how an OLE server created with Visual Basic could be used by any number of other applications.
When creating OLE servers in Visual Basic, the first step is to define objects within your Visual Basic project. These objects can then be used within your Visual Basic 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, if you wanted to create an Employee object with the following characteristics:
you would create a class module as follows:
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 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 will need to set some project options and set some properties of the class modules that you want to expose.
The first step when creating an OLE server is to set the Project options. This can be done from the Project tab in the Options dialog.
For most OLE servers, you will 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. 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 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 development environment.
To make your objects available to other applications, set the class module Public property and the Instancing property.
The Public property determines whether the class is visible to other applications. If Public is False, the class is not available 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 if 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 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 starts one server executable. That executable creates two instances of Class1.
Setting Instancing to MultiUse minimizes resource use because you will only run one copy of the OLE server. However, all requests from client applications are processed serially; that is, the server won't execute a second request until it has completed the first request. If you set Instancing to SingleUse each OLE server executable can process requests independently. This is especially important with Remote Automation where may clients might make 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 could make a reference to the server application and then use any of the objects exposed by that server.
Note To make a reference in Microsoft Excel you must have a module sheet active. From the Tools menu, choose References to display the References dialog.
For example:
Making a reference to the OLE server enables you to use the Object Browser to browse the objects that the server provides. To display the Object Browser in Microsoft Excel, choose the Object Browser command from the View menu. For example, the server created previously would appear as follows 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 example below shows using the server's objects from Microsoft Excel. Note that this same code could be run in Microsoft Access, Microsoft Project, or another instance of Microsoft Visual Basic.
Once you have tested your OLE server, you are ready to compile the server. You can compile your OLE Server to an executable file or to an OLE DLL.
If you choose Make EXE from the 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, 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 spaces as the client application and is significantly faster than calling an out-of process server.
When choosing between an OLE Executable and an OLE DLL, the main consideration is speed versus flexibility. An OLE DLL will usually be considerably faster than an OLE executable because the OLE DLL runs in the same process space as the client application.
However, there are times when you need an OLE executable in order to achieve a desired result. Some examples of when you would need to use an OLE executable include: running an OLE server asynchronously (asynchronous operations must execute in a separate process), running an OLE server on a different machine, and displaying 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 and be 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 could use the Employees Collection created above 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. You can now easily create applications that divide their processing across the network, providing increased scalability, improved client maintenance, and improved 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 (RPC), and receives them on the server. The components necessary for Remote Automation are available in the Enterprise Edition of Visual Basic.
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 easily building distributed three-tier client-server applications. as well as 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 would send a message to the client application when the process had finished.
For example, if you have a lengthy report generation task to do, you can have this execute in the background, freeing up the client application to perform other tasks.
To enable an asynchronous method
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.
Below is 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. Using a Timer control 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 w/code to get the directory info
Set MyForm.CallBack = Me 'so the timer knows what object to callback
MyForm.Timer1.Enabled = True
End Sub
The ability to create OLE Automation servers is one of the most exciting new features of Visual Basic 4.0. Sharing code with other programmers no longer involves copying actual source code into several projects. Now, programmers 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 OLE Automation enables you to distribute your applications throughout the network.
For more information on building OLE servers, see the Microsoft Visual Basic Professional Features Volume 1: Creating OLE Servers and Chapter 7, "Implementing OLE Servers" in the Microsoft Visual Basic Building Client/Server Applications guide (Enterprise Edition).