Formatting the binary trace file

If you are using memory mapped tracing, note that data is not always written to disk immediately. As a consequence, turn tracing off before you format the binary trace file, to ensure that all data is flushed to disk.

You use the Binary Trace Formatter utility cicsftrc to convert the binary trace file cicscli.bin to ASCII text. The utility has the following parameters:
-m=list of components
Specifies that only trace points from the listed components are written to the text file. The components you can specify are the same as for cicscli -m; see the cicscli -m command. If -m is not specified, all trace points in the binary trace are written to the text file.
-w[=filename]
Indicates that there are two or more binary trace files to format and then concatenate (that is, the binary files were created with a wrapping trace). If no file name is specified with the -w parameter, cicsftrc assumes that the name of the second trace file is cicscli.wrp.
-n
Indents entry and exit points in the test trace file to make it more readable. By default, indentation is turned off.
-d
Specifies detailed trace formatting. If you are using EPI calls, cicsterm or CICSPRINT, an approximation of the screen layout will be included in the trace.
-i=filename
Specifies the name of the input (binary) trace file, which is cicscli.bin by default.
-o=filename
Specifies the name of the output (text) trace file. If no -o parameter is specified, the name of the text trace file is assumed to be cicscli.trc.
-f
Overwrite any existing files.
-s
Do summary trace formatting. Summary trace formatting is controlled by a template file (cclsumtr.txt), which is read in at initialization time. It formats key trace points, and shows for example the flow of user API calls, the progress of calls through the Client daemon, and network flows to the server. For the most detailed results, specify the API.2 component when you define the components to be traced. Summary tracing provides an overview; use it as requested by your IBM® support organization.
Note: Versions of the CICS® Universal Client earlier than 5.0.1 cannot format binary trace files produced by this version.
Figure 1 shows an example summary trace.
Figure 1. Sample of API summary trace taken with API.2 and DRV options
        -->Sample of API summary trace taken with API.2 and DRV options.
        
[Process ,Thread  ]     Time       API Summary                   CCLCLNT Summary               Comms Summary 
=============================================================================================================
...
...
...
[000000bf,0000017c] 12:08:32.190 --->[7315] CCL3310 ECI Call type ECI_SYNC, UOW=0
[00000089,000000a4] 12:08:32.290                                              -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=89
[00000089,00000063] 12:08:32.400                                              <-R-[4418] CCL4412 TCP/IP (to STEMPLAR) receive data: Length=12
[00000089,0000018b] 12:08:32.511                                              <-R-[4418] CCL4412 TCP/IP (to STEMPLAR) receive data: Length=29
[00000089,000000a4] 12:08:32.521                                              -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,000000a4] 12:08:32.531                                              -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,000000a4] 12:08:32.541                                              -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,000000a4] 12:08:32.541                                              -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,000000a4] 12:08:32.551                                              -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,00000168] 12:08:32.581                                              <-R-[4418] CCL4412 TCP/IP (to STEMPLAR) receive data: Length=12
[00000089,0000017e] 12:08:32.601                                              <-R-[4418] CCL4412 TCP/IP (to STEMPLAR) receive data: Length=31
[000000bf,0000018e] 12:08:32.621     [7364] CCL3350   Event Service Thread got a request REQUEST_TYPE_ECI_1
[000000bf,0000008a] 12:08:32.671 <---[7316] CCL3311 ECI Call type ECI_SYNC, UOW=0 got rc=ECI_NO_ERROR {Time in API = 0.821 seconds}
Points to note:
  1. {Time in API} shows the amount of time that the client API call took to complete. This can help when investigating performance problems; see Performance for more information.
  2. The API Summary column refers to client API code inside the user application process. It tracks when user requests enter and leave the client API code. ---> and <--- show the program entering and leaving the Client daemon API.
  3. CCLCLNT is the background Client daemon process. You get entries here only if you specify the CCL component.
  4. The Comms Summary tracks when Client daemon calls enter and leave the network. -S-> shows a request being sent to the network; <-R- shows a reply being received.
If a user application is making EPI calls, or using cicsterm or cicsprnt, the trace formatter puts an approximation of the screen into the trace. Figure 2 shows a 3270 screen capture from a formatted trace file, taken from the CECI transaction. It is an aid to problem determination, not a completely accurate representation of the screen. See Formatting the binary trace file for details of how to format the trace file.
Figure 2. Screen capture from a formatted trace file
Command = Erase/Write, so clearing main screen
 Command2 = Read Modified
 WCC = 0x32 ( Free Kbd,80 char)
 Set Buffer Address to (1,2)
 Insert Cursor @ (1,2)
 Set Buffer Address to (1,1)
 Start Field Extended (Unprotected,Alphanumeric,Display,not-pen-detectable,Foreground Colour Green)
 Data : ' '
 Insert Cursor @ (1,3)
 Set Buffer Address to (2,1)
  Data : 'User        '
  .....
  .....
  .....
  .....
 Set Buffer Address to (24,49)
 Start Field Extended (Autoskip (Prot+Num),Display,not-pen-detectable,Foreground Colour Turquoise)
 Data : '9'
 Set Buffer Address to (24,51)
 Start Field Extended (Unprotected,Alphanumeric,Intense,pen-detectable,Foreground Colour Red)
 Data : 'Messages    '
             1         2         3         4         5         6         7         8
    12345678901234567890123456789012345678901234567890123456789012345678901234567890
 >+----------------------------------------------------------------------------------+
01| -                                                                                |
02| ´STATUS. . :´Enter one of the following:                                         |
03|     ´                                                                            |
04| ´ABend       EXtract     READPrev    WAit                                        |
05| ´ADdress     FEpi        READQ       WRITE                                       |
06| ´ALlocate    FOrmattime  RECeive     WRITEQ                                      |
07| ´ASKtime     FREE        RELease     Xctl                                        |
08| ´ASSign      FREEMain    RESetbr                                                 |
09| ´Bif         Getmain     RETRieve                                                |
10| ´CAncel      Handle      RETUrn                                                  |
11| ´CHange      IGnore      REWrite                                                 |
12| ´CONNect     INquire     SENd                                                    |
13| ´CONVerse    ISsue       SET                                                     |
14| ´DELAy       LInk        SIGNOFf                                                 |
15| ´DELETE      LOad        SIGNON                                                  |
16| ´DELETEQ     PErform     START                                                   |
17| ´DEQ         POP         STARTBr                                                 |
18| ´DUmp        POSt        SUspend                                                 |
19| ´ENDbr       PUsh        SYncpoint                                               |
20| ´ENQ         READ        Unlock                                                  |
21| ´ENTer       READNext    Verify                                                  |
22|     ´                                                                            |
23| ´PF´1-Help        ´2-HEX         ´3-End         ´4-EIB         ´5-Variables      |
24|    ´6-User                                      ´9-Messages                      |
  +----------------------------------------------------------------------------------+
  | 1BþC000                   STEMPLAR                                               |
  +----------------------------------------------------------------------------------+
    12345678901234567890123456789012345678901234567890123456789012345678901234567890
             1         2         3         4         5         6         7         8
The formatter lists the commands which built the screen, and shows an approximation of the screen.