CABLE - Compare And Browse with Limited Editing

Documentation for Version 1.99

David Mitchell

Introduction

CABLE - Compare and Browse with Limited Editing - is a program that offers you the ability to view two files at the same time in both HEX and ASCII or EBCDIC, using the cursor keys to scroll back and forth.

As well as simple compare and search facilities, CABLE also offers limited editing - no create, insert or delete, just update in place.

This document describes CABLE's main functions and is based on the CABLE.HLP file which provides on-line help available within CABLE. Since it also contains some information on CABLE's design, it may answer some of the questions you might have about why CABLE works the way it does and why it doesn't do some of the things you might want or expect it to.

At the end I've added some notes on ways in which CABLE can be patched slightly (using CABLE of course!).

CABLE Functions

Invoking Cable

The CABLE command can be used in the following ways:

  CABLE                    without options, both windows will be empty
  CABLE file1              top window will display file1
  CABLE file1 file2        file1 in top window, file2 in lower window
  CABLE ?                  jumps directly to these help screens
  CABLE file1 file2 /E     force use 43-line mode
  CABLE x.exe c:\pp\*.*    x.exe at top, c:\pp\x.exe at bottom

If you use an * instead of the name or the extension parts of file2, CABLE will copy the corresponding part of file1, as in the last example.

The CABLE Screen in 25-line Mode

The CABLE screen consists of:

Here's a screen image of CABLE in action, comparing two binary files (actually, two different versions of itself):

The CABLE Screen in 43-line Mode

CABLE can be switched into a 43-line mode. In this case the screen consists of

The Structure of a File Window

Each window has a title line, displaying the name (including drive and path), the file size (in decimal and hex) and the attributes of the file. The five attribute codes are:

H
hidden file
S
system file
R
read-only file
A
archive bit (file changed since last backup)
D
Sub-directory

Each window displays 128 bytes of data, arranged as 8 lines of 16 bytes (or 272 bytes - 17 lines of 16 bytes in 43-line mode) Each line shows the data in HEX on the left and in character form on the right. The current position is at the middle of the window - the sixth byte of the fifth (or ninth) line. The offset of this byte from the start of the file is displayed in the boxes on the left in decimal and hex. The centre of the screen shows 64 bytes from each file surrounding the current position in ASCII or EBCDIC, to make it easy to compare the two files.

The active window, the one on which CABLE commands will operate, is highlighted. The Tab key "toggles" between windows.

The Six Indicators

The six indicators on the left of the screen are:

Respect/Ignore
this determines if case is significant during searching and comparisons. Respect means it is while in Ignore means it isn't.
Forwards/Backwards
this determines which direction CABLE uses for searches and comparisons.
Character/HEX
this determines whether Edit and Search expect character strings or pairs of hex digits as input.
Conceal/Show
if you try to print the screen (via Shift-PrtSc), characters with ASCII codes below X'20' will disrupt printing because they are treated as printer control characters. In Conceal mode such characters are displayed as '.' to avoid this.
ASCII/EBCDIC
CABLE can display character data as EBCDIC instead of ASCII.
Active/Both
the scrolling keys can be made to scroll the files in both windows or just the one in the active window.

The first five indicators can be toggled in two ways:

  1. by pressing the F2, F3, F4, F5 or F6 keys
  2. using the options sub-menu

The sixth indicator can only be toggled using the F7 key.

Note that these keys are active at all times, even when editing or entering strings for the Search command or filespecs for the Dir and View commands.

Scrolling in CABLE

CABLE responds to the cursor keys as shown below:

       Home              Up               PgUp
   Top of File      Back 16 bytes     Back 64 bytes

       Left                               Right
   Back 1 byte                        Forward 1 byte

        End             Down              PgDn
   Bottom of File   Forward 16 bytes  Forward 64 bytes

The Main Menu

The main menu shows the following commands:

Compare
this scans both files, starting at the current position. It stops when a difference is found, or at end of file. Pressing any key during the compare causes it to be interrupted - the NEXT command will continue it.
Dir
you can display a directory listing within CABLE using this command which works very much like the DOS DIR command. CABLE can display up to 175 directory lines. If there are more, CABLE will beep and display an error message and only the first 175 lines will be shown.

The directory can be scrolled using the cursor keys, while if Ctrl-Enter is pressed, the highlighted file is selected for viewing in the active window. Note that although sub-directory entries are shown, these cannot be viewed as files.

You can also sort the directory, on Name, Extension, Date or Size, by pressing "S". The format of dates in the directory listing is determined by the COUNTRY= setting of CONFIG.SYS. Thus COUNTRY=44 (the code for the U.K.) will cause dates to be displayed in dd/mm/yy form.

Edit
The Edit command allows you to alter the file in the active window, either by entering characters (in Character mode) or hexadecimal digits (in HEX mode). As well as entering data you can also use the scrolling keys to move about in the normal way. If the scroll mode is BOTH, then the other file will scroll as data is entered. The Tab key will toggle between the windows. You can also use the F2-F7 keys to toggle modes. The Esc key terminates editing and returns you to the main menu.

The changes you make to the file will NOT be written to disk until you:

  • use the Write command
  • or scroll to a new part of the file when all 4 buffers are full
  • or view another file in the same window (using View or from Dir)
  • or quit from CABLE

In any case, CABLE will ask you to confirm the writing and will not let you write to Read-Only files.

Help
this command provides access to the on-line help screens. These can also be accessed by pressing F1, in which case you will get context-sensitive help - that is help related to the current high-lighted command.
Mode
this causes the Mode sub-menu to be displayed. If you have both colour and mono displays, this lets you switch between them. If an EGA is present it also allows you to select a 43-line mode.
Next
this command repeats the last Compare or Search command (whichever was later). It starts at the byte after (before if the current direction is Backwards) the current position, so for example after a Search the repeated use of Next will locate each occurence of the string in turn.
Options
this causes the Options sub-menu to be displayed. This lets you toggle five of the six mode indicators (the sixth, the Active/Both toggle, is altered using the F7 key).
Quit
this command leaves CABLE, closing any open files, and returns to DOS. If either file has been edited, you will be asked if you want to save any changes.
+ - =
these three commands are very similar. They change the current position as follows:
  • + adds the value to the current position (moves forward)
  • - subtracts the value from the current position (moves backward)
  • = makes the value the new current position.

They accept a number which can be in decimal (up to 8 digits), or a hex value (if preceded by H or h). Blanks are ignored in a hex string so H 0e bc , h 0ebc , H ebc and h00EBC are all equivalent.

Search
this asks for a string and then searches the file in the active window for it. Searching starts at the current position and stops when the string is found or at end of file. Pressing any key during the search causes it to be terminated.

In HEX mode the string is specified as pairs of decimal digits rather than characters.

View
this prompts you for a filespec and then displays the file in the active window. Any current file is closed (if it has been altered by Edit you'll be asked if you want to save the changes before it is closed). The filespec can include drive and path specifiers.

Note that a file may also be selected for viewing by:

  • selecting a file from the directory display
  • following the CABLE command with a filespec

If the file does not exist or an error occurs while the file is being opened, CABLE will beep, and an error message will be displayed.

Write
this writes out any changes that have been made, by Edit, to the file in the active window.

Some Design Decisions

In 1983 I wrote CAB, CABLE's predecessor, for a very specific purpose. It was intended to help people in IBM Entry Systems Europe examine different language versions of IBM PC programs that we were producing for sale in Europe. The machine readable information (MRI) in these programs needed to be checked to make sure that the text we had translated was properly incorporated. With CAB you could quickly compare US MULTIPLAN with French MULTIPLAN to check just what the differences were.

CAB's ability to display large files of any format made it useful for a number of other, more general purposes, but it suffered from two limitations:

Jack Gulley, of ESD Engineering Development in Boca Raton, offered to improve the colour display scrolling. I was so impressed with the results, that I decided to remove the other limitation by adding editing to CAB. The result was CABLE.

The decision to add editing to CABLE was not taken lightly. I didn't want to make CABLE much larger than CAB, so the amount of extra code I was prepared to write was small. On the other hand I did want to make the editing useful and safe.

The size limitation is the reason for keeping to update-in-place editing only. You can't create a new file, or insert or delete data. Thus CABLE is just a patching tool, not a real editor.

The question of when to write the changes out was also not easy to settle. On the one hand, I wanted to make it depend on a deliberate decision by the user, while on the other I didn't want to have to use spill files and the other things that would be required if the user could delay writing indefinitely.

After several attempts I settled on the present scheme. The user can make unlimited changes to the 16K of data that can be held in memory at one time without having to WRITE it out. If an attempt is made to scroll into another 4K section when changes have been made then CABLE asks the user if the changes are to be saved. A NO response means data will be lost, overwritten by the new chunk of data being read in.

A similar confirmation is requested if the user tries to quit from CABLE or view another file with changes outstanding. Since this may happen when the directory is being displayed, the message CABLE issues tells the user which file is involved.

The WRITE command also asks for confirmation. A NO response here will not lose data - and the message merely says "Changes not saved" rather than "Changes lost". A later WRITE could still save the changes.

When data is to be written, CABLE opens the file for output, writes the changed sections, and closes the file again. Thus the opportunity for loss of data is limited. I added the code to trap Control-Break (which was not in CAB) so that the user could not abort CABLE during a write operation.

After the data has been written, CABLE displays a message indicating how many bytes have been written out.

One problem associated with the scheme employed by CABLE is that it is possible for the user to become confused as to whether the data on the screen is the same as the data on disk - you can forget whether changes have been saved. This problem does not occur with the method employed by Bob Flavin's program Disk Repair (aka SPY), where scrolling causes any changes to the buffer to be lost. However the CABLE user can always display the file in the other window and compare the new data read from disk with the data in the buffer.

In version 1.8 I switched to using F7 rather than Scroll Lock to toggle between Active (where just one window reacts to scrolling commands) and Both (where both windows scroll). This is because:

Design Limitations

The way numbers such as file sizes and offsets are handled inside CABLE limits the maximum size file that CABLE can handle to 99MB. This limitation is partly due to allowing only 8 digits on the screen to display such numbers, but also due to the way CABLE addresses data within a file. It uses 12 bits to address a byte within a 4K block, and 16 bits to address a block within the file. Since the block number is treated as signed it can't exceed +32K, giving a maximum byte address of 4K * 32K = 128MB. It would be possible, but difficult, to remove this restriction. At the time I wrote CABLE, PC DOS didn't allow disks larger than 32 MB anyway - in fact the largest IBM hard disk was the 10MB XT hard drive!

CABLE has 4 buffers, each 4k in size, for each file. A least-recently-used algorithm controls what is in them. The fact that CABLE is a COM file, together with the way it uses memory, makes it impossible to enlarge either the number or the size of the file buffers without a lot of re-programming.

Messages

Quite a bit of space inside CABLE is taken up with messages. Most of the messages should be self-explanatory, but here are a few notes anyway.

CABLE needs 64K of free memory to run properly. Although the program is less than 16K in size, it uses 32K for buffers (see design limitations above), an 10.5K buffer for the help file and a 5K buffer for the directory. Finally it needs room for a stack. If you run it with less space available, you may get one of the following messages:

I thought it more important to keep the HELP function and suppress DIR.

CABLE traps the DOS critical error interrupt, so things like leaving the diskette drive door open don't result in the DOS "Abort, Retry or Ignore" message. I/O errors result in one of the following messages appearing instead:

The last message is produced if I/O errors occur during the DIR function. If I/O errors do occur it's best to leave CABLE and try to examine and repair the diskette some other way.

The following messages appear if the help file or directory list are too large for the buffer space available:

EBCDIC Support

CABLE's EBCDIC support provides the following facilities when in EBCDIC mode:

CABLE uses three tables to provide this support:

  1. an EBCDIC upper case translate table
  2. an ASCII to EBCDIC translate table
  3. an EBCDIC to ASCII translate table

These tables are patchable if you want to alter the way CABLE does things. See the next section for details.

Patching CABLE

The following patches can be made to CABLE.COM

The necessary fields are at the start of the CABLE.COM file, and can be changed quite easily using CABLE itself. The offsets are:

  Hex Offset  Contents           Initial Value
     3        NoData character   '*'   (=X'2A')
     4        Normal Mono Att.   X'07' (green on black)
     5        Hilite Mono Att.   X'70' (black on green)
     6        Normal Color Att.  X'1E' (yellow on blue)
     7        Hilite Color Att.  X'78' (black on grey)
     8        Case Switch        X'FF' (FF= respect, 0 = Ignore)
     9        ASCII/EBCDIC       X'00' (0= ASCII, FF=EBCDIC)
     A        lohex conceal      X'00' (0=conceal,FF = show)
     B        Character/HEX      X'00' (0= Char, 1=HEX)
     C        Direction          X'00' (0=forward, FF= backward)
     D        Scrolling Mode     X'00' (0 = Active, 1 = Both)
     E        video register     X'DA' (if set to zero then snow
              address (CGA)      X'03'  will not be eliminated)
    10        Help for Compare   X'06'
    11        Help for Dir       X'07'
    12        Help for Edit      X'09'
    13        Help for Help      X'01'
    14        Help for Mode      X'08'
    15        Help for Next      X'06'
    16        Help for Options   X'08'
    17        Help for +         X'05'
    18        Help for -         X'05'
    19        Help for =         X'05'
    1A        Help for Quit      X'0A'
    1B        Help for Search    X'06'
    1C        Help for View      X'04'
    1D        Help for Write     X'09'
    1E        Name of Help File  'CABLE.HLP',X'00'
              followed by 53 blanks
    5E        256 byte ASCII upper case table
   15E        256 byte EBCDIC upper case table
   25E        256 byte ASCII to EBCDIC translate table
   35E        256 byte EBCDIC to ASCII translate table

The NoData value at offset 3 is used to fill the hex part of a file window that is before the start or after the end of the file. It's initially set to an asterisk.

The Case switch at offset 8 determines how searching and comparing regard upper and lower case. A switch value of X'FF' means respect case (i.e. this and THIS are not the same) while a value of 0 means ignore case. Note that CABLE treats accented characters the same as DOS 3, so that e, E and various accented e's are all regarded as the same.

The switch at offset 9 determines whether CABLE treats data as ASCII (0) or EBCDIC (FF).

To allow characters with ASCII values below X'20' to be displayed just give the switch at offset A any non-zero value. Note that this works correctly even in EBCDIC mode.

The Character/HEX switch at offset B determines whether the search and edit commands expect data to be in character form or HEX digits (two digits/byte). A value of 0 means character while 1 means HEX.

The Direction switch at offset C determines the direction of searches and compares. A value of 0 means forward toward the end of file while FF means backward toward the beginning.

The Scrolling Mode switch at offset D determines whether only the Active window reacts to scrolling commands or whether both windows do. A value of 0 means only the Active window scrolls while 1 means both do.

The video register address at offset E determines if CABLE tries to eliminate snow on the CGA (and CGA-like adapters). If set to X'0000' then snow will not be eliminated but scrolling will be much faster. Set to X'03DA' (NB due to the way numbers are stored on 808x machines this means X'DA' at offset E and X'03' at offset F) snow will be eliminated.

Current display adapters do not suffer from snow. CABLE will detect the presence of such an adapter and set the value to zero itself in this case.

If you change the name of the help file remember to follow it with a X'00' byte. There's room for a name up to 63 bytes long.

If you change the content of the Help file you must make sure that it contains no TAB characters, since CABLE will not display it properly if it does. You must also keep its size below 10.5K.

The various translate tables can be patched if you don't like the way they work.