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