Introduction to Caché Direct

Important:

Note that Caché Direct is a discontinued featureOpens in a new tab.

Caché Direct is a client/server connection mechanism that provides, over a TCP connection, direct control over server operation from a Windows COM/OLE or C++ client program. The connection is performed via a very fast, low overhead mechanism. Caché Direct includes built-in, transparent support for Caché security, Citrix/Windows Terminal services, IPv6, and so on.

Note:

As of Caché 2015.1, the client is available in separate versions for 32-bit and 64-bit systems.

As suggested by its name, Caché Direct provides the most direct possible access from a client to a Caché server. That is, ObjectScript commands are sent from the client to the server, executed there, and the results returned to the client. Caché Direct sets up one or more TCP channels between the two parts of the application and manages the messages between them. The full power of Caché objects and embedded SQL are also available through Caché Direct; the client has full access to all the facilities of the server, restricted only by the Caché security settings.

Multiple server jobs/channels may be created and managed simultaneously from a single client process, providing the possibility of client multithreading and connections to multiple servers from a single client at the same time.

Caché Direct also provides facilities for calling back from the server to the client, logging flow of control and communications traffic on both the client and server, and various hooks for message transformations (such as compression), error handling, and shutdown tasks.

Note:

Caché Direct is not intended for use in building Web-based applications. Instead it is meant for direct client/server applications.

Concepts

Caché Direct provides an ActiveX control (VisM.OCX, or VisM64.OCX) that is used most frequently in Visual Basic projects, as well as a C++ interface for C++ clients. The VisM control has properties and methods that you use to specify the connection to Caché and the commands to send.

Internally, the VisM control does not communicate directly with Caché. Instead, it starts and is attached to an object called CDConnect, which in turn connects to Caché, starting a slave server process on the server and managing the communication channel. The CDConnect can be attached to multiple VisM instances, can exist even if detached from all VisM instances, and can be redirected to a different server process. This flexibility means that Caché Direct can support various architectures such as the following:

A setup in which each client VisM has its own server.
A setup where all client VisMs share a single server.
A setup in which a pool of client VisMs share a pool of servers, possibly moving among them, using whichever is currently free.
A setup in which selected client VisMs share selected servers based on the specific databases those servers can access.

The Caché Direct client is supported on all Windows platforms that support the Caché client.

The Caché Direct server is supported on all platforms that support the Caché server.

The servers can be on the same or different machines or databases, in any convenient distribution.

Terminology

The Caché Direct communications model uses the following terms:

A caller is the client code from which you call Caché. These are usually VisM instances and are referred to as VisMs in this document. They may also be C++ code.
A CDConnect is the intermediary object between the VisM client and the server. The CDConnects are created as needed and run on the client machine.
The attachment between a VisM and a CDConnect is referred to as a connection.
The TCP attachment between a CDConnect and a Caché server process is referred to as a channel.

The following figure shows a possible state of a Caché Direct application. The items in the upper area (above the double line) are all running on the client side, within a single process. The items below the double line run on the Caché server machine or machines.

generated description: communications model

Communication Model

Formally, the Caché Direct communications model obeys the following rules:

Each VisM can have at most one connection at any given time. That is, any VisM is either unattached or is attached to a single CDConnect.
Each CDConnect can have at most one channel at any given time. That is, any CDConnect is either unattached or is attached to a single Caché server process.
Each CDConnect can have any number of connections. That is, any CDConnect can be attached to zero, one, or more VisMs. This means that multiple VisMs can share the same server context. These VisMs would have access to the same server local variables, except for the variables that are reinitialized by each message; see the section Mirrored VisM Properties, in the next chapter.
A CDConnect does not have to be attached to a Cache server process. It lives independently of the VisMs and the server processes. A CDConnect exists until it is destroyed. It is destroyed automatically when it is no longer accessible (when it has no connections and if it has no tag), or you can explicitly destroy it via the DeleteConnection() method.

Note:

Before ISCDLink version 220, a CDConnect was not automatically destroyed when it became inaccessible.
A CDConnect can be redirected to a different Caché server. This means, of course, that any VisMs that are attached to this CDConnect will be effectively attached to the newly chosen server as well.
Each Caché server job is a single thread. Therefore, communication on each channel must be synchronous; that is, each client message must be processed and responded to before the next message can be read. This means that if multiple VisMs share a single CDConnect, they are constrained not to try to communicate simultaneously. If they do, you will get a “nonsynchronous communication” error.
A Caché server job must have exactly one channel. When you close a channel from a CDConnect, you also end the corresponding Caché server job.

An analogy may be helpful. A CDConnect behaves as a speaker phone with a single telephone line. The listeners in the room are the VisMs; they all hear the same communication. There is one person on the other end of the call; that person is the Caché server. If the call is transferred to another server, all the VisMs are now connected to that new person.

Available Tools and Approaches

On the client side, Caché Direct is a set of layered C++ classes, which in turn are wrapped in the VisM control, which exposes all the necessary properties and methods. When you install the Caché client software, it installs and registers this control so that you can use it in an ActiveX host, such as Visual Basic. As a result, you can use Caché Direct at several different levels:

You can include the Caché Direct ActiveX control in a Visual Basic project. Then your application (possibly with user interaction) can set values of properties, execute methods that send code to the Caché server, and display the results. This document assumes that this technique is the most common usage.
You can use the Caché Direct C++ classes in your C++ project. Then you can create instances of these classes as needed, and set properties and execute methods, to communicate with the Caché server.

On the server side, Caché Direct is a transparent part of the Caché server installation. If you need to upgrade the Caché Direct server without installing a later version of Caché itself, there is a simple way to load the latest Caché Direct server code into your Caché installation. See Upgrading Your Caché Direct Server, near the end of this manual.