Notes for Users of the Previous Versions
Caché Direct is designed to be backward compatible, but in some cases there are behavior changes you should know about. Some of the architectural changes are worth highlighting for users of previous versions, who may want to adapt their applications to take advantage of the new features.
IPv6 Issues in Caché Direct
In the current release of Caché Direct, IPv6 address formats are fully supported. In particular, the Server/MServer property of VisM.ocx allows IPv6 addresses within the same general connection string format as previously.
However, depending on how they are used by an application, there may be some hazards that need to be confronted. Specifically, the connection string in Caché Direct is a colon-delimited expression of the following general form:
where server_address is the master server and can be an IP address, a server DNS name, or the special name localhost.
On the return from setting the Server property (which is the mechanism to request a connection to the given server), the property is reset to reflect the result of the connection attempt. If the attempt was successful, a last piece was added containing the slave server address. In recent releases (since the introduction of the superserver), this piece was always the same as the second piece, making it redundant. If the connection attempt was unsuccessful, the value of the property was changed to the empty string, "".
Potential confusion arises with IPv6 addresses, which contain colons in the server_address part. IPv6 also supports more than one form of loopback address. Caché Direct supports all of these format variations. But, depending on the assumptions made by application code, the new addresses could cause incorrect behavior. The following describes how Caché Direct handles IPv6 addresses:
The connection string is still in the same general format, given above. It recognizes the extent of the server_address by looking for the square brackets that enclose the port number.
IPv6 has its own loopback form (::1) and also supports IPv4-style and “mapped IPv4” address forms. These look like ::a.b.c.d and ::FFFF.a.b.c.d, where a.b.c.d are the decimal bytes of the IPv4 address and FFFF is the two-byte sequence of all ones. So IPv4 loopbacks can be expressed as ::127.0.0.1 or ::FFFF.127.0.0.1 or ::FFFF:007F:0100 (low bytes come first in the address). All of these loopbacks are equivalent and don’t represent real addresses. In order to make meaningful comparisons, Caché Direct converts them all, whether from the registry or explicitly from application code, to the name localhost, which is recognized by the connection software and handled appropriately.
Caché Direct no longer appends a third redundant piece to the connection string if the address is in IPv6 format (i.e., contains any colons). If a connection is successful, the Server property will contain the server to which a connection was made. For IPv6 format addresses, it will look like the simple form of the string it was given. For IPv4 or DNS names, or localhost, it will still contain the redundant third piece to maintain backward compatibility with versions of Caché prior to 5.1.
If the application code relies on colons only representing piece delimiters in an IPv6 environment, it will likely fail.
The general approach is that, if a human can easily recognize what is meant by the connection string, then the software can, too. The parsing rules for the connection string are:
The first part is the same as always, CN_IPTCP:.
The next piece (the server, in IPv4 or IPv6 form, and port) is terminated by the closing square bracket after the port number. This eliminates any confusion caused by colons in the address.
The inclusion of username and password in the connection string has been deprecated since the introduction of Cache security. However, both parameters are still recognized and handled correctly by Caché Direct in the extended IPv6 format.
Previous Shared Connection Behavior
The old VisM control was a single-threaded, shared connection mechanism. It had an MServer property, which was shared among all the VisM controls in the process. The property was actually a computed value that reflected the connection to the server. If any VisM changed it, it disconnected from any current server and made a new connection to a new server process. If it was set to an empty string, it disconnected from the server.
Communication occurred in a separate thread.
The new VisM control has a new internal structure with three layers: the VisM objects, the CDConnects to which they are connected, and below that, the server processes that are attached to the CDConnects. The CDConnect has several qualities that are particularly relevant to this discussion:
The CDConnect can be connected to multiple callers. This means that multiple VisM clients can share the same server process.
The CDConnect can be disconnected from one server process and connected to another, bringing along all the callers with it.
The CDConnect does not have to be connected to any server process.
There can be multiple CDConnects, each with its own server and VisM clients.
Because there are now three layers and because of how the CDConnect layer is designed, there is a great deal more flexibility of Caché Direct applications. You can create client/server relationships that were not previously possible. Also because there are simultaneous separate connections, you can have a multithreaded application. Each connection still has a separate communication thread that it manages. Note that each connection must still be synchronous, because the server job itself is single-threaded and can only handle one message at a time.
Given the changes described here, a backward compatibility problem arises for some situations. The new VisM tries to behave the same way for the most common cases. Where it can not, it tries to do the most expected thing.
This version of VisM provides a property called Server, which you use to connect to Caché. For backward compatibility, VisM still has a property with the older name, MServer. In most situations, these properties are interchangeable. These properties do behave differently in the case where the VisM control has not yet been connected to a server.
If the application gets the MServer property and the VisM is not yet connected, it will share the most recent connection, if any, and return that as the MServer property.
If the application gets the Server property in the same situation, the VisM will not be connected, and the Server property remains as an empty string.
If the application sets either the Server property or the MServer property, the behavior is as follows:
If the VisM was not previously connected, a new connection is created, not affecting any existing VisMs or their connections. This behavior is different from that of previous versions of Caché Direct.
If the VisM had previously been connected, the connection object that it is using (possibly shared with other VisMs) will disconnect from its server and, if the connection string is not empty, connect to a new one. Only the VisMs that are sharing the channel are affected. This is compatible with the older versions of Caché Direct, which would change the server for all other VisMs.
Also, this version of VisM provides new methods, which you can read about in the chapter Basics of Using the VisM Control. These methods are Connect(), SetServer(), and DeleteConnection().
As of Caché version 2007.1, you can use a connection tag as the first argument to SetServer(). You can also now set the Server property (or the MServer property) equal to a connection tag.
Other Architecture Changes
The Caché superserver now takes the place of the old Caché Direct master server routine. Formerly, the master server would receive a request for a connection, spawn a slave server process on a new port, and redirect the caller to the new port. The caller would disconnect from the master server and then connect to the slave server on the correct port.
Now the superserver receives a request for a connection, spawns a slave server process, and forwards the caller to this process without any intermediate disconnection. No additional ports are used.
If the Caché Direct server is a Unicode server, all messages are sent in Unicode, eliminating locale issues. (Note that the same is not true for 8–bit servers; see Unicode and Locale Issues.)
Depending on the version of Caché Direct you are using, this version may have more hooks for message handling, controlling the client/server interaction, and so on.
Caché Direct now provides transparent support for Caché security, so there is little need for the login hook (^%CDSwitch("SecHook")) in the NewTask processing. The hook is still supported, but is no longer documented.