One of the issues that every developer has to contend with are problems that arise in an application after it's been distributed to end-users. And errors related to Windows Sockets programming can be even more difficult to track down because there are so many variables involved (such as the platform, operating system version, system configuration, and so on). To address these difficult problems, the SocketWrench control has the built-in ability to log the Windows Sockets API function calls that are made. There are three properties related to function tracing: Trace, TraceFile and TraceFlags. Setting these properties allows your application to dynamically manage function tracing features available to the control. The Trace property is a boolean flag which simply enables or disables the function tracing feature. The TraceFile property specifies the name of a trace log file in which each function and its parameters will be written. If this property is not explicitly set, then a file named CSTRACE.LOG will be created in the system's temporary directory (the directory specified by the TEMP environment variable). The TraceFlags property specifies what type of logging will be performed by the control, and may be set to one of four values: 0 (TRACE_ALL) in which all functions will be logged, 1 (TRACE_ERROR) in which only errors will be logged, 2 (TRACE_WARNING) in which case both warnings and errors will be written to the log file, and 4 (TRACE_HEXDUMP in which all functions will be logged, together with ASCII and hexadecimal displays of all data that is sent or received on sockets. By default, all functions calls are logged by the control (TRACE_ALL).

For the SocketWrench library there are two functions related to function tracing: InetEnableTrace and InetDisableTrace. The arguments to InetEnableTrace are equivalent to the TraceFile and TraceFlags properties of the controls, as described above. Calling InetEnableTrace is equivalent to setting Trace = True, and calling InetDisableTrace is equivalent to setting Trace = False.

The trace file has the following format:

VB6 INF: WSAAsyncSelect(46, 0xcc4, 0x7e9, 0x27) returned 0
VB6 WRN: connect(46, 192.0.0.1:1234, 16) returned -1 [10035]
VB6 ERR: accept(46, NULL, 0x0) returned -1 [10038]

The first column contains the name of the process that is being traced (in this case, it is Visual Basic 6.0). The second column identifies if the trace record is reporting information, a warning, or an error. What follows is the name of the function being called, the arguments passed to the function and the function's return value. If a warning or error is reported, the error code is appended to the record (the value is placed inside brackets).

When reading a trace log, there are two common things that you will see:

1. The error code 10035, which corresponds to the Winsock error WSAEWOULDBLOCK is a normal occurrence on connect calls, and should not be taken as a cause for concern by itself.
2. The normal return value for a select call is greater than zero, typically a value of one. A select call that returns zero usually indicates a timeout.

If parameters are passed as integer values, they are recorded in decimal. If the parameter or return value is a memory address) it is recorded as a hexadecimal value preceded with "0x". A special type of pointer, called a null pointer, is recorded as NULL. Those functions which expect socket addresses are displayed in the following format: aa.bb.cc.dd:nnnn

The first four numbers separated by periods represent the IP address, and the number following the colon represents the port number in host byte order. Note that in the second line of the above example, the control is attempting to connect to a system with the IP address 192.0.0.1 on port 1234.

To enable tracing in your application, you also need to redistribute an extra file called CSTRACE6.DLL. This library contains the actual function tracing code, and If CSTRACE6.DLL is not included with your software, the application will proceed nonetheless. If you are using the SocketWrench control, it will reset the Trace property to False if the tracing library cannot be loaded. If you are using the SocketWrench library, the function InetEnableTrace will return FALSE if the tracing library cannot be loaded. Note that this DLL will only provide function tracing capability to the SocketWrench control and library; it is not a general purpose DLL for tracing Windows Sockets functions and will not log the functions made by any other application or component.

There are several ways that you could incorporate function tracing in your software. The simplest would be a menu item or a command line switch (like /DEBUG) in which the Trace property would be set to True. A more complex approach would be to include a dialog or property sheet which allows the user to specify the log file name and tracing options. When an end-user calls for technical support and is encountering a problem that you think may be network related, you can instruct them to enable the tracing feature and then email or fax you a copy of the log file. In turn, if it is a problem that you don't understand, you can send the log file to a support technician who can analyze the log and provide you with additional information about what may be going on inside your application.

Remember that if you do not use the tracing features at any time during the execution of your program, there is no additional performance penalty. If you do enable tracing at some point, the tracing library will be loaded and memory will be allocated by the logging functions. These functions open, append to the trace log, flush and then close the log file for each Windows Sockets function call that is made. This insures that the last function called is logged in case of a general protection fault or other abnormal termination of the program. However, because of the file I/O overhead, it's recommended that your program rename or remove the log file before beginning a new trace.

Copyright © 2008 Catalyst Development Corporation. All rights reserved.