Diagnosing TP Conversation Errors with the API Trace Facility

Using the application programming interface (API) trace facility, you can collect data about APPC/MVS and CPI-C calls that an APPC/MVS TP issues. With this data, you can diagnose not only errors that occur during a specific call, but also problems with the conversation flow between the TP and its partners. This diagnostic capability reduces the amount of time and effort required to develop and service APPC applications.

Through the API trace facility, you can collect the following data for a particular TP running on a particular LU:

Parameters and values specified on calls issued for APPC/MVS and CPI-C services, and values provided on return from those calls.
The same diagnostic information that the APPC/MVS Error_Extract service provides for calls that return non-zero return codes.
Parameters and values specified on START and STOP requests for the API trace facility.
The contents of FMH-5 or FMH-7 records exchanged between conversing TPs.

This API trace data is stored in a pre-allocated data set that you specify when starting the trace. You can view the data only after all tracing activity for the data set has stopped.

To control API tracing activity, use the ATBTRACE REXX exec to start or stop tracing, or to list the status of active API traces. Through the ATBTRACE exec, you specify:

The type of trace request: START, STOP or LIST
The LU and TP combination that identifies the conversation
The pre-allocated data set for storing trace data.

You can invoke the ATBTRACE exec from TSO/E, through JCL for a TP or batch job, or from a high-level language program.

Depending on the location of the partners, you might have to start tracing activity on more than one z/OS system, or use the API trace facility together with tracing facilities provided for other operating systems, such as OS/2.

The following sections explain how to use the API trace facility:

Setting Up API Trace Data Sets describes planning topics, such as possible security requirements for trace data sets; trace data set characteristics; and how to avoid losing trace data through wrapping or resource contention.
Starting API Tracing Activity explains how to select values for the ATBTRACE START request, to ensure that APPC/MVS collects the trace data you need.
Using the ATBTRACE REXX Exec explains:
- The methods of invoking the ATBTRACE REXX exec, including programming considerations and output
- The syntax diagrams and parameter descriptions for each type of ATBTRACE request.
Interpreting API Trace Data contains general descriptions and examples of trace data set entries, an d provides suggestions for sorting and reading the entries.