Diagnosing Problems with APPC/MVS TPs

Several tools are available to help you diagnose problems related to APPC/MVS transaction programs (TPs). Like the great detectives of fiction, each tool has its own specialty. Just as Sir Arthur Conan Doyle's Sherlock Holmes collects details from the scene of the crime, so APPC component trace collects information about the environment in which APPC/MVS TPs run. In contrast, Agatha Christie's Hercule Poirot relies on conversing with each suspect to uncover facts, as the application programming interface (API) trace facility does by collecting details about conversation calls that an APPC/MVS TP issues.

While you might hire your favorite fictional detective to solve any mystery, you achieve better results if you select a diagnostic tool based on the problem symptoms, rather than using the same tool for all errors. In some cases, you might need a combination of tools to ensure that you are collecting the most pertinent diagnostic information. For example, if you are testing an APPC/MVS TP that converses with a TP on OS/2, you might need to use both the API trace facility and OS/2's tracing facility to debug problems with the conversation flow.

You also might use one or more tools even when an error has not occurred. Again, in a test environment, you could use the TP message log and the API trace facility to collect data each time the TP runs. If errors occur during the TP's processing, you already have the diagnostic data you need to debug the errors; if the TP successfully finishes its processing, you already have the data you need to verify its success.

In most cases, the API tracing facility can provide you with the diagnostic data you need. Additionally, it has the advantage of being relatively easy to start and stop. However, because it might not be the most appropriate tool in all cases, use Table 1 to help you select which tool is best suited to the error conditions you observe, or might expect to encounter, for an APPC/MVS TP.

Table 1. Selecting a Diagnostic Tool
When the symptoms are:	The usual suspects are:	The detective of choice is:
Non-zero return code from an APPC/MVS or CPI-C service call	Unknown parameters passed on the service call Incorrect parameter values passed on the call Incorrect conversation state for issuing the call to the service Conditions that prevent the successful completion of the service call	API trace facility, or Error_Extract service
Return code for product-specific error	Incorrect version of service call for the system on which the TP is running APPC/MVS is not active, or has encountered an internal error Various environmental errors, which can include security checking, caller authorization, APPC/MVS configuration errors, and so on	API trace facility, Error_Extract service, or the symptom record for the error
Unexpected results or non-zero return codes for TP processing Unexpected DISPLAY command results about the status of the TP or its partners TP or its partner seems to be hanging Abnormal end of the TP	Incorrect sequence of calls between partner TPs Incorrect TP design Incorrect parameter syntax Incorrect conversation state	API trace facility
Unexpected results or non-zero return codes for TP processing Problems related to the allocation of resources on behalf of the TP Abnormal end of the TP	Non-zero return codes from MVS macros or callable services Incorrect TP profile or side information contents	TP message log
Error messages or unexpected DISPLAY command results about the status of the APPC/MVS configuration	Status of the LU, scheduler, or server for the TP System errors or environmental conditions that affect the processing of APPC/MVS	IPCS APPCDATA or ASCHDATA subcommands, or APPC/MVS component trace

As application programmers designing and coding APPC/MVS TPs, your primary diagnostic tools are the API trace facility, Error_Extract, and the TP message log, which are described in this chapter, along with descriptions of symptom record contents for product-specific errors. The API trace facility and TP message logs require some installation set-up, which is usually performed by system programmers; z/OS MVS Planning: APPC/MVS Management contains this set-up information. Information about other diagnostic tools appears elsewhere:

For this tool:	Information appears in:
APPCDATA and ASCHDATA subcommands	z/OS MVS Diagnosis: Reference
APPC/MVS component trace	z/OS MVS Diagnosis: Tools and Service Aids