Automation Servers in Visual FoxPro
You can create, build, distribute, and access Automation servers in Visual FoxPro.
Creating Automation Servers
You can create Automation servers as OLE public user-defined classes in program (.prg) files or visual class library (.vcx) files. You can have as many OLE public classes as you want in an application project.
Building Automation Servers
After you create an Automation server, you can build it as an out-of-process or an in-process component. An out-of-process component is an executable (.exe) file that runs in its own process. An in-process component is a dynamic-link library (.dll) file that runs in the same process address space as the client that calls it. Communication between a client application and an out-of-process server is called cross-process communication.
When you build an Automation server as an executable (.exe) file, you do not lose any functionality of normal executable files. You can run the executable file, provide a user interface, and any other functionality available for an application. In addition, you increase the extensibility of your application by making it possible for other applications use the functionality you provide in the Automation server.
When building Automation servers, consider the following:
In-process servers can be faster because there is no inter-process communication overhead.
Out-of-process servers can be deployed remotely while in-process servers cannot.
An in-process server and the client share a process address space; therefore, any serious error in the in-process server terminates the client. Errors in an out-of-process server terminates only the server.
Building an Automation server creates three files:
An .exe or .dll file.
A type library (.tlb) file.
The type library file is a binary file that lists all the published classes in your Automation server, along with their properties, methods, and events. OLE object browsers read this information and present it in a readable interface. For more information, see Binding Type Libraries.
A registry (.vbr) file
The registry file lists the global unique IDs (GUID) for the classes in your server.
Note
A .vbr registry file is the same as a .reg registry file except that the .vbr file does not include hard-coded paths.
Distributing Visual FoxPro Automation Servers
When you distribute an Automation server (.dll), you must include the following files:
VFPVersionNumberR.dll or VFPVersionNumberT.dll, where VersionNumber represents the version number of this release of Visual FoxPro.
VFPVersionNumberRENU.dll
GDIPlus.dll
MSVCR70.dll
If you are distributing an Automation server as an executable (.exe) file, see Preparation for Distributing Applications. For more information about run-time libraries, see VFP9R.DLL Run-Time Library and VFP9T.DLL Run-Time Library.
Accessing Visual FoxPro Automation Servers
Any application that can create Automation objects can create objects based on your Automation server, set properties that are not HIDDEN or PROTECTED, and call methods. For example, assuming that your server is named foxole and contains a class named person with a GetName method, the following code could be run in Visual FoxPro:
oTest = CREATEOBJECT("foxole.person")
cName = oTest.GetName()
Similar code could be run in Microsoft Excel or Visual Basic:
Set oTest = CreateObject("foxole.person")
cName$ = oTest.GetName()
Handling Errors in Visual FoxPro Automation Servers
The only interaction with the objects provided by an Automation server is through the methods and properties of the exposed classes. When a client application calls a method of an object, and an error occurs in the Automation server, the method either returns an error value or raises an error in the client application.
The client application decides whether to alert the user or proceed with another execution path. The Automation server itself never interacts with the user. This allows the location of the Automation server to be transparent to the client application. The Automation server can be local, running on the user's computer, or you can use the Remote Automation feature of Visual FoxPro to run it on a network server.
When a Visual FoxPro Automation server generates an error, the Automation server sets the COM ErrorInfo object using IErrorInfo and cancels out of the current method. The Automation client can either release the Visual FoxPro Automation server or, if the client has access to the COM ErrorInfo object, handle the exception based on that information. For more information, see _ErrorInfo( ) API Library Routine.
The COMRETURNERROR( ) function handles errors that occur on an Automation server. You can use COMRETURNERROR( ) in the Error method, to populate the COM exception structure with information that Automation clients can use to determine the source of Automation server errors. For more information, see COMRETURNERROR( ) Function.
See Also
Tasks
How to: Create Automation Servers