Using Caché Direct in Non-ActiveX Applications

General Procedure

The overall procedure is as follows:

1. Get the Caché Direct header files (.h) from the InterSystems InterSystems Worldwide Response Center (WRC)Opens in a new tab. These files define the C++ classes that provide Caché Direct capabilities.

2. Include these files in your application source code.

3. To reproduce the functionality of the VisM object, have your code create an instance of the CDLink class and an instance of the CDParms class. In general:

   • CDLink includes properties such as timeouts and error properties and methods for managing connections to Caché. These are the same as the corresponding properties of the VisM control.

   • CDParms contains all the properties that the client sends to the server. These properties are also the same as the corresponding properties of the VisM control.

4. Set values of properties and execute methods as needed. The same rules and considerations apply in this case as with the VisM control.

Recommendations

The header files provide a lot of information about the Caché Direct classes, but not all these classes are suitable for direct use. The first recommendation is to use only the CDLink and CDParms classes. These classes expose the appropriate methods of the lower-level classes and ensure that connections are managed correctly. You should ignore classes other than CDLink and CDParms.

The second recommendation is to use the CtrlExec1() method of CDLink, rather than the CtrlExec() method. The former method is designed for use with the CDParms class, which you use as a container for the mirrored properties.

Notes

For reference purposes only, you may find it helpful to understand the organization of the Caché Direct classes. First, the primary classes are as follows:

• The CDLink class represents the client. The VisM control is a wrapper around this class. This class exposes the common properties and methods that would be needed by any client. Properties include timeouts, callback function pointer, the CDMsg object, Error, ErrorName and ErrorTrap, keepalive, client tag. Methods include those to manage its own properties and those of its CDConnect object, which it creates as needed. Each CDLink may be attached to zero or one CDConnect.

• The CDConnect class represents the CDConnect object, as described earlier in this document. It includes linkages to the underlying communications DLLs, either the older NTI DLLs or the newer CConnect.dll that manages Kerberos security. It also provides the client side of the read/write hooks. It holds the basic static client information, such as the executable name and signature, and the user and client machine names. It handles the communications threading, timeouts, and the keep alive facility. It provides basic methods like Connect, Send and SendKeepAlive, Receive, and Disconnect, and exposes the Server property and other properties to its clients. It also exposes server properties like whether it is a Unicode server, and the address and port of the server. It keeps a list of its zero or more attached CDLink clients.

• There is also a helper class, CDMsg, that knows how to compose and decompose messages in the proper format. CDMsg provides methods like Init, AppendField, and GetField. The CDLink includes a CDMsg for building messages from its client. There is also a CDMsg in the CDConnect, used for messages which it constructs itself, like the Task and KeepAlive messages.

To support direct access, there are also some helper classes:

• The CDProp class defines some data types and provides conversion methods for them. It is used to represent a single mirrored property.

• The CDParms class is a container for all the VisM properties that the client sends to the server: the mirrored properties and a few additional properties. Internally, this class contains multiple instances of CDProp.

Each CDProp contains a single property. CDParms is a collection of all the CDProps for one client.