ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/PROG/ASSEMBLY/XRAY15.ZIP/XRAY.DOC

Text File | 1990-02-18 | 19.5 KB | 474 lines

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.


Tom Kihlken
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
        state values.

   /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.



OUTPUT OPTIONS

  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
given.
  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.



SELECTING FUNCTIONS

  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
very quickly.
  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.



DIGGING DEEPER

  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
subject.

   Duncan, Ray. Advanced MS-DOS.  Redmond, Redmond, Wash.: Microsoft
    Corporation, 1986.

   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
   seconds.


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.



Appendix A
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



Appendix B
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
 2Ch     Z



Appendix C
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



Appendix D
IOCTL FUNCTIONS

  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