The Elements of the ActiveX Interface
The Caché ActiveX binding provides access to Caché from any application that supports ActiveX objects. This binding allows you to instantiate and manipulate Caché objects within client applications, and provides a transparent interface to their server-side object instantiations.
The examples in this book were written for Visual Basic 6 or earlier (including VBA and VBS scripting languages), and may not work in .NET Basic without modification. InterSystems strongly recommends migrating to newer and more secure technologies (see the Overview for more information).
Caché objects provide connectivity with a wide variety of client applications and development tools via an ActiveX interface:
Caché objects include the following ActiveX components:
Caché Object Server for ActiveX — An ActiveX automation server that exposes Caché objects as ActiveX objects.
Caché List Control — An ActiveX control written for Visual Basic that aids in the display of query results. You must provide the interface for selecting queries and query parameters for execution.
Caché Query Control — An ActiveX control written for Visual Basic that provides a simple interface for executing queries and displaying the results. The Caché Query Control provides an interface for selecting at runtime any query that returns the ID and for specifying any query parameters.
Caché Object Form Wizard — A Visual Basic add-in that allows you to quickly and easily create a simple form to access properties of a single Caché class.
The Caché Object Server for ActiveX
The Caché Object Server for ActiveX (CacheActiveX.dll) is a complete ActiveX in-process automation server that gives client applications access to server-based Caché objects. Internally, the Caché Object Server for ActiveX creates an ActiveX proxy object that mirrors an object on a Caché server. Object properties are exposed as ActiveX properties. Similarly, methods are exposed as ActiveX methods. When a method of an ActiveX proxy object is called, it causes the corresponding method to be called by the mirrored Caché object on the server machine.
Every client-side ObjInstance proxy object refers to a Caché object on a server. It is possible for several client-side objects to refer to the same server-side object. With each added reference, the server-side object's reference count is increased by one as long as any client-side objects are connected to it.
Client-side objects that perform special functions, such as the SysList and ResultSet objects, are not based on a Caché object and do not refer to an object on a server. See the Caché ActiveX API Reference for more information on the types of objects available from ActiveX.
The client-side proxy object is an ActiveX object and is referred to using a pointer to the IDispatch interface. For example, to access the properties and methods of a patient object from Visual Basic, use the following code:
Print patient.Name 'returns the value of Name for the referenced patient object Print patient.Admit 'runs the Admit() method of the patient object on the server
As an improvement on typical ActiveX automation servers, the Caché Object Server for ActiveX does not require you to register every object class that you define with the client operating system. Instead, it determines class information at run time. This lets you develop large applications with many client machines and many server-based objects without having to maintain ActiveX registry entries.
Upgrading from CacheObject.dll
Although CacheActiveX.dll has been the preferred version of the Caché ActiveX binding since Caché 5.1, the binding is also available through an older DLL, CacheObject.dll. This DLL is slower and has some small differences, as noted in this documentation. You should use CacheActiveX.dll for all new development. The older DLL is provided only for backward compatibility. The two DLLs differ primarily in the following ways:
CacheActiveX.dll can be used on 64-bit Windows in a 64-bit process.
Internally, CacheActiveX.dll uses the Caché C++ binding to get object-level access to a Caché server, providing better performance in some cases due to more sophisticated object caching.
CacheActiveX.dll supports Caché security (including features such as the ability to use Kerberos authentication), and does not support the less secure encrypted password feature used by CacheObject.dll.
The default SQL runtime display mode for CacheActiveX.dll is ODBC, rather than Logical as inCacheObject.dll.
When using CacheActiveX.dll proxy objects (see The Objinstance Class), the sys_Close() method actually closes the server object. The method does nothing when called by CacheObject.dll proxy objects.
To preserve complete compatibility with existing applications, Caché installs both CacheActiveX.dll and CacheObject.dll. By default, existing applications will continue to use the original CacheObject.dll. If you wish to use the newer binding, you must modify your existing application to reference this new DLL, and test that your application performs as expected. To upgrade your code from CacheObject.dll to CacheActiveX.dll, perform the following steps:
Replace all references to CacheObject.Factory with CacheActiveX.Factory.
Make any changes required by the switch from Logical to ODBC SQL runtime display mode (see the ResultSet.SetRunTimeMode() method).
Optionally, modify connection logic to use the new Caché security features, as described in Connecting to a Server.
Configuring a Visual Basic Project for Early Binding
Although you can use Caché objects from a Visual Basic project without any configuration, you must configure your Visual Basic project if you want to use early binding. Early binding is a feature of Visual Basic that allows you to declare objects so they carry information about their type. For example, with early binding, you can specify:
Dim MyList as CacheActiveX.SysList
Early binding also provides pop-up menus which show you possible elements to use to finish a statement. For example, you can choose from a list of possible object types to associate with a new instance:
Early binding also provides pop-up syntax windows for Caché elements:
To use early binding, select the project references as outlined below. The Visual Basic project configuration process consists of selecting the project references. Whenever you create a new Visual Basic project, you must add CacheActiveX.dll to your project references. To do this:
Within Visual Basic, open the references window using the References menu item in the Project menu.
Select the check box to the left of this DLL.
If this DLL does not exist in a list of available references:
Click on the Browse button.
Locate the appropriate DLL file and double-click it.
Typically, you select the CacheActiveX.dll in the Program Files\Common Files\Intersystems\Cache directory. However, if you are working with legacy code, you may be required to use the CacheObject.dll file instead. You can locate this file in the <installation-root>\bin directory.
If you upgrade to InterSystems IRIS, you must use a recent version of the CacheActiveX.dll file, which you can find in the Program Files\Common Files\Intersystems\IRIS directory. InterSystems IRIS supports ActiveX only for use in legacy applications. InterSystems recommends migrating ActiveX applications to the InterSystems IRIS Native SDK (see Using the Native API for .NET).