In rare situations, you may want to enable client or server logging, particularly to diagnose problems. The server also records all error traps in its error global.
You can enable client logging in two general ways:
By setting the LogMask
property of VisM.ocx
. This property overrides any registry settings.
By setting the registry switches. The registry settings act as defaults if the property is not set. The registry switches provide precise control over what client processes create logs. Specifically, the switches can now reside in either the HKEY_CURRENT_USER
hive or the HKEY_LOCAL_MACHINE
hive, and can be modified so that logging only occurs for a particular user, or application program, or combination of the two. The choices are searched in a hierarchy, from most specific to most general, so that general switches can be overridden by more specific ones for special purposes.
In addition, Caché Direct provides routines to set and get these registry entries, so they can be manipulated easily under program control.
You can directly set the LogMask
property of VisM.ocx
. To enable logging, set this property equal to the integer value of 0x7FFFFFFF
(for C++) or &H7FFFFFFF
(for Visual Basic). For example:
VisM1.LogMask = Val(&H7FFFFFFF)
The decimal integer corresponding to this hex value is 2147483647
To disable logging, set the property to 0. This property overrides any registry settings.
The client logging switches are registry key values with the following names:
is a bit mask that indicates whether logging should take place or not. It takes the same values as the LogMask
property described in the previous section, VisM LogMask Property
allows the logs to be directed to a specific folder. The default is the folder that contains the main executable for the application. The default applies if the value is not given or if it is blank. Also see the section Limiting the Size of the Log Files
, later in this chapter.
In addition, for a specific user running a given application, three other versions of each value are available. They are named by concatenating the user and/or application name to the basic value name. For example, if the username is Joe
and the application name is MyApp.exe
, you could also have values named LogMaskJoeMyApp
, and LogMaskMyApp
, which would be checked in that order. Each would be checked first in HKCU
and then in HKLM
. The first one found would be used. Similarly, there could be values named LogFolderJoeMyApp
, and LogFolderMyApp
Getting and Setting the Registry Values
Four client-side routines are available to set and get these registry values. They are exposed by the ISLog.dll
file. Their C signatures are as follows:
DWORD GetRegLogMaskEx(LPCSTR pUsername, LPCSTR pAppname);
DWORD SetRegLogMaskEx(HKEY hiveKey,
int GetRegLogFolderEx(LPCSTR pUsername,
void SetRegLogFolderEx(HKEY hiveKey,
In each case, if pUsername
are null or empty strings, those arguments are not used. If those arguments are given, the Get_ routines will search through the appropriate combinations, returning the first one found, if any.
returns the length of the folder name it finds, and 0 if none is found.
Limiting the Size of the Log Files
This setting specifies the maximum size of any log file, while the client is writing to the log. When the log reaches that size, the client starts writing to a new log file. If there was a previous older log file, it is discarded, so that there are never more than two log files. When the client shuts down, the two existing log files are combined, and the resulting log can be up to two times the value of LogSizeLimit
, but never more than that.
The start of the log file will contain basic information about the session, followed by a divider labeled with the string Snip
, followed by the most recently logged activity.
If you enable server logging, the logs will contain a trace of the activity in the server portion of the slave server job, including all the messages that went between the client and server. To enable server logging, use the Terminal to enter the following command:
After you enable logging, any new Caché Direct server job creates a text log file, usually in the mgr
directory, named CDxxx.log
, where xxx
is the $Job
of the job for which the log is created. Each new job gets its own log file. Once the switch is on, run whatever tests you like.
The switch is checked only as the slave server job starts. If the switch is changed after that, it has no effect on jobs that are already running. So logging cannot be turned either on or off after a job starts.
When the tests are over (or at least started), turn the switch off by setting it to an empty string or by killing it:
This switch is global and thus affects all new jobs. Also, the logs can get very large. Therefore, it is a good idea to perform logging as briefly as possible, especially if the server is not dedicated to the tests. You could automate the process from the client, running a Caché Direct job that turns on the switches just before the test itself starts and a similar job that turns them off just after the test starts. This could even be part of the test itself, setting the switches, reconnecting by resetting the Server
property (which will start a new server job), and then turning off the switches as the first activity after reconnecting. For example, if the client is a Visual Basic application, it might start up with code like this:
VisM1.Execute "Set ^%CDLOG=1"
; reset to the same value as before then start a new job
VisM1.Server = VisM1.Server
VisM1.Execute "Kill ^%CDLOG"
Independently of the server logging that is mentioned above, the server keeps an internal server error log in the global %CDServer("Error")
. This contains all trapped errors.
Note that if this log includes a line that says emergency brake,
that indicates that the server detected an infinite error loop (five or more errors within a second).