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--)-+--------------------->
   '-SYMDEST--(--sym_dest_name--)---------'   

>--+---------------------------+-------------------------------><
   |            .-*-------.    |   
   +-USERID--(--+-user_id-+--)-+   
   '-SECNONE-------------------'   

Parameters

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.

When ATBTRACE is invoked in MVS batch mode, you must specify a fully qualified data set name; otherwise, APPC/MVS rejects the ATBTRACE request.

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.

lu_name is a 17-character field containing one of the following:

• 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.

The LU and TP keyword combination is mutually exclusive with the SYMDEST keyword. You must specify either the SYMDEST keyword or the LU and TP keyword combination to start tracing.

SYMDEST(sym_dest_name)

Specifies, through a symbolic destination name, the LU and TP combination that APPC/MVS is to trace. When either of the following conditions are true, APPC/MVS collects trace data for the conversation:

• The SYMDEST keyword value matches the value for the Sym_dest_name parameter passed on the APPC/MVS Allocate, Register_for_Allocates, or CPI-C Initialize_Conversation service.
• The specific LU and TP names in the side information entry (identified through sym_dest_name) match the values for the Partner_LU and TP_name parameters passed on the APPC/MVS Allocate or Register_for_Allocates service, or the CPI-C Set_Partner_LU and Set_TP_Name services.

sym_dest_name is an 8-byte character field containing the symbolic name of the destination LU and partner TP.

This keyword is mutually exclusive with the LU and TP keyword combination. You must specify either the SYMDEST keyword or the LU and TP keyword combination to start tracing.

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.