home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / trspol41.zip / trspool.doc next >
Text File  |  1998-09-25  |  8KB  |  192 lines
  1. TRSPOOL Copyright (C) 1995 IBM UK Ltd
  2. Author: Richard Moore
  3. Date 25 Sep 1998
  4.  
  5. version 4.1
  6.  
  7. TRSPOOL extends the usefulness of the OS/2 system trace facility
  8. by capturing the single system trace buffer and spooling it a 
  9. cyclically used sequence of disk files.  The captured trace disk files
  10. may be later formatted using TRACEFMT, by selecting the Open option of
  11. the File menu.
  12.  
  13. TRSPOOL operates by polling the system trace buffer until halted by
  14. pressing Ctrl-C or by executing the TRSTOP command from another command
  15. window or CMD file.
  16.  
  17. There are two modes of capturing the system trace buffer:
  18.  
  19.   Synchronous mode
  20.   Asynchronous mode
  21.  
  22. In Synchronous mode TRSPOOL waits for a full system trace buffer to
  23. become available.  The system notifies TRSPOOL then this happens.  Only
  24. one process in the system may use synchronous read access to the system
  25. trace buffer at any one time.  If the system trace buffer has wrapped
  26. then TRSPOOL will notify the user of this so that a larger system trace
  27. buffer may be specified.  TRSPOOL accumulates each system trace buffer
  28. as it becomes full into its own buffer specified by the /B parameter.
  29. This is eventually written to disk as a single file.  In synchronous
  30. mode, TRSPOOL allocates by default two file of the size specified by /B
  31. and alterntes its use of them.  If desired more than two buffer files
  32. may be requested by specifying /F with /B.
  33.  
  34. The size of the trace buffer used by TRSPOOL should be chosen according
  35. to total amount of trace data the user wishes to capture for the period
  36. of interest.  The system trace buffer size should be chosen to avoid
  37. lost events through buffer wrapping caused by the level of trace
  38. activity.  Normally the system trace buffer will be very much smaller
  39. than the TRSPOOL buffer.
  40.  
  41. Synchronous mode is not
  42. available to all versions of OS/2.
  43.  
  44. In asynchronous mode the system trace buffer may be captured at regular 
  45. intervals or by "Adaptive polling".
  46.  
  47. Adaptive polling mode attempts to capture the system trace buffer when
  48. the system trace buffer is a certain per-centage used.  The polling
  49. time is adjusted according to the actual usage of the last captured
  50. buffer.  The adaptive algorithm has a built in hysteresis to avoid the
  51. affects of short bursts of intensive tracing or moments of inactivity.
  52. Because there is no system notification of when the trace buffer
  53. wraps, TRSPOOL may loose trace events under very erratic system
  54. performance.
  55.  
  56. The /C option allows files created buy TRSPOOL to be combined into
  57. a single combined file.
  58.  
  59. The following parameters may be specified:
  60.  
  61.  
  62.  /An Specifies the target per-centage trace buffer usage for adaptive
  63.      spooling.
  64.      Default: 30(%%). This is the default spooling method.
  65.  /Fn Specifies the number of spooled trace buffer files.
  66.      Default: 10 in asynchronous mode and 2 in synchronous mode.
  67.  /Tn Specifies fixed time trace buffer spooling, in mili-seconds,
  68.      or if specified with /A the initial sleep time.
  69.      Default: Adaptive spooling - /A option + initial sleep time
  70.      2000ms.
  71.      Note: when adaptive spooling is active, the sleep time interval
  72.      is limitated to a range between 50ms and 60000ms. Any time interval
  73.      may be specified with fixed time spooling.
  74.  /Bs Specifies the consolidated trace buffer file size (s) in K-bytes for
  75.      use in synchronous spooling mode.
  76.      This option is incompatible with /A and /T.
  77.      The minimum buffer size of 128K is enforced.
  78.  /Q  Specifies quiet operation - messages are suppressed.
  79.      Default: non-quiet mode.
  80.  /W  Specifies write-through mode. Trace files are pre-allocated 
  81.      and opened in write-through mode.
  82.      Default: normal file open mode.
  83.  /P  Specifies trace files should be pre-allocated.
  84.      Default: files are not pre-allocated unless /W is specified.
  85.  /N  Specifies that the trace buffer file will not be re-cycled having been used once.
  86.      Default: cycle trace buffer files.
  87.  /Cn Combines files TRACEBUF.000 through TRACEBUF.nnn chronologically into 
  88.      TRACEBUF.TRC. Files are searched for in the current directory and DPATH by default,
  89.      unless a directory path is specified by /D.
  90.      If n is not specfified then combine all TRACEBUF.nnn files found in
  91.      the specified or implied directory.
  92.      This option is mutually exclusive with spooling options.
  93.  /Dp Specifies the directory path (p) which will be used by /C to locate 
  94.      input trace buffer files. This option is invalid with spooling options.
  95.  /?  Display help.
  96.  
  97. The default behaviour of TRSPOOL is to display help information. 
  98.  
  99. The generated trace buffer files have names: TRACEBUF.nnn, where
  100. nnn ranges from 000 to the value specified by /Fn.
  101.  
  102. The /W option is provided for use where tracing precedes a system 
  103. outage and there is no orderly shutdown. This disadvantage of using
  104. this option is that writing to the TRACEBUG.nnn files is made 
  105. synchronous, consequently the time take to spool the trace buffer will
  106. be longer.
  107.  
  108. The /P option pre-allocates and initialises all TRACEBUF.nnn files to 
  109. nulls. This ensures that space is available on hard disk for the 
  110. requisite TRACEBUF.nnn files. In addition there is an improved chance 
  111. that data written to these files will be committed should a system 
  112. outage occur. The /P option is implied by /W.
  113.  
  114. Technical note:
  115.    Neither of the /P or /W options is fail-safe. If a system outage 
  116.    occurs after the trace buffer has been read, but before data has 
  117.    been committed to disk then it will not be recorded. However, the 
  118.    segment allocated by TRSPOOL for the local copy of the trace buffer
  119.    is reported at initialisation. This may also be located from a
  120.    system dump by searching for the eye-catcher "TRSPOOL RAS DATA" in
  121.    the TRSPOOL stack segment. The trace buffer selector follows the
  122.    eye-catcher. The file number of the last file written is also 
  123.    recorded as a word following the trace buffer selector.
  124.  
  125.  
  126. To use TRSPOOL, the system trace must first be enabled by specifying
  127.  
  128.    TRACEBUF=63
  129.  
  130. in the CONFIG.SYS.
  131.  
  132. The system trace is activated by using the TRACE command or TRACE=
  133. statement of CONFIG.SYS.
  134.  
  135.  
  136. Example scenarios:
  137.  
  138. 1) Tracing dispatched threads:
  139.  
  140. From the OS/2 command line enter:
  141.  
  142.    TRACE ON
  143.    TRACE OFF 3,4,6,7
  144.    TRACE ON KERNEL(401)
  145.    TRSPOOL
  146.  
  147.  
  148.  
  149. 2) Tracing PM WinSendMsg and WinPostMsg activity:
  150.  
  151.    TRACE ON
  152.    TRACE OFF 3,4,6,7
  153.    TRACE ON PMWIN(818,807,718,706)
  154.    TRSPOOL
  155.  
  156.  
  157. For further information see the following:
  158.  
  159.   OS/2 Command Reference TRACE and TRACEFMT commands.
  160.   The OS/2 Debugging Library (Vols 1 - 4) SBOF-8617
  161.  
  162. Changes:
  163.  6th Dec 95  1.0  released.
  164.  8th Dec 95  1.1  Minor typing corrections. TRSPOOL set to run at
  165.                   time-critical priority with maximum delta.
  166. 19th Feb 96  1.2  Allow /T to specify initial sleep time with /A.
  167.              1.2  Add /W and /P options.
  168. 20th Feb 96  1.2a Added trspool ras data and technical note.
  169. 19th Mar 96  1.2b Add last file number written to rasdata.
  170.                   Fix spelling in message.
  171.  6th Jun 96  2.0  New trace buffer format compatibility added.
  172.  4th Jul 96  2.0a Flush messages as soon as written to allow TRSPOOL 
  173.                   messages to be directed to a file.
  174.  8th Jan 97  2.1  Apply max and min sleeptime to adaptive polling only.
  175.  
  176. 22th May 97  2.2  Add signal handler to exit TRSPOOL cleanly.
  177.  
  178.  4th Sep 97  2.3  /N and /B options added.
  179.  
  180. 04 Sep 1997  3.0  Allow /F with /B
  181.                                                        
  182. 22 Oct 1997  3.1  Add check for invalid numeric parameters
  183.  
  184. 03 Nov 1997  3.2 (188960) minor corrections to @0005 
  185.                  caused by signed/unsigned casting errors
  186.                                                         
  187. 13 Nov 1997  3.3 (189813) Loop when no stda          
  188.                                                         
  189. 27 Nov 1997  4.0 Add combine function and make the defaut function help.               
  190.  
  191. 25 Sep 1998  4.1 Add TRSTOP utility.
  192.