Using the APPC/MVS API trace facility, your installation can collect data about APPC/MVS and CPI-C calls that an APPC/MVS TP issues.  With this data, your installation can diagnose not only errors that occur during a specific call, but also problems with the conversation flow between the TP and its partners.  The trace facility writes all trace data to a pre-defined trace dataset.

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.

Creating the APPC/MVS API Trace Dataset

The results of the API trace are written to the specified dataset.  This dataset will remain in exclusive use by the APPC started task until all traces specifying the dataset have been stopped.  The contents of the dataset are overwritten every time a new trace is started.  A condition known as "wrapping" may also occur if the dataset is not defined with enough primary space to contain all possible trace data - no secondary extents will be allocated by the trace dataset!

The dataset should be defined with the following attributes:

 SPACE=(CYL,(20,0),RLSE),
 DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=0

Invoking the APPC/MVS API Trace Facility

The simplest way to invoke the APPC/MVS API Trace facility is to call the ATBTRACE Rexx routine.  The following example calls the Trace invocation utility via a TSO Batch interface:

//****************************************************************************
//** INVOKE APPC API TRACING VIA TSO BATCH:                                 **
//****************************************************************************
//TRACE    EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSEXEC  DD   DSN=SYS1.SBLSCLI0,DISP=SHR
//SYSTSPRT DD   SYSOUT=*
//SYSTSIN  DD   *
    %ATBTRACE
/*

Specifying APPC/MVS API Trace Parameters

Use the following syntax diagram and parameter descriptions to code an ATBTRACE request to start tracing a conversation.  Remember that, depending on the TPs involved in the conversation you want to trace, you might have to issue more than one ATBTRACE request or also invoke a trace facility on an operating system other than MVS.

 
>>--ATBTRACE--START--DATASET--(--ds_name--)------------------------------>
 
>----LU--(--lu_name--)--TP--(--tp_name--)-------------------------------->
 
>-----------------------------------------------------------------------><
   +-------------------------------¦
   ¦ ¦            +-*-------+    ¦ ¦
   ¦ +-USERID--(----user_id----)-+ ¦
   +-SECNONE-----------------------+

START

Specifies that API tracing is to start for the conversation identified by the other parameters on the START request. APPC/MVS traces only those conversations established after it successfully processes the START request, when the inbound or outbound call to establish the conversation explicitly or implicitly uses values for LU and TP (and possibly user ID) that exactly match those specified on the START request.

DATASET(ds_name)

Specifies the data set that is to contain the trace data for the conversations to be traced. You may use the abbreviations DA, DSNAME, DSN, or DS instead of DATASET.  ds_name can be either the fully qualified or unqualified name of a pre-allocated, sequential data set. A fully qualified name must be specified within single quotes. When the data set name is specified without quotes, APPC/MVS adds a high-level qualifier, the user ID of the ATBTRACE invoker, to the data set name.

LU(lu_name) TP(tp_name)

Specifies the LU and TP combination that APPC/MVS is to trace. When both of the following conditions are true, APPC/MVS collects trace data for the conversation:

• The LU keyword value matches the partner LU value passed (explicitly or through a symbolic destination name) on the APPC/MVS Allocate, Register_for_Allocates, or CPI-C Set_Partner_LU_Name service.

• The TP keyword value matches the partner TP value passed (explicitly or through a symbolic destination name) on the APPC/MVS Allocate, Register_for_Allocates, or CPI-C Set_TP_Name service.

• A network-qualified LU name, in the form network_id.network_LU_name, in which network_id is the 8-byte ID of the network, and network_LU_name is the 8-byte local LU name
• An 8-byte local LU name
• A VTAM generic resource name.

 tp_name is a 64-byte character field containing the name of a standard TP, a multi-trans TP, a TP registered for test or a served TP. TP_name must exactly match the name specified on Allocate requests, including case. TP_name cannot be an SNA service TP name; APPC/MVS does not support tracing of SNA service TPs.
 
USERID(*|user_id)

Specifies an additional filter to limit the conversations traced for a specific LU and TP combination. You may use the abbreviations USER or U instead of USERID. Use this keyword if you want to collect trace data for inbound and outbound conversations established only by a particular user, for this LU/TP combination.

user_id is a 10-byte character field containing the user ID to be used as a filter. APPC/MVS traces the conversation only when the value for USERID matches the value of the User_id parameter specified on the Allocate service. If the conversations you want to trace might be allocated without any user ID, start the trace using the SECNONE keyword instead of USERID.
 
The USERID and SECNONE keywords are both optional, and are mutually exclusive. If you do not specify either USERID or SECNONE, APPC/MVS uses the default value for USERID, '*', which means that all conversations established for the LU/TP combination are traced, even conversations with a Security_type of security_none.

SECNONE

Specifies that APPC/MVS is to trace only conversations allocated without a user ID specified, for this LU and TP combination. When either of the following conditions is true, APPC/MVS collects trace data for the conversation:

• A Security_type of security_none is specified on the Allocate service
• A Security_type of security_same or security_pgm is specified on the Allocate service, but VTAM downgraded the conversation to security_none.

The USERID and SECNONE keywords are both optional, and are mutually exclusive. If you do not specify either USERID or SECNONE, APPC/MVS uses the default value for USERID, '*', which means that all conversations established for the LU/TP combination are traced, even conversations with a Security_type of security_none.
 
Sample JCL to start an APPC/MVS API Trace - Specific User

The following example starts an API trace for a TP called C3MVSIOF, for conversations that are accepted by or initiated from LU APPCPLU or LU APPCRLU, and are started by UserID THLUCAS.  The results of the trace are written to dataset YOURHLQ.APPC.API.TRACE.

//****************************************************************************
//** INVOKE APPC API TRACING VIA TSO BATCH
//****************************************************************************
//TRACE    EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSEXEC  DD   DSN=SYS1.SBLSCLI0,DISP=SHR
//SYSTSPRT DD   SYSOUT=*
//SYSTSIN  DD   *
 %ATBTRACE START DATASET('YOURHLQ.APPC.API.TRACE') LU(APPCPLU) -
 TP(C3MVSAPI) USERID(THLUCAS)
 %ATBTRACE START DATASET('YOURHLQ.APPC.API.TRACE') LU(APPCLLU) -
 TP(C3MVSAPI) USERID(THLUCAS)
/*

Sample JCL to start an APPC/MVS API Trace - All Users

The following example starts an API trace for a TP called C3MVSIOF, for conversations that are accepted by or initiated from LU APPCPLU or LU APPCRLU, and are started by any user.  The results of the trace are written to dataset YOURHLQ.APPC.API.TRACE.

//****************************************************************************
//** INVOKE APPC API TRACING VIA TSO BATCH
//****************************************************************************
//TRACE    EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSEXEC  DD   DSN=SYS1.SBLSCLI0,DISP=SHR
//SYSTSPRT DD   SYSOUT=*
//SYSTSIN  DD   *
 %ATBTRACE START DATASET('YOURHLQ.APPC.API.TRACE') LU(APPCPLU) -
 TP(C3MVSAPI) USERID(*)
 %ATBTRACE START DATASET('YOURHLQ.APPC.API.TRACE') LU(APPCLLU) -
 TP(C3MVSAPI) USERID(*)
/*

Sample JCL to stop an APPC/MVS API Trace

The following example stops an all API trace activity that is being written to dataset YOURHLQ.APPC.API.TRACE.

//****************************************************************************
//** INVOKE APPC API TRACING VIA TSO BATCH
//****************************************************************************
//TRACE    EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSEXEC  DD   DSN=SYS1.SBLSCLI0,DISP=SHR
//SYSTSPRT DD   SYSOUT=*
//SYSTSIN  DD   *
 %ATBTRACE STOP DATASET('YOURHLQ.APPC.API.TRACE')
/*

Sample JCL to LIST all active APPC/MVS API Traces

The following example list's all active API trace activity.

//****************************************************************************
//** INVOKE APPC API TRACING VIA TSO BATCH
//****************************************************************************
//TRACE    EXEC PGM=IKJEFT01,DYNAMNBR=30,REGION=4096K
//SYSEXEC  DD   DSN=SYS1.SBLSCLI0,DISP=SHR
//SYSTSPRT DD   SYSOUT=*
//SYSTSIN  DD   *
 %ATBTRACE LIST
/*