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.
VisM LogMask Property
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:
LogMask 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.
LogFolder 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.
The switches are located under the key hivename/Software/InterSystems/Cache, where hivename is either:
HKCU (the HKEY_CURRENT_USER hive)
HKLM (the HKEY_LOCAL_MACHINE hive).
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, LogMaskJoe, 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, LogFolderJoe, 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, LPCSTR pUsername, LPCSTR pAppname, DWORD dwMask); int GetRegLogFolderEx(LPCSTR pUsername, LPCSTR pAppname, LPSTR buf, int buflen); void SetRegLogFolderEx(HKEY hiveKey, LPCSTR pUsername, LPCSTR pAppname, LPSTR buf);
In each case, if pUsername or pAppname 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.
For example, if you call GetRegLogMaskEx(NULL, “Joe”, NULL), it will first look for LogMaskJoe in HKCU and HKLM and then LogMask in HKCU and HKLM, returning the first one found, or 0 if none are found. If both pUsername and pAppname are given, then all four combinations will be searched, in the order given above.
For the SetRegLogMaskEx and SetRegLogFolderEx routines, if HKCU or HKLM is given for the first argument, then that hive will be set. If no hive is given, then HKLM, the default, will be set.
SetRegLogMaskEx returns any previous value of the key it is setting.
GetRegLogFolderEx returns the length of the folder name it finds, and 0 if none is found.
Limiting the Size of the Log Files
Two client-side registry settings (LogSizeLimit) can prevent the log files from becoming too large. The switches are located under the key HK/Software/InterSystems/Cache, where HK is either HKCU or HKLM as before.
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"
Server Error Global
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).