Category : System Diagnostics for your computer
Archive   : DBUG.ZIP
Filename : DBUG.DOC

DBUG - The Display and Modify editor

Utility Overview

DBUG allows direct access to a disk file for display and editing purposes.
It is a screen-oriented File Editor to be used with an IBM PC or PC compatible
machine and an MS-DOS Version 2.00 compatible operating system. DBUG's main
features are:

1) Full editing capabilities are available. The user can easily position to
any byte in any given record. There are both Hexadecimal and ASCII
modification modes. Direct disk patching becomes a simple task with DBUG.
Small changes in files can be made very quickly.

2) DBUG allows record advance, backspace, and absolute positioning. Paging
back and forth through the file is accomplished at a keystroke. The user does
not need to know any diskette information (such as number of sides, number of
sectors, etc.).

3) ASCII, Hex or case independent string searches are easily performed. There
is a repeat command to position to subsequent occurrences of the same string.
DBUG searches the entire file, not just the current record. It searches for
text or ASCII strings up to 16 characters in length. Hex search strings can be
up to 8 bytes in length.

4) The Print and List commands allow sending an individual record or any
number of records to a printer.

5) A Disk Mode is also available to work with an entire disk (at the sector
level).

Throughout this manual, a character or word between vertical bars is used to
represent a keyboard key. Thus the symbol, |RETURN|, refers to the keyboard
key marked RETURN and not a six letter word. |P| means the "P" key etc.

ENTERING DBUG

DBUG may be entered simply by typing DBUG and pressing |RETURN| (assuming
DBUG.EXE is on the default drive). Optionally, a drive and/or filename may
be entered on the command line in the following format:

DBUG [d:][path\filename][.ext]

If no drive or filename was used when entering DBUG, a prompt will appear
for it. Answer this prompt by giving the filespec or drive you wish to
examine/modify. The filename may consist of up to 79 characters, and may
contain path names. To exit DBUG at this point rather than entering a
filespec, press the |RETURN| key, and control will return to the DOS level. If
an illegal or improper filespec is given, the appropriate error message will
appear, and the filespec prompt will re-display.

Hexadecimal notation in the form (X'nn') will be used to represent the current
record number and relative byte number. After a valid filespec has been given,
record X'0000' will appear on the screen, and be resident in the "edit
buffer". The term "edit buffer" will refer to the portion of the file
currently in the computer's memory which is simultaneously being displayed.

The edit buffer (also referred to as current record) will contain one DBUG
record (256 bytes) at any given time. There will be two cursors flashing
within the record (one cursor will be in the "ASCII" portion of the screen,
the other cursor will be in the "Hex" display portion). Upon initially
accessing a file, these cursors will be positioned over relative byte X'00' of
record X'0000'. Throughout this documentation, the term "relative byte" will
be used, and will indicate the byte number (X'00'-X'FF') relative to the
beginning of the current record.

There will be an input cursor located on the lower portion of the screen
following the message "Command". This will be referred to as the "command
buffer", and will be used to pass commands to DBUG.

Additional information shown on the screen will be the current record number,
filespec, relative byte within the sector, etc. The following sample display
shows where this information will be presented.

0123456789ABCDEF BYTE 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

| ......(.......KI | <00> | 00 FE 14 01 00 00 28 10 05 C3 08 00 00 00 4B 49 |
| ......DO.<....PR | <10> | 07 D0 0B 00 00 00 44 4F 06 3C 0E 00 00 00 50 52 |
| ......SI......SO | <20> | 15 08 02 0D 00 00 53 49 17 10 02 0F 00 00 53 4F |
| ......JL.g.= ..X | <30> | 0A 00 00 0A 00 00 4A 4C CD 67 02 3D 20 0C CD 58 |
| ..g.w#....=(..g. | <40> | 02 CD 67 02 77 23 10 F9 18 EE 3D 28 0B CD 67 02 |
| G.g......g.G.g.o | <50> | 47 CD 67 02 10 FB 18 E0 CD 67 02 47 CD 67 02 6F |
| ..g.g..., ...tC. | <60> | 05 CD 67 02 67 05 C9 D9 2C 20 0D E5 CD 74 43 E1 |
| .{............!. | <70> | 1C 7B D6 12 20 02 5F 14 7E D9 C9 01 88 0F 21 9B |
| ...A..+.....cPV. | <80> | 02 7E ED 41 D3 89 2B 05 F2 81 02 C9 63 50 56 08 |
| ......e......... | <90> | 18 00 18 18 00 09 65 09 00 00 00 00 00 00 00 00 |
| ................ | | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
| ................ | | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
| ................ | | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
| ................ | | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
| ................ | | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
| ................ | | 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |
Record X'0000' Byte X'84' => X'D3' = 1101 0011 = 211
D:PATH\FILENAME.EXT


|A| Enter ASCII modification mode
|B| Position to the Beginning of the file
|C||RETURN| Clear record with zeroes
|E| Position to the End of the file
|F| Enter Find mode and:
|A| find ASCII string
|H| find Hexadecimal string
|T| find Text string
|G| Go to the next occurrence of last search
|H| Enter Hex modify mode
|L||RETURN| List disk file to printer
|N||RETURN| Enter a New file
|P||RETURN| Print current record in edit buffer
|R| Position to Record
|S||RETURN| Save current record in edit buffer
|X||RETURN| Exit DBUG
|ESCAPE| Cancel current DBUG command
|RETURN| Display DBUG instruction set (Menu)
|+| |=| Advance one record in the file
|-| Backup one record in the file



Cursor Movement Commands

|@ nn| Position cursor to relative byte X'nn'
|Lt arrow| Move cursor left one byte
|Rt arrow| Move cursor right one byte
|Up arrow| Move cursor up one line
|Dn arrow| Move cursor down one line
|HOME| Position cursor to relative byte X'00' of the current record

The @ positioning command requires a hex byte consisting of up to two hex
digits. This may be any number X'0' through X'FF'. However, if a single digit
is used (no leading zero), the |RETURN| key must be pressed in order to
execute the command. This is because the |@| command expects two digits. If
two digits are used, the command will execute immediately after the second one
is typed.

This arrangement is used throughout DBUG whenever information must be
supplied in addition to the command key. Merely remember to press |RETURN| if
nothing occurs after typing in a command. This is especially true for the
strings used in all of the FIND subcommands.

The arrows may be used from within either the ASCII or Hex modification modes
to position within the buffer. The "@" command will not be accepted during
either modify mode.

The cursor movement commands will not wrap into either a prior or a subsequent
record. To switch records, use the record manipulation commands. No cursor
movement will occur if an attempt is made to violate buffer boundaries.

RECORD MANIPULATION COMMANDS - FILE MODE

|+| Advance one record sequentially in the file. For example, if the
current record is X'000C', after pressing |+|, record X'000D' would be
displayed (provided that it exists). Issuing the |+| command will not change
the position of the relative byte cursors.

|-| Back up one record sequentially in the file. If the current record is
X'0087', after pressing |-|, record X'0086' would be displayed. Issuing the
|-| command does not change the position of the relative byte cursors. The |-|
command will be ignored if it is issued when record X'0000' is being
displayed.

|B| Position to the beginning of the file (record X'0000') and position
cursors to relative byte X'00'.

|E| Position to the end of the file. Although 256 bytes are shown, the
true end of file may not be at relative byte X'FF'. Any modifications made to
bytes beyond the true EOF offset byte are usually superfluous.

|R|nnnn Position to Record X'nnnn', provided record X'nnnn' exists in the
file. If the record does not exist the request will be ignored. After entering
|R|, the prompt Record X' ' will appear in the command buffer. The input
for the record number will be taken within the single quotes. Hex digits (0-F)
must be entered. Any other characters will be ignored. |ESCAPE| will cancel
this command. The user may enter the record number without using the standard
four digit (X'nnnn') format. Simply type in the record number and press
|RETURN|. For example, if the desired record number is X'0021', type |R||2||1|
and press |RETURN|. The position of the relative byte cursors will remain
unchanged after positioning to the new record.


DBUG MODIFICATION COMMANDS

|A| Enters the ASCII Modification Mode. In this mode, modifications can be
made directly in ASCII. Any character that can be generated from the keyboard
(with the exceptions of the |ESCAPE| key and the cursor motion keys) can be
directly entered into the edit buffer. Modifications can be made by
positioning the cursor over the bytes to be changed. After the |A| command is
issued the command buffer will display "ASCII Modify". From this point on, any
characters entered will be taken as modifications to the bytes in the edit
buffer. After a character is entered, the cursors will position to the next
character in the edit buffer. If the cursors are positioned at the last
character in the edit buffer, no advance will occur. The arrow keys may be
used to position the cursor without altering the buffer contents. Any changes
made to the buffer WILL NOT automatically be written to the file. In order to
save changes to the file, see the |S|ave command. To exit the ASCII modify
mode, press the |ESCAPE| key.

|H| Enters the Hexadecimal Modification Mode. In this mode, modifications to
bytes in the edit buffer are accomplished by typing hexadecimal digits. After
the |H| command is issued, the command buffer will display "Hex Modify". From
this point on, hexadecimal digits (0-F) must be entered to modify bytes in the
buffer. Note that since a single byte is represented by two hex digits, hex
modify edits one nibble (half a byte) at a time. The arrow keys may also be
used to position the cursors for additional editing. To exit the Hex modify
mode, press the |ESCAPE| key. Like the ASCII Modification Mode, no changes are
automatically made to the file. To make the modifications to the file, see the
|S|ave command.

|C||RETURN| Clears the buffer contents from the cursor position to the end of
the buffer by filling it with X'00'. Some files have erroneous or random
information past the end-of-file offset byte in the last record. The clear
command can be used to overwrite the remainder of the buffer with zeroes to
facilitate viewing. Again, since none of the edits perform an automatic write
to disk, |S| is necessary to save the buffer contents.

|S||RETURN| Save the contents of the current edit buffer to disk. The current
record will overwrite the contents of the disk record.

DBUG Control Commands

|N||RETURN| Causes a prompt for a new filespec. DBUG will clear the screen,
print its sign-on message, and prompt the user for a new filespec.

|X||RETURN| Exit to operating system.

|RETURN| The |RETURN| key is used as a confirmation to complete most commands
that result in significant alteration of the current record. |RETURN| alone
will display a menu containing most of the DBUG commands, and a brief
description of their use. Pressing |RETURN| at the menu page will return to
the display mode.

|ESCAPE| The |ESCAPE| key is used to abort a DBUG command in progress.


DBUG OUTPUT COMMANDS

|P||RETURN| Print the current buffer contents, to a printer. If the printer
is not on line, the error message "Printer Not Ready" will be displayed.
Pressing |RETURN| at the error will attempt to print again. Pressing |ESCAPE|
will abort the operation. Note: if a printer is not physically connected,
DBUG may not display an error message. Pressing ESCAPE will exit the print
mode, however, and return to the command mode.


|L||RETURN| List the file to a line printer starting with the current buffer.
The listing will terminate when the end of the file is encountered, or when
|ESCAPE| is pressed. Error handling works exactly as with the |P| command.


DBUG SEARCH COMMANDS

|F| Enters the FIND mode. A "FIND" prompt will appear in the command line. A
subcommand declaring the type of search must be entered. After entering the
subcommand, an appropriate prompt will display followed by a data entry space
in quote marks. The following are the three FIND sub-commands:

|A| Find ASCII "string". This is a literal search for the exact ASCII
characters entered. "string" is a group of from one to sixteen ASCII
characters. If less than 16 characters are typed, the |RETURN| key must be
pressed to initiate the search.

|H| Find Hexadecimal "string". This is a literal search for the exact
hexadecimal bytes entered. "string" is a group of up to 16 hex digits (8
bytes). Only the valid hex characters (0-F) will be accepted.

|T| Find Text "string". This is a search for ASCII characters ignoring
differences in case. The same restrictions which apply to |A| apply to |T|.

|G| Go to the next occurrence of the last searched string. It simply looks for
the last "find" item specified again. It also "remembers" the last search
criterion as long as DBUG is active. This means that searches through
different files for the same string are possible without the re-entry of the
string.

Pressing |ESCAPE| at any time during the input sequence or search will cause
DBUG to display the record which was current before the search started.
During a search, only the current record number being searched will appear on
the screen. If the search string is not found, or if a disk error occurs, the
appropriate error message will be displayed and the file will be positioned to
the record current before the search began.


DISK MODE

Occasionally it is desirable to work with an entire disk as opposed to a
single file. For this purpose, the DBUG disk mode makes it possible to treat
the entire disk as a file. DBUG commands will work as described for the file
mode except as described below. To enter the disk mode, simply give the
drivespec (drive letter followed by a colon) at the "Filespec:" prompt.

The standard format of an MS-DOS 2.00 disk uses 512 byte sectors. Since only
256 bytes can be displayed at a time with DBUG, a backslash character "\"
will appear after the record number to indicate the second 256 bytes of a
sector.

|R| nnnn Position to Record X'nnnn' on disk. The Record number consists of
the absolute sector number. For example, typing |R||0||0||1||5| would position
to sector X'15', the twenty first sector of the disk. Pressing |RETURN|
following the record number is required only for requests consisting of less
than four digits. For example, position to sector 4 could be accomplished by
typing |R||4||RETURN|. The |R| command always positions to the first 256 bytes
of a sector.

|B| Position to Beginning of Disk (Cylinder 0, Sector 0). After issuing a |B|,
the current Record number would be X'0000', and the first 256 bytes would be
displayed.

|E| Position to End of Disk. The actual sector number would depend on the type
of disk. The second half of the sector will be displayed in the buffer.

|+| Position to next sector or the second half of the current sector.

|-| Position to previous sector or the first half of the current sector.


DISK I/O Errors

As with any hardware, there is always that chance of something going wrong.
This could happen when reading from or writing to a disk. For some reason,
some component failed to do its job. The problem could be in the disk media,
the disk drive, the disk controller, or the computer. Whenever an I/O error
occurs, DBUG reports the error and waits for operator input. When the
current buffer is displayed, the information in it may not be valid, depending
on the disk error.