OS/2 Shareware BBS: 14 Text/14-Text.zip/DBMTRA.ZIP/DBMTRACE.INF

OS/2 Help File | 1991-07-02 | 18KB | 689 lines

ΓòÉΓòÉΓòÉ 1. PREFACE ΓòÉΓòÉΓòÉ

This document describes the TRACE component of the Database Manager and the
Query Manager products and it's usage.

This documentation was prepared for Release 1.2 and can be used with Release
1.3.

 DBM TRACE COMPONENT OVERVIEW


ΓòÉΓòÉΓòÉ 2. DBM TRACE COMPONENT OVERVIEW ΓòÉΓòÉΓòÉ

The OS/2 System Trace Facility is used by the DBM Product as a problem
determination tool.

It helps in developing and debugging by the way of recording the flow and
dumping required data to study the problem.

In order to use the OS/2 System Trace Facility, the TRACEBUF parameter must be
specified in the CONFIG.SYS file. This parameter specifies the size of the
system trace buffer in 1K increments. The default size is 4k and a maximum size
of 63K can be specified. We recommend using 63K.

The trace buffer is used as a circular list to hold the latest trace records
that fit. This trace buffer is memory resident.

The OS/2 system trace buffer can be formatted and captured to a file using the
OS/2 TRACEFMT command.

The major and minor trace codes are in hexadecimal and the trace data is in
hexadecimal.

Additional formatting can be done for the DBM trace records by post processing
the output from the TRACEFMT command using the SQLTFMT program.

DBM has been allocated 16 major OS/2 trace codes numbered 176 to 191. See the
list on the following page for the major trace codes currently defined.

Tracing may be started or stopped only at the major trace code level by using
the OS/2 TRACE command.

For example, the command


        TRACE ON 176,180,181

would start tracing for major trace codes 176, 180 and 181. The command


        TRACE OFF 176,180

would stop tracing for major trace code 176 and 180.

Under no conditions should an unqualified "TRACE ON" be specified either in the
CONFIG.SYS file or on the OS/2 command line. This would cause all major trace
codes to be activated and the trace buffer would be filled up with all the base
operating system trace records and other subsystem trace records. The Database
Manager and Query Manager trace records would be lost as these other trace
records may overwrite the earlier records because of the circular nature of the
buffer.

OK, under certain conditions it may be advisable to use TRACE ON for very short
periods, but this is not the general case.

 DBM TRACE COMPONENT
 TRACE OUTPUT
 TRACE QUALIFICATION COMMAND
 TRACE COOKBOOK


ΓòÉΓòÉΓòÉ 3. DBM TRACE COMPONENT ΓòÉΓòÉΓòÉ

The DBM Trace Services component consists of the following:

  1. Internal DBM interface to OS/2 trace functions.

  2. DBM's OS/2 Major Trace Codes.

  3. Trace Output.

     a. TRACEFMT program which formats the OS/2 trace records.

     b. SQLTFMT program which formats the DBM trace records from the OS/2 trace
        records.

  4. SQLTRSET program which limits those DBM components to be traced.

  5. TRACE COOKBOOK, example and usage of the OS/2 and DBM trace.

 Internal DBM Interface To OS/2 Trace Functions
 DBM OS/2 Major Trace Codes


ΓòÉΓòÉΓòÉ 3.1. Internal DBM Interface To OS/2 Trace Functions. ΓòÉΓòÉΓòÉ

The DBM components have macros which register calls to the OS/2 Trace Facility
using the major OS/2 Trace Codes assigned to DBM. These are built into DBM.


ΓòÉΓòÉΓòÉ 3.2. DBM OS/2 Major Trace Codes ΓòÉΓòÉΓòÉ

The major OS/2 trace codes for DBM are:


   176 = Database Function Entry/Exit trace
   177 = User Interface trace
   178 = DB Manager API trace
   179 = Inter-component trace
   180 = Miscellaneous trace
   181 = Miscellaneous trace
   182 = Query Manager Function Entry/Exit trace
   183 = Non-Fatal Error trace
   184 = System Error trace
   185 = Database manager Performance trace
   186 = Query Manager Performance trace
   187 = Database event     (Currently unused)
   188 = Database event     (Currently unused)
   189 = Database event     (Currently unused)
   190 = Database event     (Currently unused)
   191 = Debug trace

Trace initialization is done at the STARTDBM command. Programs that can run
without requiring the STARTDBM command must invoke program SQLTRSET in a
separate OS/2 Protect Window.


ΓòÉΓòÉΓòÉ 4. TRACE OUTPUT ΓòÉΓòÉΓòÉ

The DBM trace records, collected in the OS/2 trace buffer, are processed by
TRACEFMT command to produce a reasonably formatted output. But this output has
no explanation of the codes that are in hexadecimal. To make this output more
informative, it is further  processed by the DBM SQLTFMT command to include the
component and module names and the trace identifier as a decimal number.

 Formatting Using OS/2 TRACEFMT
 Formatting Using DBM SQLTFMT
 More on Trace Formatting Commands


ΓòÉΓòÉΓòÉ 4.1. Formatting By The OS/2 TRACEFMT Command ΓòÉΓòÉΓòÉ

The OS/2 trace buffer must be formatted using the following OS/2 command.


        TRACEFMT > filename

The output is redirected to the specified file. Without the redirection, the
formatted trace records will be written to the display screen. The command will
produce the following formatted output for each trace record in the trace
buffer:


  Unrecognized Trace Event
    Issuing Process ID=pppp  Protect Mode  Dynlink Call  Time Stamp=.....
    Major Event Code=ee  Minor Event Code=cccc
    Data=qq qq ii ii mm tt dd dd dd dd dd dd ....

  where all values are in hexadecimal and are defined as

    pppp is the process identifier
    ee   is the major trace code B0 to BF corresponding to decimal 176 to 191
    cccc is the component identifier
    qqqq is the companion process identifier
    iiii is the thread identifier
    mm   is the function identifier
    tt   is the trace point identifier
    dd   are the data bytes requested to be dumped by the trace call

The OS/2 TRACEFMT command will produce the same formatted output for DBM
records with the exception that "Unrecognized Trace Event" will be replaced
with the string "(OS) Data Base - Unrecognized Trace Event".


ΓòÉΓòÉΓòÉ 4.2. Formatting By The DBM SQLTFMT Command ΓòÉΓòÉΓòÉ

The SQLTFMT command is used to further format the DBM trace records so that the
trace event type, the component name and the function name will be in
characters and the trace identifier will be in decimal.

The following is a sample of the trace records produced by SQLTFMT:


OS/2 EE Database Manager Trace Formatter

(C) Copyright IBM Corporation 1987, 1991

--------------------------------------------------------------------------

Trace Setup Information

Internal Release 200 Modification 00.00

Input file  = T1 was created on  - Fri Dec 29 09:06 1989

Output file = T2 was created on  - Fri Dec 29 09:27 1989

System Trace Records - Tracebuf=63K

--------------------------------------------------------------------------

 PID  CPID  TID  TRACE EVENT TYPE    COMPONENT           FUNCTION (TRACEID)

 0010 0000  0001 176 Function Entry  Forms Specification QRWLDEFLT (1)

 0010 0000  0001 177 User Interface  Report Generation   QRWRSSBL (50)
       Data= 42 61 73 65 20

 0012 0030  0001 178 DBM API Entry   Relation Data Serv  SQLRLGNR (2)
       Data= 42 61 73 65 20 53

 0012 0030  0001 179 Inter-Component Base Sys Utilities  SQLENDOP (51)
       Data= 42 61 73 65 20 53 79

 0012 0030  0002 180 Miscellaneous   Buffer Pool Serv    SQLBFLSH (10)
       Data= 42 61 73 65 20 53 79 73

 0012 0030  0002 182 Function Exit   Sort/List Services  SQLSZVAL (255)
       Data= 00 00

 0012 0030  0001 183 Non-Fatal Error Data Protection     SQLPGWLG (13)
       Data= 42 61 73 65 20 53 79 73 20 55 74

 0012 0030  0001 184 System Error    Index Manager       SQLISPLT (69)
       Data= FF 34 00 00 18 22 55 32 00


ΓòÉΓòÉΓòÉ 4.3. More on Trace Formatting Commands ΓòÉΓòÉΓòÉ

SQLTFMT infile outfile options

This program is issued to format the trace records in a file produced by
running the OS/2 TRACEFMT command such as


       TRACEFMT > filename

This will cause the OS/2 TRACEFMT command to format the trace records in the
OS/2 trace buffer and write the formatted trace records to the file specified.

SQLTFMT is then used to further format the output from the TRACEFMT command to
indicate the trace description, the component description and the function name
for each trace record.

The optional parameters to this program may be specified anywhere on the
command line.  The optional parameters are as follows:

 ?         As any parameter causes the help text to be displayed.

           The program will then terminate.

 infile    The name of the file containing the output from the OS/2 TRACEFMT
           command.

 outfile   The name of the file to contain the formatted trace records.

 -xxx      Indicates which trace records are to be formatted.

 /xxx      The formatting can be limited to the components specified by the
           component letters described below.

           The default is to format all the trace records.

           There should be no space between the dash (-) or slash (/) and the
           component letters.

           These options may be specified as -x -x -x or -xxx where the x is
           any valid component letter or the number 1, 2 or 3.  A slash (/) may
           be used in place of the dash (-).

 +number   Indicates the number of trace records that are to be skipped at the
           beginning of the input file.

 =number   Indicates the number of trace records that are to be formatted. The
           program terminates when this number is reached.

 The user will be prompted to enter the parameters if no parameters are
 specified on the command line.

 The help text that is displayed if the ? is specified on the command line is
 as follows:


  SQLTFMT  ?

  OS / 2  Database  Manager  Trace  Formatter
  Run  the  OS / 2  TRACEFMT  command  and  save  the  output  in  a  file .
  The  output  from  TRACEFMT  is  the  input  to  this  program .
  The  default  is  to  format  all  DBM  trace  records  unless  any
  of  the  following  options  are  specified  on  the  command  line :

    - a     Format  APS  records .       - o     Format  OSS  records .
    - b     Format  BPS  records .       - p     Format  DPS  records .
    - c     Format  DDS  records .       - r     Format  RDS  records .
    - d     Format  DMS  records .       - s     Format  SLS  records .
    - e     Format  BSU  records .       - u     Format  DBU  records .
    - f     Format  ICS  records .       - v     Format  DS   records .
    - i     Format  IXM  records .       - z     Format  GBL  records .
    - n     Format  CMP  records .       - l     Format  SSS  records .
    - t     Include  timestamp .
    - 1     Format  Database  Services  trace  records .
    - 2     Format  Query  Manager  trace  records .
    - 3     Write  non - DBM  trace  records  to  output  file .
    + num   Skip  specified  number  of  trace  records  at  beginning .
    = num   Stop  after  formatting  specified  number  of  trace  records .

  A  slash  ( / )  may  be  used  in  place  of  the  dash  ( - ) .
  More  than  one  option  may  be  specified  after  the  dash  or  slash
  without  any  spaces  between  the  options .  If  no  arguments  are  specified  they
  are  prompted  for  when  the  command  is  run .


ΓòÉΓòÉΓòÉ 5. TRACE QUALIFICATION COMMAND ΓòÉΓòÉΓòÉ

SQLTRSET traceparms

This program is issued to limit the trace by DBM components.

The input parameter (traceparms) is a character string containing any of the
following:

  1. The component letters for the components to be traced.


               a  = All Application Programming Services
               a.b= COBOL Precompiler
               a.c= C Precompiler
               a.f= FORTRAN Precompiler
               a.g= APS General Services
               a.i= APS Precompiler Services
               a.j= APS Binder Services
               a.k= APS Runtime Services
               a.p= PASCAL Precompiler
               a.r= REXX Precompiler
               b  = Buffer Pool Services
               c  = Distributed Data Services
               d  = Data Management Services
               e  = Base System Utilities
               f  = Configuration/Install
               i  = Index Manager
               l  = DOS Requestor Server Support
               m  = MUG (UPM)
               n  = Compiler
               o  = Operating System Services
               p  = Data Protection Services
               r  = Relational Data Services
               s  = Sort List Services
               u  = Utility Services
               v  = Data Services
               z  = Common Services

               C = Command Language Parser
               D = System Layer
               E = Screen Interface
               F = Panels
               G = Generic Print
               H = Helps Supporting Code
               K = Callable Interface
               L = Forms Specification
               M = Menus
               N = Navigation
               O = Table / Index
               P = Procedures
               Q = Prompted Query / View
               R = Report Generation
               S = SQL Interface
               T = Tools
               V = Variable Pool
               W = SQL Query Window
               X = Grant / Revoke
               Z = Common Functions

  2. Besides these the following options are supported.

     The maximum number system errors to be traced is set by the e option on
     the command line. It is specified as /eXX or -eXX where XX is a number.

     To stop tracing  /s or -s can be specified on the command line. To restart
     /r or -r can be specified on the command line.

     To include thread id and companion process id /p or -p can be used on the
     command line. To remove these ids form the trace record /n or -n can be
     specified.

     To allow both entry and exit trace when 176/182 trace is on, /f or -f can
     be used. To include only entry trace /fe or -fe can be used. To include
     exit tracing /fx or -fx can be used.

  3. The trace component letters may be separated by blanks or commas. All
     other input is invalid and is ignored except that a warning message
     displayed to the user.

 For any invalid options in the traceparms passed to this program, the
 following message is displayed:


      Option  ?  is  ignored .

      where  the  ?  is  the  character  that  is  invalid .

 This program will also display the following message:


      Press  ENTER  to  exit  if  you  have  issued  STARTDBM .
      Otherwise ,  leave  this  program  active .

 Since the component identifiers for the components to be traced are stored in
 the Trace Shared Segment, this program must remain active to prevent OS/2 from
 de-allocating the shared segment unless there  is some other program active
 (like STARTDBM) that has also allocated the Trace Shared Segment.


ΓòÉΓòÉΓòÉ 6. TRACE COOKBOOK ΓòÉΓòÉΓòÉ

Step by step procedures for QM and DBM Problem Determination is provided here
for general problem determination.

Particular procedures received from the National Support Division should be
followed. When a problem procedure is given for a particular problem, those
steps must be followed to insure proper isolation.

This general procedure should be executed on the failing workstations (e.g.
standalone, or both server and requester when RDS is used).

 Starting Traces Without Using Command Files
 Starting Traces Using Command Files


ΓòÉΓòÉΓòÉ 6.1. Starting Traces Without Using Command Files ΓòÉΓòÉΓòÉ

A Procedure for QM and DBM Problem Determination without using command files.

       1. In config.sys add the following to bottom of the file.
          Do this once per workstation and then IPL the workstation.

              TRACE=OFF
              TRACEBUF=63
              LOG=ON

       2. In a protect OS/2 window do the following:

             a. C:>startdbm

             b. C:>sqltrset -e0

             c. C:>trace on 176 177 178 179 180 181 182 183 184

       3. Go to a another OS/2 window and run your testcase or failing scenario:

             a. If the system had an abnormal termination, you must remember the screen
                information print it out so you can give it in the problem report.

             b. Do not continue pass the error! Any work beyond the error may cause the
                error information to be rolled out of the resident trace memory.

       4. Go back to the trace window and do:

             a. tracefmt.exe > d:\path\filenam1.ext

                YOU CAN DO THE FOLLOWING IF YOU WANT TO, BUT YOU SHOULD SEND THE ABOVE
                DATA AS A SEPARATE FILE WITH YOUR PROBLEM REPORT. IF YOU DO FORMAT THE TRACE
                USING SQLTFMT, THEN JUST SEND IN THE FORMATTED SQL TRACE FILE.

                You may not have "SQLTFMT.EXE" in your \SQLLIB database directory, but if
                you do. Then you may enter.

             a. C:>sqltfmt.exe d:\path\filenam1.ext d:\path\filenam2.ext

             b. C:>edit d:\path\filename2.ext

                If the system had an abnormal termination, then look for SQLEAPEX entry
                trace, the function just following (next line below) is the one that failed.

                Else, look for the first occurrence of trace 184 (last one as you go from
                line 1 to line n).

                If no trace 184 errors, then look for the first trace 183 error.  But, you
                have to be more careful with trace 183, because you get non-fatal errors
                like: "end of record (sqlcode 100)" or "database directory not found (no
                databases on system)" type errors.

                The data area should have the error for example: "902" in hex "FC7A" or
                "FFFFFFFC7A".

                If no SQLEAPEX, then the abend happen before or after the termination
                exit routine was installed or de-installed. You can use "WHATTRAP"
                command file to find the failing dll or exe.

                Save the trace file for problem report.

       5. Now get the system error log by:

              SYSLOG <enter>

          Print it, save it for the problem report.

          If you print it with the printer off you may copy \spool\printfile.xxx
          filename.ext to save it in a ascii file and also send that file along
          with your problem report.

          SYSLOG information is placed in \OS2\SYSTEM\LOG0001.DAT.

          If the workstation was Re-IPL'ed, then use the
          \OS2\SYSTEM\LOG0001.BAK or send both.

       6. In the trace protect OS/2 window do the following:

             a. C:>trace off 176 177 178 179 180 181 182 183 184

             b. C:>stopdbm

       7. Repeat the above steps (1-6) using trace points only 183 184.

          This should be done, if there was to much activity, that the data
          may have been lost (rolled out of the trace buffer).

          Send all files along with your problem report.


ΓòÉΓòÉΓòÉ 6.2. Starting Traces Using Command Files ΓòÉΓòÉΓòÉ

In order not to have to key in or remember all the commands, place them in a
command file.

  1. In config.sys add to bottom of the file: Do this once per workstation and
     then IPL the workstation.   TRACE=OFF   TRACEBUF=63   note: you can use
     any number less than or equal to 63,   LOG=ON        but we recommend 63.

  2. In a protect OS/2 window do the following:   TRACEON <enter>

     a. set system trace option #7 set to 0, maximum system trace for single
        treaded testcases.  For multiple threads or multiple processes use the
        default, which will only trace 184's after first 184 system error.

     b. set trace all components or just the suspected ones

     c. select exit the menu, should be back at ready prompt "C:>"

  3. Go to a another OS/2 window and run your testcase or failing scenario:

     If the system had an abnormal termination, you must remember the CS and IP
     values, and then do the following:   SQLABEND xx CS:IP <enter>

     SQLABEND will give you the component that is failing, although that
     component may not be the cause of the failure, but it will give you a
     place to start.  You can open the problem against that component.

  4. Go back to the trace window and do:   TRACEGET <enter>

     a. If the system had an abnormal termination, then look for SQLEAPEX entry
        trace, the function just following (next line below) is the one that
        failed.

     b. Else, look for the first occurrence of trace 184 (last one as you go
        from line 1 to line n).

     c. If no trace 184 errors, then look for the first trace 183 error.  But,
        you have to be more careful with trace 183, because you get non-fatal
        errors like: "end of record (sqlcode 100)" or "database directory not
        found (no databases on system)" type errors.

     d. If still no success, then you may want to use WHATTRAP command file.

  5. Save the trace file for DBM development.  Name it using the PMR Number for
     example: PMR0x055.FMT, because I already have a hundred or so TRACE.FMTs.

  6. Now get the system error log by:   SYSLOG <enter>   Print it, save for DBM
     development.

 This procedure can be modified by starting the trace before the error and then
 do TRACEGET right after the error, so that the trace won't be very large.

 The following are the CMD files used in the above procedure.  Down load this
 file and move the cmd files into their own files with your editor.


  TRACEON.CMD


  @echo off
  if x%1 == x? goto help
  prompt OS/2 Protect Mode, Trace Facility, $D, $T$_$P>
  @echo on
  startdbm
  trace on 176 177 178 179 180 181 182 183 184
  sqltrset -e0
  goto exit
  :help
  echo
  echo Help - TRACEON.CMD
  echo
  echo
  echo Turns on trace points.
  echo
  echo traceon ?
  echo
  echo     Where, ? provides help information if needed.
  echo
  echo     1.  Run in a protect window.
  echo     2.  No parameter needed, use just command file name "traceon".
  echo     3.  Must have in CONFIG.SYS
  echo         TRACE=OFF
  echo         TRACEBUF=n  where, n is 1 to 63, I suggest 63.
  echo     4.  sqltrset
  echo
  echo                                               Raymond Hernandez 04/28/89
  echo
  :exit


  TRACEGET.CMD


  @echo off
  if x%1 == x goto a
  if x%1 == x? goto help
  prompt OS/2 Protect Mode, Trace Facility, $D, $T$_$P>
  tracefmt.exe > %1
  goto b
  :a
  tracefmt.exe > c:\t.trc
  sqltfmt.exe c:\t.trc c:\t.fmt
  e d:\t.fmt
  goto exit
  :b
  if x%2 == x goto c
  sqltfmt.exe %1 %2
  e %2
  goto exit
  :c
  sqltfmt.exe %1 c:\t.fmt
  e t.fmt
  goto exit
  :help
  echo
  echo Help - TRACEGET.CMD
  echo
  echo
  echo   Used to get a formatted trace output.  Use after TRACEON.CMD
  echo
  echo   TRACEGET.CMD  dos_format_file_name  sql_format_file_name
  echo
  echo     dos_format_file_name - is where you want dos to format trace info,
  echo                            default is "c:\t.trc"
  echo
  echo     sql_format_file_name - is where DBM will format trace info,
  echo                            default is "c:\t.fmt"
  echo
  echo   Sequence of Commands:
  echo
  echo   1. tracefmt   dos_format_file_name
  echo   2. sqltfmt    dos_format_file_name  sql_format_file_name
  echo   3. e          sql_format_file_name
  echo
  echo                                               Raymond Hernandez 04/28/89
  echo
  :exit


  TRACEOFF.CMD


  @echo off
  if x%1 == x? goto help
  prompt OS/2 Protect Mode, $D, $T$_$P>
  @echo on
  trace off 176 177 178 179 180 181 182 183 184
  @echo off
  goto exit
  :help
  echo
  echo Help - traceoff.cmd
  echo
  echo
  echo   Turn off trace, use after traceon.cmd or traceget.cmd, use when no
  echo   longer needing the trace points to be captured.
  echo
  echo   traceoff ?
  echo
  echo     Where, ? provides help information, if needed.
  echo
  echo     1.  Run in a protect window.
  echo     2.  No parameter needed, use just command file name "traceoff".
  echo
  echo                                               Raymond Hernandez 04/28/89
  echo
  :exit