Trace file format for API tracing

The trace data for a single message can occupy more than one line in the trace file. Each individual message is preceded by a horizontal line indicating the time the trace entry was made. The following describes a CS Linux API trace file:

  • The process ID of the component being traced appears at the start of each line. After the process id is the thread id (separated by a period). For a single-threaded application, this will always be 00. The process ID is followed by an indicator of the component type being traced (for example, APPC, for an APPC TP).
  • Message data is shown in the following formats in separate columns to ensure that a character string in the message data appears as readable text in either the EBCDIC or the ASCII column, according to its character set:
    • Hexadecimal
    • Interpreted as EBCDIC
    • Interpreted as ASCII

The format of trace data varies slightly among the APIs:

APPC, NOF, MS
The verb control block supplied by the application to the corresponding API library is traced when the verb is issued and when it returns. For verbs issued through the asynchronous entry point and for the APPC [MC_]RECEIVE_AND_POST verb issued using the synchronous entry point, both the initial return (indicating that the verb was issued successfully and is in progress) and the return to the callback routine (when the verb completes) are traced.

The top of each section of tracing shows the name of the verb issued and the result on its return (taken from the primary return code). Any data being sent or returned is also traced following the verb control block (VCB), with the address at which the data is stored (taken from the verb control block).

If an MS or NOF application has registered to receive indications, each indication is also traced in a format similar to an asynchronous verb return.

For information about the VCB structures and content for each of these APIs, refer to the IBM Communications Server for Data Center Deployment on AIX or Linux APPC Programmer's Guide, IBM Communications Server for Data Center Deployment on Linux NOF Programmer's Guide, and IBM Communications Server for Data Center Deployment on AIX or Linux MS Programmer's Guide.

CSV
The verb control block supplied to the CSV library is traced when the verb is issued and when it returns. The top of each section of tracing shows the name of the verb issued and the result on its return (taken from the primary return code). Any data string included in a verb is also traced following the verb control block with the address at which the data is stored (taken from the verb control block).

For more information, refer to the IBM Communications Server for Data Center Deployment on AIX or Linux CSV Programmer's Guide.

LUA
The verb control block supplied to the LUA library is traced when the verb is issued and again when it returns.

If the verb returns asynchronously (the lua_flag2.async bit is set to 1 and the primary return code is set to LUA_IN_PROGRESS), the verb control block is traced a third time when it completes. In this case, you should ignore the parameters in the initial return VCB (except for lua_flag2.async set to 1 and the primary return code set to LUA_IN_PROGRESS, which indicate that this is an asynchronous verb return) and take account only of those in the final return VCB when the verb completes. In this VCB, lua_flag2.async remains set to 1 and the primary return code is set to a value other thanLUA_IN_PROGRESS.

The top of each section of tracing shows the name of the LUA verb issued and the result on its return (taken from the primary and secondary return codes). Any data being sent or returned is also traced following the verb control block, with the address at which the data is stored (taken from the verb control block).

Because CS Linux implements the SLI using RUI verbs, the LUA library converts SLI verbs into the corresponding RUI verbs (where each SLI verb may result in one or more RUI verbs). Therefore, SLI tracing includes both SLI parameters and RUI parameters. First, the SLI request is traced, then the RUI request and return for each verb (including the later asynchronous return if applicable), and finally the SLI return.

For more information, refer to the IBM Communications Server for Data Center Deployment on AIX or Linux LUA Programmer's Guide.

CPI-C
Because CS Linux implements CPI-C using APPC, the CPI-C library converts most CPI-C calls into the corresponding APPC verbs. Therefore, CPI-C tracing includes both the CPI-C parameters and the APPC parameters. First, the CPI-C request is traced, then the APPC request, then the APPC return, and finally the CPI-C return. For other CPI-C functions that deal only with local information (such as checking or setting the receive type or the synchronization level), no APPC verbs are executed, so the tracing shows only the CPI-C parameters.

The top of each section of tracing shows the name of the CPI-C call or APPC verb issued and its return code. Any data being sent or returned is also traced following the CPI-C parameters or APPC verb control block, with the address at which the data is stored.

For more information, refer to the IBM Communications Server for Data Center Deployment on AIX or Linux CPI-C Programmer's Guide.

The following examples show fragments of API trace files from CPI-C and APPC applications:

Sample API Trace File Fragment: CPI-C
|=====================================================================
|================ Initialized 14:40:35 BST  15 Sep 1997 ==============
|=====================================================================
| 4849.00 CPIC   -------------------------------- 14:40:35.07 BST  15 Sep 1997
| 4849.00 CPIC   CMINIT request
| 4849.00 CPIC    Sym dest name =
| 4849.00 CPIC   -------------------------------- 14:40:35.08 BST  15 Sep 1997
| 4849.00 CPIC   CMINIT response, result = CM_OK
| 4849.00 CPIC    Conversation ID = 01000001
| 4849.00 CPIC   Conversation characteristics
| 4849.00 CPIC    Conversation type = CM_MAPPED_CONVERSATION
| 4849.00 CPIC    Deallocate type = CM_DEALLOCATE_SYNC_LEVEL
| 4849.00 CPIC    Error direction = CM_RECEIVE_ERROR
| 4849.00 CPIC    Sync level = CM_NONE
| 4849.00 CPIC    Fill type = CM_FILL_LL
| 4849.00 CPIC    Prepare to receive type = CM_PREP_TO_RECEIVE_SYNC_LEVEL
| 4849.00 CPIC    Receive type = CM_RECEIVE_AND_WAIT
| 4849.00 CPIC    Send type = CM_BUFFER_DATA
| 4849.00 CPIC    Conversation security type = XC_SECURITY_SAME
| 4849.00 CPIC    Log data pointer = 0
| 4849.00 CPIC    Log data length = 0
| 4849.00 CPIC    Sym dest name =
| 4849.00 CPIC    Partner LU name =
| 4849.00 CPIC     20202020 20202020 20202020 20202020     ................
| 4849.00 CPIC     20                                      .@@@@@@@@@@@@@@@
| 4849.00 CPIC    Mode name =
| 4849.00 CPIC     40404040 40404040                       @@@@@@@@@@@@@@@@
| 4849.00 CPIC    Partner TP name =
| 4849.00 CPIC     40404040 40404040 40404040 40404040     @@@@@@@@@@@@@@@@
| 4849.00 CPIC     40404040 40404040 40404040 40404040     @@@@@@@@@@@@@@@@
| 4849.00 CPIC     40404040 40404040 40404040 40404040     @@@@@@@@@@@@@@@@
| 4849.00 CPIC     40404040 40404040 40404040 40404040     @@@@@@@@@@@@@@@@
Sample API Trace Fragment: APPC
| 2511.00 APPC   -------------------------------- 14:49:08.04 BST  20 Oct 1998
| 2511.00 APPC   TP_STARTED request
| 2511.00 APPC   ---- Verb Parameter Block at address 40001578 ----
| 2511.00 APPC     00140000 00000000 00000000 54504C55     .............&<.  ............TPLU
| 2511.00 APPC     31202020 00000000 00000000 E3D7D5C1     ............TPNA  1   ............
| 2511.00 APPC     D4C5F140 40404040 40404040 40404040     ME1               ...@@@@@@@@@@@@@
| 2511.00 APPC     40404040 40404040 40404040 40404040                       @@@@@@@@@@@@@@@@
| 2511.00 APPC     40404040 40404040 40404040 40404040                       @@@@@@@@@@@@@@@@
| 2511.00 APPC     40404040 40404040 40404040 00000000                 ....  @@@@@@@@@@@@....

For the APPC, CSV, LUA, MS, and NOF APIs, you can use the API trace formatter utility snaapitrcfmt (snaapitrcfmt64 for a 64-bit Linux application) to provide a more detailed interpretation of the VCB contents. See API trace formatter for more information.