All of the SocketTools networking libraries include a built-in facility for generating debugging output in the form of a log file that provides information about the internal functions that it is using and the data that is being exchanged between the client and server. This is commonly referred to in the documentation as generating a trace log or enabling function logging.

To provide logging functionality for your application, you must redistribute the cstrace6.dll library along with those SocketTools libraries you are using in your program. The cstrace6.dll library is what performs the actual logging and must be in a directory where it can be loaded by your application. It is recommended that you either install it in the Windows system directory or the directory where your application is installed. Note that this is a standard Windows dynamic link library and it does not need to be registered.

To create a trace log, your application must then call the EnableTrace function in the library. For example, if you were using the Simple Mail Transfer Protocol library, you would call the function SmtpEnableTrace. This function requires two arguments: the name of a file that the trace log data will be written to and a numeric value which specifies the level of the trace. The default level, zero, specifies that general information about the function calls being made will be logged. The most detailed logging is provided by specifying a level of four. In that case, all data exchanged between your application and the remote host is logged. This provides the most information, however it also generates the largest log files. To disable logging, use the DisableTrace function for the library, such as SmtpDisableTrace.

There are two important things that you need to consider when enabling trace logging. The first is that the log file is always appended to, never overwritten by the library. This means that the files can grow to be very large, particularly with trace that includes all of the data sent and received by your application. You can use the standard file I/O functions in your language to manage the log file or even write your own data out to the file. Each time the file is written to, SocketTools will open the file, append the logging data and then close the file. The libraries will never keep the file open between operations. This is important because if your application terminates abnormally, it ensures all of the logging data has been written and there are no open file handles being held by one of the libraries. However, this does incur additional overhead and can impact the performance of your application. When possible, it is recommended that you enable logging around the functions that you feel may be part of the problem you're trying to resolve, and then disable logging when it is no longer required. Simply enabling logging at the beginning of your application can result in unnecessarily large log files.

If your application uses multiple SocketTools libraries, it is only necessary to enable logging in one of them. Once enabled, all SocketTools network operations in the current thread will be logged, regardless of which library was used to enable logging.

Copyright © 2008 Catalyst Development Corporation. All rights reserved.