Documentation for XE - a binary file editor






INTRODUCTION

XE is a file editing program that is specially designed for
creation and modification of data files. It is not an editor
for program creation (i.e. writing source code) or for word
processing, and is not meant to be a substitute for programs
that perform those functions. It is, however, very useful to
programmers who are debugging or designing programs that read or
write binary data, and especially to programmers who write
programs that perform data interchange with mainframes or work
with data that is created by or destined for mainframe software
or mainframe devices.

XE is also useful for the knowledgable user who needs to
edit a binary data file, in order to transport the data file
from one program to another. In order to use XE for this
purpose, you will need some familiarity with the data formats of
both the source and target programs.

XE is a binary file editor that supports both ASCII and
EBCDIC character sets. This editor treats a file as a set of
records; each record is called a page. Each page contains 256
bytes and is displayed simultaneously in both hexadecimal and
text formats.

As each page of the file is displayed, XE will allow you to
optionally modify the displayed record; by deleting,
overwriting, or inserting bytes in the page. Page selection
commands allow you to move forward, backward, or at random to
any desired page.

The XE display contains a status area (at the top of the
screen), a data area (16 lines in the middle of the screen), and
an interaction area (at the bottom of the screen).
Configuration commands allow you to change the colors of both
text and background in all screen areas.






COMMAND LINE USAGE

To start XE type:

XE filename

where "filename" should be replaced by the name of the file that
you would like to view or edit. Additionally, XE allows the use
of two command line options, that allow the user to preset color
selection for a monochrome screen or to select support for the



1 Documentation for XE - a binary file editor





EBCDIC character set.

For users who have a monochrome screen, XE accepts a
command option that presets colors for monochrome screens. The
monochrome option can be specified at any position on the screen
as either "-m" or "/m". For example, either

XE -m MYFILE.TXT
or,
XE MYFILE.TXT /M

could be used to edit a file called "MYFILE.TXT" on a monochrome
screen. The monochrome option can be specified with either a
capital or lowercase 'm'. Colors for text and background can
also be selected using the "Configure" command from the main
menu of XE, after the program is started.

If your data file contains only EBCDIC text, you can add
the "/E" option to the command line, to have XE interpret text
as EBCDIC. By default (when the /E option is not present on the
command line, XE assumes that text is encoded with the ASCII
character set. You can switch freely between the two supported
character sets using the "Configure" command from the main menu
after XE is started.

Multiple file names can be specified on the command line;
in which case, XE will allow you to view and edit the files, one
at a time, in the order in which they are specified on the
command line.














SCREEN FORMAT

To begin, XE displays status information in four lines at
the top of the screen. The first line of the status display
contains the name of the file that is being edited. The second
line of the display tells the number of the page that is
currently being displayed, the character set (ASCII or EBCDIC)
that is being used for text translation, and the size (in bytes)
of the current file. The third line of the status area is
usually blank.



2 Documentation for XE - a binary file editor






The fourth line of the status area shows a set of
hexadecimal numbers that are useful for calculating the position
of any particular byte in the current page. This line consists
of sixteen, single-digit hexadecimal numbers; each number
specifies the rightmost digit of the hexadecimal offset of the
bytes that appear in the data column immediately below the
number. The left digit of the offset of a data byte is
specified by the first number that appears in each line of the
data area. More will be said about this later.

Below the status area, there are sixteen lines of data.
Each line of data begins with a four-digit hexadecimal number,
which is the offset within the page of the first byte on the
line. Following the offset, there are sixteen, two-digit
hexadecimal numbers. Each number represents the content of a
byte. Following the hexadecimal representation of the bytes,
there is a sixteen-byte word, which depicts the text
representation of the data, using the currently selected
character set (ASCII or EBCDIC). Bytes that have no graphic
representation in the selected character set will be represented
by a period ('.').

At the bottom of the screen, you will see the user
interaction area. This is where you will enter commands and
where the program will prompt for new data. When you type
commands or data, these will appear on the bottom line of the
current user interaction area.















MAIN MENU COMMANDS

The menu of the first screen appears at the bottom of the
screen in the user interaction area. This menu is called "the
main menu", and contains eight commands. The main menu commands
are: 1) Backup, 2) Configure, 3) Delete, 4) Forward, 5) Go, 6)
Insert, 7) Overwrite, and 8) Quit. The main menu looks like
this:
B)ackup, C)onfigure, D)elete, F)orward, G)o, I)nsert,
O)verwrite, Q)uit



3 Documentation for XE - a binary file editor





>
To select one of these operations, you simply type the first
letter of the command.

Three of the main menu commands are "page selection
commands"; these are 1) Backup, 2) Forward, and 3) Go. Three
commands are "data modification commands"; these are 1) Delete,
2) Insert, and 3) Overwrite. The remaining two commands are, 1)
Quit, and 2) Configure.

The Quit command is used to exit and terminate the program.
The modified file is automatically saved when the program is
terminated. If you are unsure of the modifications that you
will be making to the file, it is best to edit a copy of a file
rather than the original file itself.












PROGRAM CONFIGURATION

The Configure command, which appears in the main menu,
allows you to select screen colors and to specify the treatment
that you desire for text. When you press the 'C' key while the
main menu is displayed in the user interaction area, the main
menu will be replaced by another menu that offers the choices:
T)ext treatment, or C)olors. To change the text treatment, you
would then press the 'T' key; to select screen colors, you would
press the 'C' key.

The default treatment for text in data files is that text
is encoded in the ASCII character set, using carriage-return and
line-feed sequences for line termination. After you select the
"Text treatment" option of the Configure command, a third menu
will appear, offering the opportunity to
Select: A)SCII, or E)BCDIC
You may then select a character set by pressing either the 'A'
key (to select ASCII) or 'E' key (to select EBCDIC). If you
select EBCDIC for your character code, the character set
selection menu will then be replaced by the main menu and the
data and status areas will be refreshed to reflect your
selection.

When ASCII is selected as the character set for text data,
an additional menu will appear in the user interaction area that



4 Documentation for XE - a binary file editor





allows you to specify the line termination treatment for newly
entered text data. The "line termination menu" looks like this:

Select line termination: 1) LF, 2) CR, 3) CRLF, 4) NONE
To select a line termination treatment, you must press the
numeric key that appears before the desired selection. If you
press the '1' key, each line of ASCII text that is added to the
data file (by either Insert or Overwrite operations) will be
terminated by an ASCII line-feed. If option '2' is selected,
lines will be terminated by appending an ASCII carriage-return.
Option '3' appends both a carriage-return and a line-feed.
Option '4' does not append any carriage control characters to
the ASCII text data (i.e. text data that is to be inserted,
appended or overwritten in the data file will appear exactly as
it is typed in the user interaction area, without line
termination). After one of the line termination options is
selected, the line termination menu will be replaced by the main
menu in the user interaction area.









PAGE SELECTION COMMANDS

There are three page selection commands that appear in the
main menu; they are 1) Backward, 2) Forward, and 3) Go. To
select one of these commands, you just press the key that
corresponds to the first letter of the command. When you press
the 'B' key, XE will display the previous page of the file.
Pressing the 'F' key will display the next page of the file.
When you press the 'G' key, XE will ask,
What page?
>
Type the number of the page that you want to examine (pages are
numbered sequentially beginning with page number 1) and press
the key.

There are four additional keys that are interpreted as page
selection commands, though they do not appear in the menus.
These are 1) the "Page Up" key (a synonym for the "Backward"
command), 2) the "Page Down" key (a synonym for the "Forward"
command), 3) the "Home" key (which selects the first page of the
file), and 4) the "End" key (which selects the last page of the
file). In order to remember the function of these keys, it
might be useful to think of the beginning of the file as the
"head", and the end of the file as the "tail". These keys are
active whenever the main menu is displayed (i.e. when the other
page selection commands appear in the menu in the user



5 Documentation for XE - a binary file editor





interaction area).










FILE MODIFICATION COMMANDS

There are three file modification commands which appear in
the main menu; they are 1) Delete, 2) Insert, and 3) Overwrite.
These functions are selected by pressing the key that
corresponds to the first letter of the command, while the main
menu is displayed.

DELETING DATA

When you press 'D' to select the Delete function, XE will
ask,
At what offset (in hexadecimal)?
>
Type the hexadecimal number that corresponds to the offset of
the data that you wish to delete on the currently displayed
page. You can read this offset from the screen by combining the
row offset (a four-digit hexadecimal number that appears at the
beginning of each row of data) with the column offset (which
appears at the top of each column of data in the last line of
the status area). To combine the row offset with the column
offset, just replace the last zero of the row offset with the
single digit that appears as the column offset. The offset of
the data must be a number between 00 and ff (255), since a
number smaller or larger would correspond to the relative offset
of data on an undisplayed page.

After you have entered the offset of the data that you wish
to delete, XE will ask,
How many (in decimal)?
>
enter the number of bytes that you wish to delete. The number
of bytes that you can delete in a single operation of the
shareware version of XE is dependent upon your current position
in the file. This is due to the view of the file that is
internal to XE. XE views a data file as organized, first, as a
set of pages (each containing 256 bytes). Pages are grouped as
chapters. Each chapter contains 16 pages (or 2048 bytes). The
shareware version of XE will not allow a delete operation that
crosses a chapter boundary. If you are trying to delete a
portion of the data that crosses a chapter boundary, you must
perform separate delete operations in each chapter (2K byte



6 Documentation for XE - a binary file editor





block) of the data.

After you have entered the number of bytes to be deleted,
XE will provide a summary of the operation that has been
requested and ask for confirmation. The confirmation request
looks like this,
284 bytes to be deleted, beginning with byte at offset 0x00de on
page 3.
Is this correct (Y or N)?
If the numbers agree with what you intended, press the 'Y' key;
if they don't, then you can abort the operation at this point by
pressing any other key.

INSERTING DATA

When you press the 'I' key to select the Insert function,
XE will ask,
Begin inserting bytes at what offset (in hexadecimal)?
>
Type the hexadecimal number that corresponds to the offset of
the position at which you wish to insert data on the currently
displayed page. You can read this offset from the screen by
combining the row offset (a four-digit hexadecimal number that
appears at the beginning of each row of data) with the column
offset (which appears at the top of each column of data in the
last line of the status area). To combine the row offset with
the column offset, just replace the last zero of the row offset
with the single digit that appears as the column offset. The
offset of the data must be a number between 00 and ff (255),
since a number smaller or larger would correspond to the
relative offset of data on an undisplayed page.

After you have entered the offset of the position where you
wish to insert new data, XE will ask,
Select input mode: H)exadecimal, or T)ext.
>
If you wish to enter binary data, press the 'H' key; to enter
text data (using the currently configured character set and line
termination) press the 'T' key.

When inserting binary data, XE will prompt,
Enter bytes in hexadecimal. Blank line ends.
>
Type single or two-digit hexadecimal values (which correspond to
the desired content of bytes) separated by spaces. Each time
that you press , the values that you have specified will
be inserted in the file and will appear in the screen data area.
Terminate the operation by pressing on a blank line.

When inserting text data, XE will prompt,
Enter text. Blank line ends.
>
Type the text that you wish to insert, terminating each line of



7 Documentation for XE - a binary file editor





text with the key. The line termination treatment that
you have selected with the Configure command will be appended to
each line and the new data will be inserted in the file and
appear on the screen in the data area. Terminate the operation
by entering a blank line of text (i.e. just press ).

OVERWRITING DATA

When you press the 'O' key to select the Overwrite
function, XE will ask,
Begin replacing bytes at what offset (in hexadecimal)?
>
Type the hexadecimal number that corresponds to the offset of
the position at which you wish to overwrite data on the
currently displayed page. You can read this offset from the
screen by combining the row offset (a four-digit hexadecimal
number that appears at the beginning of each row of data) with
the column offset (which appears at the top of each column of
data in the last line of the status area). To combine the row
offset with the column offset, just replace the last zero of the
row offset with the single digit that appears as the column
offset. The offset of the data must be a number between 00 and
ff (255), since a number smaller or larger would correspond to
the relative offset of data on an undisplayed page.

After you have entered the offset of the position where you
wish to overwrite old data, XE will ask,
Select input mode: H)exadecimal, or T)ext.
>
If you wish to enter binary data, press the 'H' key; to enter
text data (using the currently configured character set and line
termination) press the 'T' key.

When inserting binary data, XE will prompt,
Enter bytes in hexadecimal. Blank line ends.
>
Type single or two-digit hexadecimal values (which correspond to
the desired content of bytes) separated by spaces. Each time
that you press , the values that you have specified will
overwrite current data in the file and will appear in the screen
data area. Terminate the operation by pressing on a
blank line.

When overwriting with text data, XE will prompt,
Enter text. Blank line ends.
>
Type the text that you wish to overlay the current data,
terminating each line of text with the key. The line
termination treatment that you have selected with the Configure
command will be appended to each line and the old data will be
overlayed in the file with the new data, which will appear on
the screen in the data area. Terminate the operation by
entering a blank line of text (i.e. just press ).



8 Documentation for XE - a binary file editor






APPENDING DATA

You can append data by either Inserting or Overwriting data
beyond the current end of the data file. Use the "End" key to
select the last page of the file (refer to the section entitled
"PAGE SELECTION COMMANDS"). Then refer to the sections entitled
"INSERTING DATA" or "OVERWRITING DATA", to learn how to perform
those operations.

















ERROR MESSAGES

error 2000: Stack overflow
Indicates a program error. Please report the problem to
the publisher.

error 2001: Null pointer assignment
Indicates a program error. Please report the problem to
the publisher.

error 2002: Floating point not loaded
Indicates a program link error. This may happen when using
a version of the program that is inappropriate for the
hardware configuration that is being used. Please report
the problem to the publisher with a description of your
hardware configuration, and request the appropriate version
of the program.

error 2003: Integer divide by 0
Indicates a program error. Please report the problem to
the publisher.

error 2004: DOS 2.0 or later required
XE requires DOS version 2.0 or greater (i.e. versions 2.0,
3.0, 3.1, 3.3, 4.0, 4.01 or 5.0). Acquire an appropriate
version of MS or PC DOS.




9 Documentation for XE - a binary file editor





error 2008: Not enough space for arguments
A very rare error (heretofore unheard of) that indicates
that too many arguments were specified on the command line
(probably too many filenames). This may happen when using
wildcards to specify file names. Reload the program,
specifying a smaller number of file names.

error 2009: Not enough space for environment
A very rare error (heretofore unheard of) that indicates
that too many variables are specified in the DOS
environment. Reduce the number of variables in the DOS
environment (see the documentation of the SET command in
your DOS reference manual) and then reload the program.

ERROR: Could not reopen input file.
Could not open the input data file after a data
modification operation. This is an indication of a DOS
level problem (i.e. directory corrupted, FAT corrupted, or
a hardware disk error).

ERROR: Could not create work file.
Could not create a temporary data file to perform a data
modification operation. This is an indication of a DOS
level problem (i.e. disk full, root directory full,
directory corrupted, FAT corrupted, or a hardware disk
error).

Insufficient memory available to perform operation.
Available memory is insufficient to perform a requested
operation. The maximum amount of memory used by XE at any
time is only 192 Kilobytes. This error may occur when the
amount of available memory for program use is less than 192
Kilobytes, due to hardware configuration or use of
multitasking environments that load multiple programs into
memory concurrently. Install more memory, or unload other
programs.

Invalid Selection.
An inappropriate key was pressed.

Invalid selection: No operation performed.
An inappropriate key was pressed, or inappropriate data was
entered.

No operation performed.
This is not an error message. It is usually preceded by an
error message, indicating the reason for the failure.

Offset must be less than 0x0100
The user has made an attempt to modify data that is not
currently displayed. Restart the operation, selecting an
offset between 0x00 and 0xff.




10 Documentation for XE - a binary file editor





Out of memory!
Available memory is insufficient to perform a necessary
operation. The maximum amount of memory used by XE at any
time is only 192 Kilobytes. This error may occur when the
amount of available memory for program use is less than 192
Kilobytes, due to hardware configuration or use of
multitasking environments that load multiple programs into
memory concurrently. Install more memory, or unload other
programs.

Out of memory! Operation could not be completed.
Available memory is insufficient to perform a necessary
operation. The maximum amount of memory used by XE at any
time is only 192 Kilobytes. This error may occur when the
amount of available memory for program use is less than 192
Kilobytes, due to hardware configuration or use of
multitasking environments that load multiple programs into
memory concurrently. Install more memory, or unload other
programs.

Please wait . . .
Not an error message. This message appears when performing
data modification operations in large data files. The
message will disappear when the operation is complete.

Press any key to acknowledge.
XE has displayed an informational message, concerning the
current operation. Read the message and then press any key
to proceed.

Requested page is beyond end of input file.
An informational message that may appear whenever a page
selection command is used to move beyond the end of a file.


Selected operation is beyond implemented capabilities.
This message appears in the shareware version of XE when
attempting to perform a delete operation that would cross a
chapter boundary. Refer to the section titled "DELETING
DATA".

XE(bncopy): Write ERROR!
This is usually an indication of a hardware error (i.e.
disk full, or bad disk sector). The most frequent problem
is that disk space has been exhausted. Copy the data file
to a larger disk, or delete extra files from the current
disk and reexecute the operation.

XE(bncopy): Read ERROR!
This is usually an indication of a hardware error (i.e. a
bad disk sector). Recovery may be possible with use of one
of the many file and disk recovery programs that are
available (i.e. Norton Utilities).



11 Documentation for XE - a binary file editor






XE(bncopy): Out of Memory!
Available memory is insufficient to perform a necessary
file copy operation. The maximum amount of memory used by
XE at any time is only 192 Kilobytes. This error may occur
when the amount of available memory for program use is less
than 192 Kilobytes, due to hardware configuration or use of
multitasking environments that load multiple programs into
memory concurrently. Install more memory, or unload other
programs.

XE(bncopy): nnn bytes remaining in counter!
A data transfer operation has failed, leaving nnn bytes
unwritten to disk. This message is always accompanied by
another message indicating the reason for the failure.











COPYRIGHT:
(c) 1991,92 Rex Robards / 4826 Billy Drive / San Antonio, TX
78220



























12 Documentation for XE - a binary file editor





REGISTRATION
and
ORDER FORM

To receive the current version of XE with documentation,
the companion disk editor (DE) and utilities for ASCII/EBCDIC
data interchange; send your name, address, and $15 to

Carefree Creations
4826 Billy Drive
San Antonio, TX 78220

ask for the "EBCDIC Support Pack".

NAME: _____________________________

ADDRESS: __________________________

CITY: _______________________ STATE: ____ ZIP: __________

Please send me the "EBCDIC Support Pack". I am enclosing
payment of $15 (check or money order).


































13