################################################################################

TRAP History
************
TRAP & SETTRAP 3.06 (1/09/90)
* different handling of double installation
using DOS-multiplex interrupt 2Fh

TRAP 3.05 (3/05/90)
* different handling of double installation
allow more than one copy of TRAP per interrupt

TRAP 3.04 (2/11/90)
* Check for double installation on same interrupt.
(all memory below TRAP loading address)
* Move the characters to be printed and/or filed to a
seperate buffer.
* The default dump filename is set to TRAPxx.DMP for each
interrupt. xx will be set to the hex interrupt number.
* Allow some user defined status changes when installing TRAP.
* Now Int 16h can be traced.

SETTRAP 3.04 (2/11/90)
* Search whole memory below SETTRAP Loading address for copies
of TRAP and put them in the int selection menu (max. 18 entries).
* Choose interrupt from menu or user input
* Check for printer present. If not skip dump option.


TRAP 3.01 (1/24/90)
Added Udo Chrosziel code:

* Interrupt number entered in hex or decimal
* Checks for double installation on same interrupt
( This works only if the interrupt hasn't been changed
by another resident programm.)
* Don't display registers on Entry of Interrupt if disabled.
* Print CRLF after 80 characters when dumping content to printer.
* Added comparison of flags.
* Fixed bug with WaitFlag
* Added a file dumping feature (dump) register content to a file.

* Changed SETTRAP (now with windowed interface).


TRAP 2.0 (1/8/90)

* fixed bug with many registers showing a wrong value. I
apologize for this infamy.
* changed SETTRAP parameters logic
* added DISP|NODISP toggle to disjoin display and printing
(this is a way to work in graphic modes)
* fixed bug in memory scanning in SETTRAP. Now Settrap scans the
whole 1meg space to find "hiloaded" copies of TRAP.

TRAP 1.8 - first version released on IBM PCTOOLS.

################################################################################

WARNING : TRAP is released to the Public Domain. Though we DO NOT authorize
any distributor to charge any amount of money for the distribution of this
program EVEN if it is included in a larger package. TRAP must be distributed
unchanged AND FREE! Period. TRAP is free for downloading from BBS or servers
like CIS or BIX. "Professional" freeware distributors and money makers,
please keep out!

We are engineers at IBM France and Germany. So, an "IBM Internal Use Only"
has also been released including copyright messages. For legal reasons, you
are not authorized (unless working at IBM) to use that version. Actually you
should never access to an IBM IUO program but it's well known that some
"leakage" exists. This one is exactly the same so please use and distribute
it instead.

################################################################################


TRAP - Interrupt Tracing


by
Patrick Philippot

Enhancements and new SETTRAP version
by
Udo Chrosziel


Released to the Public Domain

Version 3.06


TRAP is a resident DOS programmer utility allowing you to
trace any interrupt. With TRAP you can display the contents of the
CPU registers BEFORE entering and/or AFTER exiting the interrupt
handler.

You can use TRAP to debug or study the behaviour of any
program. I have learned a LOT about DOS using TRAP. For example, I
was trying to install a resident handler for INT 24h (Critical
Error Handler) and didn't understand why I was unable to replace
the original vector of this interrupt handler. Now, I know why this
is possible within a program only (see note at the end of this
file).

This package contains 3 files:

TRAP.COM the resident part of TRAP
SETTRAP.EXE the TRAP dynamic configurator
TRAP.DOC this file

Running TRAP is very straightforward:

TRAP D|Xn [/F /P /A]

where n specifies the traced interrupt number in DECIMAL (Dn)
or HEXADECIMAL (Hn).

For example, to trace the BIOS printer services Int 17h just enter:

decimal:
TRAP d23 or TRAP D23 or TRAP 23
hexadecimal:
TRAP x17 or TRAP X17

At this time TRAP is installed but not active. To activate and
configure TRAP you will use SETTRAP.

The 3 options for TRAP have the following meanings:

/F dump registers to a file (default file TRAPxx.DMP).
/P print registers on default printer.
/A activate TRAP after installation
(this option is always processed last regardless of its
position in the parameter string).

On the /F and /P option the register display is turned off
automatically.


SETTRAP takes no parameter. When invoked, a pull-down menu
appears:


Int Control Test Hex Quit
Set Interrupt Number
no interrupt


The first option you will use is INT. It allows you to specify
which interrupt handler is to be processed. You choose the handler
you want by cursor selction or entry of the interrupt number as an HEX
value unless you select the HEX option to set it to DEC.
This choice applies also to the TEST menu.


Int Control Test Hex Quit
Set Interrupt Number
no interrupt

User Interrupt
-> undefined
Int 05h at 32D8:0008
Int 60h at 3376:0008


When you select the user interrupt SETTRAP will check if a copy
of TRAP has been installed for that interrupt. It will then display
the address where this copy has been found or remain undefined if
it was not found.

Then you will choose from the CONTROL menu what kind of report
you want:


Int Control Test Hex Quit
Setting of User Control Functions
activ Int 05h

TRAP is inactive
Display Registers on Entry
Display Registers on Exit
Wait after Display
Display Registers
No Test of Registers
No fileing of Registers
No Printing of Registers


The default options are set up to display registers for both
entry and exit of the interrupt handler and to wait for a keystroke
after displaying the registers contents.

To report interrupt calls you may decide to:

1/ Display or not registers contents (in which case the above
options apply).

2/ Print registers contents. The option is only displayed if
a printer is installed in the system.

3/ Log interrupt calls to a file. You will be prompted for a
name. The default name is TRAPxx.DMP. Where xx represents the
interrupt number in hex.

You may decide to cancel all tests on registers contents by
choosing the "No Test of Registers" option. See below for tests. In
this case **ALL** calls to the trapped interrupt will be traced. Be
careful! The "No Test of Registers" option doesn't clear the TRAP
test values. Use the "Clear" or "Clear all" option in the TEST menu.


The reasonable strategy is to keep TRAP inactive until you have
completly set up the specifications for the conditional tracing.


CONDITIONAL TRACING:
*******************

This is the most usual way of running TRAP.

You may tell TRAP to display registers contents only if one or
several particular registers contain a certain value. This value
will be tested BEFORE entering the interrupt handler.

This will allow you to trace selected interrupt services only
(imagine you are tracing all calls to INT 21h... - likewise, avoid
tracing INT 28h unless you are VERY patient).

To do so use the TEST option of the pull-down menu:


Int Control Test Hex Quit
Set Register Test Values
aktiv Int 05h
AX register-menu
AX=0000h Word
BX=0000h Hi-Byte
CX=0000h Low-Byte
DX=0000h

DS=0000h flag-menu
ES=0000h Cary
Parity
SI=0000h Auxiliary
DI=0000h Zero
BP=0000h Sign
FL=0000h Trap
Interrupt
Clear Direction
Clear all Overflow



Select the register you want to test before tracing the
interrupt call. You will be prompted to enter a value for the
register (With either high byte, low byte or 16 bit word for the
accu registers).
Values are entered in HEX or DEC according to the current value of
the HEX/DEC option.

"Clear" will cancel the tests for the selected register.
"Clear All" will clear all entered values and resets the Test option
to "NO".

Now you can return to the CONTROL menu with hitting ESC and
activate TRAP.

----------------------------------------------------------------------------
Hints for the use of TRAP


HIT ESCAPE DURING REGISTERS DISPLAY TO DEACTIVATE TRAP


Doing so will deactivate TRAP but will not uninstall it. TRAP
can always be reactivated using SETTRAP.

TRAP will not display on exit of certain interrupt handlers
because they don't return to the caller or have a particular
behaviour:

INT 27h (Terminate and Stay Resident)
INT 21h service 31h (TSR)
INT 21h service 4Ch (terminate)
INT 21h service 00h "
INT 20h terminate


In this case, TRAP will display registers contents only when
entering the interrupt handler and not on exit. In short, it will
make a JMP to the original handler and not a CALL.

Before displaying the registers TRAP tests the video mode and
resets the screen address. So you can make trace INT 10h service 0
safely. However, there is no support in this version for graphic
modes. If you want to use trap in graphic modes, use the file
logging service or print registers contents while disabling registers
display.


REGISTERS VALUES
****************

Please consider that the CS:IP and SS:SP pairs indicate their
values in the calling program when the call to INT n was made.
These values are not changed on return of the interrupt handler.
Actually, CS:IP points to the return address in the caller.

TRAP shows the values that will be actually returned to the
caller, not the registers values corresponding to its own state.

Example:

If you are curious about INT 24h, you may try the following:

TRAP x21

and set up SETTRAP with the following values:

INT 21h
AH=25h
AL=24h

This will trap every call to the SetVector function of DOS for
interrupt 24h. You will be surprised to see that DOS is CONSTANTLY
resetting this interrupt vector to a hard-coded value (found in
command.com) and not to the values specified in the running program
PSP as stated in the DOS tech. ref.

Even when you are issuing a harmless "c:", the Setvector
function is triggered for INT 24h!



Happy hacking!

Patrick Philippot/Udo Chrosziel 09/05/90