History log and trace files

History log:

The log functions allow you to write message text to the iSeries™ Access for Windows^® History Log. The message text needs to be displayable ASCII character data.

iSeries Access for Windows has instrumented all of its programs to log messages to the iSeries Access for Windows History Log. Messages also are logged by the DLLs that are supplied with the product.

The History Log is a file where message text strings are logged through the cwbSV_LogMessageText API. The log provides a history of activity that has taken place on the client workstation.

Trace files:

The trace functions allow you to log low-level events that occur as your program runs. For example, you can track various return codes that were received from calling other functions. If your program is sending and receiving data, you may want to log the significant fields of the data (for example, function byte or bytes, and data length) to aid in debugging if something goes wrong. Use the Detailed data trace function (cwbSV_LogTraceData) to accomplish this.

Another form of trace, the Entry Point trace function, allows you to track entry into and exit from your routines. iSeries Access for Windows defines two different types of entry point trace points:

API trace point:

Use the API (application programming interface) trace point to track entry and exit from routines that you externalize to other programs.

SPI trace point:

Use the SPI (system programming interface) trace point to track entry and exit from key internal routines of the program that you want to trace.

The key piece of information that is provided on the APIs is a one-byte eventID. It allows you to identify which API or SPI is being entered or exited. Data such as input values can be traced on entry, as well as tracing output values on exit from a routine. These trace functions are intended to be used in pairs (for example, cwbSV_LogAPIEntry and cwbSV_LogAPIExit) in the routines that utilize them. These types of trace points provide a record of flow of control through the code.

iSeries Access for Windows has instrumented the procedural APIs described in this topic with Entry/Exit API trace points. When one of these procedural APIs is called, entry and exit trace points are logged to the Entry Point trace file if tracing is active. The Entry/Exit SPI trace logs internal calling sequences. The Detailed data trace function logs data which is useful in debugging problems.

iSeries Access for Windows supports the following types of traces:

Detailed (Data):

Allows you to trace a buffer of information at a point in your code via the cwbSV_LogTraceData API. This buffer can be a mixture of ASCII and/or binary values (for example, C-struct). The data is logged in binary form.

Entry/Exit (API):

A specialized form of trace which allows you to trace entry into and exit from your externalized routines via the cwbSV_LogAPIEntry and cwbSV_LogAPIExit APIs.

Entry/Exit (SPI):

A specialized form of trace that allows you to trace entry into and exit from your key internal routines by using the cwbSV_LogSPIEntry and cwbSV_LogSPIExit APIs.