UI21DEB - deBUGGER
==================

About
-----

UI21DEB is a DOS real mode deBUGGER focusing on file I/O activity
performed via INT $21. While the world is already full debuggers
("Insight" real mode debugger by Oleg & others, FreeDOS DEBUG, G[R]DB,
"deb" by Japheth, OlyDbgr (does it really work in DOS ?), WATCOM's "WD"
(seems not to work in DOS either ?), "SD" by Narech Koumar (dropped
with DOS/32A version 9.xx ?), and last but not least the famous
FTE-debugger), UI21DEB has some unique features, OTOH it also lacks
some features known from the other debuggers, so NO, it doesn't attempt
to obsolete them all, see "Comparison" below for details. While a
debugger is usually a tool for developers and advanced users only,
UI21DEB has some features making it useful to "average" users as well,
see "For users" below.

Package contents
-- --------------

# UI21DEB.COM   (6'644 Bytes, 060F0FB6451F9F7C7DE04FCD2569E33C)
  main file, DOS ".COM" TSR executable

# UI21DEB.ASM (136'526 Bytes, 2F013DB32500CF5B96CAE89300E5F383)
  source code

# UI21DEB.TXT  (21'555 Bytes, ????????????????????????????????)
  this text

# UIEXAMPL.TXT (92'200 Bytes, 09489E4B3596D2793C09E3B06018F9FD)
  examples of deBUGGER output: detailed list of calls, with
  comments on BUG's and oddnesses encountered

# (5 files, total 28'857 Bytes)
  BUGYWGET.PNG 8'231 7A9A7F7D3DD89CDB88EBD90479C4218C
  FAT28KIL.PNG 4'745 F8B8EDC38E057CF772BA74BA809299A5
  GIFENONT.PNG 4'407 318D229E1BC2DEF1311C993FCAE5207C
  KO9HANG.PNG  7'785 D1D5BE1FF4C458F5298A12D18EC3F54C
  MTRRONNT.PNG 3'689 2471725CB5610EB7563EFD92493BB0B3
  screenshots (KO9HANG done with BOCHS, other with SNARF)

System requirements
-------------------

For running the deBUGGER:

# CPU: At least 8086 or compatible

# RAM: At least 512 KiB

# Video: any with text mode support

# Storage: some 100 KiB of free space

# OS: My new (not yet released) DOS, RxDOS 7.30, FreeDOS 1.1,
      EDR-DOS 7.01.08 or compatible

For viewing the saved debug buffers:

# A file viewer supporting both text and "hex" mode (appropriate for
  given hardware, Japheth's "S" is a good choice, requires 80386 CPU,
  to be fixed later)

# Video: any (preferably with 80x50 chars text mode supported)

For compiling the deBUGGER from the source:

# CPU: At least 80386 or compatible

# RAM: A few MiB (check it out)

# Tools: FASM 1.67.29 or better

For viewing the screenshots:

# Viewer with PNG format support

# Hardware able to run it and supporting at least 640x480x4bpp graphics

General features
----------------

# Debugging INT $21 calls, see below "Debug"

# Fixing faulty filenames, see below "Filenames"

# Fixing / workarounding various suboptimal and faulty behaviour arising
  from interaction of DOS application with the kernel, tending to cause
  unproductive controversy or even fight about who is responsible for
  bug: whether the kernel developer or the application developer, or
  some "faulty but deliberate and documented" behaviour, see below "Misc
  features" for details

# Can be used with both real mode applications as well as various types
  of protected mode DOS applications

Debug
-----

#### Features:

# Can register INT $21 calls

# Can "kill" , "fake" and "fail" INT $21 calls

# Provides 3 outputs: count of selected groups of calls, a detailed list
  of selected calls including parameters passed and results, and an
  overall call statistics (registering all calls, almost impossible
  to overflow)

# Excellently suitable to search for bugs and performance killers
  in file I/O, like redundant repeated calls, spurious seeks,
  faulty filenames, unreasonably many read or write calls with
  negligible amount of data, excessive attribute peeking or writing,
  notorious attempts to use NTLFN calls, spurious file I/O at all, ...

# Can discover all files that an application is trying to load / save /
  use / access, including temporary files deleted before termination,
  DLL's loaded "dynamically" using "LoadLibrary" invisible in the import
  list, and undocumented ".INI" or similar files

# Very useful for debugging virii (DOS is safe and this deBUGGER makes
  it even safer)

# NTV-DM emulation in DOS (genuine NT not needed anymore)

# Useful for checking application compatibility with both the future
  and the past

# Can debug real mode applications and compilers they were brewed with

# Can debug DGJPP applications as well as DGJPP itself

# Can debug non-DGJPP DPMI applications and the compilers involved
  in creation of them

# Can debug Win32 applications running in DOS using HX Extender as
  well as HX itself (see below for limitations)

# Can disable FAT28 AH=$73 calls, thus temporarily emulate an old DOS
  version

# Can disable the "NTLFN API" AH=$71 calls, (including King Udo's
  "looooooong seek" AX=$7142 call), this feature turned out to be very
  useful to "fix" experimental very incomplete NTLFN support in some
  EDR-DOS "WIP" versions

# Can disable the "extended open" AH=$6C call (this breaks many things)

# Can disable obsolete FCB calls (except AH=$29)

# Can separately disable the "parse form FCB" AH=$29 call (this breaks
  EDR-DOS)

# Can disable floppy calls

# Can set the famous "NTrue DOS version" to $3205 (this shouldn't be
  able to break any DOS application, however, if anyone bothers to
  check oneself, tests will bring up a massive evidence of the
  opposite quickly)

# Reports names of applications causing the calls (not well with some
  DOS entenders, see below)

# Can selectively debug one application only or one application and
  everything spawned from it

# Can detect that someone else hacked INT $21 (see "I" switch below)

Filenames
---------

# Can fix (to some degree) faulty filenames ("multiple-slash-BUG" and
  "multiple-dot-BUG") supplied by many (including, but not necessarily
  limited to) NTVDM-DGJPP applications, avoiding duplicates and
  "ENOENT" , allowing to run them in DOS

# Fixing strategy of UI21DEB doesn't cause any filesystem pollution,
  slowdown or risk of corruption

# Names "only" longer than 8 chars like "VGABIOS-cirrus" and
  "VGABIOS-cumulus" are currently not being fixed and will still duplicate

# Doesn't provide 100% NTFLN compatibility, while it's verified to be
  sufficient for many cases (GIFSICLE, WGET, 7-ZIP, OPTIPNG), there
  could be applications not happy with it, so things like STARLFN or
  DOSLFN might still have a chance then

Misc features
-------------

# Disable "AbortRetryFail" (FreeCOM has an "/F" switch doing the same
  more easily, EDR-DOS hasn't)

# Disable "Remove diskette from A: and insert it into B:" (no known
  alternatives)

# Faster floppy failure - reduces unreasonably many attempts to read
  from a (not ready) floppy to just 1, if an access fails because of
  of devide not ready or physical media error, any further attempts
  within 8 seconds are failed immediately and do restart the timer

# Can completely disable floppy accesses, thus saving time and drive
  live time