Contents of the XRAY.DOC file
XRAY by Tom Kihlken
Version 1.5 - February 1990
XRAY is a DOS programming tool which displays informative messages about
the operating system (DOS) functions. With XRAY, you'll be able to snoop
in on the operating systems inards and diagnose obscure programming bugs.
The high resolution timer and summary display can also help optimize your
program's I/O. It can be used with programs written in any language and
requires no special compiler.
This program is shareware. Shareware allows you to try the program out
before you buy it. You may also make copies for your friends or post it
on another BBS. If you like the program and want to continue using it,
you must register by sending your name, address, $15, and the version
number shown above to the following address. You may purchase a copy of
the assembler language source code for $30. Your support of shareware
insures continued development of good low cost software.
3665 McKibbon Road
Saint Louis, Missouri 63114
XRAY is a memory resident program which provides either a detailed
report or a summary of exactly which DOS functins (including lots of
undocumented ones) your program is making. Whether your use it to snoop,
or to monitor you system as it crashes, you're bound to see some
surprises. Also included is a high resolution timer which helps detect
I/O bound code which can bog down even your tightest assembler program.
If your a programmer, use XRAY to check that your program is working
efficiently (or discover why it's crashing!). Of course it's just as easy
to spy on someone elses code to learn how it works. With XRAY, you'll be
able to see how data base files are updated and even how some copy
protection techniques work!
XRAY works by intercepting interrupt 21h. Each DOS function call
outputs a single line of information. The first two items on the line are
the function number and a brief description of it (Appendix A shows a
complete list of the DOS functions). Next, you will find any important
input parameters, such as file names, handles, buffer sizes, etc.
Next, the actual function is performed, and its elapsed time is shown
(accurate to 0.00001 seconds!). If the function caused any physical disk
activity, the number of sectors read or written is shown. If the function
returns information (like a filename, directory, etc.), that is shown
next. Finally, either a descriptive error message or "OK" is output to
indicate the result of the operation.
A summary table of all the past DOS functions is displayed when XRAY is
run with the "/T" option. It shows the number of functions which have
ocurred, the number of sectors of disk I/O, and the total time they
required. This table is written to standard output and may be redirected
into a file with normal DOS redirection methods.
The output may at first look complicated, but if you study it along with
a good DOS programming manual you're guaranteed to learn lots.
You may run XRAY as many times as you like to change the options. To
restore the defaults, just uninstall (/U) XRAY and then reinstall it.
Here is a complete list of the parameters.
XRAY [options] [filename]
Where the options are:
/C = Send XRAY output to the console (this is the default mode).
The BIOS write TTY video function is used to display characters.
/Dn-m = Display only DOS function calls numbered betweem n and m (n and m
are entered in hex). The default is to display functions numbered
0C-FFh (except 2Eh). By displaying only selected functions you can
minimize the amount of output XRAY produces. You may repeat the
/D (and /I) parameter to select several ranges.
/F = Send XRAYs output to a disk file (the default is to display the output
on the screen). When /D is specified, all output is internally
buffered in a 1K buffer. The default filename is is C:\XRAY.LOG,
but a differant name may be specified on the command line. Be
sure to specify the full drive, directory, and name.
/H = Display the meaning of the optional parameters.
/J = Causes XRAY to JMP to the original interrupt address rather than
CALLing it. This causes the XRAY to be less obtrusive, so give
it a try if your program doesn't run normally without it. If you
use the /J option, you won't be able to see the result code or
the elapsed time of the call however.
/In-m = Ignore DOS function calls numbered between n and m (n and m are
entered in hex). The default is to ignore functions numbered
0-0Bh and 2Eh. By ignoring low numbered functions XRAY
produces less output and your program will run faster. You may
repeat the /I (and /D) parameter to ignore several ranges.
/Kn = Use Scan code n (n is entered in hex) for the Hot key. You can
press ALT and the hot key to toggle XRAYs output ON and OFF.
The default is to not use a hot-key (for maximum keyboard
compatiblity). See appendix B for a table of scan codes.
Note: You must use the /K parameter the very first time you
install XRAY to make the hot key to work. This prevents the
keyboard interrupt vector from being redirected if you don't
use the hot key option.
/O = Turns XRAY OFF. You may turn it back on with either the hot
key or by running XRAY again from the command prompt.
/Pn = Send XRAY output to LPTn. The default is to display its output
on the screen. The printer is the best real-time output option
since it is available up to the time of a system crash.
/Sn = Use the shift state n (n is entered in hex) combined with the hot key
to toggle XRAYs output ON and OFF. The default value is 8 which is
to press Alt with the hot key. See appendix C for a table of shift
/T = Display a summary table of all DOS function calls showing the total
number of each function, sectors of disk I/O, and total elapsed time.
/U = Uninstall XRAY from memory (if possible). XRAY can only be
uninstalled if no other TSR programs (which use interrupts 9 or
21h) have been loaded.
/V = Display function calls made by COMMAND.COM. The default is to
ignore these calls. If you use the /C option, XRAY will
produce lots of output which may not be of interest for your
application but it's facinating to see how the command interpreter
does its thing. When you use /V, calls from COMMAND.COM are
marked with an asterick.
XRAY produces two types of output. Realtime output of each DOS function
call, and a cumulative table of all the function calls which have been
made. The cumulative table is displayed only when the /T parameter is
The real-time output from XRAY is sent to either the screen, printer, or
a disk file. Which one you choose depends on what you are using XRAY for.
The screen is the easiest since it is fast and you can watch it easily.
Unfortunately, it usually makes a mess of the overlying applications video
output. XRAY uses the BIOS write TTY function to drive the display.
Sending the output to a file is better for large amounts of output. The
disadvantage of using a file is that some output is lost in the event of a
system crash (due to internal buffering). The size of this buffer is 1K
(about 20 function calls).
The printer is the best output method for observing a system crash since
all of the output is displayed, right up until the machine locks up.
Printing will slow down your program however and in some cases may cause
time critical programs to timeout. XRAY uses the BIOS print character
function (INT 17h) to drive the printer.
ELAPSED TIME MEASUREMENT
XRAY uses the 8253 timer/counter to measure elapsed time of DOS function
calls. This counter is calibrated as part of the installation process
such that it measures only the actual time executing DOS code. It is
accurate to within approximately 10 microseconds (times are displayed to
the nearest .01 millisecond). The largest time which can be displayed is
about 450 seconds. This shouldn't be a problem since most functions are
completed in less than a second.
To record the elapsed time, the 8253 (timer 0) is reprogrammed to mode 2
(divide by n) on every DOS call. This doesn't affect the clock tick rate,
however it can cause a few extra ticks which make the system clock seem to
run a bit fast. If you're concerned about restoring the time after
running XRAY, you should reboot the machine.
Most programs make lots of calls to the operating system. When this
happens, XRAY produces lots of output if you don't suppress some of it. An
example of this is when a program continuously reads the clock in order to
display the time on screen. It is easy to filter out this uninteresting
stuff with XRAY, using the /D (Display)) and /I (Ignore) options.
The default setting for the filter is to ignore functions numbered lower
than 0Ch and function 2Eh. To ignore additional functions, just use the
/In-m option. To add functions to the filter, use /Dn-m. You can specify
as many ranges as you like. You can also specify a single function number
such as /I2C.
As each range is parsed from the command tail, it takes precedence over
previous ranges, so the order in which you specify them controls how they
are combined. Remember, you always start with the default filter (or the
existing filter if XRAY has already been installed).
Let's look at an example. Say we're interested in the functions 3Ch to
40h, 16h to 17h, and 4C. The correct parameters would be:
/I0-FF /D16-17 /D3C-40 /D4C
Notice the first "/I" turned off everything, the next three "/D's" turn
on the ranges we want. When selecting ranges, it's best to avoid the
console I/O functions (01h through 0Bh) since there are millions of them
in most programs.
I/O SECTOR COUNT
DOS generally buffers most I/O operations in such a way that a write
request may not be passed to the disk until a full sector of data is ready
to be written. Disk buffering and caching also affect the physical
transfer of data to the disk.
XRAY lets you observe this buffering by displaying the actual amount of
I/O in terms of number of physical sectors. If you compare the sector
count with the elapsed time, you'll be able to determine the effective
access time of the disk in real life situations (something benchmarks
can't really do). Be prepared for surprises here! Remember, some I/O
commands will hit the cache (you should be using one by now) and complete
The sector count is obtained by intercepting the BIOS diskette interrupt
(INT 13h) and saving the number of sectors. Disks which have their own
device driver (RAMDISKs, etc.) won't show up in the sector count if they
don't use interrupt 13h.
USING A HOT KEY
Normally XRAY does its job continously after installed. You can switch
XRAY off by running it again with the /O option. An easier method is to
specify a hot key which will toggle XRAY off and on.
To enable use of a hot key, you MUST specify a scan code (with the /K
parameter) during the initial installation. The default scan code is 0FFh
which indicates that the keyboard interrupt vector is not to be
intercepted and the hot key is disabled. You can change the scan code
later if you want but you MUST enable it the FIRST time XRAY is installed.
Scan codes are selected from appendix B. You must hold down the Alt key
together with the selected hot key. If you want a shift key other than
ALT, specify a shift mask with the /S option. Valid shift codes are shown
in appendix C.
A NOTE ABOUT COMPATIBILITY
XRAY was written to be as compatible as possible with most programs.
Like all TSR's however, there will always be some programs which may not
run correctly with it installed. If you seem to have trouble, there are a
couple things you can try.
First of all, remove any other TSR programs you are using (or load them
in a different order). Second, If the hot key interfers with your
application, try a different scan code or reinstall XRAY with the hot key
disabled (by not specifying a scan code).
Third, try the /J option. This causes XRAY to JMP to the original
interrupt 21 address rather than CALLing it, makint it less obtrusive.
When you do this however, you won't be able to see the result code or the
elapsed time of the call however.
After spending a little time with XRAY, you're bound to see things
you've never heard of or don't understand. I can't possibly explain
everything about DOS, so I'll recommend a couple good books on the
Duncan, Ray. Advanced MS-DOS. Redmond, Redmond, Wash.: Microsoft
Lafore, Robert. Assembly Language Primer for the IBM PC&XT.
New York: Plume/Waite, 1984.
Scanlon, Leo J. IBM PC Assembly Language: A Guide for Programmers.
Bovie, Md.: Robert J. Brady Co. 1983.
CHANGES FOR VERSION 1.5
1. Added several more undocumented DOS calls.
CHANGES FOR VERSION 1.4
1. Added /T parameter to display summary table.
2. The time display routine was extended to display times up to 450
CHANGES FOR VERSION 1.3
1. The default for the filter table was modified to ignore function 2Eh.
2. Extended error codes were added to the error table.
3. More parameters are shown with each functions.
4. Elapsed time is shown to the nearest .01ms (for times less than 2ms).
5. Number of disk sectors read/written is shown.
6. The "/T" option was deleted (time measurement is the default now).
7. You may specify a filename for the log file on the command line.
DOS FUNCTION CALLS
Following is a list of the DOS function calls. For more information,
see the DOS technical reference manual.
00h - TERMINATE PROCEDURE
01h - READ KEYBOARD WITH ECHO
02h - DISPLAY CHARACTER
03h - AUXILARY INPUT
04h - AUXILARY OUTPUT
05h - PRINT CHARACTER
06h - DIRECT CONSOLE I/O
07h - DIRECT CONSOLE INPUT
08h - READ KEYBOARD
09h - DISPLAY STRING
0Ah - BUFFERED KEYBOARD INPUT
0Bh - CHECK KEYBOARD STATUS
0Ch - FLUSH KEYBOARD BUFFER
0Dh - DISK RESET
0Eh - SELECT DEFAULT DISK
0Fh - OPEN FILE (FCB)
10h - CLOSE FILE (FCB)
11h - SEARCH FOR FIRST FILE (FCB)
12h - SEARCH FOR NEXT FILE (FCB)
13h - DELETE FILE (FCB)
14h - SEQUENTIAL READ (FCB)
15h - SEQUENTIAL WRITE (FCB)
16h - CREATE FILE (FCB)
17h - RENAME FILE (FCB)
19h - GET CURRENT DISK
1Ah - SET DISK TRANSFER ADDRESS
1Bh - GET ALLOCATION TABLE INFO FOR DEFAULT DRIVE
1Ch - GET ALLOCATION TABLE INFO FOR SPECIFIED DRIVE
21h - RANDOM READ (FCB)
22h - RANDOM WRITE (FCB)
23h - FILE SIZE (FCB)
24h - SET RELATIVE RECORD (FCB)
25h - SET VECTOR
26h - CREATE NEW PROGRAM SEGMENT
27h - RANDOM BLOCK READ (FCB)
28h - RANDOM BLOCK WRITE (FCB)
29h - PARSE FILENAME (FCB)
2Ah - GET DATE
2Bh - SET DATE
2Ch - GET TIME
2Dh - SET TIME
2Eh - SET/RESET VERIFY FLAG
2Fh - GET DATA TRANSFER AREA
30h - GET DOS VERSION NUMBER
31h - KEEP PROCESS
33h - CONTRL BREAK CHECK
34h - GET BUSY FLAG
35h - GET VECTOR
36h - GET DISK FREE SPACE
38h - GET/SET COUNTRY INFORMATION
39h - MAKE DIRECTORY
3Ah - REMOVE DIRECTORY
3Bh - CHANGE DIRECTORY
3Ch - CREATE FILE
3Dh - OPEN FILE HANDLE
3Eh - CLOSE FILE HANDLE
3Fh - READ FROM FILE/DEVICE
40h - WRITE TO A FILE/DEVICE
41h - DELETE FILE
42h - MOVE POINTER
43h - CHANGE FILE ATTRIBUTE
44h - I/O CONTROL FOR DEVICES
45h - DUPLICATE FILE HANDLE
46h - FORCE DUPLICATE FILE HANDLE
47h - GET CURRENT DIRECTORY
48h - ALLOCATE MEMORY
49h - FREE MEMORY
4Ah - MODIFY MEMORY BLOCK
4Bh - EXECUTE A PROGRAM
4Ch - TERMINATE PROGRAM
4Dh - RETRIEVE THE RETURN CODE OF A CHILD
4Eh - FIND FIRST MATCHING FILE
4Fh - FIND NEXT MATCHING FILE
50h - SET PROGRAM SEGMENT PREFIX
51h - GET PROGRAM SEGMENT PREFIX
54h - GET VERIFY SETTING
56h - RENAME A FILE
57h - GET/SET FILE DATE
59h - GET EXTENDED ERROR
5Ah - CREATE UNIQUE FILE
5Bh - CREATE NEW FILE
5Ch - LOCK/UNLOCK FILE ACCESS
5Eh - PRINTER SETUP
5Fh - DEVICE REDIRECTION FUNCTIONS
60h - GET TRUE NAME OF A FILE
61h - SET PROGRAM SEGMENT PREFIX
62h - GET PROGRAM SEGMENT PREFIX
KEYBOARD SCAN CODES
The following is a partial list of values which can used with the /K
option to specify a hot key scan code. The keys which are described as
"KP" are on the numeric keypad on the right side of the keyboard. Other
codes can be found in any good technical reference.
The default condition is for the hot key to be disabled.
Code Key Code Key Code Key
1Eh A 01h Esc 3Bh F1
30h B 02h 1 3Ch F2
2Eh C 03h 2 3Dh F3
20h D 04h 3 3Eh F4
12h E 05h 4 3Fh F5
21h F 06h 5 40h F6
22h G 07h 6 41h F7
23h H 08h 7 42h F8
17h I 09h 8 43h F9
24h J 0Ah 9 44h F10
25h K 0Bh 0 57h F11
26h L 0Ch - 58h F12
32h M 0Dh = 47h KP7
31h N 0Eh BS 48h KP8
18h O 0Fh TAB 49h KP9
19h P 1Ah [ 4Ah KP-
10h Q 1Bh ] 4Bh KP4
13h R 1Ch CR 4Ch KP5
1Fh S 2Ah L-SHIFT 4Dh KP6
14h T 39h SPACE 4Eh KP+
16h U 36h R-SHIFT 4Fh KP1
2Fh V 33h , 50h KP2
11h W 34h . 51h KP3
2Dh X 35h / 52h KP0
15h Y 53h DEL
KEYBOARD SHIFT STATE MASK CODES
The following is a list of values which can used with the /S option to
specify a hot key shift state code. The default value for this option is
8 (Alt key held down). You may numerically add values to create multiple
shift conditions. For example, "/S09" would be used to specify both the
Right shift and Alt key held down when the hot key is pressed. Only the
four lower bits of the shift mask are used.
Value Shift State
0 No shift key needed
1 Right shift held down
2 Left shift held down
4 Ctrl key held down
8 Alt key held down
IOCTL (IO control for devices) functions are involked by using DOS
function 44h. The following subfunctions are defined.
0 - Get Device information
1 - Set device information
2 - Read character device
3 - Write character device
4 - Read block device
5 - Write block device
6 - Get input status
7 - Get output status
8 - Is device changeable?
9 - Is device local or remote?
A - Is handle local or remote?
B - Change retry count
C - Reserved
D - Generic IOCTRL request
E - Get logical drive
F - Set logical drive