home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
dumptool.zip
/
TRSPOOL.ZIP
/
trspool.doc
next >
Wrap
Text File
|
1998-09-25
|
8KB
|
192 lines
TRSPOOL Copyright (C) 1995 IBM UK Ltd
Author: Richard Moore
Date 25 Sep 1998
version 4.1
TRSPOOL extends the usefulness of the OS/2 system trace facility
by capturing the single system trace buffer and spooling it a
cyclically used sequence of disk files. The captured trace disk files
may be later formatted using TRACEFMT, by selecting the Open option of
the File menu.
TRSPOOL operates by polling the system trace buffer until halted by
pressing Ctrl-C or by executing the TRSTOP command from another command
window or CMD file.
There are two modes of capturing the system trace buffer:
Synchronous mode
Asynchronous mode
In Synchronous mode TRSPOOL waits for a full system trace buffer to
become available. The system notifies TRSPOOL then this happens. Only
one process in the system may use synchronous read access to the system
trace buffer at any one time. If the system trace buffer has wrapped
then TRSPOOL will notify the user of this so that a larger system trace
buffer may be specified. TRSPOOL accumulates each system trace buffer
as it becomes full into its own buffer specified by the /B parameter.
This is eventually written to disk as a single file. In synchronous
mode, TRSPOOL allocates by default two file of the size specified by /B
and alterntes its use of them. If desired more than two buffer files
may be requested by specifying /F with /B.
The size of the trace buffer used by TRSPOOL should be chosen according
to total amount of trace data the user wishes to capture for the period
of interest. The system trace buffer size should be chosen to avoid
lost events through buffer wrapping caused by the level of trace
activity. Normally the system trace buffer will be very much smaller
than the TRSPOOL buffer.
Synchronous mode is not
available to all versions of OS/2.
In asynchronous mode the system trace buffer may be captured at regular
intervals or by "Adaptive polling".
Adaptive polling mode attempts to capture the system trace buffer when
the system trace buffer is a certain per-centage used. The polling
time is adjusted according to the actual usage of the last captured
buffer. The adaptive algorithm has a built in hysteresis to avoid the
affects of short bursts of intensive tracing or moments of inactivity.
Because there is no system notification of when the trace buffer
wraps, TRSPOOL may loose trace events under very erratic system
performance.
The /C option allows files created buy TRSPOOL to be combined into
a single combined file.
The following parameters may be specified:
/An Specifies the target per-centage trace buffer usage for adaptive
spooling.
Default: 30(%%). This is the default spooling method.
/Fn Specifies the number of spooled trace buffer files.
Default: 10 in asynchronous mode and 2 in synchronous mode.
/Tn Specifies fixed time trace buffer spooling, in mili-seconds,
or if specified with /A the initial sleep time.
Default: Adaptive spooling - /A option + initial sleep time
2000ms.
Note: when adaptive spooling is active, the sleep time interval
is limitated to a range between 50ms and 60000ms. Any time interval
may be specified with fixed time spooling.
/Bs Specifies the consolidated trace buffer file size (s) in K-bytes for
use in synchronous spooling mode.
This option is incompatible with /A and /T.
The minimum buffer size of 128K is enforced.
/Q Specifies quiet operation - messages are suppressed.
Default: non-quiet mode.
/W Specifies write-through mode. Trace files are pre-allocated
and opened in write-through mode.
Default: normal file open mode.
/P Specifies trace files should be pre-allocated.
Default: files are not pre-allocated unless /W is specified.
/N Specifies that the trace buffer file will not be re-cycled having been used once.
Default: cycle trace buffer files.
/Cn Combines files TRACEBUF.000 through TRACEBUF.nnn chronologically into
TRACEBUF.TRC. Files are searched for in the current directory and DPATH by default,
unless a directory path is specified by /D.
If n is not specfified then combine all TRACEBUF.nnn files found in
the specified or implied directory.
This option is mutually exclusive with spooling options.
/Dp Specifies the directory path (p) which will be used by /C to locate
input trace buffer files. This option is invalid with spooling options.
/? Display help.
The default behaviour of TRSPOOL is to display help information.
The generated trace buffer files have names: TRACEBUF.nnn, where
nnn ranges from 000 to the value specified by /Fn.
The /W option is provided for use where tracing precedes a system
outage and there is no orderly shutdown. This disadvantage of using
this option is that writing to the TRACEBUG.nnn files is made
synchronous, consequently the time take to spool the trace buffer will
be longer.
The /P option pre-allocates and initialises all TRACEBUF.nnn files to
nulls. This ensures that space is available on hard disk for the
requisite TRACEBUF.nnn files. In addition there is an improved chance
that data written to these files will be committed should a system
outage occur. The /P option is implied by /W.
Technical note:
Neither of the /P or /W options is fail-safe. If a system outage
occurs after the trace buffer has been read, but before data has
been committed to disk then it will not be recorded. However, the
segment allocated by TRSPOOL for the local copy of the trace buffer
is reported at initialisation. This may also be located from a
system dump by searching for the eye-catcher "TRSPOOL RAS DATA" in
the TRSPOOL stack segment. The trace buffer selector follows the
eye-catcher. The file number of the last file written is also
recorded as a word following the trace buffer selector.
To use TRSPOOL, the system trace must first be enabled by specifying
TRACEBUF=63
in the CONFIG.SYS.
The system trace is activated by using the TRACE command or TRACE=
statement of CONFIG.SYS.
Example scenarios:
1) Tracing dispatched threads:
From the OS/2 command line enter:
TRACE ON
TRACE OFF 3,4,6,7
TRACE ON KERNEL(401)
TRSPOOL
2) Tracing PM WinSendMsg and WinPostMsg activity:
TRACE ON
TRACE OFF 3,4,6,7
TRACE ON PMWIN(818,807,718,706)
TRSPOOL
For further information see the following:
OS/2 Command Reference TRACE and TRACEFMT commands.
The OS/2 Debugging Library (Vols 1 - 4) SBOF-8617
Changes:
6th Dec 95 1.0 released.
8th Dec 95 1.1 Minor typing corrections. TRSPOOL set to run at
time-critical priority with maximum delta.
19th Feb 96 1.2 Allow /T to specify initial sleep time with /A.
1.2 Add /W and /P options.
20th Feb 96 1.2a Added trspool ras data and technical note.
19th Mar 96 1.2b Add last file number written to rasdata.
Fix spelling in message.
6th Jun 96 2.0 New trace buffer format compatibility added.
4th Jul 96 2.0a Flush messages as soon as written to allow TRSPOOL
messages to be directed to a file.
8th Jan 97 2.1 Apply max and min sleeptime to adaptive polling only.
22th May 97 2.2 Add signal handler to exit TRSPOOL cleanly.
4th Sep 97 2.3 /N and /B options added.
04 Sep 1997 3.0 Allow /F with /B
22 Oct 1997 3.1 Add check for invalid numeric parameters
03 Nov 1997 3.2 (188960) minor corrections to @0005
caused by signed/unsigned casting errors
13 Nov 1997 3.3 (189813) Loop when no stda
27 Nov 1997 4.0 Add combine function and make the defaut function help.
25 Sep 1998 4.1 Add TRSTOP utility.