Using Traces

You use the ADABAS Interface trace facility to display the ADABAS Communications buffer generated by the Interface for each call made to ADABAS. This feature is useful for debugging purposes and performance monitoring. It enables you and the database administrator to track ADABAS resource usage from FOCUS. The ADABAS Format, Search, and Value buffers are also displayed when a specific ADABAS call requires one or more of them (refer to your Software AG documentation for more information on buffers).

The following trace options are available for the ADABAS Interface:

• FSTRACE is a very detailed trace that allows you to see exactly what is being passed in the ADABAS buffers. For example, if the Fetch feature is being used, a P displays under the COP1 column if Prefetch is active, or an M appears in that column if Multifetch is active. The COP1 field will be blank if the Fetch feature is not being used.
• FSTRACE4 is a summary trace with ADABAS statistical information. It displays the type of call issued (for example, RL or FIND), the key field used in the search buffer (if applicable), and information about the Fetch feature. The trace options provide this information:
• Number of I/O operations.
• Number of commands issued.
• Amount of CPU time in seconds.

• FSTRACE5 is a trace used to show the flow of control in the Interface.

All trace information is returned after the ADABAS CLOSE call is issued. To generate this information, you must specify OPEN=YES in the Access File.

The following report request uses the EMPLOYEES Master and Access Files. These files are shown in Sample File Descriptions. The request produces the report shown. This request generates the FSTRACE illustrated in Figure 9-1. FSTRACE9-1, the FSTRACE4 illustrated in Figure 9-2. FSTRACE49-2, and the FSTRACE5 illustrated in Figure 9-3. FSTRACE59-3.

TABLE FILE EMPFILE1
PRINT NAME CITY
WHERE CITY EQ 'NEW YORK'
END

NAME          CITY
----          ----
RUBIN         NEW YORK
WALLACE       NEW YORK

                                END OF REPORT

The same report request generates the following trace:

*** TRACE START ***=================================================
1. HID CMD    CID    FNR    RSP  ISN  ISL   ISQ  FBL  RBL  SBL  VBL  IBL
    A   OP   0000   000000    0    0    0    0    0    8    0    0    0
   COP1 COP2 ADD1     ADD2 ADD3     ADD4     CMDT        UA
             ********      ********           159700304 0
   RCD BUFFER: 8
  C1C3C37E F0F0F14B *ACC=001.        *
2. HID CMD    CID    FNR    RSP  ISN  ISL   ISQ  FBL  RBL  SBL  VBL  IBL
    A   OP   0000   000000    0    0 67108864 100729600    0    8    0    0
   COP1 COP2 ADD1     ADD2 ADD3     ADD4     CMDT        UA
             ********      ********       /'  159700304 e
   =================================================
   HID CMD    CID    FNR    RSP  ISN  ISL   ISQ  FBL  RBL  SBL  VBL  IBL
        L3   0001   000001    0    0   10    0    6  400    3   20  164
3. COP1 COP2 ADD1     ADD2 ADD3     ADD4     CMDT        UA
     M   V   AJ            ********           159702136 0
4. FMT BUFFER: 6
  AE,AJ.
5. VAL BUFFER: 20
  D5C5E640 E8D6D9D2 40404040 40404040      *NEW YORK        *
  40404040                                 *                *
6. SRCH BUFFER: 3
  AJ.
   HID CMD    CID    FNR    RSP  ISN  ISL   ISQ  FBL  RBL  SBL  VBL  IBL
        L3   0001   000001    0  563   10    0    6  400    3   20  164
   COP1 COP2 ADD1     ADD2 ADD3     ADD4     CMDT        UA
     M   V   AJ]è          ********       /'  159702136 e6 
7. RCD BUFFER: 400
  D9E4C2C9 D5404040 40404040 40404040      *RUBIN           *
  40404040 D5C5E640 E8D6D9D2 40404040      *    NEW YORK    *
  40404040 40404040 E6C1D3D3 C1C3C540      *        WALLACE *
                                   .
                                   .
                                   .

The first section (Item 1) displays commands sent to the ADABAS database. The second section (Item 2) is the ADABAS response.

Certain fields in a trace are particularly helpful in debugging; in the sample trace in Figure 9-1. FSTRACE9-1, those fields appear in boldface type. To understand the entire trace, please check your Software AG documentation to interpret the information in the buffers.

The following items provide a sample of the information you need to check:

1. The CMD field shows the command being issued. The first call in this trace is the OP (open) call.

2. The RSP field shows the response code from this call. In the example, the response code is 0.

3. The COP1 field indicates if the Fetch feature is in effect. In the example, the M indicates that Multifetch is active.

4. The COP2 field indicates if a starting value is used with the L3 (Read Logical) command. In the example, the V indicates that a starting value is in use.

5. The FMT BUFFER shows the fields used in this request. The AE (NAME) and AJ (CITY) fields are requested.

6. The VAL BUFFER shows the value being searched (NEW YORK).

7. The SRCH BUFFER shows the ADABAS name used for the search (AJ).

8. The RCD BUFFER shows the records returned to the ADABAS Interface from the ADABAS database.

FSTRACE4 shows an abbreviated version of this information using the RL call.

 data base OPEN mode is ON
 access mode for sgx 1 is 4 (RL SCREEN) 
 format buffer len is 6
AE,AJ.
 search buffer len is 3
AJ.
 value buffer len is 20
 record buffer len is 40
 using FETCH technique is ALLOWED
 used FETCH technique is  MULTIFETCH
 number of records per FETCH buffer is 10
 FETCH buffer (ISN buffer) size is     164 
 FETCH buffer (RB buffer) size is      400

ADABAS statistics for DBNO 0
 Number of I/O operations  : 7
 Number of commands issued : 3
 Amount of CPU time in sec : 0

FSTRACE5 tracks the flow of control in the ADABAS Interface for the same report request. This trace is used infrequently. IBI will request this trace only when necessary.

 Start scanning the list of "base" files.
 Opened AFD EMPFILE1 FOCADBS
   Record type 0000 read ...
   Record type 0000 read ...
   Record type 0001 read ...
   Record type 0000 read ...
   Record type 0002 read ...
     Describing segment S01      ; llevel index 1
   Record type 0003 read ...(6 repetitions of this line follow)
   Record type 0000 read ...
   Record type 0002 read ...(4 repetitions of this line follow)
 Closed AFD EMPFILE1 FOCADBS
 All segs are done
  *** TRACE START ***adaccx db 0
 Adding db 0 to addb
 adaccx fl 1
 Adding fl 1 to addb
 naddb 1
 addbfetch db 0 file 1 fetch_active M
 addbfetch fetch_size 10 IB_size 164 RB_size 400
 Calling adgtseg for sgx 1
 padaccx for sgx 1 is 984dbfc
 accmod for sgx 1 is 4
 Calling adgtrlscr on sgx 1
 bufoff for sgx 1 is 0
 buffer for sgx 1 for RDE is 9865010 , for data is 98650d0
 GNTINT buffer for sgx 1 is 925e000
 Called adgtseg for sgx 1 rc 0 data 1
 Calling adgtseg for sgx 1
 padaccx for sgx 1 is 984dbfc
 accmod for sgx 1 is 4
 Calling adgtrlscr on sgx 1
 bufoff for sgx 1 is 0
 buffer for sgx 1 for RDE is 9865024 , for data is 98650f8
 GNTINT buffer for sgx 1 is 925e000
 Called adgtseg for sgx 1 rc 0 data 1
 Calling adgtseg for sgx 1
 padaccx for sgx 1 is 984dbfc
 accmod for sgx 1 is 4
 Calling adgtrlscr on sgx 1
 bufoff for sgx 1 is 0
 buffer for sgx 1 for RDE is 9865034 , for data is 9865120
 GNTINT buffer for sgx 1 is 925e000
 Called adgtseg for sgx 1 rc 0 data 0

Invoking the Trace Facility

To invoke the trace facility, you must ALLOCATE (in MVS) or FILEDEF (in CMS) the ddname FSTRACE, FSTRACE4, or FSTRACE5 to the terminal or to a file with a logical record length (LRECL) of 80 bytes and a record format (RECFM) of F, FB, or V.

To allocate FSTRACE, FSTRACE4, or FSTRACE5 to the terminal, issue the following command within FOCUS:

In TSO:	DYNAM ALLOC FILE {FSTRACE|FSTRACE4|FSTRACE5} DA *
In CMS:	CMS FILEDEF {FSTRACE|FSTRACE4|FSTRACE5} TERMINAL

To assign the output to a file, issue the following command:

In TSO:	DYNAM FILE {FSTRACE|FSTRACE4|FSTRACE5} DA datasetname - SPACE 5,1 CYLINDERS LRECL 80 RECFM FB - BLKSIZE 1600 CATLG UNIT SYSDA
In CMS:	CMS FILEDEF {FSTRACE|FSTRACE4|FSTRACE5} DISK filename filetype filemode RECFM V LRECL 80 DISP MOD

For information about JCL for batch access, see Debugging Techniques.

Turning Off the Trace Facility

To turn off the trace facility, issue the following command:

In TSO:	DYNAM FREE FILE {FSTRACE|FSTRACE4|FSTRACE5}
In CMS:	CMS FILEDEF {FSTRACE|FSTRACE4|FSTRACE5} CLEAR