Skip to main content

This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRISOpens in a new window, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions pageOpens in a new window (login required).

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.

Note:
ActiveX is not recommended for new development

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).

ActiveX Components

Caché objects provide connectivity with a wide variety of client applications and development tools via an ActiveX interface:

Caché Object Server for ActiveX
generated description: objsrvractivex

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
Copy code to clipboard

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:

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
Copy code to clipboard

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:

Automatic Continuation in Visual Basic Code
generated description: vbcontinuation

Early binding also provides pop-up syntax windows for Caché elements:

Pop-Up Help Window in Visual Basic
generated description: vbhelpwin

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:

  1. Within Visual Basic, open the references window using the References menu item in the Project menu.

  2. Select the check box to the left of this DLL.

If this DLL does not exist in a list of available references:

  1. Click on the Browse button.

  2. 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.

Note:
Migrating to InterSystems IRIS

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).

FeedbackOpens in a new window