Tracing Adapter Processing

You use the adapter trace facility to display the ADABAS Communications buffer generated by the adapter 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).

Using Traces

Each trace is associated with a trace level. Using a FOCUS SET command, you must turn on each trace level you want to generate prior to issuing the request to be traced. If you are sending the trace output to a file, you must make sure that the file is allocated to DDNAME FSTRACE prior to activating each trace.

The following trace levels are available for the Adapter for ADABAS:

Level 1 shows the flow of control between adapter modules during run time.
Level 2 shows the flow of control during the setup stage to prepare the Adabas environment for communication with the adapter.
Level 3 is a very detailed trace that shows the run-time physical calls and response codes. It 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 has been disabled. For information about turning the feature off, the Adapter for ADABAS Installation Guide.
Level 4 is a summary trace and contains Adabas statistical information. This trace is recommended because it provides useful and easy-to-read information such as the:
- Type of call issued (for example, RL or FIND.
- Key field used in the search buffer (if applicable).
- Information about the Fetch feature.
- Database ID and buffer lengths.

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.

Activating, Deactivating, and Querying Traces

How to:

Each trace is assigned a level and must be associated with a component name. For the Adapter for ADABAS, the component name is ADBSIN.

Prior to activating a trace, you must issue the SET TRACEUSER=ON command. You can issue this request at the command level, in a FOCEXEC, or in any supported profile.

Top of page

Syntax: How to Enable or Disable Trace Activation

SET TRACEUSER = {ON|OFF}

where:

ON: Must be issued prior to activating any trace.

OFF: Prevents trace activation.

Top of page

Syntax: How to Activate Adapter for ADABAS Traces

You can activate mulitple trace levels or one specific trace level with the SET TRACEON command. You can issue this request at the command level, in a FOCEXEC, or in any supported profile. You must issue this command prior to running the request for which you want the trace generated. The syntax is

SET TRACEON = ADBSIN /[level]/{CLIENT|FSTRACE}

where:

ADBSIN: Indicates that the command applies to traces for the Adapter for ADABAS.
level: Is an integer that identifies the trace level to activate. Valid values are 1, 2, 3, and 4. If omitted, all trace levels are activated.
CLIENT: Sends trace output to the screen.
FSTRACE: Sends trace output to data set allocated to DDNAME FSTRACE.

Top of page

Example: Activating the Adapter for ADABAS Trace Facility

The following command turns on traces for all levels of the ADBSIN component and sends them to the terminal:

SET TRACEON = ADBSIN //CLIENT

The following example turns on the level 2 trace and sends it to the file allocated to DDNAME FSTRACE:

SET TRACEON = ADBSIN/2/FSTRACE

Top of page

Syntax: How to Control Trace Timestamps

By default, a timestamp is prepended to each line of trace output. You can turn off the trace timestamps using the SET TRACESTAMP command.

SET TRACESTAMP = {ON|OFF|TLEFT}

where:

ON: Prepends a timestamp to each line of trace output.
OFF: Omits the timestamp from the trace output.
TLEFT: Prepends a timestamp to each line of trace output. Includes microseconds in the timestamp.

Top of page

Syntax: How to Deactivate Adapter for ADABAS Traces

You can deactivate all trace levels or one specific trace level with the SET TRACEOFF command. The syntax is

SET TRACEOFF = {ADBSIN|ALL}  [/level]

where:

ADBSIN: Indicates that the command applies to traces for the Adapter for ADABAS.
ALL: Deactivates all traces.
level: Deactivates the specified trace level.

Top of page

Example: Deactivating Adapter for ADABAS Traces

The following command turns off trace level 1 for the Adapter for ADABAS:

SET TRACEOFF = ADBSIN/1

The following command turns off all traces for the Adapter for ADBSIN:

SET TRACEOFF = ADBSIN

The following command turns off all traces:

SET TRACEOFF = ALL

Top of page

Syntax: How to Query Traces

The trace query commands tell you which trace levels are either activated or deactivated for every component. Be aware that these commands may show information that does not pertain to ADABAS.

To list all of the trace level/component combinations currently active, issue the following command:

SET TRACEON = ?

To list all of the trace level/component combinations not currently active, issue the following command:

SET TRACEOFF = ?

Note: Be aware that this command may produce a voluminous display listing information about components in which you have no interest.

Top of page

Example: Querying Traces

SET TRACEON = ADBSIN

>  > SET TRACEON = ?

>  > set traceon = ?                                                       
(FOC1180) Name     Level DDName   Description          Set  Filedef  Active
(FOC1180) ADBSIN    1    FSTRACE  ADBSINX Run Time Ca  Y    Y        Y     
(FOC1180) ADBSIN    2    FSTRACE5 ADBSINX Setup    Ca  Y    Y        Y     
(FOC1180) ADBSIN    3    FSTRACE  ADBSINX RunTime Ph   Y    Y        Y     
(FOC1180) ADBSIN    4    FSTRACE4 ADBSINX DB Specific  Y    Y        Y     
>  >

Allocating Traces

How to:

You can activate all or any combination of traces during your session or in batch. You can display the results online or store them in a file or sequential data set.

Tip: The trace facilities are intended for use in query optimization and problem debugging. Application programs should not be written to depend on the format or content of any trace, as they may change in later releases.

Top of page

Syntax: How to Allocate a Trace Online

You can store trace information in a z/OS sequential data set, or you can display it online at the terminal. To capture trace data in a file, issue the appropriate allocation command for DDNAME FSTRACE from the command level. To display the trace on the terminal, no allocation is necessary.

For example, to allocate DDNAME FSTRACE, issue one of the following commands:

{MVS|TSO} ALLOC F(FSTRACE) DA('userid.FSTRACE.DATA') SHR REU

DYNAM ALLOC DD FSTRACE DATASET userid.FSTRACE.DATA SHR REUSE

Note: DCB attributes are LRECL=80 and RECFM=F.

To view the trace information, use the system editor or the FOCUS TED editor.

Top of page

Syntax: How to Allocate a Trace in Batch

You can write trace results to SYSOUT. BLKSIZE information is optional, but should be compatible with other FSTRACE formats. For example, to allocate DDNAME FSTRACE:

//FSTRACE   DD   SYSOUT=*,DCB=(LRECL=80,BLKSIZE=80,RECFM=F)
//ALLOC    EXEC PGM=IEFBR14
//FSTRACE  DD   DISP=(,CATLG),DSN=userid.FSTRACE,
//         UNIT=SYSDA,VOL=SER=USERM1,SPACE=(TRK,(5,5)),
//         DCB=(LRECL=80,BLKSIZE=80,RECFM=F)
                      .
                      .
                      .
                      .
                      .
                      .

Then, allocate the trace data set with DISP=MOD in the batch FOCUS JCL:

                      .
                      .
                      .
//FOCBATCH EXEC PGM=FOCUS
//FSTRACE  DD   DISP=(MOD,KEEP,KEEP),DSN=userid.FSTRACE

Top of page

Syntax: How to Free Trace Allocations

To disable an adapter trace, clear the associated allocation

{MVS|TSO} FREE F(FSTRACE)

DYNAM FREE FILE FSTRACE

Sample Traces

This topic contains sample traces.

The following report request produces the report shown and is used to generate the traces illustrated in the following sections.

SET TRACEON = ADBSIN//CLIENT
TABLE FILE EMPFILE1
PRINT NAME CITY
WHERE CITY EQ 'NEW YORK'
END
PAGE     1                    
                             
NAME                  CITY    
----                  ----    
RUBIN                 NEW YORK
WALLACE               NEW YORK

Top of page

Example: ADABAS Level 1 Trace

This trace shows the run time flow of control.

  *** TRACE START ***
 Calling addbop
  Data base OPEN mode is ON
   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 a1b2bf4
   accmod for sgx 1 is 4
   Calling adgtrlscr on sgx 1
     bufoff for sgx 1 is 0
     buffer for sgx 1 for RDE is a1e4220 , for data is a1e42e0
     GNTINT buffer for sgx 1 is 9b24000
 Called adgtseg for sgx 1 rc 0 data 1
 Calling adgtseg for sgx 1
   padaccx for sgx 1 is a1b2bf4
   accmod for sgx 1 is 4
   Calling adgtrlscr on sgx 1
     bufoff for sgx 1 is 0
    buffer for sgx 1 for RDE is a1e4234 , for data is a1e4308
     GNTINT buffer for sgx 1 is 9b24000
 Called adgtseg for sgx 1 rc 0 data 1
 Calling adgtseg for sgx 1
   padaccx for sgx 1 is a1b2bf4
   accmod for sgx 1 is 4
   Calling adgtrlscr on sgx 1
     bufoff for sgx 1 is 0
    buffer for sgx 1 for RDE is a1e4244 , for data is a1e4330
     GNTINT buffer for sgx 1 is 9b24000
 Called adgtseg for sgx 1 rc 0 data 0

The output of the request is:

  

  
Top of page
  

  
Example: ADABAS Level 2 TraceThis
trace tracks the flow of control in the Adapter for ADABAS.
This
trace is used infrequently. Information Builders 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
  

  
Top of page
  

  
Example: ADABAS Level 3 TraceThis
trace shows you exactly what is being passed in the ADABAS buffers.
The following trace is for ADABAS Release 5. The Release 6 trace
looks slightly different (for example, it allows for a two-digit
database number) but contains the same information.
*** 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   00000    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,
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:
The CMD field shows the
command being issued. The first call in this trace is the OP (open)
call.
The RSP field shows the response code from this call. In the
example, the response code is 0.
The COP1 field indicates if the Fetch feature is in effect.
In the example, the M indicates that Multifetch is active. 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.
The FMT BUFFER shows the fields used in this request. The AE
(NAME) and AJ (CITY) fields are requested.
The VAL BUFFER shows the value being searched (NEW YORK).The
SRCH BUFFER shows the ADABAS field used for the search (AJ).The
RCD BUFFER shows the records returned to the ADABAS Interface from
the ADABAS database.
  

  
Top of page
  

  
Example: ADABAS Level 4 TraceThis
trace shows a summary view of ADABAS calls. It is easier to read
than the level 3 trace and provides statistical information.
 data base OPEN mode is ON
 access mode for sgx 1 is 4 (RL SCREEN)  
format bufferlen 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