.COMMENT	This document contains commented-out code to allow it to be
.;		used with various modified Runoff's. By default, it works with
.;		the DECUS library version (11-530, M02). (You may wish to
.;		enable the .DX statement at the very end to get an index.)
.;
.;	To use:
.;		Spalding Version S1.4, distributed by the DECUS RSX SIG,
.;		   1.	Delete the "S14" comment markers (see below).
.;		   2.	.INCLUDE #1	if you want a manual describing Telex
.;					Computer Products defaults
.;					(.HEX, 32 bytes wide), don't .INCLUDE #1
.;					if you want Sira defaults (.LDA, 16 bytes)
.;		   3.	.INCLUDE #2	if you want installation notes included
.;					in your manual.
.;		   4.	.INCLUDE #3	if you want a manual describing HEX
.;					running on VAX/VMS compatibility mode.
.;
.;		Please note: I (CJD, Sira) haven't actually tried using
.;		Spalding Runoff, so the above may not work.
.;
.;		VAX/VMS Digital Standard Runoff
.;		   1.	Delete the "DSR" comment markers.
.;		   2.	Adjust handling of (just one) footnote by deleting end
.;			line containing ! (now replaced by .EFN)
.;		   3.	Change all ^&...\& to ^*...\* if you want bold instead
.;			of underlined.
.;		   4.	On the command line, include the /VARIANT=TCP switch
.;			if you want a manual describing Telex Computer Products
.;			file  defaults (.HEX, 32 bytes wide). Do not include the
.;			'TCP' variant if you want Sira type defaults
.;			(.LDA, 16 bytes wide).
.;		   5.	Include the /VARIANT=INSTALL switch if you want the
.;			installation notes included in your manual.
.;		   6.	Include the /VARIANT=VMS switch if you want a manual
.;			describing HEX running on VAX/VMS compatibility mode.
.;
.;		If you have Real Time Systems' xse stream editor, the command
.;			 xse -ftodsr.tr -ohex.rnh hex.rnh;-1
.;		will do this for you (and change HEX's to HFE's).
.;
.;		Issue the following 4 Runoff commands to produce the contents
.;		and index files, followed by the complete document:
.;			$ RUNOFF/INTERMEDIATE/NOOUTPUT HEX
.;			$ RUNOFF/CONTENTS HEX
.;			$ RUNOFF/INDEX HEX
.;			$ RUNOFF[/VARIANT="VMS,INSTALL"] HEX
.;		These commands are in RUNOFF.COM.
.;
.;		For Bonner Runoff
.;		   1.	Delete the "DSR" and "BON" comment markers. (The main
.;			effect of the "BON"s is to put titles in double-width
.;			characters, by using ^=...\=, if your printer supports
.;			this.)
.;		   2.	Adjust handling of (just one) footnote by deleting end
.;			line beginning ! (now replaced by .EFN)
.;		   3.	Include .NO FLAGS UNDERLINE if you have a printer with
.;			underline features.
.;		   4.	Include .VARIANT TCP if you want a manual describing
.;			Telex Computer Products file  defaults (.HEX, 32 bytes
.;			wide). Do not include the 'TCP' variant if you want
.;			Sira type defaults (.LDA, 16 bytes wide).
.;		   5.	Include .VARIANT INSTALL if you want the
.;			installation notes included in your manual.
.;		   6.	Include .VARIANT VMS if you want a manual
.;			describing HEX running on VAX/VMS compatibility mode.
.;		   7.	Never set variant NEVER -- it's a bodge to prevent some
.;			errors messages arising from incompatibilities between
.;			Bonner Runoff and DSR.
.;
.;		If you have Real Time Systems' xse stream editor, the command
.;			 xse -ftobon.tr -ohex.rnh hex.rnh;-1
.;		will do this for you (and change HEX's to HFE's).
.;
.;		Issue the commands:
.;			$ RNO/TOC=HEX.RNT/OUTPUT=NL: PREFIX,HEX
.;			$ RNO PREFIX,HEX
.;		where PREFIX.RNO is a file (supplied on the kit) that you can
.;		edit to include the option lines described in items 3-6 above.
.;
.;
.;	Instructions to 'delete the "xxx" comment markers' mean that you should
.;	delete all occurrences of ".<semicolon>xxx", e.g. by an EDT command
.;	S/.<semicolon>xxx//WH, except that you put in a real semicolon instead
.;	of <semicolon>, which can't be shown here, as a semicolon terminates
.;	a comment in Digital Standard Runoff!
.;
.;	For the information of the curious: the SIR comment markers refer to a
.;	(sadly) obsolete Sira Runoff which had a .MAJOR INDEX facility to
.;	embolden the page number of the most important index reference. This
.;	facility doesn't appear in any of the above Runoffs.
.;
.;	If you have changed HEX's task name, do a global replace (paste) of
.;	all occurences of _HEX to _yyy,
.;	  e.g. S/_HEX/_HFE/WH in EDT if your new name is _HFE.
.;
.;BON.IF NEVER
.;DSR.flags bold
.;DSR.xlower
.;BON.ENDIF NEVER
.;DSR.layout 2,2
.;DSR.noautosubtitle
.;DSR.enable toc
.;DSR.no number
.;
.PS64,80.LM0.RM80
.;BON.NHY
#
.B3
.;BON^=
.C;^&HEX#FILE#EDITOR#(_HEX)\&
.;BON\=
.b2
.c;DECUS Library Program 11-480
.b12.nf.lm+25.i-10
Author:
Kevin Angley,
Telex Terminal Communications,
3301 Terminal Drive,
Raleigh, North Carolina 27604, USA
(919) 834-5251
.B2.I-10
Modified by:
Chris Doran,
Sira Ltd.,
South Hill, Chislehurst, Kent, BR7 5EH,
England
.i-10
and
Scott Smith,
Telex Computer Products, Inc.,
Raleigh, North Carolina 27604, USA
.b2.i-10
Version:
23Sep6
.COMMENT	Update version no in Texas example too (look for <CR>_:)
.LM-25.f
.;DSR.PAGE
.;BON.T HEX FILE EDITOR
.;BON.ST Contents
.;BON.fig 5
.;BON^=
.;BON.c;CONTENTS
.;BON\=
.;BON.s2
.;DSR.REQUIRE 'HEX.RNT'
.;BON.END TOC
.ch INTRODUCTION
.T HEX FILE EDITOR
.;DSR.NUMBER PAGE
.ST Introduction
The _HEX utility is a task that runs on the PDP-11 under the RSX11M operating
system (and VAX/VMS compatibility mode). Its purpose is to manipulate object
files output by various linkers or assemblers. Such object files (often coded
as hexadecimal numbers, and hence called "hex" files) are, in essence, "task
images" of software to run in microprocessor-based systems. Detailed
descriptions of acceptable formats are given in Appendix A.
.P0
The _HEX command contains the following data structures which are manipulated
by user commands:
.lm+18.ts18.p-18
Virtual#memory	This is the principal component of the _HEX utility. It is a
32K byte area which allows the user to manipulate code in memory as if it were
resident in the target machine.
.p
Offset	extends virtual memory to cover the entire 2_*_*32 (4Mbyte) address
range via the OFFSET command which modifies the start address of the simulated
area. (see Sections 2.5.25 and 2.9)
.p
Addressing#mode	_HEX will handle 16, 24, or 32-bit addressing modes. The mode is
16-bit by default, but can be changed by the OFFSET command.
.x Addressing mode
.x Mode
.p
Pseudo-registers	A bank of 256 (decimal) bytes is available as
user-definable workspace. (Section 2.8)
.p
File#format	This defines the assembler or emulator format for various
microprocessors (Section 2.5.15 and Appendix A)
.p
Transfer#address	The transfer (start) address of the user program
can be read, modified, and written out. (Section 2.5.34)
.p
Program#name	A 0-8 character program name can be read, modified, and written
by those formats that support it. (Section 2.5.22)
.p
LOW#register	This contains the lowest address used in the last READ or
COMPARE operation. (Section 2.4)
.p
HIGH#register	This contains the highest address from READ or COMPARE.
.lm-18
.ch OPERATING INSTRUCTIONS
.T HEX FILE EDITOR
.st Operating Instructions
.;BON^=
.HL1 HOW TO INVOKE _HEX
.;BON\=
.x Invoking _HEX
_HEX can be invoked in two ways:
.LIST 1
.LE;Interactive mode
.B1.LM+5.NF
.;DSR.IF VMS
.;S14.OPTION 3
$#_HEX###########Type _HEX in response to the CLI prompt.
.;DSR.ELSE VMS
.;S14.ELSE
_>_HEX###########Type _HEX in response to the CLI prompt.
.i-5
or###_>RUN#$_HEX######if _HEX is not installed.
.;DSR.ENDIF VMS
.;S14.END OPTION 3
_HEX_>command#####Command lines may be entered.
_HEX_>command#...
_HEX_>_^Z##########Control/Z terminates _HEX.
.X Terminating _HEX
.x Control/Z
.LM-5.F.LE;Indirect command mode
.B1.LM+21.i-16
.;DSR.IF VMS
.;S14.OPTION 3
$#_HEX#@filespec#where
.;DSR.ELSE VMS
.;S14.ELSE
_>_HEX#@filespec##where
.;DSR.ENDIF VMS
.;S14.END OPTION 3
filespec is the file specification of an indirect command
file (default type CMD) containing a list of _HEX commands.
.x Indirect command file
.x Command file
.lm-21.p0
Note that the invocation of _HEX may itself be contained in an indirect command
file, but filespec as shown above may contain only _HEX commands, i.e_. command
files cannot be nested. Processing of a command file terminates prematurely
if any _HEX command reports a serious error.
.ELS
Upon entering _HEX, virtual memory is FF-filled, the offset and transfer address
values are set to 0000, the program name is blank (8 spaces), the object file
format is set to Intel-style, 16-bit mode is selected, and LOW and HIGH
.x Addressing mode
.x Mode
addresses are set to all ones and zero respectively. The _HEX_> prompt is
printed, indicating that the task is ready to receive a command.
.p0
Typically, a _HEX session would proceed as follows:
.list 1
.TP5.le;If the PROM that the user is preparing for is FF-filled when blank, it is
not necessary to fill the virtual memory. Otherwise, it will be necessary to
.X FILL
FILL the virtual memory with the normally blank value (see the FILL command in
Section 2.5.14).
.TP5.le;If the address range of the object files that you intend to manipulate
lies within the range 0000-7FFF, it is not necessary to set an offset value.
Otherwise, an OFFSET should be specified (see the OFFSET command in Section
2.5.25 and notes on using it in Section 2.9).
.x OFFSET
.TP3.le;READ the object file(s) into the virtual memory (see the READ command
in Section 2.5.27).
.TP3.le;Optionally, you may manipulate or examine the contents of virtual memory.
.TP3.le;Finally, WRITE selected sections of virtual memory out to create new object
files.
.ELS
_HEX is exited by typing EXIT, or control/Z at the terminal. If built with
parent/offspring tasking support, and run on a system with this facility,
.x Parent/offspring tasking
.x Exit status
_HEX will return exit status as follows:
.;DSR.IF VMS
.;S14.OPTION 3
.lm+27.TS27.p-27
RSX$__SUCCES##=#%X10068644	if no problems are encountered,
.i
RSX$__WARNING#=#%X10068640	if a minor fault is found -- trailer missing or
unexpected or READ or COMPARE, or name or transfer address mismatch on COMPARE,
.x READ
.x COMPARE
.i
RSX$__ERROR##=#%X10068642	on any more serious error,
.i
RSX$__FATAL##=#%X10068644	if aborted by a CLI ABOrt command.
.lm-27
.;DSR.ELSE VMS
.;S14.ELSE
.lm+18.TS18.p-18
success#=#1	if no problems are encountered,
.i
warning#=#0	if a minor fault is found -- trailer missing or unexpected
or READ or COMPARE, or name or transfer address mismatch on COMPARE,
.x READ
.x COMPARE
.i
error###=#2	on any more serious error,
.i
severe#error#=#4	if aborted by a CLI ABOrt command.
.lm-18.p0
On a system without parent/offspring tasking, or when _HEX is built without it,
only exit status values 1 and 4 can be returned.
.;DSR.ENDIF VMS
.;S14.END OPTION 3
.;BON^=
.hl1 COMMAND DESCRIPTIONS
.;BON\=
.;
.COMMENT Much of this section is summarised in Appendix B, which should be
.;	 updated in parallel.
.;
Descriptions of valid _HEX commands follow. The following general notes apply:-
.list1
.TP5.le;aaaa, bbbb, and sequential uses of early letters of the alphabet indicate
a 4, 6, or 8-digit hex number, depending on the current mode (16, 24, or
32-bit,
.x Addressing mode
.x Mode
respectively). All digits (including leading zeros) must be specified.
.;SIR.MX aaaa
.X aaaa
.TP4.le;vvvv, wwww, xxxx, or similar indicate a hex number of exactly the
same number of digits as there are characters (e.g_. vv is a 2-digit byte,
xxxxxx is a 6-digit 24-bit address).
.;SIR.MX vvvv
.X vvvv
.;SIR.mx pp
.x pp
.TP6.le;pp indicates a byte value which may be entered either as a 2-digit hex
number, or a character specifier in one of the following forms (where
c indicates a printing character):-
.;SIR.mx Character specifier
.x Character specifier
.lm+5.ts20,25.b1.nf.tp7
_^c	control codes, 00-1F, shown as _^@, _^A, _^B, ...#_^__
.TP2
'c	printing characters, codes 20-7E, with parity bit clear --
		'space to '~. (Some control codes are also accepted.)
_^_#	the parity-clear delete character, code 7F
~c	control codes with parity bit set -- 80-9F, ~@ ...#~__
.TP2
-c	printing characters with parity bit set, --
		codes A0-FE, -#, -!, ...#-~
_#_#	the parity-set delete character, code FF
.lm-5.f.TP6.le;qqqq indicates a 16-bit value which may be entered either as a 4-digit
.;SIR.MX qqqq
.X qqqq
hex number, or a double-quote followed by two ASCII characters. Thus "ab
and 4142 have the same effect, since the hex codes for characters a and b
are 41 and 42 respectively. Only parity-clear, printing, characters may
be entered in this format.
.le;nnnnnnnn or mmmmmmmm indicates a 1-8 character program name.
.x Program name
.TP3.le;_*_*_*_* represents an entity which may either be an address, as aaaa, or
.x _*_*_*_*
a pseudo-register, written as %xx.
.x Pseudo-register
.le;Uppercase words are required keywords.
.X Keyword
.TP3.le;Structures in brackets ([...]) show optional parameters. The brackets are
^&not\& part of the syntax.
.le;Slashes (/) indicate alternative keywords or options.
.TP3.le;Unless stated otherwise all numbers in this manual and all input/output
of the _HEX utility are hexadecimal.
.ELS
For example:
.p5
FILL FROM aaaa THRU bbbb WITH pp
.p0
FILL is the command, FROM, THRU, and WITH are required keywords, aaaa and
bbbb are 4, 6, or 8-digit hex numbers depending on current addressing mode,
and pp is a 2-digit hex number or character specifier. Thus the following
are valid FILL commands:-
.LM+5.B1.NF.tp3
FILL FROM 0000 THRU 07FF WITH 55          (16-bit mode)
FILL FROM 0A0010 THRU 0A0110 WITH _^A      (24-bit mode)
FILL FROM FFEE0A00 THRU FFEE0FFF WITH 'x  (32-bit mode)
.lm-5.f
.;BON^=
.hl1 COMMAND SUMMARY
.;BON\=
.X Command summary
The following commands are available:
.b1.nf.lm+5.ts17
AND	logical AND constant with bytes in address range.
APPEND	write memory at end of an existing object file.
COMPARE	compare memory with an object file or another memory area.
COMPLEMENT	take one's complement of bytes in address range.
COPY	copy values from one area to another.
CRC	compute standard bisync cyclic redundancy check on range.
CSUM	store a SAL-type CSUM block containing sum of data bytes.
DECREMENT	subtract constant from bytes in address range.
DISPLAY	display portions of memory at terminal or printer.
DIVIDE	divide bytes in address range by constant.
ECHO	turns on command line display (cancels NOECHO).
EDIT	examine and optionally replace values in the file.
EXIT	exits _HEX and returns to the operating system (CLI), as ctrl/Z.
FILL	fill address range with a value.
FORMAT	specify or display current object file format.
HELP	request on-line help.
IDENT	display _HEX's version number (latest revision date).
INCREMENT	add constant to bytes in address range.
INIT	reset to initial conditions.
MOVE	move values from one area to another.
MULTIPLY	multiply bytes in address range by constant.
NAME	set or display current program name.
NEGATE	take two's complement (negative) of bytes in address range.
NOECHO	turns off command line display (cancels ECHO).
OFFSET	display or define address offset.
OR	logical inclusive OR constant with bytes in address range.
REMAINDER	set bytes in address range to remainder on division.
REVERSE	reverses byte order in place in a given range.
ROTATE	rotate bits of bytes in address range.
READ	read in an object file.
SEARCH	scan the file for a particular byte or word value.
SHIFT	arithmetic or logically shift bits of bytes in address range.
SUM	compute Data I/O programmer 16-bit byte-wise sum-check.
TRANSFER	manipulate the transfer address.
USE	specify which 8-bit section of an addressable unit to use.
WRITE	write memory to a new object file.
XOR	logical exclusive OR constant with bytes in address range.
_*	displayable comment (used in indirect command files).
_. or $	issue system (Command Line Interpreter) command.
?	request on-line help (equivalent to HELP).
ctrl/Z	exit.
.lm-5.f
.;BON^=
.HL1 RANGE SPECIFICATION
.;BON\=
Many of these commands take a memory range specification of the basic form:
.x Range specification
.b1.c;[ODD/EVEN] FROM aaaa THRU bbbb [STEP vv]
.b1
where aaaa and bbbb are the (inclusive) addresses for the operation. By default,
every byte in that range is included, but if a STEP ss option is given,
only every vv'th address, starting at aaaa and _<= bbbb, is used.
.x STEP specification
ODD or EVEN may be used to select only odd or even addresses respectively, and
.x ODD
.x EVEN
thus imply a STEP of 02. If given, they will force aaaa to be rounded up, if
necessary, to the next appropriate byte boundary.
.p0
The main purpose of the ODD and EVEN options is to enable the production of
PROM files for 16-bit processors (e.g_. LSI-11 or TI99xx series), which need
separate hi- and lo-byte 8-bit PROMs. STEP supports the more general case, e.g_.
32-bit processors would need four PROMs each written with a STEP of 04.
.p0
The main function of these options is thus for use with the WRITE command. For
completeness, however, they are supported in all commands which take a range
specification, although they may not be of much value in many cases. Note that
if used with a WRITE command, then the resulting
.x WRITE
object file can only be sensibly processed by another READ or COMPARE with
.x READ
.x COMPARE
the same STEP.
.p0
The keywords LOW and HIGH may be given as alternatives to aaaa and bbbb.
.x LOW
.x HIGH
They have as their values the lowest and highest addresses referenced in the
last READ or COMPARE operation. Initially, and after INIT, LOW is set to all
ones, and
.x INIT
HIGH to all zeros. Their values are not affected by any other command. The
following examples illustrate the use of LOW and HIGH:
.lm+5.b1.nf.tp4
READ FILE TEST
DISPLAY FROM LOW THRU HIGH FILE TEST1
SUM FROM 0000 THRU HIGH
CRC FROM LOW THRU 7FFF
.lm-5.f.p0
Note that there is a degenerate case where the use of LOW and HIGH would
result in "Address out of range". The LOW and HIGH endpoints will always be
valid under the current offset, but not necessarily all addresses in between.
For example, in 16-bit addressing and an offset of C000, it is possible to
have a LOW of 0000 and a HIGH of FFFF, but subsequent use of LOW or HIGH would
result in addresses not valid under the current offset.
.P0
The case discussed in the previous paragraph illustrates one of the problems in
using an offset at the top end of the address range so that a "wrap" occurs to
the low part of the address range. Because of such problems, setting the
offset in this manner is not advised. The next major revision of _HEX will
probably treat this case as an error.
.p0
LOW and HIGH are not updated when the offset is changed, and may thus go out
of range after an OFFSET command,
.x OFFSET
particularly one that changes the addressing mode (number of bits).
.x Addressing mode
.x Mode
.p0
A READ or COMPARE that terminates prematurely (e.g_. on a checksum error)
leaves LOW and HIGH undefined, but they are usually correct up to the point of
error.
.p0
COMPARE, READ, WRITE, and APPEND have three optional parameters which must
follow the range specification:
.lm+16.ts16.p-11,1,3
PLUS#dddd	specifies a hex value dddd which should be added to each
address (except the transfer address) read from or written to the file.
.x PLUS
.p-11,1,3
MINUS#dddd	specifies a hex value to be subtracted from each address
in the file.
.x MINUS
.p-11,1,3
PARTIAL	indicates that the file does not or should not contain a trailer
record.
.lm-16.p0
Thus the full formal syntax of a range specification is:
.p5
[ODD#]#FROM#aaaa#THRU#bbbb#[STEP#cc]#[PLUS##dddd]#[PARTIAL]
.i5
[EVEN]######LOW#######HIGH###########[MINUS#dddd]
.p0
In the following descriptions, this will be shown as simply
.p5
FROM aaaa THRU bbbb
.b1
with an indication if PLUS, MINUS, and PARTIAL keywords are allowed.
.;BON^=
.HL2 ADDRESSES ON 12-BIT PROCESSORS
.;BON\=
Special arrangements are made for storing and addressing data on the 12-bit
PDP-8 and IM6100 processors, when RIM and BIN formats are selected.
.x PDP-8 Read-In-Mode format
.x IM6100 Read-In-Mode format
.x RIM format
.x BIN format
These are 12-bit machines, which _HEX simulates by putting the high four bits of
each 12-bit word at even (lo) addresses, and the low 8 bits at following (odd)
addresses. Addresses in files refer to 12-bit words, so _HEX doubles each
address in a file on READ, and halves it on WRITE. _HEX must always be given
doubled address values, and doubled addresses are always printed. This is
something of a bodge, and maybe _HEX should have a special 12-bit mode for these
processors. Retaining byte separation does, however, facilitate handling of
8-bit PROMs.
.;BON^=
.TP12.hl1 DETAILED DESCRIPTIONS OF COMMANDS
.hl2 AND
.X AND
.I5
.;BON\=
AND FROM aaaa THRU bbbb WITH pp
.p0
Stores in each byte in the given range the logical AND of its original value
with the constant pp. For example:
.p5
AND FROM LOW THRU HIGH WITH 07
.i5
INCREMENT FROM LOW THRU HIGH BY '0
.b1
selects only the lo three bits each byte in the area just read in, and then
adds the ASCII code for 0 to each byte, converting the area to octal digits.
.;BON^=
.hl2 APPEND
.;SIR.MX APPEND
.X APPEND
.I5
.;BON\=
APPEND FROM aaaa THRU bbbb [WIDTH vv/vvvv] FILE filespec
.p0
This is basically the same as WRITE (which see for further details), but
instead of creating a new file, the memory area is written in the current
format to the end of an existing object file.
.p0
It is the user's responsibility to ensure that the old file is in the right
format. In particular, it should have been written without a trailer (PARTIAL
option),
.x PARTIAL
otherwise the appended data will be ignored by READ. APPEND does not write a
file header record, but will write a trailer unless the PARTIAL option is
given.
.p0
One use of the append command is to write a file from a program which is in
several areas with intervening rubbish. E.g_. if a program takes low memory
from 0000 to 01FF, and high memory from 4000 to 4FFF, then it could be output
by
.P5
WRITE FROM 0000 THRU 01FF PARTIAL FILE TEMP
.I5
APPEND FROM 4000 THRU 4FFF FILE TEMP
.p0
PLUS, MINUS, and PARTIAL options are allowed in APPEND range specifications.
.p0
It is not possible to APPEND to a WHITESMITHS or TASK format file, and any
.x Task format
.x Whitesmiths' format
attempt to do so will result in an error message. See Section A.1 for a
warning note on appending Intel format files in modes above 16 bits.
.;BON^=
.HL2 COMPARE
.i5
.;BON\=
COMPARE [FROM aaaa THRU bbbb] FILE filespec
.;SIR.MX COMPARE
.X COMPARE
.b
where filespec is a file specification (see Section 2.7) of an object file
in the currently selected format.
.p0
The code contained in the file will be compared with values at the same
locations in virtual memory. Unspecified locations are not checked. Differences
are reported to the terminal. The contents of virtual memory is not affected.
.p0
Optionally, limits may be placed on the portion of the input file to be used to
compare to virtual memory. If so specified, only code defining addresses from
aaaa to bbbb will be compared to virtual memory.
.p0
MOSTEK format files ^&must\& contain a header
.x Mostek format
record. PLUS and MINUS options are also allowed in the COMPARE range
specification.
.p0
For formats which have one, an error will be generated if there is no trailer
record unless the PARTIAL option is included, or if there is a trailer record
.x PARTIAL
but PARTIAL was included. The transfer address and program name from
appropriate records (if defined for the particular format type) are also
compared with the current values, and differences reported. These errors are not
considered serious enough to terminate indirect command file processing and
only set _HEX's exit status to warning, Data mismatches, however, will set
error status and abort command file processing.
.x Indirect command file
.x Command file
.x Exit status
.p0
An alternative form of the COMPARE command enables two areas of memory to
be compared:
.p5
COMPARE [FROM aaaa THRU bbbb] WITH cccc
.p0
In this form, the command compares the contents of the area of memory from
address aaaa to address bbbb with the contents of that beginning at address
cccc. PLUS, MINUS, and STEP options in the range specification applies to
accesses to the first area only -- the second area is always read as sequential
bytes beginning at cccc. If no range specification is given in this form of
COMPARE, that of the last command line that did have one is used instead.
.p0
In either form of the COMPARE command, control/O may be pressed alternately
.;SIR.mx control/O
.x Control/O
to suppress and enable output of differences to the screen, and control/C
.;SIR.mx control/C
.x Control/C
to abort the command, e.g_. when a large number of differences are being
reported. Use of control/C does ^&not\& abort command file processing.
.;BON^=
.HL2 COMPLEMENT
.I5
.;BON\=
COMPLEMENT FROM aaaa THRU bbbb
.X COMPLEMENT
.B
This command sets each byte in the given range to its logical (one's)
complement, i.e_. reverses the sense of each bit. This may be useful for
programming PROMs which are to be read through inverting buffers.
.;BON^=
.HL2 COPY
.i5
.;BON\=
COPY FROM aaaa THRU bbbb TO cccc [REPEAT vvvv]
.X COPY
.b
This command will copy the values contained in locations aaaa to bbbb to the
locations starting at cccc. The copy does not affect the source area unless it
is overlapped by the target area. The copy proceeds from aaaa to
bbbb. The ODD, EVEN or STEP option applies only to the source area; bytes
are always written contiguously to the output area at cccc. This
is particularly useful in setting up files to program 8-bit PROMs for a 16-bit
data bus. For example:
.p5
COPY EVEN FROM 4000 THRU 5FFF TO 0000
.b1
will copy:
.lm+15.nf
4000 to 0000
4002 to 0001
####...
5FFE to 0FFF
.lm-15.f.p0
If the REPEAT option is given, vvvv contiguous copies of the source area are
made.
.;BON^=
.HL2 CRC
.i5
.;BON\=
CRC FROM aaaa THRU bbbb [TO _*_*_*_*]
.;SIR.MX CRC
.X CRC
.b
Calculates the standard bisync CRC of every byte in the range, using
a preset of 0000. If a TO address is specified, the result is stored there in
high-low order. _*_*_*_* is either an address or a pseudo-register (see
Section 2.8). If the latter, the high byte of the CRC will be put into %xx,
and the lo byte into %xx+1.
.x Pseudo-register
Whether or not a TO address is specified, the CRC value is displayed on the
terminal.
.;BON^=
.HL2 CSUM
.i5
.;BON\=
CSUM FROM aaaa THRU bbbb
.X CSUM
.b
Calculates and displays on the terminal a 16-bit byte-wise summation of
locations in the given range (i.e_. as SUM), and then writes a 4-byte SAL
assembler-type CSUM block at bbbb+1, in the form:
.lm+15.b1.nf
bbbb+1 = aaaa lo######bbbb+2 = aaaa hi
bbbb+3 =  sum lo######bbbb+4 =  sum hi
.f.LM-15.p0
The CSUM block enables instruments to check for PROM integrity, e.g_. on
startup. This command is useful for creating PROM checksum blocks in files
produced by assemblers without this facility, or to write an updated CSUM block
into edited or copied data.
.;BON^=
.HL2 DECREMENT
.I5
.;BON\=
DECREMENT FROM aaaa THRU bbbb [BY pp]
.X DECREMENT
.B
This command subtracts pp (default 01) from each byte in the given range.
.;BON^=
.HL2 DISPLAY
.i5
.;BON\=
DISPLAY [ASCII] FROM aaaa THRU bbbb [FILE filespec]
.X DISPLAY
.b
where filespec is a file specification (see Section 2.7). The default type is
.;DSR.IF VMS
.;S14.OPTION 3
LIS.
.;DSR.ELSE VMS
.;S14.ELSE
LST.
.;DSR.ENDIF VMS
.;S14.END OPTION 3
.p0
The contents of aaaa to bbbb are displayed on the terminal (or, if given,
to a file).
.; which is then spooled to the printer).
Use LP_: as the filename to get a listing on the printer.
.p0
If the STEP size is (default) 01, the address aaaa is rounded down to aaa0, and
bbbb is rounded up to bbbF.
.p0
By default, data bytes are shown as two hex digits. However, the ASCII
option causes them to be shown as ASCII characters. Non-printing characters
are shown as the printing equivalent, using the character specifier
.X Character specifier
format shown in Section 2.2, except that the apostrophe before parity-clear
printing characters is omitted.
.p0
Control/O and control/C keys may be used as described in COMPARE to suppress
.x Control/O
.x Control/C
terminal output from the DISPLAY command, or abort it completely.
.;BON^=
.HL2 DIVIDE
.I5
.;BON\=
DIVIDE [SIGNED] FROM aaaa THRU bbbb BY pp
.X DIVIDE
.B
This command divides each byte in the given range by constant pp. Source and
constant bytes are treated as signed (2's complement) if the SIGNED option
is given. The default is unsigned. Division by zero sets all bytes in the
range to zero, without warning.
.;BON^=
.HL2 ECHO
.i5
.;BON\=
ECHO
.x ECHO
.x NOECHO
.x Command file
.x Indirect command file
.b
Turns on display of lines read from an indirect command file after it has been
disabled by NOECHO (see Section 2.5.24). The default is to echo all commands
read.
.;BON^=
.tp9.HL2 EDIT
.i5
.;BON\=
EDIT aaaa [STEP ww]
.X EDIT
.b
initiates an interactive session which allows you to examine and optionally
replace the contents of virtual memory starting at location aaaa. The following
will be displayed:
.p5
aaaa vv=cc-
.b1
where aaaa is the current address being edited, vv is its contents in hex, and
cc shows the ASCII or control character in the same way as DISPLAY. _HEX then
waits for a reply in one of the following forms (_<CR_> and _<esc_> denote pressing
the RETURN or ESCAPE keys respectively):-
.lm+15.ts15.p-10,1
pp_<CR_>	to replace the contents of the location being edited and open the
next ww'th location for editing.
.i
_<CR_>	to leave the location as it is and open the next ww'th location.
.i
pp_^_<CR_>	to replace the contents of the location being edited and open
^&previous\& ww'th location for editing.
.i
_^_<CR_>	to leave the location as it is and open the previous ww'th location.
.i
pp_<esc_>	to replace the contents of the open location and then return
to _HEX command mode.
.i
_<esc_>	to leave the location as is and return to _HEX command mode.
.lm-15.p0
.X Control/Z
Ctrl/Z has the same effect as escape.
.p0
pp may take the form of a two-digit hex byte value, or a character
specifier as shown in Section 2.2.
.x Character specifier
.;BON^=
.HL2 EXIT
.i5
.;BON\=
EXIT
.x EXIT
.x Indirect command file
.x Command file
.x Control/Z
.X Terminating _HEX
.b
Exits from _HEX, returning to the operating system (CLI) or calling program.
This command has the same effect as typing control/Z at the terminal, but may
be included in a command file, enabling _HEX to be run without user
intervention. Note, however, that if any command encounters an error, _HEX will
return immediately to interactive mode, and the EXIT command will never be
reached.
.;BON^=
.HL2 FILL
.i5
.;BON\=
FILL FROM aaaa THRU bbbb WITH pp
.;SIR.MX FILL
.X FILL
.b
Every location from aaaa to bbbb is set to byte value pp.
.;BON^=
.HL2 FORMAT
.i5
.;BON\=
FORMAT [type [char/SMS]]
.x FORMAT
.b
If type is omitted, the current file format is shown, otherwise, it
specifies the object file format and default filetypes for READ, COMPARE,
.x READ
.x COMPARE
.x WRITE
.x APPEND
WRITE, and APPEND commands (and default WIDTH for WRITE and APPEND), as:-
.lm+5.b1.nf.ts23,36,45
type	###WIDTH####filetype	notes
----	###-----####--------	-----
.;S14.OPTION 1
.;S14INTEL	##32/250	.HEX
.;S14MOTOROLA	##32/252	.HEX
.;S14ROCKWELL	##32/252	.HEX
.;S14RCA	##32/168	.HEX	COSMAC UT4 utility
.;S14TEKHEX	##32/250	.HEX	Tektronix emulators
.;S14EXTENDED [TEKHEX]	##32/250	.HEX	Ditto, "Extended TekHex"
.;S14TEXAS	##32/200	.OBJ	TI 7000, 9900, and 99000 families
.;S14MOSTEK	##32/250	.HEX	
.;S14WHITESMITHS	####1	none	linker XEQ. file format
.;S14RIM	##64/254	.RIM	PDP-8 and IM6100 Read-In-Mode
.;S14BIN	#128/254	.BIN	PDP-8 and IM6100 binary mode
.;S14HEX [char/SMS]	1024/16384	.PRM	Data I/O hex-char or SMS
.;S14OCTAL [char/SMS]	1024/16384	.PRM	Data I/O octal-char or SMS
.;S14TCI	##32/253	.HEX
.;S14FAIRCHILD	##32/254	.HEX	"Fairbug" format
.;S14.ELSE
.;DSR.IF TSC
.;DSRINTEL	##32/250	.HEX
.;DSRMOTOROLA	##32/252	.HEX
.;DSRROCKWELL	##32/252	.HEX
.;DSRRCA	##32/168	.HEX	COSMAC UT4 utility
.;DSRTEKHEX	##32/250	.HEX	Tektronix emulators
.;DSREXTENDED [TEKHEX]	##32/250	.HEX	Ditto, "Extended TekHex"
.;DSRTEXAS	##32/200	.OBJ	TI 7000, 9900, and 99000 families
.;DSRMOSTEK	##32/250	.HEX	
.;DSRWHITESMITHS	####1	none	linker XEQ. file format
.;DSRRIM	##64/254	.RIM	PDP-8 and IM6100 Read-In-Mode
.;DSRBIN	#128/254	.BIN	PDP-8 and IM6100 binary mode
.;DSRHEX [char/SMS]	1024/16384	.PRM	Data I/O hex-char or SMS
.;DSROCTAL [char/SMS]	1024/16384	.PRM	Data I/O octal-char or SMS
.;DSRTCI	##32/253	.HEX
.;DSRFAIRCHILD	##32/254	.HEX	"Fairbug" format
.;DSR.ELSE TSC
INTEL	##16/250	.LDA
MOTOROLA	##16/252	.LDA
ROCKWELL	##16/252	.LDA
RCA	##16/168	.LDA	COSMAC UT4 utility
TEKHEX	##16/250	.LDA	Tektronix emulators
EXTENDED [TEKHEX]	##16/250	.LDA	Ditto, "Extended TekHex"
TEXAS	##16/200	.LDA	TI 7000, 9900, and 99000 families
MOSTEK	##16/250	.LDA	
WHITESMITHS	####1	none	linker XEQ. file format
RIM	##64/254	.RIM	PDP-8 and IM6100 Read-In-Mode
BIN	#128/254	.BIN	PDP-8 and IM6100 binary mode
HEX [char/SMS]	1024/16384	.PRM	Data I/O hex-char or SMS
OCTAL [char/SMS]	1024/16384	.PRM	Data I/O octal-char or SMS
TCI	##16/253	.LDA
FAIRCHILD	##16/254	.LDA	"Fairbug" format
.;S14.END OPTION 1
.;DSR.ENDIF TSC
SIRA	##64/505	.LDA	Sira binary
OBJECT	##64/510	.OBJ	MACRO ABS object
ABSOLUTE	##64/505	.LDA	PDP-11 paper tape absolute loader
TASK	###512	.SYS	TKB output
.lm-5.f.p0
See Section 2.4.1 for an important note regarding address specifications in RIM
and BIN formats.
.p0
WIDTH values are in decimal. Where two values are shown, the first is the
default and the second the maximum that will fit into _HEX's I/O buffer.
.p0
For Data I/O programmer formats, HEX and OCTAL, type may be followed by
.x HEX format
.x OCTAL format
.x PROM programmer format
either the keyword SMS, or a single character which is to separate data items.
Any character may be given, although the programmer only recognises the
apostrophe ('), percent (%), comma (,), and space. (SMS format only allows
apostrophe, and therefore does not permit a char specification.) If no
separator is specified, a default of space will be used. The following are all
valid commands to select HEX or OCTAL formats:
.lm+5.nf.b1
FORMAT HEX
FORMAT HEX %
FORMAT OCTAL SMS
.F.LM-5.p0
Appendix A gives full details of the various file formats.
.p0
EXTENDED TEKHEX may be abbreviated to EXTENDED.
.;BON^=
.tp14.HL2 HELP
.i5
.;BON\=
HELP [command]
.br
or###?#[command]
.b
.;SIR.MX HELP
.X HELP
.X ?
Displays instructions for using the named _HEX command (if given). If no command
is named, a summary table showing syntaxes of all commands is given.
.;DSR.IFNOT VMS
.;S14.OPTION 3
.;S14.ELSE
_*
.fn
.b1
----------
.br
_* _HEX spawns the system HELP utility to display the help information. If the
host RSX-11M system does not support parent-offspring tasking, or if _HEX was
.x Parent/offspring tasking
built without it, this cannot be done, and _HEX's HELP command only displays a
command syntax summary, even if help on an explicit topic is requested. Use the
_. or $ command to suspend _HEX, and type HELP#_HEX#command in this case.
.;DSR.EFN	.; Delete following line for DSR:
!
.;DSR.ENDIF VMS
.;S14.END OPTION 3
.;BON^=
.HL2 IDENT
.I5
.;BON\=
IDENT
.X IDENT
.B
displays the program identification for this version of _HEX, as:
.p5
:#_HEX version ddmmmy
.b1
where ddmmmy is the last revision date, day (dd), month (mmm), and year
since 1980 (y).
.;BON^=
.HL2 INCREMENT
.I5
.;BON\=
INCREMENT FROM aaaa THRU bbbb [BY pp]
.X INCREMENT
.B
This command adds pp (default 1) to each byte in the given range.
.;BON^=
.HL2 INIT
.i5
.;BON\=
INIT [WITH pp]
.b
.X INIT
This command resets the _HEX utility to its initial conditions. Virtual memory
is filled with value pp (default FF), offset and transfer address values are
set to 0000, the program name is set to null (8 blanks), and the LOW and HIGH
.x LOW
.x HIGH
range values to all ones and all zeros respectively.
.p0
Addressing mode, format, and pseudo-registers are unaffected by INIT.
.x Addressing mode
.x Mode
.;BON^=
.HL2 MOVE
.i5
.;BON\=
MOVE BYTE FROM _*_*_*_* TO _*_*_*_*
.br
or###MOVE WORD FROM _*_*_*_* TO _*_*_*_*
.b
.;SIR.MX MOVE
.X MOVE
where _*_*_*_*'s represent either a hex number valid under the current
offset, or a pseudo-register specification (see Section 2.8).
.x Pseudo-register
.p0
The MOVE command is a variation of the COPY command. It is limited to a one
byte or one word transfer, but can access the pseudo-register set. Like COPY,
MOVE has no affect on the source area. A word moves copies the entire word at
one time, rather than bytewise as in COPY.
.;BON^=
.HL2 MULTIPLY
.I5
.;BON\=
MULTIPLY FROM aaaa THRU bbbb BY pp
.X MULTIPLY
.B
This command multiplies each byte in the given range by constant pp. Any high
order part of the result is lost, so there is no difference between signed and
unsigned multiplication, and hence no need for a SIGNED option (which is not
allowed).
.;BON^=
.HL2 NAME
.i5
.;BON\=
NAME [nnnnnnnn]
.;SIR.MX NAME
.X NAME
.;SIR.mx Program name
.x Program name
.b
If nnnnnnnn is omitted, the current program name (if any) is displayed.
.p0
If nnnnnnnn is given, this becomes the new 1-8 character program name. Any
ASCII characters except space and tab, may be used in the name. Trailing blanks
are appended if less than eight are given, and any excess characters are
ignored. Not all object file formats cater for a program name, and those that
do may not accept all ASCII characters, or may not allow all eight, but _HEX
does not check the validity of the name entered.
.;BON^=
.HL2 NEGATE
.I5
.;BON\=
NEGATE FROM aaaa THRU bbbb
.X NEGATE
.B
This command sets each byte in the given range to its arithmetic (two's)
complement, i.e_. reverses its sign.
.;BON^=
.HL2 NOECHO
.i5
.;BON\=
NOECHO
.x ECHO
.x NOECHO
.x Indirect command file
.x Command file
.b
Turns off display of lines being read from an indirect command file, including
displayable comments, and also statistics reports from READ and WRITE commands.
.x Comment
.x Displayable comment
Other messages, such as errors, terminal DISPLAY listings, SEARCH and COMPARE
matches or mismatches and EDIT prompts, still appear, however. The NOECHO
command does not affect commands typed directly at the terminal; these are
always echoed. Echoing is re-enabled by the ECHO command (see Section 2.5.11).
.p0
Placing this command (which is never itself displayed) at the beginning of a
command file enables _HEX command files to be executed without filling the
screen with unwanted information. Thus a standard Whitesmiths' to Intel hex
conversion could be carried out without concerning the user with _HEX internals
by invoking it with an indirect command file containing:
.lm+5.b1.nf
NOECHO
FORMAT WHITESMITHS
READ FILE XEQ.
FORMAT INTEL
WRITE FROM LOW THRU HIGH FILE INTEL
EXIT
.F.lm-5.p0
Unfortunately, there is no way to specify the file names in the _HEX command
line, so such a command file might have to be created by the indirect command
processor, which would then invoke _HEX.
.;BON^=
.HL2 OFFSET
.i5
.;BON\=
OFFSET [aaaa]
.;SIR.MX OFFSET
.X OFFSET
.b
The offset command with no argument displays the current offset value.
.b1
If a value is specified, that value becomes the new offset.
.b1
See notes on the use of the offset in Section 2.9.
.;BON^=
.HL2 OR
.I5
.;BON\=
OR FROM aaaa THRU bbbb WITH pp
.X OR
.B
This command sets each byte in the given range to its logical inclusive OR
with the given constant.
.;BON^=
.HL2 READ
.i5
.;BON\=
READ [FROM aaaa THRU bbbb] FILE filespec
.;SIR.MX READ
.X READ
.X FILE
.b
where filespec is a file specification (see Section 2.7) of an object
file in the current format.
.p0
The code defined by the file will be placed in its proper location in virtual
memory. Unspecified locations are not affected.
.p0	
Optionally, limits may be placed on the portion of the input file to be used to
define virtual memory. If so specified, only code defining addresses from aaaa
to bbbb will be placed in virtual memory.
.p0
A STEP#vv option may be used to cause data to be placed at every vv'th location,
when the file was written in this way (presumably with a compatible WRITE).
Intermediate locations are not affected.
.p0
The transfer address and program name from the appropriate records (if
.x Program name
.x Transfer address
supported by the current file format) replace the current values, and values
for LOW and HIGH
.x LOW
.x HIGH
keywords are updated (set to all ones and all zeros respectively if no data
is read in).
.p0
If PLUS or MINUS options are given, the specified value will be added to
.x PLUS
.x MINUS
the address at which data is stored (but not the transfer address) thus enabling
it to be read and copied to an alternative area in one operation.
.p0
For formats which have one, an error will be generated if there is no trailer
record unless the PARTIAL option is included, or if there is a trailer record
.x PARTIAL
but PARTIAL was included. Such errors are not considered serious enough to
terminate indirect command file processing and only set _HEX's exit status to
warning.
.x Indirect command file
.x Command file
.x Exit status
.;BON^=
.HL2 REVERSE
.I5
.;BON\=
REVERSE [ODD/EVEN] FROM aaaa THRU bbbb [STEP ss]
.x REVERSE
.b
reverses in place the values contained in every ss'th location from aaaa to
bbbb i.e_. aaaa is exchanged with bbbb, aaaa+ss with bbbb+ss etc.. bbbb is
rounded down, if necessary, so that bbbb-aaaa is an exact multiple of ss.
If ss is not 1, intervening locations in the range are unaffected.
.p0
This command is useful when setting up data for memory which is addressed
through inverting buffers. If, for example, we have to blow a 2k PROM for
such a system, then the byte at 0000 will have to be placed at 07FF, that at
0001 at 07FE etc.. Note that for a program taking several PROMs, the contents
of each must be reversed separately, e.g.:
.lm+5.nf.b1.tp3
REVERSE FROM 0000 THRU 07FF
REVERSE FROM 0800 THRU 0FFF
WRITE FROM 0000 THRU 0FFF WIDTH 0800 FILE PROMS
.lm-5.f
.;BON^=
.HL2 REMAINDER
.I5
.;BON\=
REMAINDER [SIGNED] FROM aaaa THRU bbbb BY pp
.X REMAINDER
.B
This command sets each byte in the given range to the remainder on dividing by
constant pp (sometimes called the "modulus"). Source and constant bytes are
treated as signed (2's complement) if the SIGNED option is given, otherwise
the default is unsigned. If pp is zero, all bytes in the range are left
unchanged.
.;BON^=
.HL2 ROTATE
.I5
.;BON\=
ROTATE LEFT/RIGHT FROM aaaa THRU bbbb [BY pp]
.X ROTATE
.B
This command internally rotates each byte in the given range by pp bits
(default 01). One of the keywords LEFT or RIGHT
.x LEFT
.x RIGHT
^&must\& be given to indicate the direction of rotation. For right rotates, bit
0 is copied to bit 7 at each step, and for left rotates, bit 7 goes to bit 0.
pp is taken as a full 8-bit unsigned number, although values above 7 are redundant.
.;BON^=
.HL2 SEARCH
.;BON\=
.i5
SEARCH FROM aaaa THRU bbbb FOR [NOT] pp
.br
or###SEARCH FROM aaaa THRU bbbb FOR [NOT] qqqq
.X SEARCH
.b
searches the specified range of virtual memory for the byte or word value given
(or not given if the NOT option is set). The addresses containing the value are
displayed, together with the total number of matches found. In the case of a
word value, the search is for a pair of adjacent bytes (even if the STEP is not
01) containing that value in lo-hi order. pp is a 2-digit hexadecimal byte or
character specifier (see Section 2.2). qqqq may be a 4-digit hexadecimal
number, or a double-quote followed by two ASCII characters (only parity-cleared
printing ones are allowed).
.p0
Control/O and control/C keys may be used as described in COMPARE to suppress
.x Control/O
.x Control/C
output from the SEARCH command, or abort it completely.
.;BON^=
.HL2 SHIFT
.I5
.;BON\=
SHIFT LEFT/RIGHT [SIGNED] FROM aaaa THRU bbbb [BY pp]
.;SIR.MX SHIFT
.X SHIFT
.B
This command shifts each byte in the given range by pp bits (default 01).
One of the keywords LEFT or RIGHT
.x LEFT
.x RIGHT
^&must\& be given to indicate the direction of shift. For left shifts, bit a 0
is shifted into bit 0, and bit 7 is lost at each step. For right shifts, bit 7
is cleared unless the SIGNED option is selected, when it is replicated. pp is
taken as a full 8-bit unsigned number, although values above 7 simply cause all
bytes to be set to a constant 00 or FF.
.;BON^=
.HL2 SUM
.i5
.;BON\=
SUM FROM aaaa THRU bbbb [TO _*_*_*_*]
.;SIR.MX SUM
.X SUM
.b
Calculates and displays on the terminal a 16-bit byte-wise summation of
every byte in the range.
.p0
If a TO address is specified, the result is stored there in low-high order.
Whether or not a TO address is given, the sum value is displayed on the
terminal.
.p0
If %xx is specified as a pseudo-register, the low byte of SUM will be put into
%xx, and the high byte will be put into %xx+1.
.;BON^=
.HL2 TRANSFER
.i5
.;BON\=
TRANSFER [aaaa]
.;SIR.MX TRANSFER
.X TRANSFER
.x Transfer address
.b
The transfer command with no argument displays the current transfer address.
.p0
If a value is specified, that becomes the new transfer address.
.;BON^=
.HL2 USE
.I5
.;BON\=
USE vv OF ww FOR READ
.;SIR.MX USE
.X USE
.X READ
.p0
This command sets up _HEX to handle files in which the basic addressable unit is
wider than eight bits. The command instructs READ and COMPARE to input only one 8-bit
section of the addressable unit at each location. Thus the USE command allows
these files to be split into partitions suitable for loading into 8-bit PROMs.
.p0
ww represents the number of 8-bit groups that make up each addressable unit (the
width of the addressable unit must be a multiple of eight bits). ww specifies
which of the bb bit groups is to be input as the value of a location.
.p0
Note that USE only operates properly with file formats that consist of a single
start address followed by an uninterrupted stream contiguous data bytes. If new
addresses intervene (e.g_. at the start of each record in Intel format) then
they automatically readjust the start of the storage area, resulting in gaps.
Thus USE only works sensibly with FAIRCHILD, RCA, WHITESMITHS, and TASK
.x RCA format
.x Task format
.x Whitesmiths' format
.X COMPARE
formats, and COMPARE#...#WITH. Other formats should be handled using the ODD,
EVEN, or STEP options in the range specification.
.;BON^=
.HL2 WRITE
.i5
.;BON\=
WRITE FROM aaaa THRU bbbb [WIDTH vv/vvvv] FILE filespec
.;SIR.MX WRITE
.X WRITE
.X FILE
.b
creates an object file in the current format defining locations aaaa to bbbb.
.p0
For PROM programmer formats (HEX and OCTAL) vvvv is a 4-digit PROM size. The
STEP range argument may be used to generate hi and lo byte PROM files.
.p0
The WIDTH option has no meaning for TASK and WHITESMITHS formats, and is
.x Task format
.x Whitesmiths' format
ignored if present.
.p0
For HEX and OCTAL PROM formats, vvvv is the PROM size.
.x HEX format
.x OCTAL format
.x PROM programmer format
.p0
For all other formats, vv, if given, determines the maximum number of bytes
output per line, by causing a new record to be started at addresses which are
exact multiples of vv, e.g_. if vv=10, and aaaa is 1234, records start at
addresses 1234, 1240, 1250 ..., and the maximum length is thus 16_. bytes.
.p0
Certain formats which write data as byte pairs (Texas, RIM, and BIN) require
.x Texas format
.x RIM format
.x BIN format
WIDTH to be even. If an odd value is given, they will use the next even one
instead, without warning.
.p0
The current program name will be included in the object file if the format
provides for this. The transfer address will be included if the format allows,
unless the PARTIAL option is given to suppress it.
.p0
PLUS or MINUS options may be used to add or subtract a constant value from
load addresses (but not the transfer address) written into the file.
.p0
Appendix A gives full descriptions of object file formats. Note that not all
formats support 24 or 32-bit addressing. Where this is the case, only the low
16 bits of addresses will be written. To reload such files correctly,
a PLUS option must be used with the subsequent READ or COMPARE.
.;BON^=
.HL2 XOR
.I5
.;BON\=
XOR FROM aaaa THRU bbbb WITH pp
.;SIR.MX XOR
.X XOR
.B
This command sets each byte in the given range to its logical exclusive OR
with pp, i.e_. every bit in each source byte which differs from the equivalent
bit in pp is set; every bit which is the same as in pp is cleared.
.;BON^=
.HL2 _.#or $ (CLI command)
.;BON\=
.i5
_.#[command]
.i5
$ [command]
.;SIR.MX _. command
.X _. command
.X $ command
.x CLI command
.b
If a command argument is given, the rest of the line after the fullstop is
sent to the current Command Line Interpreter (usually DCL or MCR). Control
returns to _HEX after the command is executed.
.x Command Line Interpreter
.p0
If there is no command argument, _HEX stops or pauses (according to the
commands available on the host system),
.x Stop/pause directive
releasing control of the terminal, and allowing any series of commands to
be sent to the CLI. Before doing so, _HEX shows the command required to
restart it. If you decide you do not need to continue, use the system ABORT
command to terminate it.
.p0
The _. or $ command, in any form, enables a system command (e.g_. an assembly)
to be issued without losing the contents of _HEX's buffer and any edits made.
.P0
The first form of the command is only available on a system which supports
parent/offspring
.x Parent/offspring tasking
tasking, and with a version of _HEX which has been built to include this
system facility (see Appendix C). On other configurations, _HEX rejects anything
else on the CLI line, and simply stops or pauses to go into user interactive
mode.
.;DSR.IF VMS
.;S14.OPTION 3
.p0
If _HEX is running in compatibility mode on a VAX/VMS
.x VAX/VMS
system, then ^&only\& the first form of the command is available. _HEX under
VMS does not release control of the issuing terminal; therefore any command
which requires an interactive exchange (such as editing) will fail.
.;DSR.ENDIF VMS
.;S14.END OPTION 3
.;BON^=
.HL1 COMMAND LINE PROCESSING
.;BON\=
.X Command line
A command line consists of up to 80 (decimal) ASCII characters terminated by an
ENTER or ESC. The command line may originate from the terminal or an indirect
command file. A command line which begins with a semicolon (;) or asterisk (_*)
is treated as a comment. When commands are read from a file, comments beginning
with asterisks are displayed at the terminal, whilst those beginning with
.x Displayable comment
.x Comment
.x Semicolon
.x Asterisk
semicolons are not.
.p0
Unless it is a CLI (.) command line, all spaces and tabs are removed from the
line, all lower-case letters converted to upper-case (except for the single
character after quote ('), minus (-) or tilde (~) or double-character after
double-quote (")). This pre-processing may result in seemingly incorrect error
messages. Consider the following command line:
.p5
WRITE FROM 0000 THRU 0FF FILE TEST.LDA
.x WRITE
.b1
Since addresses must be specified with a fixed number of digits, this command
is processed as if it were:
.p5,1,4
WRITE FROM 0000 THRU 0FFF ILE TEST.LDA
.b1
Therefore, the error message would pertain to the missing keyword FILE.
.;BON^=
.HL1 FILE SPECIFICATION
.;BON\=
.;SIR.MX File specification
.X File specification
A file specification takes the standard RSX-11M form:
.b1.LM+5
ddcn:[dir]name.ext;v
.b1.nf.ts13.i-5
where
ddcn:	is a device name, default SY0:,
dir	is a directory name, defaulting to the current directory,
name	is the name of the file, no default,
ext	is the file type, default determined by the current format,
_;v	is the version number, default latest (;0).
.lm-5.f.p0
TI_: is a file specification representing the terminal at which _HEX is running.
.;BON^=
.HL1 PSEUDO-REGISTERS
.;BON\=
.;SIR.MX Pseudo-register
.X Pseudo-register
Certain commands support specification of a pseudo-register. There are 256
(decimal) 8-bit registers. These may be used as temporary storage for moving
bytes or words around in memory. Any two consecutive registers can be addressed
as a 16-bit register in the context of certain commands. They are represented
by the symbol '%' followed by a two digit hex number, %00 to %FF.
.p0
There is no requirement that an even register be specified for use as a word.
If used as a word, %xx contains the low byte and %xx+1 (modulus 100H) contains
the high byte.
.p0
Pseudo-registers are not initialised, are not affected by INIT, and have no
relation to the OFFSET structure.
.;BON^=
.HL1 OFFSET
.;BON\=
.;SIR.MX OFFSET
.X OFFSET
Internally, _HEX uses a 32K byte buffer as virtual memory. However, the utility
can handle the entire 2_*_*32 addressing range by using an offset facility. The
user is responsible for setting the appropriate offset with the OFFSET command.
This offset is automatically ^&subtracted\& from all addresses input to _HEX
(either from the hex input file or command entry) and correspondingly ^&added\&
to output (either hex output file or display).
.p0
The offset should be chosen so that the addresses to be handled will be offset
internally to within 0000 to 7FFF.
.p0
For example, if the user wishes to manipulate an object file defining addresses
9000 to BFFF, an offset of 8000 would be appropriate.
.p0
After the offset is given, the offsetting of addresses internally is totally
transparent to the user, i.e_. the user specifies (and sees) actual addresses.
Changing the offset does not affect the contents of virtual memory. Thus if
memory is filled from 0000 with the default offset of 0000, which is then
changed to 8000 (say), locations 8000 up will contain the values originally
put into 0000.
.p0
Consider the following situation: You have a machine with RAM sockets and
addressing provisions for 2_*_*32 bytes of RAM. But, alas, you only have 32K
worth of RAM chips. Assuming the chips must be placed contiguously, at what
address would you begin placing the RAM chips in order to handle the addresses
defined by your file? This address would be the appropriate offset value for
the _HEX utility. Note again, that once you have "placed the RAM chips" (by
specifying an offset), you are dealing with the actual addresses.
.p0
The OFFSET command also sets addressing mode
.;SIR.mx Addressing mode
.x Addressing mode
.;SIR.mx Mode
.x Mode
to 16, 24, or 32 bits, depending on the number of hex digits given in the
value (see OFFSET command). Subsequent addresses used in the _HEX commands must
have the same number of digits as the last offset specified.
.p0
OFFSET does ^&not\& affect LOW or HIGH registers or the transfer address.
.x LOW
.x HIGH
.x Transfer address
.;BON^=
.HL1 EXAMPLES
.;BON\=
.X Examples
As a first, simple, example, consider the need to split up file BIG.LDA, which
contains PROM code in address range 1000 to 3E65, and RAM code from 9000 up,
into separate blocks for programming 4k-byte PROMs. First, the source file is
READ in, using the THRU option to skip any RAM setup commands which would
otherwise give a read error, being in the high 32k memory area:
.lm+5.b1.nf
READ FROM 1000 THRU 5000 FILE BIG
.X WRITE
.P-5
Three WRITE commands then output the data into separate files:
.b1
WRITE FROM 1000 THRU 1FFF FILE LITTLE1
WRITE FROM 2000 THRU 2FFF FILE LITTLE2
WRITE FROM 3000 THRU 3E65 FILE LITTLE3
.p-5
These can be verified by compare operations as:
.b1
COMPARE FILE LITTLE1
COMPARE FILE LITTLE2
COMPARE FILE LITTLE3
.X COMPARE
.LM-5.F.P0,2
The second example is intentionally complicated to demonstrate the usefulness
of the indirect command file input approach. Once the commands are determined,
they can be entered in an indirect command file and used again and again.
.p0,1
Consider the following problem: You have an assembly which produces an object file
called COM.LDA that defines addresses between 0000-0FFF and from B800-BFFF. You
also have an assembly which produces a file called MTI.LDA that defines
addresses between 0000-0FFF and from B800-BFFF. You desire the following:
.list 1
.le;Files called C0000.LDA and C0800.LDA which define 0000-07FF and
0800-0FFF, respectively, using the code from COM.LDA.
.le;Files M0000.LDA and M0800.LDA which define 0000-07FF and 0800-0FFF,
respectively, using the code from MTI.LDA.
.le;A file CPROM.LDA made up as follows:
.lm+17.p-12
B800-B8FF###as defined by MTI.LDA,
.i
B900-B9FF###as defined by COM.LDA,
.i
BA00-BFF5###as defined by MTI.LDA,
.i
BFF6-BFFD###containing the CRC's in high-low for C0000.LDA, C0800.LDA,
M0000.LDA, and M0800.LDA (in that order),
.i-16
and#BFFE-BFFF###containing a value such that the CRC of the entire CPROM.LDA
will be 0000.
.LM-17
.LE;Finally, a nicely formatted display of CPROM's contents to be spooled to
the printer.
.ELS
The following commands will do the job:
.B1.LM+5.NF
READ FROM 0000 THRU 1FFF FILE COM.LDA
WRITE FROM 0000 THRU 07FF FILE C0000.LDA
WRITE FROM 0800 THRU 0FFF FILE C0800.LDA
CRC FROM 0000 THRU 07FF TO %00
CRC FROM 0800 THRU 0FFF TO %02
INIT
READ FROM 0000 THRU 1FFF FILE MTI.LDA
WRITE FROM 0000 THRU 07FF FILE M0000.LDA
WRITE FROM 0800 THRU 0FFF FILE M0800.LDA
CRC FROM 0000 THRU 07FF TO %04
CRC FROM 0800 THRU 0FFF TO %06
INIT
OFFSET 8000
READ FROM B800 THRU BFFF FILE MTI.LDA
READ FROM B900 THRU B9FF FILE COM.LDA
MOVE WORD FROM %00 TO BFF6
MOVE WORD FROM %02 TO BFF8
MOVE WORD FROM %04 TO BFFA
MOVE WORD FROM %06 TO BFFC
CRC FROM B800 THRU BFFD TO BFFE
WRITE FROM B800 THRU BFFF FILE CPROM.LDA
DISPLAY FROM B800 THRU BFFF FILE CPROM.LST
.LM-5.F.P0
The commands are self-documenting.
.P0
Again, this example is certainly not typical, but was chosen to show that a
complicated manipulation can be completely performed using _HEX.
.p0,2
As a final example, the following instructions read in file TASK.SYS produced
by the RSX-11M task-builder for a 16-bit LSI-11, and write two separate
hex-space Data#I/O PROM programmer files, HITASK.PRM and LOTASK.PRM, to put the
hi and lo bytes into 4k-byte PROMs:-
.lm+5.nf.B
FORMAT TASK
READ FILE TASK
FORMAT HEX
WRITE FROM 0000 THRU 7FFE STEP 02 WIDTH 1000 FILE LOTASK
WRITE ODD FROM 0001 THRU 7FFF WIDTH 1000 FILE HITASK
.LM-5.F.p0,1
The first line could have used EVEN instead of STEP#02 and, conversely,
the second could just have well have used STEP#02 instead of ODD.
.CH MESSAGES
.T HEX FILE EDITOR
.st Messages
Note: References in this chapter to READ usually apply also to COMPARE, and
references to WRITE may include APPEND and DISPLAY.
.p0
When an error is encountered in a READ operation, the message is followed by
a display of the offending record (unless reading a binary file), and the READ
is terminated without a statistics report.
.tp7.lm+5.p-5,2,7
Aborted by ctrl/C
.br
.x Control/C
This is an informational message displayed when a COMPARE, DISPLAY, or SEARCH
.x COMPARE
.X DISPLAY
.X SEARCH
command is aborted prematurely by pressing the terminal control/C key.
No statistics report appears when COMPARE or SEARCH are so terminated.
.p-5,1,6
Address:#aaaa###Memory:#bb=pp#####File:#cc=pp
.br
.X COMPARE
This is an informational message displayed by the COMPARE operation when a
mismatch is detected between the file and the current contents of virtual
memory. COMPARE continues until completion. The differing bytes are displayed
in hexadecimal and ASCII.
.p-5,1,4
Address:#aaaa###Memory:#bb=pp#####Address:#cccc###Memory:#dd=pp
.br
.X COMPARE
This is the equivalent message to the above when a mismatch is found on a
memory-to-memory comparison (the COMPARE#...#WITH variant).
.p-5,1,5
Address out of range
.br
The specified address in a command line or an input object file cannot be
handled under the current offset, or, the FROM address specified is greater
than the THRU address.
.p-5,1,5
Bit group out of range
.x USE
.br
The USE command only accepts bit group values between 01 and FF, inclusive.
The value representing the bit group to use must be less than or equal to
the value representing the number of bit groups at each location.
.p-5,1,7
Can't append in current format
.br
An attempt has been made to APPEND in TASK or WHITESMITHS format. It is not
.x Task format
.x Whitesmiths' format
practicable to append to such files, because they require contiguous data areas
defined in the header, so this is forbidden. (Note: MOSTEK and Extended TekHex
formats formally forbid this also, but since the addresses in the header are
not used by READ, _HEX ignores this restriction).
.p-5,1,3
Checksum error
.br
.X READ
A checksum error was detected during a file READ operation.
.p-5,1,5
Command file processing aborted
.x Indirect command file
.x Command file
.br
A serious error was detected (e.g_. file comparison failed) when taking
commands from an indirect command file. Command file processing terminates
prematurely at this point and _HEX returns to terminal command input mode.
.p-5,1,5
Command input error
.br
_HEX was unable to get a command line due to a system problem, control
characters typed accidentally, or because the specified indirect command file
was not found/accessible.
.p-5,1,3
Command input timeout
.br
.X Timeout
_HEX has exited because of a timeout on command input.
.;DSR.IF VMS
.;S14.OPTION 3
.p-5,1,3
Command not supported by VMS
.br
.x VAX/VMS
The command is not implemented under VAX/VMS compatibility mode.
.;DSR.ENDIF VMS
.;S14.END OPTION 3
.p-5,1,5
Conversion error
.br
An illegal (perhaps missing) hex character, binary byte, or number terminator
was encountered in trying to obtain a value or character specifier from a
command line or object file.
.p-5,1,4
CRC:#xxxx
.br
.X CRC
This is an informational message in response to a CRC command. It appears even
when the CRC value is destined using the TO option.
.p-5,1,4
xxxx differences
.br
This message appears at the end of a COMPARE operation, giving the number of
differences between the file and virtual memory contents.
.p-5,1,5
EOF reached before trailer record
.br
.X READ
During a file READ, physical end of file occurred before a trailer record was
found (see Appendix A). Data are read correctly, however. This situation is not
reported if the PARTIAL option is set on the command line.
.p-5,1,7
Extra ignored:
.br
This message is followed by the characters remaining on the command line after
a command syntax error was discovered, or superfluous to an otherwise
legitimate command. In the second case, the command up to that point was
accepted and processed. Spaces and tabs do not appear in the command characters
displayed.
.p-5,1,6
Filename syntax error
.br
.X File specification
The file specification was improper. A missing right bracket in the UIC
specification, for example. Note, however, that most filename syntax errors
will result in a "File open error" rather than "File name syntax error".
.p-5,1,7
File open error xxxx
.br
A problem was encountered during an attempt to open a file for input or output.
vvvv is an FCS error code if the high byte is 00, a directive error if it is FF.
Common errors are: 00E6 = non-existent file (READ, COMPARE, or APPEND),
00F0 = privilege violation -- for a READ or WRITE operation, you may not have
sufficient privilege to open such a file under the specified UIC, specified
device may be offline, or some other system problem occurred which prevented
you from opening the file, and 00E7 -- index file full on WRITE, no
more files can be created on the volume.
.p-5,1,4
Format:#f
.br
.X FORMAT
This is an informational message in response to the FORMAT command,
showing the current format for READ and WRITE.
.p-5,1,6
Header record required
.br
The format requires a header record to set up data load information. Currently,
this can only occur with MOSTEK format.
.x Mostek format
.p-5,1,3
:#_HEX version ddmmmy
.br
This is an informational message given by IDENT (See Section 2.5.17).
.p-5,1,3
Illegal command
.br
The first word of the command line was not found in the command dictionary.
.p-5,1,7
Incorrect block count
.br
During a READ operation, a block length, record length, or data count field
(depending on format) was not correct, or insufficient to allow a minimal
record. For Rockwell
.x Rockwell format
format input, this message appears if the "address" in the trailer record does
not match the number of object records in the file.
.p-5,1,3
Invalid block type
.br
A READ operation encountered an unknown block type for the current format.
.p-5,1,6
Invalid character for Extended TekHex
.br
During an Extended TekHex READ or WRITE, a character not in the allowed set
.x Extended TekHex format
(see Appendix A) was encountered. On WRITE, this is most likely to be due to an
illegal character in the program name, which should be altered accordingly.
.p-5,1,4
Invalid width parameter
.br
The WIDTH parameter must be a number between 1 and the maximum shown in
Section 2.5.15.
.p-5,1,6
I/O error xxxx
.br
An unrecoverable I/O error occurred during a READ or WRITE operation. xxxx
is the I/O error code, e.g_. 00E8 means that the disk is full on WRITE,
00F6 is end-of-file on READ. Other errors may be due to system or device
problems, such as a bad block on a disk or someone switching it off-line.
.lm-5.b1.nf.tp9
Low:#xxxx
High:#xxxx
Count:#xxxx
Sum:#xxxx
.lm+5.f
.X READ
.X WRITE
This informational message shows statistics gathered during a file READ or WRITE,
and appears only if the operation completed successfully. All numbers are
hexadecimal. The lowest address and highest address actually loaded are
displayed, as is the count of bytes loaded and the transfer address obtained
from the trailer record. The sum is a 16-bit byte-wise sum over the range of
the READ or WRITE. The transfer address and name will also displayed unless
they are null. For READ, low and high show the new values for the LOW and HIGH
range keywords. For COMPARE, the message is preceded by a line showing the
number of differences found (if any).
.p-5,1,6
xxxx matches found
.I
xxxx mis-matches found
.br
This is an informational message produced at the end of a SEARCH operation
.x SEARCH
showing the number of locations which matched, or did not match, the given key.
.p-5,1,5
Missing keyword
.br
A required keyword (FROM, THRU, TO, FILE etc.) is missing or misspelt in the
command line. Consult Appendix B for the allowed syntax of each command.
.p-5,1,5
Name:#nnnnnnnn
.br
is an informational message, giving the current program name, displayed in
.x Program name
.x NAME
response to the NAME command, or after a READ of a file which defined a program
name. nnnnnnnn is blank if there is no name currently defined.
.p-5,1,4
Name:#nnnnnnnn#######File:#mmmmmmmm
.br
This message appears on COMPARE when the program name read from the file,
mmmmmmmm, fails to match the current one, nnnnnnnn.
.x COMPARE
.p-5,1,4	
Offset:#xxxx
.br
.X OFFSET
This is an informational message in response to an OFFSET command.
The value displayed is the current offset value.
.p-5,1,4
Offset must be 16, 24, or 32-bit value
.br
The value specified in the OFFSET command must be exactly 4, 6, or 8 digits
in order to indicate addressing mode (see OFFSET in Section 2.5.25).
.p-5,1,3
Offset must be even
.br
The value given for OFFSET must be even (word-aligned).
.p-5,1,8
Pausing, to continue, type RES xxxxxx_<esc_>
.br
This message appears when the _. or $ (CLI) command is given without an
.x CLI command
.x _. command
.x $ command
argument, on a system without STOP directive support. It informs the user that
_HEX has released control of the terminal to allow multiple commands to be sent
to the CLI. xxxxxx gives _HEX's name for the MCR RESume command required to
subsequently restart it. Terminating the restart command with escape instead of
carriage-return will suppress a spurious '_>' CLI prompt.
.p-5,1,8
Spawn Failed
.br
.X CLI command
.x _. command
.X HELP
.X Spawn
The HELP or CLI command has failed to send a command line to the Command Line
.X Command Line Interpreter
Interpreter (DCL or MCR). This may be due to an attempt to use a version of _HEX
built for a system with parent/offspring tasking on a system which does not
.x Parent/offspring tasking
actually have it, or to the system being overloaded. Consult the System Manager
if the former is the case, or try re-issuing the command if the latter.
.p-5,1,5
Stopping, to continue, type UNS xxxxxx_<esc_>
.br
As the "Pausing#..." message, but on a system with STOP directive support.
.x CLI command
.x _. command
xxxxxx gives _HEX's full name for the MCR UNStop command required to
subsequently restart it.
.p-5,1,4
Sum:#xxxx
.br	
.X SUM
This is an informational message in response to a SUM command. The value is the
16-bit byte-wise sum over the specified range.
.p-5,1,5
Trailer record ignored
.br
During a READ or COMPARE operation described as PARTIAL, a trailer record
was encountered and ignored. The READ or COMPARE operation terminates at this
point.
.p-5,1,4
Transfer:#xxxx
.br
.X TRANSFER
This is an informational message in response to a TRANSFER command with no
argument. The value shown is the current transfer address.
.p-5,1,5
Transfer:#aaaa####File:#bbbb
.br
This is an informational message in given by the COMPARE operation when a
.x COMPARE
mismatch is detected between the current value of the transfer address and the
value specified by the file.
.p-5,1,4
Unsupported address size in header record
.br
A MOSTEK file read has found a header specifying an address size other than
.x Mostek format
16 or 32 bits.
.p-5,1,6
Unsupported format
.br
The format specified in the FORMAT command is unknown to _HEX. The name may have
been mistyped, or support for this format disabled at build time (see Appendix
C). If this message appears with a READ or WRITE command, it may indicate a
program bug.
.p-5,1,4
Variable length value overflows under current offset
.br
In Extended TekHex format, an attempt was made to read a variable length value
.x Extended TekHex format
.x Addressing mode
too large for the current addressing mode.
.p-5,1,14.nf
Any message which looks like:
.b1.lm+5
Task "..._HEX" terminated
Odd address trap or other trap four
PC	000000
PS	000000
R0	000000
R1	000000
R2	000000
R3	000000
R4	000000
R5	000000
SP	000000
.f.lm-10.p0,1,5
indicates a severe system problem, or the execution of a particular
sequence of instructions in the _HEX task image which resulted in register
contents and/or a trap not envisaged by the author (i.e_. you stumbled upon a
bug). Consult the System Manager.
.AX OBJECT FILE FORMATS
.t HEX FILE EDITOR
.st Object File Formats
There are three basic types of object file:-
.list 1
.le;Hexadecimal files consist of ASCII records containing hexadecimal numbers
for addresses, data bytes, and other load information. They are human-readable,
and acceptable as input to text editors. Intel, Motorola, and most other
formats fall into this class. Their basic formats are very similar, the
differences being in placement of address, data, control, and checksum
information.
.le;PROM programmer files. These also contain hexadecimal (or octal) data, but
the load address and checksum are in separate file records, instead of at the
start of each individual record.
.le;Binary files are not human-readable, and not usually acceptable to editors
(even if you could understand what you were editing). Such files are produced
by the Digital MACRO assembler and TKB task-builder, by SAL cross-assemblers with
the special Sira binary object file option, and by the Whitesmiths' linker.
.els
The records in a file need not be sorted (in ascending order by address), or
of any particular count. The file need not define every address in its range;
undefined locations will be left unchanged.
.p0
Any record following a trailer record is ignored.
.p0
This appendix summarises the various formats as they are used by _HEX. Consult
the appropriate software manuals for full details. Some formats have additional
options not described here. The effects of using them is undefined -- they may
be simply ignored, cause _HEX to reject a file READ, or even crash it.
.p0
Note that many formats do not provide for 24 or 32-bit addresses. In such cases
only as many low bytes as are supported are written by _HEX, and a suitable
OFFSET and/or PLUS value must be given in order to READ it back.
.p0
Examples are given of each format, obtained by writing out an area of memory
from 1012 to 1034 set to ascending byte values, and with a program name of
PROGRAM, and start address 1234, so a DISPLAY command would give:
.b1.tp8.lm+5.NF
Name: PROGRAM        Transfer: 1234
.B1
Addr    00  01  02  03  04  05  06  07  08  09  0A  0B  0C  0D  0E  0F
----    --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
.B1
1010    FF  FF  01  02  03  04  05  06  07  08  09  0A  0B  0C  0D  0E
1020    0F  10  11  12  13  14  15  16  17  18  19  1A  1B  1C  1D  1E
1030    1F  20  21  22  23  FF  FF  FF  FF  FF  FF  FF  FF  FF  FF  FF
.F.lm-5
.;BON^=
.HL1 INTEL FORMAT
.;BON\=
.x Intel format
Standard Intel hexadecimal object format is:
.p12
:bbaaaattdddd ... ddcc
.BR
where:
.lm+12.ts12,16.p-8
:	marks the start of the record.
.i
bb	is a two-digit hexadecimal number of data bytes in the record. 
.tp2.i
aaaa	is a four-digit hexadecimal load address of the first byte of data
if tt is 00, or always 0000 if tt is non-zero.
.TP5.i
tt	is a two-digit number defining the record type:
.lm+5.nf
00 = data record
01 = end of file
02 = extended address record
03 = transfer address record
.f.lm-5.i
dd	are 2-digit hexadecimal values of data bytes to be stored.
.TP3.i
cc	is a two-digit record checksum -- the two's complement of the sum of
all the bytes from the byte count to the last data byte, so that
(aa+aa+tt+dd+dd+#...#dd+cc) is zero.
.lm-12.s1
A file will consist of a number of records, terminating with one in which tt is
01 or bb is equal to zero (the latter condition is not part of the current Intel
standard, but is supported by _HEX for historical reasons).
.p0
.X Extended address
Extended address records (type 02) are used in 24- and 32-bit modes to specify
a "segment base address" to be added to all subsequent data record addresses
(aaaa's). Extended address records always contain two bytes of data giving, in
hi-lo order, bits 4-20 of the base address, as base address/10H (bits 0-3 are
always clear). In 24- and 32-bit modes, files written by _HEX begin with an 02
.X OFFSET
record giving the current OFFSET/10H. Only bits 0-3 of OFFSET are then added to
the address fields in subsequent data records. In 16-bit mode, no 02 record is
written, and OFFSET is added in full to data record addresses. Therefore one
.X APPEND
should not APPEND in 16-bit mode to a file previously written with a non-zero
24-or 32-bit offset -- use OFFSET 000000 instead.
.p0
The 03 record specifies a transfer address. It contains two pairs of data
bytes. The first pair gives bits 4-20 of a base address, as above, and the
second pair bits 0-15 of the relative address to be added to this. _HEX always
sets the first pair to bits 16-19 of the transfer address, with the remaining
bits clear, and puts the low 16 bits of the transfer address into the second
pair.
.p0
There is no facility to define the program name, which is therefore always
unchanged when an Intel format object file is read.
.p0
Characters preceding a colon in a record are treated as a comment, and any
record not containing a colon is ignored.
.p0,1,6
The following example is output for the standard data in 16-bit mode:
.B1.TP4.lm+5.NF
:0E1012000102030405060708090A0B0C0D0E67
:151020000F101112131415161718191A1B1C1D1E1F20212223AE
:0400000300001234B3
:00000001FF
.F.lm-5.p0,1,9
In 24-bit mode, with an OFFSET of 010000 and transfer address of 021234, _HEX
would write the following file. Note that it starts with an 02 record
giving the OFFSET/10H (010000/10=1000), and that the first data word of the
03 record has become transfer address base 2000(0):
.b1.tp5.lm+5.NF
:020000021000EC
:0E1012000102030405060708090A0B0C0D0E67
:151020000F101112131415161718191A1B1C1D1E1F20212223AE
:040000032000123493
:00000001FF
.F.lm-5
.;BON^=
.HL1 MOTOROLA FORMAT
.;BON\=
.x Motorola format
Motorola format object file consist of a number of records in the following
format:
.p12
Stbbaaaadddd#...#ddcc
.lm+12.ts12.i-12
where:
.p-8,1,4
St	is two ASCII characters defining the record type: S0 denotes a file
header, S1 and S2 data records, and S8 and S9 the end of file record.
.tp3.i
bb	is a two-digit hexadecimal number giving the number of bytes (pairs of
hex ASCII characters) specified, including the address, data and checksum.
.tp4.i
aaaa	is a 4 or 6-digit hex number setting the load address of the first
byte, high byte first. S1 and S9 records have 4-digit addresses, S2 and S8
records have 6. There is no provision for 32-bit addresses, which are
therefore truncated to 24 bits.
.i
dd	are two-digit hexadecimal values of the data to be stored.
.tp4.i
cc	is a two-digit hexadecimal record checksum. This is the one's
complement of the sum of all the bytes from the byte count to the last data
byte (bb+aa+aa+dd+dd+ .._. dd), so that the 8-bit sum of everything except the
St is $FF.
.lm-12.p0
A complete object file commences with an S0 record having a dummy address of
0000, and a data portion of 0-6 bytes, which is the first six characters of the
program name, written as ASCII character values in hexadecimal. This is
followed by a number of S1 or S2 records which contain the actual object code.
The file terminates with an S8 or S9 record containing only the program
transfer address.
.p0
As with Intel format, anything on a line up to the S, or after the S8/S9
trailer record, is treated as comment. The Whitesmiths' hex conversion utility
includes some null data bytes in the trailer record; these are also ignored.
.p0,1,7
Example:
.B1.TP4.lm+5.NF
S00B000050524F4752414D20BC
S11110120102030405060708090A0B0C0D0E63
S11810200F101112131415161718191A1B1C1D1E1F20212223AA
S9031234B6
.F.lm-5
.;BON^=
.HL1 ROCKWELL FORMAT
.;BON\=
.x Rockwell format
Rockwell format files consist of a number of records in the following format,
compatible with the KIM/TIM/MDT format, also used by the Commodore 'PET'
assembler:
.p12
_;bbaaaadd#...#ddcccc
.tp4.lm+12.ts12.i-12
where:
.p-8,1,3
bb	is a two-digit hexadecimal number giving the number of data bytes,
dd#...#dd, in the record.
.tp2.i
aaaa	is a four-digit hexadecimal load address of the first data
byte, high byte first.
.i
dd	are two-digit hexadecimal values of the data to be stored.
.tp3.i
cccc	is a four-digit hexadecimal checksum for the record. This is the sum of
all the bytes from the byte count to the last data byte inclusive
(bb+aa+aa+dd+#...#dd).
.lm-12.p0,1,4
The file ends with a record having a byte count of 00, and an "address" which
is the number of records in the file. There is no way of giving a program name
or transfer address.
.p0,1,6
Example:
.B1.TP3.lm+5.NF
_;0E10120102030405060708090A0B0C0D0E0099
_;1510200F101112131415161718191A1B1C1D1E1F202122230252
_;0000020002
.F.lm-5
.;BON^=
.HL1 RCA FORMAT
.;BON\=
.x RCA format
The UT4 utility of the COSMAC evaluation kit monitor recognises data records
of the form:
.p12
!Maaaaxddxddx...#ddxt
.b1
and trailer records as:
.b.nf.lm+12
$P[ssss]
.ts12,23.i-12
where:
.f.p-8,1,3
!M	indicates a following load address. Everything before this indicator
(or a $P) is ignored.
.tp2.i
aaaa	is a 1-4 digit hexadecimal number giving the load address. Only the
last four digits are significant.
.i
dd	are two-digit hexadecimal values of the data to be stored.
.tp4.i
x	represents any non-hex number separators, which are ignored. At least
one such terminator must appear after the aaaa address field, but they are
optional between data bytes. _HEX always writes single spaces.
.tp5.i
t	is a line terminator, comma, semicolon, or blank, where:
.LM+11.I-11
comma	indicates that the following record contains data only, to be loaded
contiguously with that on this record, and no !Maaaa address specification
is required (or allowed).
.tp3.I-11
semicolon	indicates that data on the following record is to be loaded
starting at a new address given by an aaaa field (without a !M prefix) as the
first item on that record.
.tp3.I-11
blank	indicates the end of a data record. The next record must start with a
full !Maaaa load address or a $P transfer address specification.
.tp2.LM-11.i
ssss	(if given) is the transfer address. It may be omitted, but _HEX still
expects a $P record as a file trailer.
.lm-12.f.p0
The following example illustrates the three types of data record, all which are
acceptable on READ. _HEX only WRITEs semicolon or blank terminated records,
displaying the load address of each line for convenience:
.b1.tp4.lm+5.NF
!M1012 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E,
0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E;
1030 1F 20 21 22 23
$P1234
.F.lm-5
.;BON^=
.HL1 TEKHEX FORMAT
.;BON\=
.x TekHex format
.tp6
Standard Tektronix ("TekHex") format, used by the 8000 series emulators, is:
.p12.ts12
/aaaabbhhdddddd ... ddcc
.tp6.lm+12.i-12
where:
.p-8,1,3
aaaa	is a four-digit hexadecimal load address of the first byte of the data.
.i
bb	is a two-digit hexadecimal number of data bytes in the record.
.tp2.i
hh	is a two-digit checksum of the address and byte count fields. This is
the sum of the values of those six hex digits, i.e_. a+a+a+a+b+b.
.i
dd	are two-digit hexadecimal values of the data to be stored.
.tp2.i
cc	is a two-digit hexadecimal checksum of the data bytes,
being the sum of the values of the preceding 2_*bb digits, i.e_. d+d+#...#d.
.lm-12.s1
A file may consist of a number of records and is terminated by a record
containing no data (hence bb = 00), and an address which is the transfer
address of the program (or 0000 if none), as:
.b1.tp3.lm+5.NF
/10120E120102030405060708090A0B0C0D0E69
/102015090F101112131415161718191A1B1C1D1E1F20212223A5
/1234000A
.F.lm-5
.;.p0
.;If there is no transfer address, the terminator block is replaced by an
.;"abort" record, beginning with two slashes and containing a message, as:
.;.p5
.;// No transfer address
.;BON^=
.HL1 EXTENDED TEKHEX FORMAT
.;BON\=
.X Extended TekHex format
.tp6
Extended TekHex format is used by Tektronix 8550 series emulators. The data and
trailer record format is:
.p12.ts12
%bbtccna...adddddd#...#dd
.tp6.lm+12.i-12
where:
.p-8,1,3
bb	is a two-digit hexadecimal number giving the number of characters in
the record, excluding the starting percent (%).
.tp2.i
t	is the record type: 3 is a symbol definition record (header), 6 is a
data record, and 8 a trailer.
.tp2.i
cc	is a two-digit checksum of all characters except itself and the %, with
special character coding, as shown below.
.tp2.i
na...a	is an n-digit hexadecimal load address of the first byte of the data.
.i
dd	are two-digit hexadecimal values of the data to be stored.
.p-12
The header record ("symbol record") has a somewhat different format:
.b1
%bb3ccns...s0nl...lnc...c
.p-12
where bb and cc are as above, t=3, and:
.p-8
ns...s	is the program name.
.tp2.i-8
nl...l	is an n-digit hexadecimal number giving the lowest address in the
module.
.i-8
nc...c	is an n-digit number giving the number of bytes in the module.
.lm-12.p0
_HEX writes a full header record as above, but ignores the low address and
count value. Tektronix emulators may write other information into "symbol
records", but this is also ignored by _HEX.
.p0
A file starts with a header record giving the program name, followed by a
number of data records, and terminated by a type 8 trailer record containing an
address defining the transfer address of the program (or 0000 if none), as:
.b1.tp4.lm+5.NF
%1A3BF7PROGRAM0810120000223
%2667F410120102030405060708090A0B0C0D0E
%346B9410200F101112131415161718191A1B1C1D1E1F20212223
%0A82041234
.F.lm-5
.;.p0
.;If there is no transfer address, the terminator record is replaced by an
.;"abort" record, in the same form as standard TekHex.
.p0
Checksums are computed by summing the characters in each record, assigning
them non-ASCII codes:-
.lm+15.ts30.nf.P-4,1,9
Characters####Values (decimal)
.I-4
----------####----------------
0-9	#0-9
A-Z	10-35
##$	##36
##_.	##38
##__	##39
a-z	40-65
.LM-15.F.p0
All other characters are illegal and will result in a fatal error if
encountered in a READ or WRITE operation.
.p0
Note: 8550 emulators seem to add C0000000 to all addresses, so an OFFSET of
this value should always be set before processing extended Tekhex files.
.;BON^=
.HL1 TEXAS FORMAT
.;BON\=
.x Texas format
Texas object files, used by development systems for the TI99xx series of
processors, consist of a number of entries, each of which starts with a single
"tag" character which identifies the type of entry and hence the meaning of
any following characters. The following record types are recognised by _HEX:
.lm+5.b1.TP7.nf.ts21
00000nnnnnnnn	specify program name, nnnnnnnn.
1aaaa	specify program transfer address, aaaa.
7ssss	ssss is checksum of all ASCII chars, including 7 tag.
9aaaa	specify load address, aaaa, for following B records.
Bdddd	specify data word.
F	marks end of record.
:#comment	trailer record.
.lm-5.f.p0
Other types are defined, for relocatable code, but these are not supported by
_HEX, and will give fatal load errors.
.p0
Entries of different types may be concatenated into longer file records, each
ending with an F entry. The load address automatically advances by 2 for each
B entry, unless modified by an intervening 9. Checksums are the
negative of the 16-bit sum of all ASCII codes from the previous checksum or
start of file up to and including the 7 checksum entry tag.
.p0
The transfer address record may appear anywhere in the file. _HEX places it at
the end, followed by a trailer record, the only required component of the which
is the :, _HEX adds its name and revision date as comment.
.p0
Note that data entries always give a full word. _HEX will put a null padding
byte at the end of the output if necessary. Formally, all 9 entries should
specify even addresses, and some development systems will round down an odd
one. _HEX does not do this, however, so that the addresses are correct for
a hi-byte PROM file.
.p0,1,9
Example:
.lm+5.B1.NF
00000PROGRAM 7FCA1F
91012B0102B0304B0506B0708B090AB0B0CB0D0E7F732F
91020B0F10B1112B1314B1516B1718B191AB1B1CB1D1E7F60CF
91030B1F20B2122B23007FBA1F
112347FECEF
_:#_HEX version 23Sep6
.F.lm-5
.;BON^=
.HL1 MOSTEK FORMAT
.;BON\=
.;SIR.MX Mostek format
.X Mostek format
MOSTEK files have four types of record, with the following general format:
.p12.ts12
ttrrrrxx...xxcc
.tp6.lm+12.i-12
where:
.p-8,1,4
tt	is the record type: F0 is a header record, F2 is an "enumerated"
data record, F4 is an "iterated" data record, and F6 is a trailer record.
.i
rrrr	is the number of bytes in the record body plus checksum.
.i
xx...xx	is the record body, whose format depends on the record type.
.TP3.i
cc	is the two's complement of the sum of all bytes in the record from tt
up to the last byte of the record body, so that the sum of all bytes in the
record is 00.
.p-12
Module header records take the form:
.b1
F0rrrrssnn...nnaappmmllllhhhhcc
.p-12
where, in addition to the above:
.p-8,1,3
ss	is the length of the program name. This can be up to 100 (decimal)
characters, but _HEX only reads or writes a maximum of 8.
.tp2.i-8
nn...nn	is the hexadecimally encoded program name. If there is none, ss is 00,
and nn...nn is omitted.
.tp4.i-8
aa	is the address size, according to the current mode determined in
the last OFFSET command. Only 16 and 32-bit addressing is supported; 24-bit
mode is treated as 32. This field must therefore be 10 or 20. Any other value
will give an error on READ.
.tp3.i-8
pp	is a code identifying the processor: 00#=#unknown, 01#=#3870,
02#=#8080, 03#=#Z80, 05#=#68000. _HEX ignores this field on READ, and always
sets it to 00 (unknown) on WRITE.
.tp5.i-8
mm	is the module type: 00 is a non-main module, and 02 is a main module,
01 is added to the code if there is a transfer address. READ sets or clears
the PARTIAL flag according to the transfer address bit, and ignores other bits.
WRITE always sets mm to 02 or 03.
.tp2.i-8
llll	is the low 16-bits of the lowest address in the module. This is
ignored by READ, set to FROM by WRITE.
.tp2.i-8
hhhh	is the low 16-bits of the highest address, THRU, again ignored by READ.
.p-12
Enumerated data records have format:
.b1
F2rrrraaaadd...ddcc
.i-12
where:
.p-8,1,3
aaaa	is a 4 or 8-digit hexadecimal load address for the first byte in the
record.
.i
dd...dd	are the data bytes to be loaded sequentially from this address.
.p-12
Iterated data records have format:
.b1
F4rrrraaaannnnbbyy...yycc
.i-12
where:
.p-8,1,2
aaaa	is again a 4 or 8-digit load address for the first byte.
.tp2.i
nnnn	is a replication factor giving the number of times the current
portion of the record is to be repeated.
.tp2.i
bb	is a record count, zero if this is the final inner record, non-zero
if there are further nested ones.
.tp4.i
yy...yy	is an inner nested repeat of another record containing fields
nnnnbbyy...yy if bb is non-zero, otherwise it takes the form wwdd...dd, where
ww is a byte count of dd...dd bytes to be inserted nnnn times.
.lm-12.p0
Nesting to 15 levels is allowed, but _HEX does not check whether this is
exceeded. Clearly, this nested structure can be extremely complicated. READ
should be able to process any structure. WRITE only produces the simple case of
a single level of identical data bytes when all of the current WIDTH bytes are
the same (and WIDTH_>5). Note that the checksum for an iterated record is the
sum of the bytes in the ^&record\&, ^&not\& all the repeated data stored in
memory.
.p0
The trailer record has the format:
.lm+12.b1
F6rrrraaaacc
.i-12
where:
.p-12,1,3
aaaa	is the transfer address. This may be omitted if there is none, in
which case rrrr is 0001.
.lm-12.p0
The following example is the usual demonstration data, extended to address 104F
to show an iterated record of all FFs:
.b1.tp6.lm+5.NF
F000100750524F4752414D1000030000003D91
F2001310120102030405060708090A0B0C0D0E70
F2001510200F101112131415161718191A1B1C1D1E61
F2001510301F20212223FFFFFFFFFFFFFFFFFFFFFF1F
F4000A104000100001FFA2
F600051234BF
.F.lm-5
.;BON^=
.HL1 WHITESMITHS' FORMAT
.;BON\=
.;SIR.mx Whitesmiths' format
.x Whitesmiths' format
This is the format of files output by the cross-assemblers and linkers of the
Whitesmiths' C system Version 2.1 or later (V2.0 and earlier used a different
format). It takes the form of a file of single-byte, fixed-length records, as:
.nf.b1.lm+5.ts17,30
byte 1:	ident byte, always 99H
.tp9
byte 2:	configuration byte:
	bits 0-2:	(no of chars in symbol table field)/2 - 1
	bit3:	0 = integers below are 2 bytes,
		1 = integers are 4 bytes
	bit4:	0 = integers stored msb first,
		1 = lsb first
	bits 5-6:	storage bound restriction control bits
	bit 7:	0 = relocation information supplied,
		1 = no relocation information supplied.
bytes 3-4:	size of symbol table.
.tp7.i-5
The next 6 entries are 2 or 4 byte integers as defined in byte 2, bits 3 and 4:
integer 1:	number of text (program code) bytes.
integer 2:	number of data bytes.
integer 3:	no of bss (uninitialised data) bytes.
integer 4:	size of stack+heap.
integer 5:	text area start address.
integer 6:	data area start address.
.tp5.i-5
This is followed by four contiguous records of lengths given above:
segment 1:	text area.
segment 2:	data area.
segment 3:	symbol table.
segment 4:	relocation information.
.f.lm-5.p0
Program name information is not included.
.p0
_HEX only reads the text and data areas, and assumes that all relocation has
already been done by the Whitesmiths' linker. Whitesmiths' object files, which
have the same format, may be read, but locations which should be adjusted by
the linker will be incorrect. Bits 5 and 6 of the configuration byte are used
by the Whitesmiths' utilities to indicate that addresses are being forced to
multiples of 1, 2, 4, or 8. This is done by the Whitesmiths' linker, so _HEX
ignores the bit settings on READ. Note, however, that the linker inserts null
bytes at the end of text or data areas as necessary to force the required
bounds, and these will be read in by _HEX.
.p0
On WRITE, _HEX treats the whole output range as text, and thus sets the data
count to zero. The integers are written least significant byte first, in two
bytes for 16-bit mode or four bytes for 24- or 32-bits. No symbol table or
relocation information is output. Bits 5 and 6 of the configuration byte are
always set to 00; it is the user's responsibility to set appropriate FROM
and THRU addresses if a particular boundary is required, and to insert any
padding bytes. The six integers are always written least significant byte
first, and of 2 or 4 bytes according to the current addressing mode.
.x Addressing mode
.p0
The following is an annotated hexadecimal byte DMP of the example program in a
Whitesmiths' format file. Note that, for some reason best known to DEC, values
should be read from right to left!
.b1.tp6.lm+5.NF
00 00 10 12 00 00 00 00 00 00 00 23 00 00 90 99         0000
dt ad tx ad stack  bss  data  text  table cf id
10 0F 0E 0D 0C 0B 0A 09 08 07 06 05 04 03 02 01         0010
20 1F 1E 1D 1C 1B 1A 19 18 17 16 15 14 13 12 11         0020
00 00 00 00 00 00 00 00 00 00 00 00 00 23 22 21         0030
_...empty symbol table and data area...
.F.lm-5
.;BON^=
.HL1 PDP-8/IM6100 READ-IN-MODE FORMAT
.;BON\=
.x PDP-8 Read-In-Mode format
.x IM6100 Read-In-Mode format
.x RIM format
Read-In-Mode format is used by the PDP-8 mini-computer, and the IM6100
microprocessor which simulates it, for bootstrap paper tapes. See Section 2.4.1
for a special note regarding address specifications in this format.
.p0
RIM is a binary format in which each 12-bit data word is immediately preceded
by its 12-bit address, as follows:
.lm+5.B1.TP4.ts21,37.nf
first byte:	01hhhhhh	hi 6 bits of address
second byte:	00llllll	lo 6 bits of address
third byte:	00hhhhhh	hi 6 bits of data
fourth byte:	00llllll	lo 6 bits of data
.lm-5.f.p0
The address is thus identified by having bit 6 of its first byte set. Leader
and trailer are written with bit 7 only set; any such bytes are ignored by _HEX.
Bits 12 to 15 of address and data are cleared by WRITE, but still checked by
COMPARE. WRITE expects to output byte pairs. If the data count is odd, it will
output a dummy zero six bits in the low hald of the final word.
.p0
There is no way to include a start address or program name.
.p0
The following is an octal DMP of the standard program in RIM format:
.b1.lm+5.ts21.nf.tp6
	 Record number 01. - Size 50. bytes (leader)
.b1
000000  200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200
000020  200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200
000040  200 200 200 200 200 200 200 200 200 200 200 200 200 200 200 200
000060  200 200
.b1.tp4
	 Record number 02. - Size 28. bytes
.b1
000000  140 011 004 002 140 012 014 004 140 013 024 006 140 014 034 010
000020  140 015 044 012 140 016 054 014 140 017 064 016
.b1.tp4
	 Record number 03. - Size 32. bytes
.b1
000000  140 020 074 020 140 021 004 022 140 022 014 024 140 023 024 026
000020  140 024 034 030 140 025 044 032 140 026 054 034 140 027 064 036
.b1.tp5
	 Record number 04. - Size 12. bytes
.b1
000000  140 030 074 040 140 031 004 042 140 032 140 032
.b1
	 Record number 05. - Size 50. bytes (trailer, as leader)
.lm-5.f.p0
RIM (and BIN) tapes may be punched by a simple PIP or COPY command to PP:, no
special FLX processing is required.
.;BON^=
.HL1 PDP-8/IM6100 BINARY FORMAT
.;BON\=
.X BIN format
.x PDP-8 binary format
.x IM6100 binary format
This is similar to RIM format except that addresses need not be given between
contiguously stored data words. In fact, _HEX does not distinguish at all
between the two formats for READ, only on WRITE. See the comments in the
previous section regarding address specifications. The following is a DMP
of a BIN tape containing the same data as above (header and trailer records
are omitted for brevity). Note that addresses (octal values _> 100) occur only
at the start of the records:
.b1.lm+5.tp3.nf
	 Record number 02. - Size 16. bytes
.b1
000000  140 011 004 002 014 004 024 006 034 010 044 012 054 014 064 016
.b1.tp4
	 Record number 03. - Size 22. bytes
.b1
000000  140 020 074 020 004 022 014 024 024 026 034 030 044 032 054 034
000020  064 036 074 040 004 042
.f.lm-5
.;BON^=
.HL1 HEX PROM PROGRAMMER FORMAT
.;BON\=
.x HEX format
.x PROM programmer format
HEX format is used by several PROM programmers, such as those manufactured by
Data#I/O and Stag. The format of the file is:
.s1.nf.lm+17
b$Assss,
_*
aaaa-ddxddxddx...xddxddx
              ...
aaaa-ddxddxddx...xddxddx
e$Scccc,
####################_<ctrl/S_>_<ctrl/Q_>
.lm-5.tp4.i-12
where:
.ts12.f.tp2.p-8,1,6
b	indicates the start of data. Anything except the "$Scccc," sequence
which appears before this is ignored. b is a control code: ctrl/A#=#SOH (hex
code 1) or ctrl/B#=#STX (2) for standard formats, and ctrl/R#=#SOM#=#DC2 (12)
for SMS format. _HEX always writes ctrl/A or ctrl/R.
.tp2.i
ssss	is a 1-4 digit hexadecimal load address of the first data byte of
the file (but see below).
.tp4.i
_*	is present purely for cosmetic purposes to separate the address from
the start of the data. It is ignored by _HEX, and the DataIO programmer, but may
be useful for other programs which read PROM programmer files.
.tp2.i
aaaa	is a 1-8 digit hexadecimal address of the actual load address of
the first byte of the line.
.tp5.i
dd	are hexadecimal values of the data to be stored. Any number of digits
may be given (immediately preceded by an x separator character) but only the
low byte is stored. _HEX always writes a maximum of 16 2-digit values per line,
regardless of WRITE's WIDTH argument, which sets the PROM size only.
.tp6.i
x	is an "execute" character, signifying that the previous number is to be
taken as a data value. Any intervening characters are ignored. The character
used is set when the FORMAT command is used to select HEX format (see Section
2.5.15). _HEX will accept anything, but Data#I/O programmers only take space,
apostrophe, comma, or percent. HEX SMS format always uses the apostrophe
character.
.tp4.i-8
e	indicates the end of data. Anything other than "$Scccc," between this
code and the next b is ignored. e is a control code, ctrl/C#=#ETX (hex 03)
for normal format and ctrl/T#=#EOM#=#DC4 (14) for SMS format.
.tp2.i-8
cccc	is a 1-4 digit hexadecimal a checksum for the block -- the
16-bit sum of the 8-bit data bytes.
.tp7.i-8
ctrl/S	This character is included to stop automatically a paper tape reader
being used to load data into a PROM programmer. It prevents it being confused
by spurious incoming data from later records or a ragged end of tape. It is
preceded by 20_. spaces so that a Data#I/O will stop accepting input at the
end of a record; without these spaces, successive program records will
overwrite memory from address 0000 upwards.
.tp3.i-8
ctrl/Q	Certain terminal keyboards (e.g_. the Digital VT100) are locked by the
preceding ctrl/S. This character prevents this happening if a PROM file is
displayed on such a terminal.
.lm-12.p0
Early model Data#I/O programmers cannot relocate the incoming data, and
some other programmers assume that the data starts at the base address of the
PROM. To accommodate these restrictions, _HEX always writes output from the
beginning of the PROM containing to the start address given in the WRITE
command, inserting padding null bytes before the data at the given address.
ssss is always set to 0000, and the aaaa- values specify actual addresses.
(Should the execute character be -, the address is given as aaaa=.)
.p0
When such a file is read by the programmer, the aaaa values are ignored, since
they are more than two characters away from the execute character, and
everything is written into locations relative to the base of the PROM.
.p0
_HEX, however, recognises the aaaa- addresses as well as the ssss start address,
so data should be written back into the right place. (Note that the padding
nulls will be stored unless a range specification is given.) Files written by
the programmer do not include the aaaa- addresses, so it may be necessary to
use a READ PLUS option to load data into the right region of virtual memory.
.p0,1,11
Example (HEX-space format):
.lm+5.B1.NF
PROGRAM
_<ctrl/B_>$A0000,
_*
1000-00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
1010-00 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E
1020-0F 10 11 12 13 14 15 16 17 18 19 1A 1B 1C 1D 1E
1030-1F 20 21 22 23
_<ctrl/C_>$S0276,
                    _<ctrl/S_>_<ctrl/Q_>
.F.lm-5
.;BON^=
.HL1 OCTAL PROM PROGRAMMER FORMAT
.;BON\=
.x OCTAL format
.x PROM programmer format
OCTAL format is similar to HEX except that, as the name implies, numbers are
written in octal instead of hexadecimal. Thus the checksum is a 1-6 digit
number, addresses may be up to 11 digits, and data bytes are 1-3. The following
is the usual example in OCTAL#SMS format:
.B1.tp8.lm+5.NF
PROGRAM
_*
_<ctrl/R_>$A000000,
010000-000'000'000'000'000'000'000'000'000'000'000'000'000'000'000'000'
010020-000'000'001'002'003'004'005'006'007'010'011'012'013'014'015'016'
010040-017'020'021'022'023'024'025'026'027'030'031'032'033'034'035'036'
010060-037'040'041'042'043'
_<ctrl/T_>$S001166,
                    _<ctrl/S_>_<ctrl/Q_>
.F.lm-5
.;BON^=
.HL1 TCI FORMAT
.;BON\=
.x TCI format
This format consists of records of the form:
.p12
@aaaadddd#...#dd
.TS12.lm+12.i-12
where:
.p-8,1,2
@	marks the start of the record -- everything before it is ignored.
.i
aaaa	is a four-digit hexadecimal load address of the first data byte.
.i
dd	are two-digit hexadecimal values of the data to be stored.
.lm-12.p0
There is no byte count field (everything in the file record after aaaa is taken
as data), no trailer record, and no way to write a program name or transfer
address.
.p0,1,5
Example:
.lm+5.NF.B1
@10120102030405060708090A0B0C0D0E
@10200F101112131415161718191A1B1C1D1E1F20212223
.F.lm-5
.;BON^=
.HL1 FAIRCHILD FORMAT
.;BON\=
This is the format used by the "Fairbug" monitor. Three types of record
are used:
.nf.b1.lm+12.ts12
Saaaa
Xdddd#...#ddc
_*
.F.tp4.i-12
where:
.p-8,1,3
aaaa	is a four-digit hexadecimal load address of the first data
byte, high byte first.
.i
dd	are two-digit hexadecimal values of the data to be stored.
.tp3.i
c	is a hexadecimal digit giving the checksum for the record. This is the
sum of all the data nybbles, d+d+d+#...#d, ignoring overflow above 4 bits.
.lm-12.p0,1,4
The file ends with a record starting with an asterisk. There is no way to
give a program name or transfer address.
.p0,1,7
Example:
.lm+5.B1.NF
S1012
X0102030405060708090A0B0C0D0E9
X0F101112131415161718191A1B1C1D1E1F202122235
_*
.F.lm-5
.;BON^=
.HL1 SIRA BINARY FORMAT
.;BON\=
.x Sira binary format
Sira binary format takes the following form:
.p12
1aatbbdd#...#ddc
.lm+12.ts12,24.i-12
where
.TP2.p-8,1,3
1	is a binary byte marking the start of the record -- 00000001B (ASCII
ctrl/A).
.tp2.i
aa	is two binary bytes giving the 16-bit load address of the first byte of
the data. The low address byte is stored in the first byte.
.tp4.i
t	is a binary byte defining the record type:
.lm+5.nf
00000000B = normal data record,
00000001B = end of file record,
00000002B = auto start record.
.tp2.f.lm-5.i
bb	is a two-byte binary count of the data bytes, with the
low byte of the count in the first byte.
.i
d	are single binary bytes of data.
.tp2.i
c	is a binary checksum -- the sum of all bytes apart from the start code.
.b1.lm-12
The file may consist of several records, finishing with one containing
1 or 2 in byte 4.
.p0
The following is an octal byte DMP of a Sira binary file:
.b1.tp5.lm+5.nf.ts21
	 Record number 01. - Size 42. bytes
.b1
000000  001 022 020 000 043 000 001 002 003 004 005 006 007 010 011 012
000020  013 014 015 016 017 020 021 022 023 024 025 026 027 030 031 032
000040  033 034 035 036 037 040 041 042 043 273 000 000 000 000 000 000
.b1.tp3
	 Record number 02. - Size 7. bytes
.b1
000000  001 064 022 002 000 000 110 000 000 000 000 000 000 000 000 000
.f.lm-5
.;BON^=
.HL1 DEC OBJECT FORMAT
.;BON\=
.x DEC object format
This is the output of the MACRO assembler when the _.ENABL#ABS directive, or
/EN:ABS command line switch is used. The file contains binary records in the
form:
.p12
aaddd#...#d
.lm+12.ts12.i-12.tp6
where:
.tp2.p-8,1,3
aa	is two binary bytes setting the load address of the first byte of
data. The low address byte is stored in the first byte.
.i
d	are one or more data bytes, stored sequentially.
.lm-12.p0
There is no byte count -- the whole of the record, less the two address
bytes, is taken as data.
.p0
The file is terminated by a two-byte record containing just the start
address, if even, or an odd number (always 1) if no start address is defined.
There is no facility to output a program name, even if the _.TITLE, or
_.IDENT directive appears in the source code.
.p0
The following is an octal byte DMP of an object format file:
.b1.tp5.lm+5.nf.ts21
	 Record number 01. - Size 37. bytes
.b1
000000  022 020 001 002 003 004 005 006 007 010 011 012 013 014 015 016
000020  017 020 021 022 023 024 025 026 027 030 031 032 033 034 035 036
000040  037 040 041 042 043 000 000 000 000 000 000 000 000 000 000 000
.b1.tp3
	 Record number 02. - Size 2. bytes
.b1
000000  064 022 000 000 000 000 000 000 000 000 000 000 000 000 000 000
.f.lm-5
.;BON^=
.HL1 PDP-11 ABSOLUTE LOADER FORMAT
.;BON\=
.x PDP-11 absolute loader format
.x Absolute loader format
This is the format used by the PDP-11 paper tape absolute (^&not\& bootstrap)
loader. It may be obtained by loading a tape produced by one of the stand-alone
assemblers, the VMR SAVE command, FLX DOS formatted binary output, of the RT-11
LINK utility with the /L switch (DCL command LINK/LDA). Records take the form:
.lm+12.b1
10bbaabbd#...#dc
.ts12.i-12
where:
.TP2.p-8,1,2
1	is a binary (1) byte indicating the start of the record.
.i
0	is a null padding byte.
.tp2.f.i
bb	is a two-byte binary number of bytes in the record,
from the 1 up to the last data byte, stored lo byte first.
.tp2.i
aa	is a two-byte binary load address of the first byte of
data, stored lo byte first.
.i
d	are single binary bytes of data.
.tp3.i
c	is a binary checksum -- the two's complement of sum of all bytes from
the 1 to the last byte of the data, so that the low byte of the sum for the
whole record, including the checksum, is 0.
.b1.lm-12
The file may consist of several records, finishing with a record containing
only an address, which is even if it is a transfer address, or odd (usually 1)
if there is none.
.p0
The following is an octal byte DMP of an absolute binary file:
.lm+5.nf.ts21.b1.tp5
	 Record number 01. - Size 42. bytes
.b1
000000  001 000 051 000 022 020 001 002 003 004 005 006 007 010 011 012
000020  013 014 015 016 017 020 021 022 023 024 025 026 027 030 031 032
000040  033 034 035 036 037 040 041 042 043 076
.b1.tp3
	 Record number 02. - Size 7. bytes
.b1
000000  001 000 006 000 064 022 263
.f.lm-5
.;BON^=
.HL1 TASK FILE FORMAT
.;BON\=
.x Task format
Where a number of relocatable PDP-11 modules must be combined to form a
program (e.g_. one written in a high-level language) it is not always
possible or desirable to use the MACRO assembler absolute output. In such
cases, the RSX-11M task-builder, TKB (^&not\& FTB) may be used to produce a
file which can be read by _HEX to blow PROMs for a stand-alone machine.
.p0
Assemble or compile the sources to relocatable object modules in the usual way,
and link them with a task-builder command of the form:
.nf.lm+5.b1
USERPROG.SYS/-HD/-MM/-FP/-SE,LP=USERPROG...
/
UNITS=0
ACTFIL=0
ASG=0
PAR=:_<lo addr_>:_<size_>
STACK=_<break_>
TASK=_<name_>
//
.LM+9.f.p-14,1,5.ts14
where:
.P-14,1,3
_<lo#addr_>	is the lowest memory address to be loaded. It must be given in
octal bytes, and be a multiple of 100(8).
.p-14,1,7
_<size_>	must be a value big enough to contain the given code, and is again in
octal bytes, a multiple of 100(8). A value larger than required may be given --
any excess space is not used -- so _<size_> might as well be
(200000-_<lo#addr_>)_&177700. TKB null-fills the area from the top of your
task code to the next 100-byte boundary, and sets L$BHGV (see below) to this
value.
.p-14,1,7
_<break_>	This argument to the STACK= option notionally gives the stack
pointer address, but, in fact, sets the breakpoint between absolute (assembler
_.ASECT or ABS _.PSECT) and relocatable (default REL _.PSECT) code.
Programs may be written in either or both (any modules loaded from SYSLIB will
be relocatable). The value of _<break_> should be computed, in octal, as:
.p5,1,5
_<break_> = highest absolute address - _<lo addr_>
.b1
and then divided by 2 and converted to decimal to give a "stack size" in
words.
.p0
If there is no absolute code, then _<break_> is 0, and _<lo addr_> marks the
base address of the task. Note that TKB will fail if _<break_> and
_<lo addr_> are both 0.
.p-14
_<name_>	is a program name -- 1-6 Radix-50 characters.
.lm-14.P0
A filetype of _.SYS is used instead of TKB's default _.TSK to indicate that the
task is not runnable under RSX-11M.
.p0
The above TKB options set five words in the first ("header") block of the _.SYS
file, which are used by _HEX for task image loading (_HEX ignores all other
header block entries):
.lm+14.p-14,1,3
Bytes#0-3	symbolic offset L$BTSK, contain the radix-50 code for the
first six letters of the task name, as set by the TASK= option.
.p-14
Bytes#10-11	symbolic offset L$BSA, contain _<lo addr_>.
.p-14,1,3
Bytes#12-13	symbolic offset L$BHGV, contain the highest address to load,
rounded to a 100(8) byte boundary.
.p-14
Bytes#350-51##offset L$BXFR, contain the transfer address, 000001 if none.
.p-14,1,4
Bytes#356-57##offset L$BHRB, contain the number of header records. Currently,
this is always 2, i.e_. there is one additional header block, ignored by _HEX,
before the data begins in block 3.
.lm-14.p0
_HEX writes a header block containing similar information, but relaxes the
restriction that the load area must be between addresses on 100(8) byte
boundaries, and does not write the unused block before the task data, so L$BHRB
is set to 1. Unlike the RSX-11M system, _HEX does not require the task
file to be contiguous, and does attempt to write it so.
.p0
The following is an annotated octal word DMP showing the relevant locations in
a task file:
.b1.tp7.lm+5.nf.ts21
	 Virtual block 0,000001 - Size 512. bytes
.b1
000000    063337 027221 000000 000000 010022 010064 000000 000000
          L$BTSK (PROGRA)             L$BSA  L$BHGV
.b1
000340    000000 000000 000000 000000 011064 000000 000000 000001
                                      L$BXFR               L$BHRB
.b1.tp5
	 Virtual block 0,000002 - Size 512. bytes
.b1
000000    001001 002003 003005 004007 005011 006013 007015 010017
000020    011021 012023 013025 014027 015031 016033 017035 020037
000040    021041 000043
.f.lm-5
.AX COMMAND SYNTAX SUMMARY
.T HEX FILE EDITOR
.ST Command Syntax Summary
.x Command summary
.NF.ts27
AND [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] WITH pp
APPEND [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [PLUS/MINUS cccc]
	[PARTIAL] [WIDTH ww/wwww] FILE filespec
COMPARE [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [PLUS/MINUS cccc]
	[PARTIAL] [WIDTH ww/wwww] FILE filespec/WITH dddd
COMPLEMENT [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv]
COPY [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] TO cccc [REPEAT cccc]
CRC [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [TO _*_*_*_*]
CSUM [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv]
DECREMENT [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [BY pp]
DISPLAY [ASCII] [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [FILE filespec]
DIVIDE [SIGNED] [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] BY pp
ECHO
EDIT aaaa [STEP ss]
EXIT
FILL [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] WITH ww
FORMAT [f [char/SMS]]
HELP [command]
INCREMENT [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [BY pp]
IDENT
INIT [vv]
MOVE BYTE FROM _*_*_*_* TO _*_*_*_*
MOVE WORD FROM _*_*_*_* TO _*_*_*_*
MULTIPLY [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] BY pp
NAME [nnnnnnnn]
NEGATE [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv]
NOECHO
OFFSET [aaaa]
OR [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] WITH pp
REMAINDER [SIGNED] [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] BY pp
REVERSE [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv]
ROTATE LEFT/RIGHT [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] BY pp
READ [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [PLUS/MINUS cccc]
	[PARTIAL] FILE filespec
SEARCH [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] FOR [NOT] pp/qqqq
SHIFT LEFT/RIGHT [SIGNED] [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] BY pp
SUM [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [TO _*_*_*_*]
TRANSFER [aaaa]
USE vv OF ww FOR READ
WRITE [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] [PLUS/MINUS cccc]
	[PARTIAL] [WIDTH ww/wwww] FILE filespec
XOR [ODD/EVEN] FROM aaaa THRU bbbb [STEP vv] WITH pp
.TP5
_; comment
_* comment
_. [CLI command]
$ [CLI command]
? [_HEX command] = HELP
ctrl/Z = EXIT
.b1.TP3
where:
.lm+10.p-10.ts10,20,25.f
aaaa	or similar represents a 4, 6, or 8-digit hex number.
.p-10,1,3
vv	or similar represents a hex byte value with no of digits = no of chars.
.p-10,1,10.nf
pp	is a 2-digit hex number or:
.x Character specifier
.lm+5
_^c	control codes, 00-1F, shown as _^@, _^A, _^B, ...#_^__
'c	printing characters, codes 20-7E, with parity bit set
		-- 'space to '~
_^_#	the parity-clear delete character, code 7F
~c	control codes with parity bit set -- 80-9F, ~@ ...#~__
-c	printing characters with parity bit set, --
		A0-FE, -#, -!, ...#-~
_#_#	the parity-set delete character, code FF
.lm-5.f.p-8
_*_*_*_*	is either a 4-digit hex number or a pseudo-register in form %vv.
.p-10
nnnnnnnn	is a 1-8 character program name.
.p-10,1,4
f	is an object file format type, one of:
.c;INTEL MOTOROLA ROCKWELL RCA TEKHEX EXTENDED TEXAS MOSTEK WHITESMITHS
.c;RIM BIN HEX OCTAL TCI FAIRCHILD SIRA OBJECT ABSOLUTE TASK
.p-10
char	is an optional data separator character for HEX or OCTAL.
.lm-10.b1
Uppercase words are required keywords.
.b1
Structures in brackets ([...]) show optional parameters.
.B1
The following control keys may be used
during terminal output from COMPARE, DISPLAY and SEARCH commands:
.nf.tp5
ctrl/C	aborts command.
ctrl/O	suppresses output until next ctrl/O or output complete.
ctrl/S	suspends output until ctrl/Q.
ctrl/Q	resumes output until ctrl/S.
.f
.;DSR.IF INSTALL
.;S14.IF OPTION 
.ax INSTALLATION NOTES
.T HEX FILE EDITOR
.ST Installation Notes
.;BON^=
.HL1 DISTRIBUTION KIT
.;BON\=
.X Distribution kit
NOTE: This chapter is orientated towards building under "real" RSX-11M, with
some indication of changes required to build under the VAX-11 RSX AME.
.p0
To build the non-FCSRES
.X FCSRES
version for systems without either FCS resident library,
TKB @_HEXBLD. To build the FCSRES version, TKB @_HEXRESBLD. To build the
RSX-11M-PLUS supervisor mode FCSFSL version, TKB @_HEXFSLBLD. _HEXDEBBLD.CMD is
intended for use while debugging only. It builds a non-overlaid version
incorporating ODT, and is acceptable to the Fast Task Builder (FTB).
.p0
To assemble and build from source files, type @BUILDHEX.
If you are building HEX on a VMS system, you will need to edit HEXMACS.MAC to
uncomment the definition of symbol VMS before invoking this command file.
.p0
If you need to assemble a module, type @MAC and respond with the module name
that you wish to assemble. This will produce an object file plus a listing
file, including cross-reference, spooled to the printer. If assembling
"manually" undex RSX-11M/M-PLUS, note that system definitions file
LB:[11,10]RSXMC.MAC and also HEXMACS.MAC should be used as a prefixes to all
source files, to set up hardware conditionals and define some common macros,
and that READ and WRITE require the system macro library LB:[1,1]EXEMC.MLB. For
use under VAX/VMS, these prefix files are not required as all necessary
definitions are made in HEXMACS.MAC once the VMS symbol is set.
.p0
Test file HEXTEST.CMD may be used to exercise most of the functions of the
installed task, by invoking it as:
.ts30.nf.p5
_>_HEX#@HEXTEST	!#under RSX-11M/M-PLUS
.i5
$#_HEX#@HEXTEST.COM	!#under VAX/VMS
.f.b1
which assembles a MACRO-11 file, HEXTEST.MAC, containing just a count
pattern, and reads and writes this in the various file formats. It contains a
number of embedded CLI commands in DCL format at the start. These should be
changed to MCR format if testing from MCR, or executed manually if built on a
system without parent/offspring tasking. HEXTEST.CMD generates HEXTEST.OBJ, and
a number of TEMP._* files, which should be deleted afterwards.
.p0
_HEX.RNO is this manual in a form suitable for input to the basic DECUS library
version of Runoff (M02). It may be edited fairly easily to work with the RSX
SIG's Runoff version S1.4 (submitted by Charles Spalding), the VAX/VMS Digital
Standard Runoff, or Bonner Lab Runoff. See the comments at the top of the file
for information on modifications for these versions.
.p0
_HEX.HLP is a help file for _HEX and all subcommands. If it is to be read by
the _HEX HELP command, or the system HELP utility, it must be made accessible
to HELP, e.g_. by including it in LB:[1,2]DCL.HLP etc_. for RSX-11M/M-PLUS, or
SYS$LIBRARY:HELPLIB.HLB for VAX/VMS. The Runoff source of _HEX.HLP is in
HEX.RNH, and (given a Runoff version which supports conditionals) is
conditionalised to produce either a HELP file, or an abbreviated "pocket
reference" manual. See the start of the file for instructions.
.;BON^=
.HL1 MODIFICATIONS AND EXTENSIONS
.;BON\=
You may wish to change some of the definitions in files HEXMACS.MAC and HEX.MAC
to customise the assembler for local conditions:
.p0
In HEXMACS.MAC, define, or leave undefined, the following symbols:
.lm+8.ts8.p-8,1,5
R$$EIS	define if the target processor has the extended instruction set (EIS).
If this symbol is left undefined, MUL, DIV, and ASH will be replaced by
appropriate non-EIS code. XOR and SOB will also be replaced unless L$$SI1 is
defined.
.p-8,1,6
M$$EIS	has the same function as R$$EIS, because early RSX-11M system releases
used it instead (hence _HEX conditionals always use ^&M\&$$EIS). Defining
either or both of M$$EIS and R$$EIS will select EIS code. N.B_. _HEX has been
tested with them undefined, but ^&not\& on a non-EIS machine -- there may still
be some EIS instructions lurking unnoticed somewhere!
.p-8,1,4
L$$SI1	define if the target processor is an LSI-11 (any model), indicating that
SOB and XOR instructions are available, and need not be simulated if R$$EIS
is undefined. L$$SI1 is ignored if R$$EIS is defined.
.COMMENT Don't try defining R$$T11 -- this version is barely started.
.;.p-8,1,4
.;R$$T11	This symbol should be defined if code is to be assembled for an RT-11
.;system. Leave it undefined for RSX-11M/M-PLUS.
.p-8,1,5
R$$MPL	define this symbol if the target system is RSX-11M-^&PLUS\&. This is
necessary because not all of the x$$xxx symbols that really should be defined
in M+'s RSXMC.MAC are actually defined (presumably because the facilities are
always in M+). HEXMACS.MAC caters for these omissions.
.p-8,1,8
.;SIR.MX Parent/offspring tasking
.X Parent/offspring tasking
P$$OFF	Define this symbol if the target system supports parent/offspring
tasking (the SPWN$ directive), allowing _HEX to spawn HELP for its own HELP
command, support the CLI command, and return exit status.
.x Exit status
If this symbol is left undefined (precede P$$OFF by a semicolon) _HEX's HELP is
limited to an internally stored list of command syntaxes, the CLI command is
not available, and _HEX always returns an exit status of 1 (success), unless it
is aborted by a CLI command.
.p-8,1,5
S$$TOP	define this symbol if the system supports stop directives (STOP$).
.;SIR.mx Stop/pause directive
.x Stop/pause directive
If available, _HEX will stop while waiting for a spawned task (CLI or HELP
command) to complete. If S$$TOP is not defined, _HEX will issue a wait for
directive instead.
.p-8,1,3
A$$CLI	define this symbol if the target system has alternative command
line interpreters.
.P-8,1,4
T$$RPR	define this symbol if the terminal driver on the target system
supports read-after-prompt. If it does not, EDIT will use separate read and
write QIOs to prompt for and fetch replacement data.
.p-8,1,3
TCI	define if support for TCI format is required. If undefined, the code
for this is not included, and any attempt to use it will fail.
.p-8
TASK	define if TKB format is required.
.p-8,1,4
TCP	define if Telex Computer Product file defaults (.HEX filetypes, 32
bytes wide) are desired. Do not define TCP if Sira type defaults (.LDA, 16
bytes) are desired.
.p-8
VMS	define if _HEX is to be run under VMS compatibility mode.
.p-8
Also, the following symbol in DISPLAY.MAC may need to be changed:
.p-8,1,7
PRIDIS	define if a FILE option to DISPLAY should be spooled to the printer.
Under systems which support transparent spooling (RSX-11M-PLUS and VAX/VMS),
this should be left undefined, as the user can always specify FILE#LP:.
Since on a system with parent/offspring tasking, a file can always be PRINTed
with a CLI command, it may be possible to disable spooling there also.
.p-8
In HEX.MAC:
.p-8,1,7
TIME	sets the time _HEX should wait for a command to be entered. If no
command is given within this period, it will time out and exit. This prevents
the (large) _HEX task being left running indefinitely from an unattended
terminal. However, if this feature is undesirable, it may be disabled by
defining TIME#=#0. Otherwise, set it to the timeout period in seconds (default
is 120_. sec = 2 min).
.p-8,1,8
And in WRITE.MAC:
.p-8
ABOTEK	should be defined if Tekhex files without a transfer address should end
with an abort block (//#...) instead of a transfer block with address 0000. As
distributed, the latter form is always used, as the Data I/O PROM programmer
does not recognise abort blocks. Re-enable some commented out text in the Runoff
manual if selecting this option.
.tp2.i
ABOEXT	should be defined to give an abort block for Extended Tekhex in the
same circumstances.
.lm-8.p0
Under RSX-11M/M-PLUS, all symbols of the form x$$xxx are automatically set up
(where appropriate) in the RSX-11M system definitions file,
LB:[11,10]RSXMC.MAC, included as a prefix in all command line to assemble _HEX
modules, as:
.p5
_>MAC xxx,xxx=LB:[11,10]RSXMC/PA:1,SY:[g,m]HEXMACS,xxx
.b1
Under VAX/VMS, they are automatically set up when symbol VMS is defined in
HEXMACS.MAC.
.p0
The default filetypes for READ and WRITE can be altered in table FILTPS at the
end of HEX.MAC, and the default record WIDTHs in table TABLE of WRITE.MAC. The
CLI name for spawning can be changed at one of the lines labelled SPWN:# in
HELP.MAC.
.x Command Line Interpreter
The default is CLI.._. on a system with multiple CLIs (symbol A$$CLI defined),
MCR.._. on a system without alternative CLIs, or DCL on VAX/VMS.
.p0
READ and WRITE use lookup tables for handling multiple file formats, with
common code for parsing commands and issuing reports. They are designed so that
other formats can be added fairly easily. When a new format is added, tables in
files HEX.MAC, FORMAT.MAC, READ.MAC, and WRITE.MAC must be modified. Each
format is represented internally by an even positive integer defined in symbols
F.xxx at the end of HEX.MAC (special value -2 is used by DISPLAY). Take care
that all modifications are consistent and do not change the order in tables
from that defined by symbols F.xxx.
.p0
The build command files contain instructions for changing _HEX's task name, if
this is necessary, e.g_. to avoid conflict with the Whitesmiths' utility of
the same name. A suggested alternative name is _H_F_E. HEX.HLP should also be
edited to reflect the new name, and made available to HELP under that name.
.p0
When installing on new releases of RSX-11M, note that there is a potential bug
in handling Whitesmiths' format files: Whitesmiths set the file record size to
.x Whitesmiths' format
1, but write to every byte in the file, whereas since FCS forces records to
start at even addresses, it only writes to every other byte in these
circumstances. Since we are in locate mode, it is quite possible to read from
and write into the gaps in the same way, but this may not work on later
releases of RSX-11M/M-PLUS (OK for M V4.0 and V4.1 and M+ V2.1). The correct
way to handle such files is
(presumably) to use READ$/WRITE$/WAIT$ macro calls, or direct QIOs, but at
present, PUT$S and GET$S are used in common with all other file operations.
.p0
The author, and/or revising authors, would ^&very\& much like to hear from you
if you find _HEX useful, find a bug, have modified it for other formats, added
whistles and bells, etc.. If you report an improvement, it will be likely to
find its way, along with other suggestions, into the next release. If you don't
report things, you do a disservice to others, and maybe yourself, because
you will have to put all your modifications into each "official" release that
comes out.
.;BON^=
.HL1 COMMON SUBROUTINES
.;BON\=
The following are some common subroutines used to fetch and write hexadecimal
values, process offsetting, etc. They are in files HEX.MAC and HEXIO.MAC:
.nf.b1.lm+5.ts16,24,32,40,48,50
#Name	#R1	#R2	#R3	#R4	Function
-----	----	----	----	----	--------
MATCH	#d	#-	#-	#-	Compare input with keyword
.tp2
VALID	#-	addr	adlo	adhi	Convert real addhi/lo
						to unoffsetted addr
.tp2
UNOFFSET	#-	addr	adlo	adhi	Convert unoffsetted addr
						to real addhi/lo
.tp2
FROMTH	FROM	THRU	COUNT	#-	Read FROM/THRU/COUNT
						/LOBOUND/HIBOUND from command
.tp2
PARSE	#d	#-	#-	#-	Fetch filename from command,
						setting ready for open.
GETHX1	digit	#-	#-	#-	Get hex digit to R1 (lo only)
GETHX2	byte	#-	#-	#-	Get hex byte to R1 (lo only)
GETHX4	word	#-	#-	#-	Get 16-bit hex word
GETHX6	loword	hiword	#-	#-	Get 24-bit hex value
GETHX8	loword	hiword	#-	#-	Get 32-bit hex value
GETHXV	loword	hiword	length	#-	Get variable length hex value
.tp2
GETHXL	loword	hiword	#-	#-	Get hex value, length
						according to current mode
.tp2
GETHAS	lobyte	#-	#-	#-	Get 2-digit hex value or ASCII
						character from input
PUTHX1	digit	#-	#-	#-	Write hex digit
PUTHX2	byte	#-	#-	#-	Write 2-digit hex byte
PUTHX4	word	#-	#-	#-	Write 4-digit hex word
PUTHX6	loword	hiword	#-	#-	Write 6-digit hex value
PUTHX8	loword	hiword	#-	#-	Write 8-digit hex value
.tp2
PUTHXL	loword	hiword	#-	#-	Write hex value, length
						according to current mode
.tp5
PUTHXJ	loword	hiword	#-	#-	Ditto, with trailing spaces
PUTHXV	loword	hiword	#-	#-	Write variable-length value
PUTHAS	lobyte	#-	#-	#-	Write 2-digit hex value and
						ASCII character
PUTASCII	lobyte	#-	#-	#-	Show byte as ASCII character
.lm-5.f.p0
All input/output routines update R0 past the string read or written. '-'
indicates that the register is unchanged, 'd' indicates that its value is
destroyed. Byte fetch routines (GETHX1, GETHX2, GETHAS, and GETASCII preserve
the value in the high byte of R1). All routines preserve the contents of R5.
.;DSR.ENDIF INSTALL
.;S14.END OPTION 1
.;BON.IF NEVER
.;DSR.PAGE.ST Index
.;DSR.REQUIRE 'HEX.RNX'
.;BON.ENDIF NEVER
.;S14.DX
.;BON.DX