DECSYSTEM-20 Assembly Language Guide
DECSYSTEM-20 Assembly Language Guide
Edited by:
Frank da Cruz
Chris Ryland
Columbia University Center for Computing Activities
New York, New York 10027
3 July 1980
Assembly Language Guide Page 1
Preface
This document is intended to be a comprehensive introduction to assembly
language programming on the DECSYSTEM-20. It consists of excerpts from
various DEC manuals and other documents, with the addition of programming
examples and some original material. Appropriate credit is given in each
chapter or section in which the material is not original.
Chapter 8 attempts to present a programming standard for Macro programs; in a
sense it is the most important chapter because unless a program is clear and
understandable, it will not be adaptable to new circumstances, and its
usefulness and lifetime will be limited.
This is a draft. Various sections still need to be filled in or
refined, and more material added. This will be done from time to
time. Comments are welcome.
Introduction Page 2
1. Introduction
Assembly language is a tool for writing computer programs consisting, at the
source (program text) level, of actual machine instructions. It is sometimes
desirable or necessary to use assembly language for two reasons:
1. Only in assembly language can you write a program that can take
advantage of all the features of a given machine. Higher-level
languages purposely conceal the machine from programmers so that
programs may be transported from one machine to another.
2. You have maximum control over every aspect of the operation of your
program, especially storage allocation and efficiency.
In order to use an assembler, you must first be familiar with the machine's
instruction set. This is described in Chapter 2. You will notice that this
chapter actually describes three different machines: the KA10, the KI10, and
the KL10. You should be aware that DEC-20's are KL10's (2020's are KS10's,
but these are identical to KL10's for all practical purposes).
There are several assemblers suitable for use on the DEC-20. These include
Macro-20 (the standard DEC assembler), Midas (an alternative from MIT), and
Fail (a fast 1-pass block structured assembler from Stanford). Only Macro-20
is supported by DEC, but the other two have certain distinct advantages.
Macro-20 is described in Chapter 3.
Another thing that assembly-language programmers need to know about is monitor
calls. On a timesharing system, such as the DECSYSTEM-20, there are many
things that you cannot do even in assembly language, such as issue
input/output instructions; only the monitor can do such things. You can ask
the monitor to perform services for you by issuing a monitor call (a DEC-20
monitor call is called a 'JSYS' (Jump to SYStem)), which amounts to calling a
subroutine in the monitor. Information about DEC-20 monitor calls is given in
Chapters 4 and 5
There are various aids available to assembly language programmers; these
include libraries of helpful macros and routines (Chapters 6, 7), and
interactive, symbolic debugging facilities (Chapter 10). In addition, there
are chapters on how to write, run, and debug programs on the DECSYSTEM-20 (9),
and some sample programs (11). And, as pointed out in the Preface, a very
important Chapter on programming style and standards (8).
The major intent of this guide is to provide a consolidated resource for those
who wish to write assembly language programs, not assembly language
subroutines to be called from higher-level languages; such subroutines can
only be written with detailed knowledge of the calling conventions and
internal data representations of the given language.
The reader should have some knowledge of programming and some familiarity with
DECSYSTEM-20 commands and procedures.
Introduction Page 3
1.1. Basic Concepts
Before we can proceed with descriptions of the instruction set, assembler, and
monitor calls, some terminology and a few basic concepts of machine
organization must be introduced.
1.1.1. Terminology
Timesharing One way of running a computer. Timesharing allows many users
to use the computer at once, seated at terminals, and to
converse via the terminal with various programs on the
computer.
DECSYSTEM-20 A timesharing computer system, the subject of this manual.
DEC Digital Equipment Corporation. The manufacturer of the
DECSYSTEM-20, and of its predecessors, the PDP-10 and PDP-6.
Operating System A program, or set of programs, that controls the operation of
the computer. On a timesharing computer, the operating system
functions include scheduling among users, allocating resources
to users, controlling devices, and performing various other
services for users that could not be done by the users
themselves.
Tops-20 Timesharing OPerating System-20. This is the name of the
DECSYSTEM-20's operating system.
Monitor One component of Tops-20. It is a program that is always
running, and that performs most operating system functions.
Exec Another component of Tops-20. It is the program by which
users communicate their desires to the monitor, and through
which the monitor communicates to the user.
1.1.2. Machine Organization
The computer consists of various entities. You must be aware of what some of
them are in order to program in assembly language:
Memory This is a device that allows the computer to store and
retrieve a limited amount of data very quickly. It is not
permanent storage. It is often referred to as "core" memory
(it is sometimes made from magnetic cores), to differentiate
it from registers, disks, and other kinds of memory. Whether
it's made from cores or not, it is solid-state memory, i.e. it
has no moving parts.
Register (Also called an Accumulator) This is a special kind of solid-
state memory that is much faster than ordinary memory, and
that allows operations such as arithmetic to be performed on
data that is stored there. The DECSYSTEM-20 has 16 registers.
Disk A kind of mechanical memory that is much slower than registers
Introduction Page 4
or core memory, but which allows long-term storage of data in
files whose names are kept in directories. Disks can hold
much more data than core memory.
CPU Central Processing Unit. This is the part of the computer
that does most of the work, and where the major "intelligence"
is to be found. It consists of the registers and the logic to
move data to and from the registers, as well as logic to
operate on the data in the registers (e.g. to do arithmetic).
Instruction An instruction is a code to activate some function of the CPU.
Typically, it specifies what operation to perform, what data
to operate on, and where to put the result. Typical
operations include arithmetic (add, subtract, etc.), transfer
of control, comparison of numbers, etc. Assembly language
programs consist of a sequence of instructions. When the
program is being executed, the instructions are kept in
memory.
Address An address is a number that expresses the location of a
quantity (instruction or data) in memory. Used as a verb,
"address" means to "refer to".
Bit (BInary Digit) The smallest unit of storage in memory. A bit
is a quantity whose value can be 0 or 1.
Word The major unit of storage in memory. In the DECSYSTEM-20,
each word consists of 36 bits, and has its own address. You
can address 262144 words of memory on the DECSYSTEM-20.
Byte An intermediate unit of storage; any sequence of bits within a
word. A byte is often the unit of storage for a character.
Input/Output This is the act of transferring data between memory and some
device, typically a disk or a terminal.
1.1.3. Instructions and Addressing Modes
[ this is mostly taken care of in Ch. 2 ]
1.1.4. Internal Representation of Numbers
1.1.4.1. Binary Numbers
[ to be filled in ]
Introduction Page 5
1.1.4.2. Two's Complement Representation
[ to be filled in ]
1.1.4.3. Integers
[ to be filed in ]
1.1.4.4. Floating Point Numbers
[ to be filled in ]
1.1.5. Arithmetic
[ to be filled in ]
1.1.5.1. Integer Arithmetic
[ to be filled in ]
1.1.5.2. Floating Point Arithmetic
[ to be filled in ]
1.1.6. Logical Operations
[ to be filled in ]
1.1.7. Character String Manipulation
[ to be filled in ]
1.1.8. Elementary Data Structures
1.1.8.1. Tables (Arrays) and Indexing
[ to be filled in ]
Introduction Page 6
1.1.8.2. Stacks
[ to be filled in ]
Instruction Set Page 7
2. The PDP-10/DECSYSTEM-20 Instruction Set
2.1. Introduction
This chapter was written by Ralph E. Gorin at Stanford University
and modified slightly at Columbia.
The PDP-10 is a general purpose stored program computer. There are four
different processors (computers) in the PDP-10 family: the PDP-6, the KA10,
the KI10 and the KL10. The newest of these is the KL10 which is the central
processor in various DECsystem-10 and DECSYSTEM-20 configurations. (The KS10,
found only in the DECSYSTEM-2020, is nearly identical to the KL10.) In
general, we shall discuss the KL10 processor.
There are three principal aspects of assembly language programming: the
machine instructions, the assembler, and the operating system. The machine
instructions are the primitive operations with which we write programs.
Learning the instruction set means learning what operations are performed by
each instruction. Programming is the art or science of combining these
operations to accomplish some particular task.
The machine instructions, like everything else in a computer, are in binary.
The assembler is a program that translates the mnemonic names by which we
refer to instructons into the binary form that the computer recognizes. The
assembler also does a variety of other chores that are essentially
bookkeeping.
The operating system, or "monitor", is a special program that handles all
input and output and which schedules among user programs. For its own
protection and the protection of other users the operating system places
various restrictions on user programs. User mode programs are resticted to
memory assigned to them by the operating system; they may not perform any
machine input-output instructions, nor can they perform several other
restricted operations (e.g., HALT instruction). To facilitate user
input-output and core allocation the operating system provides various monitor
calls ( or JSYS operations) by which a user program can communicate its wishes
to the system. Essentially all programs except the operating system itself
are run as user mode programs. Editors, assemblers, compilers, utilities, and
programs that you write yourself are all user mode programs.
The PDP-10 is a word oriented machine. Words contain 36 data bits, numbered
(left to right) 0 to 35. Every machine instruction is one word. There are
two formats for machine instructions.
Most instructions have the format:
Bit 000000000 0111 1 1111 112222222222333333
Position 012345678 9012 3 4567 890123456789012345
________________________________________
| | | | | |
| OP | AC |I| X | Y |
|_________|____|_|____|__________________|
In the diagram the field names are:
Instruction Set Page 8
- OP = operation code
- AC = accumulator field
- I = indirect bit
- X = index field
- Y = address field
Some example intructions are:
move 1, @100 ; MOVE is the OP. AC is 1.
; @ sets the I bit.
; X is zero, Y is 100.
hrrz 17, 1(3) ; HRRZ is the OP. AC is 17,
; Y = 1, X = 3, I = 0
sos foo ; SOS is OP, FOO is symbolic
; for the Y field. AC, X, I
; are 0.
All instructions without exception calculate an "effective address". The
effective address may itself be used as data or it may be used to address the
data or result word for a particular instruction. The effective address
computation is described by the following program. MA means memory address.
means program counter. C(MA) means contents of the word addressed by MA.
Effective Address Calculation:
IFETCH: MA := PC
OP := Bits 0:8 of C(MA);
AC := Bits 9:12 of C(MA);
EACOMP: I := Bit 13 of C(MA);
X := Bits 14:17 of C(MA);
Y := Bits 18:35 of C(MA);
E := Y;
IF X <> 0 then E := Bits 18:35 of E+C(X);
IF I=0 then go to DONE;
MA := E;
go to EACOMP
DONE:
The effective address is an 18 bit quantity. If the I and X fields of the
instruction are zero then the effective address is simply the address (Y)
field of the instruction. If X isn't zero, then the contents of the word
addressed by X (i.e., the contents a register serving as the index register
for this instruction) are added to the contents of the Y field (the sum is
truncated to 18 bits). This sum serves as the effective address, unless the
indirect (I) bit is set. If the I bit is set, a word is read from the address
specified by X and Y, and the I, X, and Y fields of that new word are used for
repeating the effective address calculation. Note that this calculation will
loop until a word is read in which the I field is zero.
Instruction Set Page 9
The result of the effective address calculation may be thought of as an
instruction word where bits 0:12 are copied from the original instruction,
bits 13:17 are zero, and 18:35 contain the effective address.
In programming the PDP-10 it is convenient to imagine that your program
occupies contiguous virtual memory locations from 0 to some maximum address.
All memory locations are equivalent for most purposes (but some operating
systems reserve some of your space for their own purposes).
Sixteen memory locations (addresses 0 to 17 - note that addresses will appear
in octal) are distinguished by their use as general purpose registers (also
called accumulators or index registers). Most PDP-10 instructions address one
memory operand and one accumulator (so-called "one and a half address"
architecture). This means that nearly all instructions affect some
accumulator. These registers are actually implemented in high speed solid
state memory rather than in slower main memory. For any purpose where it is
convenient to do so, a user may reference an accumulator as memory.
Instruction classes are formed by a mnemonic class name and one or more
modifier letters. The modifiers usually signify some transformation on the
data or the direction of data movement or the skip or jump condition. Some
functional duplications and some no-ops result from this scheme. However,
despite these drawbacks, this notion of instruction classes and modifiers
makes the instruction set easy to learn.
2.2. Full Word Instructions
These are the instructions whose basic purpose is to move one or more full
words of data from one location to another, usualy from an accumulator to a
memory location or vice versa. In some cases, minor arithmetic operations are
performed, such as taking the magnitude or negative of a word.
2.2.1. MOVE
The MOVE class of instructions perform full word data transmission between an
accumulator and a memory location. There are sixteen instructions in the MOVE
class. All mnemonics begin with MOV. The first modifier specifies a data
transformation operation; the second modifier specifies the source of data and
the destination of the result.
|E no modification | from memory to AC
MOV |N negate source |I Immediate. Source is 0,,E to AC
|M magnitude |M from AC to memory
|S swap source |S to self. If AC<>0 to AC also
C(E) signifies contents of E (effective address) prior to the execution of the
instruction. C(AC) signifies contents of the AC specified. CS(E) and CS(AC)
signify the contents of E or AC with left and right halves swapped. CR(AC)
and CL(AC) signify the 18 bit right and left contents of the AC. PC signifies
the 18 bit contents of the program counter.
Instruction Set Page 10
MOVE C(AC) := C(E)
MOVEI C(AC) := 0,,E
MOVEM C(E) := C(AC)
MOVES C(E) := C(E); if AC<>0 then C(AC) := C(E)
MOVN C(AC) := -C(E)
MOVNI C(AC) := -E
MOVNM C(E) := -C(AC)
MOVNS C(E) := -C(E); if AC<>0 then C(AC) := -C(E)
MOVM C(AC) := |C(E)|
MOVMI C(AC) := 0,,E
MOVMM C(E) := |C(AC)|
MOVMS C(E) := |C(E)|; if AC<>0 then C(AC) := |C(E)|
MOVS C(AC) := CS(E)
MOVSI C(AC) := E,,0
MOVSM C(E) := CS(AC)
MOVSS C(E) := CS(E); if AC<>0 then C(AC) := CS(E)
2.2.2. EXCH - Exchange
EXCH exchanges the contents of the selected ac with the contents of the
effective address.
EXCH C(AC):=:C(E)
2.2.3. BLT - Block Transfer
The instruction copies words from memory to memory. The left half of the
selected AC specifies the first source address. The right half of the AC
specifies the first destination address. The effective address specifies the
last destination address. Words are copied, one by one, from the source to
the destination, until a word is stored in an address greater than or equal to
the effective address of the BLT.
Caution: BLT clobbers the specified AC. Don't use the BLT AC in
address calculation for the BLT, results will be random. If source
and destination overlap, remember that BLT moves the lowest source
word first. If the destination of the BLT includes the BLT AC, then
the BLT AC better be the last destination address.
2.2.4. Programming Examples Using Fullword Instructions
In these examples, several standard PDP-10 assembly languange notations are
used:
[] Square brackets enclose a "literal". The contents of the
brackets are assembled in another place, and the bracketed
expression is replaced by the address of that place.
Instruction Set Page 11
<> Angle brackets enclose an expression.
,, Separates left- and right-half quantities in a word. In
<a,,b>, a is right-adjusted in bits 0:17, and b is right-
adjusted in bits 18:35. If either quantity is too big, it is
truncated on the left.
() Parentheses enclose an expression which denotes an index
register.
. (pronounced "dot") Denotes the current location.
; Save all the accumulators:
movem 17, savac+17
movei 17, savac ; Source is 0, destination
blt 17, savac+16 ; is SAVAC.
; Restore all the accumulators:
movsi 17, savac ; Source is SAVAC,
blt 17, 17 ; destination is 0.
; Zero 100 words starting at TABLE.
setzm table
move t1, [table,,table+1] ; Source and
blt t1, table+77 ; destination overlap
; Move 77 words from TABLE thru TABLE+76 to TABLE+1 thru
; table+77: BLT can't be done here because the source and
; destination overlap. (See the description of POP.)
move t1, [400076,,table+76]
pop t1, 1(t1) ; Store TABLE+76 into
jumpl t1, .-1 ; table+77, etc.
2.3. Stack Instructions
These two instructions insert and remove full words in a pushdown list. The
address of the top of the list is kept in the right half of the AC referenced
by these instructions. The program may keep a control count in the left half
of the AC. There are also two subroutine calling instructions (PUSHJ and
POPJ) that use this same format pushdown list.
2.3.1. PUSH - Push on Stack
PUSH C(AC):=C(AC)+<1,,1>; C(CR(AC)):=C(E)
The specified accumulator is incremented by adding 1 to each half (in the KI10
and KL10 carry out of the right half is suppressed). If, as result of the
addition, the left half of the AC becomes positive, a pushdown overflow
condition results (but the instruction procedes to completion). The word
Instruction Set Page 12
addressed by the effective address is fetched and stored on the top of the
stack which is addressed by the right half of the (incremented) accumulator.
2.3.2. POP - Pop Stack
POP C(E):=C(CR(AC)); C(AC):=C(AC)-<1,,1>
POP undoes PUSH as follows: the word at the top of the stack (addressed by the
right half of the selected AC) is fetched and stored at the effective address.
Then the AC is decremented by subtracting 1 from both halves (in the KI10 and
KL10 carry out of bit 18 is suppressed). If the AC becomes negative as a
result of the subtraction a pushdown overflow results.
Often the accumulator used as the pushdown pointer is given the symbolic name
P. To initialize a pushdown pointer (e.g., for N words starting at PDLIST),
one might do the following:
move p, [iowd n, pdList]
where the IOWD pseudo op assembles -N,,PDLIST-1. Elsewhere in the program
should appear:
pdList: block n
which defines the symbolic label PDLIST and reserves N words following it for
the stack.
2.3.3. ADJSP - Adjust Stack Pointer
ADJSP CL(AC) := CL(AC)+E; CR(AC) := CR(AC)+E
E is added algebraically, with bit 18 acting as the sign bit, to both halves
of AC. If a negative E changes the count in AC left from positive or zero to
negative, or a positive E changes the count from negative to positive or zero,
set trap 2.
2.4. Halfword Instructions
The halfword class of instructions perform data transmission between one half
of an accumulator and one half of a memory location. There are sixty-four
halfword instructions. Each mnemonic begins with H and has four modifiers.
The first modifier specifies which half of the source word; the second
specifies which half of the destination. The third modifier specifies what to
do to the other half of the destination. The fourth modifier specifies the
source of data and the destination of the result.
Instruction Set Page 13
H halfword from |R right of source
|L left
|R right of destination
|L left
| no modification of other half
|Z zero other half
|O set other half to ones
|E sign extend source to other half
| from memory to AC
|I Immediate
|M from AC to memory
|S to self. If AC<>0 to AC also.
2.4.1. HR - Halfword Right
HRR CR(AC) := CR(E)
HRRI CR(AC) := E
HRRM CR(E) := CR(AC)
HRRS CR(E) := CR(E); if AC<>0 then CR(AC) := CR(E)
HRRZ C(AC) := 0,,CR(E)
HRRZI C(AC) := 0,,E
HRRZM C(E) := 0,,CR(AC)
HRRZS C(E) := 0,,CR(E); if AC<>0 then C(AC) := 0,,CR(E)
HRRO C(AC) := 777777,,CR(E)
HRROI C(AC) := 777777,,E
HRROM C(E) := 777777,,CR(AC)
HRROS C(E) := 777777,,CR(E);
if AC<>0 then C(AC) := 777777,,CR(E)
HRRE C(AC) := 777777*C18(E),,CR(E)
HRREI C(AC) := 777777*E18,,E
HRREM C(E) := 777777*C18(AC),,CR(AC)
HRRES C(E) := 777777*C18(E),,CR(E);
if AC<>0 then C(AC) := 777777*C18(E),,CR(E)
HRL CL(AC) := CR(E)
HRLI CL(AC) := E
HRLM CL(E) := CR(AC)
HRLS CL(E) := CR(E); if AC<>0 then CL(AC) := CR(E)
HRLZ C(AC) := CR(E),,0
HRLZI C(AC) := E,,0
HRLZM C(E) := CR(AC),,0
HRLZS C(E) := CR(E),,0;
if AC<>0 then C(AC) := CR(E),,0
Instruction Set Page 14
HRLO C(AC) := CR(E),,777777
HRLOI C(AC) := E,,777777
HRLOM C(E) := CR(E),,777777
HRLOS C(E) := CR(E),,777777;
if AC<>0 then C(AC) := CR(E),,777777
HRLE C(AC) := CR(E),,777777*C18(E)
HRLEI C(AC) := E,,777777*E18
HRLEM C(E) := CR(AC),,777777*C18(AC)
HRLES C(E) := CR(E),,777777*C18(E);
if AC<>0 then C(AC) := CR(E),,777777*C18(E)
2.4.2. HL Halfword Left
HLR CR(AC) := CL(E)
HLRI CR(AC) := 0
HLRM CR(E) := CL(AC)
HLRS CR(E) := CL(E); if AC<>0 then CR(AC) := CL(E)
HLRZ C(AC) := 0,,CL(E)
HLRZI C(AC) := 0
HLRZM C(E) := 0,,CL(AC)
HLRZS C(E) := 0,,CL(E);
if AC<>0 then C(AC) := 0,,CL(E)
HLRO C(AC) := 777777,,CL(E)
HLROI C(AC) := 777777,,0
HLROM C(E) := 777777,,CL(AC)
HLROS C(E) := 777777,,CL(E);
if AC<>0 then C(AC) := 777777,,CL(E)
HLRE C(AC) := 777777*C0(E),,CL(E)
HLREI C(AC) := 0
HRREM C(E) := 777777*C0(AC),,CL(AC)
HRRES C(E) := 777777*C0(E),,CL(E);
if AC<>0 then C(AC) := 777777*C0(E),,CR(E)
HLL CL(AC) := CL(E)
HLLI CL(AC) := 0
HLLM CL(E) := CL(AC)
HLLS CL(E) := CL(E); if AC<>0 then CL(AC) := CL(E)
HLLZ C(AC) := CL(E),,0
HLLZI C(AC) := 0
HLLZM C(E) := CL(AC),,0
HLLZS C(E) := CL(E),,0;
if AC<>0 then C(AC) := CL(E),,0
HLLO C(AC) := CL(E),,777777
HLLOI C(AC) := 0,,777777
HLLOM C(E) := CL(E),,777777
HLLOS C(E) := CL(E),,777777;
if AC<>0 then C(AC) := CL(E),,777777
Instruction Set Page 15
HLLE C(AC) := CL(E),,777777*C0(E)
HLLEI C(AC) := 0
HLLEM C(E) := CL(AC),,777777*C0(AC)
HLLES C(E) := CL(E),,777777*C0(E);
if AC<>0 then C(AC) := CL(E),,777777*C0(E)
2.5. Arithmetic Testing
2.5.1. AOBJ - Add One to Both Halves and Jump
The AOBJx (Add One to Both halves of AC and Jump) instructions allow forward
indexing through an array while maintaining a control count in the left half
of an accumulator. Use of AOBJN and AOBJP can reduce loop control to one
instruction.
AOBJN C(AC):=C(AC)+<1,,1>; if C(AC)<0 then PC:=E
AOBJP C(AC):=C(AC)+<1,,1>; if C(AC)>=0 then PC:=E
Example. Add 3 to N words starting at location TAB:
movsi 1, -N ; Initialize register 1 to -N,,0.
movei 2, 3 ; Register 2 gets the constant 3.
addm 2, tab(1) ; Add 3 to one array element.
aobjn 1, .-1 ; Increment both the index and the
; control. Loop until the ADDM has
; been done N times.
By the way, for the sake of consistency, AOBJN should have been called AOBJL
and AOBJP should have been called AOBJGE. However, they weren't.
2.5.2. JUMP
The JUMP instructions compare the selected accumulator to zero and jump (to
the effective address of the instruction) if the specified relation is true.
JUMP Jump never.
JUMPL if C(AC) < 0 then PC:=E
JUMPLE if C(AC) <= 0 then PC:=E
JUMPE if C(AC) = 0 then PC:=E
JUMPN if C(AC) <> 0 then PC:=E
JUMPGE if C(AC) >= 0 then PC:=E
JUMPG if C(AC) > 0 then PC:=E
JUMPA PC:=E
Instruction Set Page 16
2.5.3. SKIP
The SKIP instructions compare the contents of the effective address to zero
and skip the next instruction if the specified relation is true. If a
non-zero AC field appears, the selected AC is loaded from memory.
SKIP if AC<>0 then C(AC):=C(E); don't skip
SKIPL if AC<>0 then C(AC):=C(E);
if C(E) < 0 then skip
SKIPLE if AC<>0 then C(AC):=C(E);
if C(E) <= 0 then skip
SKIPE if AC<>0 then C(AC):=C(E);
if C(E) = 0 then skip
SKIPN if AC<>0 then C(AC):=C(E);
if C(E) <> 0 then skip
SKIPGE if AC<>0 then C(AC):=C(E);
if C(E) >= 0 then skip
SKIPG if AC<>0 then C(AC):=C(E);
if C(E) > 0 then skip
SKIPA if AC<>0 then C(AC):=C(E); skip
2.5.4. AOS - Add One and Skip
The AOS (Add One to memory and Skip) instructions increment a memory location,
compare the result to zero to determine the skip condition, If a non-zero AC
field appears then the AC selected will be loaded (with the incremented data).
AOS C(E) := C(E)+1; if AC<>0 then C(AC):=C(E)
AOSL C(E) := C(E)+1; if AC<>0 then C(AC):=C(E);
if C(E) < 0 then skip
AOSLE C(E) := C(E)+1; if AC<>0 then C(AC):=C(E);
if C(E) <= 0 then skip
AOSE C(E) := C(E)+1; if AC<>0 then C(AC):=C(E);
if C(E) = 0 then skip
AOSN C(E) := C(E)+1; if AC<>0 then C(AC):=C(E);
if C(E) <> 0 then skip
AOSGE C(E) := C(E)+1; if AC<>0 then C(AC):=C(E);
if C(E) >= 0 then skip
AOSG C(E) := C(E)+1; if AC<>0 then C(AC):=C(E);
if C(E) > 0 then skip
AOSA C(E) := C(E)+1; if AC<>0 then C(AC):=C(E);
skip
2.5.5. SOS - Subtract One and Skip
The SOS (Subtract One from memory and Skip) instructions decrement a memory
location, compare the result to zero to determine the skip condition, If a
non-zero AC field appears then the AC selected will be loaded (with the
decremented data).
Instruction Set Page 17
SOS C(E) := C(E)-1; if AC<>0 then C(AC):=C(E)
SOSL C(E) := C(E)-1; if AC<>0 then C(AC):=C(E);
if C(E) < 0 then skip
SOSLE C(E) := C(E)-1; if AC<>0 then C(AC):=C(E);
if C(E) <= 0 then skip
SOSE C(E) := C(E)-1; if AC<>0 then C(AC):=C(E);
if C(E) = 0 then skip
SOSN C(E) := C(E)-1; if AC<>0 then C(AC):=C(E);
C(E) <> 0 then skip
SOSGE C(E) := C(E)-1; if AC<>0 then C(AC):=C(E);
if C(E) >= 0 then skip
SOSG C(E) := C(E)-1; if AC<>0 then C(AC):=C(E);
if C(E) > 0 then skip
SOSA C(E) := C(E)-1; if AC<>0 then C(AC):=C(E);
skip
2.5.6. AOJ - Add One and Jump
The AOJ (Add One to AC and Jump) instructions increment the contents of the
selected accumulator. If the result bears the indicated relation to zero then
the instruction will jump to the effective address.
AOJ C(AC) := C(AC)+1;
AOJL C(AC) := C(AC)+1; if C(AC) < 0 then PC:=E
AOJLE C(AC) := C(AC)+1; if C(AC) <= 0 then PC:=E
AOJE C(AC) := C(AC)+1; if C(AC) = 0 then PC:=E
AOJN C(AC) := C(AC)+1; if C(AC) <> 0 then PC:=E
AOJGE C(AC) := C(AC)+1; if C(AC) >= 0 then PC:=E
AOJG C(AC) := C(AC)+1; if C(AC) > 0 then PC:=E
AOJA C(AC) := C(AC)+1; PC:=E
2.5.7. SOJ - Subtract One and Jump
The SOJ (Subtract One from AC and Jump) instructions decrement the contents of
the selected accumulator. If the result bears the indicated relation to zero
then the instruction will jump to the effective address.
SOJ C(AC) := C(AC)-1
SOJL C(AC) := C(AC)-1; if C(AC) < 0 then PC:=E
SOJLE C(AC) := C(AC)-1; if C(AC) <= 0 then PC:=E
SOJE C(AC) := C(AC)-1; if C(AC) = 0 then PC:=E
SOJN C(AC) := C(AC)-1; if C(AC) <> 0 then PC:=E
SOJGE C(AC) := C(AC)-1; if C(AC) >= 0 then PC:=E
SOJG C(AC) := C(AC)-1; if C(AC) > 0 then PC:=E
SOJA C(AC) := C(AC)-1; PC:=E
Instruction Set Page 18
2.5.8. CAM - Compare Accumulator to Memory
The CAM (Compare Accumulator to Memory) class compare the contents of the
selected accumulator to the contents of the effective address. If the
indicated condition is true, the instruction will skip. The CAM instruction
is suitable for arithmetic comparision of either fixed point quantities or
normalized floating point quantities. Needless to say, for the comparison to
be meaningful both C(AC) and C(E) should be in the same format (i.e., either
both fixed or both floating).
CAM no op (references memory)
CAML if C(AC) < C(E) then skip
CAMLE if C(AC) <= C(E) then skip
CAME if C(AC) = C(E) then skip
CAMN if C(AC) <> C(E) then skip
CAMGE if C(AC) >= C(E) then skip
CAMG if C(AC) > C(E) then skip
CAMA skip
2.5.9. CAI - Compare Accumulator Immediate
The CAI (Compare Accumulator Immediate) class compare the contents of the
selected accumulator to the effective address. If the indicated condition is
true, the instruction will skip. Note than an effective address is an 18 bit
quantity that is always considered to be positive.
CAI no op
CAIL if C(AC) < E then skip
CAILE if C(AC) <= E then skip
CAIE if C(AC) = E then skip
CAIN if C(AC) <> E then skip
CAIGE if C(AC) >= E then skip
CAIG if C(AC) > E then skip
CAIA skip
Skipping instructions can be combined to achieve ANDing or ORing of logical
expressions, e.g. the sequence
cail t1, 1
caile t1, 1000
jrst bad
is equivalent to
if C(t1) < 1 or C(t1) > 1000 then go to BAD
Instruction Set Page 19
2.6. Fixed Point Arithmetic
In positive numbers bit 0 is zero. Bit 1 is most significant; bit 35 is least
significant. Negative numbers are the two's complement of positive numbers.
Results (of ADD, SUB or IMUL) outside the range -2^35 to 2^35-1 will set
overflow ( PC bit 0).
2.6.1. ADD
ADD C(AC) := C(AC) + C(E)
ADDI C(AC) := C(AC) + E
ADDM C(E) := C(AC) + C(E)
ADDB C(AC) := C(AC) + C(E); C(E) := C(AC)
2.6.2. SUB - Subtract
SUB C(AC) := C(AC) - C(E)
SUBI C(AC) := C(AC) - E
SUBM C(E) := C(AC) - C(E)
SUBB C(AC) := C(AC) - C(E); C(E) := C(AC)
2.6.3. IMUL - Single-Word Multiply
The IMUL instructions are for multiplying numbers where the product is
expected to be representable as one word.
IMUL C(AC) := C(AC) * C(E)
IMULI C(AC) := C(AC) * E
IMULM C(E) := C(AC) * C(E)
IMULB C(AC) := C(AC) * C(E); C(E) := C(AC)
2.6.4. IDIV - Single-Word Divide
The IDIV instructions are for divisions in which the dividend is a one word
quantity. AC+1 signifes the quantity (AC+1 modulo 20 octal). If the divisor
is zero set overflow and no divide; don't change AC or memory operands. The
remainder will have the same sign as the dividend.
IDIV C(AC) := C(AC) / C(E); C(AC+1) := remainder
IDIVI C(AC) := C(AC) / E; C(AC+1) := remainder
IDIVM C(E) := C(AC) / E
IDIVB C(AC) := C(AC) / C(E); C(AC+1) := remainder;
C(E) := C(AC)
Instruction Set Page 20
2.6.5. MUL - Multiply
The MUL instructions produce a double word product. A double word integer has
70 bits of significance. Bit 0 of the high order word is the sign bit. In
data, Bit 0 of the low order word is ignored by the hardware. In results, bit
0 of the low word is the same as bit 0 in the high word. MUL will set
overflow if both operands are -2^35.
MUL C(AC AC+1) := C(AC) * C(E)
MULI C(AC AC+1) := C(AC) * E
MULM C(E) := high word of product of C(AC) * C(E)
MULB C(AC AC+1) := C(AC) * C(E); C(E) := C(AC)
2.6.6. DIV - Divide
The DIV instructions are for divisions in which the dividend is a two word
quantity (such as produced by MUL). If C(AC) is greater than the memory
operand then set overflow and no divide.
DIV C(AC) := C(AC AC+1) / C(E); C(AC+1) := remainder
DIVI C(AC) := C(AC AC+1) / E; C(AC+1) := remainder
DIVM C(E) := C(AC AC+1) / E
DIVB C(AC) := C(AC AC+1) / C(E); C(AC+1) := remainder;
C(E) := C(AC)
2.7. Double Word Move Instructions (KI10 and KL10)
There are four double word move instructions. These are suitable for
manipulating KI10 and KL10 double precision floating point numbers, and for
KL10 double precision integers.
DMOVE C(AC AC+1) := C(E E+1)
DMOVEM C(E E+1) := C(AC AC+1)
DMOVN C(AC AC+1) := -C(E E+1)
DMOVNM C(E E+1) := -C(AC AC+1)
Note that the DMOVN and DMOVNM are NOT to be used for KA10 double
precision floating point numbers!
If a program is written that may be have to be run on a KA10, the use of all
double word instructions should be avoided.
2.8. Double Precision Integer Arithmetic (KL10 only)
There are four instructions for double precision integer arithmetic. None of
these instructions have any modifier: they all operate on double (or
quadruple) accumulators and double words in memory with results to double (or
quadruple) accumulators.
Instruction Set Page 21
The format for a double word integer is the same as that produced by MUL,
i.e., a 70 bit integer in two's complement, with bit 0 of the most significant
word is the sign; in operands, bit 0 of the low order word is ignored. A
quadruple word has 140 bits; bit 0 of the most significant word is the sign;
in operands, bit 0 in all other words is ignored. In double (and quadruple)
arithmetic results bit 0 of the low order word(s) is stored with the same
value as bit 0 of the high order word.
DADD C(AC AC+1) := C(AC AC+1) + C(E E+1)
DSUB C(AC AC+1) := C(AC AC+1) - C(E E+1)
DMUL C(AC AC+1 AC+2 AC+3) := C(AC AC+1) * C(E E+1)
DDIV C(AC AC+1) := C(AC AC+1 AC+2 AC+3) / C(E E+1)
C(AC+2 AC+3) := remainder
2.9. Floating Point Arithmetic
Single precision floating point numbers are represented in one 36 bit word as
follows:
Bit 0 00000000 011111111112222222222333333
Position 0 12345678 901234567890123456789012345
______________________________________
| | | |
|S| Exp | Fraction |
|_|________|___________________________|
If S is zero, the sign is positive. If S is one the sign is negative and the
word is in two's complement format. The fraction is interpreted as having a
binary point between bits 8 and 9. The exponent is a power of 2 represented
in excess 200 (octal) notation. In a normalized floating point number bit 9
is different from bit 0, except in a negative number bits 0 and 9 may both be
one if bits 10:35 are all zero. A floating point zero is represented by a
word with 36 bits of zero. Floating point numbers can represent numbers with
magnitude within the range 0.5*2^-128 to (1-2^-27)*2^127, and zero.
A number in which bit 0 is one and bits 9-35 are zero can produce an incorrect
result in any floating point operation. Any word with a zero fraction and
non-zero exponent can produce extreme loss of precision if used as an operand
in a floating point addition or subtraction.
In KI10 (and KL10) double precision floating point, a second word is included
which contains in bits 1:35 an additional 35 fraction bits. The additional
fraction bits do not significantly affect the range of representable numbers,
rather they extend the precision.
The KA10 lacks double precision floating point hardware, but there are several
instructions by which software may implement double precision. These
instructions are DFN, UFA, FADL, FSBL, FMPL, and FDVL. Users of the KL10 are
strongly advised to avoid using these intructions.
In the PDP-6 floating point is somewhat different. Consult an wizard.
Instruction Set Page 22
F floating
|AD add | result to AC
|SB subtract |R rounded |I Immediate. result to AC
|MP multiply | |M result to memory
|DV divide | |B result to memory and AC
|
|
| no rounding | result to AC
|L Long mode
|M result to memory
|B result to memory and AC
|AD add
DF double floating |SB subtract
|MP multiply
|DV divide
Note: In immediate mode, the memory operand is <E,,0>. In long
mode (except FDVL) the result appears in AC and AC+1. In FDVL the AC
operand is in AC and AC+1 and the quotient is stored in AC with the
remainder in AC+1.
2.10. Other Floating Point Instructions
2.10.1. FSC - Floating Scale
FSC (Floating SCale) will add E to the exponent of the number in AC and
normalize the result. One use of FSC is to convert an integer in AC to
floating point (but FLTR, available in the KI and KL is better). To use FSC
to float an integer, set E to 233 (excess 200 and shift the binary point 27
bits). The integer being floated must not have more than 27 significant bits.
FSC will set AROV and FOV if the resulting exponent exceeds 127. FXU (and
AROV and FOV) will be set if the exponent becomes smaller than -128.
2.10.2. FIX - Convert Floating Point to Integer
FIX will convert a floating point number to an integer. If the exponent of
the floating point number in C(E) is greater than (decimal) 35 (which is octal
243) then this instruction will set AROV and not affect C(AC). Otherwise,
convert C(E) to fixed point by the following procedure: Move C(E) to AC,
copying bit 0 of C(E) to bits 1:8 of AC (sign extend). Then ASH AC by X-27
bits (where X is the exponent from bits 1:9 of C(E) less 200 octal). FIX will
truncate towards zero, i.e., 1.9 is fixed to 1 and -1.9 is fixed to -1.
Instruction Set Page 23
2.10.3. FIXR - Fix and Round
FIXR (Fix and round) will convert a number to an integer by rounding. If the
exponent of the floating point number in C(E) is greater than (decimal) 35
(which is octal 243) then this instruction will set AROV and not affect C(AC).
Otherwise, convert C(E) to fixed point by the following procedure: Move C(E)
to AC, copying bit 0 of C(E) to bits 1:8 of AC (sign extend). Then ASH AC by
X-27 bits (where X is the exponent from bits 1:9 of C(E) less 200 octal). If
X-27 is negative (i.e., right shift) then the rounding process will consider
the bits shifted off the right end of AC. If AC is positive and the discarded
bits are >=1/2 then 1 is added to AC. If AC is negative and the discarded
bits are >1/2 then 1 is added to AC. Rounding is always in the positive
direction: 1.4 becomes 1, 1.5 becomes 2, -1.5 becomes -1, and -1.6 becomes
-2.
2.10.4. FLTR - Float and Round
FLTR (FLoaT and Round) will convert C(E), an integer, to floating point and
place the result in AC. The data from C(E) is copied to AC where its is
arithmetic shifted right 8 places (keeping the bits that fall off the end) and
the exponent 243 is inserted in bits 1:8. The resulting number is normalized
until bit 9 is significant (normalization may result in some or all of the
bits that were right shifted being brought back into AC). Finally, if any of
the bits that were right shifted still remain outside the AC the result is
rounded by looking at the bit to the right of the AC.
2.11. Shift Instructions
The following instructions shift or rotate the AC or the formed by AC and
AC+1. The number of places to shift is specified by the effective address
which is considered to be a signed number modulo 256 in magnitude. That is,
the effective shift is the number composed of bit 18 (the sign) of the
effective address and bits 28:35 of the effective address. If E is positive,
a left shift occurs. If E is negative a right shift occurs.
LSH Logical Shift. C(AC) is shifted as specified by E. Zero bits
are shifted into the AC.
LSHC Logical Shift Combined. C(AC AC+1) is shifted as a 72 bit
quantity. Zero bits are shifted in.
ASH Arithmetic Shift. Bit 0 is not changed. In a left shift zero
bits are shifted into the right end of AC. In a left shift,
if any bit of significance is shifted out of bit 1, AROV
( overflow) is set. In a right shift, bit 0 is shifted into
bit 1.
ASHC Arithmetic Shift Combined. AC bit 0 is not changed. If E is
non zero, AC bit 0 is copied to AC+1 bit 0. C(AC AC+1) is
shifted as a 70 bit quantity. In a left shift zero bits are
shifted into the right end of AC+1. In a left shift, if any
bit of significance is shifted out of AC bit 1 then AROV is
set. In a right shift AC bit 0 is shifted into AC bit 1.
Instruction Set Page 24
ROT Rotate. The 36 bit C(AC) is rotated. In a left rotate bits
shifted out of bit 0 are shifted into bit 35. In a right
rotate, Bit 35 is shifted into bit 0.
ROTC Rotate Combined. AC and AC+1 are rotated as a 72 bit
quantity. In a left rotate AC bit 0 shifts into AC+1 bit 35
and AC+1 bit 0 shifts into AC bit 35. In a right rotate, AC+1
bit 35 shifts into AC bit 0, etc.
2.12. Byte Instructions
In the PDP-10 a "byte" is some number of contiguous bits within one word. A
byte pointer is a word that describes the byte. There are three parts to the
description of a byte: the word (i.e., address) in which the byte occurs, the
position of the byte within the word, and the length of the byte.
A byte pointer has the following format:
Bit 000000 000011 1 1 1111 112222222222333333
Position 012345 678901 2 3 4567 890123456789012345
_________________________________________
| | | | | | |
| POS | SIZE |U|I| X | Y |
|______|______|_|_|____|__________________|
- POS is the byte position: the number of bits remaining in the word
to the right of the byte.
- SIZE is the byte size in bits.
- The U field is reserved for future use and must be zero.
- I, X, and Y are the same as in an instruction.
2.12.1. LDB - Load Byte
The contents of the effective address of the LDB instruction is interpreted as
a byte pointer. The byte described there is loaded, right adjusted, into the
AC. The rest of the AC is cleared.
2.12.2. DPB - Deposit Byte
The contents of the effective address of the DPB instruction is interpreted as
a byte pointer. The byte described there is deposited from the byte of the
same size at the right end of the AC. AC and the remainder of the word into
which the byte is deposited are left unchanged.
Instruction Set Page 25
2.12.3. IBP - Increment Byte Pointer
The AC field must be zero. The contents of the effective address are fetched.
The POS field is changed by subtracting the size field from it. If the result
of the subtraction is greater than or equal to zero, store the difference in
the POS field. If the difference is negative, add 1 to the Y field (in the
KA10 and PDP-6 if Y contains 777777 then this will carry into the X field; in
the KI10 and KL10 the carry out is suppressed) and set POS field to 44-SIZE
(44 is octal). The effect of this is to modify the byte pointer to address
the next byte (of the same size) that follows the byte addressed by the
original pointer, skipping over any bits that may be left over at the end of a
word (when the bytesize does not divide evenly into the wordsize, 36).
2.12.4. ILDB - Increment and Load Byte
Increment the byte pointer contained at the effective address. Then perform a
LDB function using the updated byte pointer.
2.12.5. IDPB - Increment and Deposit Byte
Increment the byte pointer contained at the effective address. Then perform a
DPB function using the updated byte pointer.
2.12.6. ADJBP - Adjust Byte Pointer
Fetch the byte pointer at the effective address, increment or decrement it by
the number of bytes specified in the AC, then place the adjusted byte pointer
in the AC. The original byte pointer is unchanged.
2.12.7. POINT - Construct a Byte Pointer
For convenience, the Macro assembler (and Fail) has a pseudo op for creating
byte pointers. The POINT pseudo op has three parameters: size, address, and
position. In the POINT pseudo op, the position argument specifies the bit
number of the right most bit in the byte. If the position field is omitted,
bit number "-1" is assumed (this assembles 44 in the POS field) which doesn't
address any byte, but which, when incremented once, will address the first
byte in the specified word.
POINT 7, 100(1) 440701,,100
POINT 36, @2000,35 004420,,2000
POINT 7, FOO 440700,,foo
Instruction Set Page 26
2.13. Logical Testing and Modification
The TEST instructions are for testing and modifying bits in an accumulator.
There are 64 instructions. Each mnemonic begins with a T and is followed by
three modifiers.
Test accumulator
|R right half immediate
|L left half immediate
|D direct mask
|S swapped mask
|N no modification
|Z zero selected bits
|O set selected bits to One
|C complement selected bits
| never skip
|N skip unless all selected bits are zero
|E skip if all selected bits are zero
|A skip always
The test operation considers two 36 bit quantities. One of these is the
contents of the selected AC. The other quantity, called the mask, depends on
the first modifier letter. For R the mask is <0,,E>; for L it is <E,,0>. For
D the mask is C(E), and for S the mask is CS(E), the swapped contents of E.
- If the skip condition N is specified, then the test instruction will
skip if the AND of the mask and the AC operand is Not equal to zero.
- If the skip condition E is specified, then the test instruction will
skip if the AND of the mask and the AC operand is Equal to zero.
- If the modification code Z appears then bits that are one in the
mask are made zero in the AC.
- If the modification code O appears then bits that are one in the
mask are made one in the AC.
- If the modification code C appears then bits that are one in the
mask are complemented in the AC.
Note that the skip condition is determined on the basis of the contents of the
AC before it is modified.
The principle use for the Test instructions is in testing and modifying single
bit flags that are kept in an accumulator.
2.14. Boolean Logic
There are 16 possible boolean functions of 2 variables. The PDP-10 has 16
instruction classes (each with 4 modifiers) that perform these operations.
Each boolean function operates on the 36 bits of AC and memory as individual
bits.
Instruction Set Page 27
Table of the Boolean functions
C(AC) 0 0 1 1
C(E) 0 1 0 1
SETZ 0 0 0 0 SET to Zero
AND 0 0 0 1 AND
ANDCM 0 0 1 0 AND with Complement of Memory
SETA 0 0 1 1 SET to AC
ANDCA 0 1 0 0 AND with Complement of AC
SETM 0 1 0 1 SET to Memory
XOR 0 1 1 0 eXclusive OR
IOR 0 1 1 1 Inclusive OR
ANDCB 1 0 0 0 AND with Complements of Both
EQV 1 0 0 1 EQuiValence
SETCM 1 0 1 0 SET to Complement of Memory
ORCA 1 0 1 1 OR with Complement of Memory
SETCA 1 1 0 0 SET to Complement of AC
ORCA 1 1 0 1 OR with Complement of AC
ORCB 1 1 1 0 OR with Complements of Both
SETO 1 1 1 1 SET to One
Each of the 16 instructions above have four modifiers that specify where to
store the result. No modifier means result to AC. Modifier I means
Immediate: the memory data is <0,,E> and the result goes to AC. M as a
modifier means result should be stored in memory. B means store the results
in both memory and AC.
2.15. PC Format
JSR, JSP, and PUSHJ all store a full word that contains the PC (Program
Counter) and various flags.
The format of a PC word is:
0 0 0 0 0 0 0 0 0 0 1 1 1 11111 112222222222333333
0 1 2 3 4 5 6 7 8 9 0 1 2 34567 890123456789012345
__________________________________________________
|A|C|C|F|F|U|I|P|A|T|T|F|D| | |
|R|R|R|O|P|S|O|U|F|R|R|X|C|00000| PC |
|O|Y|Y|V|D|E|T|B|I|A|A|U|K| | |
|V|0|1| | |R| |L| |P|P| | | | |
| | | | | | | | | |2|1| | | | |
|_|_|_|_|_|_|_|_|_|_|_|_|_|_____|__________________|
AROV, ARithmetic OVerflow, is set by any of the following:
- A single instruction has set one of CRY0 or CRY1 without setting
them both.
- An ASH or ASHC has left shifted a significant bit out of AC bit 1.
- A MULx instruction has multiplied -2^35 by itself.
Instruction Set Page 28
- A DMUL instruction has multiplied -2^70 by itself.
- An IMULx instruction has produced a product less than -2^35 or
greater than 2^35-1.
- A FIX or FIXR has fetched an operand with exponent greater than 35.
- FOV (Floating Overflow) has been set.
- DCK (Divide ChecK) has been set.
- CRY0, CaRrY 0, if set without CRY1 being set will set AROV. This
indicates any of the following conditions:
1. An ADDx has added two negative numbers with sum less than
-2^35.
2. A SUBx has subtracted a positive number from a negative number
and produced a result less than -2^35.
3. A SOSx or SOJx has decremented -2^35.
- If CRY0 and CRY1 are both set, this indicates that one of the
following non-overflow events has occurred:
1. In ADDx both summands were negative, or their signs differed
and the postive one was greater than or equal to the magnitude
of the negative summand.
2. In SUBx the sign of both operands was the same and the AC
operand was greater than or equal to the memory operand, or
the AC operand was negative and the memory operand was
positive.
3. An AOJx or AOSx has incremented -1.
4. SOJx or SOS has decremented a nonzero number other than -2^35.
5. A MOVNx has negated zero.
- CRY1, CaRrY 1, if set without CRY0 being set will set AROV. This
indicates any of the following conditions:
1. An ADDx has added two positive number with a sum greater than
2^35-1.
2. A SUBx has subtracted a negative number from a positive number
to form a difference greater than 2^35-1.
3. An AOSx or AOJx instruction has incremented 2^35-1.
4. A MOVNx or MOVMx has negated -2^35.
5. A DMOVNx has negated -2^70
The following conditions are also indicated in the PC word:
- FOV, Floating point OVerflow, is set by any of:
Instruction Set Page 29
1. In a floating point instruction other than FLTR, DMOVNx, or
DFN the exponent of the result exceeds 127.
2. FXU (Floating eXponent Underflow) has been set.
3. DCK ( Divide ChecK) has been set by FDVx, FDVRx, or DFDV.
- FPD, First Part Done, is set when the processor responds to a
priority interrupt, after having completed the first part of a two
part instruction (e.g., ILDB). This flag is not usually of interest
to the programmer.
- USER is set while the processor is in user mode. In user mode,
various instruction and addressing restrictions are in effect.
- IOT, User IN-Out mode, (also called IOT User), is a special mode in
which some of the user mode instruction (but not addressing)
restrictions are removed. In this mode a user program may perform
the hardware I/O instructions.
- PUBL, Public mode, signifies that the processor is in user public
mode or in exec supervisor mode [KI10, KL10 only].
- AFI, Address Failure Inhibit, if this flag is set, address break is
inhibited for during the execution of the next instruction [KI10,
KL10 only].
- TRAP2 - if bit 10 is not also set, pushdown overflow has occurred.
If traps are enabled, setting this flag immediately causes a trap.
At present no hardware condition sets both TRAP1 and TRAP2
simultaneously. [KI10 KL10 only]
- TRAP1 - if bit 9 is not also set, arithemetic overflow has occurred.
If traps are enabled, setting this flag immediately causes a trap.
At present no hardware condition sets both TRAP1 and TRAP2
simultaneously. [KI10 KL10 only]
- FXU, Floating eXponent Underflow, is set to signify that in a
floating instruction other than DMOVNx, FLTR, or DFN, the exponent
of the result was less than -128 and AROV and FOV have been set.
- DCK, Divide ChecK, signifies that one of the following conditions
has set AROV:
1. In a DIVx the high order word of the dividend was greater than
or equal to the divisor.
2. In an IDIVx the divisor was zero.
3. In an FDVx, FDVRx, or DFDV, the divisor was zero, or the
magnitude of the dividend fraction was greater than or equal
to twice the magnitude of the divisor fraction. In either
case, FOV is also set.
Bits 13 through 17 of the PC word are always zero to facilitate the use of
indirect addressing to return from a subroutine.
Bits 18 through 35 store an address that is one greater than the address of
Instruction Set Page 30
the instruction that stores the PC. Thus, the PC word points at the
instruction immediately following the subroutine call.
2.16. Program Control
2.16.1. JSR - Jump to Subroutine
JSR C(E):=<flags,,PC>; PC:=E+1
JSR, Jump to SubRoutine, stores the PC in the word addressed by the effective
address and jumps to the word following the word where the PC is stored. This
is the only PDP-10 instruction that stores the PC and flags without modifying
any ACs; however, it is non-reentrant, so PUSHJ is favored in most cases. The
usual return from a subroutine called by a JSR is via JRST (or JRST 2,)
indirect through the PC word. (See JRST)
2.16.2. JSP - Jump & Save PC
JSP C(AC):=<flags,,PC>; PC:=E
JSP, Jump and Save PC, stores the PC and flags in the selected accumulator and
jumps.
2.16.3. JSA - Jump and Save Accumulator
JSA C(E):=C(AC); C(AC):=<E,,PC>; PC:=E+1
JSA, Jump and Save AC, stores the AC in word addressed by the effective
address. Then the left half of the AC is set to the effective address and the
right half of AC is set to the return PC. Then the PC is set to one greater
than the effective address. The JRA instruction unwinds this call. The
advantage of this call is that a routine may have multiple entry points (which
is difficult to do with JSR) and it's easy to find (and later to skip over)
arguments that follow the calling instruction (which is possible to do with
PUSHJ, but not quite so convenient). Among the disadvantages of this call is
that it is not reentrant, and it doesn't save flags.
2.16.4. JRA - Jump and Restore Accumulator
JRA C(AC):=C(CL(AC)); PC:=E
JRA, Jump and Restore AC, is the return from JSA. If, e.g., a subrountine is
called with JSA AC, then the return is made by: JRA AC,(AC).
Instruction Set Page 31
2.16.5. PUSHJ - Push on stack and Jump
PUSHJ C(AC):=C(AC)+<1,,1>; C(CR(AC)):=<flags,,PC>;
PC:=E
PUSHJ (PUSH return address and Jump) is like PUSH except the data that is
pushed onto the top of the stack is the PC and flags word. The PC that is
stored is the PC of the instruction that follows the PUSHJ. Then the PC is
set to the effective address of the instruction. Pushdown overflow results if
the AC becomes positive when it is incremented.
2.16.6. POPJ - Pop stack and Jump
POPJ PC:=CR(CR(AC)); C(AC):=C(AC)-<1,,1>
POPJ (POP return address and Jump) undoes PUSHJ. The right half of the word
at the top of the stack is loaded into the PC (the flags are unchanged). Then
the stack pointer is decremented as in POP. The effective address of POPJ is
ignored. Pushdown overflow obtains if the AC becomes negative as a result of
the subtraction.
2.16.7. Programming Hints Using PUSHJ and POPJ
If a subroutine called by PUSHJ AC, wants to skip over the instruction
following the PUSHJ, the following sequence accomplishes that result:
aos (ac) ; AC better be nonzero.
popj ac,
If you must restore the flags that PUSHJ saved, the following sequence should
be used instead of POPJ:
pop ac, (ac) ; Adjust the stack
jrst 2, ; Restore flags and PC from
; old stack top.
2.16.8. JRST - Jump and Restore
JRST, Jump and ReSTore, is an unconditional jump instruction. In JRST, the AC
field does not address an accumulator. Instead, the AC is decoded to signify
various things.
JRST PC:=E
JRST 2, PC:=E; flags are restored (see text)
JRST 10, PC:=E; Dismiss current priority interrupt
JRST 12, PC:=E; restore flags and dismiss priority
interrupt
Instruction Set Page 32
If the AC field is zero, only a jump occurs. JRST is everyone's favorite
unconditional jump instruction (the only other one is JUMPA which is more
typing, also, on older machines JUMPA was slower than JRST).
JRST 2, (i.e., JRST with AC field set to 2) signifies jump and restore flags.
(The assembler also recognizes the mnemonic JRSTF for JRST 2,). If
indirection is used in JRSTF, then the flags are restored from the last word
fetched in the address calculation. If indexing is used with no indirection,
the flags are restored from the left half of the specified index register. If
neither indexing nor indirection is used in the address calculation the flags
are restored from the left half of the JRSTF itself! In a user mode program
JRSTF cannot clear USER nor can it set IOT User (it can however, clear IOT
User). JRST 4, JRST 10, and JRST 12 are illegal in user mode and are trapped
as UUOs.
2.16.9. JFCL - Jump on Flag and Clear
The JFCL instruction is another case in which the AC field is decoded to
modify the instruction. The AC field selects the four flags in PC bits 0
through 3. PC bits 0 to 3 correspond to bits 9 to 12 in the JFCL instruction.
JFCL will jump if any flag selected by the AC field is a 1. All flags
selected by the AC field are set to zero.
JFCL 0, since it selects no PC bits, is a no-op.
JFCL 17, will clear all flags, and will jump if any of AROV, CRY0,
CRY1, or FOV are set.
JFCL 1, (JFOV) jumps if FOV is set and clears FOV.
JFCL 10, (JOV) jumps if AROV is set and clears AROV.
2.16.10. XCT - Execute
XCT, the eXeCuTe instruction, fetches the word addressed by the effective
address and executes that word as an instruction. In the case of XCTing an
instruction that stores a PC, the PC that is stored is the address of the
instruction that follows the XCT. If the executed instruction skips, then
that skip is relative to the XCT. The AC field of the XCT should be zero.
[In monitor mode a nonzero AC field in an XCT is significant.]
The XCT instruction can be used to acheive the effect of a CASE statement, as
in the following example:
xct @[ call foo
move q1, p1
jfcl
aos q1 ](t1)
where t1 contains the case index, which should have a value (in this case)
between 0 and 3.
Instruction Set Page 33
2.16.11. JFFO - Jump if Find First One
JFFO tests the selected AC. If C(AC)=0 then set C(AC+1) to zero and execute
the next instruction. If C(AC)<>0 then set C(AC+1) to the count of the number
of zero bits in C(AC) to the left of the first one bit and jump to the
effective address. C(AC) is unchanged.
2.17. References
The following manual presents the instruction set of the PDP-10/DECSYSTEM-20
in complete detail:
DECsystem-10/DECSYSTEM-20 Hardware Reference Manual, Volume I,
Central Processor, EK-10/20-HR-001, Digital Equipment Corporation
(1978).
Historical information can be found in:
Bell, et al., "The Evolution of the DECsystem-10", CACM Jan 1978.
Macro Page 34
3. The DECSYSTEM-20 Macro Assembler
3.1. Introduction
This chapter presents excerpts from the DEC Macro-20 Reference
Manual. Certain advanced (or rarely used) features - mainly those
dealing with storage allocation and polish fixups - have been omitted;
see the actual manual if you must have them. Unfortunately, the Macro
manual does not present the material in a tutorial fashion; this
rendition of it is not much better than the original in that respect,
although examples have been added here and there, and explanations are
a little more thorough. Given the absence of a good tutorial, the
best approach to teaching yourself Macro is to read through this
chapter from beginning to end to get an idea of what kinds of things
Macro does, and what its syntax is, and then to study some
well-written Macro programs.
At the time of this writing (3 July 1980), Macro suffers from
certain limitations traceable to its origins in Tops-10 (PDP-6,
really): symbols are limited to 6 characters in length, and input
(.MAC) and output (.REL, usually) files are limited to 6 characters in
the filename and 3 in the extension (file type).
Macro is the symbolic assembler program for the DECSYSTEM-20. The assembler
reads a file of Macro statements and composes relocatable binary machine
instruction code suitable for loading by Link, the system's linking loader.
Macro is a statement-oriented language; statements are in free format and are
processed in two passes. In processing statements, the assembler:
1. Interprets machine instruction mnemonics.
2. Accepts symbol definitions.
3. Interprets symbols.
4. Interprets pseudo-ops.
5. Accepts macro definitions.
6. Expands macros on call.
7. Assigns memory addresses.
8. Generates a relocatable binary program file ( .REL file) for input
to Link.
9. Optionally generates a program listing file showing source
statements, the corresponding binary code, and any errors found.
10. Optionally generates a universal ( .UNV) file that can be searched
during other assemblies.
The following conventions are used throughout this chapter:
1. All numbers in the examples are octal unless otherwise noted.
Macro Page 35
2. All numbers in the text are decimal unless otherwise noted.
3. The name of the assembler, Macro, is capitalized; references to
user-defined macros are in lower case.
3.2. Elements of Macro
The character set recognized in Macro statements includes all ASCII
alphanumeric characters and 28 special characters (ASCII 40 through 137
(octal)). Lowercase letters are not distinguished from uppercase letters.
Macro recognizes several ASCII control codes including horizontal tab (^I),
linefeed (^J), formfeed (^L), carriage-return (^M), and control-underscore
(^_). Macro accepts any ASCII character in quoted text, or in text argument
to the ASCII and ASCIZ pseudo-ops. The line continuation character, ^_, is
always effective. Delimiters for certain pseudo-ops (such as ASCII, ASCIZ,
and COMMENT) can be any nonblank, nontab ASCII character.
A Macro program consists of statements made up of Macro language elements.
Separated into general types, these are:
1. Special characters.
2. Numbers.
3. Literals.
4. Symbols.
5. Expressions.
6. Macro-defined mnemonics.
7. Pseudo-ops.
8. Macros.
The format of a Macro statement is discussed later.
3.2.1. Special Characters
Some characters and combinations of characters have special interpretations.
These interpretations apply only in the contexts described. In particular,
they do not apply within comment fields or text strings. Uparrow (^) is to be
taken literally, e.g. ^B means the uparrow character followed by a B, not
control-B.
Char(s) (Form) Context and Interpretation
B (mBn) Between 2 integer expressions, causes the binary
representation of m to be placed with rightmost bit at bit n
(decimal).
^B (^Bn) Before an integer expression, shows that n is a binary
Macro Page 36
(base 2) number.
^D (^Dn) Before an integer expression, shows that n is a decimal
number.
E (fE+n,fE-n,fEn) Between a floating-point decimal number and a signed decimal
integer, multiplies f by the +nth power of 10 (decimal).
^O (^On) Before an integer expression, shows that n is an octal number.
: (sym:) After a symbol, shows that sym is a label, i.e. that its value
is to become the current value of the location counter.
:: (sym::) After a symbol, shows that sym is a global INTERNAL label.
; (;text) Before the end of a line, shows that text is a comment.
;; (;;text) Before end of line (usually in a macro definition), shows that
text is a comment to be printed in the macro definition but
not at call, i.e. in macro expansion.
. (.) As an expression, is replaced by the current value of the
location counter.
, (,) Among numbers and symbols, delimits operands, accumulator,
arguments. In a macro call, delimits a null argument.
,, (lhw,,rhw) Between two expressions, delimits left halfword from right
halfword.
! (A!B) Between two expressions, generates the logical inclusive OR of
A and B.
^! (A^!B) Between two expressions, generates the logical exclusive OR of
A and B.
& (A&B) Between two expressions, generates the logical AND of A and
B.
^- (^-A) Before an expression, generates the logical complement of A
(NOT A).
* (A*B) Between two expressions, generates the product of A and B.
/ (A/B) Between two expressions, generates the quotient of A by B.
+ (A+B) Between two expressions, generates the sum of A and B.
- (A-B) Between two expressions, generates the difference of A and B.
- (-A) Before an expression, generates the two's complement of the
value of A.
" ("text") In pairs around text, shows that text is a 7-bit ASCII string,
to be right justified in a field of five characters.
' ('text') In pairs around text, shows that text is a SIXBIT string, to
be right justified in a field of six characters.
Macro Page 37
' (arg'text, text'arg) Adjoing a dummy argument in the body of a macro
definition, concatenates the value of the argument to the text
during macro expansion.
\ (\expr) Prefixed to an expression in a macro call, directs that the
argument passed be the string for the ASCII value of expr in
the current radix.
\' (\'expr) Prefixed to an expression in a macro call, directs that the
argument passed be the string whose SIXBIT code is the value
of expr.
\" (\"expr) Prefixed to an expression in a macro call, directs that the
argument passed be the string whose ASCII code is the value of
expr.
^_ (Control-underscore, not uparrow underscore) before a CRLF,
continues its argument to the next line. Does not operate
across end-of-macro.
_ (A_B) Between two expressions, shifts the binary representation of A
to the left B positions (if B is negative, shift is to the
right).
@ (@address) Prefixed to an address, sets bit 13 of the instruction word,
indicating indirect addressing.
% (%arg) As the first character of a dummy argument in a macro
definition, directs that %arg be replaced by a created symbol
during macro expansion; Macro will substitute a different
symbol for it on each invocation of the macro.
() Encloses index field, encloses dummy arguments in macro
definition or parameters in a macro invocation, quotes
characters for macro argument handling, swaps the two halves
of a value.
<> Nests expressions, encloses conditional assembly code,
encloses code in REPEAT, IRP, and IRPC pseudo-ops, encloses
macro body in DEFINE pseudo-op, quotes characters for macro
argument handling, forces evaluation of a symbol.
[] delimits literals (causing the contents of the brackets to be
moved to the literal pool, and the bracketed expression to be
replaced by the location of its contents); delimits argument
in ARRAY, .COMMON, and OPDEF pseudo-ops; quotes characters for
macro argument handling.
= (sym=expr) Between symbol and expression, assigns the value of expr to
sym.
=: (sym=:) Between symbol and expression, assigns the value of expr to
sym and declares sym to be global INTERNAL.
Macro Page 38
3.2.2. Numbers
The two properties of numbers that are important in Macro are
1. The radix (base) in which the number is written.
2. How the number should be placed in memory.
You can control the interpretation of these properties by using pseudo-ops or
special characters to indicate your choices.
3.2.2.1. Integers
Macro stores an integer in its binary form, right justified in bits 1 to 35 of
its storage word. If you use a sign, place it immediately before the integer
(if you omit the sign, the integer is assumed to be positive). For a negative
number, Macro first forms its absolute value in bits 1 to 35, then replaces it
by its two's complement. Therefore a positive integer is stored with 0 in bit
0, while a negative integer has 1 in bit 0.
The largest positive integer that Macro can store is 377777 777777 (octal);
the smallest (most negative) is 400000 000000 (octal).
3.2.2.2. Radix
The initial implicit radix for a Macro program is octal (base 8). The
integers you use in your program will be interpreted as octal unless you
indicate otherwise. You can change the radix to any base from 2 to 10 by
using the RADIX pseudo-op. The new radix will be in effect until you change
it again.
Without changing the prevailing radix, you can write a particular integer in
binary, octal, or decimal. To do this, prefix the integer with ^B for binary,
^O for octal, ^D for decimal. The indicated radix applies only to the single
integer immediately following it.
A single-digit number is always interpreted as radix 10. Thus 9 is seen as
decimal 9, even if the current radix is 8.
For example, suppose the current radix is 8. Then you can write the decimal
number 23 as:
27 octal (current radix)
^d23 decimal
^b10111 binary
but you cannot write decimal 23 as ^d45-22 since the ^d applies only to the
first number, 45; the 22 is still interpreted as octal. However, you can
write decimal 23 as ^d<45-22>.
Macro Page 39
3.2.2.3. Floating-point Decimal Numbers
In your program, a floating-point decimal number is a string of digits with a
leading, trailing, or embedded decimal point and an optional leading sign.
Macro recognizes this as a mixed number in radix 10.
Macro forms a floating-point decimal number with the sign in bit 0, a binary
exponent in bits 1 to 8, and a normalized binary fraction in bits 9 to 35.
The normalized fraction can be viewed as followed: its numerator is the binary
number in bits 9 to 35, whose value is less than 2 to the 28th power, but
greater than or equal to 2 to the 27th power. Its denominator is 2 to the
28th power, so that the value of the fraction is always less than 1, but
greater than or equal to 0. (This value is 0 only if the entire stored number
is 0.)
The binary exponent is incremented by 128 so that exponents from -128 to 127
are represented as 0 to 255.
For a negative floating-point number, Macro first forms its absolute value as
a positive number, then takes the two's complement for the entire word.
Examples:
The floating point number 17.0 generates the binary word
0 10 000 101 100 010 000 000 000 000 000 000 000
where bit 0 shows the positive sign, bits 1 to 8 show the binary exponent, and
bits 9 to 35 show the proper binary fraction. The binary exponent is 133
(decimal), which after subtracting the added 128 gives 5. The fraction is
equal to 0.53125 decimal. And 0.53125 times 2 to the 5th power is 17, which
is the number given.
Similarly, 153. generates
0 10 001 000 100 110 010 000 000 000 000 000 000
while -153. generates
1 01 110 111 011 001 110 000 000 000 000 000 000
These two examples show that a negative number is two's complemented. Notice
that since the binary fraction for a negative number always has some nonzero
bits, the exponent field (taken by itself) appears to be one's complemented.
As in Fortran, you can write a floating point decimal number with a suffixed
E+/-n, and the number will be multiplied by 10 to the +/-nth power. If the
sign is missing, n is assumed to be positive. Examples: 2840000. can be
written 284.E+4 or .284E7; .0000284 can be written .284E-4 or 284.E-7.
Using this E notation with an integer (no decimal point) is not allowed, and
causes an error. Therefore you can use 284.E4 but not 284E4.
Note: Macro's algorithm for handling numbers given with the E notation is not
identical for Fortran's. The binary values generated by the two translators
may differ in the lowest order bits.
Macro Page 40
3.2.2.4. Binary Shifting
Binary shifting of a number with Bn sets the location of the rightmost bit at
bit n in the storage word, where n is a decimal integer. The shift takes
place after the binary number is formed. Any bits shifted outside the range
(bits 0 through 35) of the storage word are lost.
For example, here are some numbers with their binary representations given in
octal:
300000 000000 ^d3b2
000000 042000 ^d17b25
000001 000000 1b17
777777 777777 -1b35
000000 000001 1b35
000000 777777 -1b17
3.2.2.5. Underscore Shifting
You can also shift a number by using the underscore operator. If V is an
expression with value n, suffixing _V to a number shifts it n bits to the
left. If n is negative, the shift is to the right.
In an expression of the form W_V, W and V can be any expressions including
symbols. The binary value of W is formed in a register, V is evaluated, and
the binary value of W is shifted V bits when placed in storage.
An expression such as -3.75E4_^d18 is legal, but the shift occurs after
conversion to floating point decimal storage format. Therefore the sign,
exponent, and fraction fields are all shifted away from their usual locations.
This is true also of other storage formats.
3.2.3. Literals
A literal is a character string within square brackets inserted in your source
code. Macro stores the code generated by the enclosed string in a literal
pool beginning with the first available literal storage location, and places
the address of this location in place of the literal. The literal pool is
normally at the end of the binary program.
The statements
Macro Page 41
ldb t1, [point 6, .JBVER, 17]
LIT
are equivalent to
ldb t1, foo
foo: point 6, .JBVER, 17
A literal can also be used to generate a constant:
push p, [0] ; Generate a zero fullword.
move q1, [3,,14] ; Generate a word with 3 in
; the left half and 14 in the right.
Multiline literals are also allowed:
getChr: ildb t2, t1 ; Get a character.
cain t2, 0 ; Is it a null?
jrst [ move t1, txtPtr ; Yes, use this pointer
ildb t2, t1 ; to get a new character.
cain t2, "?" ; Is it a question mark?
jrst [ move t1, txtPt2 ; Yes, use this pointer
ildb t2, t1 ; to get the message character,
jrst getHlp ] ; and go to the help routine.
ret ] ; Not a question mark, return from getChr.
ret ; Not a null, return with char in t2.
The text of a literal continues until a matching closing square bracket is
found (unquoted and not in a comment field).
A literal can include any term, symbol, expression, or statement, but it must
generate at least one but no more than 99 words of data. A statement that
does not generate data (such as a direct assignment statement or a RADIX
pseudo-op) can be included in a literal, but the literal must not consist
entirely of such statements.
You can nest literals up to 18 levels. You can include any number of labels
in a literal, but a forward reference to a label in a literal is illegal.
If you use a dot (.) in a literal to retrieve the location counter, remember
that the location counter is pointing at the statement containing the literal,
not at the literal itself. In nested literals, a dot location counter
references a statement outside the the outermost literal. In the sequence
jrst [ hrrz t1, v
caie t1, op
jrst .+1
jrst foo ]
skipe t3
the expression .+1 generates the address of skipe t3, not jrst foo.
Macro Page 42
Literals having the same value are collapsed in Macro's literal pool. Thus
for the statements
push p,[0]
caml t2,[0]
movei t1, [asciz /frotz/]
the same address is shared by the two literals [0], and by the null word
generated at the end of [asciz /frotz/]. Literal collapsing is suppressed for
those literals that contain errors, undefined expressions, or EXTERNAL
symbols.
3.2.4. Symbols
Macro symbols include:
1. Macro-defined pseudo-ops.
2. Macro-defined mnemonics.
3. User-defined macros.
4. User-defined opdefs.
5. User-defined labels.
6. Direct-assignment symbols.
7. Dummy arguments for macros.
Macro stores symbols in three symbol tables: one for opcodes and pseudo-ops,
one for macros and opdefs, and one for user defined labels and
direct-assignment symbols. An entry in one of these tables shows the symbol,
its type, and its value.
Symbols are helpful in your program because:
1. Defining a symbol as a label gives a name to an address. You can
use the label in debugging or as a target for program control
statements.
2. In revising a program, you can change a value throughout your
program by changing a single symbol definition.
3. You can give names to values to make computations clearer.
4. You can make values available to other programs.
Macro Page 43
3.2.4.1. Selecting Valid Symbols
Follow these rules in selecting symbols:
1. Use only letters, numerals, dots (.), dollar signs ($), and percent
signs (%). Macro will consider any other character (including
blank) as a delimiter.
2. Do not begin a symbol with a numeral.
3. If you use a dot for the first character, do not use a numeral for
the second. Do not use dots for the first two characters; doing so
can interfere with Macro's created symbols.
4. Make the first six characters unique among your symbols. You can
use more than six characters, but Macro will use only the first
six.
5. Don't choose symbols composed of 1 to 4 letters followed by a
percent sign; names of this form are reserved for new monitor
calls.
Examples:
velocity Legal, only "veloci" is heeded by Macro.
chg.vel Legal, only "chg.ve" is heeded by Macro.
chg vel Illegal, looks like two symbols to Macro.
chgVel Legal.
1stNum Illegal, begins with numeral.
.11111 Illegal, begins with dot-numeral.
..1111 Unwise, could interfere with created symbols.
3.2.4.2. Defining Symbols
You can define a symbol by making it a label or by giving its value in a
direct-assignment statement. Labels cannot be redefined, but
direct-assignment symbols can be redefined anywhere in your program.
You can also define special-purpose symbols called OPDEFs and macros using the
pseudo-ops OPDEF and DEFINE.
A label is always a symbol with a suffixed colon. A label is in the first
(leftmost) field of a Macro statement and is one of the forms:
errFound: Macro uses only "errfou".
case1: Legal label.
OK:contin: Legal; you can use more than one label at a location.
Macro Page 44
case2:: Double colon declares the label to be global INTERNAL.
When Macro processes the label, the symbol and the current value of the
location counter are entered in the user symbol table. A reference to the
symbol addresses the code at the label.
You cannot redefine a label to have a value different from its original value.
A label is relocatable if the address is represents is relocatable; otherwise
it is absolute.
You can define a direct-assignment symbol by associating it with an
expression. A direct assignment is in one of the forms:
symbol=expression - The symbol and the value of the expression are entered
together in the user symbol table.
symbol=:expression - The symbol and the value of the expression are entered
together in the user symbol table and the symbol is declared
INTERNAL.
You can redefine a direct-assignment symbol at any time; the new direct
assignment simply replaces the old definition.
Note:
If you assign a multiword value using direct assignment, only the
first word of the value is assigned to the symbol. For example,
A=asciz/abcdefgh/ is equivalent to A=asciz/abcde/, since only the
first five characters in the string correspond to code in the first
word.
3.2.4.3. Symbol-table Search Order
When you use a symbol in your program, Macro looks it up in the symbol tables.
Normal Macro searches the macro table first, then the opcode table, and
finally the user symbol table. However, if Macro has already found an
operator in the current statement and is expecting operands, then it searches
the user symbol table first.
3.2.4.4. Symbol Attributes
Each symbol in your program has one of the following attributes: local,
INTERNAL global, or EXTERNAL global. This attribute is determined when the
symbol is defined.
A local symbol is defined for the use of the current program only. You can
define the same symbol to have different values in separately assembled
programs. A symbol is local unless you indicate otherwise.
A global symbol is defined in one program, but is also available for use in
other programs. Its table entry is visible to all programs in which the
symbol is declared global. A global symbol must be declared INTERNAL in the
progam where it is defined; it can be defined in only one program. In other
programs sharing the global symbol, it must be declared EXTERNAL; it can be
Macro Page 45
EXTERNAL in any number of programs.
To declare a symbol as INTERNAL global, you can:
1. Use the INTERN pseudo-op, e.g. INTERN flag1
2. Insert a colon after the "=" in a direct assignment statement, e.g.
flag2=:200.
3. Use an extra colon with a label, e.g. flag3::.
4. For subroutine entry points, use the ENTRY pseudo-op, e.g.
ENTRY foo.
To declare a symbol as an EXTERNAL global, you can use the EXTERN pseudo-op,
e.g. EXTERN flag4.
3.2.5. Expressions
You can combine numbers and defined symbols with arithmetic and logical
operators to form expressions. You can nest expressions by using angle
brackets. Macro evaluates each expression (innermost nesting levels first),
and either resolves it to a fullword value, or generates a Polish expression
to pass to Link.
3.2.5.1. Arithmetic Expressions
An arithmetic expression can include any number or defined symbol, and any of
the following operators +, -, *, /. Examples (in which words, x, y, and z
have been defined elsewhere):
movei t3, words/5
addi q2, <x+y-z>
addi q2, <<words/5>+1>*5
3.2.5.2. Logical Expressions
A logical expression can include any number or defined symbol whose value is
absolute, and any of the operators &, !, ^!, ^-. Each of the binary
operations &, !, and ^! generates a fullword by performing the indicated
operation over corresponding bits of the two operands. For example, a&b
generates a fullword whose bit 0 is the result of a's bit 0 ANDed with b's bit
0, and so forth for all 36 bits.
Macro Page 46
3.2.5.3. Evaluating Expressions
Macro has a hierarchy of operations in evaluating expressions. In an
expression without nests (angle brackets), Macro performs its operations in
this effective order:
1. All unary operations and shifts: +, -, ^-, ^d, ^o, ^b, b (binary
shift), _ (underscore shift), E.
2. Logical binary operations (from left to right): !, ^!, &.
3. Multiplication and division (from left to right): *, /.
4. Addition and subtraction (binary operations): +, -.
You can override this hierarchy by using angle brackets to show what you want
done first. For example, suppose you want to calculate the sum of a and b,
divided by c. You cannot do this with a+b/c because Macro will perform the
division b/c first, then add the result to a. With angle brackets you can
write the expresssion <a+b>/c to force Macro to add a and b first, then divide
the result by c.
Expressions can be nested to any level. The innermost nest is evaluated
first; the outermost last. Some examples of legal expressions (assuming that
a1, b1, and c are defined symbols) are:
a1+b1/5
<a1+b1>/5
^-a1&b1^!c
^b101b17-^d98+6
An expression given in halfword notation <lefthalf,,righthalf> has each half
evaluated separately in a 36-bit register. Then the 18 low-order bits of each
half are joined to form a fullword. For example, the expression <4,,6>/2
generates the value 000002 000003.
Macro Page 47
3.3. Pseudo-ops
A pseudo-op is a statement that gives the assembler information to allow it to
assemble your program in the desired way. For example, the pseudo-op RADIX
does not generate code itself, but tells Macro how to interpret numbers in
your program. The pseudo-op EXP generates one word of code for each argument
given with it.
To use a pseudo-op in your program, follow it with a space or tab, and any
required or optional arguments or parameters.
This section describes the use and functions of each pseudo-op. The headings
for each description, if applicable, are Format, Function, Examples, and
Optional Notations.
3.3.1. ARRAY
Format ARRAY sym[expression]
Expression is an integer value (to be intterpreted in the
current radix, indicating the number of words to be allocated;
the expression cannot be EXTERNAL, relocatable, or negative.
Note that although the expression must be in square brackets,
this use of the brackets is completely unrelated to literals.
Function Reserves a block of storage whose length is the value of the
expression, and whose location is identified by the symbol.
Storage is allocated along with other variable symbols in the
program, usually at the end. The allocated storage is not
necessarily zeroed.
3.3.2. ASCII
Format ASCII dtextd
where d = delimiter; first nonblank character, whose second
appearance terminates the text, and text = a string of text
characters to be entered.
Function Enters ASCII text in the binary code. Each character uses
seven bits. Characters are left justified in storage, five
per word, with bit 35 in each word set to 0, and any unused
bits in the last word set to 0.
Examples
ASCII /This is a string/
ascii !ps:<frotz>foo.txt!
Ascii?foo?
Optional Notations: Omit the space or tab after ASCII. Not allowed if the
delimiter is a letter, number, dot, dollar or percent sign
(i.e. a possible symbol constituent), or if the delimiter
character is a control character.
Macro Page 48
Right-justified ASCII can be entered by using double quotes to
surround up to five characters, as in: movei t1, "A".
3.3.3. ASCIZ
Exactly like ASCII, except that a trailing null is guaranteed, even if an
extra word of nulls must be added. Most Tops-20 monitor calls expect strings
to be in this format.
3.3.4. BLOCK
Format BLOCK expression
where the expression is not EXTERNAL or relocatable, and
evaluates to a positive integer.
Function Reserves, at the point of invocation, a block of locations
whose length is the value of the expression. The location
counter is incremented by this value. The allocated locations
are not necessarily zeroed. Note that the BLOCK pseudo-op
does not generate or store code; therefore it should not be
used in a literal, since this will result in overwriting the
reserved space during literal pooling.
Examples
BLOCK 500
block <^d512/5+1>
block <$nPag_9 - fooLen>
Optional Notations: Use the pseudo-op Z inside literals.
3.3.5. BYTE
Format BYTE bytedef ... bytedef
bytedef = (n)expression, ..., expression
n = byte size in bits; n is a decimal expression in the range
1 to 36.
Function Stores values of expressions in n-bit bytes, starting at bit 0
of the storage word. The first value is stored in bits 0 to
n-1; the second in bits n to 2n-1, and so forth for each given
value. If a byte will not fit in the remaining bits of a
word, those bits are zeroed and the byte begins in bit 0 of
the next word. If a value is too large for a byte, it is
truncated on the left. If the byte size is 0 or is missing
(empty parentheses), a zero word is generated.
Examples
Macro Page 49
V=2
BYTE (6),5,0,,101,5,V
generates the storage value 050000 010502. The two commas
indicate a null argument; the 101 (octal) is too large for the
byte size and is left truncated.
byte (6)7,0,1(9)7,0,1,"A"
generates two words: 070001 007000 and 001101 000000. Notice
that "A" is right-justified in its 9-bit byte.
Note that a comma before a left parenthesis will generate a
null byte.
3.3.6. COMMENT
Format COMMENT dtextd
d = delimiter; the first nonblank character, whose second
appearance terminates the text.
Function Treats the text between the delimiters as a comment. The text
can include carriage returns to facilitate multiline comments.
Optional Notations: Omit the space or tab after COMMENT. This is not allowed
if the delimiter is a valid character for identifiers, or is a
control character. Use a semicolon (;) to make the rest of
the line into a comment. Be careful not to use the delimiter
in the text of the comment, and avoid the use of nonprinting
delimiters.
Example :
foo: comment | Subroutine Foo
This subroutine writes a poem in the style of a given poet.
Enter with:
t1/ Pointer to asciz name of poet.
t2/ Destination designator for poem.
t3/ Pointer to asciz string describing desired topic.
Returns:
+1: always, with t1, t2, and t3 updated appropriately.
|
Macro Page 50
3.3.7. DEC
Format DEC expression, ..., expression
Function Defines the local radix for the line as decimal, then enters
the value of each given expression in a fullword of code. The
location counter is incremented by 1 for each expression.
Example DEC 10, 938, 512, 4.5, 6.03E-5
Optional Notation: Use the EXP pseudo-op and prefix ^d to each expression
that must be evaluated in radix 10.
3.3.8. DEFINE
Format DEFINE macroName(dArgList)<macroBody>
where
- macroName is a symbolic name for the macro being
defined. This name must be unique among all macro
and OPDEF symbols.
- dArgList is a list of dummy arguments.
- macroBody is the source code to be assembled when
the macro is invoked.
Function defines the macro. See the section on macros.
3.3.9. END
Format END expression
where expression is an optional operand that specifies the
address of the first instruction to be executed, which can be
EXTERNAL, in the right half and, optionally, the length of the
entry vectory in the left.
Function Must be the last statement in a Macro program. Statements
after END are ignored. The starting address is optional and
normally is given only in the main program (since subroutines
are called from the main program, they should not specify a
starting address). When the assembler first encounters an END
statement, it terminates pass 1 and begins pass 2. The END
terminates pass 2 on the second encounter, and unallocated
literals and variables (e.g. ARRAYs) are assembled at the
current location.
Examples:
end
end start
end <3,,entVec>
Macro Page 51
end <evLen,,entVec>
3.3.10. ENTRY
Format ENTRY symbol, ..., symbol
Each symbol is the name of an entry point in a library
subroutine.
Function Defines each symbol in the list following the ENTRY pseudo-op
as an INTERNAL symbol, and puts appropriate information in the
.REL file to allow the symbols to be included in an index
(such as that constructed by the MAKLIB program). Each symbol
must correspond to a label of the same name. Programs
referring to these symbols must, of course, declare them
EXTERNAL.
3.3.11. EXP
Format EXP expression, ..., expression
Function Enters the value of each expression in a fullword of code.
3.3.12. EXTERN
Format EXTERN symbol, ..., symbol
Function Identifies symbols as being defined in other programs.
EXTERNAL symbols cannot be defined within the current program.
At load time, the value of an EXTERNAL symbol is resolved by
Link if you load a module that defines the symbol as an
INTERNAL symbol; if you do not load such a module, Link gives
an error message for the undefined global symbol(s).
3.3.13. IFx Group
Gives criterion and code for conditional assembly. A symbol or expression
used to define the conditions for assembly must be defined before Macro
reaches the conditional statement. If the value of such a symbol or
expression is not the same on both assembly passes, a different number of
words of code may be generated (resulting in a phase error).
The forms of IF pseudo-op are listed below; in the first six forms, n is the
value of the given expression.
IFE expression,<code> - assemble code if n=0.
IFN expression,<code> - assemble code if n not = 0.
IFG expression,<code> - assemble code if n>0.
Macro Page 52
IFGE expression,<code> - assemble code if n>=0.
IFL expression,<code> - assemble code if n<0.
IFLE expression,<code> - assemble code if n<=0.
IF1 <code> - assemble code on Pass 1.
IF2 <code> - assemble code on Pass 2.
IFDEF symbol,<code> - assemble code if the symbol is defined as user-defined,
an opcode, or a pseudo-op.
IFNDEF symbol,<code> - assemble code if the symbol is not defined as
user-defined, an opcode, or a pseudo-op. Code is also
assembled if the symbol has been referenced, but is not yet
defined. This can occur during pass 1.
IFIDN <string1><string2>,<code> - assemble code if the strings are identical.
IFDIF <string1><string2>,<code> - assemble code if the strings are different.
IFB <string>,<code> - assemble code if the strings contain only blanks and
tabs.
IFNB <string>,<code> - assemble code if the string does not contain only
blanks and tabs.
Example:
$cc=$cc+1 ; Count a character.
ifg <$cc-5>,< ; Word overflowed?
$cc=0 ; Yes, reset character counter
$wc=$wc+1 ; and count a word.
>
Optional notations: Omit angle brackets enclosing code for single-line
conditionals. For IFIDN, IFDIF, IFB, and IFNB only: use a
nonblank, nontab character other than < as the initial and
terminal delimiters for a string (as in the pseudo-ops ASCII
and ASCIZ); you can then include angle brackets in the string.
3.3.14. INTERN
Format INTERN symbol, ..., symbol
Function Declares each given symbol to be INTERNAL global; therefore
its definition, which must be in the current program, is
available to other programs at load time. Each such symbol
must be defined as a label, a variable, or a direct assignment
symbol. OPDEF symbols can be declared INTERNAL, and thus be
made available to other programs at load time. However, if
the current program has another symbol (besides the OPDEF
symbol) of the same name, the INTERNAL declaration will apply
to that symbol rather than to the OPDEF symbol.
Macro Page 53
3.3.15. IOWD
Format IOWD exp1,exp2
Function Generations a word in a special format for use by all five
pushdown stack instructions (adjsp, push, pop, pushj, popj),
as well as for i/o instructions (hence its name). The left
half of the assembled word contains the 2's complement of the
value of exp1, and the right half contains the value exp2-1.
Example: Setting up a pushdown stack.
stkLen=100
array stack[stkLen]
move p, [iowd stkLen,stack]
3.3.16. IRP
Format IRP arg,<code>
where arg is one of the dummy arguments of the enclosing macro
definition; you can only use IRP in the body of a macro
definition.
Function Generates one expansion of the code enclosed in angle brackets
for each subargument of the string that replaces arg. Each
occurrence of arg within the expansion is replaced by the
subargument currently controlling the expansion (see the
section on macros).
Example:
define sum(a,b)<
movei q, 0
irp a,<add q,a>
movem q, b
>
sum (<x,y,z>,foo)
This invocation of sum is replaced by:
movei q, o
add q, x
add q, y
add q, z
movem q, foo
Macro Page 54
3.3.17. IRPC
Format IRPC arg,<code>
Function Generates one expansion of the bracketed code for each
character of the string that replaces arg (a dummy argument of
the enclosing macro definition). Each occurrence of arg
within the expansion is replaced by the character currently
controlling the expansion. Concatenation and line
continuation are not allowed across end-of-IRPC, since a
carriage return and linefeed are appended to each expansion.
Example:
define deposit (string,bp)<
irpc string, <
movei q, "string"
idpb q, bp
>
>
deposit <foo>,x
expands to:
movei q, "f"
idpb q, x
movei q, "o"
idpb q, x
movei q, "o"
idpb q, x
3.3.18. LIT
Format LIT
Function Assembles literals beginning at the current address. The
literals assembled are those found since the previous LIT, or
since the beginning of the program, whichever is later. The
location counter is incremented by 1 for each word assembled.
A literal found after the LIT is not affected. It will be
assembled at the next following LIT, or at the END statement,
whichever is earlier. Literals having the same value are
collapsed in Macro's literal pool.
3.3.19. OCT
Format OCT expression, ..., expresssion
Function Defines the local radix for the line as octal; the value of
each each expression is entered in a fullword of code. The
location counter is incremented by 1 for each expression.
Equivalent to using EXP with each argument prefixed by ^o.
Macro Page 55
3.3.20. OPDEF
Format OPDEF symbol[expression]
Function Defines the symbol as an operator equivalent to the
expression, giving the symbol a fullword value. When the
operator is later used with operands, the accumulator fields
are added, the indirect bits are ORed, the memory addresses
are added, and the index register addresses are added. An
OPDEF can be declared INTERNAL, using the INTERN pseudo-op.
However, if a symbol of the same name exists, the INTERNAL
declaration will apply only to that symbol, and not to the
OPDEF. Although the expression portion of an OPDEF must be in
square brackets, this use of the brackets is completely
unrelated to literals or literal handling.
3.3.21. POINT
Format POINT byteSize,address,bitPosition
Function Generates a byte pointer word for use with the machine
language byte instructions adjbp, ldb, ibp, ildb, and idbp.
The byteSize gives the decimal number of bits in the byte, and
is assembled in bits 6 to 11 of the storage word. Address
gives the location of the word containing the byte, and is
assembled in bits 13 through 35 (with normal indirect, index,
and offset fields). BitPosition gives the position (in
decimal) of the rightmost bit in the byte. Macro places the
value <35-bitPosition> in bits 0-5 of the storage word. The
default bitPosition is -1, so that the byte increment
instructions ipb, ildb, and idpb will operate on the first
byte in the address word.
3.3.22. PRGEND
Format PRGEND
Function Replaces the END statement for all except the last program of
a multiprogram assembly. PRGEND closes the local symbol table
for the current module. You can use PRGEND to place several
small programs into one file to save space and disk accesses.
The resulting binary file can be loaded in library search mode
(refer to the Link and MakLib manuals for more information
about this). PRGEND is not allowed in macros. Like END,
PRGEND causes the assembly of all unassembled literals. In a
file containing PRGENDs, using more than one LIT pseudo-op in
any but the last program produces unpredictable results. A
starting address for the program terminated by PRGEND may
optionally be given as an argument to PRGEND.
Macro Page 56
3.3.23. PRINTX
Format PRINTX text
Function Causes text to be output at the terminal during assembly,
normally once for each pass.
Example:
define prVal (v,msg)<printx [msg v]>
if2, <
$$len=.-buffer
prVal \$$len, <Size of buffer (in words):>
ifg <.-20000>,<printx <Buffer too big!>>
>
3.3.24. PURGE
Format PURGE symbol, ..., symbol
Function Deletes symbols from the symbol tables. Normally used at the
end of a program to fix multiply defined global symbol errors
that occur at Link time, or to remove unwanted symbols from
DDT typeout. If you use the same symbol for both a macro name
or OPDEF and a label, a PURGE statement deletes the macro name
or OPDEF. Repeating the PURGE statement then purges the
label.
3.3.25. RADIX
Format RADIX expression
Function Sets the radix to the value of the expression, which is
interpreted in decimal, and must be in the range 2 to 10. An
implicit RADIX 8 statement begins each Macro program. All
numerical expressions that follow (up to the next RADIX
pseudo-op) are interpreted in the given radix unless another
local radix is indicated via ^d, ^o, ^b, OCT, DEC, etc.
Ordinarily, numbers outside the range of the given radix are
not interpreted. For example, in radix 8, the number 99
causes an error. However, a single-digit number is
interpreted in any case. For example, in radix 8, the number
9 is recognized as octal 11.
3.3.26. REPEAT
Format REPEAT expression,<code>
Function Generates the bracketed code n times, where n is the value of
the expression, and must be a nonnegative integer. REPEAT
statements can be nested to any level. Line continuation is
Macro Page 57
not allowed across end-of-REPEAT, since a carriage return and
linefeed are appended to each expansion of the code. Note
that REPEAT 0,<code> is logically equivalent to a false
conditional (and is often used to "comment out" a large
section of code), and REPEAT 1,<code> is logically equivalent
to a true conditional.
3.3.27. .REQUIRE
Format .REQUIRE filespec
Function Causes the specified file to be loaded automatically at Link
time. The filespec must not include a file type, and it must
be a Tops-10 (not Tops-20!) file specification.
3.3.28. SEARCH
Format SEARCH tableName(fileName), ..., tableName(fileName)
Function Defines a list of symbol tables for Macro to search if a
symbol is not found in the current symbol table. A maximum of
ten tables can be specified. Tables are searched in the order
specified. When the SEARCH pseudo-op is seen, Macro checks
its internal UNIVERSAL tagble for a memory-resident UNIVERSAL
of the specified name. If no such entry is found, Macro reads
in the symbol table using the given file specification. If no
file specification is given, Macro reads tableName.UNV from
the connected directory, and on failure tries the same
filename in UNV: and SYS:, in that order. When all the
specified files are found, Macro builds a table for the search
sequence. If Macro cannot find a given symbol in the current
symbol table, the UNIVERSAL tables are searched in the order
specified. When the symbol is found, it is moved into the
current symbol table. This procedure saves time (at the
expense of core) on future references to the same symbol. A
UNIVERSAL file can search other UNIVERSAL files, provided all
names in the search list have been assembled.
Optional notation: Omit the filename and its enclosing parentheses. Macro
then looks on DSK:, UNV:, and SYS: (in that order) for
tableName.UNV.
3.3.29. SIXBIT
Format SIXBIT dtextd
d = delimiter (first nonblank character, whose second
appearance terminates the text)
Function Enters strings of text characters in 6-bit format. Six
characters per word are left justified in sequential storage
words. Any unused bits are set to zero. Lowercase letters in
Macro Page 58
SIXBIT text strings are treated as uppercase. Otherwise, only
the SIXBIT character set allowed. The SIXBIT character set
consists of all the printable ASCII characters except
lowercase letters, and the following symbols: `{|}~. The
values of the SIXBIT characters are 0-77 (octal); they are
offset from the corresponding ASCII values by octal 40, e.g.
ASCII "A" is 101, and SIXBIT "A" is 41. Historically, this
was a popular format for the storage of strings whose maximum
length was 6, such as filenames or program names under
Tops-10, because it allowed word comparisons and transfers
instead of slower byte manipulations.
Optional Notation: Right-justified SIXBIT can be entered by using single
quotes to surround uf to six characters, as in
move t1, ['FOOBAZ']
3.3.30. STOPI
Ends an IRP or IRPC before all subarguments or characters are used. The
current expansion is completed, but no new expansions are started. STOPI can
be used with conditionals inside IRP or IRPC to end the repeat if the given
condition is met.
3.3.31. SUBTTL
Format SUBTTL String
Function Defines a subtitle (of up to 80 characters) to be printed at
the top of each page of the listing file until the end-of-
listing or until another SUBBTL statement is found. The
initial SUBTTL usually appears on the second line of the first
page of the input file, immediately following the TITLE
statement. For subsequent SUBTTL statements, the following
rule applies: if the new SUBTTL is on the first line of a new
page, then the new subtitle appears on that page; if not, the
new subtitle appears on the next page. Even if you do not
plan to generate listing files, SUBTTL is still a useful
documentation device, and is recognized by certain programming
aids.
3.3.32. TITLE
Format TITLE String
Function Gives the program name and a title to be printed at the top of
each page of the program listing. The first characters (up to
6) are the program name; the program is saved by this name
unless another is explicitly given in the 'save' command. In
addition, the name is used when debugging with DDT to gain
access to the program's symbol table. Only one TITLE is
allowed per module (file or section of file delimited by
Macro Page 59
PRGEND's). The TITLE statement usually appears as the first
line of a program. If no TITLE statement is used, the
assembler inserts the program name ".MAIN".
3.3.33. XWD
Format XWD leftHalf,rightHalf
Function Enters two halfwords in a single storage word. Each half is
formed in a 36-bit register, and the low-order 18 bits are
placed in the halfword. The high-order bits are ignored.
Optional Notation: leftHalf,,rightHalf
3.3.34. Z
Format Z accumulator, address
Function Z is treated as if it were the null machine language mnemonic
( opcode). An instruction word if formed with zeros in bits 0
to 8. The rest of the word is formed from the accumulator an
address. If the accumulator and address fields are omitted, a
zero word is assembled.
3.4. Macro Statements and Statement Processing
A Macro statement has one or more of the following: a label, an opcode, zero
or more operands, and a comment. The general form of a macro statement is:
label: operator operand, operand ; Comment.
A carriage return ends the statement.
Direct assignment statements receive special handling.
Processing of macros is not discussed in this section because a macro call
produces text substitution. After substitution, the text is processed as
described in this section. Macros are discussed in their own chapter.
3.4.1. Labels
A label is always a symbol with a suffixed colon. The assembler recognizes a
label by finding the colon. If a statement has labels (you can use more than
one), they must be the first elements in the statement.
A label can be defined only once; its value is the address of the first word
of code generated after it.
Macro Page 60
Since a label gives an address, the label can be either absolute or
relocatable. A label is a local symbol by default, but you can declare a
label to be INTERNAL globel or EXTERNAL global.
3.4.2. Operators
After processing any labels, the assembler views the first group of following
nonblank, nontab characters as a possible operator. An operator is one of the
following:
1. A mnemonic symbol defined by Macro to stand for a machine opcode
(see Chapter 2).
2. A user-defined operator, such as an OPDEF or macro invocation.
3. A Macro pseudo-op.
If the characters found do not form one of the above, Macro views them as an
expression.
An operator is ended by the first non-alphanumeric character that is not a .,
$, or %. If it is ended by blank or tab, operands may follow; if it is ended
by a semicolon, there are no operands and the comment field begins; if it is
ended by a carriage return, the statement ends and there are no operands or
comments.
3.4.3. Operands
After processing labels and the operator, if any, the assembler views as
operands all characters up to the first unquoted semicolon or carriage return.
Unquoted commas delimit the operands.
The operator in a statement determines the number (none, one, two, or more)
and kinds of permitted or required operands. Any expected operand not found
is interpreted as null. An operand can be any expression or symbol
appropriate for the operator.
Examples:
loop: move t1, x
%print <x is %d, y is %d>,<exp t1, y>
In the first line, t1 and x are operands. In the second line, a macro,
%print, is invoked with two operands. Each of these operands is quoted by
enclosing it in angle brackets; this is necessary because each operand
contains an internal comma.
Macro Page 61
3.4.4. Comments
The first unquoted semicolon in a statement begins the comment field. You can
use any ASCII characters in a comment; however, angle brackets in a comment
may produce unpredictable results (such as unexpected termination of a macro
definition or conditional-assembly code) and should be avoided.
If the first nonblank, nontab character in a line is a semicolon, the entire
line is a comment. You can also enter a full line of comment with the
pseudo-op REMARK, or a multiline comment with the pseudo-op COMMENT.
Comments do not affect binary program output.
3.4.5. Statement Processing
Macro processes your program as a linear stream of data. During Pass 1 of an
assembly, Macro may find references to symbols not yet defined in the user
symbol table. Whenever a symbol is defined, it is entered in the table with
its value, so that on Pass 2 all definitions can be found in the table. The
values then replace the symbols in the binary code that is generated.
Note: Delayed definition is allowed only for labels and direct-
assignment symbols. A symbol that contributes to code generation (for
example, an OPDEF, a macro, or a REPEAT index) must be defined before
any reference to it.
Statement processing proceeds as follows:
1. Labels are found and entered in the user symbol table.
2. The next characters up to the first unquoted semicolon, blank, tab,
comma, or equal sign are processed:
a. Equal sign: the preceding characters form a symbol, and the
following characters form an expression. The symbol and the
value of the expression are entered in the user symbol table.
b. Other delimiter: the preceding characters form an expression
or an operator. If an operator, it is found in a table and
assembled. If an expression, its value is assembled.
If the operator takes operands, the next characters up to the first
unquoted semicolon or carriage return form operands. Unquoted
commas delimit operands. For each operand, leading and trailing
blanks and tabs are ignored. Operands are evaluated and assembled
for the given operator.
3. The first unquoted semicolon ends processing of the line. Any
further characters up to the first carriage return are comment.
4. The first unquoted carriage return ends the statement. Any
following characters begin a new statement.
Macro Page 62
3.4.6. Assigning Addresses
Macro normally (and by default) assembles statements with relocatable
addresses. Assembly begins with the zero storage word and proceeds
sequentially. Each time Macro assembles a word of binary code, it increments
its location counter by 1.
A mnemonic operator generates one word of binary code. Direct assignment
statements and some pseudo-ops do not generate any binary code. Some
pseudo-ops generate one or more word of binary code.
You can control address assignment by setting the assembler's location counter
using the pseudo-ops LOC and RELOC. You can also reference addresses relative
to the location counter by using the dot symbol (.). For example, the
expression .-1 used as an address refers to the location immediately preceding
the current location. Use of this construction is not encouraged (see Chapter
8), because you can cause an incorrect address to be assembled by adding or
removing statements withing the range of a .+n expression. Labels should be
used except when n = plus or minus 1.
3.4.7. Machine Instruction Mnemonics and Formats
An instruction is in one of the following forms:
mnemonic accumulator, address
mnemonic accumulator,
mnemonic address
where "mnemonic" evaluates to a machine operation code (opcode), "accumulator"
is an accumulator (or register) address, and "address" is a memory address,
possibly modified by indexing, indirect addressing, or both.
The accumulator address can be any expression whose value is in the range 0 to
17 (octal).
The memory address gives a location in memory, and can be any expression or
symbol whose value is an integer in the range 0 to octal 777777.
You can modify the memory address by indirect addressing, indexed addressing,
or both. For indirect addressing, prefix an at-sign (@) to the memory address
in your program. For indexed addressing, suffix an index register address in
parentheses to the memory address in your program. This address can be any
expression or symbol whose value is an integer in the range 1 to octal 17.
Note: To assemble the index, Macro places the index register
address in a fullword of storage, swaps its halfwords (as it does to
any expression in parentheses), and then adds the swapped word to the
instruction word.
Example (in which t1=1, temp=100, and x=3):
add t1, @temp(x)
This generates the following binary code:
Macro Page 63
instruction indirect
code bit memory address
010 111 000 0 001 1 0 011 000 000 000 001 000 000
accumulator index
register
The mnemonic ADD has the octal code 270, and this is assembled into bits 0 to
8. The accumulator goes into bits 9 to 12. Since the @ appears with the
memory address, bit 13 is set to 1. The index register goes into bits 14 to
17. Finally, the memory address is assembled into bits 18 to 35.
If any element is missing from a primary instruction, zeros are assembled in
its instruction word field.
3.4.8. Mnemonics with Implicit Accumulators
A few mnemonics set bits in the accumulator field as well as in the
instruction field. Therefore these mnemonics do not take accumulator
operands, and are of the form
mnemonic address
For example, JFOV gives the octal code 25504; JFCL gives 255. They both give
the opcode 255 in bits 0 to 8, but JFOV also sets the accumulator (bits 9 to
12) to binary 0001. This makes JFOV 100 equivalent to JFCL 1,100.
3.5. Using Macros
A macro is a sequence of statements defined and named in your program. When
you invoke a macro (by mentioning its name in your program), the sequence of
statements from its definition is generated in place of the invocation,
possibly with "arguments" plugged in.
By using macros with arguments, you can generate passages of code that are
similar, but whose differences are controlled by the arguments. This saves
repetition in building a source file.
3.5.1. Defining Macros
Before you can invoke a macro, you must define it. You can also redefine a
macro if you wish; the new definition simply replaces the old one.
To define (or redefine) a macro, use the pseudo-op DEFINE:
DEFINE macroName (dArgList)<macroBody>
where "macroName" is the name of the macro, "dArgList" is an optional list of
"dummy arguments", and "macroBody" is a sequence of statements. The macroName
is a symbol constructed according to the rules for symbols.
Macro Page 64
The optional dummy-argument list can give one or more dummy-argument symbols
through which values are passed to the sequence of statements. If a macro
definition has dummy arguments, they must be enclosed in parentheses. Use
commas as delimiters between dummy arguments. For each dummy argument,
leading and trailing spaces and tabs are ignored.
The macroBody is the sequence of statements you want to generate when you
invoke the macro. The macroBody must be enclosed in angle brackets.
Here is a sample macro definition:
define vMag (adrs,len) < ;; Vector Magnitude macro.
move t1, adrs ;; Get first component.
fmp t1, t1 ;; Square it.
move t2, adrs+1 ;; Get second component.
fmp t2, t2 ;; Square it
fad t1, t2 ;; and add in square of first.
move t2, adrs+2 ;; Third component...
fmp t2, t2 ;; squared...
fad t1, t2 ;; and added in to the sum.
call fSqrt ;; Go get the floating square root
movem t1, len ;; and store the result.
>
Note the double semicolons; this device allows comments to be included in
macro definitions but omitted from macro expansions.
3.5.2. Invoking Macros
You can invoke a macro by putting its name in your program. Recall that you
must define the macro before you can invoke it. You can use the macroName as
a label, an operator, or an operand.
If the macro's definition has dummy arguments, the macro invocation can have
arguments. The arguments passed to the macro are inserted into the defined
sequence of statements as it is generated. The first passed argument replaces
the first dummy argument; the second passed argument replaces the second dummy
argument; this treatment continues for each argument passed. Any missing
arguments are passed as nulls (zeros) or filled in by default arguments (see
below).
Note: if FOO is a macro with four dummy arguments, the call
FOO (a,,c) passes a and c as the first and third arguments. The
second argument is passed as null; it is not considered missing and
cannot be replaced by a default argument. The fourth argument is
missing and will be replaced by a default argument if one has been
defined; otherwise it will be passed as nulls.
After argument substitution, the defined sequence of statements replaces the
macroName and the argument list in the source text. For example, suppose you
have defined vMag(adrs,len) as shown in Section 3.5.1 above, and vMag is
invoked in your program as follows:
getMag: vMag coord, q1
Macro Page 65
Then the effect would be as if you had written the following code in your
program in place of the invocation of vMag:
getMag: move t1, coord
fmp t1, t1
move t2, coord+1
fmp t2, t2
fad t1, t2
move t2, coord+2
fmp t2, t2
fad t1, t2
call fSqrt
movem t1, q1
This code is called the "macro expansion"; the invocation of vMag has been
replaced by the macroBody from the definition of vMag, with the actual
arguments from the invocation (coord and q1) replacing the dummy arguments
from the definition (coord and len) throughout the text of the macroBody.
3.5.3. Macro Invocation Format
In a macro invocation, delimit the macroName with one or more blanks or tabs.
If the macro has arguments, the first nonblank, nontab character begins the
argument list. Each argument ends with a comma, a carriage return, or a
semicolon. These three characters cannot be used within arguments unless
enclosed by special quoting characters.
Leading spaces and tabs are stripped from each argument unless they are within
special quoting characters. Embedded spaces and tabs are not stripped.
Examples:
%erMsg eh?,errLoc
The macroName is %erMsg; the arguments are the strings "eh?" and
"errLoc".
%erMsg <Invalid foo, baz, or frotz>,errLoc
Here the first argument is quoted, because it contains commas.
%print <The coordinates are %d, %d, %d>,<
x
y
z
>
Here the first argument is quoted because it contains commas, and the second
argument is quoted because it contains carriage returns.
Macro Page 66
3.5.4. Quoting Characters in Macro Arguments
The special quoting characters for macro arguments are:
< > Angle brackets
( ) Parentheses
[ ] Square brackets
" " Doublequotes (but not single quotes (apostrophes))
Any character, including the semicolon (;), enclosed in special quoting
characters is treated as a regular character. If one of the special quoting
characters is to be passed as a regular character, it must be enclosed by
different special quoting characters.
Here are the rules for macro argument handling. In the examples, "foo" is
assumed to be a defined macro:
1. The special quoting characters are not argument delimiters. They
only tell the assembler to treat the enclosed characters as regular
characters.
foo c<a,b> has one argument: c<a,b>.
foo c,d<a,b> has two arguments: c and c<a,b>.
2. With the two exceptions explained below, special quoting characters
are always included in passed arguments.
foo a,(b,c) has two arguments: a and (b,c).
foo [xwd 1,L1]-1(ac) has one argument: [xwd 1,L1]-1(ac).
foo "(",0 has two arguments: "(" and 0.
Exceptions:
a. If the first character of the argument list is a left
parenthesis, then it and its matching right parenthesis
delimit the argument list. They are not treated as special
quoting characters and are not included in passed arguments.
All nested quoting characters except angle brackets are
disabled. After stripping the outer parentheses, angle
brackets are handled as described in Exception 2, below.
foo (a,b,c) has 3 arguments: a, b, and c.
foo (?Length > 132) has one argument: ?Length > 132.
foo ([a,b]) has two arguments: [a and b].
foo (<a,b>) has one argument: a,b.
b. If a left angle bracket is the first character of the
argument list, or the first character after an unquoted
comma, then it and its matching right angle bracket are
treated as special quoting characters, but are not included
in passed arguments.
Macro Page 67
foo <a,b>,c has two arguments: a,b and c.
foo c,<a,b> has two arguments: c and a,b.
3.5.5. Nesting Macro Definitions
You can define a macro within the body of another macro definition. The
nested macro is not defined to the assembler until the enclosing macro is
invoked. See the example in 3.5.6.
3.5.6. Concatenating Macro Arguments
The apostrophe (') is the concatenation operator for macro calls. If you
insert an apostrophe immediately before or after a dummy argument in the body
of a macro, the assembler removes it at invocation. This removal joins
(concatenates) the passed argument to the neighboring character in the
generated text.
If the apostrophe precedes the dummy argument, the passed argument is suffixed
to the preceding character; if the apostrophe is follows the dummy argument,
the passed argument is prefixed to the following character.
You can use more than one apostrophe with a dummy argument. In this case only
apostrophes next to the dummy argument will be removed (at most one from each
side). Other apostrophes are treated as regular characters in the macroBody.
The following example shows the treatment of apostrophes on both sides of the
dummy argument, and of double apostrophes:
define o (prefix,midfix) <
define ocomp (suffix) <
prefix'o'midfix''suffix
>
>
The invocation "o a,j" generates:
aoj'suffix
because when the assembler replaces "prefix" with "a", the apostrophe
following is removed to form "ao". When "j" replaces "midfix", the preceding
apostrophe and first following apostrophe are removed to form "aoj'suffix".
Now the invocation "ocomp le" generates "aojle" since the apostrophe is
removed to join "aoj" and "le".
3.5.7. Default Arguments and Created Symbols
Ordinarily, an argument missing from a macro invocation is passed as nulls.
For example, the macro defined by
Macro Page 68
define words (a,b,c) <
exp a,b,c
>
when invoked by "words 1,1" generates three words containing 1, 1, and 0,
respectively.
You can, however, alter this handling by specifying default values other than
nulls, or by using created symbols.
3.5.7.1. Specifying Default Values
If you want a missing argument to default to some value other than nulls, you
can specify the default value in your DEFINE statement. Do this by inserting
the default value in angle brackets immediately after the dummy argument. For
example, the macro defined by
define words (a,b<222>,c<333>) <
exp a, b, c
>
when invoked by "words 1,1" generates three words containing 1, 1, and 333,
respectively.
An argument passed as nulls by consecutive commas is NOT considered missing
and cannot cause a default value to be supplied. Therefore missing arguments
can occur only at the end of the list of passed arguments.
3.5.7.2. Created Symbols
A symbol used as a label in a macroBody must be different for each call of the
macro, since duplicate labels are not allowed. Therefore for each call a
different symbol for the label must be passed as an argument.
If you do not refer to such a label from outside the macro, you can simply let
the assembler provide a new label for each call. This label is called a
created symbol, and is of the form ..nnnn where nnnn is a 4-digit number.
To use a created symbol in place of a passed argument, use the percent sign
(%) as the first character of the dummy argument in your DEFINE statement.
The assembler then creates a symbol for use in the macro expansion if that
argument is missing from a call to the macro. If you provide an argument in
the call, the passed argument overrides the created symbol.
The argument is determined to be missing from, or present in, the macro
invocation in the same way in 3.5.7.1, i.e. only a trailing argument can be
missing.
Example:
Macro Page 69
define compare (test,save,index,%loc) <
%loc: move save, test
setz index,
came save, table(index)
jrst %loc
>
compare t1, t1, t3
expands to:
..0001: move t2, t1
setz t3,
came t2, table(t3)
jrst ..0001
while
compare t1, t2, t4, foo
expands to:
foo: move t2, t1
setz t4,
came t2, table(t4)
jrst foo
3.5.8. Indefinite Repetition
The pseudo-ops IRP, IRPC, and STOPI give a convenient way to repeat all or
part of a macro; you can change arguments on each repetition if you wish, and
the number of repetitions can be computed at assembly time. You can use these
three pseudo-ops only within the body of a macro definition.
To see how IRP works, assume the macro definition
define doEach (a) <
IRP a,<a>
>
The invocation "doEach <alpha,beta,gamma>" produces the code:
alpha
beta
gamma
because each subargument passed to IRP generates one repetition of the code.
Notice that the range of IRP must be enclosed in angle brackets.
Using angle brackets in the invocation of doEach is critical, since they make
the string "alpha,beta,gamma" a single argument for IRP. IRP then sees the
commas as delimiting subarguments.
IRPC is similar to IRP, but an argument passed to IRPC generates one
Macro Page 70
repetition for each character of the argument. See 3.3.17 for an example of
IRPC.
STOPI ends the action of IRP or IRPC after assembly of the current expansion.
You can use STOPI with a conditional assembly to calculate a stopping point
during assembly. Here's an example, in which IRPC is used to generate code to
copy either a whole string or the first five characters, whichever is shorter:
define copy5 (string, dest) <
$count=5
irpc string, < ;; Get a character from String.
movei t1, "string" ;; Copy it.
idpb t1, dest ;; ...
$count=$count-1 ;; Count it.
ife $count,<stopi> ;; If we've done 5, then quit.
>
>
3.5.9. Alternate Interpretations of Characters Passed to Macros
The normal argument passed by a macro call is simply the string of characters
given with the call. Macro offers three alternate interpretations of the
passed argument.
- If you prefix a backslash (\) to an expression argument, the
argument passed is the ASCII numeric character string giving the
value of the expression. See 3.3.23 for a useful example.
- If you prefix a backslash-apostrophe (\') to an expression argument,
the argument passed is the string whose value is the SIXBIT string
with the integer value of the expression.
- If you prefix backslash-doublequote (\") to an expression argument,
the argument passed is the string whose value is the ASCII string
with the integer value of the expression.
Illustration: a macro "foo" that just replaces itself by its argument can
work in many ways.
define foo (a) <
a
>
Sample invocations of foo; assume the following symbol definitions:
Z=60
ZZ='SIXBIT'
ZZZ="ASCII"
Invocation Expansion
foo 60 60
Macro Page 71
foo \60 60
foo \'60 P
foo \"60 0
foo Z Z
foo \Z 60
foo \'Z P
foo \"Z 0
foo ZZ ZZ
foo \ZZ 635170425164
foo \'ZZ SIXBIT
foo ZZZ ZZZ
foo \ZZZ 203234162311
foo \"ZZZ ASCII
3.6. Errors and Messages
Macro has three kinds of messages:
1. Informational messages
2. Single-character error codes
3. MCRxxx (where xxx is a 3-letter mnemonic code)
3.6.1. Informational Messages
This are found at the end of listings, and some of them are printed at your
terminal. The only truly useful one is:
UNASSIGNED DEFINED AS IF EXTERNAL
This message lists symbols that were not defined. A symbol can be undefined
for several reasons:
1. You forgot to define it, e.g. you referred to a label that you
forgot to include in your program.
2. You spelled it wrong either when defining it or when referring to
it.
3. You are referring to a symbol defined in another module, but you
forgot to declare it EXTERNAL in the current module.
Macro Page 72
3.6.2. Single-Character Error Codes
These cryptic and uninformative codes are printed at your terminal when Macro
encounters various kinds of errors.
A Argument error in pseudo-op.
D The statement refers to a multiply defined symbol.
E Improper use of EXTERNAL symbol.
L Literal generates less than 1 or more than 99 words of code.
M Symbol has already been defined; it will retain its first
definition.
N Number error.
O Opcode undefined, assembled as zeros.
P Phase error. In general, the assembler generates the same
number of locations on Pass 1 and Pass 2. Any discrepancy
causes a phase error.
Q Questionable. A broad class of warnings issued when the
assembler finds ambiguous language.
R Relocation error.
U Undefined Symbol.
V Symbol used to control the assembler is undefined.
X Error in defining or calling a macro during Pass 1.
3.6.3. MCRxxx Messages
These appear at your terminal during assembly, and are followed by an English
phrase that explains the problem, e.g.
MCRCFU - CANNOT FIND UNIVERSAL
The MCRxxx messages should be more or less self-explanatory.
Monitor Calls Page 73
4. Introduction to Tops-20 Monitor Calls
4.1. Introduction
This document contains all the information you need to do certain basic
monitor calls (mostly those for input/output) from assembly language programs
on the DECSYSTEM-20. Only a few of the many existing monitor calls are
described, and these are not always described in complete detail. Any
information not covered here can be found in most recent edition of the
DECSYSTEM-20 Monitor Calls Reference Manual.
Knowledge of the KL10 (DECSYSTEM-20) instruction set, and of an assembler
(preferably Macro-20), is assumed. All numbers in the following text, except
bit positions (which are always decimal), are octal (base 8) unless otherwise
noted.
4.2. General Information
Monitor calls are invocations of subroutines in the Tops-20 monitor. A DEC-20
monitor call is known as a JSYS (Jump to System). All JSYS's have opcode 104,
which is trapped by the monitor which in turn looks at the address field of
the instruction to find out which JSYS is being called. The following
conventions apply to all JSYS's:
Arguments for the JSYS are placed in accumulators (AC's). The first argument
is in AC1, the second in AC2, and so forth up to a maximum of four AC's. If
more than four arguments need to be passed, they are placed in an argument
block pointed to by an AC.
Results are also returned in AC's 1-4; if more than 4 results are to be
returned, they are returned in a block of memory whose address was specified
in the calling sequence. Any AC which does not return a result should have
the same contents after the call as before.
After execution of the JSYS, control is returned to the caller at one of two
locations. The +1 return (calling location plus 1) is often used to indicate
failure of the JSYS to perform its intended function, and an error code is
stored somewhere to indicate the exact cause of the failure. The +2 return is
used to indicate successful completion of the JSYS.
However, some JSYS's have only a single return to the instruction following
the call (+1) regardless of success or failure; this is the newer convention.
For this reason, it is generally not wise to depend on the +1/+2 convention;
another mechanism has been provided which should be used instead: erjmp/ercal.
Erjmp (which assembles as 'jump 16,') causes a jump to the specified location
if the JSYS, which must precede it immediately, failed. Ercal ('jump 17,')
works in the same way except it 'calls' rather than 'jumps'. Each JSYS, upon
encountering an error, inspects the contents of the instruction following the
JSYS call. If it is an erjmp or ercal, it takes the indicated action; if not,
it returns +1 or +2 according to its definition.
Every JSYS error has an associated error message, which provides a one-line
English description of the error, e.g.
Monitor Calls Page 74
?Directory access privileges required
The erring JSYS does not print the message; other JSYS's are provided to print
these error strings in a standard way (on the left margin, preceded by a
question mark). In general, recovery from a JSYS error involves printing the
error message and then either halting or going to some special section of code
that takes corrective action. Since these cases are overwhelmingly common,
let us assume that a special macro, called %jsErr, has been provided to take
care of them. It has the following format:
%jsErr message,address
If the message is specified, it is printed as a standard error message; if
not, the appropriate system-defined JSYS error message is printed. If the
address is specified, control will transfer to it after the message is
printed, otherwise the program will halt (but can be continued at the
instruction following the %jserr). Here are some examples (shown without
setting up the AC's):
GTJFN ; JSYS to Get Job File Number.
%jsErr ; Print standard message and halt on error.
GTJFN
%jsErr <Can't get the JFN> ; Print custom message, then halt.
GTJFN
%jsErr (,foo) ; Print standard message then go to foo.
A couple more examples not using the macro:
GTJFN
erjmp foo ; Go to foo on error.
GTJFN
ercal baz ; Call subroutine baz on error.
GTJFN
ercal [setz t1 ; Execute these instructions on error.
movei t2, 1
ret ] ; (ret = 'popj 17,')
movem t1, injfn ; Come here regardless of success or failure.
GTJFN
erjmp [setz t1 ; On failure, execute these instructions
movei t2, 1 ; ...
jrst foo ] ; then go to foo.
movem t1, injfn ; Come here only on success.
Erjmp and ercal are defined in monSym (i.e. in sys:monSym.unv) for Macro
programs, and predefined for Midas programs. %jsErr is defined, for Macro, in
CUSYM; jsErr is defined for Midas in MAC:MacSym.mid.
Monitor Calls Page 75
4.3. Using Mnemonic Symbols
Most JSYS's include among their arguments a number of arbitrarily chosen
numeric constants, including special numbers to designate the source for input
or output, and bits that can be on or off depending on whether the
corresponding option is selected. These bits are listed in the description of
each JSYS. Of course it is possible to write the (possibly combined) bits as
octal constants, but this would be extremely poor programming practice,
because the resulting code would be unreadable. Therefore, symbols have been
defined to stand for each bit. These symbols have some mnemonic value, and
they should always be used. The definitions appear in SYS:MONSYM.UNV, and you
access them from your Macro program by including the "search monSym"
directive. (Midas has the symbols built in.)
Some of the very common symbols that are not specific to any particular JSYS
are:
Value:
Symbol Left Half Right Half Meaning
------ --------- ---------- -------
.PRIIN 0 100 Primary input (usually TTY)
.PRIOU 0 101 Primary output (ditto)
.FHSLF 0 400000 Fork Handle Self (current process)
When a JSYS has option bits, these have symbols of the form JJ%NNN, where JJ
denotes which JSYS, and NNN denotes the option. The % is included to prevent
confusion with user defined symbols (which should not be of this form), and to
emphasize that the symbol stands for a JSYS bit. Examples:
Symbol JSYS Bit Meaning
------ ---- --- -------
GJ%NEW GTJFN 1 Want JFN for a new file.
GJ%OLD GTJFN 2 Want JFN for an old (i.e. existing) file.
OF%RD OPENF 19 Want to open a file for read access.
OF%WR OPENF 20 Want to open a file for write access.
4.4. Source/Destination Designators
Many monitor calls operate on or transmit byte streams; a byte stream is a
sequence of bytes of some size from 1 to 36 bits, most commonly 7 bit bytes
(ASCII text) or 36 bit bytes (machine words). The source or destination of
these bytes can be any one of several items, including a file, a terminal, or
a string in the caller's address space. In these cases, a standard 36-bit
quantity, called the source/designation designator, is used as a JSYS argument
to declare the byte stream on which to operate. It can have various formats;
these are the most common:
Monitor Calls Page 76
Value:
Symbol Left Half Right Half Meaning
------ --------- ---------- -------
(none) 0 a JFN Job file number, i.e. a file.
.PRIIN 0 100 Primary input (usually TTY).
.PRIOU 0 101 Primary output (usually TTY).
(none) reasonable address Pointer to beginning of a string
left half of in the caller's address space.
byte pointer.
(none) 777777 address Equivalent to 440700,,address,
i.e. a 7-bit byte pointer.
The monitor can tell which type of designator is intended either from its
format or from option settings which you provide. The last format is provided
to allow you to write
hrroi t1, [asciz/foo/]
rather than
move t1, [point 7, [asciz/foo/]] ; Macro
or
move t1, [440700,,[asciz/foo/]] ; Midas or Macro
This saves a memory reference, and it's easier to type. But it only works for
JSYS's, not for byte instructions; the JSYS internally translates 777777 in
the left half of a source/destination designator to 440700.
Note that JSYS's usually assume that an input byte string in memory (i.e. one
pointed to by a byte pointer) ends with a zero byte; strings are usually kept
in memory in this format, which is known as ASCIZ (7-bit ASCII, terminated by
zero).
4.5. Setting up a JSYS Invocation
You may have noticed that some of the JSYS bits described above fall in the
left half of the word, while others fall in the right half. This means that
to load the AC's with the appropriate bits could require different
instructions. Since programs should not depend on the actual values of the
symbols for JSYS bits, a macro is provided to free you from worrying about
whether a given symbol is a left-half or right-half quantity: the macro is
called MOVX; it translates to the appropriate instruction based on its
argument, e.g. if
JS%FOO = bit 35
JS%BAZ = bit 0,
() swaps its contents,
[] specifies the address of the enclosed quantity, and
! is the logical OR operator, then:
Monitor Calls Page 77
movx t1, JS%FOO (becomes) movei t1, JS%FOO
movx t1, JS%BAZ (becomes) movsi t1, (JS%BAZ)
movx t1, JS%FOO!JS%BAZ (becomes) move t1, [JS%FOO!JS%BAZ]
If you would rather avoid movx, you can use the third form; it will always
work, but it often costs an extra memory reference (and a little more typing).
One final complication: some JSYS arguments consist of fields which must take
on certain values. The desired value must somehow be logically ANDed with a
mask of 1's that specifies the field. For instance, the NOUT JSYS (which
outputs a number according to a format which you specify) accepts as one of
its arguments, the number of columns in which to print the number. This field
happens to be in bits 11-17. If you want the number to be printed in a field
of, say, 5 columns, you must put a 5 right-justified in bits 11-17. This
field has a name, NO%COL, and it assembles as 000177000000. It would be hard
to imagine how to logically AND a 5 with this field at assembly time.
Fortunately, a macro is provided for this purpose: FLD(value,mask), which in
this case would be written FLD(5,NO%COL). The result here is 000005000000,
which in turn can be logically ORed with other bits and fields to provide all
the information needed for the JSYS to return the desired result.
The FLD and MOVX macros are defined for Macro-20 in SYS:MACSYM.UNV.
Here's a fullblown example, in which the NOUT JSYS is set up to print a
number, which is stored at location foo, on the terminal in a field of 5
characters, usigned, with leading blanks, in base-4 notation. First, the
symbol definitions are reproduced from MONSYM:
Symbol Bit(s) Meaning
------ ------ -------
NO%MAG 0 Output the magnitude (i.e. unsigned).
NO%LFL 2 Output leading filler specified by NO%ZRO.
NO%ZRO 3 Output 0's as leading filler.
If off, output 1's as leading filler.
NO%COL 11-17 Number of columns to output.
NO%RDX 18-35 Radix (2-36) of number being output.
Now here's the actual JSYS setup and call:
movx t1, .PRIOU ; Output goes to terminal.
move t2, foo ; The number is stored in foo.
movx t3, NO%MAG!NO%LFL!fld(5,NO%COL)!fld(4,NO%RDX) ; Format.
NOUT ; Number Out JSYS.
%jserr ; Print message and halt on error.
This should be sufficient background for you to understand the descriptions of
the specific JSYS's.
4.6. JSYS's to Open and Close Files
A file in Tops-20 is identified by its device name, directory name, filename,
file type, and generation number. These 5 items uniquely identify any file on
the system that is accessible to a user. The device name identifies the
device on which the file is stored (or it can be a "logical device name" that
Monitor Calls Page 78
specifies a list of one or more devices and/or directories which is to be
searched for the file); the directory name identifies the directory containing
the file. The filename, type, and generation number identify a particular
file in the given device and directory.
Tops-20 requires references to files to be via "handles" that can be contained
in a few bits (a halfword, really) and do not require extensive lookup
procedures for each reference. Such a handle is called a JFN (Job File
Number); it is a small integer, valid within a particular job (even if the job
consists of many processes) but not valid across jobs; JFN 2 in job 11 will
generally be a handle on a completely different file than JFN 2 in job 18.
A JFN is associated with a file by means of the GTJFN (Get JFN) monitor call,
which accepts a file specification and returns a JFN for the indicated file.
The special JFN's 100 ( .PRIIN) and 101 ( .PRIOU) are reserved for the primary
input and output designators, respectively, and are never returned by the
GTJFN call.
To do i/o (input/output) to a file, you must first get a JFN for it, using
GTJFN. You must then open the file by giving the JFN to the OPENF JSYS. Then
you can use various monitor calls to actually transfer data. When you are
finished with the file, you must close it using the CLOSF monitor call.
These essential monitor calls are now described, but not in complete detail.
For the more esoteric features, refer to the Monitor Calls Reference Manual.
The examples shown here are for Macro programs. In general the only
difference between Macro and Midas (for these examples) the logical OR
operator (in Macro, it's "!"; in Midas it's "\")
4.6.1. GTJFN (JSYS 20) - Get Job File Number (short form)
Returns the JFN for the specified file. Accepts the specification for the
file from a string in memory or from a file (possibly a terminal) but not
both. If the source is the terminal, recognition can be done. One or more
fields of the file specification can be represented by a logical name. If any
fields are omitted, the system will provide default values as follows:
Device Connected structure.
Directory Connected directory.
Name No default; must be specified.
Type Null.
Generation Highest existing (input file); next higher (output).
Accepts in AC1: Flag bits in the left half, default generation number
in the right half (usually 0).
AC2: Source designator from which to obtain the file
specification (see description of flag bit GJ%FNS).
Returns: +1: Failure, error code in AC1.
+2: Success, flags in the left half of AC1, and the JFN
in the right.
Flag bits:
Monitor Calls Page 79
Symbol (Bit(s)) Meaning
GJ%FOU (0) (File OUtput) The file given is to be assigned the next higher
generation number; this bit indicates that a new version of a
file is to be created and is normally set if the file is for
output use.
GJ%NEW (1) The file specification must not refer to an existing file,
i.e. the file must be a new file.
GJ%OLD (2) The file specification given must refer to an existing file,
i.e. the file must be an old file. Note: if you want to open a
file in ' append' mode (i.e. you want to create a new file if
none exists, or else write to the end of an existing file),
don't specify GJ%OLD or GJ%NEW, and use OF%APP in the OPENF
call (see below).
GJ%CFM (4) ConFirMation from the user will be required (if GJ%FNS is on)
to verify that the file specification is correct. This
generally means that the user will have to type carriage
return after typing the file specification.
GJ%FNS (16) (File Name Source) The contents of AC2 are to be interpreted
as follows:
1. If this bit is on, AC2 contains an input JFN in the
left half, and an output JFN in the right. The
input JFN is used to obtain the file specification
to be associated with the JFN. The output JFN is
used to indicate the destination for printing the
names of any fields being recognized. To omit
either JFN, specify .NULIO (377777). This option
is generally used when the file specification is
being obtained from the terminal, and recognition
is being performed. The JFN's will normally be
.PRIIN and .PRIOU.
2. If this bit is off, AC2 contains a pointer to an
ASCIZ string in memory that specifies the file to
be associated with the JFN.
GJ%SHT (17) This bit should always be on to indicate that the long form of
GTJFN is not being used (the long form requires extra input).
(none) (18-35) The generation number of the file. Usually one of the
following:
1. .GJDEF (0) - the normal case - to indicate that the
next higher generation number of the file is to be
used if GJ%FOU is on, or that the highest existing
generation of the file is to be used if GJ%FOU is
off.
2. .GJNHG (-1) - to indicate that the next higher
generation number is to be used if no generation
number is supplied.
To translate a JFN to its corresponding filename string, see the description
Monitor Calls Page 80
of JFNS in the Monitor Calls Reference Manual.
Examples:
; Get a JFN from a filename string in memory.
movx t1, GJ%OLD!GJ%SHT ; For an "old" file
hrroi t2, [asciz/foo.txt/] ; called "foo.txt",
GTJFN ; get a Job File Number.
%jsErr ; Print message and halt on error.
hrrzm t1, iJfn ; Save the JFN in location "ijfn".
Note the "hrrzm", rather than "movem". This eliminates the extraneous flags
that are returned in the left half, which could cause errors in some
applications that don't need them (most don't).
; Get a JFN from the terminal, allowing recognition.
movx t1, GJ%OLD!GJ%FNS!GJ%CFM!GJ%SHT ; Old, tty i/o, confirm.
move t2, [.PRIIN,,.PRIOU] ; Get filename from terminal.
GTJFN ; Get the JFN.
%jsErr (,err) ; Print msg & go to "err" on error.
hrrzm t1, iJfn ; Save the result.
4.6.2. OPENF (JSYS 21) - Open a File
Opens the given file. No data transfer can be done until the file is open.
Accepts in AC1: JFN of the file being opened, in the right half.
AC2: Various control information, including:
Symbol Bit(s) Meaning
------ ------ -------
OF%BSZ 0-5 Byte size (maximum 36 decimal)
OF%RD 19 Allow read access.
OF%WR 20 Allow write access.
OF%APP 22 Allow append access.
OF%PLN 30 Disable line number checking and consider a line number
as 5 characters of text. If this bit is off, line
numbers will be discarded automatically.
Returns: +1: Failure, error code in AC1.
+2: Success.
No values are returned.
Monitor Calls Page 81
Example:
; Open an old file for read access.
move t1, iJfn ; The JFN already obtained by GTJFN.
movx t2, fld(7,OF%BSZ)!OF%RD ; 7-bit bytes, read access desired.
OPENF ; Open the file.
%jsErr (<Can't open the file>,fail) ; Print this message and
; go to location "fail" on error.
4.6.3. CLOSF (JSYS 22) - Close a File.
Closes a specific file.
Accepts in AC1: Flags, normally 0, in left half, JFN in right half.
Returns +1: Failure, error code in AC1.
+2: Success.
No value is returned.
Flags:
CO%NRJ (0) Do not release the JFN.
CO%ABT (6) abort any output operations currently being done. Close the
file, but do not perform any cleanup operations normally
associated with closing a file (e.g. do not output remaining
buffers). If output to a new disk file that has not been
closed (i.e. is nonexistent) is aborted, the file is closed
and then expunged.
Example:
; Close a file
move t1, ijfn ; Get the JFN into AC1.
CLOSF ; Close the file.
%jsErr (,.+1) ; On error, print message but continue.
4.7. File i/o JSYS's
There are three ways to do file i/o: by character (byte), by character string
(byte string), and by page. Of these, only the first two will be discussed.
For paged i/o see the Monitor Calls Reference Manual.
When doing input, whether byte- or string-oriented, you must always be
prepared to handle errors, and to distinguish a normal end-of-file (eof) error
from other errors. A monitor call is provided that can be used for this
purpose (among others):
Monitor Calls Page 82
4.7.1. GTSTS (JSYS 24) - Get file Status
Returns the status of a file associated with a JFN.
ACCEPTS in AC1: JFN in the right half.
Returns: +1: always, with JFN status word in AC2. If the JFN is
illegal in any way, bit GS%NAM will be 0.
The JFN Status Word has the following format:
Symbol Bit Meaning
------ --- -------
GS%OPN 0 File is open.
GS%RDF 1 Read access is allowed.
GS%WRF 2 Write access allowed.
GS%EOF 8 Last read was past end of file.
GS%NAM 10 A file specification is associated with this JFN.
If GS%OPN is 0, then the settings of the other bits are meaningless. There
are other bits and fields in the JFN Status Word; for these, see the Monitor
Calls Reference Manual.
When testing the status word for some (combination of) bit(s), you are faced
with a situation similar to loading some combination of option bits into an AC
for a JSYS call, i.e. you don't know (or at least you shouldn't depend on)
whether the bits form a left-half, right-half, or fullword quantity, and
therefore you don't know which test instruction to use (tl--, tr--, ts--, or
td--). Of course, td-- will always work if you put the argument in square
brackets, but this requires an extra memory fetch at runtime. For this
reason, a set of tx-- macros have been defined that are analogous in purpose
and operation to the "movx" macro described above. You can always use a tx--
without worrying about the actual value of the quantity being tested. These
comments apply not just to testing the JFN status word, but to testing any
word for symbolically defined bits.
Example (assume that a JSYS error has just occurred during input):
; Check for end of file.
move t1, iJfn ; Load the JFN of the input file.
GTSTS ; Get the status of the file.
txnn t2, GS%EOF ; Are we at eof?
jrst error ; No, must be some other error.
; Come here on end of file.
4.7.2. Sequential Byte i/o
The following JSYS's input or output bytes sequentially.
Monitor Calls Page 83
4.7.2.1. BIN (JSYS 50) - Byte In
Inputs the next byte from the specified source. When the byte is read from a
file, the file must first be opened, and the size of the byte given, with the
OPENF call. When the byte is read from memory, a pointer to the byte is
given; this pointer is always updated after the call (a BIN to a character
string in memory is equivalent to an ildb instruction).
Accepts in AC1: source designator (JFN or byte pointer)
Returns +1: always, with the byte right-adjusted in AC2.
If the end of file is reached, AC2 contains 0 and an erjmp or ercal
instruction following the BIN call will be activated (but note that end of
file is not the only error possible).
4.7.2.2. PBIN (JSYS 73) - Primary Byte In
Like BIN, but always obtains the byte from the primary input source (i.e. the
.PRIIN JFN, usually the terminal). Needs no input.
Returns: +1: always, with byte right-adjusted in AC1.
Various errors are possible, including end-of-file.
4.7.2.3. BOUT (JSYS 51) - Byte Out
Outputs a byte sequentially to the specified destination. When the byte is
written to a file, the file must first be opened, and the size of the byte
given, with the OPENF call. When the byte is written to memory, a pointer to
the location in which to write the byte is given in AC1. This pointer is
updated after the call.
Accepts in AC1: destination designator (JFN or byte pointer).
Returns +1: always.
Various errors are possible.
4.7.2.4. PBOUT (JSYS 74) - Primary Byte Out
Like BOUT, except byte always goes to the primary output destination (i.e. the
.PRIOU JFN, usually the terminal).
Accepts in AC1: byte to be output, right-justified.
Returns: +1: always.
Various errors are possible.
Monitor Calls Page 84
4.7.2.5. Example of Byte i/o
; This program segment reads bytes one at a time from a file whose
; JFN is stored in location "iJfn". If a byte is null (zero), it is
; discarded, otherwise it is written to the output file, whose JFN
; is stored in location "oJfn". Both files are assumed to be open.
copy: move t1, iJfn ; Load input JFN into t1.
BIN ; Get next byte.
erjmp tstEof ; On error, go test for eof.
jumpe t2, copy ; If the character was zero, ignore it.
move t1, oJfn ; Load output jfn into t1.
BOUT ; Write the byte to the output file.
%jsErr ; Print message and halt on error.
jrst copy ; Loop for all bytes in file.
; Come here on error in the BIN JSYS. Check for end of file.
tsteof: GTSTS ; JSYS to Get file Status (JFN is in t1).
txnn t2, GS%EOF ; Was it an eof?
%erMsg (,done) ; No, print the error message and finish up.
; Here when we've copied the entire file.
done: move t1, iJfn ; Close the input file
CLOSF ; using the CLOSF JSYS.
%jsErr (,.+1) ; On error, print message but continue.
move t1, ojfn ; And close the ouput file too.
CLOSF
%jsErr (,.+1)
; End of program fragment.
Note the %erMsg macro; it is identical to %jsErr, except that it is executed
unconditionally rather than via erjmp or ercal. It is mainly intended for use
after a skipping instruction or subroutine call.
4.7.3. String-oriented i/o
The following JSYS's input or output byte strings.
4.7.3.1. SIN (JSYS 52) - String In
Reads a string from the specified source into the caller's address space. The
string can be a specified number of bytes or terminated with a specified byte.
Monitor Calls Page 85
Accepts in AC1: Source designator (JFN or byte pointer).
AC2: Pointer to string in the caller's address space (destination).
AC3: Count of number of bytes to input, or 0.
AC4: Byte (right-justified) on which to terminate input (optional).
Returns: +1: Always, with updated string pointers in AC1 and AC2
(if pertinent), and updated count in AC3 (if pertinent).
The contents of AC3 controls the number of bytes to read as follows:
AC3=0 The string being read is terminated with a 0 byte.
AC3>0 A string of the specified number of bytes is to be read or a
string terminated with the byte given in AC4 is to be read,
whichever occurs first.
AC3<0 A string of minus the number of bytes is to be read.
AC4 is ignored unless AC3 contains a positive number.
An end of file can be processed as in the example above. After execution of
the call, the file's pointer is updated for subsequent i/o to the file. AC2
is updated to point to the last byte read or, if AC3 contained 0, the last
nonzero byte read. The count in AC3 is updated toward 0 by subtracting the
number of bytes read from the number of bytes requested to be read. If the
input was terminated by an end-of-file condition, AC1 thru AC3 are updated
(where pertinent) to reflect the number of bytes transferred before the end of
file was reached.
Various errors, besides eof, are possible (e.g. invalid JFN, file not open,
device or data error, etc.).
Note: The source JFN can be .PRIIN (i.e. the terminal), but SIN is
not the best JSYS to use for input of strings from the terminal,
because it does not allow for editing (via DEL, ^U, ^W, and ^R) or
prompting. Terminal string input is best done using the TEXTI or
RDTTY JSYS (RDTTY is described below); better still, all terminal
input can be done using the COMND JSYS (Chapter 5), which allows not
only prompting and editing, but automatic help and recognition, as
well as syntax checking for all sorts of fields (numbers, file names,
keywords, etc). For TEXTI and COMND, refer to the Monitor Calls
Reference Manual.
4.7.3.2. SOUT (JSYS 53) - String Out
Writes a string from the caller's address space to the specified destination.
The string can be a specified number of bytes or terminated with a specified
byte.
Monitor Calls Page 86
Accepts in AC1: Destination designator.
AC2: Pointer to string to be written.
AC3: Count of the number of bytes to be written, or 0.
AC4: Byte (right-justified) on which to terminate output.
Returns: +1: Always, updated string pointers and counts in the
AC's, if pertinent.
Interpretation of the arguments is exactly the same as by SIN, and the
operation is entirely analogous, but in the opposite direction.
4.7.3.3. PSOUT (JSYS 76) - Primary String Out
A short form of SOUT (there is no corresponding short form of SIN). Outputs a
string sequentially to the primary output destination (usually the terminal).
Accepts in AC1: Pointer to ASCIZ (zero-terminated) string in the
caller's address space.
Returns: +1: Always, with updated string pointer in AC1.
As usual, various errors are possible (usually an invalid byte pointer is the
culprit).
Monitor Calls Page 87
4.7.3.4. Example of String I/O
This program fragment copies the input file (which is already opened in 7-bit
mode and whose JFN is stored in location "iJfn") to the output file (open
similarly, JFN in "oJfn"), a string at a time, where a string is considered to
be a sequence of bytes terminated by a linefeed, but of maximum lenth 512
(decimal). Note that the linefeed character is represented symbolically; this
is considered good technique because it makes the program more readable. The
symbolic definitions of the (nonprinting) ASCII control characters are
obtained by searching MACSYM.
maxLen=^d512 ; Define maximum length symbolically.
buffer: block <maxlen/5+1> ; String buffer (convert bytes to words).
:
:
copy: move t1, iJfn ; Load the input file JFN.
hrroi t2, buffer ; Point to place in memory to put string.
movei t3, maxLen ; Maximum number of characters.
movei t4, .CHLFD ; Terminate on the CHaracter LineFeeD.
SIN ; Read the string into the buffer.
erjmp tstEof ; On error, go test for eof.
; Now write the string into the output file. Note that t3 contains
; <maxlen - <length of string>>. We can't count on the presence of the
; terminating linefeed because input may have exhausted the maximum byte
; count before a linefeed was encountered.
move t1, oJfn ; Load the output file JFN.
hrroi t2, buffer ; Point to the string to be written.
subi t3, maxLen ; Get negative length into t3.
SOUT ; Write the string out.
%jserr (,done) ; Print message and finish up on error.
jrst copy ; Loop for all strings in file.
tstEof: GTSTS ; JFN of input file already in t1.
txnn t2, GS%EOF ; Error caused by end of file?
%ermsg (,done) ; No, print message and finish up.
done: hrroi t1, [asciz /All done/] ; Type this message
PSOUT ; at the terminal.
; Now just close the files in the normal way.
; (end of program fragment)
4.7.3.5. RDTTY (JSYS 523) - Read string interactively from TTY
RDTTY is the JSYS most suited to simple terminal input; it is a subset of the
TEXTI JSYS, which is much more flexible, more powerful, but more complicated
to use (see the Monitor Calls Reference Manual for details on TEXTI and full
Monitor Calls Page 88
details on RDTTY). We will describe the most useful options of the RDTTY
JSYS.
RDTTY is most suited for interactive terminal input because it lets the user
edit her/his input, on a line-by-line (or several-line) basis, before it's
"eaten" by the program. All the editing characters, viz., ^R, ^W, ^U, ^L, and
RUBOUT, are available for editing (though no recognition is possible, since
command parsing is not being done). There are basically two ways to call
RDTTY: to read a single line (up to a carriage-return or line-feed), and to
read a whole group of lines (up to a ^Z or ESCAPE). In the single-line mode,
the program receives each line as the user types it, and thus only permits
editing on a single-line basis; in the line-group mode, the user can enter any
number of lines (limited only by the size of your input buffer) and edit all
the way back to the beginning of input (for example, MM and Mail use the
1
line-group mode to collect the text of messages to be sent).
The RDTTY JSYS reads input from the primary input port ( .PRIIN), until either
a break character is seen (such as ^Z or carriage-return) or the given byte
count is exhausted (which means your buffer is full). Output generated as a
result of editing the input text (such as echoing of deleted characters after
backslashes, as in "foo<RUBOUT><RUBOUT>ee", which echoes as "foo\o\oee" on a
hardcopy terminal) goes to the primary output port (.PRIOU). .PRIIN and
.PRIOU normally designate the user's terminal (TTY) as an both input and
output device, respectively.
Accepts in AC1: pointer to string in caller's address space where
input is to be placed.
AC2: control bits in left half, as described below, and
number of bytes available in the buffer (pointed to
by AC1) in the right half.
AC3: 0, if no prompt is wanted, or
byte pointer to prompting text (^R) buffer.
Returns: +1: failure, error code is in AC1.
+2: success, updated string pointer in AC1, appropriate
bits set in the left half of AC2, and updated count of
available bytes in the right half of AC2.
Note that the prompting text buffer is not automatically output by RDTTY; you
have to output it yourself before doing the RDTTY (but it will be output
properly if ^R or ^L is typed during user input).
The control flags in the left half of AC2 are broken into two groups: those
given to RDTTY, and those returned (see the Monitor Calls Manual for a
---------------
1
If you need to read in a group of text lines, even a large group, it's
advisable to use the the line-group mode of RDTTY, since memory is 'cheap':
just give RDTTY a large buffer area; this makes things much easier for the
poor, fallible human out there.
Monitor Calls Page 89
complete description of the control flags).
Symbol (Bit(s)) Meaning
Given to RDTTY in AC2:
RD%BRK (0) BReaK on ^Z or ESCAPE (i.e., line-group mode)
RD%BEL (3) Break on End of Line (carriage return or linefeed, i.e.,
single-line mode)
RD%RAI (10) RAIse user input: convert lower case to upper case
Returned from RDTTY in AC2:
RD%BTM (12) Break character TerMinated input: if this is set, the input
was terminated because a break character was seen; if not,
then input was terminated because the buffer is full (as
determined by the byte count given in the right half of AC2)
4.7.3.6. RDTTY Example
The following example uses the RDTTY JSYS to collect a "note", or a group of
lines about some subject, and write it all to a file (which is opened and
closed elsewhere).
; Data area
maxLen==^d10000 ; Allow 10k characters in note input.
prompt: asciz/Text of note (end with ^Z or ESCAPE): /
inBuf: block maxLen/5 + 1 ; Input buffer.
oJfn: block 1 ; Output JFN.
.
.
.
Monitor Calls Page 90
; Assume oJfn is set up with the output file JFN.
note: hrroi t1, prompt ; Prompt for the note.
PSOUT ; ...
hrroi t1, inBuf ; Get a pointer to destination buffer.
movx t2, <RD%BRK!maxLen> ; Break on ^Z, ESC, up to buffer size.
hrroi t3, prompt ; Use prompt on ^R, etc.
RDTTY ; Read the note.
%jsErr ; Die loudly if fails.
hrrz t3, t2 ; Get remaining byte count.
movns t3 ; Negate it and add to maxLen to get
add t3, [maxLen] ; number of bytes input.
hrroi t1, inBuf ; What we want to output.
move t2, oJfn ; Get destination JFN,
SOUT ; and output what we just read.
%jsErr ; Handle failure nicely.
.
.
4.7.4. Number conversion JSYS's
These are similar to string i/o JSYS's in that their input or output is a
string (in memory or in a file), but the string is the ASCII character
representation of a number in some base, and conversion is done either from
the internal form of the number to the string or vice versa.
4.7.4.1. NIN (JSYS 225) - Number In
Inputs the character-string representation of an integer number, ignoring
leading spaces. This call terminates on the first character not in the
specified radix. If that character is a carriage return followed by a line
feed, the line feed is also input.
Accepts in AC1: Source designator (JFN or byte pointer).
AC3: Radix (2-10) of number being input.
Returns: +1: Failure, error code in AC3, updated string pointer
(if pertinent) in AC1.
+2: Success, internal two's complement binary representation
of number in AC2, and updated string pointer (if
pertinent) in AC1.
Various errors are possible (invalid JFN, file not open, invalid radix, first
nonspace character not a digit, overflow, etc.). It is not advisable to use
NIN to input a number from the terminal because NIN does not allow editing and
reprompting, as does RDTTY; RDTTY should be used to get the string
representation of the number into memory, and then NIN should be used to
Monitor Calls Page 91
convert the string to a number; if the string contains invalid characters, the
error can be caught and the user can be informed and reprompted (by a
%jsErr (,foo) after the NIN, where foo is the address of the RDTTY sequence).
This technique is shown in a subsequent example.
4.7.4.2. NOUT (JSYS 224) - Number Out
Outputs an integer number to a file or to a string in memory.
Accepts in AC1: Destination designator.
AC2: Number to be output.
AC3: Format control information as follows:
Symbol (bit(s)) Meaning
NO%MAG (0) Output the magnitude. That is, output the number as an
unsigned 36-bit number (e.g. output -1 as 777777777777 in base
8).
NO%SGN (1) Output a plus sign for a positive number.
NO%LFL (2) Output leading filler. If this bit is not set, trailing
filler is output, and bit NO%ZRO is ignored.
NO%ZRO (3) Output 0's as the leading filler if the specified number of
columns (NO%COL) allows filling. If this bit is not set,
blanks are output as leading filler if the number of columns
allows filling.
NO%OOV (4) Output on column overflow and return an error. If this bit is
not set, column overflow is not output.
NO%AST (5) Output asterisks on column overflow. If this bit is not set
and NO%OOV is set, all necessary digits are output on column
oveflow.
NO%COL (11-17) Number of columns (including the sign column) to output is
right-justified in this field. If this field is 0, as many
columns as necessary are output.
NO%RDX (18-35) Radix (2-36) of number being output.
Returns: +1: Failure, error code in AC3.
+2: Success, updated string pointer in AC1, if pertinent.
Various errors are possible, including NOUTX2 (column overflow), plus those
that are possible for NIN.
Monitor Calls Page 92
4.7.4.3. NIN/NOUT Example
Here, the user is prompted at the terminal to type in a decimal number. The
number is then typed back to the user, in octal (base 8) notation,
right-adjusted in a field of width 9.
prompt: asciz /Decimal number: / ; The prompt.
numLen=^d20 ; Length of buffer for number string.
numBuf: block numLen ; The input buffer.
:
:
reTry: hrroi t1, prompt
PSOUT ; Prompt the user for a decimal number.
; Get the alleged number from the terminal into memory in string form.
hrroi t1, numBuf ; Point to buffer for string that user types.
movx t2, RD%BEL!numLen ; Break on CRLF, max length for typein.
hrroi t3, prompt ; Reprompting text.
RDTTY ; Get string, allowing editing.
%jsErr (,reTry) ; Print message & reprompt on error.
; Now convert the string to a number.
hrroi t1, numBuf ; Point to string representation of number.
movei t3, ^d10 ; Radix for interpretation.
NIN ; Number In - do the conversion.
%jsErr (,reTry) ; On error, print msg and ask again.
; Now type it back, converting to octal notation. The number is still in t2.
movx t1, .PRIOU ; Output is to primary output destination.
movx t3, NO%MAG!NO%LFL!NO%AST!fld(^d9,NO%COL)!fld(^d8,NO%RDX)
NOUT ; Type the number.
%jserr (,prompt) ; On error, print message and reprompt.
; (end of program fragment)
Similar monitor calls ( FLIN and FLOUT) exist for input and output of floating
point numbers; see the Monitor Calls Reference Manual for these.
Monitor Calls Page 93
4.7.5. Random-access i/o
Tops-20 gives you the ability to randomly access files on disk storage, which
is the only kind of device which supports this type of access (other than
DECtape, which is now essentially defunct in "DEC land").
As described earlier, disk files can be considered to be merely a sequence of
bytes, of some size from 1 to 36 bits (the normal sizes are 7, for text files,
and 36, for binary, word-oriented files); the byte size of the file is
determined at the time of the OPENF for the file (and can thus be changed from
open to open, if you're daring). Each byte in the file has a label, or index,
which is its position in the sequence, starting at zero. For example, the
text file containing the 15 ascii bytes "This is a file." can be considered to
be a sequence of bytes, as follows:
Index Byte Value Index Byte Value
0 "T" 124 8 "a" 141
1 "h" 150 9 " " 040
2 "i" 151 10 "f" 146
3 "s" 163 11 "i" 151
4 " " 040 12 "l" 154
5 "i" 151 13 "e" 145
6 "s" 163 14 "." 056
7 " " 040
For example, the zero'th byte of the file is an ascii "T" (octal value 124),
the tenth byte is an ascii "f" (octal value 146), and the fourteenth, and
last, byte is a period, "." (octal value 056).
Although it's not important to understanding the notion of random-access i/o,
it's culturally interesting to note that disk files are stored in units of
pages, or 512 36-bit words, or 2560 (512*5) 7-bit bytes. Thus, the above
file, which is 15 bytes long, would occupy 3 (15/5) words, or one page. Why
one page? Because pages are the minimum unit of disk file storage, and thus,
the above file is "wasting" 509 words of disk space (this much of the one page
it uses is unoccupied). The 512 words-per-page is a hardware parameter, which
we can't do much about, so we'll accept this waste as reasonable, since files
are generally many pages in length (and the wasted portion is then
proportionally smaller).
Tops-20 keeps track of two items, when you're doing i/o with disk files: the
current byte index (the one you would read next if you did a BIN JSYS, or
write next if you did a BOUT), known in JSYS jargon as the 'file pointer', and
the end-of-file byte index, which is simply the length of the file, in bytes
(and is thus, conceptually, the non-existent byte after the last byte in the
file).
When you first open the file (with an OPENF), the file pointer is set
depending on how you opened the file. If you opened it for reading or writing
(or both), then the file pointer will be zero, i.e., you're initially
positioned to read or write the first (zero'th) byte in the file. If you
opened it for appending, then the file pointer is initially set to the
end-of-file byte index, i.e., you're positioned to read or write the byte
right after the last real byte in the file; in the case of a BIN this first
read will return a zero byte and indicate you're at end of file; in the case
of a BOUT this first write will simply extend the file by one byte.
For example, if you had done 15 BIN JSYS's on the sample file shown above
Monitor Calls Page 94
after opening it, on the 16th BIN you would be at end-of-file (i.e., there are
no more bytes to read), and Tops-20 would obey an erjmp instruction after the
BIN, going to where you specified (which would presumably check for a true
end-of-file condition and handle it appropriately). For a more graphic
example, after 10 BIN's, say, then the situation looks like:
Index Byte Value
0 "T" 124 <- byte read on the first BIN
: : :
8 "a" 141
9 " " 040 <- byte just read on the 10th BIN
10 "f" 146 <- file pointer (what will be
11 "i" 151 read by the next BIN)
12 "l" 154
13 "e" 145
14 "." 056
15 -none- <- end-of-file byte index
Thus, as mentioned in the previous example, when the file pointer becomes
equal to the end-of-file byte index (15 in this example), end-of-file is said
to be "reached". Of course, if you're writing a file, then the end-of-file
byte index is normally the same as the file pointer, since the file pointer
indexes the next byte to be read or written.
Of course, you can mix random-access i/o with sequential i/o in any old way,
and the results are very well-defined. The SFPTR JSYS simply sets the file
pointer to the next byte to be read or written; once it's set, you can merrily
BIN, BOUT, SIN and SOUT, and they'll take place at the file pointer position,
updating the pointer appropriately. Using the sample file from before,
imagine that you've done a SFPTR to the 4th byte (which is the space after
"This" - why isn't it the "s" in "This"?). Then, suppose you do a BOUT of a
"-" character to the file. The resulting situation will be:
Index Byte Value
0 "T" 124
1 "h" 150
2 "i" 151
3 "s" 163
4 "-" 055 <- file pointer after the SFPTR
5 "i" 151 <- file pointer after the BOUT
6 "s" 163
: : :
In a more 'cultural' vein, again, you should know that Tops-20 considers a
disk file to be a completely extensible sequence of bytes, i.e., it is
possible, and quite easy, to extend a file by simply positioning to the
end-of-file position (with the SFPTR JSYS, as described below) and writing
more bytes with BOUTs or SOUTs. The end-of-file byte index will be updated
appropriately. Even more, it's possible to position the file pointer to some
point way beyond the end-of-file index, and write more bytes. The file will
simply be extended appropriately with zero bytes, up to the point at which you
started writing (technically speaking, there may be some 'holes' in the file,
but they will look like zero, or null, bytes when you read over them; they
only matter if you don't like nulls, or are doing your own direct disk page
manipulation). For example, given the sample file above, if you positioned to
the 20th byte (which doesn't exist yet), and wrote the byte string "more.",
then the file would simply be extended, resulting in a file with 25 bytes,
with the end-of-file and file pointer equal to 25, and with the file
Monitor Calls Page 95
containing
This is a file.<0><0><0><0><0>more.
where the <0>'s represent null (zero) bytes.
There are basically four JSYS's designed for dealing with disk files in a
random (not purposeless!) fashion: read the current file pointer for a file
(RFPTR), set the file pointer for a file (SFPTR), read a byte from a file,
given its index (RIN, for Random IN), and write a byte to a file, given the
desired byte index (ROUT, for Random OUT).
4.7.5.1. RFPTR (JSYS 43) - Read File Pointer
Returns the current file pointer of the specified file.
Accepts in AC1: JFN of an open file.
Returns: +1: Failure, error code in AC1.
+2: Success, byte number (index) in AC2.
Actually, you can read the file pointer of a non-disk file, but it is either
meaningless or the number of bytes read so far from the file (e.g., in a tape
file). RFPTR can fail in various ways, but only if you don't give it a valid
JFN for an open file.
4.7.5.2. SFPTR (JSYS 27) - Set File Pointer
Sets the specified file's file pointer for subsequent i/o to the file. Note
that doing an SFPTR specifying a certain byte index, followed by a BIN or BOUT
JSYS, is the same as doing a RIN or ROUT JSYS, respectively, specifying the
same byte index.
Accepts in AC1: JFN of an open disk file.
AC2: byte index to which the file pointer is to be set,
or, -1 to set the pointer to the current end-of-file
index.
Returns: +1: failure, error code in AC1.
+2: success, file pointer has been set.
The SFPTR JSYS can fail in various ways, but only if you don't give it a valid
disk file JFN.
Monitor Calls Page 96
4.7.5.3. RIN (JSYS 54) - Random byte In
Inputs a byte nonsequentially (i.e., random byte input) from the specified
file. The size of the byte is that given in the OPENF call for the file.
Accepts in AC1: JFN of an open disk file.
AC2: byte index within the file of the byte desired.
Returns: +1: always, with the byte right-justified in AC2.
If the end of file is reached (i.e., you specify a byte index greater than or
equal to the end-of-file index), a zero is returned in AC2; this is not really
an error condition, but you can catch it if you want to with an erjmp or ercal
after the RIN. The file's file pointer is updated for subsequent sequential
i/o to the file. Several errors are possible, but not if you give it a real
JFN for a file opened in (at least) read mode (unless the file is opened for
append access only, in which case you can't change the file pointer, to avoid
letting you read the part of the file you're not supposed to see, e.g., a
mail.txt file with protection 770404).
4.7.5.4. ROUT (JSYS 55) - Random byte Out
ROUT outputs a byte nonsequentially (i.e., random byte output) to the
specified file. The size of the byte is that given in the OPENF call for the
file.
Accepts in AC1: JFN for an open disk file.
AC2: the byte to be output, right-justified.
AC3: the byte index within the file at which to write
the byte in AC2.
Returns: +1: always, with the byte written in the file.
The file byte pointer after the ROUT is C(AC3)+1 (i.e., the file pointer is
set to C(AC3), the byte is written, and the file pointer updated to account
for the byte just written). ROUT will always succeed if you give it a JFN for
a disk file opened for writing and ask it to write at a nonnegative byte index
that is less than the upper limit for the disk (you can have at most 512*512
pages (or 512*512*512 36-bit bytes) in a file); also, it may fail if you try
to ROUT to a file opened in append-only mode (because that would allow you to
change parts of a file you weren't supposed to access, such as a mail.txt file
protected at 770404).
Monitor Calls Page 97
4.8. Fork-Handling JSYS's
4.8.1. What's in a Fork?
To effectively use machine language on the DEC-20, you have to understand
something about what programs are, how they are born, how they live, and how
they die.
The term 'program' can be understood in many ways; most intuitively, because
it's in the form that we understand more easily, it means a text file in some
source language, such as Macro-20 or Pascal. But, this textual form of the
program must be processed by a translator (an assembler or compiler) to
produce a form more palatable to the actual machine. Even in this form, which
is normally a '.REL' or relocatable file, it isn't quite understandable to the
machine. It needs to go a further step, called linking, which involves
combining it with any other program segments which it needs to interact with
during execution by the machine (such as a language support package for doing
input/output, etc.). Once it's linked, the result can be saved as an '.EXE'
or executable file.
An executable file is nothing more than a program in vestigial or 'pure
potential' form, i.e., a data file with contents specifying how memory is to
be filled when it is incarnated as an active, or executing, program. We can
distinguish between a program in this passive state (the result of compiling,
linking and saving), from a program actually in execution by the Tops-20
system. Using this distinction, we can properly call the passive element
--the EXE file-- the 'program', and the active element --the part that
executes the program-- the 'process' or 'fork' (the latter is jargon used when
dealing with Tops-20 processes).
It may be helpful to think of the fork as a self-contained machine with a
well-defined 'control panel', or interface to the outside world. This control
panel has a set of 'knobs' for controlling it and objects which are dealt with
via 'handles'; the knobs and handles are manipulated by other forks, via
JSYS's. A fork, considered in this way, is a machine with power to follow
instructions, which come from the passive program (EXE file); a fork is loaded
up with its instructions by pulling in the program's pages from the EXE file.
Then, it can be started, temporarily stopped (frozen), continued, stopped,
etc. There also must be a way to create and destroy these fork machines, and
there is. The fork can, under its own power, follow the program's
instructions and stop itself (it can't start itself, for obvious reasons).
From the time a fork is created until it is annihilated, it is necessarily in
some 'state', just like any good mechanical machine: stopped, running,
waiting for something external to it to happen, etc.
A Tops-20 job is nothing more than a related collection of forks; since a fork
can only come into existence by being created by another fork, each fork has a
superior fork (which created it) and some number of inferior forks (which it
created). It's also helpful to think of a fork's superior as its parent and
its inferiors as its children. The top-level fork in each job (which has no
superior) is the Tops-20 EXECutive command processor, which is responsible for
creating other forks and running programs in them. The EXEC is thus the
super-parent fork in each job, and is created by Tops-20 when you type a
control-C on an unlogged-in terminal. In a graphic form, suppose you've
logged in and have run EMACS as a kept editor, written a program, gotten out
Monitor Calls Page 98
of EMACS and started to compile it with MIDAS. At this point, your job's fork
structure looks like:
(W: Your EXEC fork)
/ #0
/ |
/ |
(H: EMACS) (R: MIDAS)
#1 #2
For convenience' sake, we label the forks with numbers (in the order in which
they were created). In fork #2, the MIDAS EXE file is being executed (R:
means running), and fork #1, containing the EMACS EXE and various TECO files,
is temporarily halted (H: means halted), since you're not using it currently.
The EXEC fork, fork #0, is waiting for the MIDAS fork to halt itself before
going on and prompting you for more commands (W: means waiting for another
fork).
Suppose, after running MIDAS, you Push to a new EXEC and run your program
(somewhat useless, but helpful for this example). At the time your program is
running, your job fork structure looks like:
(W: your EXEC)
/ #0 \
/ | \
/ | \
(H: EMACS) (H: MIDAS) (W: Pushed-to EXEC)
#1 #2 / #3
/
/
(R: your program)
#4
Here you see more clearly the 'tree' structure of the forks in your job. As
with most other trees encountered in computer science, this one is drawn
upside-down, with the branches growing down. You can also see why Tops-20
processes are called 'forks', as the tree structure forks out at each process,
just as a road forks at a junction.
To elaborate more on the superior and inferior notion, fork #0 has forks #1,
#2, and #3 as inferiors, and fork #3 has fork #4 as an inferior. Of course,
forks #1, #2 and #3 have fork #0 as a superior, and fork #4's superior is fork
#3.
Notice the states of the various forks: the top-level EXEC is now waiting on
the pushed-to EXEC to stop; your MIDAS fork has halted itself (which made the
top EXEC go on and ask you for more commands, at which point you Pushed to the
new EXEC); the EMACS fork's state hasn't changed, since you haven't told the
top EXEC to do anything with it; the pushed-to EXEC is waiting for your
running program to finish.
Monitor Calls Page 99
4.8.2. The Fork Environment
As mentioned above, each fork has a 'control panel', or interface with the
external environment, i.e. the world of forks outside itself. This panel has
several different areas, relating to the various kinds of interactions
possible with the outside world. These areas are as follows (don't worry
about the areas we haven't discussed yet):
1. The file system, each file represented by a Job File Handle (JFN);
2. The fork world, each inferior fork represented by a relative fork
handle;
3. The software interrupt system, as described by various enabled or
disabled channels and their handler address, as well as the global
state of the interrupt system for the fork;
4. Inter-process communication system, each channel of communication
represented by a Process ID (PID);
5. Inter-process sychronization system, each sychronization request
represented by outstanding Enqueue request (ENQs);
6. The user-terminal interface, consisting of various mode information
for the terminal apropos this fork;
Note that each area on the 'control panel' has a method of referencing the
various external objects related to the area; these are called 'handles' in
general (Job File Handles, Relative Fork Handles, Process ID Handles, etc.).
This is no coincidence: you have to refer to one of several objects --forks,
files, process IDs, etc.-- when you want to do something with them --open a
file, start a fork, send a message to another process, etc.-- and thus the
need for a handle. A handle is usually nothing more than a small integer
uniquely identifying the particular object you want to deal with.
4.8.3. Basic Fork-Handling JSYS's
With the above introduction to forks and their environment, we can proceed to
the two most basic fork-handling JSYS's: RESET and HALTF.
4.8.3.1. RESET (JSYS 147): Reset the current fork
This JSYS, in the terms of the previous section, cleans up the interface to
the external environment for this fork. It's always a good idea to use this
JSYS at the start of your program to make sure there are no 'loose ends' lying
around.
Returns: +1: Always (no errors are possible).
The RESET JSYS (cf. the list above in section 4.8.2):
1. closes all files for this fork (and any inferiors) and releases all
Monitor Calls Page 100
Job File Numbers (JFNs);
2. destroys all inferior forks and releases any Relative Fork Handles
it can;
3. resets the software interrupt system for this fork;
4. releases all handles on inter-process communication channels
(PIDs);
5. releases all inter-process sychronization requests (ENQs);
6. resets the terminal for this process to wake up on every character,
echo input, and translate output normally;
4.8.3.2. HALTF (JSYS 170) - Halt the current fork
Halts this fork and any forks inferior to this one; this fork (the one
executing this JSYS) then goes into the 'halted' state (with a 'voluntarily
terminated' flavor). If this fork is resumed (with a RFORK JSYS), then it
will continue with the instruction after this HALTF JSYS.
Returns: +1: only if this fork is later resumed (no errors are
possible from the HALTF itself).
4.8.3.3. Examples of RESET and HALTF
These two JSYS's are fairly simply used in practice. An example of a complete
MACRO program that prints "I'm here" and stops is:
title ImHere
search monsym
ImHere: RESET ; Tidy up the environment.
hrroi 1, [asciz/I'm here/] ; Print our
PSOUT ; message to the terminal,
HALTF ; and stop this fork.
jrst ImHere ; If this fork is continued, start over.
end ImHere
4.9. Miscellaneous JSYS's
Monitor Calls Page 101
4.9.1. STCMP (JSYS 540) - STring CoMParison
Compares two ASCIZ strings in memory. Letters are always considered as upper
case regardless of their case within the string; e.g. "ABC" and "abc" are
considered an exact match.
Accepts in AC1: Pointer to test string.
AC2: Pointer to base string.
Returns: +1: always, with
AC1 containing the compare code:
SC%LSS (bit 0) Test string less than base string.
SC%SUB (bit 1) Test string is a subset of
base string.
SC%GTR (bit 2) Test string greater than base string.
No bits are set in AC1 if the strings are equal.
AC2 containing base string pointer, updated such that
an ildb instruction will reference the first
nonmatching byte.
One string is considered less than another string if the ASCII value of the
first nonmatching character in the first string is less than the ASCII value
of the character in the same position in the second string.
On string is considered a subset of another string if both of the following
conditions are true:
1. From left to right, the ASCII values of the characters in
corresponding positions are the same.
2. The test string is shorter than the base string.
Two strings are considered equal if the ASCII values of the characters in
corresponding positions are the same and the two strings are the same size.
In this case, the contents of AC1 is 0 on return.
Example:
move t1, [point 7, string1] ; Pointers to test string
move t2, [point 7, [asciz /FOO/]] ; and base string.
STCMP ; Compare them.
jumpe t1, equal ; Do this if they're equal.
txnn t1, SC%LSS!SC%SUB ; Not equal. Test string less?
jrst greater ; No, greater - go handle.
; Get here only if test string lexically less than base string.
:
:
COMND JSYS Page 102
5. The COMND JSYS - JSYS 544
The COMND JSYS is probably the single most attractive feature of
the DECSYSTEM-20. It allows any interactive program to be totally
(and automatically) fault-tolerant and helpful to its users. The pain
involved in learning to use it effectively is worth suffering, but
should probably be deferred until you have become comfortable with the
instruction set, Macro-20, and the monitor calls described in Chapter
4.
The following introductory material was adapted for use in this
manual from a document written by Andrew R. Lowry and David S. Millman
at Columbia in August 1978.
5.1. Informal Introduction
You are probably already at least partially familiar with the workings of the
COMND jsys, although you may not be aware of your education. The COMND jsys
is the thing that figures out what you mean when you abbreviate your commands
to the EXEC, or when the EXEC finishes up your commands for you when you types
an ESCAPE character. It is also what types guide words in parentheses telling
you what you must type next, and it is the thing that will untiringly answer
your question marks with lists of alternatives for you to choose from. In
short, it is one of the things that makes learning and typing in commands to
the EXEC as easy as it is.
Using the COMND jsys mainly consists of the following: you tell it what
you're looking for, and it tells you what it finds. All the complexities have
to do with how this communication takes place. A great deal of this is common
to all the calls you can give to COMND, but some of it depends on exactly what
you're asking COMND to look for.
All the information which you must supply to COMND may be broken down
basically into two sets, the Command State Block (CSB) and the Function
Descriptor Block (FDB).
The CSB is ten words (storage locations) long and contains information about
what has been typed so far, how much more can be typed without overflowing the
space that has been set aside to store it, and where COMND can find other
information that it needs. Most of this information must be supplied only once
by the program using COMND, and from that point on COMND will update the
information as it goes.
The FDB is four words long and contains information which is more specific to
the type of call which is being made than is the information in the CSB. It
is here that COMND finds out what type of information it should be looking for
-- file name, time of day, one out of a list of possible keywords, or any
other of the 24 different items it knows how to look for. Also in the FDB it
finds pointers to a help string and a default string which the controlling
program supplies. The help string is what will be typed if the user types a
question mark, and the default string is what COMND will fill in if the user
types an escape character. Finally, COMND finds several indicators in the FDB
telling it how to process the request -- things like whether or not to convert
lower case input into upper case, whether or not to accept indirect file
specifications, etc.
COMND JSYS Page 103
The only thing left to do after the CSB and the FDB have been properly filled
in is to tell COMND where they are and let it go do its work. The only
questions now are, what does it do, and what are all the things it might give
back?
When COMND is invoked, it starts accepting characters, usually from the job's
controlling terminal. It keeps taking characters until the user types what is
called an "action" chatacter. Action characters include question mark,
escape, ctrl/f and carriage return, and they are called action characters
because COMND won't start doing what it is supposed to do until one of them is
typed. Once an action character is encountered, COMND will determine whether
or not the user has finished typing what s/he was supposed to type, and if so,
will return control to the calling program. This can be done in any of three
possible states.
If COMND was able to interpret what was typed, and decided that it was an
appropriate response, then it returns normally with the data that it received
stored in a place where the program can easily retrieve it.
If COMND was unable to understand what was typed in the context of what it was
told to look for, then it will return with an error indicator set so that the
program will know that something went wrong.
The third possibility is best shown by example. Suppose a program desires to
obtain from the user first a file name, then a time of day. This will involve
two calls to COMND. When the first call is executed, suppose the user (call
him Fred) types in FOO.BAR as his file name. COMND accepts this as a valid
file name and returns normally to the calling program, which then executes
COMND again, this time asking for a time of day.
At this point, Fred decides that he really didn't want to use FOO.BAR, but
wanted FOO.BAZ instead. So he deletes back to the R and types in a Z, and
then he goes ahead and types in a time of day as required. Now it looks like
trouble ... COMND has already told the program that Fred wanted FOO.BAR, and
now it needs some way to let the program know that he changed his mind. In
COMND jargon, we say that a "reparse" is needed. COMND sets a flag to let the
program know what has happened, and now the program must start right from the
beginning and reissue all the calls that it made to COMND for the current
command line (this rather vague term will be firmed up shortly). Thus it
redoes the call to get a file name, and COMND fills in FOO.BAZ this time, and
then it continues with the time of day call just like before. If there had
been other calls on this command line before the file name, they too would
have to be reissued in the same order as they originally were called.
The term "command line" was used a few times in the preceeding paragraph, and
although it may have a fairly intuitive meaning, it also has a very strict
meaning in the context of the COMND jsys, which will be explained now and
should be kept in mind when trying to understand the reparse mechanism.
One of the calls that can be made to COMND is called "CMINI" (each different
call has its own slightly mnemonic name). The CM signifies that it has
something to do with COMND, and the INI stands for "INItialize". This call,
unlike the rest of the calls, accepts no input from the terminal. It is used
to set up initial values in the CSB and to type out the command line prompt.
The end of this prompt is the farthest back that a user may delete when typing
the prompted-for command.
A "command line", then, consists of all responses to COMND calls made between
COMND JSYS Page 104
successive CMINI's. For a reparse, the program reissues COMND calls starting
with the one after the CMINI call that initiated the command line. The CMINI
call should not be reissued. That would be done if an error were detected and
the entire command line had to be restarted. The difference is that when
CMINI is done, COMND forgets everything that was previously contained in the
buffer. This is appropriate for a complete restart after an error, but not
for merely backing up on a reparse.
A final general topic is the concept of multiple function calls. This refers
to giving COMND more than one alternative to look for. For instance, it may
be equally acceptable at a particular point in a command line for the user to
type either a date, or simply a decimal integer, specifying possibly a number
of days from the current date. It would be advantageous for COMND to know
about the alternatives and not have to return an error if the second
alternative were chosen.
To accomplish this, it is possible to have several FDB'S all linked together
in a chain. The first one contains a pointer to the second, which contains a
pointer to the third, etc. Then if COMND can't make sense of what is typed in
the context of the first FDB, it goes on and tries the next FDB, and so on
right down the line until it gets to an FDB that does not point to another
one. At that point, if none of the FDB's succeeded, an error condition is
finally signalled and COMND returns. If one of the FDB's does fit, then not
only is the normal data returned, but also the location of the succeeding FDB
so that the program will be able to determine what ultimately happened.
The same procedures apply to multiple FDB's as to single ones in regard to
reparsing, error restarts, etc. Remember that when using multiple FDB's only
one input item is parsed, not several. The multiple nature comes from the
fact that COMND is given several choices as to how it should attempt to
interpret that item.
Note that when using multiple FDB's, only one CSB is used. This fact
underlines the main difference between the natures of information stored in
the two blocks, the CSB being fairly call-independent, while almost all of the
information in the FDB depends on exactly what call is being made.
At this point you should have an idea of what is involved in getting the COMND
jsys to do your work for you.
Various people have written comprehensive sets of macros or UUO's to simplify
use of the COMND JSYS. Such macros appear in MACSYM, CUsym, and elsewhere. A
sample program is included in Chapter 11, and a description of Columbia's
COMND macro/UUO package is included in 7.1.
This remainder of the Chapter is taken intact from the Tops-20 v4
Monitor Calls Reference Manual.
5.2. General Information
COMND - JSYS 544
Parses one field of a command that is either typed by a user or contained in a
file. When this monitor call is used to read a command from a terminal, it
provides the following features:
COMND JSYS Page 105
1. Allows the input of a command (including the guide words) to be
given in abbreviated, recognition (ESC and CTRL/F), and/or full
input mode.
2. Allows the user to edit his input with the DELETE, CTRL/U, CTRL/W,
and CTRL/R editing keys.
3. Allows fields of the command to be defaulted if an ESC or CTRL/F is
typed at the beginning of any field or if a field is omitted
entirely.
4. Allows a help message to be given if a question mark (?) is typed
at the beginning of any field.
5. Allows input of an indirect file (@file) that contains the fields
for all or the remainder of the command.
6. Allows a recall of the correct portion of the last command (i.e.,
up to the beginning of the field where an error was detected) if
the next command line begins with CTRL/H. The correct portion of
the command is retyped, and the user can then continue typing from
that point.
7. Allows input of a line to be continued onto the next line if the
user types a hyphen (-) immediately preceding a carriage return.
(The carriage return is invisible to the program executing the
COMND call, although it is stored in the text buffer.) The hyphen
can be typed by the user while he is typing a comment. The comment
is then continued onto the next line.
The COMND call allows the command line that is input to contain a comment if
the comment is preceded by either an exclamation point or a semicolon and the
previous field has been terminated. When the COMND call inputs an exclamation
point after a field that has been terminated, it ignores all text on the
remainder of the line or up to the next exclamation point. When the COMND
call inputs a semicolon after a field that has been terminated, it ignores all
text on the remainder of the line.
When an indirect file is given on the command line, it can be given at the
beginning of any field. However, it must be the last item typed on the line,
and its contents must complete the current command. The user must terminate
his input of the indirect file (after any recognition is performed) with a
carriage return. If he does not terminate his input, the message ?INDIRECT
FILE NOT CONFIRMED is output. Also, if the user types a question mark
(instead of the file specification of the indirect file) after he types the
@ character, the message FILESPEC OF INDIRECT FILE is output. The indirect
file itself should not contain an ESC or carriage return; if these characters
are included, they will be treated as spaces. The contents of the indirect
file are placed in the text buffer but are not typed on the user's terminal.
As the user types his command, the characters are placed in a command text
buffer. This buffer can also include the command line prompt, if any.
Several byte pointers and counts reflect the current state of the parsing of
the command. These pointers and counts are as follows:
1. Byte pointer to the beginning of the prompting-text buffer
(.CMRTY). This pointer is also called the CTRL/R buffer byte
pointer since it indicates the initial part of the text that will
COMND JSYS Page 106
be output on a CTRL/R. (The remainder of the text output on a
CTRL/R is what the user had typed before he typed CTRL/R.) The
buffer containing the prompt need not be contiguous with the buffer
containing the remainder of the command line. Typically this
pointer is to a string in the literals area.
2. Byte pointer to the beginning of the user's input (.CMBFP). This
is the limit back to which the user can edit.
3. Byte pointer to the beginning of the next field to be parsed
(.CMPTR).
4. Count of the space remaining in the text input buffer (.CMCNT).
5. Count of the number of characters in the buffer that have not yet
been parsed (.CMINC).
The illustration below is a logical arrangement of the byte pointers and
counts. Remember that the prompting-text buffer does not have to be adjacent
to the text buffer.
.CMCNT
!=======================================================!
! ! ! ! !
! ! ! ! !
!=======================================================!
^ ^ ^
! ! !
! ! ! .CMINC
! ! !
! ! !
! .CMBFP .CMPTR
.CMRTY
These byte pointers and other information are contained in a command state
block, whose address is given as an argument to the COMND monitor call. The
.CMINI function initializes these pointers.
Parsing of a command is performed field by field and by default begins when
the user types a carriage return, ESC, CTRL/F, or question mark. These
characters are called action characters because they cause the system to act
on the command as typed so far. A field can also be terminated with a space,
tab, slash, comma, or any other nonalphanumeric character. Normally, the
parsing does not begin, and the COMND call does not return control to the
program, until an action character is typed. However, if B8(CM%WKF) is on in
word .CMFLG when the COMND call is executed, parsing begins after each field
is terminated.
The command is parsed by repeated COMND calls. Each call specifies the type
of field expected to be parsed by supplying an appropriate function code and
any data needed for the function. This information is given in a function
descriptor block. On successful completion of each call, the current byte
pointers and the counts are updated in the command state block, and any data
COMND JSYS Page 107
obtained for the field is returned.
The program executing the COMND call should not reset the byte pointers in the
command state block after it completes the parsing of each command. It should
set up the state block once at the beginning and then use the .CMINI function
when it begins parsing each line of a command. This is true because the
.CMINI function implements the CTRL/H error recovery feature in addition to
initializing the byte pointers in the state block and printing the prompt for
the line. If the program resets the pointers, the CTRL/H feature is not
possible because the pointers from the previous command are not available.
When a CTRL/H is input, the .CMINI function allows error recovery from the
last command only if both (1) the pointer to the beginning of the user's input
(.CMBFP) is not equal to the pointer to the beginning of the next field to be
parsed (.CMPTR) and (2) the last character parsed in the previous command was
not an end-of-line character.
The design of the COMND call allows the user to delete his typed input with
the DELETE, CTRL/W, and CTRL/U keys without regard to field boundaries. When
the user deletes into a field that has already been parsed, the COMND call
returns to the program with B3(CM%RPT) set in word .CMFLG. This return
informs the program to forget the current state of the command and to reparse
from the beginning of the line. Because the complete line as typed and
corrected by the user is in the text buffer, the parse can be repeated and
will yield the same result up to the point of the change.
The calling sequence to the COMND call is as follows:
ACCEPTS IN AC1: address of the command state block
AC2: address of the first alternative function descriptor
block
RETURNS +1: always (unless a reparse is needed and the right half
of .CMFLG is nonzero), with
AC1 containing flags in the left half, and the
address of the command state block in the right
half. The flags are copied from word .CMFLG in
the command state block.
AC2 containing either the data obtained for the field
or an error code if the field could not be parsed
(CM%NOP is on).
AC3 containing in the left half the address of the
function descriptor block given in the call, and
in the right half the address of the function
descriptor block actually used (i.e., the one
that matched the input).
The format of the command state block is shown below.
COMND JSYS Page 108
0 17 18 35
!=======================================================!
.CMFLG ! Flag Bits ! Reparse Dispatch Address !
!-------------------------------------------------------!
.CMIOJ ! Input JFN ! Output JFN !
!-------------------------------------------------------!
.CMRTY ! Byte Pointer to CTRL/R Text !
!-------------------------------------------------------!
.CMBFP ! Byte Pointer to Start of Text Buffer !
!-------------------------------------------------------!
.CMPTR ! Byte Pointer to Next Input To Be Parsed !
!-------------------------------------------------------!
.CMCNT ! Count of Space Left in Buffer !
!-------------------------------------------------------!
.CMINC ! Count of Characters Left in Buffer !
!-------------------------------------------------------!
.CMABP ! Byte Pointer to Atom Buffer !
!-------------------------------------------------------!
.CMABC ! Size of Atom Buffer !
!-------------------------------------------------------!
.CMGJB ! Address of GTJFN Argument Block !
!=======================================================!
Command State Block
Word (Symbol) Meaning
.CMFLG (0) Flag bits in the left half, and the reparse dispatch address
in the right half. Some flag bits can be set by the program
executing the COMND call; others can be set by the COMND call
after its execution. The bits that can be set by the program
are described following the Command State Block description.
The bits that can be set by COMND are described following the
Function Descriptor Block description.
The reparse dispatch address is the location to which control
is automatically transferred when a reparse of the command is
needed because the user edited past the current pointer (i.e.,
the user edited characters that were already parsed). If this
field is zero, the COMND call sets B3(CM%RPT) in the left half
of this word and gives the +1 return when a reparse is needed.
The program must then test CM%RPT and, if on, must reenter the
code that parses the first field of the command. When the
reparse dispatch address is given, control is transferred
automatically to that address.
The code at the reparse dispatch address should initialize the
program's state to what it was after the last .CMINI function.
This initialization should include resetting the stack
pointer, closing and releasing any JFNs acquired since the
last .CMINI function, and transferring control to the code
immediately following the last .CMINI function call.
.CMIOJ (1) Input JFN in the left half, and output JFN in the right half.
These designators identify the source for the input of the
command and the destination for the output of the typescript.
COMND JSYS Page 109
These designators are usually .PRIIN (for input) and .PRIOU
(for output).
.CMRTY (2) Byte pointer to the beginning of the prompting-text.
.CMBFP (3) Byte pointer to the beginning of the user's input. The user
cannot edit back past this pointer.
.CMPTR (4) Byte pointer to the beginning of the next field to be parsed.
.CMCNT (5) Count of the space remaining in the buffer after the .CMPTR
pointer.
.CMINC (6) Count of the number of unparsed characters in the buffer after
the .CMPTR pointer.
.CMABP (7) Byte pointer to the atom buffer, a temporary storage buffer
that contains the last field parsed by the COMND call. The
terminator of the field is not placed in this buffer. The
atom buffer is terminated with a null.
.CMABC (10) Count of the number of characters in the atom tbuffer. This
count should be at least as large as the largest field
expected to be parsed.
.CMGJB (11) Address of a GTJFN argument block. This block must be at
least 16(octal) words long and must be writable. If a longer
GTJFN block is being reserved, the count in the right half of
word .GJF2 of the GTJFN argument block must be greater than
four. This block is usually filled in by the COMND call with
arguments for the GTJFN call if the specifified function is
requesting a JFN (i.e., functions .CMIFI, .CMOFI, and .CMFIL).
The user should store data in this block on the .CMFIL
function only.
The flag bits that can be set by the user in the left half of word .CMFLG in
the Command State Block are described below. These bits apply to the parsing
of the entire command and are preserved by COMND after execution. See the end
of the COMND JSYS discussion for the bits that are returned by COMND in the
left half of word .CMFLG.
5.3. Bits Supplied in State Block on COMND Call
Symbol (bit) Meaning
CM%RAI (6) Convert lowercase input to uppercase.
CM%XIF (7) Do not recognize the @ character as designating an indirect
file; instead consider the character as ordinary unctuation.
A program sets this bit to prevent the input of an indirect
file.
CM%WKF (8) Begin parsing after each field is terminated instead of only
after an action character (carriage return, ESC, CTRL/F,
question mark) is typed. For example, a program sets this bit
if it must change terminal characteristics (e.g., it must turn
COMND JSYS Page 110
off echoing because a password may be input) in the middle of
a command. However, use of this bit is not recommended
because terminal wakeup occurs after each field is terminated,
thereby increasing system overhead. The recommended method of
changing terminal characteristics within a command is to input
the field requiring the special characteristic on the next
line with its own prompt. For example, if a program is
accepting a password, it should turn off echoing after the
.CMCFM function of the main command and perform the .CMINI
function to type the prompt requesting a password on the next
line.
The format of the function descriptor block is shown below.
0 8 9 17 18 35
!=======================================================!
! function ! function ! address of next function !
.CMFNP! code ! flags ! descriptor block !
!-------------------------------------------------------!
.CMDAT! Data for specific function !
!-------------------------------------------------------!
.CMHLP! Byte pointer to help text for field !
!-------------------------------------------------------!
.CMDEF! Byte pointer to default string for field !
!-------------------------------------------------------!
.CMBRK! Pointer to 4-word break mask !
!=======================================================!
5.4. Function Descriptor Block
Symbol (word) Meaning
.CMFNP (0) Function code and pointer to next function descriptor block
(FDB).
B0-B8(CM%FNC) Function code
B9-B17(CM%FFL) Function-specific flags
B18-B35(CM%LST) Address of the next FDB
.CMDAT (1) Data for the specific function, if any.
.CMHLP (2) Byte pointer to the help text for this field. This word can
be zero if the program is not supplying its own help text.
CM%HPP must be set (in word 0) in order for this pointer to be
used.
.CMDEF (3) Byte pointer to the default string for this field. This word
can be zero if the program is not supplying its own default
string.
.CMBRK (4) Pointer to a 4-word break mask that specifies which characters
constitute end of field. Word .CMBRK is ignored unless CM%BRK
(B13) is on.
The individual words in the function descriptor block are described in the
COMND JSYS Page 111
following paragraphs.
5.4.1. Words .CMFNP and .CMDAT of the FDB
Word .CMFNP contains the function code for the expected field to be parsed,
and word .CMDAT contains any additional data needed for that function. The
function codes, along with any required data for the functions, are described
below.
Symbol (code) Meaning
.CMKEY (0) Parse a keyword, such as a command name. Word .CMDAT contains
the address of a keyword symbol table in the format described
in the TBLUK monitor call description (i.e., alphabetical).
The data bits that can be defined in the right half of the
first word of the argument pointed to by the table entries
(when B0-B6 of the first word are off and B7(CM%FW) is on) are
as follows:
B35(CM%INV) Suppress this keyword in the list output on a
?. The program can set this bit to include
entries in the table that should be invisible
because they are not preferred keywords. For
example, this bit can be set to allow the
keyword LIST to be valid, even though the
preferred keyword may be PRINT. The LIST
keyword would not be listed in the output
given on a ?. This bit is also used in
conjunction with the CM%ABR bit to suppress an
abbreviation in the output given on a ?.
B34(CM%NOR) Do not recognize this keyword even if an exact
match is typed by the user and suppress its
listing in the list output on a ?. (Refer to
the TBLUK call description for more
information on using this bit.)
B33(CM%ABR) Consider this keyword a valid abbreviation for
another entry in the table. The right half of
this table entry points to the keyword for
which this is an abbreviation. The program
can set this bit to include entries in the
table that are less than the minimum unique
abbreviation. For example, this bit can be
set to include the entry ST (for START) in the
table. If the user then types ST as a
keyword, it will be accepted as a valid
abbreviation even though there may be other
keywords beginning with ST. To suppress the
output of this abbreviation in the list typed
on a ?, the program must also set the CM%INV
bit.
On a successful return from .CMKEY, AC2 contains the address of the table
entry where the keyword was found.
COMND JSYS Page 112
CMNUM (1) Parse a number. Word .CMDAT contains the radix from 2 to 10)
of the number. On a successful return, AC2 contains the
number.
.CMNOI (2) Parse a guide word string, but do not return an error if no
guide word is input. An error is returned only if a guide
word is input that does not match the one expected by the
COMND call. A guide word field must be delimited by
parentheses. Word .CMDAT contains a byte pointer to an ASCIZ
string. This string does not contain the parentheses of the
guide word. Guide words are output if the user terminated the
previous field with ESC. Guide words are not output, nor can
they be input, if the user has caused parsing into the next
field.
.CMSWI (3) Parse a switch. A switch field must begin with a slash and
can be terminated with a colon in addition to any of the legal
terminators. Word .CMDAT contains the address of a switch
keyword symbol table. (Refer to the TBLUK monitor call
description for the format of the table.) The entries in the
table do not contain the slash of the switch keywords;
however, they should end with a colon if the switch requires a
value. The data bits CM%INV, CM%NOR, and CM%ABR defined for
the .CMKEY function can also be set on this function. On a
successful return, AC2 contains the address of the table entry
where the switch keyword was found.
.CMIFI (4) Parse an input file specification. This function causes the
COMND call to execute a GTJFN call to attempt to parse the
specification for an existing file, using no default fields.
The .CMGJB address (word 11 in the command state block) must
be supplied, but the GTJFN block should be empty. (Data
stored in the block will be overwritten by the COMND JSYS.
Also, certain GTJFN flags are set.) On a successful return,
AC2 contains the JFN assigned. Hyphens are treated as
alphanumeric characters for this function
See note following .CMFIL function.
.CMOFI (5) Parse an output file specification. This function causes the
COMND call to execute a GTJFN call to attempt to parse the
specification for either a new or an existing file. The
default generation number is the generation number of the
existing file plus 1. The .CMGJB address must be supplied,
but the GTJFN block should be empty. (Data stored in the
block will be overwritten by the COMND JSYS. Also, certain
GTJFN flags are set.) On a successful return, AC2 contains
the JFN assigned. Hyphens are treated as alphanumeric
characters for this function.
See note following .CMFIL function.
.CMFIL (6) Parse a general (arbitrary) file specification. This function
causes the COMND call to execute a GTJFN to attempt to parse
the specification for the file. The .CMGJB address must be
supplied, but data stored in certain words of the GTJFN block
will be overwritten by the COMND JSYS and certain GTJFN flags
will be set (see note below). On a successful return, AC2
COMND JSYS Page 113
contains the JFN assigned. Hyphens are treated as
alphanumeric characters for this function.
Note that portions of the GTJFN block used by functions
.CMOFI, .CMIFI, and .CMFIL are controlled by COMND. The
following list shows which words are under the control of
COMND and which words are under the control of the user:
GTJFN Controlled Characteristics
Word(s) by
.GJGEN COMND
1. .CMOFI sets flags
GJ%FOU, GJ%MSG, and
GJ%XTN and clears all
other flags.
2. .CMIFI sets flag
GJ%OLD, and GJ%XTN
and clears all other
flags.
3. .CMOFI and .CMIFI
zero the right half
of word .GJGEN
4. .CMFIL sets flag
GJ%XTN and clears
GJ%FCM
.GJSRC COMND None
.GJDEV -
.GJJFN COMND/
USER Functions .CMIFI AND
.CMOFI give COMND control
of these words. .CMFIL
gives the user control of
these words.
.GJF2 -
.GJATR COMND None
.CMFLD (7) Parse an arbitrary field. This function is useful for fields
not normally handled by the COMND call. The input, as
delimited by the first nonalphanumeric character, is copied
into the atom buffer; the delimiter is not copied. Note the
following:
1. This function will parse a null field
2. Hyphens are treated as alphanumeric characters for
this function
3. No validation is performed (such as filename
validation)
4. No standard help message is available (see below)
COMND JSYS Page 114
5. The FLDBK. and BRMSK. macros may be used for
including other characters in the field (like "*").
.CMCFM (10) Confirm. This function waits for the user to confirm the
command with a carriage return and should be used at the end
of parsing a command line.
.CMDIR (11) Parse a directory name. Login and files-only directories are
allowed. Word .CMDAT contains data bits for this function.
The currently defined bit is as follows:
B0(CM%DWC) Allow wildcard characters
On a successful return, AC2 contains the 36-bit directory
number.
.CMUSR (12) Parse a user name. Only login directories are allowed. On a
successful return, AC2 contains the 36-bit user number.
.CMCMA (13) Comma. Sets B1(CM%NOP-no parse) in word .CMFLG of the command
state block and returns if a comma is not the next item in the
input. Blanks can appear on either side of the comma. This
function is useful for parsing a list of arguments.
.CMINI (14) Initialize the command line (e.g., set up internal monitor
pointers, type the prompt, and check for CTRL/H). This
function should be used at the beginning of parsing a command
line but not when reparsing a line. Otherwise, the CTRL/H
feature will not work.
To use this function, the user first moves the appropriate
data into the command state block and then issues .CMINI. If,
at any time during the parsing of a line, an error occurs,
.CMINI is issued again to reinitialize the line. However, for
the 2'nd thru N'th invocation of .CMINI for a given line, the
user should not alter the byte pointers and character counts
in the command state block. To do so would disable the CTRL/H
feature. This feature allows the user program, on parsing a
bad atom, to print an error message, reissue the prompt, and
parse the command line again without forcing the user to
retype the entire line.
If .CMINI reads a CTRL/H character, .CMINI will reset all byte
pointers and character counts except the .CMINC count to their
original state. .CMINI will set the .CMINC count to the
number of characters in the buffer up to the bad atom. These
characters are output to the terminal and parsed again.
Control then passes to the reparse address (if provided) and
normal parsing resumes. The effect on the program is as if
the bad atom had never been typed.
.CMFLT (15) Parse a floating-point number. On a successful return, AC2
contains the floating-point number.
.CMDEV (16) Parse a device name. On a successful return, AC2 contains the
device designator.
.CMTXT (17) Parse the input text up to the next carriage return, place the
COMND JSYS Page 115
text in the atom buffer, and return. If an ESC or CTRL/F is
typed, it causes the terminal bell to ring (because
recognition is not available with this function) and is
otherwise ignored. If a ? is typed, an appropriate response
is given, and the ? is not included in the atom buffer. (A ?
can be included in the input text if it is preceded by a
CTRL/V.)
.CMTAD (20) Parse a date and/or time field according to the setting of
bits CM%IDA and CM%ITM. The user must input the field as
requested. Any date format allowed by the IDTIM call can be
input. If a date is not input, it is assumed to be the
current date. If a time is not input, it is assumed to be
00:00:01. When both the date and time fields are input, they
must be separated by one or more spaces. If the fields are
input separately, they must be terminated with a space or
carriage return. Word .CMDAT contains bits in the left half
and an address in the right half as data for the function.
The bits are:
B0(CM%IDA) Parse a date
B1(CM%ITM) Parse a time
B2(CM%NCI) Do not convert the date and/or time to
internal format.
The address in the right half is the beginning of a 3-word
block in the caller's address space. On a successful return,
this block contains data returned from the IDTNC call executed
by COMND if B2(CM%NCI) was on in the COMND call (i.e., if the
input date and/or time field was not to be converted to
internal format). If B2(CM%NCI) was off in the COMND call, on
a successful return, AC2 contains the internal date and time
format.
.CMQST (21) Parse a quoted string up to the terminating quote. The
delimiters for the string must be double quotation marks and
are not copied to the atom buffer. A double quotation mark is
input as part of the string if two double quotation marks
appear together. This function is useful if the legal field
terminators and the action characters are to be included as
part of a string. The characters ?, ESC, and CTRL/F are not
treated as action characters and are included in the string
stored in the atom buffer. Carriage return is an invalid
character in a quoted string and causes B1(CM%NOP) to be set
on return.
.CMUQS (22) Parse an unquoted string up to one of the specified break
characters. Word .CMDAT contains the address of a 4-word
block of 128 break character mask bits. (Refer to word .RDBRK
of the TEXTI call description for an explanation of the mask.)
The characters scanned are not placed in the atom buffer. On
return, .CMPTR is pointing to the break character. This
function is useful for parsing a string with an arbitrary
delimiter. The characters ?, ESC, and CTRL/F are not treated
as action characters (unless they are specified in the mask)
and can be included in the string. Carriage return can also
be included if it is not one of the specified break
characters.
COMND JSYS Page 116
.CMTOK (23) Parse the input and compare it with a given string ("token").
Word .CMDAT contains the byte pointer to the given string.
This function sets B1(CM%NOP) in word .CMFLG of the command
state block and returns if the next input characters do not
match the given string. Leading blanks in the input are
ignored. This function is useful for parsing single or
multiple character operators (e.g., + or **).
.CMNUX (24) Parse a number and terminate on the first non-numeric
character. Word .CMDAT contains the radix (from 2 to 10) of
the number. On a successful return, AC2 contains the number.
This function is useful for parsing a number that may not be
terminated with a nonalphabetic character (e.g., 100PRINT
FILEA).
Note that non-numeric identifiers can begin with a digit
(e.g., 1SMITH as a user name). When a non-numeric identifier
and a number appear as alternates for a field, the order of
the function descriptor blocks is important. The .CMNUX
function, if given first, would accept the digit in the
non-numeric identifier as a valid number instead of as the
beginning character of a non-numeric identifier.
.CMACT (25) Parse an account string. The input, as delimited by the first
nonalphanumeric character, is copied into the atom buffer; the
delimiter is not copied. No verification is performed nor is
any standard help message available.
.CMNOD (26) Parse a network node name. A node name consists of up to six
alphanumeric characters followed by 2 colons ("::").
Lowercase characters are converted to uppercase characters.
The node name is copied into the atom buffer without the
colons. Note that this function does not verify the existence
of the node.
In addition to the .CMFNP word of the function descriptor block containing the
function code in bits 0-8 (CM%FNC), this word also contains function-specific
flag bits in bits 9-17 (CM%FFL) and the address of another function descriptor
block in bits 18-35 (CM%LST).
The flag bits that can be set in bits 9-17 (CM%FFL) are as follows:
Symbol (bit) Meaning
CM%PO (14) The field is to be parsed only and the field's existence is
not to be verified. This bit currently applies to the .CMDIR
and .CMUSR functions and is ignored for the remaining
functions. On return, COMND sets B1(CM%NOP-no parse) only if
the field typed is not in the correct syntax. Also, data
returned in AC2 may not be correct.
CM%HPP (15) A byte pointer to a program-supplied help message for this
field is given in word 2 (.CMHLP) of this function descriptor
block.
CM%DPP (16) A byte pointer to a program-supplied default string for this
field is given in word 3 (.CMDEF) of this function descriptor
block.
COMND JSYS Page 117
CM%SDH (17) The output of the default help message is to be suppressed if
the user types a question mark. (See below for the default
messages.)
The address of another function descriptor block can be given in bits 18-35
(CM%LST) of the .CMFNP word. The use of this second descriptor block is
described below.
Usually one COMND call is executed for each field in the command. However,
for some fields, more than one type of input may be possible (e.g., after a
keyword field, the next field could be a switch or a filename field). In
these cases, all the possibilities for a field must be tried in an order
selected to test unambiguous cases first.
When the COMND call cannot parse the field as indicated by the function code,
it does one of two things:
1. It sets the current pointer and counts such that the next call will
attempt to parse the same input over again. It then returns with
B1(CM%NOP) set in the left half of the .CMFLG word in the command
state block. The caller can then issue another COMND call with a
function code indicating another of the possible fields. After the
execution of each call, the caller should test the CM%NOP flag to
see if the field was parsed successfully.
2. If an address of another function descriptor block is given in
CM%LST, the COMND call moves to this descriptor block automatically
and attempts to parse the field as indicated by the function code
contained in B0-B8(CM%FNC) in word .CMFNP of that block. If the
COMND call fails to parse the field using this new function code,
it moves to a third descriptor block if one is given. This
sequence continues until either the field is successfully parsed or
the end of the chain of function blocks is reached. Upon
completion of the COMND call, AC3 contains the addresses of the
first and last function blocks used.
By specifying a chained list of function blocks, the program can have the
COMND call automatically check all possible alternatives for a field and not
have to issue a separate call for each one. In addition, if the user types a
question mark, a list is output of all the alternatives for the field as
indicated by the list of function descriptor blocks.
5.4.2. Word .CMHLP of the FDB
This word contains a byte pointer to a program-supplied help text to be output
if the user types a question mark when entering his command. The default help
message is appended to the output of the program-supplied message if
B17(CM%SDH) is not set. If B17(CM%SDH) is set, only the program-supplied
message is output. If this word in the descriptor block is zero, only the
default message is output when the user types a question mark. Bit 15(CM%HPP)
must be set in word 0 (.CMFNP) of the function descriptor block for this
pointer to be used. The default help message depends on the particular
function being used to parse the current field. The table below lists the
default help message for each function available in the COMND call.
COMND JSYS Page 118
5.4.3. Default Help Messages
Function Message
.CMKEY (keyword) ONE OF THE FOLLOWING followed by the alphabetical list of
valid keywords. If the user types a question mark in the
middle of the field, only the keywords that can possibly match
the field as currently typed are output. If no keyword can
possibly match the currently typed field, the message KEYWORD
(NO DEFINED KEYWORDS MATCH THIS INPUT) is output.
.CMNUM (number) The help message output depends on the radix specified in
.CMDAT in the descriptor block. If the radix is octal, the
help message is OCTAL NUMBER If the radix is decimal, the help
message is DECIMAL NUMBER If the radix is any other radix, the
help message is A NUMBER IN BASE nn where nn is the radix.
.CMNOI (guide word) None
.CMSWI (switch) ONE OF THE FOLLOWING followed by the alphabetical list of
valid switch keywords. The same rules apply as for .CMKEY
function. (See above.)
.CMIFI (input file) The help message output depends on the
.CMOFI (output file) settings of certain bits in the GTJFN call.
.CMFIL (any file) If bit GJ%OLD is off and bit GJ%FOU is on, the help message
is OUTPUT FILESPEC Otherwise, the help message is INPUT
FILESPEC
.CMFLD (any field) None
.CMCFM (confirm) CONFIRM WITH CARRIAGE RETURN
.CMDIR (directory) DIRECTORY NAME
.CMUSR (user) USER NAME
.CMCMA (comma) COMMA
.CMINI (initialize) None
.CMFLT (floating point) NUMBER
.CMDEV (device) DEVICE NAME
.CMTXT (text) TEXT STRING
.CMTAD (date) The help message depends on the bits set in .CMDAT in the
descriptor block. If CM%IDA is set, the help message is DATE
If CM%ITM is set, the help message is TIME If both are set,
the help message is DATE AND TIME
.CMQST (quoted) QUOTED STRING
.CMUQS (unquoted) None
COMND JSYS Page 119
.CMTOK (token) None
.CMNUX (number) Same as .CMNUM
.CMACT (account) None
.CMNOD (node) NODE NAME
5.4.4. Word .CMDEF of the FDB
This word contains a byte pointer to the ASCIZ string to be used as the
default for this field. For this pointer to be used, bit 16 (CM%DPP) must be
set in word 0 (.CMFNP) of the descriptor block. The string is output to the
destination, as well as copied to the text buffer, if the user types an ESC or
CTRL/F as the first non-blank character in the field. If the user types a
carriage return, the string is copied to the atom buffer but is not output to
the destination.
When the caller supplies a list of function descriptor blocks, the byte
pointer for the default string must be included in the first block. The
CM%DPP bit and the pointer for the default string are ignored when they appear
in subsequent blocks. However, the default string can be worded so that it
will apply to any of the alternative fields. The effect is the same as if the
user had typed the given string.
Defaults for fields of a file specification can also be supplied with the
.CMFIL function. If both the byte pointer to the default string and the GTJFN
defaults have been provided, the COMND default will be used first and then, if
necessary, the GTJFN defaults.
NOTE: The function descriptor block, whose address is given in AC2,
can be set up by the FLDDB. and FLDBK. macros defined in MACSYM. (See
end of COMND section for a description of these macros.)
5.4.5. Word .CMBRK of the FDB
This word contains a pointer to a 4-word user-specified mask that determines
which characters constitute end of field. The leftmost 32 bits of each word
correspond to a character in the ASCII collating sequence (in ascending
order). If the bit is on for a given character, typing that character will
cause the COMND JSYS to treat the characters typed so far as a separate field
and parse it according to the function being used. CM%BRK (B13) must be on in
the first word of the function descriptor block or COMND will ignore word
.CMBRK.
Ordinarily, the user would rely on COMND's default masks (varying according to
function) to specify which characters signal end of field and thus would not
be concerned with word .CMBRK of the function block. However, for special
purposes such as allowing "*" or "%" to be part of a field rather than a field
delimiter, the user must specify his own mask. (In this example, the bits for
"*" and "%" would be off in the mask word.) The user may inspect COMND's
default masks (defined in MONSYM) for help in designing a custom mask.
The following is a list of the COMND functions that use masks:
COMND JSYS Page 120
Mask COMND Changeable
Symbols Function by User
KEYB0. - KEYB3. .CMKEY Yes
DEVB0. - DEVB3. .CMDEV Yes (only if parse-only)
FLDB0. - FLDB3. .CMFLD Yes
EOLB0. - EOLB3. .CMTXT Yes
KEYB0. - KEYB3. .CMSWI Yes
User specified .CMDAT Yes
USRB0. - USRB3. .CMUSR No
FILB0. - FILB3. .CMFIL No
FILB0. - FILB3. .CMIFI No
FILB0. - FILB3. .CMOFI No
internal .CMNUM No
FILB0. - FILB3. .CMDIR No
internal .CMFLT No
ACTB0. - ACTB3. .CMACT No
COMND will ignore any break masks that are specified for functions that do not
allow user-modified masks.
Note that specifying a zero mask with CM%BRK set will cause the TTY line
buffer to fill up and generate an error.
On a successful return, the COMND call returns flag bits in the left half of
AC1 and preserves the address of the command state block in the right half of
AC1. These flag bits are copied from word .CMFLG in the command state block
and are described as follows.
5.5. Bits Returned on COMND Call
Symbol (bit) Meaning
CM%ESC (0) An ESC was typed by the user as the terminator for this field.
CM%NOP (1) The field could not be parsed because it did not conform to
the specified function(s). An error code is returned in AC2.
CM%EOC (2) The field was terminated with a carriage return.
CM%RPT (3) Characters already parsed need to be reparsed because the user
edited them. This bit does not need to be examined if the
program has supplied a reparse dispatch address in the right
half of .CMFLG in the command state block.
CM%SWT (4) A switch field was terminated with a colon. This bit is on if
the user either used recognition on a switch that ends with a
colon or typed a colon at the end of the switch.
CM%PFE (5) The previous field was terminated with an ESC.
When a field cannot be parsed, B1(CM%NOP) is set in AC1, and one of the
following error codes is returned in AC2. Note that if a list of function
descriptor blocks is given and an error code is returned, the error is
associated with the last function descriptor block in the list.
COMND JSYS Page 121
NPXAMB: ambiguous
NPXNSW: not a switch - does not begin with slash
NPXNOM: does not match switch or keyword
NPXNUL: null switch or keyword given
NPXINW: invalid guide word
NPXNC: not confirmed
NPXICN: invalid character in number
NPXIDT: invalid device terminator
NPXNQS: not a quoted string - does not begin with double quote
NPXNMT: does not match token
NPXNMD: does not match directory or user name
NPXCMA: comma not given
COMX18: invalid character in node name
COMX19: too many characters in node name
5.6. Macros
Several macros (defined in MACSYM) are available to make using the COMND JSYS
more convenient. These macros are as follows:
5.6.1. FLDDB.(TYP,FLGS,DATA,HLPM,DEFM,LST)
where:
TYP = function type
FLGS = function flags
DATA = function-specific data
HLPM = help message
DEFM = default text
LST = additional invocations of the FLDDB. macro (used
only if multiple function blocks are required)
This macro generates function descriptor blocks for COMND. For example, the
following code would perform a .CMINI function:
MOVEI T1,STEBLK ; Get address of COMND state block
MOVEI T2,[FLDDB.(.CMINI)] ; Get address of function block
COMND
COMND JSYS Page 122
The following code would perform a .CMKEY function (assuming that the keyword
table started at address CMDTAB:
MOVEI T1,STEBLK ; Get address of COMND state block
MOVEI T2,[FLDDB(.CMKEY,<CM%DPP+CM%+CM%HPP>,CMDTAB,
<help text>,<default text>)]
COMND
5.6.2. FLDBK.(TYP,FLGS,DATA,HLPM,DEFM,BRKADR,LST)
This is exactly the same as FLDDB. except that a provision has been made for
the address of the first word of a 4-word character mask (BRKADR). This
version is for use when a user-specified character mask is required.
5.6.3. BRMSK.(INI0,INI1,INI2,INI3,ALLOW,DISALLOW)
where:
INI0 = first word of character mask
INI1 = second word of character mask
INI2 = third word of character mask
INI3 = fourth word of character mask
ALLOW = characters to allow in the mask
DISALLOW = characters to disallow in the mask
This macro generates 4-word character masks for use with those COMND functions
that allow the user to specify his own mask. For example, executing the
following code would allow "*" in the predefined mask for the .CMFLD function
(FLDB0 thru BLDB3):
BRMSK.(FLDB0.,FLDB1.,FLDB2.,FLDB3.,<*>,)
5.6.4. FLDBK.
Also, the BRMSK. macro may be invoked within the FLDBK. macro:
FLDBK.(TYP,FLGS,DATA,HLPM,DEFM,[
BRMSK.(INI0,INI1,INI2,INI3,ALLOW,DISALLOW)],LST)
The COMND call causes other monitor calls to be executed, depending on the
particular function that is requested. Failure of these calls usually results
in the failure to parse the requested field. In these cases, the relevant
error code can be obtained via the GETER and ERSTR monitor calls.
- Any TBLUK error can occur on the keyword and switch functions.
- Any NIN/NOUT and FLIN/FLOUT error can occur on the number functions.
COMND JSYS Page 123
- Any GTJFN error except for GJFX37 can occur on the file
specification functions.
- Any IDTNC error can occur on the date/time function.
- Any RCDIR or RCUSR error can occur on the directory and user
functions.
- Any STDEV error can occur on the device function.
5.7. Errors
Generates an illegal instruction interrupt on error conditions below.
COMND ERROR MNEMONICS:
COMNX1: invalid COMND function code
COMNX2: field too long for internal buffer
COMNX3: command too long for internal buffer
COMNX5: invalid string pointer argument
COMNX8: number base out of range 2-10
COMNX9: end of input file reached
COMX10: invalid default string
COMX11: invalid CMRTY pointer
COMX12: invalid CMBFP pointer
COMX13: invalid CMPTR pointer
COMX14: invalid CMABP pointer
COMX15: invalid default string pointer
COMX16: invalid help message pointer
COMX17: invalid byte pointer in function block
MACSYM Page 124
6. MACSYM System Macros
This chapter was written by Dan Murphy, Digital Equipment
Corporation, July 1976.
6.1. Introduction
MACSYM is a file of standard macro and symbol definitions for use with TOPS20
machine language programs. Use of these definitions is recommended as a means
of producing more consistent and readable MACRO sources. Some of the
definitions were obtained from C.MAC; others will be added if they are
generally useful.
MACSYM is available on SYS: in two forms, MACSYM.UNV and MACREL.REL. The
first is the universal file of macro and symbol definitions; the second is a
file of small support routines used by certain of the facilities (e.g., stack
variables). The universal file is normally obtained at assembly time by the
source statement
SEARCH MACSYM
The object file, if necessary, may be obtained by the source statement
.REQUIRE SYS:MACREL
This instructs LINK to load the object file along with the main program. The
file is loaded only once even if the .REQUIRE appears in several source
modules, and no explicit LINK command need be given.
Certain conventions are observed regarding the construction of symbols as
follows: ("x" represents any alphanumeric)
xxxxx. an opdef or macro defininition
.xxxxx a constant value
xx%xxx a mask, i.e., a bit or bits which specify a field.
Symbols containing multiple periods may be used internally by some macros.
Symbols containing "$" are not used or defined by DEC and are reserved for
customer use.
6.2. Definitions
The following definitions are available in MACSYM and are arranged into groups
as shown.
MACSYM Page 125
6.2.1. Standard Program Version
This macro assembles the standard contents of .JBVER.
PGVER. VERS,UPDAT,EDIT,CUST
where
VERS is the major version number
UPDAT is the update or minor version number (1=A, 2=B, ...)
EDIT is the edit number
CUST is the customer/SWS edit code (1=SWS, 2-7= customer)
A word constructed from these quantities is assembled into absolute location
.JBVER (137); the current assembly location is restored.
6.2.2. Miscellaneous Constants (Symbols)
.INFIN = 377777,,777777 ;plus infinity
.MINFI = 400000,,0 ;minus infinity
.LHALF = 777777,,0 ;left half
.RHALF = 0,,777777 ;right half
.FWORD = 777777,,777777 ;full word
6.2.3. Control Characters (Symbols)
Symbols are defined for all control character codes 0 to 37 and 175-177. The
following are the commonly used characters; see source listing for others.
.CHBEL = 07 ;bell
.CHBSP = 10 ;backspace
.CHTAB = 11 ;tab
.CHLFD = 12 ;linefeed
.CHFFD = 14 ;formfeed
.CHCRT = 15 ;carriage return
.CHESC = 33 ;escape
.CHDEL = 177 ;delete (rubout)
6.2.4. PC Flags (Mask Symbols)
PC%OVF = 1B0 ;overflow
PC%CYO = 1B1 ;carry 0
PC%CY1 = 1B2 ;carry 1
PC%FOV = 1B3 ;floating overflow
PC%BIS = 1B4 ;first part done (byte increment
suppress)
PC%USR = 1B5 ;user mode
MACSYM Page 126
PC%UIO = 1B6 ;user IO mode
PC%LIP = 1B7 ;last instruction public
PC%AFI = 1B9 ;ADDRESS FAILURE INHIBIT
PC%ATN = 1B10 ;apr trap number
PC%FUF = 1B11 ;floating underflow
PC%NDV = 1B12 ;no divide
6.2.5. Macros to Manipulate Field Masks
Many of the symbols in MACSYM and MONSYM define flag bits and fields. A field
mask is a full-word value with a single contiguous group of 1's in the field.
E.g., 000000,,777000 defines a field consisting of bits 18-26. The following
macros may be used in expressions to deal with these masks.
6.2.5.1. WID(MASK)
Width - computes the width of the field defined by the mask, i.e., the number
of contiguous 1-bits. Value is not defined if mask contains non-contiguous
1-bits.
6.2.5.2. POS(MASK)
Position - computes the position of the field defined by the mask. The
position of a field is always represented by the bit number of the rightmost
bit of the field regardless of the width of the field. This is sufficient to
specify the entire field in the case of flags (1-bit fields).
6.2.5.3. POINTR(LOC,MASK)
Byte pointer - constructs a byte pointer to location LOC which references the
byte defined by MASK, e.g.,
POINTR(100,77) = POINT 6,100,35 = 000600,,100
6.2.5.4. FLD(VAL,MASK)
Field value - Places the value VAL into the field defined by MASK, e.g.,
FLD(3,700) = 0,,000300
6.2.5.5. .RTJST(VAL,MASK)
Right-justify - Shift VAL right such that the field defined by MASK is moved
to the low-order bits of the word, e.g.,
.RTJST(300,700) = 3
MACSYM Page 127
6.2.5.6. MASKB(LBIT,RBIT)
Mask - construct a mask word which defines a field from bit LBIT to bit RBIT
inclusive. E.g., MASKB(18,26) = 0,,777000.
6.2.6. Instructions Using Field Masks (Macros)
The following mnemonics are similar to certain machine instructions used to
move and test bits and fields. These macros select the most efficient
instruction for the mask being used.
6.2.6.1. MOVX AC,MASK
Load AC with constant. MASK may be any constant; this assembles one of the
following instructions: MOVEI, MOVSI, HRROI, HRLOI, or MOVE literal.
6.2.6.2. TXmn AC,MASK
where m is: N, Z, O, C
n is: E, N, A, null
There are 16 definitions of this form which include all of the modification
and testing combinations fo the test instructions, i.e., TXNN, TXNE, TXO,
TXON, etc. A TL, TR, or TD literal is assembled as appropriate.
6.2.6.3. IORX AC,MASK; ANDX AC,MASK; XORX AC,MASK
These are equivalent to certain of the TX functions but are provided for
mnemonic value.
6.2.6.4. JXm AC,MASK,ADDRESS
This is a set of four definitions which jump to ADDRESS if the field specified
by MASK meets a certain condition. The condition (m) may be:
E - jump if all masked bits are 0
N - jump if not all masked bits are 0
O - jump if all masked bits are 1
F - jump if not al masked bits are 1 (false)
These macros will assemble into one, two, or three instructions as necessary
to effect the specified result, e.g.
JXN T1,1B0,FOO = JUMPL T1,FOO
JXE T1,770,FOO = TRNN T1,770
JRST FOO
MACSYM Page 128
6.2.7. Data Structure Facility (Macros)
This set of macros provides a comprehensive facility for the definition and
use of data structures. It is an extension of some of the techniques
represented by the field mask facilities above. Typically, a data structure
definition will include some information about the location of the data in
memory as well as its position within a word. These facilities are intended
to provide the following advantages:
- Data items may be referenced more mnemonically, e.g., two data items
in the same word would be given different names rather than merely
being known as the left half or right half of the word.
- Should the need arise, storage formats may be changed without
incurring the expense of a search of the code to change each
reference.
6.2.7.1. DEFSTR and MSKSTR
DEFSTR NAME,LOCATION,POSITION,SIZE
MSKSTR NAME,LOCATION,MASK
These macros both define a data structure called NAME. LOCATION specifies the
memory location of the desired word and consists of address, index, and
indirect fields in the usual form, i.e., @address(index). Any of the fields
may be omitted if not needed, and the entire location argument may be null in
some circumstances. The remaining arguments define the desired field. DEFSTR
specifies the field in terms of its position (right-most bit number) and size
(number of bits), while MSKSTR specifies the field by a full-word mask as
described earlier. Normally, the actual storage to be used is declared
separately, e.g., by a BLOCK statement.
As a simple example, consider an array of full-word data items. We wish to
use the name FOO for the data itself, so we declare the actual storage by some
other name, e.g.,
FOO1: BLOCK n
Then we declare the structure by
DEFSTR FOO,FOO1(FOOX),35,36
This says that we declare a data item called FOO, that the items are addressed
by FOO1(FOOX) (assuming that the index is kept in register FOOX), that the
items are 36-bit quantities with the rightmost bit in bit 35 (i.e., full
words). If instead, we wish to declare that each word of FOO1 consists of an
item in the left half and two 9-bit items in the right half, we could write:
DEFSTR FIRSTD,FOO1(FOOX),17,18 ; LH item.
DEFSTR SECOND,FOO1(FOOX),26,9 ; One 9-bit item
DEFSTR THIRDD,FOO1(FOOX),35,9 ; Another 9-bit item.
Data items defined with DEFSTR or MSKSTR may be referenced in a general way.
MACSYM Page 129
At each instance, additional location information may be given if necessary.
A set of reference functions (macros) is defined for most common operations,
some affecting AC and memory, others only memory. For example, the LOAD
function loads a data item into an AC and is written as
LOAD AC,NAME,LOCATION
where
AC is the AC to be loaded
NAME is the structure name as defined with DEFSTR
LOC is location specification in addition to that declared in the
structure definition. This field may be null in some cases.
Taking the example definitions above, we may write
LOAD T1,FOO
which would assemble into
MOVE T1,FOO1(FOOX)
or
LOAD T1,SECOND = LDB T1,[POINT 9,FOO1(FOOX),26]
LOAD T1,FIRSTD = HLRZ T1,FOO1(FOOX)
Note that the macro compiles the most efficient instruction available to
reference the specified field.
The optional third argument is provided to allow some of the location
information to be specified at each instance. For example, if the definition
is
DEFSTR FOO,FOO1,35,36
Then the index may be specified at each instance, e.g.,
LOAD T1,FOO,(XX)
LOAD T2,FOO,(T1)
The specification given in the definition is concatentated with the
specification given in the reference.
The following reference functions are presently defined:
LOAD AC,NAME,LOC load data item into AC
STOR AC,NAME,LOC store data item from AC into
memory
The data item is right justified in the AC.
MACSYM Page 130
SETZRO NAME,LOC set the data item to zero
SETONE NAME,LOC set the data item to all ones
SETCMP NAME,LOC complement the data item
INCR NAME,LOC increment the data item
DECR NAME,LOC decrement the data item
For functions not specifically provided, the following may be used:
OPSTR OP,NAME,LOC
OPSTRM OP,NAME,LOC
OP is any machine instruction written without an address field. It will be
assembled such as to reference the specified data structure. OPSTR is used if
memory is not modified, OPSTRM is used if memory is modified. E.g.,
OPSTRM <ADDM T1,>,FOO
to add the quantity in T1 to the data item FOO.
The following test and transfer functions are presently defined:
JE NAME,LOC,ADDR jump to ADDR if data is 0
JN NAME,LOC,ADDR jump to ADDR if data is not 0
The following test and transfer functions take a list of structure names
(surrounded by angle-brackets) or a single structure name. They compile code
to test each data item in the order given, and will stop as soon as the result
of the function is known (e.g., AND encounters a false term).
JOR NAMLST,LOC,ADDR jump to ADDR if any data item is true
(non-0)
JAND NAMLST,LOC,ADDR jump to ADDR if all data items true
(non-0)
JNOR NAMLST,LOC,ADDR jump to ADDR if all data items false
(0)
JNAND NAMLST,LOC,ADDR jump to ADDR if any data item is false
(0)
These functions optimize multiple fields in the same word if they are adjacent
in the structure list. If the final location is an accumulator, further
optimization is done.
As a final example of the data structure facility, consider the typical case
of data organized into unit blocks with pointers to other blocks. Such a
block may appear as
Flag 1 Flag 2 Code List pointer
! ! ! !
V V v V
+---+---+---------+---------+-------------------------+
! ! !/////////! ! !
+---+---+---------+---------+-------------------------+
! additional node data !
+-----------------------------------------------------+
! '''''''' !
MACSYM Page 131
We assume that n-word blocks will be allocated from a free pool at execution
time. The structure of the block is declared as follows:
MSKSTR FLAG1,0,1B0
MSKSTR FLAG2,0,1B1
DEFSTR CODE,0,17,9
DEFSTR LINK,0,35,18
DEFSTR NODDAT,1,35,36
Note that the location field contains only the offset address of the word
within the block; the address of the block will be specified in an index at
each reference. References would appear as follows:
LOAD T1,LINK,(T1) ;step to next node in list
STOR T2,CODE,(T1) ;set new block code
JE FLAG1,(T1),FLOFF ;jump if flag1 is off
JAND <FLAG1,FLAG2>,(T1),FLGSON ;jump if flag1 and
; flag2 are both on
6.2.8. Subroutine Conventions (Macros/opDefs)
The following definitions are used to make subroutine mechanics more mnemonic.
Reference is made to these conventions elsewhere in this document.
6.2.8.1. CALL address
Call subroutine at address; equivalent to PUSHJ P,address
6.2.8.2. RET
Return from subroutine; equivalent to POPJ P,
6.2.8.3. RETSKP
Return from subroutine and skip; equivalent to
JRST [AOS 0(P)
RET]
6.2.8.4. CALLRET address
Call the subroutine at address and return immediately thereafter; equivalent
to
MACSYM Page 132
CALL address
RET
RETSKP
CALLRET assembles as JRST but should be treated as if it assembles into
several instructions and cannot be skipped over.
6.2.8.5. AC Conventions
The facilities described here assume in some cases the following accumulator
naming conventions:
AC1-AC4 temporary, may be used to pass and return values
AC0,AC5-AC15 preserved, i.e., saved and restored if used by subroutine
AC16 temporary, used as scratch by some MACSYM facilities
AC17 stack pointer
6.2.9. Named Variable Facilities (Macros and Runtime Code)
A traditional deficiency of machine language coding environments is facilities
for named transient storage ("automatic", etc.). Sometimes, permanent storage
is assigned (e.g., by BLOCK statements) when no recursion is expected. More
often, ACs are used for a small number of local variables. In this case, the
previous contents must usually be saved, and a general mnemonic (e.g., T1, A,
X) is usually used. In some cases, data on the stack is referenced, e.g.,
MOVE T1,-2(P)
but this is completely non-mnemonic and likely to fail if addition storage is
added to or removed from the stack. The facilities described here provide
local named variable storage. Two of these allocate the storage on the stack;
the third allocates it in the ACs.
6.2.9.1. STKVAR namelist
This statement allocates space on the stack and assigns local names. The list
consists of one or more symbols separated by commas. Each symbol is assigned
to one stack word. If more than one word is needed for a particular variable,
then a size parameter may be given enclosed with the symbol in angle-brackets.
E.g.,
STKVAR <AA,BB>
STKVAR <AA,<BB,3>>
Variables declared in this way may be referenced as ordinary memory operands,
e.g.,
MACSYM Page 133
MOVE T1,AA
DPB T1,[POINT 6,BB,5]
Each variable is assembled as a negative offset from the current stack
location, e.g.,
MOVE T1,AA = MOVE T1,-2(P)
Hence, no other index may be given in the address field. Indirection may be
used if desired. There is no explicit limit to the scope of the variables
defined by STKVAR, but the following logical constraints must be observed:
1. The stack pointer must not be changed within the logical scope of
the variables, e.g., by PUSH or PUSHJ instructions. This also
implies that the variables may not be referenced within a local
subroutine called from the declaring routine.
2. The declaring routine must return with a RET or RETSKP. This will
cause the stack storage to be automatically deallocated.
STKVAR assumes that the stack pointer is in P, and it uses .A16 (AC16) as a
temporary.
6.2.9.2. TRVAR namelist
This statement allocates stack space and assigns local names. It is
equivalent to STKVAR except that it uses one additional preserved AC and
eliminates some of the scope restrictions of STKVAR. In particular, it uses
.FP (AC15) as a frame pointer. .FP is setup (and the previous contents saved)
at the same time as the stack space is allocated, and references to the
variables use .FP as the index rather than P. This allows additional storage
to be allocated on the stack and allows the variables to be referenced from
local subroutines. Note that all such subroutines (i.e., all variable
references) must appear after the declaration in the source. STKVAR may be
used within TRVAR, e.g., by a local subroutine.
STKVAR and TRVAR declarations are normally placed at the beginning of a
routine. They need not be the first statement. If a routine has two or more
entry points, a single declaration may be placed in the common path, or
several identical declarations may be used in each of the separate paths.
Care must be taken that control passes through exactly one declaration before
any variables are referenced. E.g.,
MACSYM Page 134
;MAIN ROUTINE
ENT1: TXO F,FLAG ;entry 1, set flag
JRST ENT0 ;join common code
ENT2: TXZ F,FLAG ;entry 2, clear flag
ENT0: TRVAR <AA,BB> ;common code, declare locals
..
CALL LSUBR ;call local subroutine
..
RET
;LOCAL SUBROUTINE
LSUBR: STKVAR <CC> ;local subroutine, declare
; locals
MOVE T1,AA ;reference outer routine
; variable
MOVEM T1,CC ;reference local variable
..
RETSKP ;skip return
6.2.9.3. ASUBR namelist
This statement is used to declare formals for a subroutine. The namelist
consists of from one to four variable names. The arguments are passed to the
subroutine in ACs T1 to T4, and values may be returned in these same ACs.
ASUBR causes these four ACs to be stored on the stack (regardless of how many
formals are declared), and defines the variable names as the corresponding
stack locations. The return does not restore T1-T4. The same frame pointer
AC is used by ASUBR and TRVAR, hence these declarations may not be used within
the same routine. Scope rules are the same as for TRVAR.
6.2.9.4. ACVAR namelist
This statement declares local storage which is allocated from the set of
preserved ACs. An optional size parameter may be given for each variable.
The previous contents of the ACs are saved on the stack and automatically
restored on the next return. Variables declared by ACVAR may be referenced as
ordinary AC operands.
6.2.10. Miscellaneous
6.2.10.1. TMSG string
Type literal string; uses AC1, outputs to primary output. E.g., TMSG <TYPE
THIS TEXT>
MACSYM Page 135
6.2.10.2. JSERR
Handle unexpected JSYS error; type "?JSYS ERROR: message". This is a single
instruction subroutine call which returns +1 always.
6.2.10.3. JSHLT
Handle unexpected fatal JSYS error; same as JSERR except does HALTF instead of
returning.
6.2.10.4. MOD.(DEND,DSOR)
Modulo - In assembly-time expression, gives remainder of DEND divided by DSOR;
e.g., MOD. 10,3 = 1.
Columbia Page 136
7. Columbia Macros and Packages
The items described in this chapter are peculiar to Columbia's DECSYSTEM-20.
Programs that use these facilities are not transportable to other
DECSYSTEM-20's (except in their .EXE form) unless the appropriate library
files are taken, too.
7.1. Utility UUO Package for Macro-20
[ Programs and text by Chris Ryland, 1978. ]
Preliminary Specs
Note: all of these UUOs have a general restriction that must be
observed: no strings addressed as arguments may live in the ACs.
Further, none of the COMND functions may use FLDDBs that address
indirectly through ac's t1-t4, .fp or p.
7.1.1. Formatted Printing Package
%print <format string>, <
addr of arg1
addr of arg2
...>
This expands into a call on the %uprint uuo, with argument
[[point 7,[asciz/string/], addr of arg1, addr of arg2, ...]
If you understand that the arguments are just part of a literal, then you can
understand why they're in this format, and how to extend it; e.g., you might
also say
%print <format>, <exp arg1-addr, arg2-addr, ...>
or call the %uprint uuo directly, if the format string is a variable, e.g.,
%uprint [exp fmstr, arg1-addr, arg2-addr]
The semantics of this beast are: the characters in the format string are
output sequentially, until an escape character `%' is seen; then, a argument
descriptor is eaten from the format string (see below for the definition of
the argument descriptor), and one or more arguments are eaten from the
argument list, and used for output, as directed by the descriptor. the basic
idea here is that each argument descriptor item directs special output
handling for a group of argument items (usually one). to make this discussion
more concrete, here is an example of how this macro might be used:
Columbia Page 137
%print <Here's a number: %d, and the time: %@n%/>, <
[^d234]
[ot%day!ot%fdy]
>
What happens here is that "Here's a number: " is printed on the primary
output, and then the argument descriptor %d is processed, which slurps up the
next argument, [^d234] (remember, all arguments are actually addresses of the
object in question), and prints it as a decimal number. then, ", and the
time: " is printed --nothing special here--, and the argument descriptor %@n
is hit; this descriptor, mnemonic for `the time as of now', has a @ modifier
(described in detail below) which causes the print package to pick up the next
argument from the list and use it as the date/time format value (again, what's
actually there is a literal, since arguments are always addresses of the value
to be used). finally, the arg descriptor `%/' is seen, which means print a
CRLF, and we're all done (because we hit the end of the asciz format string).
Each argument descriptor is of the form `%<@><key>'. The `@' means pick up
additional data to modify the action of the <key>, from the argument list
(this data is eaten just like data that is output; see below). Then, the
action denoted by <key> is taken, which results in one or more data items
being eaten from the argument list and output according the the format <key>.
these constant references to `eating' are to graphically state that when an
argument is used, it disappears from the argument list. thus, you can think
of the argument list as being eaten one argument at a time, from the top to
the bottom (or left to right, depending on how you coded it).
Note that this type of output differs from Fortran-style formatting, in that
it is format-driven, not argument-driven. E.g., in Fortran, each list item
(argument) is taken in turn, and the next format item selected to be used as
the output specification. in this package, just the reverse is done; the
format items cause argument-handling.
If any Jsys errors occur during printing, then if the %print is followed by an
erjmp or ercal, the jump or call is taken, just as in a jsys invocation.
Otherwise, a fatal error occurs.
The equivalent, but skipping, UUO is %prSkp; it returns +2 on success (or +3
if it has an erjmp or ercal after it).
The various argument descriptors, also known as format items, are:
%% print a `%'
%! ignore all following characters until a `!' is seen, at which
point formatting resumes normally. This is designed to allow
formats to nicely cross line boundaries.
%{ print a <
%} print a > (these last two are for non-paired <>)
%/ print a Carriage-Return/Line-feed pair
%= use the argument as a destination designator for the remainder
of the output for this %print call; note that any JFN
top-of-stack is then ignored for the rest of the %print (and
Columbia Page 138
is NOT updated after the %print is done).
%_ print a Horizontal Tab
%^ print a Form-Feed (^L)
%c print the name of the Connected directory, with punctuation
(str:<...>); use any @ modifier value as a directory number,
and print its name instead
%d print a Decimal number; use any @ modifier as the NOUT format.
If no radix is given in the @ modifier case, decimal radix is
used.
%e with no modifier, print the last error message encountered by
this process; with a modifier, use the argument value as an
error number to print symbolically.
%? do error synchronization: clear terminal input and wait for
terminal output to drain, and print a newline, followed by a
"?". Rest of this %print will go to the physical terminal
device.
%f print the Floating (single-precision) value of the argument;
use any @ modifier as the FLOUT format
%h print the ascii cHaracter value of the argument
%i like %d, but print +Inf if negative (for printing positive
numbers)
%j print the name of the file as given by the Jfn argument; use
any @ modifier value as the JFNS format
%n print the date and time of Now; use any @ modifier value as
the ODTIM format
%o print the argument as an (unsigned) Octal number; use any
@ modifier value as the NOUT format. If no radix is given in
the @ modifier case, octal radix is used.
%s print the argument as an asciz String (of byte size as given
by the argument's byte size); -1 in the left half of the
argument means treat it as 7-bit asciz (NB: the argument is a
really the address of a byte pointer, not a byte pointer
itself; see examples below)
%t print the date and Time as given by the argument; use any
@ modifier value as the ODTIM format
%u print the user's login ID, with no punctuation; with a
@ modifier, print the user name of the given user number
%v print the deVice name for the designator given as argument
%x print the argument as a siX-bit value.
Columbia Page 139
7.1.2. %prPush and %prPop
Warning: this facility is not implemented yet!
These two instructions push and pop the %print UUO's output JFN stack,
respectively. The top-of-stack entry (or .priou if the stack is empty) is
used as the destination designator, and is updated after each %print (unless a
%= or %? is used in the format string, see above), so that a byte pointer may
be effectively used as the output destination. %prPush takes an argument
which is an address of the output designator (a JFN or a byte pointer).
%prPop simply pops off the top of stack and discards it. (Note that you can't
have indexed or indirected byte pointers, as this is doable but infinitely
hairy for the UUO package. Also note that since the destination designator
itself is updated after each %print, you can't use a literal (e.g. a byte
pointer) for the argument to %prPush, unless you don't mind modifying pure
data (which you should!).)
Some examples are:
sPtr: point 7, buffer ; Byte pointer to a memory buffer.
:
%prPush sPtr ; Use buffer as general
: ; output area.
%print <foo, bar> ; Output to it.
: ; (sPtr now points at last char).
%prPop ; Get rid of this destination
: ; now that we're done.
Columbia Page 140
7.1.3. COMND-Jsys-Made-Easy Package
This set of macros implements an easy access route to the COMND Jsys;
familiarity with COMND and its functions IS required, though - we're only
trying to ease the pain of using it, not learning about it.
Following are the macros used to invoke the different functions of the COMND
Jsys as well as ancillary tasks such as setting up various control blocks,
getting information out of some of the data structures deliberately hidden to
ease use of COMND, etc. The naming conventions used are designed to follow as
much as possible the names of each of the COMND functions, with slightly
varied punctuation that corresponds to CUsym conventions. E.g., the .cmkey
function of COMND is invoked with the %cmkey macro; induction should get you
the rest.
Some philosophy about error-handling: any COMND function can fail in two ways
(actually, three, but the third is merged into the first to make your job all
that much easier): the function can't be parsed with the given input, or the
user deletes input back into an already-parsed field. We treat these two
`errors' uniformly: each invocation of a function either returns normally if
no error occurs, or takes an erjmp or ercal path (if provided) if an error is
found. Thus, a simple, uniform method of handling parse errors and reparse
conditions is provided: each subroutine of the main parse routine can always
return non-skip on any error (real or reparse), or skip on success. The main
parse routine can worry about whether a real error occurred, and print an
appropriate message, restarting the parse from scratch, or whether just a
reparse is needed, restarting from the first parse step. When an error
occurs, t1 contains the flags from COMND (note in the success case that t1
isn't modified), and t1 is not set. If a real COMND Jsys error (i.e., not a
user parse error occurs, like a COMND internal buffer overflow), the parse
error bit will be set, and the error return will happen as usual; this is done
to make COMND errors be treated uniformly.
Note that each COMND function, if it succeeds, returns a value in t2 (even if
it doesn't return any useful result).
Also, if any COMND function is invoked with more than one FDB (i.e., alternate
FDBs are used), then upon return t3 contains what it normally after the COMND
Jsys (q.v.): the FDB actually used, and the first FDB given.
%cmini (prompt, flags, iojfn, gjfblk)
This macro prepares everything for a command parse. All the arguments are
optional; their use is:
prompt a text string used as the prompt; e.g., <<CRDIR>>. If not
supplied, the prompt `>' is used. Note that if a `>' is
required on the end of this prompt, then you must use the form
<<prompt>>. Blame macro.
flags the flags destined for the (left half of the) CSB .cmflg word,
such as raise all input, wake on every field, etc.
iojfn the <input jfn,,output jfn> pair for the parse.
gjfblk the address of the GTJFN argument block, used in the .cmifi,
.cmofi, .cmfil functions (and it must be supplied if you plan
to use these functions). Its length must be at least .gjln
Columbia Page 141
(defined in CUsym).
This function will only fail if some horrible mistake has been made, usually
by the COMND package, so expect success. Note that this UUO only does a
.CMini COMND Jsys on the second and subsequent invocations, until a %cmres UUO
is done, at which point it will re-initialize everything (see the %cmres UUO
description below for an explanation).
7.1.3.1. %cmRes
This UUO, automatically done by %setUp at normal program startup, resets all
COMND parsing information, so that the next %cmini UUO will cause a full setup
of the Command State Block (set up the prompt, reset all the buffer pointers,
etc.). It should be invoked whenever you intend to start a whole new section
of parsing (e.g., changing the prompt or the set of commands, such as
subcommand mode). In the simplest case, you never have to worry about it, as
it's automatically done at startup. In the most usual case where it would be
needed, a subroutine called to do some subsidiary parsing (e.g., the GetOK
routine in mac:), the safest approach is to do a %cmres before the
subroutine's %cmini, and a %cmres after finishing its parsing job. This
guarantees that the caller won't get hurt.
7.1.3.2. %cmKey (keytab, help, default, flags)
This macro invokes the .cmkey COMND function; upon success, t2 contains the
address of the table entry where the parsed keyword was found. All but the
first arguments are optional.
keytab address of a TBLUK keyword table
help a literal string (usually enclosed in <> if it contains
anything other than alphanumerics and spaces) that will be
used as the help message. if not given, the default help
message is used.
default a literal string that will be used as the default keyword if
none is supplied; if not given, no default is possible.
flags flags, such as suppress default help, etc.
Note that these arguments are just used to build a function descriptor block,
and thus the usual things happen in their absence or presence. Many of the
other macros use the same structure for their arguments, and the same comments
apply as here, so they will usually be elided. If you need to use a
hand-crafted function descriptor block, you can call the COMND package uuo
directly, with the address of the FDB, as in %comnd [flddb. .cmkey,...].
Rather than give each COMND function as above, we will let you induce on the
`base step' above and assume that the remaining functions are invoked
similarly. What follows are those functions that do not map directly to a
COMND function.
Columbia Page 142
7.1.3.3. %cmgab bp
This function asks the COMND interface package to get the current contents of
the atom buffer into the string pointed to by the byte-pointer given as
argument; this cannot fail. Note that the atom buffer can be quite long --how
long depends on the current implementation of the COMND package, but a
reasonable size would be 100 words--, so be wary of extremely long atoms. The
byte pointer is updated.
Note that `bp' is the address of where the byte pointer can be found; i.e.,
the effective address of this UUO is the address of the byte pointer. BEWARE:
if you supply the argument as a literal, the byte pointer gets updated in the
literal pool; if you use the same literal later, it will not be pointing where
you think!
7.1.3.4. %comnd flddb
This is the general COMND function interface, for doing things not directly
supported by this package. `flddb' is the address of a function descriptor
block. It returns the data as the COMND jsys does, except that t1 is not used
to return the parse flags (see %cmgfg below, if you want to do this).
7.1.3.5. %cmgfg flag
This function get the flags from the .cmflg word of the Command State Block
into the word addressed by `flag'; e.g., to get the parse flags into t1, a
%cmgfg t1 will do just fine.
Some notes about using these COMND support macros in a structured fashion:
- The basic idea, as hinted at in the description above, is that each
COMND function either returns successfully if the parse succeeded
(including no reparse needed), or takes an erjmp/ercal path if one
is provided. Thus, each subroutine that is doing some `piece' of
the parsing can, at each step in its job, simply return non-skip on
error, or go on if each parse step succeeds, returning skip when it
finally finishes successfully. Only the top-level parse routine has
to worry about whether a reparse is needed, or an actual parse error
occurred; in the former case, the routine only needs to start the
parse over (without re-initializing); in the latter, an error
message can be issued, and the parse started over from scratch.
- There are several macros to help with this philosophy of parsing:
%pret To be used in a parse subroutine after each COMND
function; it just returns non-skip if a parse error
occurs.
%errep errlab, replab
To be used in a situation (either top-level or a
subroutine) where an error or reparse must be
handled specially. Mostly useful in the top-level
parse routine.
Columbia Page 143
%merrep errlab, replab
Mostly like %errep, but it prints a parse error
message before going to errlab; this is useful in
the top-level parse routine.
Note that an erjmp or ercal after a COMND function invocation is usually
sufficient for handling most errors; e.g., after a %cmfil invocation in a
parse subroutine, if any errors occur later in the same routine, an erjmp to a
cleanup segment (that releases the jfn gotten by the %cmfil) is quite
sufficient for handling both noparse and reparse errors.
Columbia Page 144
7.2. CUrel Utility Subroutines
CUrel.rel is an indexed library that can be searched for the handlers for the
Columbia UUOs for COMND Jsys calls and formatted printing (described in
CUUOs.doc) and for the routines described below.
7.2.1. Helper
Types the desired help file at the job's controlling terminal. Actually, it
will type any 7-bit ASCII file, but the error messages all refer to help
files.
Input:
t2/ 7-bit byte pointer to ASCIZ filespec.
Effects:
If the specified file is found and accessible then it is typed,
otherwise an appropriate error message is typed.
Returns +1 always.
Calling sequence:
search CUsym
extern helper
:
%setup
:
move t2, [point 7, [asciz\HLP:FILE.HLP\]]
call helper
:
- F. da Cruz, CUCCA, 1978
7.2.2. GetOK
Get affirmative or negative response to a question, using the COMND Jsys (help
is given on '?', recognition on ESC).
A default answer can be specified, which will be supplied automatically if the
user types carriage return alone in response to the question.
Columbia Page 145
Input:
t1/ 7-bit byte pointer to ASCIZ string posing the question.
t2/ zero -- no default answer.
positive (nonzero) -- default answer is "yes".
negative -- default is "no".
Returns:
+1 if response was negative.
+2 if response was affirmative.
Caution:
Don't call this routine while processing
another COMND Jsys (i.e. after .CMINI but before .CMCFM).
Example:
move t1, [point 7, [asciz\Really delete all your files? \]]
move t2, [-1] ; default is 'no'.
call getok
jrst dont ; answer was no, don't do it.
; code here will be executed if answer was 'yes'.
- F. da Cruz, C. Ryland, CUCCA, 1978
7.2.3. Gfcpg
This routine will allocate a page to the user. This is useful, for instance,
when PMAPping is to be done to a single page in memory.
Returns:
+1: error, no free core pages;
+2: success, page number in t1.
Example:
call %gfcpg
%ermsg <couldn't get a page>,nopage ; do this on +1 return
; come here when a page has been successfully allocated
- George Lotridge (DEC), CUCCA, 1977
7.2.4. pagMgr
A page management facility. Gives greater functionality that gfcpg at a
slightly greater cost in overhead. Allows allocation and deallocation of
consecutive blocks of pages. Keeps an internal 'own' page table for page
management.
Columbia Page 146
Call with:
Function codes in t1:
0: Get pages, searching from 770 -> 0.
1: Get pages, searching from 0 -> 770.
2: Free pages.
3: Initialize the pages-in-use vector.
(this is done automatically the first time this routine
is called, before the selected function is executed).
Arguments in t2:
For get-page functions:
Left half contains number of consecutive pages to get,
Right half contains starting page number to search from.
For free-page function:
Left half contains number of consecutive pages to free,
Right half contains starting page number to free from.
(in these functions, if the number of pages given is 0,
it will be treated as 1.)
For reinitialize function:
t2 is not examined.
Returns
+1: Not enough pages available; t2 contains maximum
number available of type requested.
If there was an error on initialization (e.g. invalid argument),
a message is typed at the terminal, and t1 is set to -1.
+2: t1/ Address of block of pages in right half, and page
number in the left.
t2/ page count.
Joel Rosenblatt, CUCCA, 1978.
7.2.5. Subbp
Subroutine to subtract two byte pointers, i.e. to tell the number of bytes
between the bytes pointed by the first one and the second one. The two byte
pointers must point to bytes of the same size. Indirection (@) and indexing
is handled properly.
Columbia Page 147
Call with:
t1/ First byte pointer.
t2/ Second byte pointer.
Returns:
+1 if the byte sizes are different, with t1-t3 unchanged, or else
+2 with:
t1/ Unchanged.
t2/ Unchanged.
t3/ The number of bytes of the specified bytesize in
thee string pointed to by the first byte pointer (in t1)
up to, but not including, the byte pointed to by the
second byte pointer (in t2).
Example:
; assume a SIN has just been done to get a string into location
; 'buffer'. SIN returns the updated byte pointer in t2. This
; call to Subbp will tell how many characters were in the string.
move t1, [point 7, buffer] ; Point to beginning of buffer.
call subbp ; (t2 already has the pointer to the end).
%ermsg <bytesize error>,error ; Do this on error.
movem t3, count ; Save the byte count.
- F. da Cruz, CUCCA, November 1977
7.2.6. Rescan
Allow arguments to be passed to programs via the Exec command line.
Look in the rescan buffer for the name of the calling program followed by any
arguments. If the first field found in the rescan buffer is not the same as
the program name, or if the program name matches but there are no arguments
after it then this routine returns +2 with no other effect. Otherwise it
returns +1 to indicate that special handling (usually the setting of a flag)
can be done.
Enter with:
t1/ Byte pointer to asciz program name.
Returns:
+1: If arguments found in rescan buffer,
with updated pointer in t1.
+2: otherwise.
Example:
extern Rescan
%trnOff rscFlg ; Assume no rescan args.
move t1, [point 7, [asciz/foo/]] ; Name of this program.
call rescan ; Rescan args on command line?
%trnOn rscFlg ; Yes, turn on the flag.
Columbia Page 148
If arguments were detected then subsequent requests for tty input will be
satisfied by the data in the rescan buffer until the rescan buffer is
exhausted or the program issues a .CMINI (or otherwise clears the input
buffer), at which time tty input will automatically revert to the physical
tty. The caller should skip over the first .CMINI after return from this
routine, which has already issued a .CMINI.
The contents of the rescan buffer are discarded if the first field found on
rescan does not match the program name passed in t1.
- Jeff Langer, CUCCA, April 1979
Columbia Page 149
7.3. CUsym MACSYM Augmentation Macros
The CUsym macros and documentation were written by George
L. Lotridge of Digital Equipment Corporation (while he was assigned to
Columbia University as a resident software specialist) and Chris
Ryland of Columbia.
CUsym contains a whole set of symbol and macro definitions to augment MONSYM
and MACSYM. Included are the standard register definitions, macros for
interfacing to the UUO package (which supports standard I/O, simple uses of
the COMND Jsys, etc.), and generally any macro which has been found to be
useful and which is missing from MONSYM and MACSYM (a working knowledge of
which is assumed).
NOTE: you should have a good feel for the contents of MACSYM (6)
document and the Macro coding standards document (8) before using this
package.
A word about naming conventions: all names in this module are of the form
%symbol; this will hopefully sidestep any name conflicts with a SEARCHing
program. DEC has reserved names with % and . in them, but their use of % is
restricted to other than the first char- acter, so we're safe. (Actually, a
few of our Useful Symbols, below, use a "." as their first character, which is
also DEC-reserved, but they're simple and few enough to cause no problems.)
Also, a few of the 'hidden' symbols used herein (e.g., the stack, or global
symbols in the support package) begin with "%%".
7.3.1. Accumulator Support
Accumulator (register) definitions (conform to the DEC coding standard) These
must be used exclusively, unless specifically redefined at the start of a
module with the %DefAC macro (see below).
p=:17 ; Stack pointer
cx=:16 ; Call/Return temporary
.sac=:16 ; CU/MacSym utility reg
f=:0 ; Flag register (preserved)
t1=:1 ; General temp and Jsys registers:
t2=:2 ; never preserved
t3=:3 ; ...
t4=:4 ;
q1=:5 ; First set of preserved regs
q2=:6 ; (must be preserved by callee
q3=:7 ; across a call)
p1=:10 ; Second set of preserved regs
p2=:11 ; (ditto)
p3=:12 ;
p4=:13 ;
p5=:14 ;
p6=:15 ; NB: not useable with TrVar MacSym facility
.fp=:15 ; Frame pointer for TrVar facility
Columbia Page 150
7.3.2. %DefAC
Define an alternate name for one of the registers; this macro should egisters
are re-defined, and the new definition should be made in terms of one of the
definitions above. This macro purges the old name, thus preventing multiple
names for one register.
define %defac(new, old)
7.3.3. Useful Symbols
.prjfn=<.priin,, .priou> ; Symbol for usual primary JFN pair
.null==0 ; General nothing value
.nil==0 ; General nothing pointer
.True==1 ; General boolean truth value
.False==0 ; and its complement
; Lengths of various Jsys control blocks; ommitted from MONSYM, sadly.
.acln ; Length of ACCES arg block
.ckln ; Length of CHKAC arg block
.cmln ; Length of Command State Block
.cmfln ; Length of Function Descriptor Block
.cdln ; Length of CRDIR arg block
.cjln ; Length of CRJOB arg block
.jiln ; Length of GETJI arg block
.gjln ; Length of (long form) GTJFN arg block
.ipln ; Length of ipcf packet descriptor block
.rsln ; Length of SFTAD arg block
.rdln ; Length of TEXTI arg block
7.3.4. UUO Package OPDEFs and Interface Symbols
%uprin ; Print UUO
%comnd ; COMND interface UUO
%ucmin ; COMND initializer UUO
%cmgfg ; Get COMND flags UUO
%cmgab ; Get COMND atom buffer UUO
%nuuo ; Add-new-UUO UUO
%cmres ; COMND reset UUO
%prPush ; JFN-stack push (%print package) UUO
%prPop ; JFN-stack pop (ditto) UUO
; length of COMND interface UUO atom buffer:
%atmbl==^d250/5+1 ; in words
extern %csb ; command state block, for you hackers
Columbia Page 151
7.3.5. Setup Environment Macros
7.3.5.1. %setEnv
%SetEnv is a macro that must be used as the first thing after your Title and
Search CUsym statements; it sets up the CUsym, MonSym, and MacSym environments
properly. Its use is envisioned as:
title Baz - tweak the frob's runtime
search CUsym ; (No MAC: needed!)
%setenv ; Set up our environment
...
7.3.5.2. %setUp
%SetUp is a macro that you should use as the first executable action in your
program; it Resets the execution environment, sets up a stack, clears the flag
register F, sets up for UUO calls, sets up for COMND parsing (resetting) (and
starts off your code in %Pure mode).
7.3.6. Storage Declaration Macros
%Pure, %Impure, %Routine
Use these macros to declare what sort of storage follows them: either %pure
code (or read-only data) or %impure data (read-write). Thus, before beginning
a new logical section of code or data, always use one of them to declare what
follows (if you don't use them, you may be surprised!). It goes without
saying that %Pure should precede all code (which is NEVER impure). Using this
pair of macros is a good way of keeping impure data, which belongs to a
routine, physically (on the written page, that is) together with the routine.
The alias %routine for %pure exists for purely mnemonic purposes; its use is
suggested, as in:
%routine
openit: stkvar <fee,<foo,,5>>
7.3.7. General-Purpose Macros
7.3.7.1. %Stack
This macro creates the stack area, and loads P with the stack pointer. Its
argument, the stack height, is optional, and defaults reasonably.
Columbia Page 152
7.3.7.2. %Version
This macro builds a standard DEC version word from its arguments. In order,
its arguments are the major version, the edit number, the minor version, and
the customer version. Omitted fields default to zero.
7.3.7.3. %Clear
This macro takes three args, two of which are optional. The first,
non-optional, argument is the starting address of the area to be cleared. The
next is the number of locations to clear, which defaults to one. The last
argument is the desired filler, which defaults to zero.
7.3.8. Macros Used for Common Primary I/O
Note that since these macros use %print, that any string argument shouldn't
include `%'s, or things may get very confusing. Also note that %typnum's
first argument, the address of the number, must conform to the %print argument
standard (q.v.).
7.3.8.1. %typeCR(string)
Types the given literal string at your terminal, followed by a carriage return
(CR).
Example:
%typeCR <And your little dog, too!>
7.3.8.2. %crType(string)
Like %typeCR, but types the CR before, instead of after, the string.
To type a literal string with no CR, either before or after, use
the MACSYM macro TMSG.
7.3.8.3. %typNum(num,cols,rdx)
Types the number in location 'num' at your terminal. The two trailing
arguments are optional.
cols Field width in which to print the number. Default is 0, i.e.
use only as many character positions as are necessary to type
the number.
rdx Radix in which to type the number. Default is 10 (decimal).
Columbia Page 153
7.3.8.4. %crlf
Types a carriage-return/linefeed sequence at your terminal.
7.3.8.5. %tab
Types a horizontal tab at your terminal.
7.3.9. JSYS Support Macros
7.3.9.1. %jsErr
Macro to be used after a Jsys that either returns +1 on error or always
returns +1 (i.e., all but two of the Jsysi); %JSerr types the user's error
message (if given) or the Jsys error that caused it to be invoked (if no
message is given); it then either halts (if no address is supplied) or goes to
the address (if given).
Note: this is similar to the MacSym macro JSERR, but it only works
after a Jsys, since it is invoked by an erjmp; %JSerr has the
advantage, though, that it ALWAYS works after a Jsys, which JSERR
doesn't.
Note also that both %Jserr and %ErMsg, if they halt and are continued, will
simply return to the point after the invocation of the %Jserr or %ErMsg.
Both of these macros, since they use %print, can produce customized error
messages (eg, %jsErr <CUsym: Bad command %s [%e]>,,<ptrToS> will print an
error-synchronized message, with a string argument and the monitor error
message in brackets, and then halt).
7.3.9.2. %erMsg
This macro, which, in contrast to %JSerr, is designed to be used in a non-Jsys
skip context, will print a message (if given) or the last fork error (if not
given); finally, it either jumps to an address (if given), or halts (if not
given). See %Jserr comments for more info.
7.3.10. Local Label Support Macros
The intent of this set of macros is to provide a facility usually available in
good assemblers (hint, hint): local labels. The idea, due to Knuth, is that
instead of agonizing over choosing a label for each little local motion within
some code, you simply plant one of nine local labels, of the form %N, and
refer to the next local label %N by %NF, and the previous local label %N by
%NB - a simple example of all this is:
Columbia Page 154
some: stkvar <from,to>
txne t1,gj%old ; Does he want an old file?
jrst %1f ; Yes, go handle it
txz t1,gj%fou ; No, reset this
setom from ; and set 'from' flag
%1 call foo ; Continue with processing
jrst %1b ; Failed: try it again
... ; etc etc
These macros (internally) use symbols of the form %n% and %n%m, where n ranges
from 1 to 9, and m from 0 to 777, so be wary.
7.3.10.1. %Cat(a,b)
Useful macro that just returns its two arguments (as text strings),
concatenated.
7.3.11. COMND JSYS Support Macros
7.3.11.1. %Ptr(string)
Build a standard 7-bit ASCIZ pointer to a literal string.
7.3.11.2. %table and %tbEnd
%table is used to start a keyword table definition; %tbEnd ends a keyword
table definition. Suggested use is as in the following example, which also
illustrates %key.
cmtb: %table ; Keywords for frotz program
%key Mumble,domum,cm%inv ; mumble command (invisible)
%key Noodle,donood ; noodle command
%key Zork,dungeo ; invoke dungeon command
%tbend ; End of this keyword table
7.3.11.3. %key(name, data, flags)
This macro takes three arguments: an (alphanumerics only!) name, the data to
be associated with the name, and an (optional) flag value. It creates either
a flag-less keyword (the normal case), or, if flags are given, a keyword with
flags in the first word (and cm%fw set). Thus, the result is a TBLUK table
entry, suitable for use by the .CMkey COMND Jsys function. Note that all %Key
words in a table must be bracketted by %table and %TbEnd macros (see above).
Columbia Page 155
7.3.11.4. %Flddb (typ, flgs, data, hlpm, defm, lst)
This macro is useful for building function descriptor blocks that don't
contain just literal strings for the help and default components; otherwise,
it's the same as the MONSYM flddb. macro.
7.3.11.5. %Handlr(p,e), %PrsAdr, %EvlAdr
Macros to support structured parse/evaluation; %Handlr builds a structure
comprised of the parse routine address (p) and evaluation routine address (e),
for a given keyword (it should be in a literal in the %Key macro); %prsAdr and
%evlAdr are the DEFSTR structures for accessing these two elements of a
structure, respectively.
An example of all this:
:
%cmkey comtab, <command,> ; Get a top-level keyword
%merrep restart, repars; Usual error handling
hrrz t2, (t2) ; Pick up data value from keyword
load t2, %evladr, (t2) ; Get evaluation routine
movem t2, evaler ; Save its address
load t2, %prsadr, (t2) ; Now, get parse routine
call (t2) ; And call it
%jmerrep restart, repars, restart ; Handle errors
: ; Continue
; Pure data for main parse
%table ; Main command table
%key bletch, [%handlr(bletcm, doblet)] ; Bletch mode
%key mumble, [%handlr(mumbcm, domumbl)] ; Mumble mode
%tbend
:
7.3.11.6. %CMxxx Macros to Invoke .CMxxx COMND Functions
See the CUUOS document (7.1) for information about using these. They are
listed here for convenience:
- %cmIni (prompt, flags, ioJfn, gjfBlk): Initialize parse.
- %cmKey (keyTab, help, defalt, flags): Parse a keyword.
- %cmNum (radx, help, defalt, flags): Parse a number.
- %cmNoi (guide-word): Parse guide words.
- %cmSwi (swTab, help, defalt, flags): Parse a switch.
- %cmIfi (help, defalt, flags): Parse an input filespec.
- %cmOfi (help, defalt, flags): Parse an output filespec.
Columbia Page 156
- %cmFil (help, defalt, flags): Parse a general filespec.
- cmFld (help, defalt, flags): Parse a "field".
- %cmCfm (help, flags): Get confirmation (CR).
- %cmDir (data, help, defalt, flags): Parse a directory name.
- %cmUsr (help, defalt, flags): Parse a user name.
- %cmCma (help, flags): Parse a comma.
- %cmFlt (help, defalt, flags): Parse a floating-point number.
- %cmDev (help, defalt, flags): Parse a device name.
- %cmTxt (help, defalt, flags): Parse a text string.
- %cmTad (tadBlk, help, defalt, flags): Parse time and date. Note
that the Time-and-Date flags belong to the first argument, since
they're part of the data to the function.
- %cmQst (help, defalt, flags): Parse a quoted string.
- %cmUqs (brkTab, help, defalt, flags): Parse an unquoted string.
- %cmTok (token, help, defalt, flags): Parse a token. The token as
given should be a string in double quotes, as in %cmtok "*"; if you
need some other form, use the %comnd UUO bare.
- %cmNux (radix, help, defalt, flags): Parse a number.
- %cmAct (help, defalt, flags): Parse an account string.
- %cmNod (help, defalt, flags): Parse a network node name.
7.3.12. Macros to Handle COMND Errors
7.3.12.1. %pret
For use in secondary parsing subroutines. Handle a parse error or reparse by
just returning non-skip.
7.3.12.2. %errep errlab, replab
For use in top-level command parser. Handle an error by going to errlab, and
a reparse by going to replab.
Columbia Page 157
7.3.12.3. %merrep errlab, replab
For use in top-level command parser. Handle an error by giving an error
message and going to errlab, and a reparse by going to replab.
7.3.12.4. Macros for Fail-Return from Parsing Routines
These macros help with error- and reparse-handling after a parse subroutine
call (which is expected to return skip on success, and non-skip on failure);
three sorts of errors can be expected from such subroutines: parse error,
reparse needed, other type of failure (usually a semantic problem). Thus,
these macros have three dispatch addresses, corresponding to these three
errors. Note that the method used here assumes that if neither the parse
error or reparse flags are set in the command state block, then the error is
of type `other'.
7.3.12.5. %jerrep errlab, replab, othrlb
Handle a skip-return error condition as described above.
7.3.12.6. %jmerrep errlab, replab, othrlb
Handle a skip-return error condition as described above, printing an error
message on a parse error.
Note! t1 is clobbered by %errep, %merrep, %jerrep, %jmerrep.
7.3.13. Flag-Handling Macros
All of the following flag-handling macros use register F, the preserved flag
register. F is assumed to be the flag register for any program that uses
these macros. Note that %SetUp clears F, thus initializing flag management.
7.3.13.1. %Flags(aFlg,bFlg,cFlg,...)
This macro takes a list of flag names, and assigns a flag value to each name
(within a 36-bit word). It can be used more than once, but no more than 36
flags can be defined.
7.3.13.2. %trnOn & %trnOff
These macros take a flag quantity (one or more flags ORed together), and turn
them on or off, respectively (with no skipping).
Columbia Page 158
7.3.13.3. %TrOnS & %TrOfS
Like %TrnOn and %TrnOff, but skip always afterwards.
7.3.13.4. %SkpOn & %SkpOff
These macros take a flag quantity, and will skip if ALL the flags are on or
off, respectively.
7.3.13.5. %AnyOn & %AnyOff
These macros take a flag quantity, and will skip if ANY of the flags are on or
off, respectively.
7.3.14. CUuos (CUCCA Utility UUOs) Interface
7.3.14.1. %print, %prSkp
Formatted-print macros: output the arguments according to the format string.
%PrSkp returns skipping (+2 instead of +1, but handling a following
erjmp/ercal properly). See 7.1 for details.
A note about arguments: the argument list is really nothing more than a
sequence of addresses, so if you choose to use addressing forms such as
address(index), be sure and use the <z address(index)> form so that macro will
be happy with the address. The same applies to address forms such as
<z @(t1)>, etc.
Standards Page 159
8. Macro-20 Programming Standards and Conventions
8.1. Introduction
This document was adapted in April 1979 at the Columbia University Computer
Center from the document
TOPS20 Coding Standards and Conventions, 17 January 1974, revised
8 September 1976
written by the DEC Tops-20 monitor group for its own use. This version
departs from the original in certain ways, by additions and deletions, and by
modifications of certain details, but the net effect is about the same. These
standards and specifications apply in specific detail to Macro-20 programs,
and in spirit to other DEC-20/DEC-10 assemblers (Macro-10, Midas, Fail). They
do not apply in their entirety to assembly language routines written to be
called from other languages, which usually have different subroutine calling
conventions, and may have registers dedicated to different uses, precluding
the use of certain MACSYM facilities. Familiarity with Macro-20 and DEC-20
monitor calls is assumed.
A standard of programming style and conventions is especially important for
the assembly language programmer because assembly language lacks high-level
language facilities such as control and data structures, scoping of variables,
etc., without which the programmer must exercise tremendous discipline to
write a clear, easily modifiable program. It is hoped that this standard will
make assembly language programming easier by relieving the programmer of the
burden of deciding at every turn how to format a statement, how to use
registers, how to pass parameters to a subroutine, and so forth. Like any
standard, this one contains many elements that are arbitrary and capricious,
and few people will agree with every detail. The bulk of the standard comes
to us as a fait accompli, having been in use at DEC for several years and
forming the basis for a very large amount of code. Other facets have been
added after long experience both in writing programs and in reading and
modifying code from various installations. It is felt the rules of style and
usage given here can result in programs that are as clear as Macro-20 programs
can be.
8.2. Statements
The general form of a statment should be:
label: opcode ac, @addr(x) ; Comment.
where:
1. Tabstops are assumed to be set every 8 spaces.
2. The label begins at the left margin.
3. The opcode begins at the first tab stop. There should be one tab
before the opcode. If the label and colon(s) occupy 8 or more
spaces, the opcode should start at the first tab stop on the next
Standards Page 160
line. Exceptions to this rule apply in multi-line literals and
following skipping instructions, JSYS's, and subroutine calls (see
below).
4. One space (a blank, not a tab) should follow the opcode unless
there are no other fields except the comment to be specified in the
statement, in which case sufficient tabs should follow to put the
comment field at the 4th tab stop. Space is preferred to tab for a
number of reasons: spaces take up less space and cause fewer
overflows into the comment field; an instruction is typed the same
way in the program text as it is in DDT (DDT will not accept a tab
in an instruction); tabbing does not achieve vertical alignment of
equivalent fields since various quantities can follow the opcode
(register, address, and others); tabs would line up the operands
with the opcodes of multiline literals; using tab prevents the
operands of an indented opcode from reflecting the indentation and
sometimes forces the operand forward an additional tab stop. This
standard attempts to help the whole instruction to be perceived
visually as a single unit; the use of tab tends to visually
separate opcode and operands for no useful reason. Vertical
alignment of operand fields such as produced by tab in this context
appears to be mainly a carryover from punched-card oriented
processors where parsing was done by field rather than on a
character stream.
5. When any field is not used by the instruction, it may be omitted
along with its directly related punctuation. A field which is
affected by an instruction should NOT be defaulted to 0 by omitting
it.
6. The semicolon which begins the comment should be at the 4th tab
stop. There should be one or more tabs preceding the semicolon as
necessary to place the semicolon at the 4th tab stop unless the
preceding fields extend to or beyond the 4th tab stop. In this
case, one space (blank) should be used to separate the last
preceding field and the semicolon. The semicolon should be
followed by a space.
The instruction which follows a skipping monitor or subroutine call should be
indented 1 additional space (1 space beyond the first tab stop) to indicate
the possibility of that instruction being skipped. Indenting in this manner
should also be done following skipping machine instructions; when several
skipping instructions appear consecutively, each instruction that could be
skipped should be indented 1 space.
8.3. Comments
A comment on the same line as a statement should begin at the 4th tab stop as
described above. When a comment consists of a single sentence or phrase which
requires more than one line, the subsequent lines should have two spaces
between the semicolon (at the 4th tab stop) and the comment to indicate to the
reader that the several lines are part of one logical statement.
A comment on a line by itself should begin at the left margin.
A group of comment lines (1 or more lines) should be preceded and followed by
Standards Page 161
a blank line.
A long comment (10 or more lines) may be enclosed within a REPEAT 0 or COMMENT
pseudo-op and the semicolons omitted.
Extensive commenting of source listings is strongly encouraged:
1. Routines, modules, sections, macro definitions, etc., should be
described at their beginning. See also requirements for subroutine
comments below.
2. Comments should appear on almost every statement line. As the
reader views the listing page, the comments (aligned at the 4th tab
stop) should appear as a running commentary on what the code is
doing. These on-line comments should explain the logical procedure
being carried out, not just describe the obvious action of the
instruction. Humorous or irrelevant comments (e.g. "; Oops...",
"; Oh well...") are discouraged since they provide no information
to the reader.
Comments should be written in plain English, without jargon, following normal
rules of capitalization, punctuation, and grammar. A reader should be able to
read the comments without seeing the code and obtain a coherent understanding
of what the program is doing. When a variable or other mnemonic symbol is
referred to in the comments, an english phrase rather than the mnemonic itself
should frequently be used (e.g. "last page address" rather than "LPGADR").
Comments, particularly routine headers, should describe why non-obvious
actions are being taken and/or what assumptions are being made (e.g. "Get
here only when ...").
Comments should exist on three levels. The highest level is a sentence or
paragraph that describes the operation of an entire program or routine, and
appears at the head of the program or routine (at the top of a page), usually
enclosed by the COMMENT pseudo-op so that each line need not begin with a
semicolon. The first top-level comment in a file should include the author's
name, organization (and department), the date, and possibly a copyright
notice. The lowest level is the per-statement comment at the 4th tab stop.
The intermediate level is a one- or two-line comment, beginning on the left
margin, which describes the purpose or operation of a group of statements.
There should never be more than 8 or 10 lines of code without such an
intermediate comment.
Think of any program you write as if it were a letter to a stranger who will
have to fix all the bugs you left in it, add new functionality, or translate
it to another language. It should be possible to read through a program on
four levels:
1. At the top level only. Reading only the highest-level comments
should give the reader a broad idea of the purpose and structure of
the program.
2. At the intermediate level. Reading the top- and intermediate-level
comments should show you not only what the program does, but what
algorithm was used.
3. At the lowest comment level. Including these comments in a reading
of the program adds detailed information about the actual
implementation of the algorithm.
Standards Page 162
4. At the code level. Including the code itself brings you down to
the bit-twiddling level. It should never be necessary to read code
unless you want to learn how things are done, or you are modifying
the program.
Example showing intermediate- and low-level comments:
; Get a JFN for the input file.
movx t1, GJ%SHT!GJ%OLD ; Using short form GTJFN, for an old file
hrroi t2, [asciz /foo.txt/] ; called foo.txt,
GTJFN ; get a Job File Number.
erjmp filErr ; On error go to the file-error handler.
hrrzm t1, inJfn ; No error, save the JFN (without flags).
; Now open the file.
movx t2, fld(7,OF%BSZ)!OF%RD ; In 7-bit byte read mode,
OPENF ; open the file.
erjmp filErr ; On error go to the file-error handler.
; File is open. Now begin processing.
:
:
The style of capitalization of the opcodes, JSYS bits, and variables is a
matter of taste, but consistent use of a mixture of upper and lower case to
enhance the readability of the program is strongly encouraged. In this
example, MONSYM symbols (JSYS names and bits) are capitalized, instructions
and register names are in lower case, and variable names formed from multiple
words have capital letters at word breaks (e.g. filErr = file error).
8.4. Pagination of Source Programs
Source listings should be divided into pages by formfeed (control-L)
characters. A CRLF should precede and follow each formfeed. Source files
should be arranged so that major modules, subroutines, etc., begin at the top
of a page. Only when a subroutine is a quarter page or less in total size
should it begin other than at the top of a page.
Judicious use should be made of blank lines (they should be inserted to
emphasize logical boundaries, but without large gaps). Garish graphic devices
like lines across the page, boxes around headings, etc., should be avoided
since they waste the programmer's time (both in typing them in and in waiting
for them to be typed out) without adding any useful information to the
program; the principle formatting devices for separating things and getting
attention should be blank lines and formfeed characters.
It should rarely be necessary for flow of control to cross a listing page.
That is, the last instruction on each page would normally be an unconditional
transfer of control not preceded by a skipping instruction. An unbroken
sequence of instructions longer than one listing page is strong evidence of
insufficient subroutinization. However, when a sequence of instructions does
Standards Page 163
cross a page, the last line on the preceding page and the first line on the
following page should be a comment line of the form
; ..
where the semicolon appears at the first tab stop directly under the preceding
opcode. E.g.,
move t1, foo ; Comment
; ..
^L
; Comment about continuation.
; ..
label: movem t1, baz ; Comment
The page break should occur at a natural juncture in the program logic.
8.5. Other Assembler Functions
For top-level macro definitions, the DEFINE should appear at the left margin
and be followed by one space. The name of the macro being defined should
appear next, followed by one space. The dummy argument list, if any, should
appear next, followed by the open angle-bracket. E.g.,
define macnam (a,b,c)<
or
define macnam <
A comment or CRLF should follow the open angle-bracket, and the body of the
macro definition should begin on the next line, except when the entire macro
definition is on one line in order to be used as part of an expression. The
terminating right angle bracket should be on a line by itelf, on the left
margin.
Example:
define getSum (a,b,c)< ;; Macro to get a sum into an AC.
move a, b ;; Load contents of b into AC a,
add a, c ;; and add contents of c.
>
Macro calls generally do not require parentheses surrounding the arguments.
The exception is a macro call appearing within an expression, e.g.
aa+foo(xx,yy)+bb
Standards Page 164
In some cases, however, the parentheses improve clarity, e.g. "foo (,x)" shows
more clearly that the first argument to foo is omitted than does "foo ,x".
Angle-brackets should be used to quote any argument containing
non-alphanumeric characters; this is especially true of character strings with
imbedded blanks.
Examples (where %jsErr is a macro name):
GTJFN
%jsErr <Can't get a JFN>, r
OPENF
%jsErr (,r)
Top level assembler conditionals should be indented 3 spaces from the left
margin (so that tag and comment lines may always be leftmost). Lower level
conditionals should be indented 3 or more spaces. The terminating
angle-bracket of a conditional should appear:
1. immediately following the last instruction if the conditional is
only one line long;
2. on a separate line indented the same amount as the pseudo-op which
began the conditional.
Example:
tag:
ife ftFoo,<move t1, mumble> ; If feature Foo is selected just do this.
ifn ftFoo,< ; If feature Foo is not selected...
move t1, mumble ; then do this,
ifn ftBaz,< ; and if feature Baz is selected...
add t1, baz ; do this
move t2, frotz ; and this too.
> ; End of ifn ftBaz.
jrst frotzH ; Go to the frotz handler.
> ; End of ifn ftFoo.
A closing angle bracket should NEVER appear in a comment (i.e. following a
semicolon on the same line). The coding should be correct even if the
assembler were made to ignore angle-brackets in comments.
Assembly listing options are provided for those who want listings, but
experience has shown that assembly listings are rarely useful; it is usually
sufficient to work from a source listing. However, all assemblies should
begin with SALL which has been shown to produce the most readable assembly
listings. In addition, all source files should have a TITLE, and SUBTTL's for
each logical section of the program (e.g. symbol definitions, initialization,
main program, support routines, data area).
In general, macros worth defining at all are worth defining on a system-wide
basis. Therefore, localized, special-purpose macros are discouraged.
Standards Page 165
8.6. Instruction Mnemonics
The standard KL-10 instruction mnemonics as defined by the DECsystem-10/20
Hardware Reference Manual should be used throughout. No abbreviated opcodes
should be used.
Macro or opdef definitions should be made to define a useful mnemonic which is
related to a function being performed in the code. See the subroutine
conventions below for examples.
8.7. Variables and Structures
Use of the stack variable and data structure facilities in MACSYM is
recommended. See MACSYM documentation. Because of these facilities, the
following should be observed:
1. Explicit pushing and popping of quantities is rarely done.
2. Explicit referencing of the stack, e.g. as -n(p) is never done.
3. Fields within data blocks or tables are not referenced by halfword
instructions or explicit byte pointers but rather by the MACSYM
facilities LOAD, STOR, etc.
4. Flags can be defined with DEFSTR, MSKSTR, or as full-word
parameters, and can be referenced with the TXmn MACSYM macro. Flags
should never be defined as half-word quantities which require the
programmer to remember whether to use TL or TR. Other macros may
be defined to operate on single-bit flags, which should be held in
register 0; in this case too, no instruction should depend on the
actual value or location of a flag.
8.8. Subroutines
All AC's should be preserved over a subroutine call unless an explicit
statement to the contrary appears in the subroutine description. ACs are
changed over a subroutine call only when values are to be returned to the
caller.
The allocation of ACs for all inter- and intra-module subroutine calls should
be:
ACs 1,2,3,4 Passing arguments and returning results.
ACs 0, 5-15 Preserved, not changed by subroutine (or saved and restored if
necessary).
AC 16 Temporary, used by MACSYM call/return procedure and reserved
for use by other call/return procedures.
AC 17 Global stack pointer
Call and return should be effected by 'pushj p,' and 'popj p,' respectively.
A set of assembler mnemonics has been defined for subroutine mechanics as
Standards Page 166
follows:
call (= pushj p,) should be used to call subroutines, e.g.
'call subr'.
ret (= popj p,) should be used to return +1 from subroutines.
retskp should be used to return +2 from subroutines. Retskp is
equivalent to:
jrst [ aos (p)
popj p,]
callret may be used to call a subroutine and return immediately
thereafter. It is equivalent to
call subr
ret
or
call subr
ret
retskp
Note that 'callret' is not guaranteed to be a single instruction; therefore it
may not be skipped over. The other returns above are guaranteed to be single
instructions.
These mnemonics are used to emphasize the FUNCTION being performed (calling,
returning) rather than the mechanics of the function (pushing, jumping, etc.).
Also, these mnemonics could continue to be used even if a more general calling
standard were adopted at some time in the future.
Return may also be effected by transferring control to one of the global
labels R or RSKP, e.g.
jumpe t1, r ; Equivalent to "jumpe t1, [ret]".
jumpn t1, rskp ; Equivalent to "jumpn t1, [retskp]".
The general temporaries should be used for passing arguments to subroutines
and returning values. AC1 (t1) should be used for a single argument routine,
ACs 1 and 2 for a two-argument routine, etc. When subroutines modify of
depend on global data, including flags, such effects should be clearly and
completely documented.
A routine defined to return caller +2 (skip) on success and caller +1 (noskip)
on failure is acceptable. Returns greater than caller +2 are considered very
bad form.
Standards Page 167
8.9. AC Definitions
The following mnemonics have been chosen to be consistent with the AC-use
conventions above. The preserved ACs are divided into three groups, f
intended for Flags, and q1-q3 and p1-p6 intended for general use. The ACs
within each group are consecutive.
0 - f 10 - p1
1 - t1 11 - p2
2 - t2 12 - p3
3 - t3 13 - p4
4 - t4 14 - p5
5 - q1 15 - p6
6 - q2 16 - cx
7 - q3 17 - p
The programmer should assume that each group (Tn, Qn, Pn,) is in ascending
order, e.g. that t2 = t1+1, but that the specific assignment of numbers may
change. Explicit numeric offsets from AC symbols (e.g. T1+1) should NEVER be
used. Instructions which use more than one AC (e.g. div, jffo) must be given
an AC operand such that the other AC(s) implicitly affected are in the same
group. E.g. t3 (and t4) is OK for idiv because t3+1=t4, but q3 is not because
q3+1=??. AC0 is almost universally used as a flag register, and should not be
used for any other purpose.
There is a facility in MACSYM to save and automatically restore ACs. The
indicated ACs are saved on the stack at the point of execution and a dummy
return is placed on the stack which causes these ACs to be restored
automatically when the current routine returns. Use of this facility
eliminates the need for matching push/pop pairs at the entry and exits of
routines and eliminates the bugs which often arise from an unmatched push or
pop. The facility is:
saveAC <a,b,c>
in which a, b, and c are AC names; one or more may be specified.
Defining a different mnemonic for a preserved AC may be of value when the AC
is used for a specific function by a large body of code. However, it offers
the possibility of confusion because two different symbols may refer to the
same AC unbeknownst to the programmer. In smaller programs, use of certain
ACs can be restricted to specific functions, and a global definition is
appropriate. A very large program, however, usually cannot accomodate a
sufficient number of dedicated ACs.
Therefore, when a specific function-oriented AC definition is made, it should
be explicitly decided which modules should use the definition (by "module" is
meant a separately-compiled section of code). Within these modules, the usual
name for the AC must be purged so that there is no possibility of using two
different symbols for the same AC.
Only preserved ACs may be used for special definitions. Parameters to
subroutines may be passed in functionally defined ACs in the following cases:
1. On an intra-module call where the contents of the AC is appropriate
to its function definition.
Standards Page 168
2. On an inter-module call where the same definition exists in both
modules and the AC is being used for its intended function.
A parameter may NOT be passed in a preserved AC unless both caller and callee
know it by the same name, and that name must be a specific one related to the
function which the AC is performing.
The procedure for declaring a functionally defined AC is:
defAC newAC,oldAC
This must be done at the beginning of an assembly, and it causes newAC to take
on the value of oldAC. OldAC must be the mnemonic for one of the regular
preserved ACs, and this mnemonic will be purged and therefore unavailable for
use in the current assembly.
An AC with a special definition should not be used for other purposes; e.g.
"JFN" should not be used to hold some quantity other than a JFN merely because
it happens to be available.
8.10. Subroutine Documentation
The following is a suggested format for documenting the calling sequence of a
subroutine. A description of this sort should appear at the beginning of
every subroutine, no matter how short.
srName: comment |
One or more lines describing what the subroutine does.
Enter with:
t1/ Description of first argument.
t2/ Description of second argument.
:
:
global foo/ Description of required global variable.
Returns:
+1: Conditions giving this return, with:
t1/ Value(s) returned.
t2/ More value(s) returned.
:
:
global foo/ Description of how it was effected.
+2: Conditions and values as above.
|
Notes:
1. The arguments, if any, should be documented as the contents of
registers and/or variables as shown. If there are more than 4
arguments, then the address of an argument list should be passed.
2. It is absolutely essential that all global inputs and outputs
(variables, tables, flags, etc., that are not declared within the
Standards Page 169
subroutine) be noted; failure to do so hides crucial assumptions
and effects from readers, and makes modification a very tricky
business.
3. An example of argument setup, call, and +1/+2 handling should be
given if necessary for clarification.
4. The return(s) should be noted as shown; "Always" or "Never" may be
used as the condition where appropriate; the +2 return need not be
shown if it does not exist; values returned should be described in
the same form as arguments.
8.11. Multi-line Literals
The use of multi-line literals is encouraged as a technique for making code
more readable and easier to follow. The following additional rules apply:
1. The opening bracket for a multi-line literal should occur in the
position that the first character of the address field would have
appeared if the instruction had an ordinary address, e.g.
skipge foo
jrst [
2. The first and all following instructions within the literal should
begin at the second tab stop, e.g.
jrst [ move t1, mumble ; Comment
jrst fie ] ; Comment
The tab between the open bracket and the first opcode may be
omitted if the line position is already at or beyond the second tab
stop, e.g.
GTJFN
ercal [move t1, mumble
If the first opcode is beyond the second tab stop, it is better to
start the enclosed code on a new line, e.g.
jumpge t1, [
move t1, mumble
3. The closing bracket should follow the last field of the last
instruction (as above), and should be before the comment on the
same line. It should have a blank before it to set it off from the
preceding token.
Standards Page 170
4. Nesting of multi-line literals to a depth greater than two is
discouraged because of awkward formatting problems.
5. Labels should not appear in multi-line literals.
6. No hard and fast fules can be given as to when to use or not use
multi-line literals. However, a literal longer than about 10 lines
becomes suspect.
7. Use of ".+1" is legal in a literal to return to the main sequence.
8.12. Flow of Control - Branch Conventions
In general, jumps should be to labels forward (down the page) from the point
of branch except for loops. Tops of loops should be identified by comment.
The expressions ".+1" and ".-1" are the only legal uses of "." (this
location). All other potential uses should be avoided in favor of an
explicitly defined label.
"Global" jumps should be avoided altogether. Higher-level languages do not
permit them, and with good reason. The only exceptions are jumps to well
defined and published exit sequences, e.g. R, RSKP (see subroutine
conventions, above).
8.13. Numbers
In general, there should be no occasion to use a literal number in in-line
code. All parameters, bit definitions, etc., should be defined mnemonically
at appropriate places. It is much easier to err in the direction of too
little use of mnemonics rather than too much; therefore, when in the slightest
doubt, define a mnemonic.
8.14. Sharability
When two or more people are running the same (copy of a) program, they can
share the memory pages it occupies. This cuts down on page faults and makes
the program, and the system, run more efficiently. Most higher level
languages produce sharable code automatically, but the assembly language
programmer must take special pains to do so. To write sharable programs, you
must collect all your impure data together in one place, segregating it from
actual program code and pure data (a word is impure if it can be modified at
runtime). Each user gets a private copy of any page that has been written
into, so sharability is greatest when all the impure data has been collected
into the fewest possible pages. Pure data (e.g. command or dispatch tables)
can be freely mingled with code provided there is no way for control to pass
into it.
Standards Page 171
8.15. Living in an Imperfect World
Much of the current DECSYSTEM-20 software was written before the existence of
this standard and therefore does not conform to it. A great deal of
systematic editing has already been done to improve conformance, but obvious
irregularities exist. In general, new code being added should conform exactly
to this standard even if being integrated with old code. The following are
some specific problems which may arise and the recommended solutions:
8.15.1. AC Mnemonics
Some code uses absolute numeric ACs. If new code is being integrated into a
sequence which uses numeric ACs, it is desirable that the existing code be
edited to use the standard mnemonics, particularly for the preserved ACs. If
the programmer cannot take the time to do that, then the mnemonics T1-T4
should be used for ACs 1-4, and other ACs should be referenced in the same way
as is done by the existing code. Some code uses mnemonics A,B,C,D for the
temporary ACs. These same mnemonics should be used for new code integrated
into this existing code, or all references can be edited to use the standard
mnemonics. You may write some code using the standard mnemonics for preserved
ACs and then discover that the module into which you wish to put this code has
redefined some of these ACs. The solution is one or a combination of the
following:
1. Move the new code to a module which does not redefine the preserved
ACs.
2. Use different preserved ACs -- ones which have not been redefined.
(Note it is not acceptable to use an AC with a special definition
for other than its special purpose.)
Clearly, code which needs some of the special definitions must be placed in a
module which has these ACs defined and must therefore use only the other
preserved ACs.
Note that a value which usually resides in a special AC need not ALWAYS reside
there; for example, it can be placed in one of t1-t4 as a subroutine argument.
8.15.2. Stack Handling
Use of the several stack variable facilities defined in MACSYM is recommended.
Some old code uses explicit PUSH and POP and references of the form -n(p)
however, and when anything more than trivial modifications must be made to
such code, it is most strongly recommended that the code be edited to use
STKVAR or TRVAR. Failing that, references must be consistent with the
existing code.
How To Page 172
9. How to Write, Assemble, and Run Programs
Macro programs must be entered into the computer by means of a text editor.
The best such editor is EMACS, which not only surpasses other editors in power
and flexibility, but understands the syntax of Macro programs; to take
advantage of this understanding you should put EMACS in Macro mode (MM Macro
Mode).
Macro programs are fully compatible with the Exec Load-Class commands. These
are:
COMPILE The COMPILE command produces a relocatable object program from
one or more source programs. The resulting object file has
the extension .REL. If there is already a .REL file of the
given name that is newer than any of the source files, no
compilation will be done unless the /COMPILE switch is
included.
LOAD The LOAD command invokes LINK, the system linkage-editor and
loader, to bring compiled modules into memory, resolving any
unresolved references, and produce an executable core image.
The LOAD command will recompile any module whose most recent
.REL file is older than the most recent source (.MAC), i.e.,
any source file you've edited since the last LOAD. If you
want to have a directly-executable (.EXE) version of your
program on the disk, you should issue the SAVE or CSAVE
command after the LOAD command completes. LOAD does not start
the program; you must use the START command to do this.
EXECUTE The EXECUTE does what the LOAD command does and then STARTs
execution of your program.
DEBUG The DEBUG command acts like the EXECUTE command, but it also
loads DDT (the source-level assembly language debugger) into
memory and starts DDT instead of the program. It is
equivalent to LOAD followed by DDT.
If you repeatedly edit your program with EMACS, EDIT, or Otto, you can issue a
special command which saves the .MAC file, exits from the editor, and then
tells the Exec to reissue its last load class command, with the 'saved
arguments'. In EDIT the command is 'g'; in Otto it is 'go'; in EMACS it must
be assigned to a key in your EMACS.INIT file.
All the LOAD-class commands have the following features:
1. Recognizing that your program is in Macro, provided the extension
(filetype) of the source file is .MAC.
2. Saving their arguments, or if no arguments were specified,
recalling the arguments of the last LOAD-class command in which
arguments were specified. For instance, if you have already issued
the command
LOAD foo,mylib:bar
you can achieve the same effect in subsequent compilations by
merely typing
How To Page 173
LOAD
The same effect is achieved by exiting the editor with a 'go'-type
command, as described above.
3. Taking arguments from an indirect file. You can put repeatedly used
arguments in a file as they would appear in the command and then
give a command like 'load @mac'. The '@' indicates that the
command should look to the file for its arguments.
4. Gathering files together to produce one program. This is done by
separating the files to be worked on by either commas or plus signs
on the command line; commas mean to consider the files as separate
modules (with surrounded by Title and End pseudo-ops), a plus signs
means to concatenate the enclosing files.
5. Passing switches to the compilers and LINK.
The load-class commands themselves have many switches. Type any load-class
command followed by a slash and then a question mark to see what they are.
DDT Page 174
10. Interactive Debugging of Assembly Language Programs
This chapter was adapted from the DECsystem-10 Utilities Manual and
the Rutgers University IDDT manual.
DDT (Dynamic Debugging Tool) is a program that allows you to test and debug
assembly language programs interactively using the same symbols (labels and
register names) that are used in the program. You can invoke DDT in either of
two ways: type 'DDT' after the completion of a LOAD command (or after GETting
an .EXE file) or by using the DEBUG command (see 9). In either case, the
effect is the same: DDT is loaded into pages 770-777 of your address space
(your program should not use these pages) and started. You may then type DDT
commands to examine storage locations, set breakpoints, execute selected
sections of the program, single-step through the program, search for certain
instructions or data, modify code or data, and so forth.
DDT commands are purposely terse, and therefore somewhat cryptic. You can use
DEL (RUBOUT) and ^U to edit commands; these have the expected effect, but echo
as "XXX".
In the following descriptions, a dollar sign ($) indicates that the ESC
(ESCAPE or ALTMODE) character should be typed. All numbers are in octal
unless otherwise noted.
10.1. Typeout Modes
You can select how DDT will display the contents of memory. Normally (i.e. by
default) it tries to interpret each word as an instruction, decoding the
opcode, accumulator, index, indirect, index, and address fields and
substituting appropriate values from the program's (or DDT's own) symbol
table, e.g. 202067,,1000 (octal) would be typed by DDT as
MOVEM T1, @FOO(Q3)
assuming that T1 is defined to be 1, Q3 to be 7, and FOO to be 100 in the
program's symbol table.
You can tell DDT to interpret words in other ways, either on a temporary or
prevailing basis.
The following commands are used to set the type-out modes:
$S Symbolic instruction.
$C Numeric, in current radix.
$F Floating point.
$T 7-bit ASCII text.
$6T SIXBIT text.
$5T RADIX50.
$H Halfwords, two addresses.
DDT Page 175
$nO Bytes (of n bits each), separated by commas.
10.1.1. Address Mode Typeout
The following commands are used to set the address modes in typeout of
symbolic instructions and halfwords:
$R Relative to symbolic address, e.g. FOO+17
$A Absolute numeric address, e.g. 4023.
10.1.2. Radix Typeout
You can also determine the radix (base, e.g. decimal, octal) in which the
numeric parts of a displayed word are typed, using the following command:
$nR Change radix to n (n>1).
10.1.3. Prevailing vs Temporary Modes
The typout-mode commands shown above may be started with a single ESC ($), or
two ESC's ($$):
$$ Set the prevailing type-out or address mode or a prevailing
radix (e.g. $$10R - set prevailing numeric radix to 10)
$ Set the temporary typeout mode; display words or fields in
this mode until carriage return is typed (e.g. $2R - set the
temporary numeric radix to 2).
CR (carriage return) Terminate temporary modes, and revert to prevailing
modes.
Initial modes are: $$S (symbolic instructions), $$R (relative addresses), and
$$8R (radix 8 [octal]).
10.2. Storage Words
The following commands are used to examine storage words. If you type ESC
between the address and the delimiter, the effective address of the typed
quantity will be calculated first, e.g. 1(p)$/ will print the contents of the
word after the one pointed to by p.
adr/ Open and examine the contents of adr in current type-out mode.
adr! Open, but inhibit the type-out.
adr[ Open and examine word as a number in current radix.
adr] Open and examine word as symbolic instruction.
DDT Page 176
; retype last quantity typed (useful after setting a temporary
type-out mode, e.g. $6T;).
adr\ Open in current mode, but don't change location counter.
10.2.1. Related Storage Words
The following are used to examine related storage words:
<lf> (linefeed or ^J) Close the current word (making any modifications typed
in) and to open the following word.
^ (circumflex) or ^H (backspace) to close current word (with modifications)
and open adr-1.
^I (tab) Close current word (with modifications) and open word
specified by address of current word and to set the location
counter to that place.
\ Same as ^I, but location counter is not changed.
<cr> Close word (with modifications) and revert type-out to
prevailing mode.
10.2.2. Retyping In Modes Other than the Prevailing Mode
Each of the following commands specifies the mode in which DDT should
immediately retype the last expression typed by DDT or the user. Neither the
temporary nor the prevailing mode is altered.
= Retype as halfwords in current radix.
_ (undescore) Retype as a symbolic instruction (address part determined by
$A or $R).
/ Type out, in current type-out mode, the contents of the
location specified by the address in the open instruction
word, and to open that location, but not to change the
location counter.
[ Retype as a number and open contents of the location specified
by the open instruction and not to change the location
counter.
] Same as above, but type out as a symbolic instruction.
10.3. Typing In
These are shown by example:
ADD AC1,@DATE(17) to type in instruction simply type it in symbolically.
DDT Page 177
402,,202 to type in halfwords.
1234 to type in octal values.
99. to type in fixed point decimal integer.
101.11 to type in ..
77.0E+2 ... a floating-point number.
"/ABCDE/ ASCII input (/ is delimiter; up to 5 characters).
"A$ ASCII input (one character, right justified).
$"/ABCDEF/ SIXBIT input (/ is delimiter; up to 6 characters).
$"Q$ one SIXBIT character.
10.4. Symbols
A symbol is is defined in DDT as a string of up to six letters and numbers
including the special characters ., %, and $. Characters after the sixth are
ignored. They are defined in a table kept with the program you are DDTing,
called the "symbol table". Programs have only one symbol table unless their
authors have taken explicit action to create more than one. Such actions
include compiling and/or linking the program from more than one source and/or
.REL file.
foo$: Permit reference to local symbols within a module with title
"foo" (open the symbol table of foo). You can refer to
symbols in a program without issuing this command, but DDT
always appends "#" to the symbol on typeout in this case to
show that it's only guessing. If a program has more than one
symbol table, you should use this command to let it know which
table to use.
n<sym Insert or redefine a symbol in the symbol table and give it a
value n.
sym: Insert or redefine a symbol and give a value equal to the
current location counter (.).
sym$$K Delete a symbol from the symbol table.
sym$K Kill a symbol for type-outs (but sill permit it for type-ins).
$D Perform a $K on last symbol typed out and then retype the last
quantity.
sym# Declare a symbol whose value is to be defined later.
? Type a list of all undefined symbols (created by #).
DDT Page 178
10.4.1. Special DDT Symbols
. The present location counter.
$Q The last quantity typed.
$$Q The last quantity typed, halves reversed.
@ Indirect bit.
$M The address of the mask register.
$I The address of save flags.
$nB Pointer to nth breakpoint.
10.4.2. Arithmetic Operators
DDT can evaluate expressions involving the following arithmetic operators:
+ two's complement addition.
- two's complement subtraction.
* integer multiplication.
' integer division (apostrophe).
Parentheses are used to denote an index field or to interchange the left and
right halves of the enclosed expression.
Expressions are evaluated as follows: A left parenthesis stores the states of
the storage-word assembler on a stack and reinitializes the assembler to form
a new storage word. A right parenthesis terminates the storage word and swaps
its two halves to form the result inside the parentheses. The result is
treated in one of two ways:
1. If +, -, ', or * immediately preceded the left parenthesis, the
expression is treated as a term in the larger expression being
assembled and therefore may be truncated to 18 bits if part of an
address field.
2. Otherwise, the swapped quantity is added into the storage word.
Parentheses may be nested to form subexpressions, to specify the left half of
an expression, or to swap the left half of an expression into the right half.
10.4.3. Field Delimiters In Symbolic Type-ins
SPACE Delimit opcode name (spaces or blanks). Add the value of the
immediately preceding expression (normally an opcode) into the
sotrage word, and set a flag so that the expression going into
the address field is truncated to 18 bits.
DDT Page 179
, (comma) Delimit accumulator field. The comma does three things:
1. The left half of the expression is added into the
storage word.
2. The right half is shifted left 23 bits (into the
accumulator field) and added into the storage word.
3. A flag is set to truncate addresses to 18 bits.
,, (double comma) Delimit two halfwords.
( ) Delimit index register (the halfwords are swapped).
@ Indicate indirect addressing (set bit 13).
The address field expression is terminated by any word termination command or
character.
10.5. Breakpoints
You can automatically stop your program at a strategic point by specifying an
address at which the program should stop if the instruction at that address is
about to be executed (i.e. if the PC (Program Counter) attains that value).
These addresses are called breakpoints; there may be up to eight of them
active at one time. Breakpoints may be set before the debugging run is
started or during another breakpoint stop.
The commands to set and remove breakpoints are:
adr$nB Set breakpoint n.
adr$B Set next unused breakpoint.
adr$$nB Set breakpoint...
adr$$B ... with automatic proceed.
x,,adr$nB Set breakpoint which will...
x,,adr$B ...automaticaly open and...
x,,adr$$nB ...display the contents of...
x,,adr$$B ...address X.
0$nB Remove breakpoint n.
$B Remove all breakpoints.
$nB/ Check status of a breakpoint.
If the address field (adr) is omitted, the breakpoint will be set at the
current location.
When your program reaches a breakpoint, DDT types (for example)
DDT Page 180
$7B>>FOO+23
where breakpoint number 7 was set at location FOO+23 (for instance, by the
command FOO+23$7B).
10.5.1. Proceeding from a Breakpoint
After you have poked around to your satisfaction, you may continue the program
using the following commands:
$P Proceed from a breakpoint. Keep executing until another (or
the same) breakpoint is encountered, or the program halts.
n$P Proceed as above, but pass this breakpoint n-1 times (i.e.
ignore it until the nth encounter).
$$P Proceed from a breakpoint...
n$$P ...and thereafter proceed automatically.
10.5.2. Single Stepping
After a breakpoint has been encountered, you may wish to single-step through
your program, rather than continuing with $P. DDT provides the following
commands for single-stepping:
$x Execute the current instruction, type out the new contents of
any locations affected by the instruction, type out the next
instruction, and wait. No breakpoints are moved or removed.
n$x Like $x, but do it for n instructions.
n$$x Same as $x, but execute instructions unconditionally, without
typing anything out, until PC reaches either .+1 or .+2. This
is useful for executing debugged subroutines or UUO's.
10.5.3. Conditional Breakpoints
You can insert a conditional instruction, or a call to a closed subroutine,
using the following command:
$nB+1/instruction Insert a conditional instruction or call a conditional
routine, when breakpoint n is reached.
When the breakpoint is reached, this instruction or subroutine is executed.
If the instruction (or subroutine) does not skip, the program either stops or
continues based on the contents of the proceed counter (located at $nB+2). If
the instruction or subroutine skips, the program stops. If the subroutine
causes a double skip return, the program proceeds. This works as follows:
DDT Page 181
skipe $nB+1 ; Conditional break instruction?
xct $nB+1 ; Yes, execute it (it may skip).
sosg $nB+2 ; Decrement proceed counter.
jrst <break routine> ; If greater than 0 then break
jrst <proceed routine> ; else proceed.
10.5.4. Starting the Program
$G Start at .JBSA (the normal starting address).
adr$G Start or continue at a specific address.
10.6. Searching
There are three kinds of searches: word search, not-word search, and
effective address search. In the following commands, a<b>c are respectively:
lower limit, upper limit, searchword; a defaults to 0, b defaults to "end".
The word search and not-word search compare each storage word with the word
being searched for in those bit positions where the mask, located at $M, has
ones. The mask word contains all ones unless otherwise set by you. All words
in the given range that show equality to the search object under the mask are
typed out.
a<b>c$w Search for word containing c.
a<b>c$N Search for word not containg c.
a<b>c$E Search for a word containing effective address c.
n$M Set the mask to n.
$M/ Examine the mask.
You may use the word search command to list the range of locations from
'first' to 'last', as follows:
0$M first<last>0$W
This sets the mask to 0 and then performs a word search for 0. Remember to
put the mask back to -1 (or whatever its previous value was) before
continuing.
10.6.1. Zeroing Memory
$$Z Zero memory except DDT, locations 20-137, and the symbol
table.
first<last$$Z Zero locations 'first' thru 'last'.
DDT Page 182
10.7. Special Characters
The following are used in DDT type-outs:
> Break caused by conditional break instruction.
>> Break because proceed counter exhausted.
U Undefined symbol can not be assembled.
# (as in FOO#) The symbol has been interpreted from a symbol
table you have not formally opened.
number,,number Half-word number type-out.
#1.234E+27 Unnormalized floating-point number.
123. Decimal point indicates decimal number.
? Illegal command or all 8 breakpoints used.
XXX Rubout, ^U echo.
10.8. Miscellaneous DDT Commands
10.8.1. Immediate Mode Instruction Execution
instr$X Execute the instruction in immediate mode.
10.8.2. Execute Indirect Command File
$Y Read and execute a command file called BATCH.DDT.
$"/name/$Y Read and execute a command file called name.DDT.
10.8.3. Patch
A patch is a section of code or data inserted into an .EXE file, usually to
correct a bug. At the appropriate location, an instruction is replaced by an
unconditional jump to the new code; the instruction that was displaced is
included in the new code, and the new code usually terminates with a jump back
the original sequence. You can use DDT to insert a patch with the following
commands:
$< Patch before the currently open location.
$$< Patch after the currently open location.
$> End the patch.
DDT Page 183
When you begin a patch, DDT will open the first location in the patch area (an
area set aside automatically by Macro, or by other means, for the installation
of patches). The patch area is defined by the symbol PAT.. or PATCH or
C(.JBFF), whichever is found first. Alternately, you can type a single symbol
preceding the patch begin command (as in "FF$<"), and it will be taken as the
beginning of the patch area. If you are doing a patch after the current
location, DDT will insert your original instruction and then open open the
next location. You may now proceed to enter your patch using linefeeds to
enter the new instructions or data.
When you have finished the patch, type $> and DDT will:
1. Close the current location, if any.
2. If a patch "before" was was being done, DDT will insert the
instruction from the original location.
3. DDT will insert JUMPA 1,LOC+1 and JUMPA 2,LOC+2, where LOC is the
original patch location. Thus skipping instructions may be
patched.
Note: the original location is not changed until the patch completion command
is given. Thus, you can give up or restart the patch at any time. DDT
remembers the parameters of the most recent patch begin command and uses them
at patch completion, whereupon they are forgotten. A second patch completion
will produce an error indication.
10.9. Sample DDT Session
Here's a very short DDT session, just to get you started. A Macro program is
compiled and loaded, DDT is called in, a breakpoint is set, the program is
started and runs until the breakpoint is encountered. A location is examined
and its contents replaced, and the program is then continued. This short
example illustrates the most useful DDT commands. In the example, after DDT
is started, DDT typeout is shown in upper case; your commands are shown in
lower case.
@load foo ; Compile and load the program.
MACRO: Foo
LINK: Loading
EXIT
@ddt ; Start DDT.
DDT ; DDT's greeting.
foo$: ; Open Foo's symbol table.
subr$b $g ; Set a breakpoint and start.
$1B>>SUBR ; The breakpoint is encountered.
./ MOVEM T1, FROB ; Display the instruction at the breakpoint.
t1/ 5 -1 ; Display contents of t1, then replace
; it with -1.
$x ; Now execute the instruction.
T1/ -1 FROB/ -1 ; The effected locations are displayed.
SUBR+1/ MOVE T1,Q1 $p ; The next instruction is shown, and
. ; the program is continued using $P.
. ; (the session continues...
. ; ...)
DDT Page 184
^Z ; Exit from DDT
@ ; back to the Exec.
10.10. IDDT (Invisible DDT)
This section is extracted from a document from Rutgers University,
describing IDDT, a program that has a long lineage, starting at BBN
and including at least SRI, MIT, and Rutgers. All of the elementary
commands and features have been included. For further details, see
the complete IDDT manual.
IDDT is a debugger which will handle programs with multiple forks and ones
which use high core (which is used by regular DDT) as well as other programs
which DDT can't handle. It has many of the same commands as the standard DDT
and ordinarily may be used without regard to the fact that it is a different
debugger.
The primary feature of IDDT is that it operates on user programs which run in
any inferior fork of IDDT. Thus, an errant user program cannot destroy the
debugger or its symbol table because the debugger is in a totally different
address space. This relation between the program being debugged and IDDT is
much the same as the relation between current user programs (including IDDT)
and the Exec. Because of this, IDDT must simulate many of the services
ordinarily provided by the EXEC, such as GET, LINK, RUN, etc.
10.10.1. Using IDDT
IDDT may be called into service either before or after programs have been
loaded into memory. This is done by typing the Exec command IDDT.
This command causes the EXEC to splice a fork containing IDDT in between
itself and the program to be debugged. This operation is done in a way that
preserves the state of the user's program including its fork structure. It is
possible to ^C out of a running program and get IDDT. If this is done, a $P
(Proceed) command will resume running the user program.
The EXEC command "NO IDDT" will unsplice the fork containing IDDT in the event
the user wishes to continue his program without having an IDDT above it.
A fairly common practice is to get IDDT first and use it to load the program
to be debugged. One of three IDDT commands may be used to load the object
program: $L (run LINK in the user fork), ;L (Loadgo (RUN) named file), or ;Y
(Yank (GET) the named file). The first of these is essentially the same as
the EXEC command, LINK. The second is comparable to RUN, while the last is
similar to GET. In addition the ;M (Merge the named file) will simulate the
MERGE EXEC command.
The $L command causes IDDT to run LINK in the user's address space. Upon
completion, LINK may return control to IDDT. At this point IDDT will have the
LOADER's symbol table. In order to switch to the symbols of the program which
was loaded, the ;S (Symbol) command should be typed. ;S tells IDDT to look
for a standard symbol table pointer in location 116 (.JBSYM).
DDT Page 185
10.10.2. EXEC-like Features
For convenience, IDDT has several commands which provide the same services as
some EXEC commands. These are:
<n>;A Give informaton about page n or if n is missing about all
pages. (like a INFO MEMORY command)
<n>;F Fork information about fork n or if n is missing about all
forks. (like INFO FORK command)
<n>;J JFN information on JFN n or if n is missing about all JFNs.
(like INFO FILES)
;;J Job information (like INFO JOB and INFO FORK)
;I Interupt status of PSI system (like INFO PSI-STATUS)
<n>;V "View cell" - sets address, contents of which is displayed
when ^T (control T) is typed. If n is missing clear "view
cell"
;Y Yank - analogous to EXEC command GET
;M Merge - analogous to EXEC command MERGE
;L Loadgo - Analogous to EXEC command RUN
$$G Go - analogous to EXEC command START
$$1G Analogous to EXEC command REENTER
$$nG Analogous to EXEC command START at offset n of entry vector
$P Proceed - analogous to EXEC command CONTINUE
;U Unget (SAVE 0 777)
a<b$nU Unprotect page (like SET PAGE-ACCESS command)
loc$$nU Set address break trap for loc in current fork; n is the type
of access to trap on (defaults to 2): 1 - read, 2 - write, 4
- execute (these can be or'ed together); like the EXEC command
SET ADDRESS-BREAK
;O Obtain symbol file (no EXEC equivalent)
;W Write symbol file (no EXEC equivalent)
;H Halt IDDT (return to EXEC)
;W, ;M, ;Y, ;O, ;L, and ;U ask for a file name from the user. The default
extension will be .EXE or .SYMBOLS as appropriate.
DDT Page 186
10.10.3. View Cell
A command such as FOO+5;V or 12345;V will define the "view cell". When IDDT
handles a ^T (control T) the address and contents of the view cell will be
typed. The view cell may be undefined and consequently removed from the ^T
(control T) typeout by ;V (no argument).
Note: The contents of the view cell in the fork to which IDDT's attention has
been directed to is what will be typed out on the ^T.
10.10.4. Breakpoints
When a fork hits a breakpoint, IDDT's handle on the breaking fork is printed
in parens before the breakpoint name unless it is the the top fork, e.g.
(2)$1B>>105.
10.10.5. Fork Handles
IDDT's attention can be shifted to any fork in the program being debugged
using the ;;F command. In the form: n;;F, fork n becomes current and all
examines, deposits, breakpoints etc pertain to it. n is a small number
(actually the low bits of IDDT's fork handle on the fork in question). 0
always means the top fork of the debugee. In the form m<n;;F, attention is
switched to the m-th inferior of fork n. Again, n is IDDT's handle on some
fork in the debugee. m is the low bits of fork n's relative handle on some
fork (IDDT executes GFRKH(400000+n, 400000+m) to get the new handle). The
relative handle so obtained is printed.
10.10.6. Escape character
IDDT initially arms ^D (control D) as an interrupt character. This may be
changes with the ;E (set Escape character) command. If a user program has
been started under IDDT, typing ^D (the escape character) will gracefully
suspend that process and give control to IDDT which then types a message of
the form
XXX:FOO+5/ MOVE A,DAT+21
The interrupt is understood to have occurred immediately before this
instruction, and that if a $P (proceed) command is typed, this instruction
will be the next one executed by the user.
10.10.7. RUBOUT and Type-in Editing
RUBOUTs typed while IDDT is running behave much the same as they do in normal
DDTs, that is, the current command is aborted. This is particularly
convenient for stopping long searches ($W, $N and $E commands), with IDDT
because it is an interrupt and does not have to be read by a PBIN to initiate
action as it does with old-style DDT's.
DDT Page 187
On command typein RUBOUT acts as it does under the EXEC, that is to delete the
previous character in the input buffer. In addition ^W and ^U (control W and
control U) also work as in the EXEC by deleting the word and line
respectively.
10.10.8. Interface with the Exec
The EXEC command "FORK n" may be used to switch the EXEC's attention between
the fork containing IDDT and the one containing the user's program. This may
be done for the purpose of doing a "MEMSTAT" or ^T. The EXEC examine and
deposit commands also pertain to the currently selected fork.
If the user has returned to the EXEC by typing ;H to IDDT, IDDT may be resumed
by a "CONTINUE". A HALTF in the user's program will return to IDDT. It may
be continued by a $P to IDDT.
10.10.9. Saving a Core Image
The ;U command asks for a file name and then does the equivalent of a SAVE
from page 0 through page 777 on this file. The entry vector will be copied if
it exists. If no entry vector has been declared for the fork, IDDT will set a
length one entry vector at "." . A message is typed to this effect.
10.10.10. Single Instruction Executes
When the user types an instruction followed by $X, IDDT pushes down several
words of state information, plants the instruction in the user's address space
followed by three breakpoints, and restarts the user at this special location.
When the instruction completes, IDDT types the proper number of $-signs to
indicate how many times the instruction skipped, and pops back the saved state
information. The state information currently includes the program counter
($G), and which breakpoint (if any) the user was stopped at. This makes it
possible to hit a breakpoint, execute an instruction (which might be a PUSHJ
to a subroutine), and then, upon completion of the $X, do a $P to proceed the
breakpoint.
IDDT's $X register points in the user's address space to the four words which
will be used for $X commands. $X initially contains 777774 so that the top
four words are used. The user is free to change the contents of $X.
10.10.11. Search Commands
The search commands ($W, $N, and $N) have been generalized to take an argument
which specifies the maximum number of "finds" that shall occur before the
search will terminate. An example is:
FOO<BAR>QQZZ$5E
This command will stop after typing five instructions lying between locations
"FOO" and "BAR" which have an effective address of "QQZZ".
DDT Page 188
10.10.12. Single Stepping
There are two flavors of single stepping, $Y and $J:
$J just fetches the next instruction and executes it, so if that next
instruction is a subroutine call, the entire subroutine will be executed, and
if that instruction is a jrst, the program will be continued.
$Y fetches the next instruction and if it is a jump of any sort, it is
interpreted so that in fact only one instruction is executed at a time, so
that if the instruction is a subroutine call, the program counter will be set
to the beginning of the subroutine. (this is most like $X in other DDTs)
Both commands have the same syntax:
$J single steps
<num>$J will step num times
<num>(<loc>)$J will step num instruction or until the contents of location loc
are changed, in which case it will stop and say
(WP)PC LOC/ new contents of loc
where pc is the instruction after the one that attempted to change the value
of loc. Note, however the contents of loc will not be changed.
<loc>$$J is equivalent to infinity(<loc>)$J, ie it will single step until an
attempt is made to change the contents of loc.
If the verbose switch is on, the instruction being executed and any AC's or
the view cell (see above) that change will be typed out.
Both instruction are extremely slow.
10.10.13. Other Commands
^L blanks the screen
$. returns current PC
;.<internal symbol name> inserts the value of the internal symbol into the
expression. Current internal symbols are:
SYMOFS Offset from symbol printed as in
<symbol>+<nnn> (default value is 777 octal).
PC Current PC (see also $.) (can be set with
<adr>$0G).
example: ;.PC/ 10010 displays the contants of the PC register
Examples Page 189
11. Programming Examples
The programs in this chapter are purely pedagogical in nature and don't do
anything useful.
11.1. Binary Search Program
title binSrc - Demonstration of binary search.
$VERNO=1 ; Program version number
$EDNO=2 ; Program edit number
comment \ Most recent update: 10:23am Thursday, 19 April 1979
Prompts user for a number, looks it up in a list containing the
even numbers from 2 to 12 (with some duplicates).
H. Eskin, F. da Cruz, CUCCA, April 1979
\
search CUsym ; Obtain Columbia macros, symbols, etc.
%setEnv ; Search Monsym, Macsym, initialize things.
numLen=^d20 ; Buffer for number typein.
; Standard 3-word entry vector
entVec: jrst start ; Start address
jrst reEntr ; Reentry address
%version ($VERNO,$EDNO) ; Standard version number
evlen=.-entvec ; Entry vector length
reentr: jrst start ; reentry handling (nothing special)
start: %setUp ; RESET, set up stack, etc.
hrroi t1, [asciz /Number to search for: /]
call getNum
call search
%print < No exact match%/>
%print < %d found at %o%/>,<exp t1,t2>
jrst start
Examples: Binary Search Page 190
search: comment | Binary search routine
Looks the given number up in a list, which is presumed to be
in ascending numeric order (with duplications allowed).
Returns values appropriately for insertion of a new element.
Enter with:
t1/ Number to search for.
global list/ list of numbers to be searched, in ascending order.
global top/ address of the word after the last element in the list.
Returns:
+1: if number not found,
+2: if number found, with (in either case):
t1/ Number that was found;
t2/ The address of the greatest number less than or equal
to the desired number. If no such number, then the address
of the word before the beginning of the list.
|
Lo=p1 ; Mnemonic aliases for registers
hi=p2 ; (not normally recommended).
PURGE p1,p2 ; (to avoid duplicate names for same ACs).
saveAC <hi,Lo,q1> ; Save these registers.
; Set up initial conditions.
movei Lo, list-1 ; Point before search list
move hi, top ; and after it.
; This loop does the binary search.
loop: cail lo, -1(hi) ; Is the list null?
jrst nFound ; Yes, then the element has not been found.
move q1, Lo ; No, calculate midpoint: set probe to Lo
add q1, hi ; ... + hi
idivi q1, 2 ; ... / 2.
camn t1, (q1) ; Exact match?
jrst found ; Yes, done.
; No match, adjust boundaries of list appropriately.
caml t1, (q1) ; If search key is not less than this one
skipa Lo, q1 ; then move low bound and skip
move hi, q1 ; else move high bound,
jrst loop ; and go back and try again.
;.. ; (continued next page...
Examples: Binary Search Page 191
;...continued from preceding page)
; Get here when the list is used up (and the search object not found).
nFound: move t1, (Lo) ; Greatest element that was less than search
move t2, Lo ; key was found at this address.
ret ; Return indicating failure to find key.
; Get here only on exact match. Must check for duplicates.
; Put aobjn counter in left half of probe, then search.
found: movn t2, top ; Negative Address of 1st element not in list.
add t2, q1 ; Calculate -number of elements to be checked.
hrl q1, t2 ; Make aobjn pointer.
next: camn t1, 1(q1) ; Toodle down the list until no match
aobjn q1, next ; or no more elements.
fin: move t1, (q1) ; Return the value that was found
hrrz t2, q1 ; and its address.
retskp ; Skip return to indicate that it was found.
p1=Lo ; Restore normal AC mnemonics
p2=hi ; ...
PURGE hi, Lo ; ...
Examples: Binary Search Page 192
getNum: comment | Get a number from the terminal, allowing editing.
Enter with:
t1/ pointer to asciz prompt.
global numBuf defined to be of length numLen.
Returns +1 always, with
t1/ number that was typed.
This routine catches all format errors and reprompts the user
until a valid integer is typed.
|
saveAC <t2,t3,q1> ; Since not used for passing args.
move q1, t1 ; Save pointer to prompt.
reTry: move t1, q1 ; And restore it in case of error.
PSOUT ; Issue the first prompt.
hrroi t1, numBuf ; Point to buffer for string that user types.
movx t2, RD%BEL!numLen ; Break on CRLF, max length for typein.
move t3, q1 ; Reprompting text.
RDTTY ; Get string, allowing editing.
%jsErr ; Errors are fatal, but very unlikely.
; Now convert the string to a number. We don't do the NIN directly from
; the terminal because NIN does not allow editing.
hrroi t1, numBuf ; Point to string representation of number.
movei t3, ^d10 ; Radix for interpretation.
NIN ; Number In - do the conversion.
%jsErr (,reTry) ; On error, print msg and ask again.
move t1, t2
ret ; All OK, return.
Examples: Binary Search Page 193
%impure ; impure data
numBuf: block numLen ; For number typein.
radix ^d10
list: 0
2
2
2
4
6
8
10
10
12
top: .
^L
end <evlen,,entvec>
; - EMACS editing modes -
; local modes:
; mode:Macro
; comment start:;
; comment rounding:+1
; end:
Examples: COMND JSYS Page 194
11.2. COMND Example
title Foo - A small Exec
$VERNO=1 ; Program version number
$EDNO=1 ; Program edit number
comment \ most recent update: 11:04am Wednesday, 30 May 1979
This program is written to demonstrate various things:
1. Use of the COMND JSYS via the Columbia UUOs, with secondary
parsing done by subroutines, which return success or failure indications
to the main parsing sequence. This is the recommended method for
writing most interactive programs.
2. The normal convention for "rescan" entry into a program. If the program
is invoked by typing "foo xxx" to the Exec, where "xxx" is a Foo command,
the program executes that command and then halts; in other words, it
behaves as though "foo xxx" was an Exec command. On the other hand, if
the program is invoked by typing "foo", the user is prompted for commands
until the "exit" command is given.
3. The $dir routine shows how to do filename stepping with the GNJFN JSYS.
4. The %print UUO is demonstrated in various places. The fact that it
assembles into one word in line is shown to be handy; it can be used
in "case" statements, it can be skipped over, etc.
F. da Cruz, CUCCA, May 1979
\
search CUsym ; Obtain macros, symbols, etc.
%setEnv ; Search Monsym, Macsym, initialize things.
extern rescan ; Routines from CUrel.
; Symbol and flag definitions
%flags <xitFlg>
Examples: COMND JSYS Page 195
; Standard 3-word entry vector
entVec: jrst start ; Start address
jrst reEntr ; Reentry address
%version ($VERNO,$EDNO) ; Standard version number
evLen=.-entVec ; Entry vector length
reEntr: jrst start ; Nothing special on reentry.
start: %setUp ; RESET, set up stack, etc.
call init ; Initialize.
jrst [ HALTF ; On failure, halt
jrst . ] ; and don't allow continuation.
; Get here after successful initialization, or upon continuation.
cont: call main ; Do the work.
HALTF ; and stop the program.
%trnOff xitFlg ; (In case they continue
jrst cont ; ...)
Examples: COMND JSYS Page 196
subttl Initialization
init: comment | Initialize the program. |
; Pass rescan argument (if any) to command parser
%trnOff xitFlg ; Turn off the exit flag
move t1, [point 7, [asciz/Foo/]] ; Name of this program.
call rescan ; Do rescan processing.
%trnOn xitFlg ; Rescan arg was found, turn on flag.
retskp
Examples: COMND JSYS Page 197
subttl Main program - highest level command parser.
main: stkVar temp ; Allocate local temporary variable on stack.
%skpOff xitFlg ; Rescan entry?
jrst repars ; Yes, don't set up prompt.
restar: %skpOff xitFlg ; If we get here with the exit-flag on, there
ret ; was an error in the rescan line, so exit.
; Come here when there were no arguments on the Exec command line.
%cmIni <<Foo>>,,,gjfBlk ; Issue prompt, specify GTJFN block address.
%jsErr <Foo internal error: .CMINI failure> ; Handle errors.
; This is the reparse address. Come here after any parse error, including
; deletion into a field previously parsed (this is done automatically by
; the %merrep and %jmerrep macros).
repars: %cmKey cmdTab,<command,> ; Get major command.
%merrep restar, repars ; Handle any parse errors.
hrrz t2, (t2) ; Get address of associated dispatch word
hrrzm t2, temp ; (we'll need it again soon)
load t1, %prsAd, (t2) ; and secondary parse routine address
call (t1) ; which we call to parse the next field(s).
%jmerrep restar, repars, restar ; Handle error return.
; Get here after all fields have been successfully parsed.
move t2, temp ; Get command table word back again,
load t1, %evlAd, (t2) ; and from it, the action routine address.
call (t1) ; Call the action routine.
nop ; (ignore failure)
%skpOff xitFlg ; Was it an exit command?
ret ; Yes, exit.
jrst restar ; No, keep going.
; This is the major command table. Note that it although it is data and
; not code, it is still pure storage, and can be kept with the routine
; that uses it.
cmdTab: %table
%key <directory>, [.dir,,$dir]
%key <echo>, [.echo,,$echo]
%key <exit>, [.exit,,$exit]
%key <help>, [.help,,$help]
%key <information>, [.info,,$info]
%tbEnd
Examples: COMND JSYS Page 198
subttl Secondary Parsing Routines and Action Routines.
.dir: comment | Parse rest of "directory" command. |
movx t1, CZ%NCL!.FHSLF ; Release all non-open JFNs
CLZFF ; ...
%cmNoi <of files> ; Issue guide words.
%pret ; Fail-return on error.
; Get file specification for directory listing.
%cmFil <file specification, possibly wild>,,CM%SDH
%pret ; Fail-return on error.
move q1, t2 ; Save directory JFN in q1.
%cmCfm ; Get confirmation.
%pret ; Fail-return on error.
retskp ; Return successfully.
$dir: comment | Execute the "directory" command. |
setzi p1, ; File counter.
move t1, q1 ; JFN of first file.
; Loop to get the next file that matches the given specification
; and to print its name at the terminal.
$dLoop: aos p1 ; Count the file.
hrrzs t1 ; Clear out the wildcard flags,
%print < %j%/>,<t1> ; and print the filename.
move t1, q1 ; Get back the original JFN.
GNJFN ; Get the Next JFN that matches.
jrst $dDone ; If none, then all done.
jrst $dLoop ; Loop for all files.
; Come here when no more files match the given specification.
$dDone: %print <%/ %d File>,<p1> ; Say how many files.
caie p1, 1 ; If other than one,
%print <s> ; then pluralize.
retskp ; Return successfully.
Examples: COMND JSYS Page 199
.echo: comment | Parse rest of "echo" command. |
%cmNoi <line> ; Issue noise word.
%pret ; Fail-return on error.
%cmTxt <line to be echoed,> ; Get a text line.
%pret ; Fail-return on error.
move t1, [point 7, buf] ; Get the text line into buf
%cmGab t1 ; from the atom buffer.
%cmCfm ; Get confirmation.
%pret ; Fail-return on error,
retskp ; otherwise return successfully.
$echo: comment | Execute the "echo" command. |
%print <%s>,<[point 7, buf]> ; Print the text line.
retskp
Examples: COMND JSYS Page 200
.exit: comment | Parse the rest of the "exit" command. |
%cmNoi <from Foo> ; Issue guide words.
%pret ; Fail-return on error.
%cmCfm ; Get confirmation.
%pret ; Fail-return on error,
retskp ; otherwise, return successfully.
$exit: comment | Execute the "exit" command. |
%trnOn xitFlg ; Just turn on the exit flag,
retskp ; and return successfully.
Examples: COMND JSYS Page 201
.help: comment | Parse the rest of the "help" command. |
%cmNoi <about> ; Issue noise words.
%pret ; Fail-return on error.
%cmKey hlpTab, <command,>, help ; Get command to help with.
%pret ; Fail-return on error.
hrrz p1, (t2) ; Get address of help text.
%cmCfm ; Get confirmation.
%pret ; Fail-return on error,
retskp ; otherwise return successfully.
$help: comment | Execute the "help" command. |
%print <%s>,<[point 7, (p1)]> ; Print the help text.
retskp
hlpTab: %table ; Table of help commands.
%key <directory>, $$dir
%key <echo>, $$echo
%key <exit>, $$exit
%key <help>, $$help
%key <information>, $$info
%tbEnd
$$dir: asciz |
Type "directory xxx", where "xxx" is a file specification. If there
is a file that matches that specification, its name will be typed.
If the specification is "wild", i.e. contains "*" or "%" characters,
the names of all files that match will be typed.
|
$$echo: asciz |
The 'echo' command types back what you type as its argument, e.g.
"echo xxx" types "xxx" at your terminal.
|
$$exit: asciz |
The 'exit' command halts the program. You can continue by
typing the Exec 'continue' command.
|
$$help: asciz |
The 'help' command gives information about the various Foo commands.
Type "help xxx" where 'xxx' is any Foo command. Type "help ?" to see
what commands have help available.
|
$$info: asciz |
The 'information' command prints information about various things.
Type 'information ?' to see what things are available.
|
Examples: COMND JSYS Page 202
.info: comment | Parse rest of "information" command. |
%cmNoi <about> ; Noise word.
%pret ; Fail-return on error.
%cmKey <infTab> ; Get keyword.
%pret ; Fail-return on error.
hrrz p1, (t2) ; Get info routine index.
%cmCfm ; Get confirmation,
%pret ; Fail-return on error,
retskp ; otherwise return successfully.
infTab: %table ; Info command table.
%key <connected-directory>, 0
%key <date-and-time>, 1
%key <logged-in-directory>, 2
%tbEnd
$info: comment | Execute the "information" command. |
xct [ %print < You are connected to %c> ; Print the quantity
%print < %n> ; given by the
%print < You are logged in as %u> ; "case index"
](p1) ; in p1.
retskp ; Return successfully
Examples: COMND JSYS Page 203
subttl Impure Data Section
%impure ; Declare it impure for sharability.
; GTJFN block for %cmFil. Some of the words are filled in by COMND,
; so this block must be in the impure section.
gjfBlk: GJ%OLD!GJ%IFG!GJ%FLG!GJ%ACC!.GJALL ; Flag bits,,generation number.
.PRIIN,,.PRIOU ; Input,,output JFNs.
0 ; Default device (none).
0 ; Default directory (none).
point 7, [asciz/*/] ; Default Filename (wild).
point 7, [asciz/*/] ; Default filetype (wild).
0 ; Default protection (none).
0 ; Default account (none).
0 ; JFN to assign (none).
0 ; No extended block.
block ^d10 ; Other args not used either.
buf: block ^d500/5+1 ; Buffer for "echo" string.
^L
end <evLen,,entVec> ; Address,,length of entry vector.
; - EMACS editing modes -
; local modes:
; mode:Macro
; comment start:;
; comment rounding:+1
; end:
Assembly Language Guide Page 204
Index
%clear 152
%cmRes 141
%erMsg 84, 153
%jsErr 74, 153
%print 136
%prSkp 137
%setEnv 151
%setUp 141, 151
.EXE 97, 174
.MAC 34, 172
.PRIIN 75, 78, 79, 83, 88
.PRIOU 75, 78, 79, 83, 88
.REL 34, 51, 97, 172, 177
.REQUIRE 57, 124
.RTJST 126
.UNV 34, 57
Accumulator 3, 8, 9, 12, 15, 73, 132, 149, 159, 165, 167, 174
Accumulators, Restoring 167
Accumulators, Saving 11, 167
ACVAR 134
ADD 19, 28
Address 4, 8, 62, 159, 174, 175
Address Space 184
ADJBP 25
ADJSP 12
AND 26, 36, 77
ANDCA 26
ANDCB 26
ANDCM 26
AOBJ 15
AOJ 17, 28, 67
AOS 16, 28
Appending to a File 79, 80
Argument 37, 63, 64, 67, 70, 73, 163, 168
Arithmetic 19, 20, 21
Arithmetic Expression 45
Arithmetic Shift 23
AROV 27
Array 15, 37, 47
ASCII 35, 36, 47, 70, 75, 101, 174, 177
ASCIZ 48, 76, 79, 101
ASH 22, 23, 27
ASHC 23, 27
Assembler 7, 34, 97
Assembly Language 2, 159
ASUBR 134
BIN 83
Binary 7, 35, 38
Bit 4, 8, 19, 26, 40, 75, 124, 174
BLOCK 48
Assembly Language Guide Page 205
BLT 10, 11
Boolean Logic 26
BOUT 83
Breakpoint 179, 186
Byte 4, 24, 48, 58, 75, 93, 174
Byte Pointer 24, 25, 55, 75, 126, 146, 165
CAI 18
CALL 131, 165
CALLRET 131, 166
CAM 18
Case Statement 32
Character 4
CLOSF 78, 81
Closing a File 81
Command Initialization 114, 140
Comment 36, 49, 59, 61, 64, 105, 159, 160, 168
COMND 85, 102, 136, 140, 144, 149, 154
COMPILE 172
Concatenation 37, 67
Conditional Assembly 164
Confirmation 79, 114
Continuation 35, 37, 105
CPU 4
CUrel 144
CUsym 104
CUUOs 136
Data Structure 128, 165
DCK 28, 29
DDT 58, 160, 172, 174
DDT Type-in 176
DDT Type-out 174, 182
Debug 172
DEC 3, 50
Decimal 34, 36, 38, 177
DECR 129
DECsystem-10 33
DECSYSTEM-20 3
Default Argument 64, 67
DEFINE 50, 63
DEFSTR 128, 165
Destination 12, 75
Device 78, 114, 138
DFAD 22
DFDV 22, 29
DFMP 22
DFSB 22
Difference 36
Directory 4, 78, 114, 138
Disk 3
DIV 20, 29
Divide 19, 20, 29
DMOVE 20
DMOVN 28
DMUL 27
Double Precision 20, 21, 22
Double Word 20, 23
Assembly Language Guide Page 206
DPB 24
Dummy Argument 63, 64
Effective Address 8, 175
EMACS 172
END 50, 54, 55
End of File 81, 82, 83, 85, 93, 96
ENTRY 45, 51
EQV 26
ERCAL 73, 137
ERJMP 73, 137
Error Message 73, 138, 153
Errors 71
Excess 200 21
EXCH 10
Exec 3, 97, 172, 184, 185, 187
Execute 172
EXP 51, 54
Exponent 21, 22, 23, 39
Expression 10, 37, 40, 45, 60, 70, 178
EXTERN 51
FAD 21
Fail 2, 159
Failure Return 73, 157
FDV 21, 29
FDVR 29
Field 77, 113, 126
File 4, 75, 77, 78, 93
File Name 78
File Pointer 93
File Type 78
FIX 22, 28
Fixed Point Arithmetic 19, 20
FIXR 23, 28
Flag 157, 165
FLD 77, 126
FLIN 92
Floating Point 21, 23, 36, 39, 92, 114, 138, 177
Floating Point Arithmetic 21
Floating Point Overflow 28
Floating Point Zero 21
FLOUT 92
FLTR 22, 23
FMP 21
Fork 97, 184
Fortran 39
FOV 28, 29
Fraction 21, 39
FSB 21
FSC 22
Generation Number 78, 79
GetOK 144
Global 44
GTJFN 78, 140
GTSTS 82
Guide Word 112
Assembly Language Guide Page 207
Halfword 12, 36, 46, 59, 76, 165, 174
HALTF 100
Handle 99
Help Message 105, 116, 144
HRROI 76
IBP 25
IDDT 184
IDIV 19, 29
IDPB 25, 55
IFx 51
ILDB 25, 55
IMUL 19, 28
INCR 129
Indefinite Repetition 69
Indentation 160
Index 8, 15, 37, 62, 159, 174
Indirect 8, 29, 30, 32, 37, 62, 159, 174
Indirect File 105, 173
Input File 79, 112
Input/Output 4, 81, 82, 84
Instruction 4, 7, 165
Instruction Modifier 9, 27
Integer 22, 23, 38, 90, 91
Integer Arithmetic 19, 20
INTERN 52
INTERNAL 36, 37, 44
IOR 26
IOWD 12, 53
IPB 55
IRP 53, 58, 69
IRPC 54, 58, 69
JAND 130
JFCL 32, 63
JFFO 33
JFN 78, 99
JFNS 79, 138
JFOV 63
JNAND 130
JNOR 130
JOR 130
JRA 30
JRST 31, 132
JSA 30
JSERR 135, 153
JSHLT 135
JSP 27, 30
JSR 27, 30
JSYS 7, 73
JSYS Error Recovery 74
JUMP 15
JXm 127
KA10 2, 7, 20, 21, 25
Keyword 111, 141, 154
KI10 2, 7, 11, 25
Assembly Language Guide Page 208
KL10 2, 7, 11, 25, 73
KS10 2, 7
Label 36, 43, 59, 159
LDB 24
Link 34, 51, 57, 124, 172
Linked List 130
LIT 40, 54, 55
Literal 10, 37, 40, 54, 136, 169
LOAD 129, 165, 172
Load-Class Commands 172
LOC 62
Local 44
Local Label 153
Location Counter 36, 41, 62
Logical Complement 36
Logical Expression 18, 45
Logical Shift 23
Logical Testing 26
Loop 15
Lowercase 35
LSH 23
LSHC 23
Macro Expansion 65
Macro-20 2, 34, 73, 159
Macros 35, 36, 37, 50, 59, 61, 63, 77, 124, 163
MACSYM 77, 86, 104, 124, 149, 165
MAKLIB 51
Mask 26, 77, 124, 126, 127
MASKB 127
Memory 3, 9, 12, 62, 97
Midas 2, 159
MOD. 135
Module 167
Modulo 135
Monitor 3, 7
Monitor Call 2, 7, 43, 73
MONSYM 75, 77, 149
MOVE 9, 20
MOVM 28
MOVN 28
MOVX 76, 127
MSKSTR 128, 165
MUL 20, 27
Multiply 19
NIN 90, 92
NOUT 77, 91, 92, 138
Number 111, 116, 152, 170
Number Conversion 22, 90
OCT 54
Octal 34, 36, 38, 138, 177
Opcode 59, 60, 62, 73, 159, 162, 174, 178
OPDEF 55, 60, 61, 165
OPENF 78, 80
Opening a File 80
Assembly Language Guide Page 209
Operand 59, 60
Operating System 3, 7
Operator 60
OPSTR 130
OPSTRM 130
OR 36, 77, 78
ORCA 26
ORCB 26
Output File 79, 112
Overflow 11, 12, 19, 20, 22, 23, 27, 31
Page 93, 145
Pagination of Programs 162
Pass 34, 61, 72
Patch 182
PBIN 83
PBOUT 83
PC 8, 19, 27, 31, 32, 125, 179, 188
PDP-10 3, 7, 33
PDP-6 3, 7, 21, 25
Phase 51, 72
POINT 25, 55
POINTR 126
POP 11, 12, 165, 171
POPJ 165
POS 126
PRGEND 55, 58
PRINTX 56
Process 97
Product 36
Program 97
Program Control 15, 30, 42, 73, 162, 170
Program Counter 27
Program Version Number 152
Prompt 88, 105, 140
Pseudo-op 47, 60
PSOUT 86
PURGE 56
PUSH 11, 12, 133, 165, 171
PUSHJ 27, 31, 133, 165
Quadruple Word 20
Quotient 36
R 166
Radix 38, 56, 175
RADIX50 174
Random-access Input/Output 93
RDTTY 85, 87, 90
Recognition 78, 79, 105
Reentrant 30, 170
Register 3, 9
RELOC 62
Remainder 19
REPEAT 56, 61
Rescan 147
RESET 99
RET 131, 133
Assembly Language Guide Page 210
RETSKP 131, 133
Return 165
RFORK 100
RFPTR 95
RIN 96
ROT 23
Rotate 23
ROTC 24
Round 23
ROUT 96
RSKP 166
Save 187
Scale 22
SEARCH 57, 124, 149
Sequential Input/Output 82, 94
SETA 26
SETCA 26
SETCM 26
SETCMP 129
SETM 26
SETO 26
SETONE 129
SETZ 26
SETZRO 129
SFPTR 94, 95
Sharability 170
Shift 23, 37, 40, 126
Sign 21, 38, 39, 91
SIN 84, 147
SIXBIT 36, 37, 57, 70, 138, 174, 177
SKIP 16
Skip Return 31, 73, 166
Skipping Instruction 160
SOJ 17, 28
SOS 16, 28
Source 12, 75
Source/Destination Designator 75
SOUT 85
Stack 11, 12, 31, 132, 151, 165, 171
Standards 159
Statement 34, 59, 61, 159
STCMP 101
STKVAR 132, 171
STOPI 58, 69, 70
STOR 165
String 75, 115
String Input/Output 84, 86
Style 159
SUB 19, 28
Subroutine 45, 73, 142, 165, 168
SUBTTL 58, 164
Sum 36
Swap 37
Switch 112
Symbol 37, 42, 75, 124, 150, 170, 177
Symbol Table 42, 44, 55, 57, 58, 61, 177
Symbol, Created 67, 68
Assembly Language Guide Page 211
Terminal 75, 78, 87, 99
TEST Instructions 26
TEXTI 85
Timesharing 3
TITLE 58, 164, 177
TMSG 134, 152
Token 115
Tops-10 34, 57, 58
Tops-20 3, 73
TRVAR 133, 171
Two's Complement 19, 21, 36, 38
TXmn 82, 127, 165
Unconditional Jump 31
UNIVERSAL 57
UUO 7, 144, 150
WID 126
Word 4, 7, 19, 21, 38, 40, 175
XCT 32
XOR 26
XWD 59
Z 59
Assembly Language Guide Page i
Table of Contents
1. Introduction 2
1.1. Basic Concepts 3
1.1.1. Terminology 3
1.1.2. Machine Organization 3
1.1.3. Instructions and Addressing Modes 4
1.1.4. Internal Representation of Numbers 4
1.1.4.1. Binary Numbers 4
1.1.4.2. Two's Complement Representation 5
1.1.4.3. Integers 5
1.1.4.4. Floating Point Numbers 5
1.1.5. Arithmetic 5
1.1.5.1. Integer Arithmetic 5
1.1.5.2. Floating Point Arithmetic 5
1.1.6. Logical Operations 5
1.1.7. Character String Manipulation 5
1.1.8. Elementary Data Structures 5
1.1.8.1. Tables (Arrays) and Indexing 5
1.1.8.2. Stacks 6
2. The PDP-10/DECSYSTEM-20 Instruction Set 7
2.1. Introduction 7
2.2. Full Word Instructions 9
2.2.1. MOVE 9
2.2.2. EXCH - Exchange 10
2.2.3. BLT - Block Transfer 10
2.2.4. Programming Examples Using Fullword Instructions 10
2.3. Stack Instructions 11
2.3.1. PUSH - Push on Stack 11
2.3.2. POP - Pop Stack 12
2.3.3. ADJSP - Adjust Stack Pointer 12
2.4. Halfword Instructions 12
2.4.1. HR - Halfword Right 13
2.4.2. HL Halfword Left 14
2.5. Arithmetic Testing 15
2.5.1. AOBJ - Add One to Both Halves and Jump 15
2.5.2. JUMP 15
2.5.3. SKIP 16
2.5.4. AOS - Add One and Skip 16
2.5.5. SOS - Subtract One and Skip 16
2.5.6. AOJ - Add One and Jump 17
2.5.7. SOJ - Subtract One and Jump 17
2.5.8. CAM - Compare Accumulator to Memory 18
2.5.9. CAI - Compare Accumulator Immediate 18
2.6. Fixed Point Arithmetic 19
2.6.1. ADD 19
2.6.2. SUB - Subtract 19
2.6.3. IMUL - Single-Word Multiply 19
2.6.4. IDIV - Single-Word Divide 19
2.6.5. MUL - Multiply 20
2.6.6. DIV - Divide 20
Assembly Language Guide Page ii
2.7. Double Word Move Instructions (KI10 and KL10) 20
2.8. Double Precision Integer Arithmetic (KL10 only) 20
2.9. Floating Point Arithmetic 21
2.10. Other Floating Point Instructions 22
2.10.1. FSC - Floating Scale 22
2.10.2. FIX - Convert Floating Point to Integer 22
2.10.3. FIXR - Fix and Round 23
2.10.4. FLTR - Float and Round 23
2.11. Shift Instructions 23
2.12. Byte Instructions 24
2.12.1. LDB - Load Byte 24
2.12.2. DPB - Deposit Byte 24
2.12.3. IBP - Increment Byte Pointer 25
2.12.4. ILDB - Increment and Load Byte 25
2.12.5. IDPB - Increment and Deposit Byte 25
2.12.6. ADJBP - Adjust Byte Pointer 25
2.12.7. POINT - Construct a Byte Pointer 25
2.13. Logical Testing and Modification 26
2.14. Boolean Logic 26
2.15. PC Format 27
2.16. Program Control 30
2.16.1. JSR - Jump to Subroutine 30
2.16.2. JSP - Jump & Save PC 30
2.16.3. JSA - Jump and Save Accumulator 30
2.16.4. JRA - Jump and Restore Accumulator 30
2.16.5. PUSHJ - Push on stack and Jump 31
2.16.6. POPJ - Pop stack and Jump 31
2.16.7. Programming Hints Using PUSHJ and POPJ 31
2.16.8. JRST - Jump and Restore 31
2.16.9. JFCL - Jump on Flag and Clear 32
2.16.10. XCT - Execute 32
2.16.11. JFFO - Jump if Find First One 33
2.17. References 33
3. The DECSYSTEM-20 Macro Assembler 34
3.1. Introduction 34
3.2. Elements of Macro 35
3.2.1. Special Characters 35
3.2.2. Numbers 38
3.2.2.1. Integers 38
3.2.2.2. Radix 38
3.2.2.3. Floating-point Decimal Numbers 39
3.2.2.4. Binary Shifting 40
3.2.2.5. Underscore Shifting 40
3.2.3. Literals 40
3.2.4. Symbols 42
3.2.4.1. Selecting Valid Symbols 43
3.2.4.2. Defining Symbols 43
3.2.4.3. Symbol-table Search Order 44
3.2.4.4. Symbol Attributes 44
3.2.5. Expressions 45
3.2.5.1. Arithmetic Expressions 45
3.2.5.2. Logical Expressions 45
3.2.5.3. Evaluating Expressions 46
Assembly Language Guide Page iii
3.3. Pseudo-ops 47
3.3.1. ARRAY 47
3.3.2. ASCII 47
3.3.3. ASCIZ 48
3.3.4. BLOCK 48
3.3.5. BYTE 48
3.3.6. COMMENT 49
3.3.7. DEC 50
3.3.8. DEFINE 50
3.3.9. END 50
3.3.10. ENTRY 51
3.3.11. EXP 51
3.3.12. EXTERN 51
3.3.13. IFx Group 51
3.3.14. INTERN 52
3.3.15. IOWD 53
3.3.16. IRP 53
3.3.17. IRPC 54
3.3.18. LIT 54
3.3.19. OCT 54
3.3.20. OPDEF 55
3.3.21. POINT 55
3.3.22. PRGEND 55
3.3.23. PRINTX 56
3.3.24. PURGE 56
3.3.25. RADIX 56
3.3.26. REPEAT 56
3.3.27. .REQUIRE 57
3.3.28. SEARCH 57
3.3.29. SIXBIT 57
3.3.30. STOPI 58
3.3.31. SUBTTL 58
3.3.32. TITLE 58
3.3.33. XWD 59
3.3.34. Z 59
3.4. Macro Statements and Statement Processing 59
3.4.1. Labels 59
3.4.2. Operators 60
3.4.3. Operands 60
3.4.4. Comments 61
3.4.5. Statement Processing 61
3.4.6. Assigning Addresses 62
3.4.7. Machine Instruction Mnemonics and Formats 62
3.4.8. Mnemonics with Implicit Accumulators 63
3.5. Using Macros 63
3.5.1. Defining Macros 63
3.5.2. Invoking Macros 64
3.5.3. Macro Invocation Format 65
3.5.4. Quoting Characters in Macro Arguments 66
3.5.5. Nesting Macro Definitions 67
3.5.6. Concatenating Macro Arguments 67
3.5.7. Default Arguments and Created Symbols 67
3.5.7.1. Specifying Default Values 68
3.5.7.2. Created Symbols 68
3.5.8. Indefinite Repetition 69
3.5.9. Alternate Interpretations of Characters Passed to Macros 70
Assembly Language Guide Page iv
3.6. Errors and Messages 71
3.6.1. Informational Messages 71
3.6.2. Single-Character Error Codes 72
3.6.3. MCRxxx Messages 72
4. Introduction to Tops-20 Monitor Calls 73
4.1. Introduction 73
4.2. General Information 73
4.3. Using Mnemonic Symbols 75
4.4. Source/Destination Designators 75
4.5. Setting up a JSYS Invocation 76
4.6. JSYS's to Open and Close Files 77
4.6.1. GTJFN (JSYS 20) - Get Job File Number (short form) 78
4.6.2. OPENF (JSYS 21) - Open a File 80
4.6.3. CLOSF (JSYS 22) - Close a File. 81
4.7. File i/o JSYS's 81
4.7.1. GTSTS (JSYS 24) - Get file Status 82
4.7.2. Sequential Byte i/o 82
4.7.2.1. BIN (JSYS 50) - Byte In 83
4.7.2.2. PBIN (JSYS 73) - Primary Byte In 83
4.7.2.3. BOUT (JSYS 51) - Byte Out 83
4.7.2.4. PBOUT (JSYS 74) - Primary Byte Out 83
4.7.2.5. Example of Byte i/o 84
4.7.3. String-oriented i/o 84
4.7.3.1. SIN (JSYS 52) - String In 84
4.7.3.2. SOUT (JSYS 53) - String Out 85
4.7.3.3. PSOUT (JSYS 76) - Primary String Out 86
4.7.3.4. Example of String I/O 86
4.7.3.5. RDTTY (JSYS 523) - Read string interactively from TTY 87
4.7.3.6. RDTTY Example 89
4.7.4. Number conversion JSYS's 90
4.7.4.1. NIN (JSYS 225) - Number In 90
4.7.4.2. NOUT (JSYS 224) - Number Out 91
4.7.4.3. NIN/NOUT Example 92
4.7.5. Random-access i/o 93
4.7.5.1. RFPTR (JSYS 43) - Read File Pointer 95
4.7.5.2. SFPTR (JSYS 27) - Set File Pointer 95
4.7.5.3. RIN (JSYS 54) - Random byte In 96
4.7.5.4. ROUT (JSYS 55) - Random byte Out 96
4.8. Fork-Handling JSYS's 97
4.8.1. What's in a Fork? 97
4.8.2. The Fork Environment 99
4.8.3. Basic Fork-Handling JSYS's 99
4.8.3.1. RESET (JSYS 147): Reset the current fork 99
4.8.3.2. HALTF (JSYS 170) - Halt the current fork 100
4.8.3.3. Examples of RESET and HALTF 100
4.9. Miscellaneous JSYS's 100
4.9.1. STCMP (JSYS 540) - STring CoMParison 101
5. The COMND JSYS - JSYS 544 102
5.1. Informal Introduction 102
Assembly Language Guide Page v
5.2. General Information 104
5.3. Bits Supplied in State Block on COMND Call 109
5.4. Function Descriptor Block 110
5.4.1. Words .CMFNP and .CMDAT of the FDB 111
5.4.2. Word .CMHLP of the FDB 117
5.4.3. Default Help Messages 118
5.4.4. Word .CMDEF of the FDB 119
5.4.5. Word .CMBRK of the FDB 119
5.5. Bits Returned on COMND Call 120
5.6. Macros 121
5.6.1. FLDDB.(TYP,FLGS,DATA,HLPM,DEFM,LST) 121
5.6.2. FLDBK.(TYP,FLGS,DATA,HLPM,DEFM,BRKADR,LST) 122
5.6.3. BRMSK.(INI0,INI1,INI2,INI3,ALLOW,DISALLOW) 122
5.6.4. FLDBK. 122
5.7. Errors 123
6. MACSYM System Macros 124
6.1. Introduction 124
6.2. Definitions 124
6.2.1. Standard Program Version 125
6.2.2. Miscellaneous Constants (Symbols) 125
6.2.3. Control Characters (Symbols) 125
6.2.4. PC Flags (Mask Symbols) 125
6.2.5. Macros to Manipulate Field Masks 126
6.2.5.1. WID(MASK) 126
6.2.5.2. POS(MASK) 126
6.2.5.3. POINTR(LOC,MASK) 126
6.2.5.4. FLD(VAL,MASK) 126
6.2.5.5. .RTJST(VAL,MASK) 126
6.2.5.6. MASKB(LBIT,RBIT) 127
6.2.6. Instructions Using Field Masks (Macros) 127
6.2.6.1. MOVX AC,MASK 127
6.2.6.2. TXmn AC,MASK 127
6.2.6.3. IORX AC,MASK; ANDX AC,MASK; XORX AC,MASK 127
6.2.6.4. JXm AC,MASK,ADDRESS 127
6.2.7. Data Structure Facility (Macros) 128
6.2.7.1. DEFSTR and MSKSTR 128
6.2.8. Subroutine Conventions (Macros/opDefs) 131
6.2.8.1. CALL address 131
6.2.8.2. RET 131
6.2.8.3. RETSKP 131
6.2.8.4. CALLRET address 131
6.2.8.5. AC Conventions 132
6.2.9. Named Variable Facilities (Macros and Runtime Code) 132
6.2.9.1. STKVAR namelist 132
6.2.9.2. TRVAR namelist 133
6.2.9.3. ASUBR namelist 134
6.2.9.4. ACVAR namelist 134
6.2.10. Miscellaneous 134
6.2.10.1. TMSG string 134
6.2.10.2. JSERR 135
6.2.10.3. JSHLT 135
6.2.10.4. MOD.(DEND,DSOR) 135
Assembly Language Guide Page vi
7. Columbia Macros and Packages 136
7.1. Utility UUO Package for Macro-20 136
7.1.1. Formatted Printing Package 136
7.1.2. %prPush and %prPop 139
7.1.3. COMND-Jsys-Made-Easy Package 140
7.1.3.1. %cmRes 141
7.1.3.2. %cmKey (keytab, help, default, flags) 141
7.1.3.3. %cmgab bp 142
7.1.3.4. %comnd flddb 142
7.1.3.5. %cmgfg flag 142
7.2. CUrel Utility Subroutines 144
7.2.1. Helper 144
7.2.2. GetOK 144
7.2.3. Gfcpg 145
7.2.4. pagMgr 145
7.2.5. Subbp 146
7.2.6. Rescan 147
7.3. CUsym MACSYM Augmentation Macros 149
7.3.1. Accumulator Support 149
7.3.2. %DefAC 150
7.3.3. Useful Symbols 150
7.3.4. UUO Package OPDEFs and Interface Symbols 150
7.3.5. Setup Environment Macros 151
7.3.5.1. %setEnv 151
7.3.5.2. %setUp 151
7.3.6. Storage Declaration Macros 151
7.3.7. General-Purpose Macros 151
7.3.7.1. %Stack 151
7.3.7.2. %Version 152
7.3.7.3. %Clear 152
7.3.8. Macros Used for Common Primary I/O 152
7.3.8.1. %typeCR(string) 152
7.3.8.2. %crType(string) 152
7.3.8.3. %typNum(num,cols,rdx) 152
7.3.8.4. %crlf 153
7.3.8.5. %tab 153
7.3.9. JSYS Support Macros 153
7.3.9.1. %jsErr 153
7.3.9.2. %erMsg 153
7.3.10. Local Label Support Macros 153
7.3.10.1. %Cat(a,b) 154
7.3.11. COMND JSYS Support Macros 154
7.3.11.1. %Ptr(string) 154
7.3.11.2. %table and %tbEnd 154
7.3.11.3. %key(name, data, flags) 154
7.3.11.4. %Flddb (typ, flgs, data, hlpm, defm, lst) 155
7.3.11.5. %Handlr(p,e), %PrsAdr, %EvlAdr 155
7.3.11.6. %CMxxx Macros to Invoke .CMxxx COMND Functions 155
7.3.12. Macros to Handle COMND Errors 156
7.3.12.1. %pret 156
7.3.12.2. %errep errlab, replab 156
7.3.12.3. %merrep errlab, replab 157
7.3.12.4. Macros for Fail-Return from Parsing Routines 157
7.3.12.5. %jerrep errlab, replab, othrlb 157
7.3.12.6. %jmerrep errlab, replab, othrlb 157
7.3.13. Flag-Handling Macros 157
7.3.13.1. %Flags(aFlg,bFlg,cFlg,...) 157
Assembly Language Guide Page vii
7.3.13.2. %trnOn & %trnOff 157
7.3.13.3. %TrOnS & %TrOfS 158
7.3.13.4. %SkpOn & %SkpOff 158
7.3.13.5. %AnyOn & %AnyOff 158
7.3.14. CUuos (CUCCA Utility UUOs) Interface 158
7.3.14.1. %print, %prSkp 158
8. Macro-20 Programming Standards and Conventions 159
8.1. Introduction 159
8.2. Statements 159
8.3. Comments 160
8.4. Pagination of Source Programs 162
8.5. Other Assembler Functions 163
8.6. Instruction Mnemonics 165
8.7. Variables and Structures 165
8.8. Subroutines 165
8.9. AC Definitions 167
8.10. Subroutine Documentation 168
8.11. Multi-line Literals 169
8.12. Flow of Control - Branch Conventions 170
8.13. Numbers 170
8.14. Sharability 170
8.15. Living in an Imperfect World 171
8.15.1. AC Mnemonics 171
8.15.2. Stack Handling 171
9. How to Write, Assemble, and Run Programs 172
10. Interactive Debugging of Assembly Language Programs 174
10.1. Typeout Modes 174
10.1.1. Address Mode Typeout 175
10.1.2. Radix Typeout 175
10.1.3. Prevailing vs Temporary Modes 175
10.2. Storage Words 175
10.2.1. Related Storage Words 176
10.2.2. Retyping In Modes Other than the Prevailing Mode 176
10.3. Typing In 176
10.4. Symbols 177
10.4.1. Special DDT Symbols 178
10.4.2. Arithmetic Operators 178
10.4.3. Field Delimiters In Symbolic Type-ins 178
10.5. Breakpoints 179
10.5.1. Proceeding from a Breakpoint 180
10.5.2. Single Stepping 180
10.5.3. Conditional Breakpoints 180
10.5.4. Starting the Program 181
10.6. Searching 181
10.6.1. Zeroing Memory 181
10.7. Special Characters 182
10.8. Miscellaneous DDT Commands 182
10.8.1. Immediate Mode Instruction Execution 182
10.8.2. Execute Indirect Command File 182
10.8.3. Patch 182
Assembly Language Guide Page viii
10.9. Sample DDT Session 183
10.10. IDDT (Invisible DDT) 184
10.10.1. Using IDDT 184
10.10.2. EXEC-like Features 185
10.10.3. View Cell 186
10.10.4. Breakpoints 186
10.10.5. Fork Handles 186
10.10.6. Escape character 186
10.10.7. RUBOUT and Type-in Editing 186
10.10.8. Interface with the Exec 187
10.10.9. Saving a Core Image 187
10.10.10. Single Instruction Executes 187
10.10.11. Search Commands 187
10.10.12. Single Stepping 188
10.10.13. Other Commands 188
11. Programming Examples 189
11.1. Binary Search Program 189
11.2. COMND Example 194
Index 204