home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / os2trace.zip / OS2TRACE.DOC < prev    next >
Text File  |  2001-01-10  |  51KB  |  941 lines
  1.  
  2.  
  3.                          Operating System/2 API Trace
  4.  
  5.   Author       : Dave Blaschke
  6.                  IBM Austin, Texas
  7.                  Internal (Notes) - Dave Blaschke@IBMUS
  8.                  Internal (VM)    - IBMUSM26(BLASCHKE)
  9.                  External         - blaschke@us.ibm.com
  10.  
  11.   Description  : Enables, customizes, controls and summarizes the tracing of
  12.                  OS/2 APIs imported  by a 16-bit  or 32-bit  executable file
  13.                  without affecting its source  code or requiring recompiling
  14.                  or relinking.
  15.  
  16.                  The  first  feat,   trace  enabling,   is  accomplished  by
  17.                  processing  each  entry in  the table of strings within the
  18.                  executable  file that  contains the  names of  the imported
  19.                  DLLs.  If the entry  represents one  of the  supported OS/2
  20.                  DLLs and the  user requested  enablement of API tracing for
  21.                  this  DLL,  the  entry is  replaced  with the  name  of the
  22.                  appropriate  trace  DLL.    When  the  executable  file  is
  23.                  invoked,   the  trace  DLL  intercepts  API  calls  to  its
  24.                  corresponding OS/2 DLL, logs API input information, invokes
  25.                  the API,  and logs  API output  information.  If  the entry
  26.                  represents one  of the  trace DLLs  and the  user requested
  27.                  disablement  of  API  tracing  for this  DLL,  the entry is
  28.                  replaced  with the  name of the  supported OS/2  DLL.  When
  29.                  finished,  the updated table  of strings is  written to the
  30.                  executable file.
  31.  
  32.                  NOTE:   All  private  APIs  are  simply  forwarded  to  the
  33.                  corresponding OS/2 DLL with  no intervention from the trace
  34.                  DLL.
  35.  
  36.                  The  user   can  request   enablement  of  API  tracing  by
  37.                  specifying the -ON option or can request disablement of API
  38.                  tracing  by  specifying  the  -OFF  option.  The  user  can
  39.                  request enablement or disablement of API tracing for one or
  40.                  more of the supported DLLs  individually by specifying each
  41.                  DLL's name  as an  option,  or can  request  enablement  or
  42.                  disablement  of  API  tracing  for all  supported  DLLs  by
  43.                  specifying  the  -ALL  option.  The  user  can  request  to
  44.                  preserve  the  executable  file's date  and  time  stamp by
  45.                  specifying the -P option.
  46.  
  47.                  NOTE:  Trace enablement alters the contents of the table of
  48.                  strings within the executable file  that contains the names
  49.                  of the imported DLLs.  Although this action does not affect
  50.                  the  functionality of  the executable,  it does  affect its
  51.                  date and time stamp unless the -P option is specified.
  52.  
  53.                  The  second feat,  trace customizing,  is  accomplished  by
  54.                  storing the state of the trace customization options in the
  55.                  operating  system's  user profile,  OS2.INI.  The  state of
  56.                  these options can then be  retrieved by the trace DLLs when
  57.                  a trace-enabled executable commences running.
  58.  
  59.                  The user can  request to  log all  trace information  to an
  60.                  alternative directory by specifying the -A s option,  where
  61.                  s is the fully  qualified drive and path  of the directory.
  62.                  The user can  request to log  all trace information  to the
  63.                  default directory (same directory as the .EXE/.COM file) by
  64.                  by specifying the -A NONE option.  The user  can request to
  65.                  log a maximum number of  bytes of level 3 trace information
  66.                  from buffers by  specifying the -B n  option,  where n is a
  67.                  decimal number between 16 and 65536 (64KB),  inclusive, and
  68.                  is rounded up to  the nearest multiple  of 16.  The decimal
  69.                  number can include the 'K' (kilobyte) suffix, in which case
  70.                  the maximum possible value is 64K.  The  user  can  request
  71.                  to log  all  level 3  trace  information  from  buffers  by
  72.                  specifying  the  -B ALL  option.  The user  can  request to
  73.                  enable tracing control  (the -PAUSE and -RESUME options) by
  74.                  specifying  the  -C ON  option.  The  user  can request  to
  75.                  disable tracing  control by specifying the -C OFF option.
  76.  
  77.                  NOTE: When tracing control is enabled,  a thread is created
  78.                  within the application being traced for the sole purpose of
  79.                  monitoring pause  and resume  requests.  If this additional
  80.                  thread  is not  desired for  performance or  other reasons,
  81.                  tracing control should be disabled.
  82.  
  83.                  The user can request to  trace specific groups of APIs from
  84.                  DOSCALLS.DLL by specifying the -D g option,  where g is ALL
  85.                  (request all  API groups),  one or  more of  the  following
  86.                  delimited by commas (request only specific API groups),  or
  87.                  ALL and one  or more  of the  following  each prefixed by a
  88.                  "NO" and delimited  by commas  (request all except specific
  89.                  API groups):
  90.  
  91.                    DEV  indicates trace device API group
  92.                    FILE indicates trace file API group
  93.                    MEM  indicates trace memory API group
  94.                    MISC indicates trace miscellaneous API group
  95.                    MOD  indicates trace module API group
  96.                    MVDM indicates trace MVDM API group
  97.                    NLS  indicates trace national language support API group
  98.                    PIPE indicates trace pipe API group
  99.                    PRF  indicates trace performance API group
  100.                    PROC indicates trace process and thread API group
  101.                    RES  indicates trace resource API group
  102.                    SEM  indicates trace semaphore API group
  103.                    SES  indicates trace session API group
  104.                    TIME indicates trace date/time and timer API group
  105.                    XCPT indicates trace exception API group
  106.                    MSG  indicates trace message API group
  107.                    INFO indicates trace InfoSeg API group
  108.                    SIG  indicates trace signal API group
  109.                    SMP  indicates trace SMP API group
  110.                    PROF indicates trace DosProfile
  111.  
  112.                  The  user   can  request  to   enable  logging   of  EBCDIC
  113.                  translation  of character  buffers by  specifying the -E ON
  114.                  option.  The user can request  to disable logging of EBCDIC
  115.                  translation of  character buffers by  specifying the -E OFF
  116.                  option.
  117.  
  118.                  NOTE:  Logging of  ASCII translation  of character  buffers
  119.                  occurs regardless of the state of the -E option.
  120.  
  121.                  The user can  request to log a  maximum  number of bytes of
  122.                  trace  information  before  log file wrapping  (overwriting
  123.                  from the beginning) occurs by  specifying the  -F n option,
  124.                  where n is a decimal number between 4096 (4KB) and 67108864
  125.                  (64MB),  inclusive,  and  is  rounded  up  to  the  nearest
  126.                  multiple of 4096.  The decimal  number can  include the 'K'
  127.                  (kilobyte) suffix, in which case the maximum possible value
  128.                  is 65536K,  or the 'M' (megabyte) suffix, in which case the
  129.                  maximum possible value is 64M.  The user can request to log
  130.                  all  trace   information  without  log  file   wrapping  by
  131.                  specifying the -F ALL option.
  132.  
  133.                  NOTE:  -F ALL appends trace  information to the  end of any
  134.                  preexisting trace information file,  while -F n  erases the
  135.                  contents of any preexisting trace information file.
  136.  
  137.                  NOTE:  Setting the  log file  wrapping  length to  anything
  138.                  other than ALL  will further impact the  performance of the
  139.                  application being traced, as log file wrapping requires the
  140.                  log file to be unbuffered,  meaning that  trace information
  141.                  cannot be buffered  in a memory cache before  being written
  142.                  to disk.
  143.  
  144.                  The user can request to  trace specific groups of APIs from
  145.                  PMGPI.DLL by  specifying  the -G g  option, where  g is ALL
  146.                  (request all  API groups),  one  or more  of the  following
  147.                  delimited by commas (request only specific API groups),  or
  148.                  ALL and one  or more of  the following  each prefixed  by a
  149.                  "NO" and delimited  by commas  (request all except specific
  150.                  API groups):
  151.  
  152.                    BIT  indicates trace bitmap API group
  153.                    CORR indicates trace correlation API group
  154.                    CTRL indicates trace control API group
  155.                    DEF  indicates trace defaults API group
  156.                    EDIT indicates trace segment editing API group
  157.                    LCID indicates trace LCID API group
  158.                    LCT  indicates trace logical color table API group
  159.                    META indicates trace metafile API group
  160.                    PATH indicates trace path API group
  161.                    POLY indicates trace polygon API group
  162.                    PRIM indicates trace primitive API group
  163.                    RGN  indicates trace region API group
  164.                    SEG  indicates trace segment API group
  165.                    TRAN indicates trace transform API group
  166.                    DEV  indicates trace device API group
  167.  
  168.                  The user can request to  enable interception of dynamic API
  169.                  calls by specifying the -I ON option.  The user can request
  170.                  to disable intercaption of  dynamic API calls by specifying
  171.                  the -I OFF option.  The  user can request  to log  specific
  172.                  levels of  trace information by specifying the -L n option,
  173.                  where n is one of the
  174.                  following:
  175.  
  176.                    1 indicates log API entry/exit information
  177.                    2 indicates log API parameters
  178.                    3 indicates log API parameter contents
  179.  
  180.                  The user can request to enable time stamping of API entries
  181.                  and exits by  specifying the  -T ON  option.  The user  can
  182.                  request to disable  time stamping of API  entries and exits
  183.                  by specifying the -T OFF option.
  184.  
  185.                  NOTE:  API entry time  stamps reflect  entry into the trace
  186.                  API, not entry into the actual OS/2 API.
  187.  
  188.                  The user can request to  trace specific groups of APIs from
  189.                  PMWIN.DLL by  specifying  the -W g  option, where  g is ALL
  190.                  (request all  API groups),  one  or more  of the  following
  191.                  delimited by commas (request only specific API groups),  or
  192.                  ALL and one  or more of  the following  each prefixed  by a
  193.                  "NO" and delimited  by commas  (request all except specific
  194.                  API groups):
  195.  
  196.                    ACCL indicates trace accelerator API group
  197.                    ATOM indicates trace atom API group
  198.                    CLIP indicates trace clipboard API group
  199.                    CTRY indicates trace country API group
  200.                    CUR  indicates trace cursor API group
  201.                    DDE  indicates trace DDE API group
  202.                    DESK indicates trace desktop API group
  203.                    DLG  indicates trace dialog API group
  204.                    DWIN indicates trace WinDefWindowProc
  205.                    ERR  indicates trace error API group
  206.                    FRAM indicates trace frame API group
  207.                    HOOK indicates trace hook API group
  208.                    INPT indicates trace input API group
  209.                    LOAD indicates trace load API group
  210.                    MENU indicates trace menu API group
  211.                    MSG  indicates trace message API group  (does not include
  212.                         MSGL group)
  213.                    MSGL indicates trace WinDispatchMsg and WinGetMsg
  214.                    PAL  indicates trace palette API group
  215.                    PTR  indicates trace pointer API group
  216.                    RECT indicates trace rectangle API group
  217.                    SYS  indicates trace system API group
  218.                    THK  indicates trace thunk API group
  219.                    TIME indicates trace time API group
  220.                    TREC indicates trace track rectangle API group
  221.                    WIN  indicates trace window API group  (does not  include
  222.                         DWIN group)
  223.                    ENV  indicates trace WinCatch and WinThrow
  224.                    HEAP indicates trace heap API group
  225.                    SEI  indicates trace set error info API group
  226.  
  227.                  NOTE:  DWIN and MSGL are separated from WIN and MSG because
  228.                  these  APIs,  when being  traced,  can severely  impact the
  229.                  performance of the trace-enabled executable.
  230.  
  231.                  The user can  request to  display the  current state of the
  232.                  trace customization options stored in OS2.INI by specifying
  233.                  the -Q option.
  234.  
  235.                  NOTE:   No  changes  are made  to the  state  of  the trace
  236.                  customization options stored in OS2.INI if the -Q option is
  237.                  specified,  even if other customization options are present
  238.                  on the command line.
  239.  
  240.                  The  third feat,  trace  controlling,  is  accomplished  by
  241.                  creating a thread within the  application being traced that
  242.                  awaits  pause  and resume  requests.  When  such  a request
  243.                  arrives the thread awakens,  pauses or resumes tracing, and
  244.                  goes back to sleep awaiting the next request.
  245.  
  246.                  The  user can  request to pause  tracing by  specifying the
  247.                  -PAUSE option.  The user  can request to  resume tracing by
  248.                  specifying the -RESUME option.
  249.  
  250.                  NOTE:  In order for  the -PAUSE  and -RESUME  options to be
  251.                  effective on a  trace-enabled  executable,  tracing control
  252.                  must be enabled by  specifying the -C ON  option before the
  253.                  executable commences running.
  254.  
  255.                  NOTE:  A trace-enabled  executable  can  be  started  while
  256.                  tracing is paused, as the state of the trace control option
  257.                  is stored in OS2.INI  and retrieved by the  trace DLLs when
  258.                  the executable commences running.
  259.  
  260.                  The  fourth feat,  trace  summarizing,  is  accomplished by
  261.                  parsing  the   trace  information   file  generated   by  a
  262.                  trace-enabled  executable and  recording the  number of API
  263.                  entries and exits  logged in the file.  When finished,  the
  264.                  summary statistics  are displayed in  alphabetical order to
  265.                  standard output.
  266.  
  267.                  The user  can request to summarize  the contents of a trace
  268.                  information file by specifying the -S option.
  269.  
  270.                  The user can request helping  information by specifying the
  271.                  -?, -H, or -HELP option.
  272.  
  273.                  OS/2 API Trace works on all 32-bit versions of OS/2:
  274.  
  275.                                                      |  Major  |  Minor
  276.                  Name                                | Version | Version
  277.                  ------------------------------------+---------+---------
  278.                  OS/2 Version 2.0x                   |    20   |    0x
  279.                  OS/2 Version 2.1x                   |    20   |    1x
  280.                  OS/2 Warp Version 3                 |    20   |    30
  281.                  OS/2 Warp Version 4                 |    20   |    40
  282.                  OS/2 Warp Server for e-business     |    20   |    45
  283.                  OS/2 Warp Connect (PowerPC Edition) |    30   |    00
  284.  
  285.                  where major and minor versions are the corresponding values
  286.                  returned from DosQuerySysInfo.  Note that the  ELF versions
  287.                  of the executables  and trace DLLs  are required  to run on
  288.                  OS/2 Warp Connect (PowerPC Edition).
  289.  
  290.   Installation : Place the executables,  OS2TRACE.EXE and PMOS2TRC.EXE, in a
  291.                  directory  along the PATH  environment variable,  place the
  292.                  help  file,  PMOS2TRC.HLP,  in a  directory along  the HELP
  293.                  environment variable, and place the trace DLLs, T_*.DLL, in
  294.                  a directory along the system LIBPATH.
  295.  
  296.   Usage        : Trace enabler -
  297.  
  298.                  OS2TRACE -OFF|-ON {-ALL|-dll}... [-P] file
  299.  
  300.                  Where:
  301.                    -OFF indicates disable API tracing
  302.                    -ON  indicates enable API tracing
  303.                    -ALL indicates enable/disable API tracing for all DLLs
  304.                    -dll indicates  enable/disable  API tracing  for specific
  305.                         DLL, where dll can be one of the following:
  306.                           DOSCALLS  HELPMGR   KBDCALLS  MONCALLS  MOUCALLS
  307.                           MSG       NAMPIPES  NLS       PMBIDI    PMCTLS
  308.                           PMDRAG    PMGPI     PMMERGE   PMPIC     PMSHAPI
  309.                           PMSPL     PMVIOP    PMWIN     PMWP      QUECALLS
  310.                           SESMGR    VIOCALLS
  311.                    -P   indicates preserve executable file date/time stamp
  312.                    file indicates  name  of  executable  file  to  be  trace
  313.                         enabled/disabled
  314.  
  315.                  NOTE:     Trace  enablement  alters  the  contents  of  the
  316.                  executable file's import module name table.
  317.  
  318.                  In  the following example,  tracing is enabled  in TEST.EXE
  319.                  for  the  APIs  imported  from  QUECALLS  and  SESMGR,  and
  320.                  TEST.EXE's date and time stamp is preserved:
  321.  
  322.                  OS2TRACE -ON -QUECALLS -SESMGR -P TEST.EXE
  323.  
  324.                  In  the following example,  tracing is disabled in TEST.EXE
  325.                  for the APIs imported from all supported DLLs:
  326.  
  327.                  OS2TRACE -OFF -ALL TEST.EXE
  328.  
  329.                  Trace customizer -
  330.  
  331.                  OS2TRACE {-A s|-B n|-C f|-D g|-E f|-F n|
  332.                            -G g|-I f|-L n|-Q|-T f|-W g}...
  333.  
  334.                  Where:
  335.                    -A s indicates   fully   qualified  drive   and  path  of
  336.                         alternative  logging  directory or  NONE for default
  337.                         directory
  338.                    -B n indicates log maximum of n bytes from buffers, where
  339.                         16 ≤ n ≤ 65536  (K suffix allowed)  or n is  ALL  to
  340.                         indicate log all bytes from buffers
  341.                    -C f indicates  enable  (f = ON)   or  disable  (f = OFF)
  342.                         tracing control (-PAUSE and -RESUME options)
  343.                    -D g indicates trace specific DOSCALLS API groups,  where
  344.                         g is either ALL[,NOgrp]...  or grp[,grp]...  and grp
  345.                         is one of the following:
  346.                           DEV       FILE      MEM       MISC      MOD
  347.                           MVDM      NLS       PIPE      PRF       PROC
  348.                           RES       SEM       SES       TIME      XCPT
  349.                           MSG       INFO      SIG       SMP       PROF
  350.                    -E f indicates  enable  (f = ON)   or  disable  (f = OFF)
  351.                         logging of EBCDIC translation of character buffers
  352.                    -F n indicates  log maximum  of n  bytes before  log file
  353.                         wrapping occurs,  where 4096 ≤ n ≤ 67108864  (K or M
  354.                         suffixes allowed)  or n is  ALL  to indicate log all
  355.                         information without log file wrapping
  356.                    -G g indicates  trace  specific  PMGPI API groups,  where
  357.                         g is either ALL[,NOgrp]...  or grp[,grp]...  and grp
  358.                         is one of the following:
  359.                           BIT       CORR      CTRL      DEF       EDIT
  360.                           LCID      LCT       META      PATH      POLY
  361.                           PRIM      RGN       SEG       TRAN      DEV
  362.                           INK
  363.                    -I f indicates  enable  (f = ON)   or  disable  (f = OFF)
  364.                         interception of dynamic API calls
  365.                    -L n indicates log level n information, where 1 ≤ n ≤ 3:
  366.                           1 indicates log API entry/exit information
  367.                           2 indicates log API parameters
  368.                           3 indicates log API parameter contents
  369.                    -Q   indicates query current trace customization options
  370.                    -T f indicates enable (f = ON)  or disable (f = OFF) time
  371.                         stamping of API entries and exits
  372.                    -W g indicates  trace  specific  PMWIN API groups,  where
  373.                         g is either ALL[,NOgrp]...  or grp[,grp]...  and grp
  374.                         is one of the following:
  375.                           ACCL      ATOM      CLIP      CTRY      CUR
  376.                           DDE       DESK      DLG       ERR       FRAM
  377.                           HOOK      INPT      LOAD      MENU      MSG
  378.                           PAL       PTR       RECT      SYS       THK
  379.                           TIME      TREC      WIN       ENV       HEAP
  380.                           SEI
  381.  
  382.                  NOTE: The default trace customization option settings are:
  383.  
  384.                  -A NONE
  385.                  -B 256
  386.                  -C OFF
  387.                  -D ALL
  388.                  -E OFF
  389.                  -F ALL
  390.                  -G ALL
  391.                  -I OFF
  392.                  -L 1
  393.                  -T OFF
  394.                  -W ALL
  395.  
  396.                  In the following example,  tracing is customized to log all
  397.                  trace information to the D:\TRACELOG directory.
  398.  
  399.                  OS2TRACE -A D:\TRACELOG
  400.  
  401.                  In the  following  example,  tracing is  customized  to log
  402.                  a maximum of  512 bytes of  level 3 trace information  from
  403.                  buffers:
  404.  
  405.                  OS2TRACE -B 512
  406.  
  407.                  In the  following example,  tracing is customized to enable
  408.                  tracing control (-PAUSE/-RESUME options):
  409.  
  410.                  OS2TRACE -C ON
  411.  
  412.                  In the  following example,  tracing is customized  to trace
  413.                  only memory and semaphore API groups from DOSCALLS.DLL:
  414.  
  415.                  OS2TRACE -D MEM,SEM
  416.  
  417.                  In the  following example,  tracing is customized to enable
  418.                  logging of EBCDIC translation of character buffers:
  419.  
  420.                  OS2TRACE -E ON
  421.  
  422.                  In the  following  example,  tracing is  customized  to log
  423.                  a maximum of 16384 (16K) bytes of  trace information before
  424.                  log file wrapping occurs:
  425.  
  426.                  OS2TRACE -F 16K
  427.  
  428.                  In the  following example,  tracing is customized  to trace
  429.                  only  bitmap,  metafile,  and  transform  API  groups  from
  430.                  PMGPI.DLL:
  431.  
  432.                  OS2TRACE -G BIT,META,TRAN
  433.  
  434.                  In the  following example,  tracing is customized to enable
  435.                  interception of dynamic API calls:
  436.  
  437.                  OS2TRACE -I ON
  438.  
  439.                  In the  following  example,  tracing is  customized  to log
  440.                  level 2 information:
  441.  
  442.                  OS2TRACE -L 2
  443.  
  444.                  In the  following example,  the current state  of the trace
  445.                  customization options stored in OS2.INI is displayed:
  446.  
  447.                  OS2TRACE -Q
  448.  
  449.                  In the  following example,  tracing is customized to enable
  450.                  time stamping of API entries/exits:
  451.  
  452.                  OS2TRACE -T ON
  453.  
  454.                  In the  following example,  tracing is customized  to trace
  455.                  all except hook and system API groups from PMWIN.DLL:
  456.  
  457.                  OS2TRACE -W ALL,NOHOOK,NOSYS
  458.  
  459.                  Trace controller -
  460.  
  461.                  OS2TRACE -PAUSE|-RESUME
  462.  
  463.                  Where:
  464.                    -PAUSE  indicates pause API tracing
  465.                    -RESUME indicates resume API tracing
  466.  
  467.                  In the following  example, tracing is paused:
  468.  
  469.                  OS2TRACE -PAUSE
  470.  
  471.                  In the following  example, tracing is resumed:
  472.  
  473.                  OS2TRACE -RESUME
  474.  
  475.                  Trace summarizer -
  476.  
  477.                  OS2TRACE -S file
  478.  
  479.                  Where:
  480.                    -S   indicates summarize API tracing
  481.                    file indicates name of trace information file to be trace
  482.                         summarized
  483.  
  484.                  In the following example, tracing in TEST.TRC is summarized
  485.                  and placed in TEST.SUM:
  486.  
  487.                  OS2TRACE -S TEST.TRC > TEST.SUM
  488.  
  489.   Scenario     : The following  example shows a  typical scenario  where the
  490.                  several personalities of OS2TRACE can be used in conjuction
  491.                  to produce a summary of NLS APIs used by TEST.EXE:
  492.  
  493.                  OS2TRACE -D NLS -L 1
  494.                  OS2TRACE -ON -DOSCALLS -NLS TEST.EXE
  495.                  TEST
  496.                  OS2TRACE -OFF -DOSCALLS -NLS TEST.EXE
  497.                  OS2TRACE -S TEST.TRC > TEST.NLS
  498.  
  499.                  The first  line  customizes  API tracing,  the second  line
  500.                  enables API tracing, the third line invokes the executable,
  501.                  which places  all its API tracing  information in TEST.TRC,
  502.                  the fourth line  disables API tracing,  and the fifth  line
  503.                  summarizes API tracing.
  504.  
  505.   Output       : Trace enabler -
  506.  
  507.                  If  the  user  requests  enablement  of  API  tracing  (-ON
  508.                  option),  information similar to the following is displayed
  509.                  for each requested  DLL that is imported  by the executable
  510.                  file:
  511.  
  512.                  DLLNAME : File imports from DLL, API tracing enabled
  513.  
  514.                  information similar to the  following is displayed for each
  515.                  requested DLL  whose trace DLL  is already imported  by the
  516.                  executable file:
  517.  
  518.                  DLLNAME : File imports from trace DLL,  API tracing already
  519.                            enabled
  520.  
  521.                  information similar to the  following is displayed for each
  522.                  requested DLL that is not imported by the executable file:
  523.  
  524.                  DLLNAME : File does not  import from DLL,  API  tracing not
  525.                            enabled
  526.  
  527.                  information similar to the  following is displayed for each
  528.                  requested DLL that has an  unsupported API name imported by
  529.                  the executable file:
  530.  
  531.                  DLLNAME : File imports APINAME by name,  API tracing cannot
  532.                            be enabled
  533.  
  534.                  and information similar  to the following  is displayed for
  535.                  each requested DLL that has an unsupported ordinal imported
  536.                  by the executable file:
  537.  
  538.                  DLLNAME : File imports  unsupported ordinal N,  API tracing
  539.                            cannot be enabled
  540.  
  541.                  If  the  user  requests disablement  of  API tracing  (-OFF
  542.                  option),  information similar to the following is displayed
  543.                  for  each  requested  trace  DLL that  is imported  by  the
  544.                  executable file:
  545.  
  546.                  DLLNAME : File imports from trace DLL, API tracing disabled
  547.  
  548.                  information similar to the  following is displayed for each
  549.                  requested trace DLL  whose DLL  is already imported  by the
  550.                  executable file:
  551.  
  552.                  DLLNAME : File  imports  from  DLL,   API  tracing  already
  553.                            disabled
  554.  
  555.                  and information  similar to the following  is displayed for
  556.                  each  requested  trace DLL  that is  not  imported  by  the
  557.                  executable file:
  558.  
  559.                  DLLNAME : File does not import from trace DLL,  API tracing
  560.                            not disabled
  561.  
  562.                  Trace customizer -
  563.  
  564.                  If the user requests customization of API tracing  (-A, -B,
  565.                  -C,  -D,  -E,  -F,  -G,  -I,  -L,  -T, and/or  -W options),
  566.                  information similar to the following is displayed:
  567.  
  568.                  Old trace customization options:
  569.                    -A D:\ -B 64 -C OFF -D ALL -E ON -F 8192 -G DEV,INK ...
  570.                  New trace customization options:
  571.                    -A NONE -B 256 -C ON -D MEM,SEM -E ON -F ALL -G ALL ...
  572.  
  573.                  The  first  two  lines  contain  the  state  of  the  trace
  574.                  customization  options prior to the invocation of  OS2TRACE
  575.                  while  the last two lines  contain the  state of  the trace
  576.                  customization options after the invocation of OS2TRACE.
  577.  
  578.                  Trace controller -
  579.  
  580.                  If  the  user  requests  pausing  of  API  tracing  (-PAUSE
  581.                  option),  information similar to the following is displayed
  582.                  if tracing  is not  already  paused  and there  are  active
  583.                  trace-enabled applications  that were started while tracing
  584.                  control was enabled (-C ON option):
  585.  
  586.                  Tracing paused
  587.                    C:\OS2\E.EXE (PID 0F1C) paused
  588.  
  589.                  information  similar  to  the  following  is  displayed  if
  590.                  tracing  is not  already  paused  and  there  are no active
  591.                  trace-enabled applications there were started while tracing
  592.                  control was enabled (-C ON option):
  593.  
  594.                  Tracing paused
  595.                    No active trace-enabled applications
  596.  
  597.                  and information  similar  to the following  is displayed if
  598.                  tracing is already paused:
  599.  
  600.                  Tracing already paused
  601.  
  602.                  If the  user  requests resuming  of  API  tracing  (-RESUME
  603.                  option),  information similar to the following is displayed
  604.                  if tracing  is not  already resumed  and there  are  active
  605.                  trace-enabled applications  that were started while tracing
  606.                  control was enabled (-C ON option):
  607.  
  608.                  Tracing resumed
  609.                    C:\OS2\E.EXE (PID 0F1C) resumed
  610.  
  611.                  information  similar  to  the  following  is  displayed  if
  612.                  tracing  is not  already resumed  and  there  are no active
  613.                  trace-enabled applications there were started while tracing
  614.                  control was enabled (-C ON option):
  615.  
  616.                  Tracing resumed
  617.                    No active trace-enabled applications
  618.  
  619.                  and information  similar  to the following  is displayed if
  620.                  tracing is already resumed:
  621.  
  622.                  Tracing already resumed
  623.  
  624.                  Trace summarizer -
  625.  
  626.                  If the user  requests  summarization  of the  contents of a
  627.                  trace information file (-S option),  information similar to
  628.                  the following is displayed:
  629.  
  630.                  Used APIs:
  631.                    APINAME (12 Pass, 4 Fail, 1 Indeterminate, 2 No Return)
  632.  
  633.                  Each line contains the name of the used API,  the number of
  634.                  successful invocations, if any,  the number of unsuccessful
  635.                  invocations,    if  any,    the  number  of   indeterminate
  636.                  invocations, if any,  and the number of API entries without
  637.                  matching  exits  (indicated  by  "No Return"),  if any.  It
  638.                  should be noted that these  APIs are listed in alphabetical
  639.                  order.
  640.  
  641.                  NOTE:    A  warning  message  is  issued  if  summarization
  642.                  information  may   not  be   accurate  due   to  lost   API
  643.                  entries/exits, pausing/resuming trace, or file wrapping.
  644.  
  645.                  Trace-enabled executable -
  646.  
  647.                  All levels of information, from the trace-enabled .EXE/.COM
  648.                  and/or any  trace-enabled  .DLLs that  are attached  to the
  649.                  .EXE/.COM,  are logged to a text file with a file name that
  650.                  matches the  .EXE/.COM file name and  an extension of .TRC.
  651.                  This trace information  file resides in the  same directory
  652.                  as the .EXE/.COM  file or the alternative directory, if one
  653.                  exists.  If  another  instance  of the  same  .EXE/.COM  is
  654.                  already  running or  the text  file  is already open in the
  655.                  alternative directory, the file  name of the  text file  is
  656.                  changed  to  PROC  followed   by  the  hexadecimal  process
  657.                  identifier (i.e. PROC003A.TRC).   If this occurs, a warning
  658.                  message is issued.
  659.  
  660.                  NOTE:  If a REXX program loads any trace-enabled .DLLs, all
  661.                  trace  information  is  logged  to   CMD.TRC  in  the  same
  662.                  directory  as the  CMD.EXE executable  that loaded the REXX
  663.                  program or the alternative directory, if one exists.
  664.  
  665.                  If the user requests  level 1 information,  data similar to
  666.                  the following is logged for each API call:
  667.  
  668.                  003A 0001 | Dos32CreateQueue Entry
  669.  
  670.                  003A 0001 | Dos32CreateQueue Exit
  671.                       PASS | Return code: 0
  672.  
  673.                  If the user requests  level 2 information,  data similar to
  674.                  the following is logged for each API call:
  675.  
  676.                  003A 0001 | Dos32CreateQueue Entry
  677.                            | Parameter 1: PHQUEUE = 0x00028BE8
  678.                            | Parameter 2: ULONG = 0x00000002
  679.                            | Parameter 3: PSZ = 0x000200A4
  680.  
  681.                  003A 0001 | Dos32CreateQueue Exit
  682.                       PASS | Return code: 0
  683.                            | Parameter 1: PHQUEUE = 0x00028BE8
  684.  
  685.                  If the user requests  level 3 information,  data similar to
  686.                  to the following is logged for each API call:
  687.  
  688.                  003A 0001 | Dos32CreateQueue Entry, Return Address =...
  689.                            | Parameter 1: PHQUEUE = 0x00028BE8
  690.                            | Parameter 2: ULONG = 0x00000002
  691.                            | Parameter 3: PSZ = 0x000200A4 ["\QUEUES\..."]
  692.  
  693.                  003A 0001 | Dos32CreateQueue Exit
  694.                       PASS | Return code: 0 (NO_ERROR)
  695.                            | Parameter 1: PHQUEUE = 0x00028BE8 [0x00000007]
  696.  
  697.                  The first number  on both  the API entry  and exit lines is
  698.                  the hexadecimal process identifier (PID) of the executable.
  699.                  The  second  number is the  hexadecimal  thread  identifier
  700.                  (TID) of  the thread within the executable that invoked the
  701.                  API.
  702.  
  703.                  If the user requests  level 3 information  and a character,
  704.                  ASCIIZ  string,  integer,  color,   FIXED,  POINTL,  RECTL,
  705.                  WPOINT,  or user-defined buffer is  larger than the maximum
  706.                  specified by the -B n  option,  the  data is  truncated and
  707.                  -- More -- is logged.
  708.  
  709.                  If log  file wrapping  occurs,  information similar  to the
  710.                  following is  logged after the executable's  stopping time,
  711.                  OS2TRACE banner, and executable's starting time:
  712.  
  713.                  < Trace information lost due to log file wrapping n times >
  714.  
  715.                  If the length of an API's entry/exit information is greater
  716.                  than the log file  wrapping length,  information similar to
  717.                  the following is logged in lieu of the entry/exit:
  718.  
  719.                  < API entry/exit information lost >
  720.  
  721.                  If  interception   of   dynamic  API   calls   is  enabled,
  722.                  information  similar to the following is  logged after each
  723.                  Dos16GetProcAddr and/or  Dos32QueryProcAddr call that loads
  724.                  an API within a supported DLL that is enabled for tracing:
  725.  
  726.                  < Intercepting ordinal n in module DLLNAME >
  727.  
  728.                  NOTE:  Dos16GetProcAddr and  Dos32QueryProcAddr do NOT have
  729.                  to be traced in order to  intercept dynamic API calls,  but
  730.                  DOSCALLS must be enabled for tracing.
  731.  
  732.                  If the user  requests to trace  the DOSCALLS SMP API  group
  733.                  and the version of OS/2 is not the multiprocessing version,
  734.                  information similar  to the following  is logged after each
  735.                  SMP API call:
  736.  
  737.                  < Returning n for API not present on this version of OS/2 >
  738.  
  739.                  If the user requests  to trace the  DOSCALLS SEM API  group
  740.                  and a semaphore API removed  by the Convenience Package for
  741.                  Warp Server for e-business is called,  information  similar
  742.                  to the following is logged:
  743.  
  744.                  < Returning n for API removed by WSeB Convenience Package >
  745.  
  746.                  If tracing is paused when the executable commences running,
  747.                  information similar to the following is logged:
  748.  
  749.                  < Tracing initially paused >
  750.  
  751.                  If tracing  is  paused  while  the  executable  is running,
  752.                  information similar to the following is logged:
  753.  
  754.                  < Pausing trace at nn:nn:nn.nn >
  755.  
  756.                  If tracing  is resumed  while  the  executable  is running,
  757.                  information similar to the following is logged:
  758.  
  759.                  < Resuming trace at nn:nn:nn.nn >
  760.  
  761.                  All  warning   and  error   messages   generated   by   the
  762.                  trace-enabled  executable  are placed in the  error message
  763.                  file OS2TRACE.ERR  in the  root  directory of the operating
  764.                  system's  boot drive in order  to avoid conflicts  with the
  765.                  executable's output.
  766.  
  767.   History      : Version Date    Item
  768.                  2.30.00 12Jun95 Created (supported LX format and 32-bit Dos
  769.                                  APIs only)
  770.                  2.30.01 09Jul95 Issued warning if trace DLL not on LIBPATH
  771.                  2.30.02 18Jul95 Added optional "NO" prefix to API groups
  772.                  2.30.03 20Jul95 Added 32-bit Win APIs
  773.                  2.30.04 28Jul95 Fixed integer buffer logging
  774.                  2.30.05 04Aug95 Added 32-bit Gpi APIs
  775.                  2.30.06 09Aug95 Fixed Dos32DevIOCtl bug
  776.                  2.30.07 11Aug95 Changed to new build structure
  777.                  2.30.08 11Aug95 Added 32-bit Ddf APIs
  778.                  2.30.09 12Aug95 Added 32-bit Dev APIs
  779.                  2.30.10 13Aug95 Added 32-bit Drg APIs
  780.                  2.30.11 14Aug95 Added 32-bit Prf APIs
  781.                  2.30.12 25Aug95 Fixed Dos32QueryMessageCP bug
  782.                  2.30.13 27Aug95 Added OS/2 for PowerPC support
  783.                  2.30.14 29Aug95 Added 32-bit Prt and Spl APIs
  784.                  2.30.15 29Aug95 Added 32-bit Pic APIs
  785.                  2.30.16 22Sep95 Enhanced -B option
  786.                  2.30.17 22Sep95 Added -F option
  787.                  2.30.18 24Sep95 Added -T option
  788.                  2.30.19 02Nov95 Fixed Drg32DragFiles bug
  789.                  2.30.20 27Nov95 Added support for  Dos APIs  in  MSG,  NLS,
  790.                                  QUECALLS, and SESMGR exported by DOSCALLS
  791.                  2.30.21 13Dec95 Forwarded private entry table ordinals
  792.                  2.30.22 19Dec95 Added new OS/2 3.00 non-Uni Dos APIs
  793.                  2.30.23 27Mar96 Fixed PMWIN bugs
  794.                  2.30.24 29Mar96 Added PM interface (supported customization
  795.                                  and help only)
  796.                  2.30.25 15Apr96 Verified DOS header new header file address
  797.                  2.30.26 23May96 Issued more specific enablement messages
  798.                  2.30.27 13Jun96 Logged FEA2 structure EA value
  799.                  2.30.28 14Jun96 Changed "\r\n" to "\n" in output
  800.                  2.30.29 21Jun96 Fixed Dos32UnwindException bug
  801.                  2.30.30 26Jun94 Added OS/2 2.00 PM debugger APIs
  802.                  2.40.00 05Sep96 Added new OS/2 2.40 APIs
  803.                  2.40.01 27Sep96 Fixed customization information display bug
  804.                  2.40.02 11Mar97 Removed  loading/unloading  trace DLLs from
  805.                                  .EXE
  806.                  2.40.03 11Mar97 Converted to IBM VisualAge C++
  807.                  2.40.04 12Mar97 Fixed OS/2 for PowerPC DLL support
  808.                  2.40.05 12Mar97 Added enablement support to PM interface
  809.                  2.40.06 12Mar97 Fixed Win32EnumObjectClasses bug
  810.                  2.40.07 13Mar97 Added customization cancel confirmation
  811.                  2.40.08 13Mar97 Added summarization support to PM interface
  812.                  2.40.09 14Mar97 Removed  summarization   API  exit  without
  813.                                  entry error
  814.                  2.40.10 14Mar97 Fixed Dev32StdOpen bug
  815.                  2.40.11 19Mar97 Added  save  window  position  option to PM
  816.                                  interface
  817.                  2.40.12 19Mar97 Added support for NE format
  818.                  2.40.13 20Mar97 Added  launch   .EXE  files  option  to  PM
  819.                                  interface
  820.                  2.40.14 25Mar97 Fixed DENA2 buffer logging
  821.                  2.40.15 01Apr97 Fixed Dos32FindFirst bug
  822.                  2.40.16 15Apr97 Removed OS/2 for PowerPC from PM help
  823.                  2.40.17 21Apr97 Added 16-bit Dos APIs
  824.                  2.40.18 30Apr97 Added 16-bit Kbd APIs
  825.                  2.40.19 01May97 Added 16-bit Mou APIs
  826.                  2.40.20 05May97 Added 16-bit Vio APIs
  827.                  2.40.21 20May97 Fixed/minimized 16-bit stack usage
  828.                  2.40.22 22May97 Added FAQ
  829.                  2.40.23 27May97 Linked .EXEs with proper threaded C library
  830.                  2.40.24 03Jun97 Added FAQ to PM interface help submenu
  831.                  2.40.25 04Jun97 Fixed 16-bit registers structure init bug
  832.                  2.40.26 24Jun97 Added 16-bit Win APIs
  833.                  2.40.27 22Jul97 Added 16-bit Gpi APIs
  834.                  2.40.28 06Aug97 Added 16-bit Dev APIs
  835.                  2.40.29 07Aug97 Added 16-bit Drg APIs
  836.                  2.40.30 08Aug97 Added 16-bit Pic APIs
  837.                  2.40.31 08Aug97 Logged user-defined buffer initial bytes
  838.                  2.40.32 11Aug97 Added 16-bit Prf APIs
  839.                  2.40.33 11Aug97 Added 16-bit Prt APIs
  840.                  2.40.34 13Aug97 Added 16-bit DosPrint and Spl APIs
  841.                  2.40.35 13Aug97 Fixed Spl32EnumDevice/Spl32EnumQueue bug
  842.                  2.40.36 14Aug97 Added -I option
  843.                  2.40.37 15Aug97 Fixed Vio16GetPhysBuf bug
  844.                  2.40.38 15Aug97 Added TRACE-IT batch file
  845.                  2.40.39 17Sep97 Fixed 16-bit DosProtect APIs bug
  846.                  2.40.40 12Jan98 Enhanced performance
  847.                  2.40.41 12Jan98 Fixed Dos16GetInfoSeg bug
  848.                  2.40.42 23Jan98 Added PRQINFO8 structure
  849.                  2.40.43 23Jan98 Fixed Dos16PrintQSetInfo/Spl32SetQueue bug
  850.                  2.40.44 27Jan98 Fixed returned MRESULT thunk bug
  851.                  2.40.45 28Jan98 Added indeterminate API return codes
  852.                  2.40.46 28Jan98 Fixed summarization alphabetical API bug
  853.                  2.40.47 29Jan98 Added Win16DefAVioWindowProc
  854.                  2.40.48 30Jan98 Fixed Win16Catch bug
  855.                  2.40.49 04Feb98 Added OS2TRACE.API text file
  856.                  2.40.50 06Feb98 Fixed CX and DX  corruption by  16-bit Kbd,
  857.                                  Mou, and Vio APIs
  858.                  2.40.51 18Feb98 Verified saved  window  position  origin on
  859.                                  desktop
  860.                  2.40.52 16Mar98 Fixed file dialog root directory bug
  861.                  2.40.53 16Mar98 Fixed file dialog clean up bug
  862.                  2.40.54 16Mar98 Changed main window identifier to 1
  863.                  2.40.55 02Jun98 Fixed DevQueryHardcopyCaps bug
  864.                  2.40.56 02Jun98 Changed default selection  for cancellation
  865.                                  dialog to "No"
  866.                  2.40.57 25Jun98 Added trace-enabled executable checker
  867.                  2.40.58 01Jul98 Added version checking to trace DLLs
  868.                  2.40.59 06Jul98 Added bitmaps of dialogs to PM help
  869.                  2.40.60 08Jul98 Added  title/action  bar only  option to PM
  870.                                  interface
  871.                  2.40.61 17Aug98 Added SMP Dos APIs
  872.                  2.40.62 18Aug98 Removed  unnecesary  semaphore  nesting  in
  873.                                  DosFindFirst/DosFindClose
  874.                  2.40.63 19Aug98 Fixed -F option
  875.                  2.40.64 21Aug98 Added bitmap of logo to PM help
  876.                  2.40.65 28Aug98 Added monitor trace options to PM interface
  877.                  2.40.66 09Sep98 Added private profile Dos APIs
  878.                  2.40.67 24Sep98 Removed unloading trace DLLs from .DLLs
  879.                  2.40.68 12Oct98 Fixed/enhanced helping information
  880.                  2.40.69 21Oct98 Forwarded removed entry table ordinals
  881.                  2.40.70 21Oct98 Added miscellaneous Dos APIs
  882.                  2.40.71 22Oct98 Added PM AVIO Vio APIs
  883.                  2.40.72 22Oct98 Moved Prt/Spl APIs loading to OS/2 2.30
  884.                  2.40.73 26Oct98 Fixed   Dos32GetMessage/Dos32QueryMessageCP
  885.                                  bug
  886.                  2.40.74 27Oct98 Added WinSetErrorInfo
  887.                  2.40.75 28Oct98 Added Gpi/Win APIs exported from PMBIDI
  888.                  2.40.76 28Oct98 Issued more specific trace DLL load errors
  889.                  2.40.77 28Oct98 Added Win32MessageBox2
  890.                  2.40.78 16Nov98 Added miscellaneous Dos APIs
  891.                  2.40.79 24Nov98 Fixed Dos32QueryModFromEIP usage bug
  892.                  2.40.80 02Dec98 Added undocumented -DUMPSTACK option
  893.                  2.40.81 02Dec98 Added -E option
  894.                  2.40.82 07Dec98 Fixed stack dump at DosExit bug
  895.                  2.40.83 12Jan99 Enhanced trace monitoring
  896.                  2.40.84 20Jan99 Fixed monitor trace options dialogs bugs
  897.                  2.40.85 21Jan99 Added -P option
  898.                  2.40.86 03Mar99 Added support  for executables  without DOS
  899.                                  header
  900.                  2.40.87 23Mar99 Fixed 16-bit SMP Dos APIs loading bug
  901.                  2.45.00 15Apr99 Added new OS/2 2.45 APIs
  902.                  2.45.01 02May99 Added  support for  Gpi/Win APIs  in PMGPI,
  903.                                  PMSHAPI, and PMWIN exported by PMMERGE
  904.                  2.45.02 02May99 Fixed WinQueryWindowText bug
  905.                  2.45.03 02May99 Added   support  for  Drg  APIs  in  PMDRAG
  906.                                  exported by PMCTLS
  907.                  2.45.04 05May99 Added -Q option
  908.                  2.45.05 09May99 Added support for  K and M  suffixes to  -B
  909.                                  and -F options
  910.                  2.45.06 16May99 Added support for  KB and MB  values to  PM
  911.                                  interface
  912.                  2.45.07 21May99 Fixed Dos32Debug bug
  913.                  2.45.08 11Jun99 Added support for .COM files
  914.                  2.45.09 11Jun99 Logged Dos16DevIOCtl(2) output buffers
  915.                  2.45.10 02Aug99 Moved common strings into T_COMMON
  916.                  2.45.11 03Aug99 Logged name of module  containing API being
  917.                                  intercepted
  918.                  2.45.12 01Feb00 Displayed customization options on new line
  919.                  2.45.13 01Feb00 Logged PID in errors and warnings
  920.                  2.45.14 02Feb00 Saved OS2.INI information only when changed
  921.                  2.45.15 08Feb00 Standardized output
  922.                  2.45.16 18Feb00 Added -C, -PAUSE, and -RESUME options
  923.                  2.45.17 21Feb00 Added restore window  position option to PM
  924.                                  interface
  925.                  2.45.18 28Feb00 Removed import by name restriction
  926.                  2.45.19 29Feb00 Fixed  trace monitoring without  background
  927.                                  font
  928.                  2.45.20 29Feb00 Fixed control semaphore IPE under OS/2 2.00
  929.                  2.45.21 29Feb00 Fixed resizing main window with zero height
  930.                                  twice during trace monitoring
  931.                  2.45.22 01Mar00 Removed  drawing  background font if bitmap
  932.                                  calculation too long
  933.                  2.45.23 24May00 Handled running out of disk space
  934.                  2.45.24 01Jun00 Added -A option
  935.                  2.45.25 03Jun00 Added trace information file API stripper
  936.                  2.45.26 10Jan01 Handled OS/2 2.45 APIs removed by WSeB CP
  937.  
  938.   Please direct all comments,  problems,  questions,  and suggestions to the
  939.   author above, or, if undeliverable, to deblaschke@yahoo.com.
  940.  
  941.