assembler-guide.txt

                     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