home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / os2trace.zip / OS2TRACE.FAQ < prev    next >
Text File  |  2001-01-10  |  31KB  |  631 lines
  1.  
  2.  
  3.             Operating System/2 API Trace Frequently Asked Questions
  4.  
  5.  
  6.   Q: In as simple  terms as possible,  how does tracing  with OS/2 API Trace
  7.      really work?
  8.  
  9.   A: In short,  OS/2 API Trace intercepts the OS/2 API calls  an application
  10.      makes,  allowing it to  log tracing  information both  before and after
  11.      calling  the  intended  OS/2 API.  How  this  is done  is really  quite
  12.      simple, albeit a little lengthy to describe in "simple" terms.
  13.  
  14.      Every time an  executable file makes a call to a  procedure external to
  15.      itself, such as an OS/2 API, a fixup record is generated by the program
  16.      linker that tells the operating system which procedure is required when
  17.      the file is loaded at run-time.  This fixup record includes information
  18.      such  as what  dynamic link  library (DLL)  contains the  procedure and
  19.      which procedure it is,  identified by either  name or ordinal.  Instead
  20.      of  storing the  name of each  procedure's DLL within  the actual fixup
  21.      record,  the DLL names are instead stored together  in a separate place
  22.      within the executable file, the import module name table,  and an index
  23.      into this  table is stored  within the  fixup record.  This is  done to
  24.      save space,  in that a  DLL's name  is stored once  per executable file
  25.      instead of once per fixup record.
  26.  
  27.      When tracing is enabled  for one of the supported DLLs,  OS/2 API Trace
  28.      simply  goes into  the executable file's  import module name  table and
  29.      overwrites the name of the OS/2 DLL being enabled,  such as "DOSCALLS",
  30.      with the name of the corresponding trace DLL, such as "T_DOS___".  When
  31.      the executable  file is loaded,  the program  loader  redirects all API
  32.      calls intended for the  OS/2 DLL to the exact  same ordinals within the
  33.      trace DLL instead  because the trace DLL's name  now resides within the
  34.      import module  name table.  Each trace  DLL mirrors  its  corresponding
  35.      OS/2 DLL  ordinal  for ordinal.  If the  ordinal  within  the  OS/2 DLL
  36.      represents a published API, the trace DLL contains a matching trace API
  37.      (with identical parameter list) that logs API entry information,  calls
  38.      the OS/2 API, and logs API exit information.  If the ordinal within the
  39.      OS/2 DLL represents an unpublished (private) API,  the trace DLL passes
  40.      the call directly to the OS/2 DLL through use of a forwarder entry.
  41.  
  42.      When tracing is disabled for one of the supported DLLs,  OS/2 API Trace
  43.      simply undoes what was  done during enablement.  That is,  it goes into
  44.      the executable file's import module  name table and overwrites the name
  45.      of the trace DLL being disabled,  such as "T_DOS___",  with the name of
  46.      the  corresponding  OS/2 DLL,  such as "DOSCALLS".  When complete,  the
  47.      executable file  is restored  to its  original state  and all  OS/2 API
  48.      calls go directly to the OS/2 DLL.
  49.  
  50.   Q: How easy is it for a non-technical  person to trace an application with
  51.      OS/2 API Trace?
  52.  
  53.   A: It is really quite easy to trace  an application with OS/2 API Trace as
  54.      long as  one doesn't  get  overwhelmed  by the  number of  options  the
  55.      utility  provides.  Keep in  mind  that  OS/2 API Trace  provides  four
  56.      unique functions: trace enablement, trace customization, trace control,
  57.      and trace  summarization.  Trace enablement turns on/off tracing  of an
  58.      application,  trace customization  sets the types  of trace information
  59.      generated by the application,  trace control pauses/resumes  tracing of
  60.      the application,  and trace summarization  totals the APIs in the trace
  61.      information generated by the application.
  62.  
  63.      As an example,  follow the simple scenario below to trace an executable
  64.      present on every OS/2 system, CMD.EXE.
  65.  
  66.      Begin by opening an OS/2 window or full screen session and entering the
  67.      following commands:
  68.  
  69.        md \cmdtrace
  70.        cd \cmdtrace
  71.        copy x:\os2\cmd.exe
  72.  
  73.      where x is the drive on which OS/2 is installed.  These commands create
  74.      a temporary copy of CMD.EXE to work  on so as not to interfere with the
  75.      original copy  in the \OS2  directory.  A temporary copy  is not really
  76.      necessary,  but will avoid  duplicate trace files  being created in the
  77.      event that some other process uses CMD.EXE while running this scenario.
  78.  
  79.      Start the tracing process by customizing OS/2 API Trace so as to get as
  80.      much trace information as possible:
  81.  
  82.        os2trace -a none -b all -c off -d all -e on -f all -g all -i on -l 3
  83.                 -t on -w all
  84.  
  85.      After the program banner,  the utility displays  the former  options as
  86.      well  as these  new  options.  OS/2 API Trace  remembers the  states of
  87.      these customization options  and uses them for  all future traces until
  88.      they are changed by some subsequent customization commands.
  89.  
  90.      Continue the tracing process by trace-enabling CMD.EXE:
  91.  
  92.        os2trace -on -all cmd.exe
  93.  
  94.      After the program banner, the utility displays which DLLs were and were
  95.      not enabled for tracing.  Note that in  this case CMD.EXE  only imports
  96.      APIs from DOSCALLS.
  97.  
  98.      At this point,  CMD is ready to be traced.  Go ahead and  execute it by
  99.      entering the following command:
  100.  
  101.        cmd
  102.  
  103.      Enter as few or as many commands  in this new command shell as desired;
  104.      when complete, terminate the shell by entering the following command:
  105.  
  106.        exit
  107.  
  108.      Complete the  tracing process  by trace-disabling  CMD.EXE so  that any
  109.      future  invocations  of  CMD.EXE  do  not  produce  additional  tracing
  110.      information which overwrites CMD.TRC:
  111.  
  112.        os2trace -off -all cmd.exe
  113.  
  114.      After the program banner, the utility displays which DLLs were and were
  115.      not disabled for tracing.
  116.  
  117.      NOTE:    The TRACE-IT batch file incorporates all of the above OS2TRACE
  118.      commands and  invokes the executable,  so the following  works just  as
  119.      well:
  120.  
  121.        trace-it cmd
  122.  
  123.      Now  go  ahead  and  edit  CMD.TRC,   which  contains  entry  and  exit
  124.      information for every API used  by CMD.EXE while it was executing.  For
  125.      instance,  note how  every  keystroke  is read  in by  Kbd16CharIn  and
  126.      echoed to  the display  by Vio16WrtTTY,  using the editor's find/search
  127.      capabilities to locate these APIs within the trace information file.
  128.  
  129.      Optionally extend  the tracing process by  summarizing the APIs used by
  130.      CMD.EXE:
  131.  
  132.        os2trace -s cmd.trc
  133.  
  134.      After the program banner,  the utility displays an alphabetical list of
  135.      the APIs  used and  how many  times each  was invoked  successfully and
  136.      unsuccessfully.
  137.  
  138.      Finish by entering the following commands:
  139.  
  140.        del cmd.*
  141.        cd \
  142.        rd \cmdtrace
  143.  
  144.      to remove the temporary files and directory.
  145.  
  146.   Q: What versions of OS/2 are supported by OS/2 API Trace?
  147.  
  148.   A: OS/2 API Trace supports all 32-bit versions of OS/2:
  149.  
  150.      Name                                | Major Version | Minor Version
  151.      ------------------------------------+---------------+--------------
  152.      OS/2 Version 2.0                    |            20 |             0
  153.      OS/2 Version 2.1                    |            20 |            10
  154.      OS/2 Version 2.11                   |            20 |            11
  155.      OS/2 Warp Version 3                 |            20 |            30
  156.      OS/2 Warp Version 4                 |            20 |            40
  157.      OS/2 Warp Server for e-business     |            20 |            45
  158.      OS/2 Warp Connect (PowerPC Edition) |            30 |             0
  159.  
  160.      where  major and minor  versions are the  corresponding values returned
  161.      from  DosQuerySysInfo.  Note that  the ELF versions  of the executables
  162.      and trace  DLLs  are  required  to  run on  OS/2 Warp Connect  (PowerPC
  163.      Edition).
  164.  
  165.   Q: What purpose does each file serve in OS/2 API Trace?
  166.  
  167.   A: The files that comprise the OS/2 API Trace utility are described in the
  168.      following table:
  169.  
  170.      Name         | Purpose
  171.      -------------+---------------------------------------------------------
  172.      OS2TRACE.NWS | Text file describing the  change history of the complete
  173.                   |   OS/2 API Trace package
  174.      OS2TRACE.DOC | Text file providing a  technical description of OS/2 API
  175.                   |   Trace, its usage and output, and a typical scenario
  176.      OS2TRACE.FAQ | Text file providing answers to the most frequently asked
  177.                   |   questions about OS/2 API Trace
  178.      OS2TRACE.API | Text file  containing  all of the  supported  APIs along
  179.                   |   with  their OS/2 DLL,  trace API group  (if any),  and
  180.                   |   minimum required version of 32-bit OS/2
  181.      OS2TRACE.EXE | OS/2 API Trace command line interface
  182.      PMOS2TRC.EXE | OS/2   API  Trace   Presentation   Manager   (graphical)
  183.                   |   interface
  184.      PMOS2TRC.HLP | Online help for the Presentation Manager interface
  185.      TRACE-IT.CMD | Batch file that performs all commands necessary to trace
  186.                   |   a .EXE file
  187.      CHK4TRC.DOC  | Text  file  providing a  technical  description  of  the
  188.                   |   trace-enabled executable checker, its usage and output
  189.      CHK4TRC.EXE  | Trace-enabled executable checker command line interface
  190.      STRIPAPI.DOC | Text  file  providing a  technical  description  of  the
  191.                   |   trace  information  file API  stripper,  its usage and
  192.                   |   output
  193.      STRIPAPI.EXE | Trace   information  file  API  stripper   command  line
  194.                   |   interface
  195.      T_*.DLL      | Trace DLLs
  196.  
  197.   Q: Why  won't  OS/2 API Trace  enable  tracing  of a DLL  that has  an API
  198.      imported by name?
  199.  
  200.   A: This  restriction  was removed  as of version  2.45.18  except for  the
  201.      following APIs:
  202.  
  203.      PMDRAG.DRGACCESSDRAGINFO           PMPIC.PICPRINT
  204.      PMDRAG.DRGADDSTRHANDLE             PMPIC.PICICHG
  205.      PMDRAG.DRGALLOCDRAGINFO            PMPIC.PIF2MET
  206.      PMDRAG.DRGALLOCDRAGTRANSFER        PMPIC.PRFPIF2MET
  207.      PMDRAG.DRGDELETEDRAGINFOSTRHANDLES PMPIC.PIC32PRINT
  208.      PMDRAG.DRGDELETESTRHANDLE          PMPIC.PIC32ICHG
  209.      PMDRAG.DRGDRAG                     PMPIC.PRF32PIF2MET
  210.      PMDRAG.DRGFREEDRAGINFO
  211.      PMDRAG.DRGFREEDRAGTRANSFER
  212.      PMDRAG.DRGGETPS
  213.      PMDRAG.DRGPOSTTRANSFERMSG
  214.      PMDRAG.DRGPUSHDRAGINFO
  215.      PMDRAG.DRGQUERYDRAGITEM
  216.      PMDRAG.DRGQUERYDRAGITEMCOUNT
  217.      PMDRAG.DRGQUERYDRAGITEMPTR
  218.      PMDRAG.DRGQUERYNATIVERMF
  219.      PMDRAG.DRGQUERYNATIVERMFLEN
  220.      PMDRAG.DRGQUERYSTRNAME
  221.      PMDRAG.DRGQUERYSTRNAMELEN
  222.      PMDRAG.DRGQUERYTRUETYPE
  223.      PMDRAG.DRGQUERYTRUETYPELEN
  224.      PMDRAG.DRGRELEASEPS
  225.      PMDRAG.DRGSENDTRANSFERMSG
  226.      PMDRAG.DRGSETDRAGPOINTER
  227.      PMDRAG.DRGSETDRAGIMAGE
  228.      PMDRAG.DRGSETDRAGITEM
  229.      PMDRAG.DRGVERIFYNATIVERMF
  230.      PMDRAG.DRGVERIFYRMF
  231.      PMDRAG.DRGVERIFYTRUETYPE
  232.      PMDRAG.DRGVERIFYTYPE
  233.      PMDRAG.DRGVERIFYTYPESET
  234.      PMDRAG.DRGDRAGFILES
  235.      PMDRAG.DRGACCEPTDROPPEDFILES
  236.  
  237.      The reason that these PMDRAG APIs  are unsupported is that between OS/2
  238.      2.10 and 2.30  their  names  were changed to include "16" in the prefix
  239.      (for example, DRGACCESSDRAGINFO became DRG16ACCESSDRAGINFO);  the newer
  240.      names are  supported.  The reason that these PMPIC APIs are unsupported
  241.      is that between  OS/2 2.30 and 2.40  their names were  changed to mixed
  242.      case (for  example,  PICPRINT  became  PicPrint);  the newer  names are
  243.      supported.  Special  versions of the  PMDRAG and PMPIC  trace DLLs that
  244.      support the older names can be requested from the author.
  245.  
  246.   Q: Why does  the date and  time stamp  of an  executable file  change when
  247.      tracing is enabled or disabled?
  248.  
  249.   A: An executable file's  date and time stamp changes  whenever a supported
  250.      DLL is enabled or disabled for tracing because the file's import module
  251.      name table is  updated and the  changes written  to disk.  Nothing else
  252.      within the executable file is affected by OS/2 API Trace.
  253.  
  254.      NOTE:  As of version 2.40.85, the executable file's date and time stamp
  255.      can be preserved  through use of  OS2TRACE's -P option  and  PMOS2TRC's
  256.      "Preserve file date/time stamp" item on the "Enable" submenu.
  257.  
  258.   Q: Can DLLs be traced through OS/2 API Trace?
  259.  
  260.   A: Yes,  OS/2 API Trace will work on any  segmented (16-bit, NE format) or
  261.      linear (32-bit, LX format)  executable file,  such as .EXE,  .COM,  and
  262.      .DLL files.  Any trace information generated by a DLL,  however, cannot
  263.      be stored in a trace information file named after the .DLL file because
  264.      DLLs can  be shared by  more than one process.  As a result,  all trace
  265.      information generated  by a DLL is stored  in a trace information  file
  266.      named after the .EXE or .COM file.  For example,  if A.EXE imports from
  267.      B.DLL and B.DLL is trace-enabled,  the trace  information from B.DLL is
  268.      logged to A.TRC when A.EXE is executed.
  269.  
  270.      There is no limit to the number of DLLs that can be traced at once, but
  271.      trace information from all DLLs is logged to a single trace information
  272.      file named  after  the .EXE or .COM  file that  directly or  indirectly
  273.      loaded the DLLs.
  274.  
  275.   Q: Can 16-bit APIs be traced with OS/2 API Trace?
  276.  
  277.   A: Yes, all the 16-bit APIs present in the Base subsystem (Dos, Kbd,  Mou,
  278.      and Vio APIs) and Presentation Manager subsystem (Dev,  Drg,  Gpi, Pic,
  279.      Prf, Prt, Spl, and Win APIs)  are supported as of version 2.40.34.  See
  280.      OS2TRACE.API for a table containing all supported APIs.
  281.  
  282.   Q: Can SMP (Symmetric Multiprocessing) APIs be traced with OS/2 API Trace?
  283.  
  284.   A: Yes,  all the 16-bit and 32-bit SMP APIs  present in the Base subsystem
  285.      (Dos APIs) are supported as of version 2.40.61.  See OS2TRACE.API for a
  286.      table containing all supported APIs.
  287.  
  288.   Q: Can APIs loaded by the application at run-time through Dos16GetProcAddr
  289.      or Dos32QueryProcAddr be traced with OS/2 API Trace?
  290.  
  291.   A: Yes, OS2TRACE's -I option and PMOS2TRC's "API interception" item on the
  292.      "Customize" submenu enable interception and tracing of these APIs, also
  293.      known as dynamically  loaded APIs.  This functionality  is available as
  294.      of version 2.40.36.
  295.  
  296.      NOTE: In order to intercept dynamic API calls, DOSCALLS must be enabled
  297.      for tracing even though Dos16GetProcAddr  and Dos32QueryProcAddr do not
  298.      have to actually be traced.
  299.  
  300.   Q: What needs to be done to trace all APIs of a specific type, such as Dos
  301.      APIs or Win APIs?
  302.  
  303.   A: Use the following table  to determine which  DLL or DLLs to  enable for
  304.      tracing in order to trace all APIs of a specific API type:
  305.  
  306.      API Type     | DLL(s)
  307.      -------------+---------------------------------------------------------
  308.      Ddf (32-bit) | HELPMGR
  309.      Dev (16-bit) | PMGPI
  310.      Dev (32-bit) | PMGPI
  311.      Dos (16-bit) | DOSCALLS, MSG, NLS, MONCALLS, NAMPIPES, PMSPL, SESMGR,
  312.                   |   QUECALLS
  313.      Dos (32-bit) | DOSCALLS, MSG, NLS, SESMGR, QUECALLS
  314.      Drg (16-bit) | PMDRAG
  315.      Drg (32-bit) | PMDRAG
  316.      Gpi (16-bit) | PMBIDI, PMGPI, PMWIN
  317.      Gpi (32-bit) | PMBIDI, PMGPI
  318.      Kbd (16-bit) | KBDCALLS
  319.      Mou (16-bit) | MOUCALLS
  320.      Pic (16-bit) | PMPIC
  321.      Pic (32-bit) | PMPIC
  322.      Prf (16-bit) | PMSHAPI
  323.      Prf (32-bit) | PMSHAPI
  324.      Prt (16-bit) | PMSPL
  325.      Prt (32-bit) | PMSPL
  326.      Spl (16-bit) | PMSPL
  327.      Spl (32-bit) | PMSPL
  328.      Vio (16-bit) | VIOCALLS
  329.      Win (16-bit) | HELPMGR, PMBIDI, PMSHAPI, PMVIOP, PMWIN
  330.      Win (32-bit) | HELPMGR, PMBIDI, PMCTLS, PMMERGE, PMSHAPI, PMWIN, PMWP
  331.  
  332.      Note that some DLLs contain more than one API type, such as HELPMGR and
  333.      PMSPL, so there may be some overlap of API types involved when enabling
  334.      one of these DLLs for tracing.
  335.  
  336.   Q: Where are all those APIs in the trace information file coming from that
  337.      aren't part of the application's source code?
  338.  
  339.   A: The C run-time.  Remember that OS/2 API Trace intercepts every OS/2 API
  340.      call made by an  application being traced,  and the C run-time requires
  341.      OS/2 APIs to function properly under OS/2.  For instance,  the run-time
  342.      needs DosWrite in order to implement fprintf.
  343.  
  344.   Q: Can network APIs be traced with OS/2 API Trace?
  345.  
  346.   A: No,  OS/2 API Trace  only covers APIs  included in the  basic operating
  347.      system,  which includes the Base,  Presentation Manager,  and Workplace
  348.      Shell  subsystems.  Operating  system  extensions  such as  Multimedia,
  349.      TCP/IP,  and Network  are not supported.  See OS2TRACE.API  for a table
  350.      containing all supported APIs.
  351.  
  352.   Q: Are there any  special steps  should be  taken to  trace an application
  353.      over a long period of time, such as hours or even days?
  354.  
  355.   A: Outside of a minimal performance impact, OS/2 API Trace does not hinder
  356.      the functionality  of any APIs  being traced,  so no unusual  steps are
  357.      required to trace an application  over a long period of time.  However,
  358.      a couple of customization  options are provided  that may be beneficial
  359.      when tracing over large periods of time.
  360.  
  361.      The first  such option  is time  stamping,  which is specified  through
  362.      OS2TRACE's  -T  option  and  PMOS2TRC's  "Time stamping"  item  on  the
  363.      "Customize" submenu and is available as of version 2.30.18.  When  time
  364.      stamping is enabled, all API entries and exits are marked with the time
  365.      they  occurred accurate to a  hundredth of a second.  Time stamping can
  366.      be quite useful  to record when exactly APIs were  called while logging
  367.      several hours of trace information.
  368.  
  369.      The  second  option  is  file  wrapping,  which  is  specified  through
  370.      OS2TRACE's  -F  option  and  PMOS2TRC's  "File wrapping"  item  on  the
  371.      "Customize" submenu  and is available as of version 2.30.17.  When file
  372.      wrapping  is enabled,  only  a certain  amount of trace  information is
  373.      logged before the trace information  file is  overwritten starting from
  374.      the beginning.  File  wrapping can be  quite useful to  set an absolute
  375.      limit to the trace information file  size,  because,  depending  on the
  376.      level  of  trace  information requested  and the  number of APIs  being
  377.      traced,  OS/2  API Trace  can  generate  megabytes  upon  megabytes  of
  378.      information rather quickly.
  379.  
  380.      NOTE:  Setting the log file wrapping  length to anything other than ALL
  381.      will further impact the performance of the application being traced, as
  382.      log file wrapping requires the log file to be unbuffered,  meaning that
  383.      trace information  cannot be  buffered in  a memory cache  before being
  384.      written to disk.
  385.  
  386.   Q: It is documented  that OS/2 API Trace  can trace  APIs from  the latest
  387.      version  of OS/2.  Does  this  mean  that it  cannot  work  on  earlier
  388.      versions of OS/2 because the latest APIs were not yet present on them?
  389.  
  390.   A: OS/2 API Trace will  work on ALL versions of 32-bit OS/2,  or OS/2 2.x.
  391.      This is possible because the trace DLLs dynamically load all APIs added
  392.      to OS/2 after  version 2.00  through use  of the  DosQueryProcAddr API.
  393.      Only APIs supported  by OS/2 2.00 are  actually  imported  by the trace
  394.      DLLs.
  395.  
  396.   Q: Will OS/2 API Trace work on 16-bit versions of OS/2?
  397.  
  398.   A: No, all executable files that comprise OS/2 API Trace are of the linear
  399.      (32-bit,  LX) executable file format,  which is unknown to all versions
  400.      of  16-bit OS/2,  or OS/2 1.x.  The  16-bit  APIs  that OS/2  API Trace
  401.      supports can only be traced under OS/2 2.x.
  402.  
  403.   Q: How can an application be traced if it resides on a disk with little,
  404.      if any, available space?
  405.  
  406.   A: An alternative logging directory can be specified through OS2TRACE's -A
  407.      option and PMOS2TRC's  "Alternative directory"  item on the "Customize"
  408.      submenu and is available as of version 2.45.24.  When a fully qualified
  409.      drive and path is specified for the alternative directory, it overrides
  410.      the  default  directory  (same as the  .EXE/.COM file)  and  all  trace
  411.      information files  are generated  within it.  This allows  applications
  412.      that reside on disks with space  constraints to be traced by specifying
  413.      an alternative directory on a different drive altogether.
  414.  
  415.   Q: When under  disk space constraints,  can only the trace DLLs  needed be
  416.      placed on the system where the tracing will take place?
  417.  
  418.   A: Yes, the only trace DLLs that are required in order for tracing to take
  419.      place are T_COMMON.DLL  and whatever  trace DLLs have  been enabled for
  420.      tracing.  The only exceptions to this rule are in the following table:
  421.  
  422.      Trace DLL    | Other Required Trace DLLs
  423.      -------------+---------------------------------------------------------
  424.      T_CTL_.DLL   | T_DRG_.DLL
  425.      T_DOS___.DLL | T_KBD___.DLL, T_M.DLL, T_MON___.DLL, T_MOU___.DLL,
  426.                   |   T_N.DLL, T_PIP___.DLL,  T_QUE___.DLL, T_SES_.DLL,
  427.                   |   T_VIO___.DLL
  428.      T_MRG__.DLL  | T_GPI.DLL, T_SHL__.DLL, T_WIN.DLL
  429.  
  430.      These other trace DLLs are required  because the trace DLLs in the left
  431.      column import trace APIs from the  trace DLLs in the right column.  The
  432.      following  table  shows  all  of  the  supported  OS/2  DLLs  and their
  433.      corresponding trace DLLs:
  434.  
  435.      OS/2 DLL     | Trace DLL
  436.      -------------+-------------
  437.      DOSCALLS.DLL | T_DOS___.DLL
  438.      HELPMGR.DLL  | T_HLP__.DLL
  439.      KBDCALLS.DLL | T_KBD___.DLL
  440.      MONCALLS.DLL | T_MON___.DLL
  441.      MOUCALLS.DLL | T_MOU___.DLL
  442.      MSG.DLL      | T_M.DLL
  443.      NAMPIPES.DLL | T_PIP___.DLL
  444.      NLS.DLL      | T_N.DLL
  445.      PMBIDI.DLL   | T_PBD_.DLL
  446.      PMCTLS.DLL   | T_CTL_.DLL
  447.      PMDRAG.DLL   | T_DRG_.DLL
  448.      PMGPI.DLL    | T_GPI.DLL
  449.      PMMERGE.DLL  | T_MRG__.DLL
  450.      PMPIC.DLL    | T_PIC.DLL
  451.      PMSHAPI.DLL  | T_SHL__.DLL
  452.      PMSPL.DLL    | T_SPL.DLL
  453.      PMVIOP.DLL   | T_PVP_.DLL
  454.      PMWIN.DLL    | T_WIN.DLL
  455.      PMWP.DLL     | T_WP.DLL
  456.      QUECALLS.DLL | T_QUE___.DLL
  457.      SESMGR.DLL   | T_SES_.DLL
  458.      VIOCALLS.DLL | T_VIO___.DLL
  459.  
  460.   Q: Can only the files needed be replaced  when updating to a later version
  461.      of OS/2 API Trace?
  462.  
  463.   A: It is not recommended,  as OS/2 API Trace may (and usually will) change
  464.      internally from release to release.  In fact, as of version 2.40.58, an
  465.      error is issued if the  version of one of  the required trace DLLs does
  466.      not match the  version of T_COMMON.  Make sure that  all the files that
  467.      comprise  OS/2 API Trace  have the  same date  and time  stamps  before
  468.      attempting to use the utility.
  469.  
  470.      The sizes and  date and time stamps of all the files  that comprise the
  471.      latest release, Version 2.45.26, are shown in the following table:
  472.  
  473.      Name         | Size   | Date     | Time
  474.      -------------+--------+----------+------
  475.      OS2TRACE.NWS |  38386 | 01-10-01 | 5:00p
  476.      OS2TRACE.DOC |  50562 | 01-10-01 | 5:00p
  477.      OS2TRACE.FAQ |  30655 | 01-10-01 | 5:00p
  478.      OS2TRACE.API | 124821 | 01-10-01 | 5:00p
  479.      OS2TRACE.EXE |  90754 | 01-10-01 | 5:00p
  480.      PMOS2TRC.EXE | 160095 | 01-10-01 | 5:00p
  481.      PMOS2TRC.HLP | 232828 | 01-10-01 | 5:00p
  482.      TRACE-IT.CMD |   3022 | 01-10-01 | 5:00p
  483.      CHK4TRC.DOC  |   3705 | 01-10-01 | 5:00p
  484.      CHK4TRC.EXE  |  49405 | 01-10-01 | 5:00p
  485.      STRIPAPI.DOC |   2987 | 01-10-01 | 5:00p
  486.      STRIPAPI.EXE |  54496 | 01-10-01 | 5:00p
  487.      T_COMMON.DLL | 328929 | 01-10-01 | 5:00p
  488.      T_CTL_.DLL   |  27864 | 01-10-01 | 5:00p
  489.      T_DOS___.DLL | 185786 | 01-10-01 | 5:00p
  490.      T_DRG_.DLL   |  49512 | 01-10-01 | 5:00p
  491.      T_GPI.DLL    | 236951 | 01-10-01 | 5:00p
  492.      T_HLP__.DLL  |  33113 | 01-10-01 | 5:00p
  493.      T_KBD___.DLL |  32858 | 01-10-01 | 5:00p
  494.      T_M.DLL      |  28021 | 01-10-01 | 5:00p
  495.      T_MON___.DLL |  26682 | 01-10-01 | 5:00p
  496.      T_MOU___.DLL |  35002 | 01-10-01 | 5:00p
  497.      T_MRG__.DLL  |  41849 | 01-10-01 | 5:00p
  498.      T_N.DLL      |  27829 | 01-10-01 | 5:00p
  499.      T_PBD_.DLL   |  31992 | 01-10-01 | 5:00p
  500.      T_PIC.DLL    |  25767 | 01-10-01 | 5:00p
  501.      T_PIP___.DLL |  31914 | 01-10-01 | 5:00p
  502.      T_PVP_.DLL   |  26728 | 01-10-01 | 5:00p
  503.      T_QUE___.DLL |  31674 | 01-10-01 | 5:00p
  504.      T_SES_.DLL   |  28072 | 01-10-01 | 5:00p
  505.      T_SHL__.DLL  |  55641 | 01-10-01 | 5:00p
  506.      T_SPL.DLL    |  76167 | 01-10-01 | 5:00p
  507.      T_VIO___.DLL |  52762 | 01-10-01 | 5:00p
  508.      T_WIN.DLL    | 226183 | 01-10-01 | 5:00p
  509.      T_WP.DLL     |  33302 | 01-10-01 | 5:00p
  510.  
  511.   Q: Why do some 16-bit  applications trap or behave  differently when being
  512.      traced?
  513.  
  514.   A: Traps and/or  different behavior  when tracing  16-bit applications  is
  515.      usually a sign of stack overwriting and/or stack overflow.  The problem
  516.      stems from the fact that stacks for all 16-bit threads must be provided
  517.      by the programmer,  which often leads to stacks that  are surrounded by
  518.      data variables and/or stacks that do not have the recommended amount of
  519.      space available (4KB) when calling into an OS/2 API.  This problem does
  520.      not usually occur in the case of  32-bit threads because the programmer
  521.      need only provide a stack size,  resulting in a separate object for the
  522.      stack  being allocated  by the  operating system.  Regardless,  tracing
  523.      does require  additional stack  space over and  above what  is required
  524.      normally, as shown in the following table:
  525.  
  526.      API    | Additional Stack Space Requirement (in bytes)
  527.      -------+---------------------------------------------------------------
  528.      16-bit | 122 + ( 2 * sizeof( parameters ) )
  529.      32-bit | sizeof( parameters )
  530.  
  531.      This slight  overhead can easily  lead to traps or  different behavior.
  532.      If these symptoms occur when tracing your own application, increase the
  533.      stack size for all of your threads and try again.
  534.  
  535.   Q: What is trace control good for?
  536.  
  537.   A: Trace  control  allows tracing  to be  paused  (no logging occurs)  and
  538.      resumed  (normal logging occurs ) while trace-enabled  applications are
  539.      running.  This is  especially useful when  only interested in tracing a
  540.      specific behavior of an application.  For example, pause tracing, start
  541.      the application and let  it run to the point where  tracing is desired,
  542.      resume tracing, perform the desired function,  pause tracing again, and
  543.      let the  application  run to  termination.  The trace  information file
  544.      will only  contain API calls  made while  tracing was active (resumed),
  545.      which are just those APIs associated with the specific behavior.
  546.  
  547.   Q: What is trace summarization good for?
  548.  
  549.   A: Summarizing a trace  information file produces  an alphabetical listing
  550.      of all the APIs  called by an  application and how  many times each API
  551.      was successfully  and unsuccessfully  called.  This information  can be
  552.      quite useful  in determining where  erroneous API calls  can be removed
  553.      or repaired and where performance enhancements can be made.
  554.  
  555.   Q: Why are there  so many failures logged when tracing certain APIs,  such
  556.      as WinDefWindowProc, when the application clearly works?
  557.  
  558.   A: Some Presentation Manager  APIs return identical  values with different
  559.      meanings based solely on the input parameters.  This is most evident in
  560.      APIs dealing  with messages,  where some messages  will return  zero to
  561.      indicate success  while others  will return  zero to  indicate failure.
  562.      Instead of going  through rather  lengthy logic to  determine whether a
  563.      return value indicates success or failure for this small group of APIs,
  564.      OS/2  API Trace  assumes  that  zero  indicates  failure  and  non-zero
  565.      indicates success.
  566.  
  567.      NOTE:  As of  version 2.40.45,  OS/2 API Trace  considers the following
  568.      APIs'  return  codes  to  be  indeterminate   (neither  successful  nor
  569.      unsuccessful):
  570.  
  571.      Drg16SendTransferMsg
  572.      Drg32SendTransferMsg
  573.      Win16DdeRespond
  574.      Win32DdeRespond
  575.      Win16DefDlgProc
  576.      Win32DefDlgProc
  577.      Win32DefFileDlgProc
  578.      Win32DefFontDlgProc
  579.      Win16DefWindowProc
  580.      Win32DefWindowProc
  581.      Win16DispatchMsg
  582.      Win32DispatchMsg
  583.      Win16SendDlgItemMsg
  584.      Win32SendDlgItemMsg
  585.      Win16SendMsg
  586.      Win32SendMsg
  587.      Win16SetErrorInfo
  588.      Win32SetErrorInfo
  589.  
  590.   Q: Why would an application appear to terminate prematurely?
  591.  
  592.   A: OS/2 API Trace is an  OS/2 application and thereby  constrained by OS/2
  593.      resource limits,  especially those  that apply  to memory,  semaphores,
  594.      files,  and Presentation Manager.  Should  tracing appear  to terminate
  595.      the  application prematurely,  make sure to pay attention  to any error
  596.      messages  displayed either to  the console or  in a message box.  Also,
  597.      make sure to  check the contents of both  OS2TRACE.ERR and PMOS2TRC.ERR
  598.      in the root directory of the boot drive.
  599.  
  600.   Q: Why aren't  some  of the  supported  Dos APIs  in DOSCALLS.DLL  getting
  601.      traced even when DOSCALLS is enabled for tracing?
  602.  
  603.   A: If the  missing APIs are  listed in  OS2TRACE.API,  then make  sure the
  604.      application does not  import any of the APIs from  DOSCALL1.DLL through
  605.      its module definitions file (.DEF), as in the following:
  606.  
  607.      IMPORTS
  608.          DosQueryThreadContext=DOSCALL1.877
  609.  
  610.      If this is indeed the case, change DOSCALL1 to DOSCALLS and rebuild the
  611.      application.  This  will not  affect the  application  as  DOSCALLS and
  612.      DOSCALL1 and  virtually the same  to the application  even though it is
  613.      possible to import APIs from both simultaneously.
  614.  
  615.      Currently OS/2 API Trace only traces DOSCALLS APIs because the standard
  616.      32-bit  OS/2 library,  OS2386.LIB,  does not contain  any references to
  617.      DOSCALL1.
  618.  
  619.   Q: Is there a means for reporting OS/2 API Trace bugs?
  620.  
  621.   A: Yes!  Please send all problem reports to the author,  Dave Blaschke, at
  622.      whichever of the following IDs is most appropriate:
  623.  
  624.      Internal to IBM (Notes) - Dave Blaschke@IBMUS
  625.      Internal to IBM (VM)    - IBMUSM26(BLASCHKE)
  626.      External to IBM         - blaschke@us.ibm.com
  627.  
  628.      or,  if undeliverable,  to deblaschke@yahoo.com.  Comments,  questions,
  629.      and suggestions are also welcome.
  630.  
  631.