.;This file is designed to be used as input to Digital Standard Runoff. .;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). .;Include the /VARIANT=INSTALL switch if you want the installation notes .;included in your manual. .;Include the /VARIANT=VMS switch if you want a manual describing HEX running .;on VAX/VMS compatibility mode. .flags bold .layout 2,2 .noautosubtitle .enable toc .xlower .no number .PS64,85.NHY # .B3 .C;^*HEX FILE EDITOR (HEX)\* .b2 .c;DECUS Library Program 11-480 .b12.nf.lm25.i-10 Author: Kevin Angley, Telex Computer Products, Inc. Communications Products Division 3301 Terminal Drive, Raleigh, North Carolina 27604, USA (919) 834-5251 .b2.i-10 Modified by: Chris Doran Sira Ltd. Research _& Development Division South Hill, Chislehurst, Kent BR75EH England 01-467 2636 Telex: 896649 .b2.i-10 Versions combined and updated by: Scott Smith Telex Computer Products, Inc. Raleigh, North Carolina 27604, USA .b2.i-10 Version: 18-APR-84 .f .PS70,84 .ch INTRODUCTION .number page .lm 8 .RM 77 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 call "hex" files) are, in essence, "task images" of software to run in microprocessor-based systems. Detailed description of acceptable formats are given in Appendix A. .P0 The HEX command contains the following data structures which are manipulated by user commands: .lm26.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.38) .p Program name#####A 0-8 character program name can be read, modified, and written by those formats that support it. (Section 2.5.23) .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. .ps 64 .lm8 .ch OPERATING INSTRUCTIONS .T HEX FILE EDITOR .st Operating Instructions .lm 8 .RM 77 .HL1 HOW TO INVOKE HEX .b1 .x Invoking HEX HEX can be invoked in two ways: .LIST 1 .LE;Interactive mode .B1.LM+5.NF >HEX###########Type HEX in response to the CLI prompt. 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+20.i-15 >HEX#@filespec#where filespec is the file specification of an indirect command file containing a list of HEX commands. .x Indirect command file .x Command file .lm-20.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. .end list 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 .tp 4 .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). .tp 5 .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.26 and notes on using it in Section 2.9). .x OFFSET .tp 3 .le;READ the object file(s) into the virtual memory (see the READ command in Section 2.5.31). .tp 3 .le;Optionally, you may manipulate or examine the contents of virtual memory. .tp 3 .le;Finally, WRITE selected sections of virtual memory out to create new object files. .end list 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: .lm31.p-12.ts23 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. .lm8.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. .hl1 COMMAND DESCRIPTIONS .b1 .; .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 .tp 5 .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. .X aaaa .tp 3 .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). .X vvvv .tp 4 .le;pp indicates a byte value which may be entered either as a 2-digit hex .X pp number, or a character specification in one of the following forms (where c indicates a printing character and ^,',~,- are literal characters):- .X Character specification .lm+3.ts20,25.b1.nf.tp7 .rm 83 _^c###control codes, 00-1F, shown as _^@, _^A, _^B, ...#_^__ 'c###printing characters, codes 20-7E, with parity bit set -- ##########'space to '~. (Some control codes are also accepted.) _^_####the parity-clear delete character, code 7F ~c###control codes with parity bit set -- 80-9F, ~@ ...#~__ -c###printing characters with parity bit set, -- ###########codes A0-FE, -#, -!, ...#-~ ~_####the parity-set delete character, code FF .rm 77 .lm-3.f .tp 6 .le;qqqq indicates a 16-bit value which may be entered either as a 4-digit .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. .tp 2 .le;nnnnnnnn or mmmmmmmm indicates a 1-8 character program name. .x Program name .tp 3 .le;_*_*_*_* represents an entity which may either be a four-digit address or .x _*_*_*_* a pseudo-register, written as %xx. .x Pseudo-register .le;Uppercase words are required keywords. .X Keyword .tp 3 .le;Structures in braces ({...}) show an optional parameter. The braces are ^*not\* part of the syntax. .tp 3 .le;All numbers in this manual (unless stated otherwise) and all input/output of the HEX utility are hexadecimal. .end list 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 specification. Thus the following are valid FILL commands:- .LM13.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) .lm8.f .hl1 COMMAND SUMMARY .b1 .X Command summary The following commands are available: .b1.nf.lm13.ts17 .RM 85 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. 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. READ########read in an object file. 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. 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). _;###########displayable comment (used in indirect command files). _.##########issue system (Command Line Interpreter) command. ?###########request on-line help (equivalent to HELP). ctrl/Z######exit. .lm8.f .RM 77 .HL1 RANGE SPECIFICATION .b1 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: .lm13.b1.nf.tp4 READ FILE TEST DISPLAY FROM LOW THRU HIGH FILE TEST1 SUM FROM 0000 THRU HIGH CRC FROM LOW THRU 7FFF .lm8.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/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 likely 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. .PAGE COMPARE, READ, WRITE, and APPEND have three optional parameters which must follow the range specification: .lm28.ts20.p-15,1,4 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-15,1,3 MINUS dddd#####specifies a hex value to be subtracted from each address in the file. .x MINUS .p-15,1,3 PARTIAL########indicates that the file does not or should not contain a trailer record. .lm8.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. .HL2 ADDRESSES ON 12-BIT PROCESSORS 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. .hl1 DETAILED DESCRIPTIONS OF COMMANDS .b1 .hl2 AND .X AND .I5 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. .hl2 APPEND .X APPEND .I5 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. .hl2 COMPARE .i5 COMPARE { FROM aaaa THRU bbbb } FILE filespec .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 .hl2 COMPLEMENT .I5 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. .hl2 COPY .i5 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: .lm23.nf 4000 to 0000 4002 to 0001 ####... 5FFE to 0FFF .lm8.f.p0 If the REPEAT option is given, vvvv contiguous copies of the source area are made. .hl2 CRC .i5 CRC FROM aaaa THRU bbbb { TO _*_*_*_* } .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 a four-byte 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. .hl2 CSUM .i5 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 form: .lm23.b1.nf bbbb+1 = aaaa lo######bbbb+2 = aaaa hi bbbb+3 = sum lo######bbbb+4 = sum hi .f.LM8.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. .hl2 DECREMENT .I5 DECREMENT FROM aaaa THRU bbbb { BY pp } .X DECREMENT .B This command subtracts pp (default 01) from each byte in the given range. .hl2 DISPLAY .i5 DISPLAY { ASCII } FROM aaaa THRU bbbb { FILE filespec } .X DISPLAY .b where filespec is a file specification (see Section 2.7). .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). .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 specification .X Character specification format shown in Section 2.2, except that the apostrophe before parity-clear printing characters is omitted. .hl2 DIVIDE .I5 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. .hl2 ECHO .i5 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.25). The default is to echo all commands read. .tp9.hl2 EDIT .i5 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=pp- .b1 where aaaa is the current address being edited, vv is its contents in hex, and pp shows the ASCII or control character in the same way as DISPLAY. HEX then waits for a reply in one of the following forms ( and denote pressing the RETURN or ESCAPE keys .TP 20 respectively):- .lm23.ts15.p-10,1 pp to replace the contents of the location being edited and open the next ww'th location for editing. .i to leave the location as it is and open the next ww'th location. .i pp_^ to replace the contents of the location being edited and open ^*previous\* ww'th location for editing. .i _^ to leave the location as it is and open the previous ww'th location. .i pp to replace the contents of the open location and then return to HEX command mode. .i to leave the location as is and return to HEX command mode. .lm8.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 specification as shown in Section 2.2. .x Character specification .hl2 EXIT .i5 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. .hl2 FILL .i5 FILL FROM aaaa THRU bbbb WITH pp .X FILL .b Every location from aaaa to bbbb is set to byte value pp. .hl2 FORMAT .i5 FORMAT { type { char}} .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, .TP 23 .x READ .x COMPARE .x WRITE .x APPEND COMPARE, WRITE, and APPEND commands (and default WIDTH for WRITE and APPEND), as:- .lm16.b1.nf.ts23,37,47 .RM 85 ####type###########WIDTH####filetype####notes -----------#####----------##--------####----- .if TCP INTEL#############32/250######.HEX MOTOROLA##########32/252######.HEX ROCKWELL##########32/252######.HEX RCA###############32/169######.HEX TEKHEX############32/250######.HEX######Tektronix emulators EXTENDED#{TEKHEX}#32/250######.HEX######Ditto TEXAS#############32/200######.OBJ######TI99xx family MOSTEK############32/250######.HEX 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}######1024/16384####.PRM######Data I/O hex-char OCTAL#{char}####1024/16384####.PRM######Data I/O octal-char TCI###############32/253######.HEX .else TCP INTEL#############16/250######.LDA MOTOROLA##########16/252######.LDA ROCKWELL##########16/252######.LDA RCA###############16/169######.LDA TEKHEX############16/250######.LDA######Tektronix emulators EXTENDED#{TEKHEX}#16/250######.LDA######Ditto TEXAS#############16/200######.OBJ######TI99xx family 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}######1024/16384####.PRM######Data I/O hex-char OCTAL#{char}####1024/16384####.PRM######Data I/O octal-char TCI###############16/253######.LDA .endif TCP 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 .RM 77 .lm8.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 but must be specified in hexadecimal. 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 a single character which is to separate data items. Any character may be given, although the programmer only recognises the apostrophe ('), percent (%), and space. If no separator is specified, a default of space will be used. .p0 Appendix A gives full details of the various file formats. .tp 20 .hl2 HELP .i5 HELP { command } .br or###? { command } .b .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.#_* .fn .lm8.rm77 ---------------- .b1 _*#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 _.# command to suspend HEX, and type HELP#HEX#command in this case. .EFN .hl2 IDENT .I5 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). .hl2 INCREMENT .I5 INCREMENT FROM aaaa THRU bbbb { BY pp } .X INCREMENT .B This command adds pp (default 1) to each byte in the given range. .hl2 INIT .i5 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. .tp 7 .p0 Addressing mode, format, and pseudo-registers are unaffected by INIT. .x Addressing mode .x Mode .hl2 MOVE .i5 MOVE BYTE FROM _*_*_*_* TO _*_*_*_* .br or###MOVE WORD FROM _*_*_*_* TO _*_*_*_* .b .X MOVE where _*_*_*_*'s represent either a four-digit 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. .hl2 MULTIPLY .I5 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). .hl2 NAME .i5 NAME { nnnnnnnn } .X 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. .hl2 NEGATE .I5 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. .hl2 NOECHO .i5 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 Asterisk .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: .lm13.b1.nf NOECHO FORMAT WHITESMITHS READ FILE XEQ. FORMAT INTEL WRITE FROM LOW THRU HIGH FILE INTEL EXIT .F.lm8.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. .hl2 OFFSET .i5 OFFSET { aaaa } .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. .hl2 OR .I5 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. .hl2 READ .i5 READ { FROM aaaa THRU bbbb } FILE filespec .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 .hl2 REVERSE .I5 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.: .lm13.nf.b1.tp3 REVERSE FROM 0000 THRU 07FF REVERSE FROM 0800 THRU 0FFF WRITE FROM 0000 THRU 0FFF WIDTH 0800 FILE PROMS .lm8.f .hl2 REMAINDER .I5 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. .hl2 ROTATE .I5 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. .hl2 SEARCH .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 specification (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). .hl2 SHIFT .I5 SHIFT LEFT/RIGHT { SIGNED } FROM aaaa THRU bbbb { BY pp } .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. .hl2 SUM .i5 SUM FROM aaaa THRU bbbb { TO _*_*_*_* } .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. .hl2 TRANSFER .i5 TRANSFER { aaaa } .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. .hl2 USE .i5 USE aa OF bb FOR READ .X USE .X READ .b This command sets up HEX to handle files in which the basic addressable unit is wider than eight bits. The command instructs READ 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 bb 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). aa specifies which of the bb bit groups is to be input as the value of a location. .hl2 WRITE .i5 WRITE FROM aaaa THRU bbbb { WIDTH vv/vvvv } FILE filespec .X WRITE .X FILE .b creates an object file defining locations aaaa to bbbb in the currently defined format. .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 PROM programmer format .x Octal 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. .hl2 XOR .I5 XOR FROM aaaa THRU bbbb WITH pp .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. not displayed, but those beginning with asterisks are shown at the terminal. .hl2 _.#(CLI command) .i5 _.#{ 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 _.# command, in either 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. .if VMS .p0 If HEX is running in compatability mode on a VAX/VMS .x VAX/VMS system, then ^*only\* the first form of the command is available. HEX on a VMS system will make no attempt to translate commands before passing them to the CLI (i.e. DCL user-defined commands implemented by symbol substitution will not be understood). HEX under VMS does not release control of the issuing terminal, therefore any command which requires an interactive exchange will fail. .endif VMS .hl1 COMMAND LINE PROCESSING .b1 .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 Internally, since 4-digit addresses are required, 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. .hl1 FILE SPECIFICATION .b1 .X File specification A file specification takes the standard RSX-11M form: .b1.LM13 dd00:[ggg,mmm]name.ext;v .b1.nf.ts13.i-5 where dd00: is a device name, default SY00:, ggg,mmm is a uic, default current UIC, 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). .lm8.f.p0 TI:# is a file specification representing the terminal at which HEX is running. .hl1 PSEUDO-REGISTERS .b1 .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. .hl1 OFFSET .b1 .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 .X Addressing 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 .hl1 EXAMPLES .b1 .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: .lm13.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 .LM8.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), and .i 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. .end list The following commands will do the job: .B1.LM13.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 .LM8.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:- .lm13.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 .LM8.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 .lm 8 .RM 77 Note: References to READ below usually apply also to COMPARE, and 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. .tp4.lm13.p-5,2 Address:#aaaa###Memory:#bb=pp#####File:#cc=pp .br .X COMPARE This is an informative 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,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,7 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 ot 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. .if VMS .p-5,1,5 Command not supported by VMS .br .X VAX/VMS The command is not implemented under VAX/VMS compatibility mode. .endif VMS .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 specification from a command line or object file. .p-5,1,4 CRC:#xxxx .br .X CRC This is an informative 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,6 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 informative 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 informative 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,5 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. .lm8.b1.nf.tp9 Low:#xxxx High:#xxxx Count:#xxxx Sum:#xxxx .lm13.f .X READ .X WRITE This informative 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,5 xxxx matches found .br .i-5 xxxx mis-matches found .br This is an informative 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,4 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,6 Name:#nnnnnnnn .br is an informative 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 informative 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 .br This message appears when the _.# (CLI) command is given without an .x CLI 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 .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 informative message in response to a SUM command. The value is the 16-bit byte-wise sum over the specified range. .p-5,1,4 Trailer record ignored .br During a READ or COMPARE operation described as PARTIAL, a trailer record was encountered and ignored. The READ/COMPARE operation terminates at this point. .p-5,1,4 Transfer:#xxxx .br .X TRANSFER This is an informative 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 informative 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,4 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. .test page 18 .p-5,1,14.nf any message which looks like: .b1.lm13 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.lm8.p0 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 .lm 8 .RM 77 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 DEC MACRO assembler and TKB task-builder, by SAL cross-assemblers with the special Sira binary object file option, and by the Whitesmiths' linker. .end list 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.lm13.literal Name: PROGRAM Transfer: 1234 Addr 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F ---- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 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 .el.lm8 .hl1 INTEL FILE FORMAT .b1 .x Intel format Standard Intel hexadecimal object format is: .p12 :bbaaaattdddd ... ddcc .BR where: .lm20.ts12.p-8 : is the start of block symbol. .i bb is two hex digits giving the number of data bytes in the block. .tp2.i aaaa is four hex digits defining the load address of the first byte of data. .TP4.i tt is two hex digits defining the block type: .lm+5.nf 00 - defines a data block, 01 - defines end of file, 02 - defines auto start. .f.lm-5.i dd are pairs of hex digits defining the data to be stored. .TP4.i cc is two hex ASCII characters giving the checksum of the block -- the two's complement of the sum of all the bytes from the byte count to the last data byte, so that the total of all the bytes except the :bb is zero. .lm8.s1 A file will consist of a number of blocks, terminating with a block in which tt is non zero or bb is equal to zero. The address of such a block is taken as the start address of the program (0000 if none). Note that types 01 and 02 are not part of the Intel standard, however, HEX always generates one or the other when it WRITEs a file. It also recognises a block with bb=00, i.e.# no data, as a trailer record. .p0 There is no facility to define the program name, which is therefore always unchanged when an Intel format object file is read. .p0 Any record not containing a colon is treated as a comment. Characters or spaces preceding a colon in a record are treated as a comment. .p0,1,6 Example: .lm13.literal :0E1012000102030405060708090A0B0C0D0E67 :151020000F101112131415161718191A1B1C1D1E1F20212223AE :00123402B8 .el.lm8 .HL1 MOTOROLA FILE FORMAT .b1 .x Motorola format Motorola format object file consist of a number of blocks in the following format: .p12 Stbbaaaadddd#...#ddcc .lm20.ts12.i-12 where: .p-8,1,4 St is two ASCII characters defining the block type: S0 denotes a file header, S1 and S2 define data blocks, and S8 and S9 define end of file blocks. .tp2.i bb is two hex digits 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 defining 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 pairs of hex digits defining the data to be stored. .tp4.i cc is two hex ASCII characters defining the checksum for the block. 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. .lm8.p0 A complete object file commences with an S0 block 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 start address of the program. .p0 As for Intel, 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: .lm13.literal S00B000050524F4752414D20BC S11110120102030405060708090A0B0C0D0E63 S11810200F101112131415161718191A1B1C1D1E1F20212223AA S9031234B6 .el.lm8 .hl1 ROCKWELL FILE FORMAT .b1 .x Rockwell format Rockwell format files consist of a number of blocks in the following format, compatible with the KIM/TIM/MDT format, also used by the Commodore 'PET' assembler: .p12 ;bbaaaadd#...#ddcccc .tp4.lm20.ts12.i-12 where: .p-8,1,3 bb is two hex digits giving the number of data bytes, dd#...#dd, (pairs of hex ASCII characters) in the block. .tp2.i aaaa is a four hexadecimal number giving the load address of the first byte, high byte first. .i dd are two-digit hexadecimal numbers defining the data to be stored. .tp3.i cccc is four-digit hexadecimal the checksum for the block. This is the sum of all the bytes from the byte count to the last data byte inclusive (bb+aa+aa+dd+#...#dd). .lm8.p0,1,4 The file ends with a block having a byte count of 00, and an "address" which is the number of blocks in the file. There is no way of giving a program name or start address. .p0,1,6 Example: .lm13.literal ;0E10120102030405060708090A0B0C0D0E0099 ;1510200F101112131415161718191A1B1C1D1E1F202122230252 ;0000020002 .el.lm8 .hl1 RCA FILE FORMAT .b1 .x RCA format The RCA manuals do not define an object file format. HEX therefore uses that of the manual loader of the single-board evaluation kit monitor, as follows: .b.nf.lm20 aaaa#dd#dd#...#dd#; .ts12.i-12 where: .p-8 aaaa are 4 hex ASCII characters to define the load address. .i dd are 2 hex ASCII characters to define the contents of each byte. .lm8.s1.f The file may consist of several blocks. There is no facility to include a program name or start address. .p0,1,6 Example: .lm13.literal 1012 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 ; .el.lm8 .hl1 TEKHEX FILE FORMAT .b1 .x Tekhex format .tp6 Standard Tektronix ("TekHex") format, used by the 8000 series emulators, is: .p12.ts12 /aaaabbhhdddddd ... ddcc .tp6.lm20.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 two hex digits giving the number of data bytes in the block. .tp3.i hh is two hex digits giving the 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 pairs of hex digits defining the data bytes. .tp2.i cc is two hex ASCII characters defining the checksum of the data bytes, being the sum of the values of the preceding 2_*bb digits. .lm8.s1 A file may consist of a number of blocks and is terminated by a block containing no data (hence bb = 00), and an address defining the start address of the program, as: .b1.tp3.lm13.literal /10120E120102030405060708090A0B0C0D0E69 /102015090F101112131415161718191A1B1C1D1E1F20212223A5 /1234000A .el.lm8.p0 If there is no transfer address, the terminator block is replaced by an "abort" block, beginning with two slashes and containing a message, as: .p5 // No transfer address .hl1 EXTENDED TEKHEX FORMAT .b1 .X Extended TekHex format .tp6 Extended TekHex format is used by Tektronix 8550 series emulators. The data and trailer block format is: .p12.ts12 %bbtccna...adddddd#...#dd .tp6.lm20.i-12 where: .p-8,1,3 bb is two hex digits giving the number of characters in the block, excluding the starting percent (%). .tp2.i t is the block type: 3 is a symbol definition block (header), 6 is a data block, and 8 a trailer. .tp2.i cc is the 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 pairs of hex digits defining the data bytes. .p-12 The header block ("symbol block") 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. .lm8.p0 HEX writes a full header block as above, but ignores the low address and count value. Tektronix emulators may write other information into "symbol blocks", but this is also ignored by HEX. .p0 A file starts with a header block giving the program name, followed by a number of data blocks, and terminated by a type 8 trailer block containing an address defining the start address of the program, as: .b1.tp4.lm13.literal %1A3BF7PROGRAM0810120000223 %2667F410120102030405060708090A0B0C0D0E %346B9410200F101112131415161718191A1B1C1D1E1F20212223 %0A82041234 .el.lm8.p0 If there is no transfer address, the terminator block is replaced by an "abort" block, in the same form as standard TekHex. .p0 Checksums are computed by summing the characters in each block, assigning them non-ASCII codes:- .lm23.ts30.nf.P-4,1,8 Characters####Values (decimal) .I-4 ----------####---------------- 0-9 #0-9 A-Z 10-35 ##$ ##36 ##_. ##38 ##__ ##39 a-z 40-65 .LM8.F.p0 All other characters are illegal and will result in a fatal error if encountered in a or WRITE operation. .hl1 TEXAS FILE FORMAT .b1 .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: .lm13.b1.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 block. .lm8.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 block may appear anywhere in the file HEX places it at the end, followed by a trailer block, 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: .lm13.literal 00000PROGRAM 7FCA1F 91012B0102B0304B0506B0708B090AB0B0CB0D0E7F732F 91020B0F10B1112B1314B1516B1718B191AB1B1CB1D1E7F60CF 91030B1F20B2122B23007FBA1F 112347FECEF : HEX version 17JAN4 .el.lm8 .HL1 MOSTEK FILE FORMAT .b1 .X Mostek format MOSTEK files have four types of record, with the following general format: .p12.ts12 ttrrrrxx...xxcc .tp6.lm20.i-12 where: .p-8,1,2 tt is the block 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. .i cc is the negative of the sum of all bytes in the block from tt up to the last byte of the record body, so that the sum of all bytes in the block is 00. .p-12 Module header blocks 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. .tp4.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 block is to be repeated. .tp2.i bb is a block count, zero if this is the final inner block, non-zero if there are further nested ones. .tp3.i yy...yy is an inner nested repeat of another block 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. .lm8.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 block has the format: .lm20.b1 F6rrrraaaacc .i-12 where: .p-12,1,3 aaaa is the transfer address. This may be omitted if there isn't one, in which case rrrr is 0001. .lm8.p0 The following example is the standard data, extended to address 104F to show an iterated record of all FFs: .b1.tp6.lm13.literal F000100750524F4752414D1000030000003D91 F2001310120102030405060708090A0B0C0D0E70 F2001510200F101112131415161718191A1B1C1D1E61 F2001510301F20212223FFFFFFFFFFFFFFFFFFFFFF1F F4000A104000100001FFA2 F600051234BF .el.lm8 .hl1 WHITESMITHS' FILE FORMAT .b1 .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.lm13.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 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 blocks of lengths given above: segment 1: text area. segment 2: data area. segment 3: symbol table. segment 4: relocation information. .f.lm8.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 ans 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.lm13.literal 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... .el.lm8 .hl1 PDP-8/IM6100 READ-IN-MODE FORMAT .b1 .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: .lm13.ts21,37.b1.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 .lm8.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, however, they are 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.lm13.ts21.nf.tp6 .rm 83 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) .lm8.f.p0 .rm 77 RIM (and BIN) tapes may be punched by a simple PIP or COPY command to PP:, no special FLX processing is required. .hl1 PDP-8/IM6100 BINARY FORMAT .b1 .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 value > 100) occur only at the start of the records: .b1.lm13.tp3.nf .rm 83 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 .rm 77 .f.lm8 .hl1 HEX PROM PROGRAMMER FILE FORMAT .b1 .x Hex PROM programmer format HEX format handles programs in a form used by several PROM programmers, such as those manufactured by Data#I/O and Stag. The format of the file is: .s1.nf.lm23 $Assss, aaaa-ddxddxddx...xddxddx ... aaaa-ddxddxddx...xddxddx $Scccc, #################### .lm20.tp4.i-12 where: .ts12.f.tp2.p-8,1,3 ctrl/A indicates the start of data. Anything except the "$Scccc," sequence which appears before this is ignored. .tp2.i ssss is four hex digits defining the load address of the first data byte of the file (but see below). .tp2.i aaaa is a 4, 6, or 8-digit hexadecimal address of the actual load address of the first byte of the line. .tp5.i dd are pairs of hex digits defining the data to be stored (a leading zero may be omitted, provided the single digit is immediately preceded by an x separator character). A maximum of 16 dd pairs are always written per line, regardless of WRITE's STEP argument, which sets the PROM size only. .tp6.i x is an "execute" character, signifying that the previous one or two digits are 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, or percent. .tp2.i-8 ctrl/C indicates the end of data. Anything other than "$Scccc," between this code and the next ctrl/B is ignored. .tp2.i-8 cccc is four hex ASCII characters giving 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 blocks 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 block; without these spaces, successive program blocks will overwrite memory from address 0000 upwards. .tp3.i-8 ctrl/Q Certain terminal keyboards (e.g.# the DEC VT100) are locked by the preceding ctrl/S. This character prevents this happening if a PROM file is displayed on such a terminal. .lm8.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): .lm13.literal PROGRAM $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 $S0276, .el.lm8 .hl1 OCTAL PROM PROGRAMMER FILE FORMAT .b1 .x Octal PROM programmer format OCTAL format is similar to HEX except that, as the name implies, numbers are written in octal instead of hexadecimal. Thus and checksum is a 6-digit number, addresses may be up to 11, data bytes are one to three. The following is the above example in octal-percent format: .p0,1,11 Example (octal-apostrophe format): .lm13.literal PROGRAM $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' $S001166, .el.lm8 .HL1 TCI FORMAT .b1 .x TCI format This format consists of records of the form: .p12 @aaaadddd#...#dd .TS12.lm20.i-12 where: .p-8,1,2 @ marks the start of the record -- everything before it is ignored. .tp2.i aaaa is a four-digit hexadecimal load address of the first byte of the data. .i dd are pairs of hex digits defining the data bytes. .lm8.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 program name or start address. .p0,1,5 Example: .lm13.literal @10120102030405060708090A0B0C0D0E @10200F101112131415161718191A1B1C1D1E1F20212223 .el.lm8 .hl1 SIRA BINARY FORMAT .b1 .x Sira binary format Sira binary format takes the following form: .p12 1aatbbdd#...#ddc .lm20.ts12.i-12 where .TP2.p-8,1,3 1 is a binary byte defining the start of block -- 00000001B (ASCII ctrl/A). .tp2.i aa is two binary bytes defining the 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 block type: .lm+5.nf 00000000B - normal data block, 00000001B - end of file block, 00000002B - auto start block. .tp2.f.lm-5.i bb is two binary bytes defining the byte count of the data bytes. The low byte of the byte count is stored 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.lm8 The file may consist of several blocks, finishing with a block containing 1 or 2 in byte 4. .p0 The following is an octal byte DMP of a Sira binary file: .b1.tp5.lm13.nf.ts21 .rm 83 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 .rm 77 .f.lm8 .hl1 DEC OBJECT FORMAT .b1 .x DEC object format This is the output of the RSX-11M MACRO assembler when the _.ENABL#ABS directive, or /EN:ABS command line switch is used. The file consists of binary records taking the form: .p12 aaddd#...#d .lm20.ts12.i-12.tp6 where: .tp2.p-8,1,2 aa is two binary bytes defining the load address of the first byte of the data. The low address byte is stored in the first byte. .i d are one or more data bytes, stored sequentially. .lm8.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.lm13.nf.ts21 .rm 83 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 .rm 77 .f.lm8 .hl1 PDP-11 ABSOLUTE LOADER FORMAT .b1 .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. .p0 Records take the form: .lm20.b1 10bbaabbd#...#dc .ts12.i-12 where: .TP2.p-8,1,2 1 is a binary byte defining the start of block, always 1. .i 0 is a null padding byte. .tp2.f.i bb is two binary bytes giving the total number of bytes in the block, from the 1 up to the last data byte, stored lo byte first. .tp2.i aa is two binary bytes defining the load address of the first byte of the data, stored lo byte first. .i d are single binary bytes of data. .tp2.i c is a binary checksum -- the negative 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.lm8 The file may consist of several blocks, finishing with a block containing only an address, which is even if it is a transfer address, or odd (usually 1) if there is no transfer address. .p0 The following is an octal byte DMP of an absolute binary file: .lm13.nf.ts21.b1.tp5 .rm 83 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 .rm 77 .f.lm8 .hl1 TASK FILE FORMAT .b1 .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 (&n&o&t 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.lm13.b1 USERPROG.SYS/-HD/-MM/-FP/-SE,LP=USERPROG... / UNITS=0 ACTFIL=0 ASG=0 PAR=:: STACK= TASK= // .LM22.f.p-14,1,5.ts14 where: .P-14,1,3 is the lowest memory area to be loaded. It must be given in octal bytes, and a multiple of 100(8). .p-14,1,4 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 unnecessary space is not used. .p 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 should be computed in octal as: .p5,1,5 = highest absolute address - .b1 and then divided by 2 and converted to decimal to give a "stack size" in words. .p-14,1,2 is a six letter program name. .lm8.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 for task image loading: .lm22.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,1,2 Bytes#10-11 symbolic offset L$BSA, contain . .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,1,2 Bytes#350-52##offset L$BXFR, contain the transfer address, 000001 if none. .p-14,1,4 Bytes#356-60##offset L$BHRB, contain the number of header blocks. Currently, this is always 2, i.e.# there is one additional header block, ignored by HEX, before the data begins in block 3. .lm8.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 utilities, HEX does not require an input task file to be contiguous, and does not write one contiguously. .p0 The following is an annotated octal word DMP showing the relevant locations in a task file: .b1.tp8.lm13.nf.ts21 .rm 83 Virtual block 0,000001 - Size 512. bytes .b1 000000 063337 027221 000000 000000 010022 010064 000000 000000 L$BTSK (PROGRA) L$BSA L$BHGV 000020 000000 000000 000000 000000 000000 000000 000000 000000 .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 .rm 77 .f.lm8 .AX COMMAND SYNTAX SUMMARY .x Command summary .NF.ts30 .lm 8 .RM 77 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 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}} 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 READ { ODD/EVEN } FROM aaaa THRU bbbb { STEP vv } { PLUS/MINUS cccc } { PARTIAL } FILE filespec 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 SEARCH { ODD/EVEN } FROM aaaa THRU bbbb { STEP vv } FOR { NOT } pp SEARCH { ODD/EVEN } FROM aaaa THRU bbbb { STEP vv } FOR { NOT } 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 aa OF bb 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 ; comment _* comment _. { CLI command } ? { HEX command } = HELP ctrl/Z = EXIT .b1 where: .lm18.p-10,1,3.ts10,20,25.f aaaa or similar represents a 4, 6, or 8-digit hex number. .p vv or similar represents a hex byte value with no of digits = no of chars. .p-10,1,7.nf pp is a 2-digit hex number or: .X Character specification .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,1,2 _*_*_*_* is either a 4-digit hex number or a pseudo-register in form %vv. .p-10,1,2 nnnnnnnn is a 1-8 character program name. .p-10,1,5 f is an object file format type, one of: .c;INTEL MOTOROLA ROCKWELL RCA TEKHEX EXTENDED TEXAS MOSTEK .c;WHITESMITHS RIM BIN HEX OCTAL TCI SIRA OBJECT ABSOLUTE TASK .p-10,1,2 char is an optional data separator character for HEX or OCTAL. .lm8.b1 Uppercase words are required keywords. .b1 Structures in braces ({...}) show optional parameters. .IF INSTALL .ax INSTALLATION NOTES .T HEX FILE EDITOR .ST Installation Notes .hl1 DISTRIBUTION KIT .b1 .X Distribution kit .lm 8 .RM 77 To build HEX type @BUILDHEX. If you are building HEX on a VMS system, you will need to edit HEXMACS.MAC to uncomment the RSX symbol definitions and system macros before invoking the build 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" on an RSX-11M system, 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. .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.. .p0 Test file HEXTEST.CMD may be used to exercise most of the functions of the installed task, by invoking it as: .p5 >HEX @HEXTEST .b1 which assembles a MACRO-11 file, HEXTEST.MAC, which just contains 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 HEXRNOMAN.RNO is this manual in a form suitable for input to the RSX SIG's RUNOFF version S1.4 (submitted by Charles Spalding), and HEXDSRMAN.RNO is a form suitable for input to DIGITAL Standard Runoff. See the comments at the top of each of these files for information on conditional processing. .hl1 MODIFICATIONS AND EXTENSIONS .b1 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: .lm18.ts10.p-10 M$$EIS define if the target processor has the extended instruction set (EIS). If this symbol is left undefined, MUL, DIV, ASH, XOR, SOB etc.# will be replaced by appropriate non-EIS code. N.B.# HEX has been tested with M$$EIS undefined, but ^*not\* on a non-EIS machine -- there may still be some EIS instructions lurking unnoticed somewhere! .p-10,1,6 .;R$$T11 This symbol should be defined in code is to be assembled for an RT-11 .;system. Leave it undefined for RSX-11M. .;.p-10 .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-10 S$$TOP Define this symbol if the system supports stop directives (STOP$). .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-10 A$$CLI Define this symbol if the target system has alternative command line interpreters. .P-10 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-10 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-10 TASK Define if TKB format is required. .p-10 TCP Define if Telex Computer Product file defaults (.HEX extension, 32 bytes wide) are desired. Do not define TCP if Sira type defaults (.LDA, 16 bytes) are desired. .p-10 VMS Define if HEX is to be run under VMS compatibility mode. .lm8.p0 Also, the following symbol in HEX.MAC may need to be changed: .lm18.p-10 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). .lm8.p0 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 .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), or MCR...# on a system without alternative CLIs. .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 HFE. 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 (OK for V4.0). 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 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.. .hl1 COMMON SUBROUTINES .b1 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.lm13.ts16,24,32,40,48,50 #Name #R1 #R2 #R3 #R4 Function ----- ---- ---- ---- ---- -------- MATCH #d #- #- #- Compare input with keyword VALID #- addr adlo adhi Convert real addhi/lo to unoffsetted addr UNOFFSET #- addr adlo adhi Convert unoffsetted addr to real addhi/lo FROMTH FROM THRU COUNT #- Read FROM/THRU/COUNT /LOBOUND/HIBOUND from command 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 GETHXL loword hiword #- #- Get hex value, length according to current mode 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 PUTHXL loword hiword #- #- Write hex value, length according to current mode 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 .lm8.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. .ENDIF INSTALL .DX