Digital PDFs

DEC-9A-GUAB-D

1968

146 pages

Original

3.5MB

Document:	PDP-9 UTILITY PROGRAMS ADVANCED SOFTWARE SYSTEM Programmer’'s Reference Manual
Order Number:	DEC-9A-GUAB-D
Revision:
Pages:	146
Original Filename:	http://bitsavers.org/pdf/dec/pdp9/DEC-9A-GUAB-D_UTILITIES.pdf

OCR Text

PDP-8
UTILITY PROGRAMS
ADVANCED SOFTWARE SYSTEM
Programmer's Reference

Order No. DEC-9A-GUAB-D from Program Library, Maynard, MeIss.

Manual

Price $4.50

Direct comments concerning this manual to Software Quality Control, Maynard, Mass.

DIGITAL EQUIPMENT CORPORATION. MAYNARD. I\/IASSACHUSETTS

CONTENTS
DDT -9
EDITOR-9
PIP-9
LIN KING LOADER
7-TO-9 CONVERTER

iii

To The Reader
Notification of changes and revisions to this document, to the software
described, and of new software products available from the DEC Program Library, is
currently published in DECUSCOPE, the magazine of the Digital Equipment Computer Userls Society (DECUS). This information appears in a section of DECUSCOPE
called II DEC Library News. 1\
Revised software products and documents are shipped only after the Program
Library rece ives a spec ifi c request from a user.
DECUSCOPE is distributed periodically to both DECUS members and to
non-members who request it. If you are not now receiving this information, you are
urged to return the request form below so that your name will be placed on the mailing list.

• • • • • • • • • • • • • • • • • ~-' -..!-eLl .....6£.1 e..a,.- ~ ..... _

To:

• .&,If ~ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ~ . . . . . . . . . . . . . . . . . . . ...,

.-r.-r.T'.r••••. :-: .--:-."":'. -:-;::.~. ~:; ••

DECUS Office,
Digital Equipment Corporation,
Maynard, Mass. 01754

Please send DECUS installation membership information.

Please send DECUS individual membership information.

Please add my name to the DECUSCOPE non-member mailing list.
Name ______________________________
Company ____________________________
Address ____________________________

(Zip Code)

t", _

••••••••••••••

'. . . . . . . . . . . . . . . . . .., 'I • • • • • • • • • • • • • • • • • • • • - • • • • • - . . . . . . . . . . . . . . .- . . . . . . . . . . . . . . . . . . . . e·. . . . . . . . ,. . . . . . . . . . . . . . . . . . . . . . . . . II •

••••••••••••••••••••

it • •

DDT-9

DDT-9
CONTENTS
Section
INTRODUCTION .••••. " .•••••••••.•••••••.•••••••••••..••••••••••••

1-1

1.1

General Information

1.2

Terminology Used in i'his Manual ••••..•••••••••••••••••.•••••••••.

1-1

DEBUGGING WITH DDT" ••••••••••••••••••.••••••••••••••••••••••••.

2-1

2. 1

Loading the Program n' • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • •

2-1

2.2

Using the Breakpoints •••••••••.•••••••••••.•••••••••••.•.•••.••••

2-1

2.3

Examination and Modification .•••..•••.•••••••••••••••••••••••••••

2-3

2.4

Type-Out Modes ... () ........................................... .

2-4

2.4.1

Address Modes .

••••••••••••••••••••••••••••••••••••••••••••

1-1

2-5

2.5

Starting and Restarting .••••••••••••.•.••••••••••••.••••••••••••••

2-6

2.6

Search i n9 Operations ........................................... .

2-6

2.7

Spec ial Locations Used by DDT -9 .••••••••••••••••••••••••••••..•••

2-7

2.8

Symbol Definitions .

2-8

2.9

Patch Fi Ie Output ..

2.10

Patch File Input ....) ..•....................•....................

2-8

2. 11

Co-Resident Subroutines .•.•.••.•••••••.•••••••.•••••••••.••••.•••

2-9

2.12

Indirect Address References •••••••••••••••••••••.••••••••••••••••.

2-9

2.13

Miscellaneous Features •••••.•••••••••••••••••••••••.•.••••.•.••••

2-9

••••••••••••••••••••••••••••••••••••••••••••

2-8

APPENDIXES
Appendix
SUMMARY OF COMMANDS .'........................................

A1-1

MNEMONIC INSTRUCTION TABLE .••.•.••••••••••••••••••••••••••••••

A2-1

FORMAT OF PATCH FILE •••.••••••••••••••••.•••.••••••••••.•••.••••

A3-1

iii

DDT-9
SECTION 1
INTRODUCTION
1.1

GENERAL INFORMATION
DDT -9 (the Dynamic Debugging Technique program for the PDP-9) provides convenient

on-line debugging assistance for MACRO-9 and FORTRAN programmers.

By typing simple commands

on the Teletype keyboard, programmers may make corrections and additions in symbolic code (or octa!),
suspend execution of the program at any predetermined point during the debugging run, and examine
the status of any memory word in the program. The user's program is started and stopped by commands
to DDT -9.

Under normal conditions, the user is always able to stop a "runaway" program.
DDT -9 operates as part of the PDP-9 Advanced Software System. It is loaded into memory

(the top 1600

positions) along with the Linking Loader which, upon command, loads the user's pro10
gram (including the symbol table and any sub-programs) and the needed I/O handlers, FORTRAN Object Time System routines and library subroutines. DDT -9 disables the automatic priority interrupt immediately upon receiving control from the Monitor.
All user communication with DDT -9 is via the Teletype, which may be any model included
in standard PD P- 9 confi gurat ions.
DDT -9 interprets all numeric input, and outputs all numeric data in octal radix. The digits
8 and 9 are treated as alphabetic characters.
1 .2

TERMINOLOGY USED IN THIS MANUAL

A non-printing character used for text representation of the carriage return key.
A non-printing character used for text representation of the Iine feed key.
A text representation of the control key, always used in conjunction with another key.
It is also the printing character, up arrow.

The non-printing character obtained by holding the control key while striking the T.
The term C (R) represents the content of storage word R.
In examples, underlining designates information typed by DDT -9.

Elements are to be added.
Elements are to be subtracted.

'-' (Space) field delimiter, as between operation code and address.
A Transfer Vector is a word which contains the 15-bit address of another word. Bits 0-2 are
meaningless and may be used for codes. In the PDP-9, transfer vectors are used in indirect addressing,
by the Linking Loader for subroutine calls, and are required In addressing to another memory bank.
1-1

DDT-9

SECTION 2
DEBUGGING WITH DDT
2. 1

LOADING THE PROGRAM
In an I/O Monitor (paper tape) environment, the Linking Loader forms an integral part of

the DDT tape.
In the Keyboard Monitor, the teletype command DDT (DDTNS) calls the Linking Loader as
well as DDT.

(DDTNS is used to prevent loading of the user symbol table to save memory.)

The first response from the teletype, in either system, will be:
LOADER

>
The user program is then loaded in the usual manner.

(See section 2. 1 and 2.2 of the Linking

Loader manual.) When loading is complete, DDT takes control and types:
DDT

>
to indicate its readiness to accept DDT commands.
With the Keyboard Monitor, DAT slots -4 (user program) and -5 (user external library, if
any) must be assigned to appropriate devices for proper loading. DAT slot -6 (patch fi Ie output) and
-10 (patch file input) must be assigned to the paper tape punch and paper tape reader, respective Iy,
if the patch file capability is to be used.
2.2

Otherwise DAT slots -6 and -10 should be assigned to NONE.

USING THE BREAKPOINTS
A breakpoint provides a convenient means of interrupting a user program at any predetermined

step, allowing examination of the program status at that point. DDT -9 inserts a breakpoint (upon request)
by replacing the indicated instruction with a jump to DDT -9. When the program reaches that point,
control shifts to DDT -9, which types the number of breakpoint, the address of the breakpoint, the contents of the AC, the status of the Link, and the go-ahead signal (». The user may then perform any
of the debugging operations explained in this manual.
DDT-9 allows the use of four breakpoints to facilitate debugging when there is uncertainty
as to which path the program will follow.
The user may place a breakpoint at any point in his program, considering only the following
I imitations:
a.

Instructions wh ich are program modified

Instructions which are used as literals

XCT instructions pointing to memory reference instructions.

2-1

DDT-9

Breakpoin.ts may be placed on skip, jump, and JMS instructions. Breakpoints may also be placed on
CAL instructions, but since CAL instructions may contain arguments required by the called subroutine,
as well as having a variable number of subsequent arguments, DDT -9 is unable to simulate the CAL
(as it is able to simulate a JMS) . Therefore, a breakpoint which has been placed on a CAL is removed
by DDT -9 before continuing (exclamation point command).

However, DDT -9- retains the request for a

breakpoint at that location, and restores it if another breakpoint is entered and exi1"ed.

If the user

wants to place a breakpoint at a CAL, and restore it after each stop, he could place a second breakpoint at the return from the CAL, as shown in this example.
LOC

(Breakpoint 1)

CAL 3

12
LAC BUFF

(Breakpoint 2)

Upon leaving the second breakpoint at LOC + 2, the breakpoint on the CAL instruction is restored.
Operation of breakpoints requires one auto-index register; DDT -9 in itially assumes regi!iter 17.
The user may spec ify any other auto-index register by modifying DDT -9's spec ial register, AX$, as
follows:
AX $/

000017

tl.

(Modification procedure is explained later in
this manual.)

The commands control I ing breakpoints are as follows:

nil

Causes a breakpoint to be inserted at location k. The number n (1-4) is assigned to that breakpoint.

nil

Causes the breakpoint assigned the number n to be removed.

Causes all existing breakpoints to be removed.

The insertion of a breakpoint takes place when control returns to the user program. The
breakpoint occurs before execution of the instruction at the breakpoint address.
Examples:
LOC + 1 ....... 1"

Inserts a breakpoint at LOC+l

TAG ....... 2"

Inserts a breakpoint at TAG

111

Removes breakpoint number 1

A breakpoint number may be reassigned without first removing the previous assignment.
To restart from a breakpoint, the user simply types an exclamation point (!). DDT -9 restores
the AC and Link and returns control to the user's program, starting with the instruction at the breakpoint
address. An octal number typed before the exclamation point will cause DDT -9 to bypass that bre(lkpoint
n times. This ability is convenient when a breakpoint has been inserted in a program loop, and the user
does not wish to stop every time through the loop.

2-2

DDT-9

If the user's program does not reach the breakpoint, the operator may stop the action and return control to DDT -9 by typing control T (hold the CONTROL key down wh ile striking the T). DDT-9
will type the go-ahead (». The program interrupt control must be on to perform this operation.
2.3

EXAMINATION AND MODIFICATION
DDT -9 provides several variations of the procedure for examining and modifying the contents

of any storage word. They are:

The slash, typed after an address (k) causes the addressed storage word to be opened
and its contents displayed on the teleprinter. For example,
LOC/ TAD COUNT
where the instruction TAD COUNT is contained at the location labeled LaC. The
storage word is now opened and may be modified by typing the desired content and
issuing one of the commands described below.

The carriage return closes the storage word and resets DDT-9, enabling it to accept
other commands. Any change which has been entered is incorporated, as shown
below:

Loci

TAD COUNT

TAG/

JMP LaC

JMP

LOC+lit

The line feed c loses the storage word I then opens the next sequential storage word:

Loci

TAD COUNT

LOC+l1

CMA

The up arrow closes the storage word, then opens the preceding storage word.
LOC/

TAD COUNT

LOC-l/ LAC A

Control Z allows the user to examine (and modify) a single storage word, out of
sequence, and then return to the original sequence. This command closes the
storage word, then opens the referenced storage word. A line feed will then open
the next storage word in the original sequence, as shown:

LABEL!

JMP LaC

Loci

TAD COUNT

LABEL+l1

LAC HOLD

2-3

TAD CNTR

DDT-9

Control A allows the user to examine a new sequence of storage words. This command closes the storage word, then opens the referenced storage word, establishing
a new sequence. A line feed will then open the second storage word in the new
sequence.

LABEL!

JMP LOC
-----

LOC/

TAD COUNT

LOC+l/

CMA

TAD CNTR

Control X is used, in multi-memory bank systems in conjunction with transfer vectors,
to examine a new sequence of storage words. This command operates with a 15-bit
address taken directly from the currently open word.

(In contrast, the t Z and t A

operations take 13 bits from the currently open word and the two memory bank bits
from the address of the open storage word.)

2.4

TAG/

36307

36307/

000000

TYPE-OUT MODES
DDT -9 allows the user to choose from several modes of representing "the requested information.

These modes, and their commands, are as follows:
NUM$

In this mode, DDT-9 types memory word contents as 6-digit octal numbers, including
any leading zeroes.

TV$

In thi s mode, DDT -9 interprets words as transfer vectors.

Bits 0-2 are ignored, and

bits 3-17 are interpreted according to the address modes as described below.
SYM$

In this mode, which is assumed initially, DDT-9 interprets words as symbolic instructions.

Bits 0-3 are first examined to determine the instruction class. If bit 4

(indirect addressing bit) of a memory reference instruction is set, an asterisk e') is
typed after the mnemonic op code. The address portion is handled according f'o the
address mode as described below. Operate instructions are further examined f,or
specific mnemonic codes. (See appendix 2 for recognized codes.) Operate
instructions not found in DDT -9 1s table are typed out as NOP+XXXX. Subroutine
calls, extended arithmetic element, and input/output instructions ·are interpreted
as CAL+XXXX, EAE+XXXX, and IOT+XXXX, respectively.

2-4

DDT-9

The colon, typed afl'er a word has been displayed in either numeric (NUM$) or
symbolic (SYM$) mode, causes DDT-9 to retype the word in the alternate mode.

Loci
Loci

340126

TAD LABEL
340126

TAD LABEL

The equal sign, typed after a word has been displayed in either numeric or symbolic
mode, causes DDT -9 to retype the word as a transfer vector.

Loci
2.4.1

CAL+126

LABEL

Address Modes
The following commands set the address mode, which affects the handling of transfer vectors,

address portions of memory reference inslTuctions, and display addresses.
REL$

In this mode, which is assumed initially, DDT-9 types addresses which are relative
to user defined symbols.

Loci

TAD LABEL- 3

If there is no symbolic label within ±77 positions, the address is typed as re-

locatable (see next paragraph below). Symbols defined in direct assignments are
not recognized by DDT -9.
RLC$

In this mode, DDT-9 types addresses in relocatable form, as shown on the assembly
listing. For example,

Loci
ABS$

TAD 147

In this mode, DDT-9 types addresses in absolute form:

Loci

TAD 13147

The difference between the results of RLC$ and ABS$ modes is the relocation factor
(in th is case, 13000). The relocation factor is found in the memory map output by the
Loader.
The user may type modification input in whatever representation he finds most convenient.
There are, however, two points to keep in mind.

If a memory reference mnemonic is entered with a numeric address, DDT -9 assumes -that address to be relocatable unless the address output mode has been set to ABS$. For example,

LOci

TAD 147 ~

TAD COUNT

(DDT -9 adds the relocation factor before storing the information).
A requested address, typed numerically, is always considered absolute.

411

Opens word 41 of the machine.

13000+41 I or 130411

Opens word 41 of the program, where 13000 is
the relocation factor.

2-5

DDT-9

2.5

STARTING AND RESTARTING
DDT -9 receives control, initially, from the Monitor and normally regains control from the

user's program by means of a breakpoint, as described above. A control T may be typed at any fime

(if the program interrupt control is enabled) to restore control to DDT-9.
The following commands sh ift control from DDT -9 to the user's program:
The apostrophe, typed alone, starts the user's program at its normal starting clddress.
(That address given in the source . END statement, or the first physical location of
the first program loaded.
k'

The user may start his program at any other point by simply typing that addres;s
ahead of the apostrophe.
The exclamation point restarts the user's program after a breakpoint. The AC and the
Link are restored before continuing.

An octal number (n) entered before the exc lamation point causes DDT -9 to bypass
that breakpoint n times before stopping again. This ability is useful when a breakpoint has been placed in a program loop.

2.6

SEARCHING OPERATIONS
DDT -9 has a powerful searching operation with which every word in a user's program hClving

particular characteristics can be found with ease. Two special locations, LO$ and HI$ (further explained in the next section), control the limits of the search, and a mask (MSK$) allows the search to
be based on all or any portion of the word. The mask is initially set at 777777, for a fu II word seclrch;
and the limits are initially set to encompass the entire user's program, including all subprograms and
library routines.
There eire three types of searches as follows:

k ....... EQ$

Starts a search for all words, within the set limits, whose contents, after mask·ing by C(MSK$) ,are equal to the expression k.

k ....... UN$

Starts a search for all words, within the set limits, whose contents, after mask-·
ing by C(MSK$), are not equal to the expression k.

k ....... ADR$

Starts a search for all memory reference instructions, within the set limits,
with effective addresses which, after masking by C(MSK$), are equal to i·he
address k. Indirect addressing is followed one step.

2-6

DDT-9
Examples:
LOC+11....1 ADR$ might produce
TAG/

LAC LOC+ 1

POS/

XOR LOC+1

LABEL/

DAC* POINT

If the> is typed with no other output, the search routine has found no qualifying words.
2.7

SPECIAL LOCATIONS USED BY DDT-9
The following special locations contain information of use to the user, and which he may

wish to change.
AC$

Holds C(AC) at a breakpoint.

LNK$

Holds status of the Link at a breakpoint.

MSK$

Contains the search mask, initialized at 777777.

LO$

Contains the address of the lower limit of the search operation.

HI$

Contains the address of the upper I imit of the search operation.

PAS

Contains the address of the first position available for inserting patches. (Note
that the initial contents of LO$ show the last available position plus one.)

AX$

Contains the number of the auto-index register to be used by the breakpoint
routines, initialized to 17.

RF$

Contains the current relocation factor.

SA$

Contains the normal starting address used by the apostrophe routine.

Bn$

Contains the address of breakpoint n.

These words are stored sequentially as listed; the line feed may be used to step through them.
In the following example, the mask is set to examine instruction code bits (0-3) within the
limits specified by LO$ and HI$.
MSK$/

LAW 17777

740000 l

LO$/

CAL+ll075

BEGIN-1 ~

JillL

END+67

END+1 ~

After the mask and search limits have been set, the user may execute the search operation for
the desired instruction class (all JMP instructions) by typing:
JMP,-,EQ$ J,

2-7

DDT-9

2.8

SYMBOL DEFINITIONS

If the user finds, while debugging, that more symbols would be useful he can easily define
them with the following DDT -9 procedure:
S)

DDT -9 assigns the symbol S to the current location.

k(S)

DDT -9 assigns the symbol S to the location specified by the address k.

Example:

13627 (LOCAT)
Space is provided for approximately 25 additional symbols; the exact number will depend
on the length of the symbols entered. If an attempt is made to enter symbols beyond the allowablEl limit,
DDT-9 types the message OVERFLOW.

2.9

PATCH FILE OUTPUT
When the process of debugging extends to a number of sessions at the computer, it is con-

venient to be able to save those changes already checked out for use at later sessions. The commcmds
described below control the output of a patch file onto paper tape.
PFO$

DDT -9 outputs all registers within the limits set by LO$ and HI$ onto the
patch file.

PFO$ may be given as many times as desired.

k L-I PFO$

Put location k only onto the patch file.

SNS$

DDT -9 puts all symbols defined during debugging onto the patch fi Ie, thus
saving them for reference at later sessions.

PFE$

Close the patch file.

As many files as desired may be produced by following the sequence of commands, as follows:
PFO$
(as many as desired)
PFO$
SNS$

(optional)

PFE$
2.10

PATCH FILE INPUT
Because of the patch fileJs format, it may be loaded only by DDT -9,. This is done after the

user's program has been loaded in the usual manner. If a read error occurs, DDT -9 stops reading (md
types the message ERROR followed by a right angle bracket (». Data up to the point of error is correctly in memory.
PFI$

DDT-9reads in the patch file.

2-8

DDT-9

Typing PFI$ at this point (without repositioning the tape), will cause patch loading to continue with
the patch word after the word causing the error.
Repositioning the tape by moving the tape back one block wi II cause PFI(1) to attempt to
re-read the error word.
2. 11

(See appendix 3 for format of the patch fi Ie.)

CO-RESIDENT SUBROUTINES
Since identical symbols may be used in two or more separately assembled or compi led, re-

locatable program segments that are loaded and run together, the user must be able to specify which
set of symbols DDT -9 is to use.

DDT-9 initially assumes that the symbol table associated with the first

program loaded (i.e., the main program) will be used. The relocation factor used by DDT -9 comes from
the symbol table and is, also, initially assumed to be that of the main program. The following DDT-9
command changes both the symbol table search and the relocation factor to the named subroutine.
k HDR$

Sets DDT -9 to refer to that portion of the symbol table associated with the
subroutine name k, and to use the relocation factor for that subroutine.

(The

memory map output by the loader shows all relocation factors.) Symbol tables
are not loaded for lOPS and FORTRAN library subroutines.
HDR$

If no program name is specified, DDT-9 is reset to the initial condition, with
main program symbol table and relocation factor assumed.

2. 12

INDIRECT ADDRESS REFERENCES
External global symbols (those used within the program segment, but defined outside of it)

are treated differently in the symbol table than those defined within the program segment. These
symbols refer to a transfer vector pointing to the named register, not to the named register itself.
Example:
LAB/

007603

7603 is the actual address of the storage word named LAB. This address must be used when any reference
is made to LAB.
In FORTRAN programs, this condition also applies to symbols defined in DIMENSION statements.
2.13

MISCELLANEOUS FEATURES
Q$

Q$ represents the content of the currently open storage word. It makes it
possible to make small changes without typing the entire contents. In the
following example, Q$ represents JMP LOC+3.
LOC/

JMP LOC+3

LOC/

JMP LOC+7

2-9

Q$+4 ~

DDT-9
The period, typed alone, represents the address of the currently open or the
most recently opened word

Loci

JMP LOC+3

JMP LOC+7

JMP .+7zl

The ampersand causes DDT -9 to bypass the mnemonic instruction lookup. It
is necessary if the user has used a recognized mnemonic operator as a symbolic
address.

JMPI

Is inval id, but

&JMP/

wi II open the word named JMP.

LOC/

JMP GO

JMPJMPil,

The second JMP, in this case, is
interpreted as an address.

DDT-9 executes the instruction k. The AC and Link are restored to the ir con-'
dition before the breakpoint (if one is in effect)

If the instruction is nolo a

JMP, control returns to DDT -9, and the new AC and Link (if affected) are
stored.

For example,

JMS L....I SUBA#
will cause subroutine SUBA to be executed

SUBA cannot look for subsequent

arguments. Skip instructions cause the return pointer to be incremented by one.

If the user makes a typing error, he can cancel the current line by typinbl
control U. DDT -9 types(CY as evidence of acceptance. Single character
deletion (RUB-OUT) is not allowed by DDT -9. If a RUB-OUT is typed, i't will
be treated as a control U

The user may interrupt his program (or DDT) at any time he desires, by typing
control T

DDT -9 then types:

DDT

C(PC)

C(AC)

S(L)

>
and waits for a command from the teletype.

2-10

DDT-9

APPENDIX 1
SUMMARY OF COMMANDS
Linkage Characters

Arithmetic plus
Arithmetic minus

(space)

Field separator
Breakpoints

nil

nil
II

Insert breakpoint at location k, assign number n (1-4)
Remove breakpoint number n
Remove all existing breakpoints
Restart from breakpoint

Restart from breakpoint, wait n times before reentering breakpoint

Restart DDT-9
Examination and Modification

Open location k

(Carriage return) Close the location
(Line feed) C lose the location, open next location
(up arrow) C lose 'the location, open the preceding location.

(Control Z) Close the location, open addressed location, continue original
sequence

(Control A) C lose the location, open addressed location, start new sequence

(Control X) Close the location, open the location addressed by 15-bit
transfer vector, start new sequence
Type-ou t Modes

NUM$

Type contents as 6-digit octal numbers

TV$

Type contents as transfer vectors

SYM$

Type contents as symbolic instructions (assumed by default)
Retype in alternate mode (NUM$, SYM$)
Retype as transfer vector

REL$

Type addresses as relative to defined symbols (assumed by default)

A 1-1

DDT-9
Type-out Modes {continued}
RLC$

Type address as relocatable numbers

ABS$

Type addresses as absolute numbers
Starts and Restarts
Starts user's program at normal starting point

Starts user's program at location k
Restarts user's program from breakpoint

Restarts user's program from breakpoint, waits n times before reentering
breakpoint

Restart DDT-9
_Searching Operations

k L-J EQ$

Search for words equal to k

k ' - I UN$

Search for words not equal to k

k L-J ADR$

Search for instructions with effective address equal to k
Special DDT -9 Locations

AC$

Holds AC at a breakpoint

LNK$

Status of Link at a breakpoint

MSK$

Contains search mask

LO$

Lower I imit of search

HI$

Upper I imit of search

PA$

First unused location in patch area

AX$

Number of auto-index used by breakpoints

RF$

Current relocation factor

SA$

Normal starting address

Bn$

Address of breakpoint n

Al-2

DDT-9
Symbol Definition

Assign symbol s to the current location

k(s)

Assign symbol s to location k
Patch File Output

PFO$

Patch file output

kL-l PFO$

Single location patch file output

SNS$

Save new symbols

PFE$

Close patch file output

Patch Fi Ie Input
PFI$

Read patch fi Ie
Coresident Subroutines

k HDR$

Use symbol table and relocation factor of subroutine k

HDR$

Use symbol table and relocation factor of main program
Miscellaneous Features

Contents of currently open location
Address of currently open or most recently opened location
Bypass mnemonic instruction lookup
Execute the instruction k

Cancel the line

Restart DDT-9

Al-3

DDT-9
APPENDIX 2
MNEMONIC INSTRUCTION TAB LE
Memorl Reference

Operate

CAL

000000

NOP

740000*

DAC

040000

OPR

740000

JMS

100000

CMA

740001

DZM

140000

CML

740002

LAC

200000

RAL

740010

XOR

240000

RAR

740020

ADD

300000

SMA

740100

TAD

340000

SZA

740200

XCT

400000

SNL

740400

ISZ

440000

SKP

741000

AND

500000

SPA

741100

SAD

540000

SNA

741200

JMP

600000

SZL

741010

RTL

742010

RTR

742020

CLL

744000

STL

744002

RCL

744010

RCR

744020

CLA

750000

CLC
GLK

750001
750010

LAW

760000

EAE Group
EAE

640000
Input/Output

lOT

700000

*DDT -9 interprets 740000 as NOP.
A2-1

DDT-9
APPENDIX 3
PATCH FILE FORMAT
DDT -9 punches the patch file in four-word blocks, including the two-word block header
used by the lOPs system, with blank tape showing between the blocks. Each block carries the address
and the contents of one memory word.

(See figure A3-1.) The Save New Symbols command (SNS$)

punches the additional symbol table area in the same manner. The PFE$ command punches an lOPs
end-of-file block.

WD 0

word pair
count and mode

checksum

WD 2

address of
patch

WD 3

contents of
patch

}IOPS

Figure A3-1

A3-1

block header

EDITOR-9

PDP-9 TEXT EDITOR

ACKNOWLEDGEMENTS
The structure of the PDP-9 Text Editor control language is based in large part upon that
offered by TVPSET* , a context-editing program designed and written by Jerome H. Saltzer in November,
1964, under the auspices of Project MAC, The Massachusetts Institute of Technology.

* The Compatible Time-Sharing System: A Programmer's Guide, 2nd Edition, ed. P.A. Crisman (The
M.I.T. Press, Cambridge, 1965), Section AH.9.01.

P DP-9 TEXT EDI TOR
CONTENTS
Page
1

INTRODUCTION ......•...••........................•...................

1-1

FUNCTIONAL DESCRIPTION ............................................ .
,Control Modes .......•..............................................

2-1
2-1

2. 1

2.2
2.2.1
2.2.2
2.3
2.3.1
2.3.2
2.3.3
2.4
2.5

.. , .......•.............................................

2-1

Line-by- Line ................... '............................... .

2-1
2-1
2-3
2-3
2-3
2-4
2-5
2-5

Data Modes

Block Data Mode ............................................... .
Data Fi les ...........................•.................•............
Using Monitor I/O ......•...........................•............
Input and Subsi diary Fi les .....•..•..•.............................
Output Fi les .....••......•......................................
Using the Break (CNTRL P) Character ................•..................
Using the Erase and Kill Characters

.................................. .

3
3.1
3.2
3.3
3.4
3.5
3.6
3.6.1
3.6.2
3.6.3
3.6.4
3.6.5

EDITING OPERATIONS ..••..............•.•.•....................•......

.......•................. " ',,',' ....... .
Fi Ie-Naming and Calling Errors ......••..•.•.......................

3-1
3-1
3-1
3-2
3-2
3-2
3-2
3-2
3-3
3-4
3-4
3-4

EDITOR COMMANDS ....•......•......................•.................

4-1

4.1

OPEN (filename (ext)),? .....•.......•...•.•.....................•....

4-1

4.2
4.3
4.4
4.5
4.6

CLOSE (fi lename (ext))'; .........•..........................•........

4-1

NEXT [N] (u n),/ ...•.....•..............•..•............•........
PRINT [p] (u n) J ................................................ .
FIND [f] string

4.7

DE LE TE [D] (u n) ~ .....•..........................................

4.8

BOTTOM [B]

4.9

RETYPE [R] u line'~ .......•..•......................................

4.10
4.11

I NSERT [I] u line J ................................................ .
INSERT[I] ,I ............ .•..........................................

4.12
4.13

GET [G] (u n)J ......••...........................................

4-2
4-2
4-2
4-2
4-3
4-3
4-3
4-3
4-3
4-3

CHANGE [C] u q string1q string2q j

4-4

Modifying an Existing Fi Ie ....•...........•..•..•...............••.....
Creating A New Fi Ie ..•....•.........................................
Input/Edit Modes

.. . .............................................. .

Block Mode ...........•.............................................
Closing the New Fi Ie ....•...........................................
Error-Handling Conventions
Command String Errors .......•............•.......•.•.•....•.....
Premature End of Fi Ie .......................................... .
Read Errors and Line Overflow ....••...•...........•...............
Block-M~de Buffer Overflow

J ................................................ .

LOCATE [L] stringJi .......................................•........

J ..................................................... .

iii

................................. .

PDP-9 TEXT EDITOR
CON TEN T S (continued)
Page

4.14

TOP [T] ~

........................................ .

4-4

4.15

VERIFY ['I] u

{g~ ~ . . . . • . . . . • . . . . • . . . . . . . . . . . . • . . . . .

4-4

4.16

OVERLAY [0] {u n} ~

4.17

APPEND [A] u string ~

4.18

BRIEF u

4.19

BLOCK u

4-5
.•...•......•...••...••...••.•••.

4-5

{g~F ~

•..............•..•...•..•....•..•.•

4-5

{g~F ~

.••..•••••.•••.••••••.•••••••••.•.••

4-6

4.20

SIZE [S] u n ~ .••..•..........•.•••••••••..•.•..•...•

4-6

4.21

READ ~

4-6

4.22

WRITE -.

4-6

4.23

MOVE u TAG 1 {±n } U TAG2{±n } u TAG3 {±n } • . . • . . . . . . . • . • . • •
1
3
2
EXIT
.....•.......••.•.•••••••••••••.•••...••.•..

4-7

4.24

.••.•••.••.•.••••.•••••.••••.•••.•••.••••••

4-7

RECOVERY PROCEDURES

.•.......•.•.......•.•........•....

.5-1

EXAMPLES OF EDITING REQUESTS .•....••..••••••.•••••••••.•.

6-1

APPENDIX
Appendix
SUMMARY OF EDITING COMMANDS. . . . . . . . • . • • . . . . • . • . • . . • • •.

A1-1

ILLUSTRATIONS
Figure
2-1

Schematic of Line Processing in Block and Normal Modes

••.••••••.••.••

:2-2

6-1

Sample Input File ....•....••....•..•...••.••.••••...••.••.

6-2

Input File Listing Marked for Correction ....•.•..••••.•••••••••••••

6-3

6-3A

Hard-Copy Output of Editing Session

6-4

6-3B

Hard-Copy Output of Editing Session

6-5

6-4

File Resulting From Editing Session ..•.•..•.••••••••••••••••••••.

6-6

TABLES
Table
2,-1

Standard DAT Assignments for PDP-9 Symbolic Editor ...•.•..••••.••••.

:2-3

2-2

Output Fi Ie Conventions for PDP-9 Symbol ic Editor

2-4

PDP-9 TEXT EDITOR
INTRODUCTION
The PDP-9 Text Editor (EDIT 9) is a powerful context-editing program that allows the modification and creation of symbolic source programs and other ASCII text material. * By means of commands
issued from the Teletype, the Editor is directed to bring a line, or group of lines, from the input file to
an internal buffer. The user may then, by means of additional commands, examine, delete, and change
the contents of the buffer, and insert new text at any point in the buffer. When the line, or block of
lines, has been edited, it is written into a new file on the output device.
The Editor is most frequently used to modify MACRO-9 and FORTRAN IV source programs,
but it may also be used to edit any symbolic text.
The Editor operates in the ADVANCED Software System with either the VO or Keyboard
Monitor and may be used with all standard peripheral devices. The program resides in locations 13000
8
to 177638 of the highest memory bank present, occupying 2471 10 registers. ** Additional memory, excepting that reserved for the Monitor and the required device handlers, is utilized for block mode buffers.

*The Editor reads and writes standard lOPS ASCII lines. The characteristics of lOPS ASCII text are
described in the Monitor manual (DEC-9A-MABO-D).
** Attention is drawn to the Monitor manual, Chapter 3, for a detailed discussion of loading and memoryallocation schemes for system programs.

1-1

PDP-9 TEXT EDITOR
2

FUNCTIONAL DESCRIPTION

2.1

Contro I Modes
The PDP-9 Editor operates in one of two control modes; in edit (or command) mode the pro-

gram accepts and acts upon control word and data strings to open and close files, to bring lines of text
from an open file into the work area, to change, delete, or replace the line currently in the work area,
and to insert single or multiple lines after the line in the work area. In input (or text) mode, lines from
the Teletype are interpreted as text to be added to the open file. Commands are avai lable for conveniently changing control mode.
2.2

Data Modes
Data from the input file is made available for editing in two ways: in line-by-line mode or

in block mode.

2.2.1

Line-by- Line
In line-by-line data mode a single line is the unit of the input file available to the user for

modification at any point. The Iine currently avai lable is spec ified by a pointer wh ich can be thought
of as moving sequentially through the fi Ie, starti ng at the first line, in response to typed editing commands. When a file is opened at the beginning of an editing session, the first Iine of that fi Ie is brought
into the work area and is available for modification. This line remains in the work area until the user
requests that a new line be brought in. The pointer then moves down the file unti I the Iine requested is
encountered. That line is brought to the work area a~d, as the "current line, II can be modified. Lines
previously skipped over are no longer avai lable for editing by the user, but are written in the output
fi Ie. Thus at any point in a single edit run in line-by-line mode, the user is able to modify only the
portion of the input file consisting of the current line and all lines between the current line and the end
of the file (i.e., the current line and all lines below it).

2.2.2

Block Data Mode
In block data mode, a user-spec ified portion of the input file is held in a core buffer for

editing unti I the user requests that the contents of the buffer be added to the output file. All of the
Editor commands used in line-by-line editing are employed when editing blocks; in addition, a group of
commands is available for use in block mode only (see Chapter 5).
When the user is operating in block mode, commands to the Editor are honored only with
respect to that portion of the input file currently occupying the buffer. The lines of text in the buffer are
made available for modification through the use of normal locative requests and, moreover, may be reaccessed unti I the buffer is emptied by the user.

2-1

PDP-9 TEXT EDITOR

Unless deleted, lines passed over in block mode are not lost to the user (as in line-by-line
mode) unti I the contents of the buffer are written in the output fi Ie. Consider, for example, the e:diting
request to search for and bring in a specified line.

In line-by-line mode, the result is a scan of

(possibly) the entire fi Ie below the pointer. The same request in block mode provides a search of f'he
enf'ire buffer below the pointer, but no further.
Block mode has another advantage: rapid correction of editing command errors.

If the user

finds that he has typed the wrong command, he can immediately correct it, since the buffer has nCit
been added to the output file.

In line-by-line mode, a command error may cause the program to bypass

a I ine in which a change is needed. The user would then have to punch a new input fi Ie and begin
editing (more carefully) ago in.

READ AND
DECODE
COMMAND

YES

ADD CURRENT
LINE TO
OUTPUT PAGE

YES

ADD CURRENT
LINE TO
OUTPUT FILE

1
GET NEXT
LINE FROM
INPUT PAGE

GET NEXT
LINE FROM
INPUT FILE

Figure 2-1

YES

Schematic of line Processing in
Block and Normal Modes

2-2

PDP-9 TEXT EDITOR
2.3

Data Files

2.3.1

Using Monitor I/O
The Editor makes use of the Monitor Input/Output Programming System for I/O transfers and

communicates with lOPS by way of entries in the Device Assignment Table. Entries in DAT which are
required by the Editor are given in Table 2-1. Methods of modifying DAT are described in the Monitor
manual (DEC-9A-MABO-D).
Table 2-1

Standard DAT Assignments for PDP-9 Text Editor

DAT Entry Number

Used For

-3

Teleprinter output; messages to user

-2

Keyboard input; text and commands

-14

File input

-15

Scratch or edit file output*

-10

Subsidiary fi Ie input

*The use of the scratch device is described in Section 2.3.3.
2.3.2

Input and Subsidiary Fi les
The Editor will accept file input from a maximum of two devices in addition to input from the

keyboard. The first device nor'mally holds a previously prepared file upon which changes are to be
carried out. The second, the subsidiary file device, is usually the medium through which additional,
previously prepared, text is inserted in the object file. Either one, or both, of these devices may be
ignored by the user, in which case the Editor assumes that all data will come from the keyboard.
Care must be taken in the specification of the subsidiary input device to ensure that the data
of interest residing thereon was recorded in nonfile-structured fashion.
"readers, this is the only recording mode.

For the paper tape and card

For other devices (e.g., DECtape), however, the user has

the choice of writing data in either a file-structured or a nonfile-structured manner. * When the Editor
is first loaded, the characteristics of the subsidiary input device are determined. If that device can be
fi Ie-structured, the comment
SECONDARY INPUT DEVICE IS FILE-ORIENTED
is printed on the Teletype. The intent here is to warn the user that disaster will result if the data to be
read from the device is file-structured.

Note, however, that if the data to be read was recorded in

* For a discussion of data-handling conventions in fi Ie-structured and nonfile-structured input/output
modes, see the Monitor manual (DEC-9A-MBOO-D).

2-3

PDP-9 TEXT EDITOR

nonfile-structured fashion, then the requested device is a legal one for secondary input. Accordi'ngly"
the Editor then asks the question,
DO YOU WISH TO CONTINUE?
The user's answer to this question is taken to indicate the nature of the data on the secondary input de··
vice. If the user's response is
YESt
then the program wi II read data from the device in the normal (nonfile-structured) way. If the user's
answer is NO (or anything except YES) file-structured data is assumed and return is made (via. EXIT)
to the Monitor.
2.3.3

Output Files
Immediately upon receiving control after having been loaded, the Editor attempts to dE~ter

mine whether or not the input and scratch devices are fi Ie structured. If either one of the device:) is
not file structured, then the scratch device (OAT entry -15) is assigned as the final output device. If
both devices are file structured, the scratch device is assigned an intermediary function and the input
device is used as the final output device.
The intent, in all cases, is to allow replacement of the input file by the edited output file.
This is possible only when the input and output devices can be both read and written. If replacement
can be accomplished (both devices are file structured), the following sequence of events takes plclce
when the files are closed after editing.
1.

The intermediate output file is read from the scratch device and written on the input

device under a temporary name.
2.

The old input file is deleted from the input device.

The intermediate output file is deleted from the scratch device.

The intermediate output file, temporarily named and now residing on the input device,

is given the name previously assigned to the old (now deleted) input file.
5.

The output fi Ie is closed and immediately becomes avai lable for use.

If no replacement can be accomplished, no change is ever made to the input file. If the
output device is file oriented, the new edited file is properly entered in the file directory for thai'
device under the name given in the OPEN or CLOSE command sequences.
The possible destinations of the new edited file are summarized in Table 2-2.
Note that in the process of file housekeeping, there is always at least one copy of the I::>Utput
file available on one, or both, of the devices. Further, the original input file is not deleted until the
new file has been successfully written and closed. A system fai lure, therefore I can never result in
total loss of data. Recovery procedures to be used in case of difficulty are outlined in Chapter 5.

2-4

PDP-9 TEXT EDITOR
Table 2-2
Input Device

Output File Conventions for PDP-9 Text Editor

Scratch or Output Device

Edited File appears on:

Input File is:

File oriented

Input Device

Deleted

File oriented

Nonfile oriented

Output Device

Unchanged

Nonfile oriented

Fi Ie oriented

Output Device

Unchanged

Nonfile orien'ted

Nonfile oriented

Output Device

Unchanged

2.4

Using the Break (CNTRL P) Character
Frequently, the user, having made a mistake in h is command line, wishes to stop processing

and reissue his request. The user, for example, may have asked erroneously for a line which is absent
from the input file. When the Editor begins its search for the requested line, it wi II not give up until
that line is found, or until the end of the input file is encountered. The user, meanwhile, has noticed
his typing mistake. If control could somehow be transferred from the command processor to the command
decoder, the user's temper and time might be saved.
The Editor's break, or quit, character provides the mechanism for the orderly accomplishment
of the transfer. When the user types the quit character (CNTRL P) during command processing, the
normal instruction sequence is interrupted when processing of the current line has been completed, edit
mode is reentered, and the program reads a new edit command from the keyboard.
the output file.

Noth ing is lost from

Depending upon the command being serviced when CNTRL P was typed, the pointer is

left in one of two positions. In the first (usual) case, the pointer indicates the line which was being
processed when the break character appeared. This line is now the current line, and may be dealt with
in the normal way. In the second case, the pointer is left between two lines. The current-line area is
empty, and some locative request (e.g., NEXT) must be issued to move a line into the work area.
The break character results in program restart when the Editor is waiting for a command. In
input mode, the break character results in a control mode change.
2.5

(Using the Erase and Ki II Characters
The Monitor allows the use of "wo keyboard characters for correction of the line currently

being typed by the user. The Rubout key (Erase character) results in the deletion or the immediately
preceding character. The Monitor echoes a back slash (\) for each Rubout typed. CNTRL U (Ki II
character) results in the deletion or the entire line typed so far. The Monitor echoes a commercial at
sign (@) for each CNTRL U typed.
CNTRL U has a second function when used during output from the Editor to the Teletype.
When the user types CNTRL U while a line is being printed, output is immediately terminated and a

2-5

PDP-9 TEXT EDITOR
carriage return is issued. CNTRL U functions in this case as the user's means of overriding his previous
request for the output of tediously long lines.

2-6

PDP-9 TEXT EDITOR

EDITING OPERATIONS
The Editor always begins in edit mode and assumes that the user wishes to modify some (named

or unnamed) fi Ie. When first loaded, or when restarted for a new fi Ie, the program types
EDITOR

>
on the teleprinter and waits for the user1s first command.
3. 1

Modifying an Existing Fi Ie

If the input device is file structured (disk, drum, magnetic tape, or DECtape), the first
command to the Editor must be
OPEN filename extJ
where "filename" is the primary name of the wanted file residing on the input device and "ext" is its
IIExt" may be omitted and, if so, is assumed to be SRC. If the file specified is not found

extension.

in the directory, the program assumes that the user wishes to create a file named IIfilename ext. II
Accordingly, when it has been determined that the named file is absent from the input device, the
Editor types
FILE filename ext NOT FOUND.
INPUT
Input mode is entered and subsequent lines from the Teletype are inserted in a new, temporarily named,
file on the output devi ce.

If the specified file is present on the input device, an intermediate, temporarily named,
file is opened for writing on the output device and the input file is opened for reading. The user may
then proceed to make the necessary changes in the input file.

If the input device is not file structured (e.g., paper tape reader, card reader), the user1s
first command after program initialization may be any edit request. The OPEN command is not required
for nonfile structured devices.
3.2

Creating a New File
When the user wishes to create a new file, he need only issue a carri age return, thereby

entering input mode. If the output device is fi Ie structured, a temporarily named file is opened for
writing and text lines from the Teletype are added to it as they appear. If the output device is not
fj Ie structured, the file-naming conventions are bypassed.

Where both input and output devi ces are fi Ie structured, the user may issue the OPEN command followed by the name he wishes to assign to h is new fi Ie. Since a fi Ie of the name given is

3-1

PDP-9 TEXT EDITOR
guaranteed not to be found (if the user has properly chosen his new name), input mode will immediately
be entered following the standard error message. The name specified will be assigned to the final output fi Ie if no other name is given in the C LOSE command.
3.3

Input/Edit Modes
To enter text from the Teletype, the Editor must be in input mode. To carry out an edi1-

function on the current line, the Editor must be in edit mode.
Control mode may be changed at any time by typing a line of zero length (a line consisting
of a carriage return only). The Editor command INSERT (without arguments) also causes a mode change.
After the user changes control modes, the Editor types INPUT or EDIT, indicating the control mode in
effect.
3.4

Block Mode
The Editor recognizes several commands which are designed to be useful in the block or page

mode.

In block mode, a user-specified portion of the input fi Ie is he Id in a core buffer unti I the user

indicates his satisfaction with the current state of that portion.

Block mode is entered via the control

word BLOC K, followed by the parameter ON. When in block mode, the user may take advantage of
all the locative and manipulative commands (FIND, LOCATE, CHANGE, etc.) and, in addition, may
employ the MOVE command to rearrange arbitrarily long blocks of text within "the buffer.
Line-by-I ine mode is reentered by use of the BLOC K OFF command.
3.5

Closing the New File
When the user, after modifying his input fi Ie, is satisfied that a II needed changes have been

carried out, he is required to close out the input and output files. The edit command
CLOSE filename ext ~
will initiate the sequence of events described above (Section 2.3.3).
Neither "filename" nor "ext" need be specified if previously given in the OPEN commolnd.
If "filename" and "ext" are present in the command string,· they override the names given in the OPEN
command.
Both "filename" and "ext" are ignored if the output device is nonfile oriented.

3.6

Error-Handling Conventions

3.6. 1

Command String Errors
All mistakes in the use of edit-mode control words result in a common complaint by the

Editor. Although the possible errors in usage fall into a number of distinct categories, the program

3-2

PDP-9 TEXT EDITOR

makes no attempt to differenti ate among error types. The reasons for th is common treatment lie in the
requirement that the Editor take some cognizance of its memory allocation (relatively obscure error
types need as much memory for recognition and response as do the more usual mistakes) and in the fact
that the treatment rendered makes the error self-explanatory, in most cases, with respect to the difficulty
encountered.
Command string errors, then, all result in the single typed comment,
NOT A REqUEST:
followed, on the next line, by the request line with which the Editor had trouble.
Usual types of command string errors include the following:
A.

The edit control word issued was not among those in the program's repertoire.

A SIZE command was issued with a missing argument or an argument of 111 • II

A MOVE request was issued when BLOCK mode was OFF.

When BRIEF mode is ON, the Editor comment and the command Iine in error are replaced by
a single typed question mark, thus:

?~
3.6.2

Premature End-of-Fi Ie
During the processing of some commands, it occasionally happens that a read is attempted

which moves the pointer below the last line of a logical (or physical) group. Consider, for example,
the effect of a numeric argument in the GET n command line. The program reads successive lines from
the subsidiary input device unti I exactly n lines have been read • If, in the process of reading, it is
discovered that fewer than n lines are physically present on the secondary input medium (paper tape,
say), then a premature end-of-file condition is said to exist. An improperly-formulated FIND request
(the character string typed is absent from the fi Ie) will resu It in a simi lar condition.
Depending upon the character of the incoming group of lines (block buffer, secondary input
medium, or input fi Ie), the appearance of an unexpected end-of-fi Ie causes a comment to be typed
informing the user of the difficulty. The form of the message is:

END OF

BUFFER}
MEDIUM REACHED BY:
{ FILE

followed, on the next line, by the edit request which caused the problem.
A premature end-of-file causes the pointer to be left below the final line of the group being
read.

3-3

PDP-9 TEXT EDITOR

3.6.3

Read Errors and Li ne Overflow
The Editor recognizes two sorts of errors which may occur during the processing of the input

fi Ie.

Both errors result in an appropriate printed comment and immediate transfer of control to the

command decoder. The line in error is printed and left in the work area for modification by the user.
The first type of error occurs when the input fi Ie device handler detects ei ther incorrect
parity or a faulty checksum in the incoming line. The printed comment is:
READ ERROR:
fo I lowed by the Ii ne in wh i ch the error was encountered.
The second difficulty results from the appearance of a line which is too long to be contained!
in the program's internal buffers. Any line of more than 9010 characters (not including terminator)
results in the comment:
TRUNCATED:
followed by the first (leftmost) 90 characters of the long line. The remaining right-end character~; are
discarded.
The user has the choice, after either type of error, of modifying the line which caused the
complaint (via any manipulative request) or of allowing the line to stand as is in the output file (via any
locative request).

3.6.4

Block-Mode Buffer Overflow
When block mode is in effect, it is possible for an attempted addition of a line to the block--

mode buffer to exceed the buffer's capacity. This might occur, for example, during the processin!9 of
a READ request if the buffer length (previously defined by a SIZE command) is too great to be accl::>mmodated by the memory available. When the capacity of the buffer is exceeded, the program typ'ss the
comment:
BUFFER CAPACITY EXCEEDED BY:
followed by the line which caused the overflow. This line remains in the current-line area and tlhe
program reads a new command from the keyboard.
3.6.5

Fi le- Naming and Calling Errors
Errors in file-name usage can be classified in three general groups. Either (1) the namE~d

file cannot be found, or (2) a name has not been given to the file at a point where one is needed, or
(3) a name has been given wh ich cannot be used.
3.6.5.1

Absent File - If the file named in the OPEN request line cannot be found on the devicE~

associated with DAT slot-14, the assumption is made that the user wishes to create a new file with the

3-4

PDP-9 TEXT EDITOR

the name given. The program prints the comment:
FILE fi lename ext NOT FOUND.
and changes to input mode.
3.6.5.2

Absent File Name - If no file name is given either in an OPEN request line or as an argument

to the CLOSE command, the program, after attempting to process the CLOSE request, will print:
NO FILE NAME GIVEN.
The next edit request must be another CLOSE naming the file.

If no OPEN command is issued (a new file is being created), any locative request (FIND,
NEXT) will result in the comment:
NO INPUT FILE PRESENT.
3.6.5.3

Identically-Named Files - The problem of duplicate file names is apparent on two levels.

In the first case, it is possible for a previous edit run to have been aborted with one of the Editor's
temporary files (normally • TFI L1 EDT) closed on the output device. The c losing of the temporary fi Ie
created during the current edit run will result in the deletion of the like-named fi Ie from the previous
run, perhaps to the user's keen disappointment. To enable the retrieval of prior work, the Editor types
the comments:
FILE. TFIL 1 EDT IS PRESENT ON OUTPUT DEVICE.
DO YOU WISH TO DE LETE IT?

If the user's response to this question is
YESJ
then the version of the fi Ie on the output device ~s deleted and processing continues as usual. If the
user's response is
NO (or anything except YES)
then return is made (via. EXIT) to the Monitor. The

user may then rename. TFILl EDT.

At the second level, it may happen that the fi Ie name given in a CLOSE sequence is identical
to that of another fi Ie on the (current) output device. In th is case, the program types:
PLEASE USE ANOTHER NAME.
A second CLOSE request (with a unique name) may then be issued.

3-5

PDP-9 TEXT EDITOR

EDITOR COMMANDS
When edit mode ~s in effect, the following commands resu It in the specified activity.

Abbreviations for most commands consist of the initial characters of those commands.

Legal abbrevia-

tions are given in square brackets. Optional arguments are given in parentheses.
Certa in commands (e.g., FIN D, RETYPE) require the presence of arguments. Others
(DELETE, NEXT) may take explicit arguments at the option of the user. All commands must be separated
from their argument strings by a single blank character. This blank del imiter is considered by the Editor
to be a part of the command itself, not part of the argument string which follows the command. Thus,
the command
RETYPE u /COMMENT ~
results in the following line:
/COMMENT
If more than one blank appears between the command and its argument string, all blanks except the first
are taken as part of the argument. Thus,

FrND u u u /COMMENT ~
results in a search for the line which begins with the character string
uu/COMMENT
4. 1

OPEN (filename (ext)) ~
The fi Ie whose name is "fi lename" and whose extension is "ext" is searched for on the input

device.

If a file of this name is not found, a message is printed on the Teletype and the mode is changed

to input. An intermediate write file is opened on the output device and lines from the keyboard are
written into it as they are completed. "Ext," if not given, is assumed to be SRC.
If the file specified is found on the input device, it is opened for reading.

Subsequent typed

Iines are interpreted as Editor commands.
Neither file name nor extension need be given if the input device is nonfile oriented.
4.2

CLOSE (fi lename (ext)) ~
If an input fi Ie is present, all Iines in that fi Ie fall ing below the current Iine are appended

to the output file and the output file is closed. If no input file is present, the current line is added to
the output fi Ie and the output fi Ie is closed.

No further editing is permitted.

If the extension is omitted, and none was assigned in the OPEN command line, the extension
is assumed to be SRC.

If no file name is given, the name assigned in the OPEN command line is used.

Neither "filename" nor "ext" need be given for nonfile-oriented output devices.

4-1

PDP-9 TEXT EDITOR

NEXT [N] (un)~

4.3

The pointer is moved past the next n lines, beginning with the line currently in the work
area.

Line n + 1 is brought into the work area for modification.

output file.

If omitted, n is assumed to be 1.

Lines skipped over are added to "the

If the command results in the pointer moving past the

last Iine of the fi Ie (or buffer, if block mode is on) the error message
FILE
}
END OF { BUFFER

REACHED BY:

NEXT n
is printed.

4 .4

PRI NT [P] ( un) ~
n lines from the input file (or buffer, in block mode), including the current line, are printedl

on the Teletype. The pointer is left at the last line printed; n is assumed to be 1 If omitted.
If, as a result of the command, the pointer moves past the last line of the file, the error
message
FILE
}
END OF { BUFFER

REACHED BY:

PRINT n
is printed.
4.5

FIND [F] u string j
The input file or buffer is searched, beginning with the line following the current line, for

the next occurrence of a line whi ch beg ins with the character group "string." If the search is sucl:essful, the line beginning with "string" is brought into the work area.

If the search is unsuccessful

(pointer moves past end of file), the end-of-file error message is printed.
"String" may contain any number of characters.

4.6

LOCATE [LJ u string ~
The input file is searched, beginning with the line following the current line, for the next

occurrence of a line whi ch con'tains the character group "string".
which satisfies the search is brought to the work area.

If the search is unsuccessful, the end-of-file

message is printed and the pointer is moved to the top of the file.
II

String" may contain any number of characters.

4-2

If the search is successful, the line

PDP-9 TEXT EDITOR
4 •7

DEL ET E [ D ] (u n) ~
n lines, inclUding the current line, are deleted from the input file. The line following the

last line deleted becomes the current line.

If n is omitted, only the current line is deleted.

If n is

large enough to cause the pointer to move past the end of the file, the end-of-file error message is
printed.

4.8

BOTTOM [B J _
The pointer is moved to the final line in the input file (or buffer) which then becomes the

current line.

4.9

Lines skipped over in the process of moving the pointer are added to the output fi Ie.

RETYPE [RJ u line ~
The character string IIline ll replaces the current line. The new line is left in the work area

and may be subsequently modified.

4.10

INSERT [I] u line ~
The current line is added to the output file and the character string IIline ll is taken as the

current line.

Note that insertions are always made below the current line. The program remains in

edit mode when command processing is completed.

4. 11

I NS ERT [I ] ~
The current line is added to the output file and the mode is changed from edit to input.

Subsequent Iines are interpreted as text to be added to the output f~ Ie.

4.12

GET [G] (un)~
n lines from the subsidiary input device are added to the output file.

New lines are added

below the current line. When command processing is complete, the nth Iine read is left in the work
area as the current line.

If n is omitted, it is assumed to be 1 .

If an end-of-medium condition is encountered on the subsidiary input device before n lines
are read, the error message

END OF MEDIUM REACHED BY:
GET n
is printed. The pointer rema ins at the last Iine read.

4-3

PDP-9 TEXT EDITOR

4.13

CHANGE [C] u q stringlq string2q ~
In the current line, the first character group (" stringl") which matches that occurring bE~tween

the first pair of quote characters (q1s, in this case) is replaced by the character group (" string2")
appearing between the second pair of quote characters. The quote character chosen by the user may be'
any graphic (including blank) which does not appear in either of the character strings quoted.

Both

"string 1" and I string2" may contain any number of characters, including zero. If verify mode is in effect,
the program wi II print the new current Iine on the Te letype when the requested change has been accompi ished.

Examples of change requests:

Current line:
a.

NXTLIN

JMS

TYPOUT

/PRNT THE LINE.

JMS

TYPOUT

/PRI NT THE LI NE.

JMP*

TYPOUT

/PRINT THE LINE.

JMP*

TYPOUT

/PRINT THE LINE.

In the comment, spell "PRINT" properly.
Request:

CHANGE u/RN/RI N/J

New line:

NXTLIN

Make the "JMS" a "JMP*".
Request:

CHANGE uXSXP*X ~

New line:

NXTLIN

Delete the IItll in the tag.

Request:

Cu/T/

New line:

NXLlN

Move the pointer to the beginning of the edited file or buffer. The first Iine of the file
becomes the current line.

4.15

VERIFY[V]u{g~~
Set the verify mode according to the parameter. When verify mode is on, text lines are:

printed in response to certain editing commands, for example:
].

The line brought into the work area as a result of a FIND or LOCATE request is printed.

The last I ine of the fi Ie, brought in by the BOTTOM request, is printed.

The new Iine resulting from a CHA NGE request is printed.

When verify mode is off, only error messages are printed. After the Editor is loaded initia II}',
verify mode is on.

4-4

PDP-9 TEXT EDITOR

The command
VERIFY [ V] ~
{without arguments} is equivalent to
VERIFY [V J uON_
4.16

OVERLAY [0] (un) )
Starting with the current line, n lines {or the current line only, if n is omitted} are deleted

from the input file. Control mode is changed to input with the normal typed program response,
INPUT
Subsequent typed I ines are interpreted as text intended to replace the I ines so OVERLAYed.

4.17

APPEND [A] u string ~

String II is added to the current Iine following the last data character and preceding the

terminating carriage return. Thus, to add a comment to the current line
JMS GETNUM
the command might be
APPEND u --.t/GET DECIMAL ARGUMENT.~
The new current line would be
JMS GETNUM ...,/GET DECIMAL ARGUMENT.
If "string" is absent, the current line is unchanged.
4.18

BRIEFu {g~ ~
Set brief mode according to the ON/OFF parameter.

Brief mode results in the abbreviated

printing of the current line during the servicing of some commands. An attempt is made to print only
the tag, operation code, and address fields of lines brought in as a result of the FIND, LOCATE, and
BOTTOM commands.

In addition, the printing of the new line resulting from a CHANGE request is

terminated at the last newly-inserted character.
Brief mode is set to off initially. The setting of the brief mode indicator is of no consequence
when verify mode is off.
The command
BRIEF_
{without arguments} is equivalent to
BRIEFuON.

4-5

PDP-9 TEXT EDITOR

4.19

BLOCKu{g~ ~
Set block mode according to the parameter. When block mode is on, the editing commands

READ, WRITE, and MOVE are accepted by the program; these commands are treated as illega I if block
mode is off. When block mode is in effect, the program treats several lines as a subfile, retaining
them internally in a block buffer.

In block mode, editing commands which move the pointer referencE~

only those Iines currently residing in the buffer. Tne contents of the buffer are saved unti I a WRITE
command is encountered or until, by way of the DELETE command, it is emptied.
When block mode is off, sequential Iines in the input fi Ie are moved sing Iy to the work areel
and are not avai lable for reexamination after the pointer has been moved to a later line.
When the Editor is initially loaded, block mode is set to on if either the input or the scratch
device is nonfile oriented. If both devices are fi Ie oriented, block mode is set off.
The command

BLOCK~
{without arguments} is equiva lent to
BLOCKuON~

4 . 20

SIZE [S] u n ~

Set the tota I number of lines whi ch will occupy a buffer (in block mode) to n. The SIZE
command may be issued at any time, and takes effect when the next group of Iines is inserted in i"he
buffer via a READ command.

n is initia lIy set to 55

, n must be greater than 1 .

NOTE
Commands 4.21-4.23 are legal only in the BLOCK data mode.
4.21

READ.
Read sequential lines from the input file, inserting them in the buffer as they are encountered,

unti I the number of Iines in the buffer is equal to the argument specified in the SIZE request. The
pointer is set to the first Iine of the buffer when the operation is complete.
The REA D request will not be accepted if any Iines remain in the current buffer. The buffer
must have been cleared by DELETE requests or a WRITE command.
The READ request is treated as illegal if block mode is off.
4.22

WRITE ~
Add the current contents of the block buffer to the output fi Ie and clear the buffer.

is output if the buffer is empty. This request is illega I if block mode is not in effect.

4-6

Nothi ng

PDP-9 TEXT EDITOR

Perform a block transfer of several lines in the buffer. The inc lusive limits of the block to be
moved are defined by the first two arguments (TAG 1 and TAG2). The destination of the block so transferred is defined by the third argument (TAG3).
TAG1, TAG2, and TAG3 are symbolic labels in lines anywhere in the the buffer. The n.

are optional augments to be used when block-limiting lines are not labeled.
At the completion of command processing, the block of I ines between and including those
labeled TAG 1 and TAG2 (augmented, if desired) are repositioned to appear after the I ine labeled
TAG3. The po inter is left at the top of the buffer.
This command is legal only in block mode.

4.24

EXIT
Control is transferred from the Editor to the Monitor. This command is illegal if any file is

open f?r reading or writing when it is issued, i. e., it may only be given as the first command after
Editor initialization and the message
EDITOR

4-7

PDP-9 TEXT EDITOR

RECOVERY PROCEDURES
In case of a hardware or system failure, the user may recover at the point at which the last

complete version of the edited output fi Ie was closed.

The Editor, in preparing intermediate fi les,

assigns them temporary names. Thus, in the event of disaster, one (or both) of the following files may
be found .
. TFILl EDT and. TFIL2 EDT both contain the version of the edited file extant at the point at
which the crash occurred.

No editing is lost. If neither of these files is' present, the file specified in

the OPEN command contains the version of the file extant at the time the latest TOP command was
issued. All editing taking place after the latest TOP command is lost. If neither. TFILl EDT nor
• TFIL2 EDT is found and if no file name was given in the OPEN command, no recovery is possible.

5-1

PDP-9 TEXT EDITOR

EXAMPLES OF EDITING REQUESTS
This chapter contains illustrations of one complete iteration through the modification process

usi ng the Ed itor.
Figure 6-1 shows the assembly listing of a sample input file.
Figure 6-2 shows the same Iisting marked for correction.
Figures 6-3A and 6-3B show the hard-copy output of the editing session.

The sequence

numbers at the right marg in are not program generated, but were added later for reference.
Figure 6-4 is the assembly listing of the new, edited file showing the results of the editing
run.

6-1

R
R

000000

0v002

"'40~44

0(~0P3

2?000~

Vlv0~4

0vlO~5

R
R
R
R
R

040052
0400147
440000
777773
040V'!45
220044
0001:-'00

0C'0ti10
~WeJ01

d
U

0V0lil6
1ll~007

0"'010

~V011

LU
U
J
U
'J
U
U

J
0I

340~52

A
R
R
R
R
R
R
A
R
R
R
A
R
R
R
R
R
R
R
R
A
R
R
A
R
R
R
A
R
R
A
R
A
R

620000
00000(.l\

R
A

777777

A "LIT

2~HW00

M012

i,H"013

74H'0~

VlvI?J14
eCi015

R
R
R

600V'33

0"'016
1i1V'017
017'020
0V'0?1
0v'0?2

I('Jv'0?3
00024

R
R
P

R
P

4413"'44
440lil44
1i140~55

1"'0051
440046
61i'10lil43
2~0V154

7410010

M'0?5

040~54

0(70?6
0(7027

R
p

2010"'53

1()V'030

eJt?031

744(7110
060052
44005?

0v032
0(1033

·6~0"'5~

777773
540!7.45
600171201
750001

u
J

0(1'034
"'''035

P
~

0~'036

~r037

M'040
M"041

0C:'042

R
R
R
R

i2lv!2i-;7

34~V'i47

740001

ISUBROUTINE PACK, 7-8IT CHARS TO lOPS ASCII.
ICALL:
JMS PACK
I
FROM
I
TO
PACK
~
LAC PACK
IGET FROM ADRESS.
DAC PFROM
IGIVE TO FROM POINTER.
LAC .. PACK
IGET ADDRESS OF TO ARRAY.
DAC PTO
IGIVr TO OUTPUT POINTER.
DAC PL~H
ISAVf AS START ADDRESS.
IS2 PACK
IBUMP TO RETURN.
PLOOPl
LAW ·17773
ISET UP
OAC PK~CI-lR
IGET NEXT WORD IN INPUT ARRAY,
LAC .. PFROM
PLOOP2
ITERMINATOR?
SAC (-1
SKP
INO. SKIP.
IYES, GO CLOSE OUTPUT ARRAY.
JMP PCLOS
1St: PFROM
IPOINT TO NEXT WORD.
1St: PFROM
IPOINT TO NEXT WORD.
OAC PWRD3
ISET UP TO ROTATE.
JMS PRAL7
PLOOP7
,52 PK~CP
15 CHARS IN.Q
JMP LPOOP2
INO, GET ANOTHfR.
LAC PWRD?
IWORO PAIR COMPLETE.
RAL
ICLEAR PAIR BIT 35.
DAC PWRD2
LAC PWRDl
IGET FIRST WD OF PAR ..
RAL!CLL
IBIT 10 OF WD 2.
IINSERT FIRST WD IN OUT ARRAY.
OAC" PTa
ISl PTO
IRUMP OUT ADDRESS.
JMP PL'fI0Pl
IGO SET UP NEXT PAIR.
PCLOS
IMAKE SURE PAIR IS COMPLrTE.
LAh 17773
SAD PKSCHR
JMP PLrJOP7
IINCOMPLETE PAIR.
CLA!CMA
IFORM WORD PAIR COUNT
TAD PL~H
1ST ART ADDRESS.
CMA
TAD PTf)
ILESS END ADDRESS.
IRfTURN TO CALLER.
JMP" PACK
.END

Figure 6= 1

Samp!e Input File

-c

-c
I

'"
m

-t

m
0

0
;;:0

~EFT-,,)J.TI.I..$,etJ

Yj"

ISUBROUTINE PACK, 7-BIT~CHARS TOJIOPS ASCII •
JMS PArK
MfLLi2N, Ik, 1kJt.,9$ 7OTIH- w()etH tX.£,aIJ,ti)
FROM
/.srA£.;-a';:' //JpurAe£4v.
i?N p~€-IJAeIlAV. A woe/j tn=h-I-.t!S Mt.J.-&T
ITO
/ ~JJ-e.reK'- ou.Tl'ttT1he£A-Ve
I~MI AJAr;: TJJe INfJw (UN rAG~e(J ) MeAVe
A
PACK
11
R
L~* ~ PACK
IGET FROM A[~ESS.
R 1st ~~~DAC PF~OM
IGIVE TO FROM POINTER.
R
LAC* PACK
IGET ADDRESS OF TO ARRAY.
R
DAC PTn
IGIVE TO OUTPUT POINTER.
R
nAG PL~II
ISAVE AS START ADDRESS.
R
1St PAGK
IBUMP TO RETURN.
A
PLOOP1
LAW 17773
ISET UP
/.&-- (!~T.te f!LXU) ,.-6e.
R
nAC PK~CHR
IGET NEXT WORD IN INPUT ARRAY.
R
PLOOP2
LAC* P~ROM
R
SA-/)" ~ ~--{t::Nbc:..HJ:! ITfRMINATOR?
INO, SKIP.
A
~ ~*~IYES, GO CLOSE OUTPUT ARRAY.
R
JMP PCLOS
IPOINT TO NEXT WORD.
R
ISl PFROM
R
1St PFROtl
,POINT TO NEXT UORO.
ISET UP TO ROTATE.
R
DAC PWRD3
R
PLOOP7
JMS PRAL7
1
15 CHARS IN.Q
•
R
ISr.~!,GSc.He
INO, GET AN HfR.
R
JMP~PL06PZ
IWORD PAJR COMPLETE.
R
I
LAC PWRD2
A
RJrL.. e.I-L ~
ICLEAR PAIR BIT 35.~~I2
R
DAC PWRD2
IGET FIRST WD OF P~~
R
LAC PWRDl
IBIT 0 OF WD 2.
A
12.AL ~
IINSERT FIRST Wo IN OUT ARRAY.
R
DAC* PTO
IBUMP OUT ADDRESS.
R
ISl PTn
IGO SET UP NEXT PAIR.
R
JMP ~PLOOP~
IMAKr SURE PAIR IS COMPLETE.
A
PCLOS
LA~ 1777~
R i)ZM PW,etl.3YSAO PK'5CHR
IINCOMPLETE PAIR.
R
JMP PLnOP7
IFORM WORD PAIR COUNT&
AEIVl>C~ LAW .--' ~
1ST ART ADDRESS.
R
71fo~p;rc,K:.. ~
A
CMA
ILESS END ADDRESS.
R
/sZ ~'-~ AD PTO
IRFTURN TO CALLER.
R
~JMP* PACK
A
(.ENO
A *LIT

• ~UJid.. 'j)ltt:-K, P21K-7., ~~()~.:J.ICALL:
PW£O'l, Pw~o3
I

000000
2"'0000

0~003

R
R
R
P

0V004
0V005

R
R

00006
00007
00010

0~011

0(7)012
0f013
00014

0~0?2

R
R
R
R
R
R
R
R
R
R
R
R
R

0400.52
040047
440000
777773

000?3

u
0I

u
u

(.,.)

u
U

00000
0"'001
0V002

0~015

00016
0~017

00020
0V'021

0~'024

0"'037
00040
0(ij041
0"'042

R
R
R
R
R
R
R
R
R
R
R
R
R
R
R

0?0'57

0~025

0'026
0V1027

00030
0P031
0"'032
0V033

00034
0V035

u
U

0V'036

040~44
220~00

040~45

220~44

000000
741000
600~33

440044
44017J44
040055
10~051

440046
600043
200054
740~10

040054
200053
744010
060052
440052
617l017J50
777773
540045
600~20

7'50?eJ1
340047
7400.01
340052
620000.
000000
777777

NON-H13AM?R.G-l)

p,o
PFecJII1
PJCSC~

¢
¢

Figure 6-2

Input Fi Ie Listing Marked for Correction

-0

-0
I
-.0
-I

-I

o
;:;:0

PDP-9 TEXT EDITOR
EDITOk
>QPEN PACK SR.C
>FIND ISUBEOUT
ISUBkOUTINE PACKI 7-EIT CHA~S TO lOPS ASCII.
>OVEf-:LAY 1
INPUT
ISUB~OUTINE PACKI 7-BIT LEFT-AD~ruSTED CHARS TO NON-HEADEhED lOPS
IASCII. ON RETURNI AC HOLDS TOTAL WO~US OCCUPIED BY PACKED ARRAY.
IA WOhD OF· ALL l'S MUST O\TEHMINATE THE INPUT (UNPACKED) AhRAY.

3
4
5

7
8

9
10
11

EDIT
>LOCATE FROM

>AtJPEND
ISTAhT OF INPUT ARRAY.
>NEXI
ISTAhT OF OUTPUT AhhAY.
>APEND
NOT A l{EQUEST:
I STP.hT OF OUTPUT ARhAY.
APEND
ISTAhT OF OUTPUT AkhAY.
>APPEND
>PHINT 1
I
ISTAhT OF OUTPUT ARRAY.
TO
• GLOEL PACKI PHAL 71 PWRD11 PWHD21 Pv.'RD3
>INSEHT
>L LAC
IGET I'hOM ADRESS.
LAC PACf<
>CHANGE LAC/LAC*I
IGET FHOtl, ADHESS.
LAC PACK
\~CHANGE ILAC/LAC*I
l(iET FROM ALRESS.
LAC* PACK
>NEXT 1
>INSEhT
INPUf
I BUMP TO "TO" ADDHESS.
ISZ PACK
EDIT
>PhINT

13
14
15
16
17
18
19
20
21
22
23

25
26
27
28

.29

30
31
32
33
34

ISZ PACK

bUMP TO "TO"

ADUhE~S.

>BrdEF ON
>C • I .1.

35
36
37

38
39

ISZ PACK

1St.: PACK

18UMP TO "TO" ADDHESS.

>PRINT

40
In

>L PLBH
DAC PLBH

>BHIEF OFF
>PhINT

l~5

DAG PLBH
>UELETE 2
>prlINT
PLOOPl
>N
>A
>L

ISAVE AS STAhT ADDHESS.

LAW 17773

ISET UP

15-CHAHACTEh COUNTER.

SAC (-1
>VEriIFY OFF
>C ISAC/SADI
>C 1(-I/ENDCHRI
>V ON
>P
SAD ENDCHh
>N

ITERM INATOH1

ITERM INATOh?

51
52
53

54
55
56
57
58
59
60

61
62

>'0

>N
>P
ISZ PFHOM

Figure 6-3A

IPOINT TO NEXT WORD.

Hard-Copy Output of Editing Session

6-4

63
64

PDP-9 TEXT EDITOR
>D
>P
ISZ PFHOM

65
66
67

IPOINT TO NEXT WORD.

>1' PL

JMS PRAL?

PLOOP?
>N
>RETYPE
>N

ISZ PK5CHri
JMP PLOOP2

>N 2
>CHANGE IL/L!CLL
RAL!CLL
>L kAL
riAL! CLL
>C I!CLLII
hAL
>L JMP
~JMP PL00P 1
>CHANGE 11313/001
JMP PLOOPl
>N

70
71
72

15 CHARS IN?

INa" GET ANOTHER.

74
75

76
77
78
79

ICLli:Aii PAlk BIT 35.
IBIT 0 OF WD 2.

80
81
82
83
84
85
86

IBIT 0 OF \vD 2.
IGO SET UP NEXT PAIR.
1(;0 SET UP NEXT PAIR.

87
88

INPUT
DZM P\oJhD3

IFILL PAIN WITH

CLA!CMA
LA \.J -1

IFORM WORD PAIR GaUNT
IFORM WOhD PAIR COUNT.

2~HO~S.

E.DIT
>L
>h ENDCHh
>N
>h
>L PTa

ISTAhT ADDhESS.

TAD* PACK
TAD PTa
ISZ PACK

>INSEHT
>EOTTOM

ILESS END ADDhESS.

§~

100
101
102
103
104
105
106
107
108
109
110

.END
>OVEhLAY
INPUT
PFROM
PhO@PTO
PK5CHR

89
90
91
92
93
94

0
(6

• END
EDIT
>TOP
>L ADf{ESS

III

LAC* PACK
>C IADR/ADDRI
LAC* PACK
>LOCATE ••
LAC P:"}hDl
>V OFF
>C Ih./lkl
>PRINT
LAC P~vhDl
>CLOSE

IGET FROM ADRESS.
IGET FROM ADDRESS.
/GET

IR.S'!' WD OF PAR ••

IGET FIRST WD OF PAIR.

EDITOH
>EXIT
MONITOR
$

Figure 6-3B

Hard-Copy Output of Editing Session {continued}

6-5

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

0v0?'0
"'HHH
0r0P'2

R
R
R

~~0~3

040042
44121V'0rt1

1IH1'0P4

~(}005

0~0((16

ftlr0~7

2?0(J0~

22~H~0rt1

R
R
R
R

~41J~43

777773

6Q10(7!3l'!

A
R
R
R
R

0~013

440!i'4?

I6r014

0V015

R
R

-V
IV!004'; V
44"'044 R

0V010

~40044
171

IiW011
0"-012

5409134

fdV016

/dV0l.7
kW020
0I
0-

elr(!~00'"

0~0?1

0"'022
0~023

2?0 42

~4~915P

60~V110

R
R

29'I/W47
744V"10

"'40~47

R
R

2')10046

R
V

A
V
V

A
R
R
R

tJv'027

R
R
R

0V030

740010
060""43
4409:43
6(:\0006
77777?

16" ",31
""032

140f?:50

54~F~44

1,1"033

r:;-

600'i)1'5

~(t034

1dV'035

777777
36V1 .~~(l!

R
R
A
R

0~036

f<'

74~17!i11

~(I("37

340 1)\43

0"040

R
R

6201/1001

R
R
R
A
A
A
A

0Ct:024

IiH'025
0V'026

\1H141
1d!l'042
I(JV043
I(}v044

441J00~

R
R

"'00['001

IJ0I1Jit"eJOI

0~0'''~H?
000~0fi!

ISUBROUTINE PACK, 7-RIT LEFT-ADJ~STED CHARS TO NON-HEADERED lOPS
IASCII. ON RETURr-J, AC HOLDS TOTAL WORDS OCCUPIED BY PACKED ARRAY.
IA WORD OF ALL l'S MUST TERMINAI[ THE INPUT (UNPACKED) ARRAY.
ICALL:
JMS PACK
I
FROM
1ST ART OF INPUT ARRAY.
I
ISTART OF OUTPUT ARRAY.
TO
.GLORL PACK, PRAL7, PWRD1, PWR02, PWRD3
PACK
IG[T FROM ADDRESS.
PACK
'LAC"
"
OAC PFROt-l
IGIVE TO FROM POINTER.
1St PAf;K
IBUMP TO "TO" ADDRESS.
IGET -ADDRESS OF TO ARRAY.
LAC" PACK
OAC PTO
IGIVE TO OUTPUT POINTER.
-LAW 17773
ISfT UP
PLDOP1
DAr. PKC:;CHR
15-CHARACTER COUNTER.
IGfT NEXT WORD IN INPUT ARRAY.
PLOOP2
LAC" PFROM
ITERMINATOR?
SAD ENnCHR
IY[S, GO CLOSE OUTPUT ARRAY.
JMP PCLOSo
IS? PFROt-l
IPOINT TO NEXT WORD.
ISfT UP TO ROTATE.
OAC PWRD3
JMS PR4L7
PLOOP7
!S~ PK'5CHR
15 CHARS IN?
JMP PLOOP2
INO, GET ANOTHER.
IWORO PAIR COMPLETE.
LAC PwRD?
RAL! CLL.
ICLEAR PAIR RIT 35.
DAC PwRD?
IGET FIRST WD OF PAIR.
LAC Pw RD1
RAL
IBIT 0 OF WD 2.
IINSERT FIRST WD IN OUT ARRAY.
DAC" PTO
ISiZ PTO
IRUMP OUT ADDRESS.
JMP PU~OPl
IGO SET UP NEXT PAIR.
IMAKE SURE PAIR IS COMPLETE.
PCLOS
LAw 17773
IFILL PAIR WITH ~EROES.
nl"" PWRD3
SAl) PK'5CHR
JMP PU)QP7
IINCOMPLFTE PAIR.
LAW -1
ENDCYR
IFORM WORD PAIR COUNT.
TAn* PACt<
1ST ART ADDRESS.
CMA
TAli PTn
ILESS ENn ADDRESS.
IS~ PACK
JMP .. PACK
IRE TURN TO CALLER.
III
PFRO"1
PTa
0
PK5C ... R
0
.ENU

Figure 6-4

File Resulting From Editing Session

-c
0
-c
I

-.0
--I

--I

-0
0

- -I

:;::0

PDP-9 TEXT EDITOR

APPENDIX 1
SUMMARY OF EDITING COMMANDS
Editor-Monitor Communication
Command
EXIT

Abbreviation

Activity

Li ne Number*

Section

nla

Transfer control to Monitor.

124

4.24

Line Number

Section

-File Housekeeping
Command

Abbreviation

Activity

OPEN nm ext

nla

Prepare input file (named "nm
ext") for editing.

4. 1

nla

Terminate editing on input fi Ie.

121

4.2

Locative Requests
FIND string

Bring first line beginning with
"string" to work area.

3,68

4.5

LOCATE string

Bring first line containing "string"
to work area.

12,52

4.6

Bring next consecutive Iine to
work area.

15,70

4.3

BOTTOM

Bring last line of file to work area.

100

4.8

TOP

Reset pointer to beginning of file

110

4.14

Print the current Iine on the Teletype

20,58

4.4

Manipulative Requests
DELETE

Discard the current line.

47,61

4.7

RETYPE string

Replace current line with "stringll .

71,94

4.9

INSERT string

Add "string", as a complete line,
to the file after (below) the current
line.

4.10

CHANGE /string 1/string2/

Replace, in the current line, the
first occurrence of "stringl 11 with
"string211 .

25,27,38

4.13

C
OVERLAY

Replace multiple lines.

5, 102

4.16

APPEND string

Add II string II at the rightmost end
of the current line.

14,16,19

4.17

*Entries under II Line Number" refer to line sequence numbers (in Figure 6-3) where examples of command usage are to be found.
A 1-1

PDP-9 TEXT EDITOR

Mode Control
Abbreviation

Command

Activity

VERIFY

{ON
OFF

Set verify mode to print (ON)
or ignore printing (OFF) lines
after processing CHANGE,
LOCA TE, and FIND requests.

BLOCK

{ON
OFF

n/a

Set program to operate in block
mode (ON) or in line-by-line
mode (OFF).

n/a

Set brief mode to print truncated
(ON) or full (OFF) lines

BRIEF

{ON
OFF

Line Number
54,57

Section
---4 . 15

4" 19

37,44

4" 18

Input/Outeut Reguests
READ

n/a

Fill block buffer from input file.

4 . 21

WRITE

n/a

Add block buffer to output fi Ie.

4 . 22

GET

Add Iines from subsidiary input
device after (below) current line.

4 . 12

M isce Ilaneous Regu.ests
SIZE
INSERT

Set total lines to occupy block
buffer.
Change mode to input.

Al-2

4 . 20
30

4 . 11

PIP-9

PIP-9
CONTENTS
Section
INTRODUCTION ................•....................................

DEVICE ASSIGNMENTS .............................................. .

2. 1

I/O Monitor System ..........••.•.•.............•.•........•......

2.2

Keyboard Monitor ....................•..•...•..........•.........

PIP-9 COMMAND STRING: GENERAL ...................•.............

3.1

Operation Character ................•.•....•..•........•....•.....

3.2

Device Name ...•••..•.......•.........................•.........

3.3

Fi Ie Name and Extension .....•.....................................

3.4

Switch Options ........................•..........................

3.4.1

Data Modes ...•...••..•....•....•..........•.................

3.4.2

Subsidiary Operations .........•...............................

PIP-9 FUNCTIONAL DESCRiPTION .................................... .

Operations Under the I/O Monitor .......•..........................

4. 1 . 1

Transfer Fi Ie (T) ......•..•....................................

4.1.2

Verify Fi Ie (V)

....•.............................•...........

4.1.3

Segment Fi Ie (S)

.......•..•..................................

Switch Options Under the I/O Monitor ......•..........•............

4.2.1

Image AlphanumE~ric (I) ...........................•............

4.2.2

lOPS Binary (B) ............................................. .

4.2.3

lOPS ASCII (A) ............................................. .

4.2.4

Bad Parity Correction (G) ...........•..............•...•.......

4.2.5

Tab to Space Conversion (E) ................................... .

4.2.6

Space to Tab Conversion (C) .................................. .

4.2.7

Segment Fi Ie (Y) ...........•.................................

4.2.8

Combined -Fi fe (W) ........................................... .

Operations Under the Keyboard Monitor ..•..•.......................

4.3.1

List Directory (L) .....•.......................................

4.3.2

New Directory (N) ......•..•........•..•..•...•.....•.........

4.3.3

De lete Fi Ie (D) .............................................. .

A.3.4

Rename Fi Ie (R) ............................................. .

4.3.5

Copy Tape (C) ..............•...•............................

4.3.6

Block Copy (B) ............................................ .

Switch Options Under the Keyboard Monitor .......•..................

4.1

4.2

4.3

4.4

iii

CON TEN T S (cont)
Page

4.4.1

Image Binary (H) ....•....•........•............•.............

4.4.2

Dump Mode (D)

............................................ .

4.4.3

New Directory (N) ......•....................................

4.4.4

Create System Directory (S) .....••............................

PDP-9 COMMAND STRING .......................................... .

Transfer Fi Ie (T) ....................................•............

5
5.1
5.1.1

Copyi ng Fi les

5.1.2

Creating Fi les

5.1.3

Listing Fi les

................•....•..........................

5.1.4

Using the G Switch ...............•..........................

5.'1.5

Using the C or E Swi tc hes ..... .... . •........................

5.'1.6

Using the N or S Switch ..................................... .

5.'1.7

Using ,the W Switch ......................................... .

5. '1.8

Using the Y Switch

5.2

Verify Fi Ie (V)

5. ~3

Segment Fi Ie (S) .....•...........................................

5.4

List Directory (L) ...•.............................................

5.5

New Directory (N) ......•................•.......................

5.6

De lete Fi Ie (D)

..................................... '.......... .

5.7

Rename Fi Ie (R) .............•..•.....•...•.......................

5.8

Copy Tape (C)

........•.........................................

5.9

Block Copy (B) ..........•.....•...........•.......... '.......... .

CORRECTION PROCEDURES .......................................... .

6.1

'P (Control Key P) ................................ , ............ .

6.2

Rubout (RO) ..................•..•................. , ............. .

6.3

(Control Key U) .......•......................•................

6.4

PIP-9 Error Detection and Correction ..............................•.

APPENDIXES
Appendix
o ••••••••••

A1-·1

.........................................•...

A2-·1

SUMMARY OF PIP-9 COMMANDS ........•..•..............
2

PIP-9 ERROR MESSAGES

TAB LE S
Table

3-1

PIP-9 Operation Characters ......•....•...................•...•........

3-2

PI P-9 Device Names

.....................•..•........................

4-1

Legal Operation/Switch Combinations .................................. .

4-2

Legal Switch Combinations for Transfer Fi Ie (T) .......................... .

4-3

Legal Operation/Switch Combinations .................................. .

4-4

Lega I Switch Combinations for Transfer Fi Ie ....••....•..........•........

PIP-9

1•

INTRODUCTION
PIP-9 (for Peripheral Interchange Program) is a utility program in the PDP-9 ADVANCED

Software System used to transfer data fi les from one standard peripheral device to another. PIP operates
under Monitor control, using the Monitor I/O device handlers.
Files may be verified, renamed, deleted, combined or split into segments. Entire DECtapes,
or individual DECtape blocks, may be copied and verified.

File directories may be listed or initialized.

Some of these functions and other subsidiary functions may be combined by inserting optional switches
when the user types a command string to PIP-9.
The following peripheral devices may be used as either input (source) or output (destination):
Mnemonic
DECtape (TC02 Control Unit with TU55 Transports)

DTn

Paper Tape Reader/Punch (PC02)

PR (Reader)
PP (Punch)

Line Printer (Type 647) (output on Iy)

Teletype (KSR 33 or KSR 35)

Card Reader (CROl E or CR02B)

Later versions of PIP-9 will also transfer fi les on magnetic tape and disk.
2.

DEVICE ASSIGNMENTS
Before using PIP, the user mus't be sure that the peripheral devices he plans to use are as-

signed to positive slots in the Monitor1s Device Assignment Table. This is for use by PIP. When typing
his command string, the user specifies devices by writing mnemonic codes, such as DT2, PR or TT.
2. 1

I/O Mon i tor System
In paper tape I/O Monitor systems, where the Device Assignment Table is fixed, the user

need not be concerned with. DAT slot assignments.

Line Printer and card reader users must be certain

that the appropri ate handlers are inc luded in their systems.
2.2

Keyboard Monitor
In Keyboard Monitor systems, the user must be sure that the devices he will use are assigned

. DAT slots. He should use the Monitor REQUEST PIP command to get a typeout of all current. DAT slot
assignments. If a device he plans to use is not listed, he may use an ASSIGN command to assign that
device to any positive .DAT slot, with the exception of .DAT slot 1 which must always be assigned to
the system device. The most complete handler, (e.g. DTA, PPA, etc.), must be assigned. If the same
device is to be used as both the source and destination device, it must be assigned to two .DAT slots.

PIP-9

Since these • DAT slot assignments are for use by PIP, they need not be remembered by the
user. Systems distributed by DEC initially have the assignments shown below in Table 2-1.
Table 2-1
Initial .DAT Slot Assignments
.DAT Slot No.

Assignment

1
2
3
4
5
6
7

DTAO
DTAl
DTA2
TTAO
PRAO
PPAO
DTAl
DTA2

PIP-9 COMMAND STRING: GENERAL
Once in core memory, whether in an I/O Monitor or Keyboard Monitor environment PIP-9

informs the user of its readiness to accept keyboard commands by outputting the following on the
teleprinter:
PIP

>
The user may then type a command string to PIP-9 on the same line as the right angle bracket (».
Successful completion and readiness for the next command is normally acknowledged by "CR, LF, >"
unless there has been intermediate output to the teleprinter by PIP. In the latter case, the initial
response (PIP, CR, LF, » is output once again for ease of later printout examination. PIP commclnd
strings are of the following general form:
a ddf :

lfnamef

~PAC~

where,

lext (x) .... sdr

~PACEJ

: Jfnamer

~PACE

lext (x)r~
It,LT MOD~

~PAC~

a = A single letter, specifying a PIP operation.
dd = the destination device
fname = fi Ie name
ext = fi Ie name extension
(x) = letter(s) specifying a PIP switch option(s).
sd = source device

The left arrow (4--) terminates information concerning the destination device. Data for the source
device follows the 4--. CR or ALT MODE must terminate a command string. ALT MODE forces PIP-9
to return control to KM-9 upon successful completion of the command. CR causes PIP-9 to wait f()r an-other command upon completion of the current one.

PIP-9
Multiple spaces are ignored by the command string processor. In fact, delimiters are
absolutely required only following the operation character, device names and file names.
Example:

TL....JDT1L-JNEWNAM BIN (B)"'-L..JDT2L...JOLDNAML-IBIN#

DT1:NEWNAM;BIN

(B)+- L..JDT2:0LDNAM;BIN~

The elements in the preceding example are:

PIP-9 Transfer Fi Ie operati on

DT1, DT2

DECtape 1 is the destination device,
DECtape 2 is the source device.

NEWNAM, OLDNAM

File names

BIN

Fi Ie name extension
Transfer direction indicator (right to left,
i • e ., DT2 to DT 1)

B
3. 1 i

Switch option

Operation Character
The first character in a PIP-9 command string must be an operation character defining the

main function to be performed. It must be followed by a space. Legal operational characters are
listed in Table 3-1 below.
Table 3-1
PIP-9 Operation Characters
(T)
(L)
(D)
(C)
(R)

3.2

(V)
(S)
(B)
(N)

Transfer Fi Ie
List Directory
Delete File
Copy
Rename File

Verify File
Segment Fi Ie
Block Copy
New Directory

Device Name
Because the PDP-9 ADVANCED Software System provides more than one device handler for

some peripherals, a 2-letter mnemonic (corresponding to the first two letters of the handler name) is
used for device name specification in PIP. Table 3-2 lists legal device names. For multi-unit peripherals, e.g., DECtape, the unit number, 0-7, appears after the device manemonic, e.g., DT7. The
device name delimiter must be a colon (:) or a space.

3 '

PIP-9
Table 3-2
PIP-9 Device Names
(PR)
(PP)
(TT)
(LP)

3.3

(DT)
DECtape
(MT) Magnetic Tape

Paper Tape Reader
Paper Tape Punch
Teletype
Line Printer

(CD) Card Reader
(DK) Disk

File Name and Extension
File name and extension, if used, constitute one element of the command string, where the

file-name delimiter is a semicolon (i) or space. If the extension is omitted, the default assumption is
three null characters. If more than one file name is specified, the second, third, etc., are separated
from earlier names by commas ( , ). If the device is not a file-oriented device, fi Ie names may bE!
omitted. Commas, however, must still be used for file count purposes. Some examples of device, file
name and fi Ie-name extensions follow:
DT5: FILEA, FILE B;SRC

(2 fi les)

or DT5 FILEA, FILEB SRC

PR:"

(3 files)

or PR "

PP:

(1 file)

or PP

A file name is a string of up to six (6) alphanumeric characters. Any printing character in
the ASCII set may be used with the exception of a space, (:), (i), (,), (0 and 0), which have a specific
delimiter meaning to PIP. The fi Ie-name extension may be up to three (3) characters long.
3.4

Swi tch Options
Switch options are enclosed in parentheses and require no delimiters to separate them from

each other. They may appear either with the destination device information or wHh the source device
information. PIP-9 switch options are divided into two classes: (1) data modes and (2) subsidiary
operations.
3.4. 1

3.4.2

Data Modes
(A)

lOPS ASCII

(B)

lOPS Binary

(I)

Image Alphanumeric

(H)

Image Binary

(D)

Dump

Subsidi ary Operations
(G)

Correct Bad Parity/checksum lines

(E)

Convert tabs to spaces

PIP-9

(C)

Convert multiple spaces to tabs

(S)

Create new system directory

(N)

New directory

(Y)

Segment fi Ie

(W)*

Combine several source files, or tapes, stripping • EOT's and
.END's from intermediate tapes.

(W)*
4.

Comgine several binary files, stripping EOF's from intermediate files.

PIP-9 FUNCTIONAL DESCRIPTION
Functionally, PIP-9 may be described in terms of operations which may be specified and

subsidiary switch functions requested as a part of a given operation. All PIP-9 operations and switches
which are valid in the I/O Monitor paper tape system are also valid in the Keyboard Monitor system.
The converse is not true, however.
4. 1

Operations Under the I/O Monitor
Three PIP-9 operations are provided in an I/O Monitor environment: (1) Transfer Fi Ie,

(2) Verify Fi Ie, (3) Segment File.

4.1.1

Transfer Fi Ie (T) - T performs basic data or fi Ie transfer from one I/O device to another. In

an I/O Monitor environment T is used to copy paper tapes and list paper tapes or card decks on the
Teletype or line printer. T also provides the ability to create a source file by transferring from Teletype
to paper tape punch. Paper tapes may be combined into one paper tape or segmented (lOPS ASCII tapes
only) into several tapes.

4.1.2

Verify File (V) - The V operation allows parity and/or checksum verification of paper tapes.

This function is particularly useful for verifying paper tapes copied with the T command.
4. 1 .3

Segment File (S) - The S operation provides a means for segmentation of source paper tapes

whose unwieldy bulk makes two or more smaller tapes desirable. All PIP-9 operation commands are
independent of other commands except Segment which is used prior to a Transfer command in order to
specify at what points in the source file segmentation is to take place. The S command string allows
for up to sixteen segmentation points or character strings (1-5 characters) at the beginning of lines at
wh ich segmentation is to take place. The file is terminated just prior to the segmentation point after a
• EOT is appended. Transfer continues to the next segmentation point and so on.

* . END and. EOT on the final ASCII tape and EOF of the final binary tape are retained.
5

PIP-9

4.2

Switch Options Under the I/O Monitor
The data mode switches which may be used in an I/O Monitor environment are:
(A)

lOPS ASCII

(B)

lOPS Binary

(I)

Image Alphanumeric

Function switches for use under the I/O Monitor are:
(G)

Correct bad parity lines

(E)

Convert tabs to spaces

(C)

Convert multiple spaces to tabs

(Y)

Segment fi Ie

(W)

Combine files

Switch options may be used for some operations and are meaningless for other operations.
Table 4-1 lists legal options by operation in an I/O Monitor environment. Furthermore, certain switch
options conflict, e.g., combining the option to convert tabs to spaces (E) and spaces to tabs (C) is
clearly a conflict. Table 4-2 lists legal switch combinations for the primary PIP-9 operation, Transfer
File.
Table 4-1
Legal Operation/Switch Combinations
Operation

Legal Switches

Transfer File (T)

A,B,I,E,G,C,W,Y

Verify File (V)

A or B

Segment File (S)

(None)

Table 4-2
Legal Switch Combinations for Transfer File (T)
Switches

I
I
I
I

E
G
C

/
j

../

I
I
I

PIP-9

4.2. 1

Image Alphanumeric (I) - The (I) data mode permits copying of any paper tape but, in

particular, (I) must be used when copying tapes which are in Hardware Read-in Mode (HRM or RIM
tapes). Thus MACRO-9 .ABS or • FULL tapes require the (I) data mode.
4.2.2

lOPS Binary (B) - Relocatable binary tapes are reproduced using the binary data mode (B).

4.2.3

lOPS ASCII (A) - PDP-9 source tapes are normally copied using the (A) data mode. It should

be noted, however, that use of the (A) mode will result in lOPS ASCII paper tapes having even parity
in channel 8 of each frame. (See Section 2. 1 .2. 1 of the PDP-9 Monitor Manual, DEC-9A-MAAO-D
for a detailed discussion of lOPS ASCII.) If for some reason this is undesirable to the user, a data mode
of (I) is recommended.
4.2.4

Bad Parity Correction (G) - Whenever data modes (A) or (B) are specified during a Transfer

command, PIP-9 automatically verifies the correctness of parity and/or checksum. The G switch,
used with lOPS ASCII mode only, allows the user to modify erroneous input I ines via teletype keyboard
input. User intervention may take one of three forms: (1) the line may be deleted, (2) the line may be
accepted, or (3) the line may be replaced from the keyboard. The option to restart ("P) is always
available.
4.2.5

Tab to Space Conversion (E) - The E switch allows for conversion of horizontal tabs to spaces

in order to allow off-line listing of ASCII tapes on Model 33 Teletypes. It is used with lOPS ASCII
tapes. Since lOPS (Input/Output Programming System) follows a tenth position tab setting convention,
enough spaces are substituted for a tab to place the next printing character of the line in position 10,
20, 30, etc.
4.2.6

Space to Tab Conversion (C) - In order to condense an ASCII paper tape the C switch is used

to convert multiple spaces on an input file into horizontal tabs on the output file. Trailing spaces are
simply deleted. Again, C is legal only when used with the (A) data mode.
4.2.7

Segment File (Y) - In order to apply the ~egment operation during a !.ransfer file command,

a (Y) switch is required in the T command string. On the basis of the (Y) switch the lOPS ASCII input
file is segmented into the number of output files specified in the preceding S command.
4.2.8

Combine Files (W) - Although combining files or a series of pap_er tapes into one file is most

common when !.ransferring from paper tape to a mass storage medium, it is possible to combine several
small paper tapes into a single larger paper tape by indicating a W switch in a T command. Either lOPS

PIP-9

binary or ASCII tapes may be so combined. For binary files, all but the final EOF block of the input
tapes are discarded on output.

Likewise, when combining a series of lOPS ASCII paper tapes, all .EOT's

and .END's are stripped except that of the final input tape.
4.3

Operations Under the Keyboard Monitor
The presence of mass storage devices in a PDP-9 configuration allows additional opercltions

with PIP-9. In addition to the .!ransfer ~erify and ~egment fi Ie operation, the following are aV<li labl e:
I

(1) ~ist Directory, (2) ~ew Directory, (3) Qelete Fi Ie, (4) ~ename Fi Ie, (5) ,Sopy Tape, and (6) !~Iock

Copy.
4.3. 1

(Additional switch options also become available.)
List Directory (L) - The directory of any file-structured mass storage device may be lisf'ed on

teleprinter or line printer with the L command. The file name, extension, starting block number ·and
number of blocks occupied, are printed along with the number of free blocks remaining.
4.3.2

New Directory (N) - The N command provides recording of a fresh directory on a mass

storpge device. In the case of DECtape, the Fi Ie Bit Map blocks are cleared and the Directory block
is initialized to indicate only the File Bit Map and Directory blocks as occupied.
4.3.3

Delete File (D) - To delete one or more named files from a mass storage device, the D operCJ-

tion is employed. Deletion impl ies removing references to the fi Ie from both the Directory and Fi Ie Bi't
Map blocks.
4.3.4

Rename File (R) - Renaming one or more files requires an R command. Only the name t:md

extension in the Directory are changed.
4.3.5

Copy Tape (C) - This function provides a convenient means of reproducnng tapes (especially

system tapes) in their entirety. Programmed read-after-write verification is performed. Differenc:es in
file structuring will be accounted for in the transfer from one type of device to another.
4.3.6

Block Copy. (B) - The block copy operation is used with DECtape when copying one or more

blocks seems desirable, e.g., when one or a few blocks on a tape seem suspect after a copy opercltion.
The B operation obviates the need to recopy an entire tape.

Blocks to be copied and verified are

specified by their octal block number (0-1077).
4.4

Switch Options Under the Keyboard Monitor
Four additiona I switch options are avai lable in a Keyboard Monitor environment. Two are

data modes: Image Binary (H) and Dump Mode (D). Two are subsidiary functions:
and Create System Directory (S).

New Director}' (N)

PIP-9

Tables 4-3 and 4-4 summarize legal switch/operation combinations within a Keyboard
Monitor environment.
Table 4-3
Legal Operation/Switch Combinations
Operation

Legal Switches

Transfer Fi Ie (T)

A, BI I I H,D I EI G I C I W, Y,N I S

Verify Fi Ie (V)

A or B

Segment Fi Ie (S)

(None)

List Directory (L)

N or S or None

New Directory (N)

(None)

Delete File (D)

(None)

Rename Fi Ie (R)

(None)

Copy Tape (C)

N or S or H or None

Block Copy (B)

N or S or None

Table 4-4
Legal Switch Combinations for Transfer File
Switches

j
j
j
j

4.4.1

..;
~ J
J ~ J j
j
~ j

J
J

j
I ~
/
~ j

j
j

~
~

Image Binary (H) - The reader is referred to Section 2.1.2 of the PDP-9 Monitor Manual for

a discussion of data modes. The use of Image Binary as a data mode on mass storage devices such as
DECtape or disk implies the intent to retain the exact form of the binary data as it originally appeared
in hard copy I e.g. I paper tape or cards such that I at a later time I the original data may be retrieved
(ance again onto paper tape) I without alteration. It should be noted again that use of Image ASCII will
always exactly reproduce an identical tape whether or not DECtape or disk has been used for intermediate
storage (see Section 4.2.1).

PIP-9

The meaning of Image Binary as a switch option with the Copy (C) function is expanded
beyond its customary meani ng to imply a block by block DECtape copy.

Later examples wi II i Ilu~;trate

this use of H mode.

4.4.2

Dump Mode (D) - Files recorded in dump mode may customarily be expected to reside on a

mass storage device. Hence, D is used as a data mode most frequently when transferring to and from
mass storage. There is no restriction on its use from mass storage to paper tape or vice versa, however.

4.4.3

New Directory (N) - The N swHch option, like the N operation, initializes the Directory

of the destination device. Permitting its use as a switch provides the added convenience of combining
operations in a single command string.

4.4.4

Create System Directory (S) - The S switch constructs a basic system tape on the destination

device prior to executing the main operation of the command string. The system tape must be mounted
on unit 0 and OAT slot one (1) must be assigned to the system device in order to use the S switch.

Basic

system tape refers to the Directory, File Bit Maps, all absolute system programs and the relocatable
system files: DDT9, .LOAD, .LIBR, INTEGE EAE, INTEGE NON, REAL EAE, and REAL NON.
5.

PIP-9 COMMAND STRING
This section illustrates PIP-9 commands and usage in detail. Since reference is made in

earlier sections to I/O and Keyboard Monitor environmental differences, no further mention is made
here. Examples are given without the optional (:) and semicolon (;) delimiters for use of which the
reader may refer to Section 3, page 3.
5. 'I

Transfer File (T)
Under the T command are inc luded the tasks of listing, copying, creating, combining cmd

segmenting files. An input and an output device are required in the command string as well as one of
the five (5) data modes. File names must be specified only for file structured devices.

5. 1 • 1

Copying Fi les - The command:
T DT7 FILEA SRC (A) ___ PR,J

copies a single tape from the paper tape reclder to DECtape unit 7 in lOPS ASCII mode.
The command:
T DT7 FA SRC,FB SRC,FC SRC (A)4- PR I I;
transfers three paper tapes as three separate files named FA SRC, FB SRC, and FC SRC.

PIP-9
The command:
T DT2 FILNEW BIN (B).--DT1 FILOLD BIN~
not only transfers FILOLD BIN from DECtape unit 1 to 2 but also renames the file: FILNEW BIN.
5. 1 .2

Creating Fi les - Creating a fi Ie is normally an Editor function.

However, a T command from

Teletype to any output device is perfectly legitimate. It should be kept in mind, however, that correction faci lities provided by an Editor are not in PIP-9.
The command:
T PP (A) 4 - TT ~
directs PIP-9 to accept the input from Teletype to be punched on paper tape. To terminate file creation,
a final line consisting of
5.1.3

D (Control Key D) must be typed.

Listing Fi les The command:
T LP4--DK FIlNAM SRC (A)

lists FILNAM SRC on the line printer. lOPS ASCII is the only permissible mode to the line printer.
Both lOPS and image ASCII are acceptable to the Teletype, the alternate listing device.

5.1.4

Using the G Switch - PIP-9 normally examines the correctness of parity and checksum when

data mode A or B is specified. Transfer is discontinued after display of one of the two following messages
on the Teletype:
INPUT PARITY ERROR
INPUT CHECKSUM ERROR

The G switch allows for user correction of an ASCII line with bad parity. It may only be used with
data mode A. Consider the following example:
T DT7 FILEA SRC (AG)----PR~
is fyped.

During transfer bad parity is encountered and the input parity error message is output on the

Teletype followed by the line in error. The user may:
(1)

Accept the line by typing a carriage return.

(2)

Delete the line by typing D~

(3)

Retype the line, terminating with a carriage return.

(4) Abort the operation by typing

P to restart PIP-9 or

+C to reload the Keyboard

Monitor.
5.1.5

Using the C or E Switches - The C or E switch may be used only with A as the data mode.

C and E may not be used together.

PIP-9

The command:
T DT7 FILEA SRC (AC).-PR,l
effects a transfer from paper tape to DECtape during which process all multiple spaces are converted
to tabs and trailing spaces are deleted.
The command:
T PP (AE)4-DT2 FILEB SRC*
effects a transfer of FILEB SRC from DECtape unit 2 to the paper tape punch during which process all
tabs are converted to spaces allowing listing of the file on an off-line Teletype which lacks a tabbing
mechanism.

5.1.6

Using the N or S Switch - Initializing the directory of certain mass storage devices, e.g.,

DECtape, is a frequent operation. The N switch allows initialization within the context of a File
transfer. S is the only switch which conflicts with N.
The command:
T DT4 FILEA IMG (IN)~PR~
inHializes the Directory and File Bit maps of DECtape unit 4 and, subsequently, l"ransfers the paper tape

fi Ie to DECtape in image ASCII mode.
Given a DAT slot 1 assignment of DT AO and PDP-9 Advanced Software System tape on DECtape unit 0, the command:
T DT4 FILEA BIN (BS)4-PR,\
copies system programs and Directory information from DECtape unit

to unit 4 prior to transferring

FIlEA BIN from paper tape to DEC tape.

5.1.7

Using the W Switch - Source fi les are frequently of such size as to require several paper

tapes. Although they may be maintained on a mass storage device in segmented form, it is more often
desirable to combine the segments into one fi Ie. The W switch performs this function. It is legal with
data modes A or B and conflicts with the Y switch.
The command:
T DT1 FILEA SRC (AW) 4 - PR"" ~
trcmsfers five (5) ASCII paper tapes to DECtape unit 1 as the single file, FILEA SRC. Because inl"ermediate. EDT or • END pseudo ops are no longer useful, all but the one on the final tape are deleted
duri ng transfer.
Used with a data mode of B, the W switch provides a convenient way to combine several
binary subprograms into a single file such as a library fi Ie.

PIP-9
The command:
T DT6 LIBRY BIN (BW)4-DT1 A BIN,B BIN,C BIN;
combines the three (3) binary files, A BIN, B BIN and C BIN into one file LIBRY BIN, deleting intermediate End-of-Files in the process.

5.1.8

Using the Y Switch - In contrast to the W switch which combines files, the Y switch is used

when ASCII file segmentation is required. It is used only with data mode A and confl iets with the W
switch.

Given a sizable source file on mass storage which is to be segmented, the command:
T PP"", (AY) 4--DT1 FILBIG SRC*

wi" result in FILBIG SRC being split up into six (6) paper tapes where five (5) segmentation points must
have been specified in an S operation immediately preceding the current T command string (see Section

5.3, p.20).
The command:
T DT3 FA SRC,FB SRC+-DK FILBIG SRC (AY)~
similarly segments the disk file FILBIG SRC into two smaller DECtape files, FA SRC and FB SRC. The
preceding S operation will have specified one segmentation point.
As each output file is closed, PIP-9 will output on Teletype

+P which is the restart request.

The purpose for th is is to allow dismounting of tapes or removal of tape from the punch. Clearly, if the
file was so large as to require segmentation, time for operator management of the segments seems appropriate.

5.2

Verify File 01)
File verification is performed in either lOPS ASCII (A) or lOPS binary (B) data modes.

other switch options apply to the verify operation. Since there is no output, only the input device (and
file name if a file structured device) need be specified.
The command:

V PR (B),l
requests parity and checksum verification of one binary paper tape. If a parity error occurs, the following message is typed:
INPUT PARITY ERROR

If checksum fai lure:
INPUT CHECKSUM FAILURE
For an ASCII file, the error line is also printed. In either case, after the message is printed, verification continues until the entire file has been examined allowing the user to assess how many errors are
present.

PIP-9

Multiple files may be verified in a single command string. For example, the command
V DT3 FILEA SRC,FILEB SRC (A)~
requests verification of both FILEA SRC and FILEB SRC.
5.3

Segment Fi Ie (S)
The S operation allows specification of up to sixteen fi Ie segmentation points. Device nam4~S,

fi Ie names and switch options are all meaningless in the S command.
The segmentation points are specified as 1 to 5 character strings.

In the subsequent T c:om-

mClnd, if a Y switch is specified, PIP-9 will examine the beginning of every line for the specified seg-·
mentation points in order of occurrence. Vertical form control characters at the beginning of a Iline
are exc luded from the string search. As each segmentation point is found, PIP-9 wi" c lose the CIJrrenir
output fi Ie segment, appending the pseudo op, • EOT, at the end of the segment. The next segmemt wii"
start with the line which begins with the current segmentation point.
The command:
S TAGA, TAGB, TAGC, TAGD,J
sets up the four segmentation points TAGA, TAGB, TAGC, and TAGD for the immediately following
c6mmand:
T PP" 1 / (AY) +-DT3 FILBIG SRC~
the end result is five paper tapes, all but the last of which are terminated with .EOT. The last four
begin with the lines TAGA---, TAGB---, etc.
As each segment is completed,

+P will be output on the teleprinter allowing time to rE!mOVE!

the paper tape segment, dismount tapes, etc. When ready to continue, the user simply types CTRL P
and PIP-9 resumes segmentation.
5.4

List Directory (L)
The Directory contents of any file structured device may be listed by the L operation. The

N or S switch options may be used.
The command:
L TT4-0T1 ~
results in a printout such as the one below:
DIRECTORY LISTING
MACRO ONE

of File
4¥' 2264-#1stofBlock
Blocks Occupied

MACRO TWO

140

MACRO SRC

365

4 SYS PGM BLKS
121 FREE BLOCKS

PIP-9

5.5

New Directory (N)
Although the N function may be performed as a switch option in the command string of

another operation, it has proven useful to include it as a distinct operation.

No switch options are

used with the N command and only the destination device need be specified.
The command:

N DT4,l
results in a fresh directory on DECtape unit 4, a listing of which (as requested by an L operation) will
appear as follows:
DIRECTORY LISTING
4 SYS PGM BLKS
1074 FREE BLOCKS
The four system program blocks are the Directory and three File Bit Map blocks.
5.6

Delete File (D)
File deletion is performed by the operation, D. Only the destination device is specified.

No switch options are used.
The command:
D DT3 FILEA, FILEB~
causes PIP-9 to delete both FILEA and FILEB from DECtape unit 3.
5.7

Rename File (R)
The R command is used to rename files on a file-structured device without data transfer of

~ny kind.

No other unit is needed although the device name must appear with both source and destina-

tion data. A simple 9-character name substitution takes place into the directory entry section of the
directory block. All switch options are illegal.
The command:
R DT2 NEWNAM BIN4-DT2 OLDNAM BIN*
changes the name of the file OLDNAM BIN ON DECtape unit 2 to NEWNAM BIN.
5.8

Copy Tape (C)
Copying the contents of one file-structured device onto another implies one of two tasks:

(1) incorporation of all information on the input device into the organization and content of the output
device or (2) total replacement of all information on the output device by information on the input device. The latter is performed by the C operation in conjunction with the H data mode switch.
The command:

PIP-9
replaces all data on DECtape unit 5 with data from unit 3 in a block by block copy and read after
write.
Incorporation is effected in one of the following three ways:

(1) Absence of switch options in the C command:
C DT54-DT3#
All fi les on DT3 wi II be incorporated into the fi Ie organization of DT5.
(2)

Use of the N Switch:
C DT5 (N) ..e-DT3,\

Prior to transferring the files on DECtape unit 3 to unit 5 the Directory and File Bit MClps
of unit 5 will be initialized.
(3)

Use of the S Switch:
C DT5 (S) -4- DT3

After copying the system from the system device onto DECtape unit 5, the files on
unit 3 will be transferred to unit 5. PIP assumes that DAT slot 1 is assigned to the
system device.
5.9

Block Copy (B)
To copy one or more blocks of one DECtape onto another, the B command is used. Sw'itche:s

N or S may be employed within command string also. Instead of specifying file names, actual octal
block numbers (0-1077) are given in the command string. These block numbers may appear either with
the destination or source data and are separated by commas.
The command:
B DT7..- DT4 5,15, 165, 1075#
or
B DT7 5,15, 165, 10754-DT4~
requests copy and verification of blocks 5,15,165 and 1075 from DECtape unit 4 to unit 7.
The command:
B DT2 10,15..e-DTl 4,3;
requests blocks 4 and 3 of DECtape unit 1 to be copied (and verified) onto blocks 10 and 15 of DECtape
unit 2 respectively.
6.

CORRECTION PROCEDURES
Four correction procedures are avai lable to the user in h is operation of PIP-9. The procedure

chosen is largely a function of what point in the PIP-9 process the user decides to correct or somehow
modify PIP-9 action. Aborting a task is the most drastic procedure. Deleting one or more characters
in a command string, negating the entire command string, or responding with corrected command strin~,
information after a PIP-9 error message are others.

PIP-9
6. 1

+p (Control Key P)
A task may be aborted and PIP-9 restarted by typing in the

any time.

tp (control key P) character at

+p has a secondary use in PIp·-9 wh ich is to indicate loading of the next in a series of paper

tapes or output of the next in a series of fi les during segmentation. For example, at the end of each of
several paper tapes to be combined into one output file, PIP-9 will typetp on the teleprinter directing
the user to load the next paper tape. When ready, the user types
6.2

for PIP-9 continuation.

Rubout (RO)
During typing of a command string, one or more characters may be deleted by use of the

rubout (RO) key. For each character deleted, starting with the last one typed, a back slash (\) is
echoed. For example:
T ZT3~DT3 FILEA (A)4--PR*
The character Z is in error. Three rubouts have been used to back up to the erroneous character.
6.3

+U (Control Key U)
At any point while typing a command string, that is, prior to the CR or ALTMODE, a

may be typed to delete the entire command string up to that point. An "at" sign (@) is echoed. The
user may then start from the beginning of the command string again.
The command:
T ZT3@T DT3 FILEA (A)4- PR,l
demonstrates a
6.4

+U correction.

PIP-9 Error Detection and Correction
Once a command string is completed, PIP-9 may discover erroneous information. When this

occurs, an appropriate error message is output to the teleprinter and the questionable command string
is output up to but not including the offending character or element followed by "? ", requiring correct
completion by the user. If the user prefers to retype the command, a carriage return or

+p will in this

instance signal PIP-9 to accept a new command from the beginning. The characters RO and

+U may

not be used since the Teletype handler (which no longer has access to the erroneous command string)
and not PIP-9, interprets and acts upon RO and

tU.

Appendix II contains a complE~te list of PIP-9 error messages. Hence only two examples are
cited here. Suppose a user intends to transfer an lOPS ASCII file from paper tape to DECtape. He
types:
T DT2 FI LEA SRC (F) 4 - PR

PIP-9

Recognizing F as an illegal switch option, PIP-9 types:
INVALID SWITCH OPTION
T DT2 FI LEA SRC(?
The user may complete the command string from the erroneous character or element on to the end, or
use a

+p to indicate he prefers to restart the message.
If a DECtape handler and unit are not assigned to any of the positive • OAT slots, PIP-9

would type in response to the above example:
DEVICE (UNIT) NOT ASSIGNED TO POSITNE .DAT TABLE
T?
to indicate that the command was in error (could not be honored due to absence of the necessary • OAT
assignment) at the point of the device and unit specification code.

PIP-9
Appendix I
Summary of PIP-9 Commands
I/O Monitor Environment:
Source Dev.

File Names

Command

Abbrev.

Dest. Dev.

Transfer File

Yes

Verify File
Segment Fi Ie

V
S

No
No

Yes
No

No
No*

Legal Switches
A,B,I,E,
G,C,W,Y
A or B
None

Keyboard Mon itor Env ironment:
Command

Abbrev.

Dest. Dev.

Transfer Fi Ie

Yes

Verify File
Segment Fi Ie
List Directory
New Directory
Delete File
Rename File
Copy Tape
Block Copy

V
S
L
N
D
R
C
B

No
No
Yes
Yes
No
Yes
Yes
Yes

File Names

Legal Switches

Yes

Yes
No
Yes
No
Yes
Yes
Yes
Yes

Yes
No*
No
No
Yes
Yes
No
No**

A,B,I,H,D,E,
G,C,W,Y,N,S
A or B
None
Nor S
None
None
None
N or S or H
Nor S

Source Dev.

*Segmentation points instead of file names.
**Block numbers instead of file names.

Al-l

PIP-9
Appendix II
PIP-9 Error Messages

Command String Too Long, Try Again

Retype command stri ng

III. Function

Retype from function character on.

III. Dev. or Unit
}
III. Dev. or Unit Terminator
Dev. III. for Option or Function and Direction

Retype from device name on.

Dev. (Unit) Not in + DAT Table }III. Sys. Dev. in DAT Slot 1

Type+C to restore
Monitor and perform ASSIGN

Sys. Tape Not on Unit 0

Mount System Tape on Unit 0 and retype command
string.

Too Many Files or Blks., Try Again

Retype command string

Too Many Chars. in File or Ext. Name}
Source Fi Ie Not on Dev.

Retype from Fi Ie Name
on.

Too Many Source Fi les
Too Many Dest. Fi les

}

Check number of fi les actually transferred and
type another command string to -transfer remainder.

Data Mode Needed

Type data mode in parentheses followed
by carriage return

Switch III. for Dev.
)
III. Switch
Switch Conflict
Switch III. for Function

Retype from swi tch on.

III. Terminator

Retype from term i nator on.

Input Pari ty Err.

If binary, check data.
If ASCII, retype command string using G switch.

Input Checksum Err
}
ASCII Input Line Too Long
,
#
III. Blk.

Check data
Retype from block # on.

Read - Compo Err. on Blk. n

When operation complete, try B function
on error block.

S Operation Not Performed

Execute S operation; then retype T command.

Strings 1 to 16 Accepted

Perform segmentation; then further segment
last destination file.

Too Few Dest. Fi les for # of Segment Points

Retype command string with correct # of destination fi les. (1 more than # of segmentation points).

A2-1

'. LINKING LOADER

LINKING LOADER
CONTENTS
Section

INTRODUCTION .••••••••••.•••••••••••••••••••••••••••••••••••••••

1-1

DESCRIPTION .•••••••••••••••••••••••••••••••••••••••••••••••••••.•

2-1

INFORMATION UNITS •••••••.••••••••••••••••••••••••••••••••.•••••

3-1

IDENTIFICATION CODES .•••••••••••••••••••••••••.••••••••••••••••.

4-1

MAIN PROGRAM ORGANIZATION •••••••••••••••••••••••••••••••••••

5-1

5. 1

Subprogram Organization .•••••••.•••••••••••••••••••••••••••••••.

5-2

5.2

Block Data Subprogram Organization •••••••••••••••••••••••••••••••

5-3

DE FINITIO NS ••••••••••••••••••••••••••••••••••••••••••••••••••••••

6-1

LINKING LOADER OPERATING PROCEDURES .•.•••••••••••••••.•••••••

7-1

I/O Monitor Environment •••••••••••••••••••••••••••••••••••••••••

7-1

7. 1 • 1

Structure of System Library .••.•••••••••••••••••••••••••••••••

7-2

7.1.2

Loader Memory Map .••••••••••••••••••••••••••••••••••••••••

7-2

7.1.3

Error Messages .•.••••••••.••••••••••••••••••••••••••••••••••

7-3

Keyboard Monitor Environment •••.•.•.••••••••••••••••••••••••••••

7-4

7. 1

7.2
8.

MEMORY MAPS .•••••

•••••••••••••••••••••••••••••••••••••••••••••

8-1

8. 1

I/O Monitor Environment .••••••.•••••••••••.•••••••••••••••••••.•

8-1

8.2

Keyboard Mon i tor Env ironment •••••••••••••••••••••••••••.••••••••

8-3

A-1

SYMBOL CONCATENATION - RADIX 508 FORMAT •••.••••••.••.••••••.

A1-1

A-2

LOADER SYMBOL TABLE ..•.•••.•••••••••••••••••••••••••••

A2-1

iii

0.•••••••••

LINKING LOADER

SECTION 1
INTRODUCTION
This document describes the operation of the Linking Loader and the composition of the binary
information which comprises a loadable program unit.

Operating procedures for the I/O Monitor and

Keyboard Monitor environments are included along with memory maps of the various phases of loading by
the Linking Loader.

1-1

LINKING LOADER

SECTION 2
DESCRIPTION
The Linking Loader loads and Iinks relocatable or absolute binary program units as produced
by the FORTRAN IV compiler and the MACRO-9 Assembler.

Absolute and relocatable coding should

not be intermixed in one unit, and care should be taken in I inking relocatable and absolute units.

For

FORTRAN and Assembler generated program units, the Loader also assigns the common data storage area.
The input medium may be any input device.
Initially the loader will load ail the program units whose names appear on the command
string (see operating procedures, section 7). After all the programs named by the command string
have been loaded, the Loader automatically loads and links all requested and unresolved librarysubprograms.

The requested I ibrary subprograms are loaded from the external I ibrary and the system I ibrary (in

that order).

After both libraries have been examined for requested subprograms, the loader displays the

If the user requires I/O handlers that are already

names of all subprograms which have not been found.

in core for Linking Loader purposes, the resident handlers will be used.
As individual program units cannot be executed if the program flows across an 8K memory
bank, the Loader will prevent this type of loading.
gram in the next memory bank.

The Loader will, however, load (and link) the pro-

No checking of this type is made with absolute binary program units.

Optionally, symbols and their absolute definitions are loaded into a program dictionary for
use by the on-I ine debugging package (DDT).

The loader also sets up for DDT the start execution ad-

dress of the main program ( in the system communication tables) and the initial relocation value of all
the program un its.

2-1

LINKING LOADER

SECTION 3
INFORMATION UNITS
The binary output from the FORTRAN compiler and the MACRO-9 Assembler consists of blocks
of information units.
(18 bits).

Each information unit consists of an identification code (6 bits) and a data word

The form of the object program at run time is determined by the content and the ordering of

the information units.

Several information units may be grouped to convey a single run-time instruction

to the Loader.
A block of information units consists of four 18-bit machine words arranged in the following
manner:

o
Word 1

5 6
Code 1

11 12
Code 2

Word 2

Data Word 1

Word 3

Data Word 2

Word 4

Data Word 3

Code 3

Standard lOPS binary I ine sizes (48 information words and a 2 word header) are input by the Loader.

3-1

LINKING LOADER

SECTION 4
IDENTIFICATION CODES
The identification code is used to instruct the Loader on how to handle the associated data
word.
Code
01

Loader Action
Program Unit Size
The data word specifies the number of machine words required by this program
unit. This number does not inc lude the required number of machine words for
common storage. The program size is used by the Loader to determine whether
the program will fit within the unused locations of any available 8K memory
bank. Loading terminates with an appropri ate error message if the program cannot be loaded. This information unit appears only once per program unit and is
the first information unit of the binary output. In absolute loads, no checking
is made for overlays; this is left to the discretion of the user. The program size
is also used to determine where to begin loading as loading proceeds from the
top of core down (see Memory Maps).

o 1

Program Size

Data Word

t.- {1 if absolute load

o if relocatable load

Program Load Address
The data word is an unre located memory address.

This address specifies either

an absolute or a relative storage address for program data words and is incremented by one for each data word stored (codes 03, 04, and 05).

If the ad-

dress is relative, it is initially incremented by the current relocation factor
(modulo 15 bits).

Bit 0 of the data word is used to indicate an absolute address

(bit 0 = 1) or a relative address (bit 0 = O).
012 3
Data Word

1 X 10 01
Load Address
t
{O, relative load address
1, absolute load address

Relocatable Instruction
The data word is a memory referencing instruction.

The address portion of the

instruction is incremented by the current relocation factor (modulo 13 bits).

4-1

LINKING LOADER

Loader Action

Code

The instruction is stored in the location specified by the load address which is
incremented by one after the word is stored.

045
Data Word
04

Unrelocate~

Op Code

Memory Add~

Absolute Instruction/Constant/Address
The data word is either a non-memory referencing instruction, a non-reloc:::atable memory referencing instruction, an absolute address, or a constant.

The

word is stored in the location specified by the load address which is incre··
mented by one after the word is stored.

Data Word

Non-Relocatable Word

Relocatable Vector
The data word contains a relocatable program address (vector).

The word is

incremented by the current relocation factor (modulo 15 bits).

The data word

is stored in the location specified by the load address which is incremented by
one after the word is stored.

Data Word

o
o

2 3

Vector

Non-Common Storage Allocation
The data word specifies the number of machine words required for non-common
variable and array storage.
by the load address.

Storag~ allocation begins at the address spec'ified

The load address is incremented by this number.

Thl~

block of memory is not cleared.

o
Data Word

4 5

0---0

Storage Size

]

Symbol-First Three Characters
The data word contains the first 3-characters of a symbol in radix 50 format
S
(see appendix 1). The data word is saved by the loader for future referenc:e.

4-2

LINKING LOADER

Loader Action

Code

012

Ixlo I

Data Word

Symbol

L {O, 1- to 3-character symbol
1, 4- to 6-character symbol

Symbol - Last Three Characters
The data word contains the last 3-characters of a symbol in radix 508 format.
The data word is saved by the loader for future reference.
only if in the code 07 data word bit

°=

1.
17

1 2

Data Word
09

This word is used

Symbol

External Symbol Definition
The data word contains the unrelocated address of the transfer vector for the
subprogram named by the last symbol loaded {codes 07 and 08}.

If the external

. subprogram has already been loaded, the address {definition} of the symbol is
stored into the specified vector address {relocated modulo 15 bits}.

If the sub-

program has not been loaded and this is the initial request, -the symbol and the
relocated {modulo 15 bits} transfer vector address are entered into the Loader
symbol dictionary as a request for subprogram loading.

This action automati-

cally forces the Loader into a Iibrary search mode when the end of the command
string is encountered.

If the Loader is already in the I ibrary search mode, it

remains there until all virtual globals have been resolved.

If the subprogram

has been previously requested (symbol in dictionary) but not loaded, the Loader
chains the reference locations.

This chain, generated exclusively by the

Loader, is followed when the external definition is encountered.

{Unchained

transfer vector locations must initially contain a reference address (code 04 or
05) to themselves.) For example, . GLOBL SUB where SUB is virtual should cause
the output of
012
07

010

09 1

17
SUB{radix 508)

TVADD

2 3

and SUB defined internally as TV ADD.
JMS* SUB

4-3

17
17
TVADD
Subroutine calls are made via

TVADD

LINKING LOADER

Loader Action

Code

3
Transfer Vector Address

Data Word
10

Internal Global Symbol Definition
The data word contains the unrelocated or absolute address (definition) of the
last symbol loaded (codes 07 and 08).

The last symbol loaded is a global sym-

bol internal to the program unit which follows.

In the library search mode, if

a request for subprogram loading exists (code 09) in the Loader dictionarYj, the
relocated (modulo 15 bits) definition is stored in the specified transfer vectors
and the program unit is loaded.

The definition also replaces the transfer vec-

tor address in the Loader dictionary.

If no request for loading exists, the pro-

gram unit is not loaded and the Loader continues to examine information lmits
until the next internal global symbol definition is found (I ibrary search mc,de).
If the program unit is to be loaded, all internal symbols following the one
causing loading are automatically entered into the Loader dictionary as defined global symbols.

If the symbol already exists in the dictionary and is

defined (indicating that a program unit with the same name is already loaded)
the current program unit is ignored.

o
o

Data Word

Symbol Definition

Block Data Declaration
This information unit instructs the Loader that the common blocks and data
constants following are part of a block data subprogram.

o
Data Word

Block Size

Common Block Definition
The data word specifies the number of machine words required for the common
block named by the last symbol loaded (codes 07 and 08).

In general, th.e

assignment of memory space for the common block is deferred until all reqlJested
I ibrary and subprograms have been loaded.

The exception to this rule occurs

when the block data declaration (code 11) has been encountered.

In this case

the common block name is treated as an internal global symbol and the block
is assigned to memory.

After the block is assigned to memory, the startinf;1 ad-

dress is entered into the Loader dictionary and the starting address is saved by
the Loader for future use (code 13).

4-4

All symbols in the dictionary associa1'ed

LINKING LOADER

Loader Action

Code

with the block are assigned addresses with respect to this starting address.

All

symbols which are yet to be loaded (via code 13 and 14) will also be assigned
as they are encountered.

When the block data flag is not set, the Loader en-

ters the name and the size into the dictionary (if it is not already there) and
also enters the word containing the next available dictionary entry address.
This entry will contain the first symbol in this common block and will be used
as the head of the chain of all symbols in this common block.

The address of

the head of chain is saved by the Loader so that the new set of symbols in the
common block may be added to the chain.

The larger of the two block sizes

is retained as the block size.
When the common block has been assigned memory locations, the assigned address is saved by ,the Loader for future reference (code 13) and the respective
lengths are compared.

Loading terminates, with an appropriate error message,

if the assigned block is the smaller. When the assigned block is larger or both
are equal, loading continues.

o
Data Word
13

3
0

Block Size

Common Symbol Definition
The data word specifies the relative location of the last symbol loaded (codes
07 and 08) in the last common block (code 12).

If the associated common

block has been defined (block data), the absolute address of the symbol is calculated (block address plus relative position) and placed in T. V. location
(code 14). When the common block has not been assigned, the relative address
is entered into the Loader dictionary. and chained to the symbols associated
with the common block.

o
Data Word
14

3
0

Relative Address

Common Symbol Reference Definition
The data word contains the unrelocated address of the transfer vector for references to the common symbol named by the last symbol loaded (codes 07 and 08).
The symbol definition (code 13) is stored in the relocated (modulo 15 bits) address specified when the associated common block has been assigned (code 12).
When the block has not been assigned, the relocated (modulo 15 bits) address is
entered into the Loader dictionary along with the relative address (code 13) of
the symbol.

4-5

LINKING LOADER

Loader Action

Code

o
Data Word
15

3
0

Address of Vector

Data Initialization Constant - First Word
The data word contains the first machine word of a data initialization constant"
It is saved by the Loader for future use (code 18).

Data Word
16

Data Constant

Data Initial ization Constant - Second Word
The data word contains the second machine word of a data initialization (:onstant.

It is saved by the Loader for future use (code 18).

Data Word
17

Data Constant

Data Initialization Constant - Third Word
The data word contains the third machine word of a data initial ization constant.
It is saved by the Loader for future use (code 18).

Data Word
18

Data Constant

Data Initial ization Constant Definition
The data word contains the relative load address of the last data initializc]tion
constant loaded (codes 15, 16, and 17) and a mode code identifying the constant (real, integer, double, logical).

The load address is incremented b}' the

current relocation factor (modulo 15 bits) if the constant initial izes a non-'
common storage element.

When the constant initial izes a common storage

element (indicated by the presence of the block data flag, code 11), the load
address is incremented by the address of the last common block loaded (code 12),
The constant is stored according to mode and the relocated load address.

o 1 2 3
Data Word

10 IXX I

17
Load Address

00, mode = integer (1 word)
01, mode = rea I

(2 words)

10, mode = double (3 words)
11, mode = logical (1 word)

4-6

LINKING LOADER

Code
19

Loader Action
Internal Symbol Definition
The data word contains the unrelocated or absolute address {definition} of the
last symbol loaded {codes 07 and 08}.

The symbol is strictly internal to the

program being loaded and is entered conditionaHy {if a DDT Load} along with
its relocated address {modulo 15 bits}, into the DDT symbol dictionary.

The

program unit name is indicated by bit 0 of the data word.

Data Word

17
Symbol Definition

L {O, internal symbol
1, program name -- from FORTRAN IV or
MACRO-9 command strin,g
All symbols fall into this category.
20

String Code - First Half
The data word contains the unrelocated address of a data word whose address
portion is to be replaced by another value.

The relocated {modulo 15 bits} ad-

dress is saved by the Loader for future use {code 21}.

Data Word
21

Stri ng Address

String Code - Second Hal f
The data word contains an unrelocated address.

The address portion of the data

word specified by the first half-string code {code 20} is repraced with this address {relocated modulo 13 bits}.

Data Word
22

4 5

10-

0 1

17
Replacement Address

Input/Output Device Routine Request
The data word specifies the unit number {. OAT slot number} associated with a
device level I/O routine.

The Loader defers loading of any I/O routines until

ar I other subprogram loading has been completed; when subprogram loading is
complete, the system I ibrary is searched for all requested I/O device routines
not already residing in memory {see Operating Procedures}.
are then loaded.

4-7

The I/O routines

LINKING LOADER

Loader Action

Code

o
Data Word

Unit Number

t{ =
0

single unit

2's complement when
negative

1 = all units
(. IODEV ALL) all
positive . OAT slots with non-zero contents

End of Program Unit
This information unit is the last unit of a program unit.

The data word contains

the unrelocated start execution address of the program.

This address is relo-

cated (modulo 15 bits) and entered into the system communication tables 1"0 be
used when control is given to the user.

Only the first start address ehcountered

is entered into the communication tables.

(It is assumed that the first program

unit specified in the command string is the main program.) The first addre~ss of
the main program wi II be used if the. END pseudo-op did not have a start address.

When loading from either the system or external libraries, the end unit

causes the Loader to examine the next line buffer for the end-of-file condition.
When the end-of-file for the external library is obtained, the Loader aut()maticall y begins searching the system Iibrary to resolve any remaining globals.
Upon encountering the end-of-file of the system I ibrary, the Loader announces
any unresolved global names.

W~en loading is complete,

control is returned

to the Monitor for dispatching to the user, DDT, keyboard listener (see Operating Procedure~.

o
Data Word

Start Address

4-8

LINKING LOADER

SECTION 5
MAIN PROGRAM ORGANIZATION
PROGRAM SIZE (code 01) absolute or relative, does not include COMMON size
PROGRAM NAME (code 19)
PROGRAM LOAD ADDRESS (code 02) absolute or relative
COMMON STORAGE (codes 1"2, 13 and 14)
NO N-COMMO N STORAGE (code 06)
Array Declaration Information
Equivalenced Arrays and Variables
Non-Equivalenced Arrays
PROGRAM BODY
Codes
Codes
3
07 } Symbol
04
08
Instructions
05
09
Exte rna I Sym bo I
Definition

Constants
Non-Equivalenced Variables
Literal s
Transfer Vectors (code 05)
EXTERNAL SYMBOL DEFINITIONS (code 09)
END (code 23)

5-1

LINKING LOADER

5.1

SUBPROGRAM ORGANIZATION
PROGRAM SIZE (code 01) absolute or relative, does notinclude COMMON
INTERNAL GLOBAL DEFINITIONS (code 10)
PROGRAM NAME (code 19)
PROGRAM LOAD ADDRESS (code 02) absolute or relative
COMMON STORAGE (codes 12, 13 and 14)
NON-COMMON STORAGE (code 06)
Array Declaration Information
Equivalenced Arrays and Variables
Non-Equivalenced Arrays
PROGRAM BODY
Codes
Codes
03
07
08
Instructions
04
{
09
05
Constants
Non-Equivalenced Variables
Literal s
Transfer Vectors (code 05)
EXTERNAL SYMBOL DEFINITIONS (code 09)
END (code 23)

5-2

LINKING LOADER

5.2

BLOCK DATA SUBPROGRAM ORGANIZATION
BLOCK DATA INDICATOR (code 11)
PROGRAM NAME (code 19)
COMMON STORAGE (codes 12, 13, and 14)
DATA INITIALIZATION CONSTANTS (codes 15, 16, 17, and 18)
END (code 23)

5-3

LlNKI NG LOADER

SECTION 6
DEFINITIONS
Loadable Program Unit

A main program, subprogram, or a block data subprogram.

Transfer Vector

A core location containing the address ofa subprogram or an entity in
common. All references to subprograms and entities in common are
indirect.

Internal Global Symbol

A symbol whose definition is accessible to all programs.

External Symbol

A symbol which is referenced in one program and defined in another.

Relocation Factor

The amount added to relative addresses to form absolute addresses; initially, the first loadable core location. The relocation factor for programs following the first program unit is the next available load address.

Radix 508 Format

A method of symbol concatenation utilizing 508 characters as a "humber
set each with a unique value between and including to 47 , The sym8
bol (ll num ber") is converted using standard base conversion methods
(see append ix 1).

6-1

LINKING LOADER

SECTION 7
LINKING LOADER OPERATING PROCEDURES
7. 1

I/O MONITOR ENVIRONMENT
When the Linking Loader is ready to accept the load command string from the keyboard, it

will output to the teleprinter.
LOADER
>

Set up the input device and if it is the paper tape reader, momentari Iy
depress the tape feed control to clear the reader out-of-tape flag.

The file names, of all the programs that are to be unconditionally loaded from the input device (. DAT Slot· -4) must be input from the Teletype Keyboard, in the following form:
>NAME 1, NAME2, NAME3 ~
>NAME4, NAME5 (ALT MODE)
The main program must be requested first. The file names consist of 1 to 6 characters with
any characters over 6 being ignored. File names are exactly those used in command strings for assembly
or compi lation •
A file name is terminated by a comma (,), a carriage return (~), or ALT mode. Until the
comma, the carriage return, or the ALT mode is encountered, N RUBOUTS may be used to delete the N
previous characters of the file name.
ALT mode terminates the command string. When the input device is not file oriented, N
commas, followed by the ALT mode will prime the Loader to load N + 1 programs from the device.
After loading the programs requested in the keyboard command string, the Loader wi II attempt to resolve all unsatisfied subroutine requests by scanning the system library (. DAT Slot -1).
The library must be in the following format:

7-1

LINKING LOADER

7.1.1

Structure of System Li brary
ONE FILE: .LlBR

rr------------------------------A------------------------------~\

END-OF-FI~
UNIT

PROGRAM SIZE
DESCRIPTOR

PROGRAM UNIT

INTERNAL
GLOBALS

~--------~A~__--------~\

LOAD ADDRESS
DESCRIPTOR

DATA

PROGRAM
UNIT

ONE rops
BINARY
BUFFER

•

H1
VIRTUAL
GLOBALS

END CODE

Cl I CZ1C3

lOPS
- lONE
BINARY
BUFFER

.....

>- FOUR-WORD
GROUP

DZ
C4 /C 5 /C 6

TWO-WORD
HEADER

Cn-Z310 TERMINATES
A PROGRAM UNIT. THE
NEXT UNIT MUST BEGIN
A NEW lOPS BINARY
BUFFER.

)
- - DESCRI PTOR

>- 48
10
WORD S

06
I
I

C34 /C 35 /C 36
034
035
036
0-89-17
WORD 0
WORD 1

}

END-OF-FILE
UNIT
4----'

END-O':-FILE UNIT ONLY PRESENT
AT END' OF .LIBR FILE. MUST BE
REMOVED FROM END OF ALL PROGRAM UNITS, SINCE FORTRAN IV
AND MACRO-9 ALWAYS CREATES
E-O-F UNIT.

7.1.2

Loader Memory Map
The loader will output to the teleprinter the names and relocation factors (starting load ':Jd-

dresses) of all the programs requested in the command string, followed by the required Iibrall"Y routines
in the following format:

NAMEl
NAME2
NAME3
NAME4
NAMES
LlBR1
LIBR2

16572
14301
10765
06427
06313
05304
04112

7-2

LINKING LOADER

NOTE: Whenever the Loader detects end-of-medium in the input device,
or the system library device, it types tP on the teleprinter. To continue, place
more input in the device, and if the paper tape reader momentari Iy depress the
tape feed control, and type t P on the keyboard.
7. 1 .3

Error Messages
The Loader wi II output to the te leprinter . LOAD followed by the pertinent error code and

th en it will h a It.
Error Code

Mean i ng
Memory overflow - the Loader's symbol table and the user's program have overlapped. The loader memory map will contain printouts of all programs successfu Ily loaded, prior to the one which caused the memory overflow. Use of
COMMON storage may enable the program to be loaded as it can overlay the
Loader and its symbol table because it is not loaded into until run time.

Input Data Error - parity err.or, checksum error, illegal data code or buffer overflow (input line bigger than Loader's buffer),

Unresolved globals - if an explicitly or implicitly requested program cannot be
found, it will appear in the memory map with an address of 00000. This indicates that loading was unsuccessful; the cause of the trouble should be remedied
and loading tried again.

Illegal • DAT slot request-the . DAT slot requested is
(a) out of the range of legal • DAT slots
(b) 0
(c) does not have a device associated with it; that is, it was not set up at
SYSTEM generation time, and (in Keyboard Moni tor systems) was not set up by
a ASSIGN command.

When all the requested programs have been loaded and all library requests satisfied, the
Loader will output tS on the teleprinter and sit in a JMP loop. Typing 'tS on the keyboard will give
control to the starting address of the user's main program.
NOTE: If use is to be made of the paper tape reader, load the reader and
then momentarily depress the tape-feed control.
When the user program has completed its operation and terminated via the 'EXIT command,
the computer will halt.

If a DDT load, on completion of the loading and building of a DDT symbol table (exclusive
of the library routine symbols and those of DDT itself) control is automatically given to the starting address of DDT. DDT types DDT to inform the user that it is waiting for a DDT command.

7-3

LINKING LOADER

The user can force control back to DDT whenever he wants, by typing tT on the Teletype
keyboard.
7.2

KEYBOARD MONITOR ENVIRONMENT
The operating procedures noted below are required in addition to those described under the

I/O Monitor environment.
After loading the programs requested in the keyboard command string, ,the Loader attempts to
resolve all unsatisfied subroutine requests by scanning the external (. DAT Slot -5) and system (. DAT
Slot -1) libraries, in that order.
In order to inform the Loader that an external (user) library file exists for this load, it is
necessary to ASSIGN an I/O device to • DAT Slot -5 prior to the LOAD, DDT, DDTNS or GLOAD
command, i.e.,
$ASSIGN

DTA4

-5

$LOAD
The format of the external library file is identical to that of the system library file (see
section 7. 1 .1) .

If a DDT load, (DDT), on completion of the loading and the building of a DDT symbol table
(exclu,ive of the library routines' symbols and those of DDT itself), control is automatically given to
the starting address of DDT.
DDT uses • DAT slots -6 and -10 for patch output and patch input respectively. If the- user
knows that he will not make use of this feature, he should ASSIGN NONE to those slots so that unnecessary device handlers do not take up needed core space. For example,
$ASSIGN

NONE

-6, -10

$DDT
A program may be loaded with DDT but without the DDT symbol table by requesting loadin~J
with the DDTNS keyboard command. For example,
$ASSIGN

NONE

-6, -10

$DDTNS
This feature gives the user. more operating space but deprives him of symbolic referencc~s to
user symbols in DDT commands.

If a loading error occurs, an appropriate error message will be output to the teleprinter and
control will be given to the system bootstrap to reinitialize the Keyboard Monitor.
When all the requested programs have been loaded and all I ibrary requests satisfied, the
Loader will
a.

If LOAD, wait on the recognition of t S by the keyboard handler and then give
control to the starting address of the user's main program.

If GLOAD, give control to the starting address of the user's main program.

If DDT or DDTNS, automatically give control to the starting address of DDT.

7-4

LINKING LOADER

When the user program has completed its operation and terminated via the • EXIT command 1
control will be given to the system bootstrap to reinitialize the Keyboard Monitor and wait for the
next keyboard command.

7-5

LINKING LOADER

SECTION 8
MEMORY MAPS

8. 1

I/O MONITOR ENVIRONMENT
Link i ng Loader Tape

8K or 16K or
24K or 32K

BOOTSTRAP
LOADER IN
HRM FORMAT

• SCOM AND • SCOM +3

USER
PROGRAMS

+
Refer to memory map 2A of Keyboard Monitor
Systems for results of Link Loading.

GLOBAL
SYMBOL
TABLE

• SCOM +2

LINKING LOADER

PAPER TAPE
READER HANDLER
• SCOM +1
110 MONITOR
WITH TELETYPE -IN
AND
TELETYPE-OUT
DEVICE HANDLERS

8-1

LI NK ING LOADER

DDT Tape
BK or t6K 0 r

24K or 32K

BOOTSTRAP
LOADER IN
HRM FORMAT
•

SCOM

•

SCOM +3

DDT

Refer to memory map 2B of Keyboard Monitor
Systems for results of Link Loading in DDT mode.

US'ER
PROGRAMS

+
+

GLOBAL AND
DDT
SYMBOL TABLES

• SCOM +2

LINKING
LOADER

Paper Tape Punch Handler is only present in
version of DDT with patch file capabilitiies.

PAPER TAPE
PUNCH HANDLER
PAPER TAPE
READER HANDLER
•

SCOM

I/O MONITOR
WITH TELETYPE-IN
AND
TELETYPE-OUT
DEVICE HANDLERS

8-2

LINKING LOADER

8.2

KEYBOARD MONITOR ENVIRONMENT
LOAD
GLOAD
DDT
DDTNS (DDT without symbol table)
Phase 1

8K or 16K or
24K or 32K
RESIDENT
SYSTEM
800TSTRAP

The System Loader learns which I/O handlers
are required by the Linking Loader I loads
them relocatably and then loads the Linking
Loader relocatably.

• SCOM AND. SCOM+3

The Linking Loader I during loading of user
programs down from • SCOM+3 bui Ids the
loader (GLOBAL) and DDT (if DDT) symbol
tables up from .SCOM+2.

If a DDT load I the Linking Loader just prior
to giving control to DDT moves the DDT
symbol table down in core so that it overlays all of the Linking Loader except for the
small routine that makes the block transfer.

• SCOM+2

LINKING
LOADER

The Linking Loader will not load a device
handler that is already in core for its own
use.

LINKING LOADER
DEVICE
HANDLER
LINKING LOADER
DEVICE
HANDLER
• SCOM+l

RESIDENT
KM-9
(INCLUDING
TELETYPE
HANDLER)

8-3

LINKING LOADER

Phase 2B (DDT or DDT NS)
BK or 16K or

24K or 32K
RESIDENT
SYSTEM
BOOTSTRAP

• SCOM
DDT

• EXIT from the user program causes the
system bootstrap to re-initialize the Keyboard Mon i tor.

USER
PROGRAM(S)

USER/DDT
DEVICE HANDLER
USER/DDT
DEVICE HANDLER
•

SCOM +3

•

SCOM +2

•

SCOM

DDT
PATCH SPACE

If a DDTNS load, no DDT symbol table is
built.

DDT
SYMBOL

I-~------

TABLE

COMPACT DDT {
SYMBOL TABLE

'111/1/111111111
LINKING LOADER
DEVICE HANDLER
LINKING LOADER
DEVICE HANDLER

Non BLOCK DATA COMMON (FORTRAN ltV
or MACRO-9 output) may make use of core
as low as the compact DDT symbol table (DDT
only retains certain symbol table entries).
However I the user must be carefu I abolJt
placing patches.

LINKING LOADER
BLOCK TRANSFER
ROUTINE

RESIDENT
KM-9
(INCLUDING
TELETYPE
HANDLER)

The Linking Loader device handlers would
have been used to satisfy user device rt~quests.

8-4

LINKING LOADER

Phase 2 ( Not DDT or DDTNS)
8K or 16K or
24K or 32K
RESIDENT
SYSTEM
800TSTRAP
• SCOM

. EXIT from the user program causes the
system bootstrap to re-initialize the
Keyboard Mon i tor.

USER
PROGRAM(S)

USER DEVICE
HANDLER
USER DEVICE
HANDLER
USER DEVICE
HANDLER

-------

• SCOM +3

.SCOM+l and .SCOM+2 point to one of
two places.
(a) If the user program did not have any
device handlers in common with the
Linking Loader.

(b.)

LINKING LOADER
DEVICE HANDLER
~------LINKING LOADER
DEVICE HANDLER

If the user program did have at least
one device handler in common with
the Linking Loader.
Non BLOCK DATA COMMON (FORTRAN IV
or MACRO-9 output) may make use of core as
low.SCOM+2
(b)

(0.)

RESIDENT
KM-9
(INCLUDING
TELETYPE
HANDLER)

8-5

LINKING LOADER

APPENDIX 1
SYMBOL CONCATENATION - RADIX 50

FORMAT

Radix 50 is a technique used by the MACRO-9 Assembler and the FORTRAN IV Compiler
a
to condense the binary representation of symbolic names in symbol tables. Three characters plus two
symbol classification bits are contained in each la-bit word. A symbol is defined as a string of one
to six characters, i. e. ,

where C. is defined as
I

Character

6-bit octal code

Space

9
#

The symbol is concatenated as follows:
Word 1

((C * 50 ) +C ) 50 +C
1
2
a
a
3

Word 2

((C * 50 ) +C ) 50 + C
4
a
5
6
a

For example: The symbol SYMNAM would be entered in the Loader's symbol table as:
Word 1

((23 * 50a)+31a)50a+15a
a

475265*

Word 2

((16 * 50 )+1)50 +15
a
a
a
a

053665

*The sign bit of WORD 1 is set to 1 to indicate that this symbol consists of more than 3 characters and
that the WORD 2 is necessary.

Al-l

LINKING LOADER

APPENDIX 2
LOADER SYMBOL TABLE
Common Block Name

2 3

Block Size

ID = 7 when not defined
ID = 3 when defined

Name (2A)

3
4

Symtabaddress of last entry in chain

o if no entries

Block Definition

o if not defi ned

Name II may requ i re 2 words.

Common Name

o
1

2 3

o if last entry in chain

Symtab Chain Address

ID =4
BO = 1 for easy entry
update

TV Address

Relative Address in Block

If associated COMMO N block was defined when code 14 is encountered, no entry is needed
in the symbol table.
Virtual Global (internal)

Definition

Name (2A)
ID = 1

Definition (Virtual) = Absolute Address of last TV in chain

Virtual

Definition {Internal} = Absolute Address of Symbol

Internal ID = 5

Name

may require 2 words.

Interna I Names

3
ID

2
II

ID = 0

Definition
Name (2A)

Name" may require 2 words.

A2-1

If Program Name
ID = 6

Only entered
into the symbol
table during
DDT loads.

7-to-9 CONVERTER

CONTENTS
1.

INTRODUCTION

CONVERTER FUNCTIONS ..•.•••••••....••...•.•....•..•....•.••.••

OPERATING INSTRUCTIONS ....••.•.•..••.••......••.••..•.•......•

3. 1

Command String Format ..•.•.•••...••...••...••...••...•.•...•..

3.2

With I/O Monitor .••.•••.•••.•••.•.•.••..•.•...•••.•.••..•.••••..•

3.3

With Keyboard Monitor .....••.••.••....•..••.•....•.••.•..•••..

Device Assignments .•....••...••...••..•.•.••..•••.......••

USING THE CONVERTER ....•..•.••••...•.•••..•..•.•.••..•.•.•••.•

ASSEMBLE WITH MACRO-9

3.3.1

iii

7-to-9 CONVERTER

1•

INTRODUCTION
Source programs written for the PDP-7 Assembler in ASCII (or the PDP-9 BASIC Software

System Symbolic Assembler) may be converted to the source language and statement format of the PDP-9
ADVANCED Software System Assembler, MACRO-9, by the 7-to-9 Converter program. FIODEC is not
accepted by the Converter.

It is assumed that the reader is familiar with both assembler formats.

The Converter operates in the PDP-9 ADVANCED Software System environments, with either
the I/O Monitor (paper tape system) or the Keyboard Mon itor (DECtape or other mass storage systems).
Basically, th is program converts statements in the input PDP-7 program to equ ivalent
MACRO-9 statements. Some PDP-7 Assembler pseudo-ops cannot be translated because MACRO-9 does
not perform a comparable function. These are not changed by the converter, but will be flagged as
undefined symbols when assembled by MACRO-9. PDP-7 pseudo-ops which cannot be converted are

I isted below.
ANALEX

FIODEC

NOSYMBOLS

SYMBOLS

BAR

FIX

PUNCH

TELETYPE

CHAR

FLEX

PUNDEF

TEXT

EXPUNGE

NOINPUT

VARIABLES

Since MACRO-9 does not allow multiword variables, the dollar sign ($) should not appear
in the input source program.
2.

CONVERTER FUNCTIONS
The converter performs the following functions.
a.

Removes commas from tags (or labels).

Removes Location Counter Settings. For example, 100/ is normally exactly transla-

ted as • LOC 100, but the user may spec ify, in the command string that the Location
Counter setting be removed completely.
c.

If another statement follows on the same I ine, the converter inserts the semicolon

del im iter as requ ired in the MACRO-9 statement format.
d.

Inserts plus signs where needed

LAC

5 is translated to LAC A+5.

Changes the indirect address indicator from I to * I as LAC

A to LAC* A.

Normally, the converter does not produce a printed I isting, and term inates programs with an
.E ND statement. The user may make command string entries, however I to request the follow ing functions.
a.

A printed listing

Insert the .ABS pseudo-op

Remove Location Counter settings

7-to-9 CONVERTER

d. Terminate physical segments with. EOT instead of • END
e. Multiple inputs
3.

OPERATING INSTRUCTIONS

3.1

Command String Format
After the converter types,
7-TO-9 CONVERTER

>
the user types the command string in the following format,
optional

L, A, R, E, Tn

input
name

output
name

fi Ie 1

,fi le2

terminator
~ (or AL T mode)

where, if typed,
L

Requests a printed output listing

Insert .ABS

Remove Location Counter settings

Terminate with. EOT

Multiple input, followed by n

Number of inputs

The reverse arrow must follow the optional function entries, or start the command string if no
optional entries are made.
filel

Input program name, if different from output, otherwise it is omitted.

file2

Name of the program to be output. May be used to rename the program.

If the command string is terminated by a carriage return, on completion of conversion, c:ontrol returns to the 7-to-9 Converter to convert another program. If terminated by ALT mode, control
returns to Monitor (if in Keyboard Monitor environment).
Optional entries may appear in any order, separated by commas, and terminated by the reverse
arrow. Rubouts may be used to delete any unwanted characters prior to typing the command string term inator. If an error is detected, the Converter types,
COMMAND STRING ERROR

>
and the user may type the corrected command string.

7-to-9 CONVERTER
The following command strings are val id and correct,
>L, E, T3.....

NAME7, NAME9 ~

>T2,R,A ..... SEVEN, NINE ~
> ..... SAME (ALT)
In the last example, there will be no listing, no .ABS insertion, Location Counter settings
will be converted to .LOCs, .END will terminate, and only one input will be allowed.

Both the input

and output program are named SAME, and upon conversion, control returns to Monitor.

3.2

With I/O Monitor
In the paper tape only environment, to load the 7-to-9 Converter, place the CONV tape in

the reader, set the address switches to 17720 of the highest memory bank, depress the I/O RESET switch,
and then depresses the hardware READIN switch. When the Converter is ready to rece ive a command
string, it types,
7-TO-9 CONVERTER

>
3.3

With Keyboard Monitor
The Converter is called by typing CONV, after the Keyboard Monitor has typed $. When

ready to receive a command string, the Converter types,
7-TO-9 CONVERTER

>
3.3.1

Device Assignments - The Converter assumes that the input is assigned • DAT slot -14, the

output is assigned. DAT slot -15, and the listing device is assigned -12. The user may check the current device assignments by typing $ REQUEST CONV, and he may use the ASSIGN command to modify
the assignments if desired.
4.

USING THE CONVERTER

It is normally expected that some editing will be necessary to the output of the converter.
The converter performs the tedious operat'ion of adjusting statement format from that of the Basic Assembler to that of MACRO-9. If any of the pseudo-ops I isted in Section 1 are used, editing must be done
before the converted program wi II assemble correctly.

If the converted program is to be in relocatable form and run in the PDP-9 Monitor environment (I/O or Keyboard), the input/output procedures must be revised to utilize the lOPS routines.
Any device lOT instructions which are to be kept in the converted programs must be defined
by statements such as TSF = 700401. The Editor may be used to insert these definitions at the front of
the converter output.

7-to-9 CONVERTER
The procedure to convert a program for assembly in the absolute (. ABS) mode is as follows.
a.

Be sure the source tape is punched in ASCII.

Run the converter (CONV-9), using option A to place .ABS on the converted

program.
c.

An assembly may be run to locate any illegal codes not corrected by the COnVE!rter.

Edit

revise coding to remove pseudo-ops which MACRO-9 cannot handle

define device lOT 'instructions

Assemble with MACRO-9.

The procedure to convert a program for assembly in the relocatable mode, for running in the
monitor environment, is as follows:

Be sure the source tape is punched in ASCII.

Run the converter (CONV-9). Do not use option A.

An assembly may be run to locate any illegal codes not corrected by the COnVE!rter.

Edit
1.

revise coding to remove pseudo-ops which MACRO-9 cannot handle.

revise input/output procedures to uti lize the lOPS routines.

ASSEMBLE WITH MACRO-9.

UTILITY PROGRAMS
ADVANCED SOFTWARE SYSTEM
PROGRAMMERS REFERENCE MANUAL
DEC-9A-GUAB-D

READER'S COMMENTS
Digital Equipment Corporation maintains a continuous effort to improve the quality and usefulness of its publications.
To do this effectively, we need user feedback: your critical evaluation of this manual and the DEC products described.
Please comment on this publication. For example, in your judgment, is _it complete, accurate, well-organized, wellwritten, usable, etc? _______________________________________.___

What single feature did you like best in this manual? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

Did you find errors inth~manuan Pleasedescribe. _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~ __~____~_

Please describe your position. _________________________~_ _ _ _ _ _ __
Name,_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ___

OrganizationL-.___~_ _ _ _ _ _ _ _ _ __

Street_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

State __________._______ Zip______________

......................................................................................... Fold l-lere ......................................................................................... ,

............................................................................ Do Not Tear - Fold Here and Staple .............................................................. ..

FIRST CLASS
PERMIT NO. 33
MA YNARD, MASS.
BUSINESS REPLY MAIL
NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES

.............................................................
Postage will be paid by:

mamaama
Digital Equipment Corporation
Software Quality Control
Building 12
146 Main Street
Maynard, Mass. 01754