EDFILE is a public domain utility which allows display and
editing of data in files. It has been tested and run under CP/M-
80 version 2.2 and TurboDOS 1.2 and should run in any CP/M-80
type environment.
EDFILE is approximately 11k in size. EDFILE may be freely
distributed to whomever desires it. The date of this document
should agree with the version date in EDFILE.
FEATURES:
========
- Hex and ASCII display of record data.
- Screen editing of selected record.
- Hex or ASCII input when editing file records.
- Fully programmable cursor control.
- Powerful file search capabilities.
- Forward and backward record scrolling.
- Address and/or record number referencing.
- Decimal or Hex number inputs.
- Disk reset on input (prevents Disk R/O error).
- Full online abbreviated help AND expanded help menus.
INSTALLATION:
============
The following information will aid the user when installing
EDFILE on a different terminal.
The EDFILE original distribution program is originally configured
for an ADM-3A type terminal or equivalent (I use a Digilog
S1500). The terminal must be able to display 80 columns by 24
rows. The only absolutely necessary function required for proper
use is the cursor positioning function. Other functions
that can be added merely for visual purposes are the cursor on,
cursor off and clear to end-of-line functions. If the clear to
end-of-line function is not preprogrammed, it is performed in
software. These functions are not implemented in the original
distribution version of EDFILE. For ADM-3A type terminals, the
following commands can be patched in EDFILE if these attributes
are desired:
For example, to add the clear to end-of-line function, patch a 02
for the string length (2 bytes for the sequence) at address 146.
Then patch a 1B in location 147 and a 51 in location 148.
Certain functions are programmable for the type of terminal in
use. Five bytes are reserved for each terminal function (string
sequence). The first byte represents the length of the string
sequence. For example: the initial cursor positioning string for
an ADM-3A terminal is 'ESC ='. This is two bytes in length.
Therefore, the values inserted into the cursor positioning
sequence area are (in hex): 02,1B,3D. To complete the cursor
positioning sequence for the terminal, the row and column must be
issued as well. The ADM-3A requires an adjustment value (or
offset) of 32 decimal (20 hex) be added to the row and column.
For terminals that require a different offset, this value can be
changed as well.
The row is usually sent before the column, but if your terminal
is different, i.e., the column must be issued first, then set the
high order bit of the cursor offset value. This flags the cursor
positioning routine to send the column before the row. The
following addresses detail the location of the modifiable
parameters for the terminal.
Address Default (hex) Function
------- ------------- --------
140 02,1B,3D,00,00 *Initial cursor positioning string sequence
145 20 *Row/column adjustment (set high bit for column/row)
146 00,00,00,00,00 Clear to end-of-line string sequence
14B 00,00,00,00,00 Enable cursor (cursor on) string sequence
150 00,00,00,00,00 Disable cursor (cursor off) string sequence
155 08 Cursor left (normally CTRL-H)
156 0C Cursor right (normally CTRL-L)
157 0B Cursor up (normally CTRL-K)
158 0A Cursor down (normally CTRL-J)
159 00..........00 Terminal initialization string (35 bytes)
* - Must be implemented.
If your terminal requires some sort of initialization string,
either to preset it or to program a function key pad, this can be
inserted into the terminal initialization string area provided.
The first byte represents the length of the string to be issued
to the terminal. There are 35 bytes available for an
initialization string. Why so many? The Digilog S1500 computer I
use allows reprogramming of the numeric keypad. This requires 28
bytes.
The actual control sequences for positioning the cursor (up,
down, left and right) can be changed. This is provided for
terminals that have cursor positioning keypads which don't issue
the same ones programmed here. For example: usually a CTRL-L
moves the cursor one space to the right. However, if your cursor
pad issues some other control character, like a CTRL-D (WordStar
type), then patch a 04 (hex equivalent of CTRL-D) for the cursor
right value. Note, the help menus will still display the default
values for up, down, left and right cursor movements. You'll have
to make a note about this or, better yet, use EDFILE to patch the
help menus.
All of the above modifications (patches) can be made easily with
EDFILE itself. Of course, if it won't run at all, you'll have to
resort to some sort of debugger such as DDT, SID, MONITOR,
etc..., or better yet, use someone elses computer with a
(working) version of EDFILE to modify it for your terminal.
EDFILE should work on virtually all terminals currently in use.
There may be some real strange ones out there that I don't know
about, but that's life.
OPERATION:
=========
EDFILE is simple to use especially with the online help menus.
Therefore, just a few tidbits of information is provided here for
operation. To invoke EDFILE, simply type EDFILE followed by the
name of the file you wish to dump and/or edit. Example:
EDFILE performs an automatic disk reset (^C) when executed.
Therefore, don't panic if you suddenly realized you forgot to
perform a Control-C after making some changes. This prevents the
infamous (and frustrating) Bdos Err on A: R/O from occuring when
writing records.
The LOF means the Length-Of-File which is the total number of
records in the file. Record numbers begin at 0; the last
displayable record number is actually the LOF - 1.
If you don't specify a file on the command line, you'll get an
error: "No File Specified."; or if the file is not found, you'll
get an error telling you this: "<filename> Not Found." Simple.
At the ? prompt, type 'H'. The brief help menu will be displayed:
-------------------------------------------------------------------------------
Read/Edit File Utility Functions:
A - Address to dump B - Dump at beginning C - Continue Search
E - Enter Edit Mode H - This help list M - Expanded Help list
O - Set address offset Q - Quit this program R - Read & dump record
S - Search for string Z - Dump at end of file CR - (+/=) - Adv record
(-/_) - Decr record
Edit Mode Functions:
^E - Toggle data fields ^W - Write buffer out ^X - Abort Edit Mode
^J - Cursor Down ^K - Cursor Up ^H - Cursor Left
^L - Cursor Right
-------------------------------------------------------------------------------
Again at the ? prompt, type 'M'. This will display the expanded help menu.
-------------------------------------------------------------------------------
Read/Edit File Utility Functions:
A - Enter relative address to dump
B - Set record to beginning of file and dump data
C - Continue search. Restarts search on last entered search string.
E - Enter Edit mode on current record
H - Brief description of the functions
M - This help description
O - Enter offset address relative to start of file (.COM = 100h)
Q - Quit program
R - Enter record number to dump
S - Search for hex or ASCII string in file (starts at current record)
'\' = ASCII string delimiters (ex: \Test\)
',' = hex and/or ASCII delimiters (ex: 41,\Test\,4A
';' = select search options
A - Start search from beginning of file
B - Search Backwards
M - Search on certain bits set; use mask xx
O - Stop on xx occurrence of string
U - Translate lower case characters to upper case
Z - Search recognition on least significant 7 bits only
Z - Set record to end of file and dump data
CR - carriage return (or +/= key) - advances record and dumps the data
-/_ key - decrements record and dumps the data
Edit mode: ('^' refers to the Control key)
^[ - (ESC) Accept next char into edit field even if a control char
^E - Toggle between ASCII and hex data fields
^W - Flush record to disk
^X - Abort edit mode without updating record
^J - Cursor down ^K - Cursor up
^H - Cursor left ^L - Cursor right
Input integers are decimal. Use 'h' suffix for hexadecimal entries.
-------------------------------------------------------------------------------
Use the '=' key (which has the '+') or the RETURN key to advance
the record. You don't have to use the shift key with the '=' key.
EDFILE will wrap around to the start of the file when attempting
to advance beyond the end of the file.
The following paragraphs expand on the features available in
EDFILE. Most of the options are self-explanatory from the help
menus. However, some require additional explanations and are
provided below.
ADDRESS/OFFSET OPTIONS
----------------------
The address option allows you to specify an address within the
file. This is useful for patching COM files and the like when the
address of the patch is known. Note that when EDFILE'ing COM
files, EDFILE automatically sets the offset to 0100h. The offset
can be changed by typing 'O' at the command level and entering
the desired offset. The headings will be adjusted for the
different offset automatically. The address option always
references the starting offset so that locations within programs
which don't begin at 0100h (overlays, for example) can be easily
referenced once the offset has been properly programmed. The
Address option also has a wrap-around feature so that references
below the current offset will be readjusted. This feature can be
quite handy when tinkering around with COM files. You have to
experiment a little to pickup the usefulness of these options.
SEARCH OPTION
-------------
The 'search' option is the most involved because it offers so
many different possibilites. The description provided here should
provide enough information to effectively use it.
String searches normally start from the current record and
proceed until the end of the file (EOF) is encountered. Certain
suboptions can alter this sequence. If a match is not found, the
program will indicate this and restore the screen to the record
last displayed. The search can be aborted at any time by simply
striking a key.
If a string match occurs across records, the search will stop on
the last record read into its' local buffer and position the
cursor at the end of the found string. It just wasn't worth
putting in the extra code to handle this wierd situation.
When using the Occurrence ('O') and Mask ('M') suboptions, the
program will prompt for the occurrence number and/or search mask
to be used. The suboptions are inserted after a semicolon to
delimit them from the search string entered. No spaces should be
inserted between the suboptions. Upper or lower case is
acceptable. Example:
?Search String = \This is great\;auo
Stop on string occurrence = 3
This means to search for the string 'This is great' starting
from the beginning of the file, ignoring the case of the
string (i.e., translate lower to upper case) and stopping on
the third occurrence of the string.
ASCII strings must be delimitted by backslashes ('\'). The
limitation here, of course, is that you can't search for
backslashes in the file. So use the hex equivalent if necessary:
5C.
The 'U' suboption (translate lower case to upper case) will
translate the search string to upper case automatically, as well
as converting all lower case characters read from the file. So,
you don't have to input the search string in upper case when
using the 'U' suboption.
When inputting hexidecimal values as part of a search key, they
MUST be two-digit HEX (not decimal) numbers. An invalid hex digit
entry will cause an error and the string entry must be reentered.
Two digits must be supplied for each hex number otherwise the
search won't work properly. Upper or lower case for the
hexidecimal letters is acceptable. Example:
?Search String = 40,FE,e5,05
You can mix hex entries with string entries within the search
key. Example:
?Search String = 40,FE,\help me\,E5,05
The Backward search suboption (B) will start the search from the
current record and continue towards the start of the file. It
DOES NOT reverse the search string key, that is, if you enter
\HELP\ for a search string key, it will not search backwards for
\PLEH\. It only refers to the direction the records will be read
while searching for a matching string. Also, each record is
searched from the start of the record. The search stops when the
start of the file (SOF) is encountered.
The Mask suboption is for those cases where bytes in a file use
certain bits for special meanings. The input mask is logically
AND'd with each byte in the file before comparing it to the
search string. Therefore, some bytes could pass the search test
but still may not be exactly what your looking for.
?Search String = 03;M
Enter string search mask = 0Fh
This will mask all upper nibbles (upper 4 bits of each byte)
and then compare it to a 3. Therefore, any data bytes which
have a 3 in the lower nibble will cause a match with the search
key.
When the search string is found in the file, the search is
temporarily terminated and the cursor is positioned at the start
of the found string. Note, that the program is NOT in the edit
mode, so the next key entered is a command not an edit control
key. Hit a space (or any unrecognizable command) to redump the
record and place the cursor on the command line. Hit an 'E' to go
into the edit mode. The cur
sor will remain positioned at the
start of the found string.
CONTINUE SEARCH OPTION
----------------------
Hitting a 'C' at the command level will restart the search from
the current record and cursor position (if previously defined).
The search facility will then look for the NEXT occurrence of the
entered string sequence. The 'O' suboption is affective only on
the initial start of the search. The Continue ('C') option
effectively disables the occurrence value previously entered. The
default string occurrence is 1, i.e., the first (or next)
occurrence. The Continue option can be invoked at any time after
a search string key has been entered. All other suboptions are in
affect when continuing the search.
RECORD EDITING
--------------
Record editing is accomplished by typing an 'E' at the command
level. When in the edit mode, there are two modes of editing. You
can edit the HEXIDECIMAL field area of the record or the ASCII
field area. When entering the edit mode the cursor will be
positioned at the upper left corner in the HEX data field of the
current record. To switch to the ASCII data field of the record,
simply enter a CTRL-E. This will toggle the cursor between the
two fields. The HEX field area will only accept hexidecimal
digits for inputs. The ASCII field will accept all key inputs
including control key inputs if they are preceeded by an ESC key.
For example: to input a CTRL-K into the record at the current
cursor position, hit the ESC key followed by a CTRL-K. The ESC
key simply means 'put the next input character into the record
even if its' a control character'. This is only affective in the
ASCII field area. Non-control characters (i.e., regular ASCII)
can be typed in directly.
To make the record changes permanently to the file, they must be
flushed to the disk by typing a CTRL-W. Typing a CTRL-X will exit
the edit mode without updating the file.
BUGS:
====
There are currenly no know bugs. However, inputs are not
completely validated, therefore, some conditions could cause
different results. None, however, are know to cause file crashes
or anything catastrophic. Any reports of bugs will be noted and
appreciated.
USE UNDER TURBODOS:
==================
EDFILE is especially useful under TurboDOS. Using the filename
$.DSK or $.DIR upon entering EDFILE allows editing of the disk
and/or directory. I use EDFILE in every case when I need to look
at the disk directory and make changes to it. The search facility
makes this task a breeze.
BACKGROUND INFO:
===============
EDFILE was written in a language called SIL (Systems
Implementation Language) which was obtained from DDJ and then
enhanced and improved at Digilog, Inc for use in writing systems
programs and utilities. SIL is very similar to 'C' but allows
true inline 8080/Z80 assembly language coding (very useful) and
compiles to actual assembly mnemonics. The output of the compiler
is passed to Digital Research Inc's Relocatable Assembler (RMAC)
and then to DRI's Linker (LINK). No special tricks were used in
this program; that is, no system specific calls or locations were
referenced, therefore, it should run on any CP/M or equivalent
system. Of course, Murphy is lurking around, so don't depend on
that assumption.
FUTURE VERSIONS:
===============
On the wish list is to add the capability to read and edit the
data off of the disk on a track/sector basis. Any other ideas
will be seriously considered in future versions of EDFILE.
Thanks and good EDFILE'ing.
Problems, suggestions or questions can be sent to me on my
CompuServe number (#72345,1540) or via my home address:
Mike Mosko
519 E. Station Ave.
Coopersburg, PA 18036
