Tracing

Use tracing to diagnose HDLC API problems. Tracing records communications events and API calls to a time stamped log. MgslSetTraceLevel enables and disables tracing. MgslGetTraceLevel returns the currently enabled trace levels. MgslResetTraceBuffers discards any trace events in the API trace buffers. MgslGetTraceEvent gets trace events from the API trace buffer as they become available. MgslCancelGetTraceEvent cancels a pending call to MgslGetTraceEvent. MgslPutTraceEvent places application defined trace events into the trace buffer.

WARNING: Enabling tracing may severely degrade the API performance and may generate large volumes of trace data. Use tracing only for diagnostic purposes.

The API has a limited internal trace buffer. If this buffer is full when the next trace event occurs, the API discards the new event and queues a special trace event with EventType_BufferOverflow at the point the buffer overflow occurred. Tracing remains enabled after an overflow, and as buffer space becomes available, the API adds new trace events to the buffers. There may be gaps in any trace data following the overflow event. The trace buffer overflow indicates that the operating speed is too fast for the current tracing level. Reduce the tracing level or lower the operating speed.

If tracing is embedded directly into an HDLC application, then all tracing functions use the device handle returned by MgslOpen. Because normally only one handle to a port can be open at once, external tracing programs, such as the trace utility supplied with the run time kit, call MgslOpenTraceHandle to obtain a device handle. MgslOpenTraceHandle allows opening one extra handle for tracing by another process. Under Windows NT calling MgslOpenTraceHandle required administrative privilege.