Digital PDFs

DEC-9A-GUAB-D

November 1968

117 pages

Original

3.4MB

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

OCR Text

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

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

Manual

Price $4.50

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

DIGITAL EQUIPMENT CORPORATION. MAYNARD, MASSACHUSETTS

1st Printing August 1967
2nd Printing February 1968
3rd Printing November 1968

The following are registered trademarks of Digita I
Equipment Corporation, Maynard, Massachusetts:
DEC
FLIP CHIP
DIGITAL

PDP
FOCAL
COMPUTER LAB

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

iii

DDT-9

DDT-9
CONTENTS
Section

Page
INTRODUCTION .•..•.•.•.....•.•.•••.•...•...•.•.••...•••••.•.•.••

1-1

1.1

General Information .••.•••.•.•...•••••.•.••••...•...••...•.•..•.

1-1

1.2

Terminology Used in this Manual ...•..•••..••••••••.•...••..•.•••.

1-1

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

2-1

2. 1

Loading the Program ....•••••...•.•.••.•..•...•..••...•.•......•.

2-1

2.2

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

2-1

2.3

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

2-3

2.4

Type-Out Modes .•.•...••.•.••..•••.•••.•••••••...•.•.••.•.•••••

2-4

Address Modes .•••..•.•.•.•..••.•.•.•.•.•.•••...••••.••.••••

2-5

2.5

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

2-6

2.6

Search ing 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-8

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.4.1

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

A 1-1

MNEMONIC INSTRUCTION TABLE ................................... '.

A2-1

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

A3-1

iii

DDT-9
SECTION 1
INTRODUCTION
1. 1

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

on-I ine 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 wh ich, 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 PDP-9 configurations.
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 con junc tion 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 libr,ary, 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, respectively,

if the patch file capability is to be used. Otherwise DAT slots -6 and -10 should be assigned to NONE.
2.2

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 sh ifts to DDT -9, which types the number of breakpo int, 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

Breakpoints 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 we II 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 exited.

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

CAL 3

{Breakpoint 1}

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 register 17.
The user may specify any other auto-index register by modifying DDT -9 1 s special register, AX$, as
follows:

AX $/

000017

lOu..

{Modification procedure is explained later in
th is manual.}

The commands controlling 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-1 1"

Inserts a breakpoint at LOC+1

TAG '-' 2"

Inserts a breakpoint at TAG

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 breakpoint
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 i1e 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:
k/

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 L.OC. 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:
LOC/

TAD COUNT

TAG/

JMP LaC

JMP

LOC+l il.

The line feed closes the storage word, then opens the next sequential storage word:
LOC/

TAD COUNT

LOC+l/

CMA

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

TAD COUNT

LOC-l/ LAC A
tZ

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

LOC/

TAD COUNT

LABEL+l/

LAC HOLD

2-3

TAD CNTR ~

DDT-9

Control A allows the user to examine a new sequence of storage words. This command c loses the storage word, then opens the referenced storage word, establ ish ing
a new sequence. A line feed wi II then open the second storage word in the new
sequence.

LABEL/

JMP LOC

LOC/

TAD COUNT

LOC+1/

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-9typesmemory 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 (*) is
typed after the mnemonic op code. The address portion is handled according to the
address mode as described below. Operate instructions are further examined for
specific mnemonic codes. (See appendix 2 for recognized codes.) Operate
instructions not found in DDT -9's 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 after 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

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 instructions, 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 ±778 positions, the address is typed as relocatable (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 I 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 13041 I

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 time

(if the program interrupt control is enabled) to restore control to DDT -9.
The foHowing 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 address.
(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 address
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 having

particular characteristics can be found with ease. Two special locations, LO$ and HI$ (further ex'plained 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 mClsk is initially set at 777777, for a full word search;
and the limits are initially set to encompass the entire user's program, including all subprograms and
library routi nes.
There are three types of searches as follows:

k '-' EQ$

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

k '-' UN$

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

k,-, ADR$

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

2-6

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

LAC LOC+1

POS/

X OR 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 I imit of the search operation.

HI$

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

PA$

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 ~

lillL

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:
JMPI-I 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 allowable 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 commands
described below control the output of a patch fi Ie 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-J PFO$

Put location k only onto the patch file.

SNS$

DDT -9 puts all symbols defined during debugging onto the patch file, 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$
S NS$

(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 and
types the message ERROR followed by a right angle bracket (». Data up to the point of error is correctly in memory.
PFI$

DDT -9 reads in the patch file.

2-8

DDT-9

Typing PFI$ at this point (without repositioning the tape), wi II 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 will cause PFI($) to attempt to
re-read the error word.
2. 11

(See appendix 3 for format of the patch file.)

CO-RESIDENT SUBROUTINES
Since identical symbols may be used in two or more separately assembled or compiled, 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 subrout'ine.

(The

memory map output by the loader shows all re location 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:
007603

LAB/

7603 is the actual address of the storage word named LAB. This address must be used when (my reference
is made to LAB.
In FORTRAN programs, this condition also appl ies to symbols defined in DIMENSION statements.
2. 13

MISCE LLANEOUS 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:J,

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 .+7

The ampersand causes DDT -9 to bypass the mnemonic instruction lookup.

is necessary if the user has used a recognized mnemonic operator as a symbolic
address.

JMPI

Is inval id, but

&JMPI

wi II open the word named JMP.

Loci

JMP JMP ,1

JMP GO

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

DDT-9 executes the instruction k. The AC and Link are restored to their condition before the breakpoint (if one is in effect). If the instruction is not a
JMP, control returns to DDT -9, and the new AC and Link (if affected) are
stored.

For example,

JMS L...I SUBA#
wi" 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 typing
control U.

DDT -9 typesrcy as evidence of acceptance. Single character

deletion (RUB-OUT) is not allowed by DDT-9. If a RUB-OUT is typed, it 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

o
>

C(PC)

C(AC)

S(L)

and wai,ts for a command from the teletype.

2-10

DDT-9

APPENDIX 1
SUMMARY OF COMMANDS
Linkage Characters
-I-

Arithmetic plus
Arithmetic minus

(space)

Fi e Id separator
Breakpoints

nil

nil
III

Insert breakpo i nt 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

j}..

(Carriage return) Close the location
(Line feed) C lose the location, open n~xtlocation
(up arrow) Close 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-out 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,-, EQ$

Search for words equal to k

k '-' UN$

Search for words not equal to k

k '-' 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 limit of search

HI$

Upper limit 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 fi Ie output

k~PFO$

Single location patch file output

SNS$

Save new symbols

PFE$

C lose 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
Misce Ilaneous 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
Operate

Memorl Reference
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

750001

GLK

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 (S NS$)

punches the additional symbol table area in the same manner. The PFE$ command punches an lOPs
end-of-fi Ie 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 TYPSET* , 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.

PDP-9 TEXT EDITOR
CONTENTS
Page
1

INTRODUCTION........................................................

1-1

FUNCTIONAL DESCRIPTION .........•...................................

2-1

2. 1

Contro I Modes .......•..............................................

2-1

2. 2

Data Modes

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

2- 1

2.2.1

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

2-1

2.2.2

Block Data Mode................................................

2-1

Data Fi les ...........................•..............................

2-3

2.3.1

Using Monitor I/O ......•........................................

2-3

2.3.2

Input and Subsi diary Fi les .. . . . • . . • . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-3

2.3.3

Output Fi les .....•..............................................

2-4

2.4

Using the Break (CNTRL P) Character...................................

2-5

2.5

Using the Erase and Kill Characters

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

2-5

EDITING OPERATIONS.............................. ....................

3-1

3. 1

Modifying an Existing Fi Ie ....•...........•..•...................•....'.

3-1

3.2

Creating A New Fi Ie ................................................ "

3-1

3.3

Input/Edit Modes

.. . .............................................. "

3-2

3.4

Block Mode ...........•............................................ "

3-2

3.5

Closing the New Fi Ie ....•.......................................... "

3-2

3.6

Error-Handling Conventions

2.3

3.6.1

Command String Errors

.......•........................•....•.... "

3-2
3-2

3.6.2

Premature End of Fi Ie

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

3-3

3.6.3

Read Errors and Line Overflow .................................... .

3-4

3.6.4

Block-Mode Buffer Overflow

.......•..................."., ........ .

3-4

3.6.5

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

3-4

EDITOR COMMANDS ................................................... .

4-1

4.1

OPEN (fi lename (ext)),,! .........................................•... "

4-1

4.2

CLOSE (fi lename (ext))"J ............................................ ,

4-1

4.3

NEXT [N] (u n)';

...•.....•..............•..•.................... ,'

4-2

4.4

PRINT [p] (u n),I

." .............................................. .

4-2

4.5

FIND [f]

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

4-2

4.6

LOCATE lL] string J ............................................... .

4-2

4.7

DE LETE [D] (u n)J

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

4-3

4.8

BOTTOM [B]

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

4-3

4.9

RETYPE [R] u line'., ................................................ .

4-3

4.10

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

4.11

I NSERT [I] U line J
INSERT[I]

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

4-3
4-3

4.12

GET [G] (u n),} .................................................. .

4-3

4.13

CHANGE [C] u q stringlq string2q,} ................................. .

4-4

string,)

iii

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

TOP [T] ~

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

4-·4

4.15

VERIFY [\I] u

{g~F ~ . . . . . . . . . . . . . . . . . . . . • . '. . . . . . • . . ..

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

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 Symbol ic Editor .•.•••.....•...••.

2-3

2-2

Output File Conventions for PDP-9 Symbolic 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, (md 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 N source programs,
but it may also be used to edit any symbolic text.
The Editor operates in the ADVANCED Software System with either the I/O 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.

'kThe 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 memorya I location schemes for system programs.

1-1

PDP-9 TEXT EDITOR

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 fi Ie. 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 line currently available is specified by a pointer which can be thought
of as moving sequentially through the file, starting at the first line, in response to typed editing commands. When a file is opened at the beginning of an editing session, the first line of that file is brought
into the work area and is available for modification. This line remains in the work area unti'l 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 and, as the "current line," can be modified. Lines
previously skipped over are no longer avai lable for editing by the user, but are written in the output
file. Thus at any point in a single edit run in line-by-Iine 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 f.iJe (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 fi Ie 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 I 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 modifi cation through the use of normal locative requests and, moreover, may be reaccessed until the buffer is emptied by the user.

2-1

PDP-9 TEXT EDITOR

Unless deleted, I ines passed over in block mode are not lost to the user {as in Iine-by-I ine
mode} until the contents of the buffer are written in the output file.
request to search for and bring in a specified line.

Consider, for example, the editing

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

{possibly} the entire file below the pointer. The same request in block mode provides a search of the
entire 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 not
been added to the output file.

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

a line in which a change is needed. The user would then have to punch a new input file and begin
editing {more carefully} aga in.

READ A D D
DECODE
COMMAND

~-------,

YES

ADD CURRENT
LINE TO
OUTPUT PAGE

YES

GET NEXT
LINE FROM
INPUT PAGE,

ADD CURRENT
LINE TO
OUTPUT FILE

GET NEXT
LINE FROM
INPUT FILE

YES----------------~

Figure 2-1

Schematic of Line Processing in
Block and Normal Modes

2-2

PDP-9 TEXT EDITOR
2.3

Data Fi les

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 whi'ch 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 file 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 normally holds a previously prepared file upon which changes are to be
carried out. The second, the subsidiary file device, is usually the medium through wh ich addif'ional,
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.

For the paper tape and card

readers, this is the only recording mode. 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 wi II resu It 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 file-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. Accordingly,
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 device. If the user's response is
YES,t
then the program wi II read datel 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 Fi les
Immediately upon receiving control after having been loaded, the Editor attempts to deter-

mine whether or not the input and scratch devices are fi Ie structured. If either one of the devices 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.
Th is 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 place
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 fi Ie 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 file is closed and immediately becomes available 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 fi Ie is properly entered in the file directory for that
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 output
fi Ie available on one, or both, of the devices. Further, the original input file is not de leted until the
new file has been successfully written and closed. A system failure, therefore, 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 Fille is:

Fi Ie oriented

File oriented

Input Device

Deleted

File oriented

Nonfile oriented

Output Device

Unchanged

Nonfile oriented

Fi Ie oriented

Output Dev ice

Unchanged

Nonfile oriented

Output Device

Unchanged

2.4

Using the Break (CNTRL P) Character
Frequently, the user, having made a mistake in his 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 will 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 iis lost from

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

left in one of two posi tions.

In the first (usual) case, the pointer indicates the line whi ch weJS 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 two 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 (Kill
character) results in the deletion or the entire line typed so for. The Monitor echoes a commercial at
sign «(9)) 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 File

If the input device is file structured (disk, drum, magnetic tape, or DECtape), the first
command to the Editor must be
OPE N fi lename ext
where Ilfilename
extension.

is the primary name of the wanted file residing on the input device and lIe:d ll is its

Ext ll may be omitted and, if so, is assumed to be SRC. If the fi Ie specified is not found

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 device.

If the specified file is present on the input device, an intermediate, temporarily named,
fi Ie 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 fi Ie 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 carriage return, thereby

entering input mode. If the output device is file 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
fi Ie structured, the fi Ie-naming conventions are bypassed.
Where both input and output devices are file 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 edit

function on the current line, the Editor must be in edit mode.
Control mode may be changed at any time by typing a Iine of zero length (a Iine 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 until the user

indicates his satisfaction with the current state of that portion.

Block mode is entered via the control

word BLOCK, 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-line mode is reentered by use of the BLOCK 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 IIfilename ll nor lIext ll need be specified if previously given in the OPEN command.
If "filename ll and "ext ll are present in the command string, they override the names given in the OIPEN
command.
Both "filename ll and "ext" are ignored if the output device is nonfile oriented.
3.6

Error-Hand Iing 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 differentiate among error types. The reasons for this common treatment He 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 wh ich 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 "l • II

A MOVE request was issued when BLOCK mode was OFF.

When BRIEF mode is ON, the Editor comment and the command line 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

wh ich moves the pointer be low the last Iine 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 until exactly n lines have been read. If, in the process of readin~l, it is
discovered that fewer than n lines are physically present on the secondary input medium (paper tape,
say), then a premature end-of-fi Ie condition is said to exist. An improperly-formulated FIND request
(the character string typed is absent from the fi Ie) will result in a simi lar condition.
Depending upon the character of the incoming group of lines (block buffer, secondary input
medivm, Olr 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 Line 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 file device handler detects either incorrect
parity or a faulty checksum in the incoming line. The printed comment is:
READ ERROR:
followed by the line in which 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 characters 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. Th is might occur, for example, during the processing of
a READ request if the buffer length (previously defined by a SIZE command) is too great to be accommodated by the memory available. When the capacity of the buffer is exceeded, the program types the
comment:
BUFFER CAPACITY EXCEEDED BY:
followed by the line which caused the overflow. This line remains in the current-line area and the
program reads a new command from the keyboard.
3.6.5

File-Naming and Calling Errors
Errors in file-name usage can be classified in three general groups.

Either (1) the named

fi Ie cannot be found, or (2) a name has not been given to the fi Ie at a point where one is needed, or
(3) a name has been given which 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 filename 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 C LOSE command, the program, after attempting to process the C LOSE request, wi II print:
NO FILE NAME GIVEN.
The next edit request must be another C LOSE naming the fi Ie.

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 IEditor's
temporary files (normally. TFILl EDT) closed on the output device. The closing of the temporary file
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. TFILl 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 file on the output device is 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. TFIL 1 EDT.

At the second level, it may happen that the file name given in a CLOSE sequenc:e is identical
to that of another file on the (current) output device.

In this 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 is 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 delimiter 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 ~
resu Its in the follow ing 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 IIfi lename" and whose extension is "ext ll 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 fi Ie is opened on the output devi ce and Iines from the keyboard are
written into it as they are completed.

II Ext, II if not given, is assumed to be SRC.

If the file specified is found on the input dev i ce, 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 file fall ing be low the current Iine are appended
to the output fi Ie and the output fi Ie is closed. If no input file is present, the current Iine is added to
the output file and the output file 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 fi Ie name is given, the name assigned in the OPEN command Iine is used.

Neither IIfilename li nor lIext li need be given for nonfile-oriented output devices.

4-1

PDP-9 TEXT EDITOR
NEXT [N]' (u n) ~

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 modifi cation.

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

END OF {

~~F~ER }

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 printed

on the Teletype. The pointer is left at the last Iine printed; n is assumed to be 1 if omitted.
If, as a resu It of the command, the pointer moves past the last Iine of the fi Ie, the error
message
FILE
}
END OF { BUFFER

REACHED BY:

PRINT n
is printed.
4.5

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

the next occurrence of a line which begins with the character group "string." If the search is successful, the line beginning with "string" is brought into the work area.

If the search is unsuccessful

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

4.6

LOCATE [LJ u string.
The inpu't file is searched, beginning with the line following the current line, for the next

occurrence of a line which contains 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.

last line deleted becomes the current line.

The line foll()wing the

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] ~
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 "Iine" 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 fi Ie and the character string "I ine" 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. 1 1

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 fi 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 I ine 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 string1q string2q ~

In the current line, the first character group (l string1") which matches that occurring between
the first pair of quote characters (q1s, in this case) is replaced by the character group (" string2 11 )
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

IIstring 111 and IIstring211 may contain any number of characters, including zero. If verify mode is in effect,
the program will print the new current line on the Teletype when the requested change has been accompi ished.

Examples of change requests:

Current line:
a.

4.14

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:

CHANGEu/RN/RIN/J

New line:

NXTLIN

Make the IIJMS II a IIJMP*II.
Request:

CHANGEuXSXP*X~

New line:

NXTLIN

Delete the IIt ll in the tag.
Request:

Cu/T//J

New line:

NXLlN

TOP [T]~
Move the pointer to the beginning of the edited file or buffer. The first line 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 Iines 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 Iine of the fi Ie, brought in by the BOTTOM request, is printed.

The new line resulting from a CHANGE request is printed.

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

4-4

PDP-9 TEXT EDITOR

The command
VERIFY [ V J ~
(without arguments) is equiva lent to
VERIFY [V] uON ~
4.16

OVERLAY [0] (un) }
Starting with the current line, n Iines (or the current I ine on Iy, if n is omitted) are deleted

from the input file.

Control mode is changed to input with the normal typed program respOn5,e,

INPUT
Subsequent typed'i ines are interpreted as text intended to replace the I ines so OVERLAYed.

4.17

APPEN D [A] u string ~

String" is added to the current I ine following the last data character and preceding the

term inating 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 -+tIGET DECIMAL ARGUMENT.
If II string II is absent, the current Iine is unchanged.
4.18

BRIEFu {g~ ~
Set brief mode according to the ONIOFF parameter.

Brief mode results in the abbreviated

printing of the current Iine during the servi cing of some commands. An attempt is made to print on Iy
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 indi cator 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. The 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 area
and are not ava i 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 nonfi Ie oriented. If both devices are fi Ie oriented, block mode is set off.
The command

BLOCK~
(without arguments) is equivalent to
BLOCKuON~

4.20

SIZE [5] u n ~
Set the tota I number of lines whi ch wi II 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 lines is inserted in the
buffer via a READ command.

n is initially 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

~EAD ~
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 READ request wi II 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

Nothing

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.

(lre optional augments to be used when block-limiting lines are not labeled.
At the completion of command processing, the block of lines between and including those
labeled TAGl and TAG2 (augmented, if desired) are repositioned to appear after the line 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 ofter
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 file was closed. The Editor, in preparing intermediate files,
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

using the Editor.
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 margin are not program generated, but were added later for reference.
Figure 6-4 is the assembly I isting of the new, edited file showin~ the results of the editing
run.

6-1

0"0~13

09'001
0(7002
1.H'0P' 3

R
R
R

~H 004

040~52

0V-005

IllV006
IllV0P17
l.1(i~H 0

1340V'147
4400100
777773
0412JV'!45
2213"'44
13 0I2JVI 130
741(1'13(71
6013(;'33
441,H'44
44121[1144
1.14121055
1 (I'l12JV'I 51
4412JV'!46
617112Ji?l43

Ll
J

R
~

il.'!V 016

J
I'.)

R
R

M014
0v015

U
Ll

~V'011

0ti012

0("013

0-.

R
R

J
J
Ll

J
LI

i1"'13?3
0~1324

M'13?5
13(70?6
0"1327
v)V'1330
0(1'12131
IM032

0?1Z'17
0IJ020
09'0?1

R
A
R
R
R
A
R
R
R
R

j{jVeJ34

P
R
R

740V'11171
0413(/'54
200Vl53
744010
13613052
4413r?5?
60 ill V'I 5(i1
777773
540~45

~Hn5

6(i'13~2V'!

i!:W036

750001

R
A
R
A

0[-042

R
R
R
R
R

0V 0')7

~:W13?2

M"0~7

0C'040

2?13~~Hl!

A
R
R
R
R

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

ilIvill33
J

R
R
R
R
P
R
R

000000
20130130
iJ412lVl44

~W041

R
R
p

2(i'1~Hl54

340~47

7400'01

340V'52

6?0000
0013(1100'
777777

R
A

ISUBROUTINE PACK, 7-RIT CHARS TO lOPS ASCII,
ICALL:
JMS PACK
I
FROM
I
TO
0
PACK
IGET FROM ADRESS.
LAC PA(;K
OAC PFROM
IGIV[ TO FROM POINTER.
LA(;it PACK
IGET ADDRESS OF TO ARRAY,
DAC PTO
IGIVr TO OUTPUT POINTER,
OAC PL~H
ISAvr AS START ADDRESS,
ISZZ PACK
IBUMP TO RETURN,
PLOOPl
LAW 17773
IS£T UP
OAC PKC:;C~R
PLOOP2
IGET NEXT WORD IN INPUT ARRAY,
LAC* PFROM
SAC ( -1
ITERMINATOR?
SKP
INO, SKIP,
JMP PCLOS
IYES, GO CLOSE OUTPUT ARRAY.
IS? PFROH
IPOINT TO NEXT WORD,
IS? PFROM
IPOINT TO NEXT WORD.
("lAC PWRD3
IS£T UP TO ROTATE.
PLOOP7
JMS PRAL7
ISZZ PKsCP
15 CHARS IN, Q
JMP LPOOP2
INO, GET ANOTHFR,
IWORD PAIR COMPLFTE,
LAC PWRD?
RAL
ICLEAR PAIR BIT 35.
DAr PWRD2
LAC PWRDl
/.GET FIRST 1'40 OF PAR, •
RAL~CLL
181T 13 OF WD 2,
/INSE"RT FIRST WD IN OUT ARRAY,
I'JA(;* PTO
ISl PTn
IRUMP OUT ADDRESS.
JMP PL 'II I2JP 1
IGO SET UP NEXT PAIR.
LAw 17773
PCLOS
IMAKE" SURE PAIR IS COMPLrTE.
SAO PKC;CHR
JMP PLnOP7
IINCOMPLETE PAIR.
CLA!CMA
IFORM WORD PAIR COUNT
TAO PL~H
ISTART ADDRESS,
CMA
TAO PTn
ILE:SS END ADDRESS.
IRfTURN TO CALLER,
JMP* PACK
,END

A *LIT

Figure 6-1

Sample Input File

-c
0
-c

I
-..0
-I

-I

=i
0
;;:0

t.EFT-IIATlLS,t:i:)

NON-HeAD£i2G1)

ISUBROUTINE PACK, 7-BIT~CHARS TO~IOPS ASCII •
JMS PArK
I
FROM
/erM!;-a,&- /A)PurAeRACf.

• 111oaL /J/tC-K, P£IK. 7., A4i~/)~1.ICALL:
PW~O'l, PW~o3
0~000

u
u
u

u
U

0V:001
0v'002
~~003
0~004
0~005
0~006
0~007

00010
0r011
00012
00013

R
p
R
R

040~44
220~00

R
R
R

R
R
p

04005?
040047
440000
777773
0400,45
220044
~00000
741000
6000'33
440044

/~r,(J-£F""eN"- du.TfJtLTlhel2lfAf'e

A
PACK
0
R
L~iIc ~ PACK
R 15r AfC-~~DAC PP~OM
R
LAC* PACK
R
DAC PTo
R
OAG PLfJlI
R
IS~ PACK
A
PLOOPl
LAW 17773
R
nAC PK'5CHR
R
PLOOP2
LAC* P~ROM
R
SAl> "- ~ ~--(t::Nb'-H~
A
~ ~~~
R
JMP PCLOS
R
1St PFROM

0~015

4400 44

or 016
0V017
00'020

P
P

040055
100-051
440(7.46

R
DAC PWRD3
R
PLOOP7
JMS PRAL 7
R
I Sl~!,e;ScHe
R
JMP~PLOOPZ
R
D~J !P/L
LAC PWRD2
A
I'-rn-_ ~~
~
R
DAC PWRD2
R
LAC PWRDl
A
2.AL ~
R
DAC* PTO
R
1St PTn
R
JMP ~PLOOP~
A
PCLOS
LAW 1777~
R i)Zfv1 pw.etl.3rSAO PK'5CHR
R
JMP PLOOP7
AEN()C~ LAw' --.1 ~
R
71J-J)-If; ~I:::.. J.A,.O..-Pt11f1
A
CMA
R
/SZ ~ \. --I AD PTO
R
~JMP* PACK

u
u
u
I

000000
2vHH'J00

R
R

00'014

0-.

R
R

u
LJ
U
U

0V:021
0V0?2
0~0?'3

R
R

600~43

0(7.025

200054
740f?1f{J
040054

00'026

2000'53

0t7;0?7

R
R

744010
060052
440052
6V'10050
777773
540045

0~·024

0~030
0~031

00'032
0V033

~~034

0V035
0V036
o(i" 0 3 7

0(7'040
0('1,041

~(i"042

m57

R
R
R

R
R

6~0?20

340047

R
R
R

740~01

7~0?01

340~52

6?0000

I 5 Z P F R m1

YJIt ~1l.U2N, ~

~
A(~ESS.

IGET FROM
IGIVE TO FROM POINTER.
IGET ADDRESS OF TO ARRAY.
IGIVE TO OUTPUT POINTER.
ISAVE AS START ADDRESS.
IBUMP TO RETURN.
ISET UP
..
/.::;-- c!~T~ ~ ~-oe.
IG[T NEXT WORD IN INPUT ARRAY.
ITfRMINATOR?
INO, SKIP.
IYES, GO CLOSE OUTPUT ARRAY.
IPOINT TO NEXT WORD.
- I POI ~ T T 0 ~J EXT II 0 RD.

@;f

ISET UP TO ROTATE.
7
15 CHARS IN. Q
•
INO, GET AN
HFR.
IWORD PAIR COMPLETE,
ICLEAR PA I RBI T 35

.
d

""'C

CJ
""'C

-.0
-I

IINCOMPLETE PAIR.
IFORM WORD PAIR COUNT£
1ST ART ADDRESS.
e
ILESS END ADDRESS.
IRFTURN TO CALLER.

J-J

P~;H!! ~

Input File Listing Marked for Correction

.,.2

-I

IGET FIRST WD OF P R ••
IBIT 0 OF WD 2.
IINSERT FIRST WD IN OUT ARRAY,
IBUMP OUT ADDRESS,
IGO SET UP NEXT PA I R.
IMAKE SURE PAIR IS COMPLETE.

Figure 6-2

w()etM ~,e-v

A wo~tJ tn=A-u.....t~ MLL4T

I~MI AJAT~ TIJe INPuT (UNrAG~ea) A7<!1!Av.

~~~~~~ ~~T ~7 (.Er--10
Pio

ikJl--t}$ IoTIH-

JSy p~t:=-iJAeIlAY.

CJ
~

o
;;:0

PDP-9 TEXT EDITOR
EDITOH
>OPEN PACK ShC
>FIND ISUBhOUT
ISUBnOUTINE PAGX~ 7-81T CHARS TO lOPS ASCII.
>OVEHLAY 1
INPUT
ISUEhOUTINE PACK~ 7-BIT L~FT-AD,ruSTEU CHAhS TO NON-HEADEEED lOPS
I ASC I I. ON hETUriN ~ AC HOLDS TOTAL v.JO,,\ US acc UP I ED BY PACKED Af~hAY.
IA WOhD OF ALL l'S MUST O\TEHMI~ATE THE INPUT (UNPACKEU) AhhAY.

1
2

3
4
5
6
7
8
9

10
EDIT
>LOCATE FhOM
FliOt<,
I
>Aj-lj-lEND
ISTAhT OF IN~UT AhhAY.
>NEXT
>APENiJ
IS1'AhT OF OUTPUT AhhAY.
NOT A i{E\:.lUEST:
APEND
ISTAhT OF' OUTPUT AHhAY.
>AP?END
ISTAhT OF OUTPUT AhhAY.
>PHINT 1
I
ISTAi'd' OF OUTPUT AhRAY.
TO
>INSEHT
.GLOEL PACK~ PE.AL7~ PWhDl~ P\IiH.D2~ P~'ED3
>L LAC
LAC PACK
IGET F~OM ADRESS.
>CHANGE LAC/LAC*I
IGET FHOV ADHESS.
LAC PACK
?CHANGE ILAC/LAC*I
IGET FHOM ALhESS.
LAC* PACK
>l>JEXT 1
>INS£hT
INPUf
I BUMP TO "TO" AlJDi\E:SS.
ISZ PACK
EDIT
>PhINT

13
14
15
16

18
19
20
21
22

23
24

26
27
28

,29

30
31

32
33

34
bUlVl,P TO "TO" ADUhESS.

ISZ PACK

lSI: PACK

IBUMP TO "TO" AUDhESS.

>BrdEF ON
>C • I • I ..
>PRINT
>L PLBH

35
36
37
38
39

40
41

42
UAC PLBH

>BhIEF OF'F
>PhINT
lJ.l\C

>DELETE 2
>,PrlINT
PLOOPl
>N 1
>A
>L

PLBH

ISAVE AS STAhT ADDHESS.

44
45
46
47
48

LAW 17773

ISET UP

51
52

15-CHAl-<ACTEh COUNTER.

'sAC (-1
>VEriIFY OFF
>C ISAC/SADI
>C 1(-1/ENUCHHI
>V Or>J
>P
SAD ENDCHh
>N

ITEhMINATOH?

53
54

55
56
57

ITEHt-J INATOh?

>'0

>N
>P
ISZ PFhOM

Figure 6-3A

IPOINT TO NEXT

~OhD.

Hard-Copy Output of Editing Session

6-4

58
59
60
61

62
63

PDP-9 TEXT EDITOR
>D
>P
ISZ PFHOM
>F PL
PLOOP?
JMS PHAL?
>N
>nETYPE
IS2 PK5CHri
>N
>C .. LP .. PL ..
JtviP PLOOP2
>N 2
>CHANGE /L/L!CLL
HAL! CLL
>L hAL
rtAL!CLL
>C /fCLL//
hAL
>L JMP
~Jr.':P PL00P 1
>CHANGE /00/00/
JMP PLOOPI
>N

6:)
66
67'

/POINT TO NEXT WOHD.

69
70

/5 CHAHS IN?
/NO ..

71
72

73
7 l t-

GET ANOTHER.

7:)
76

/CLc:.t\h PAlh BIT 35.

7t3
79

/BIT 0 OF vJD 2.

80
81

/BIT .0 OF \I)D 2.

8;~

/GO SET UP NEXT PAIR.
/(30

83
8 1i8~)

SET UP NEXT PAIR.

8'7

INF)UT
DZlv: P\YKu3

/FILL PAIH WI'fH

CLA!CMA
LAW-l

/FOHM WORD PAIh COUNT
/FOHM ~OhD PAIR COUNT.

813
2~~O~S.

EDIT
>L
>h ENDCHh
>N
>h
>L PTO

/STAhT ADDhESS.

TAD* PACK
TAD PTO
ISZ PACK

>INSEHT
>BOTTOM

/LESS END

PhO@PTO
PK5CHR

ADDH~SS.

0
(3
(6

• END
EDIT
>TOP
>L ADRESS
LAC* PACK
>C /ADR/AI.JDR/
LAC* PACK
>LOCATE ••
LAC P\'/hlJ 1
>V OFT,
>C /h./HU
>PRINT
LAC P~lihI.Jl
>CLOSE

/GET FROM ADRESS.
/GET FROM ADDRESS.
IGE~ ~IRST WlJ OF

/G~T

PAh ••

FIRST WD OF PAIR.

ElJITOH

>EXIT
MONITOR

Figure 6-3B

Hard-Copy Output of Editing Session (continued)

6-5

93
9j~

9~)

9'7

.END
>OVEhLAY
INPUT
PFROM

89
90
91
92

98
99

100
101
102
103
10·4
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

~'0~1
000~2

R
R

~4004?

A
R
R

0~0et3

440V'elQI

00004

220(1100

0G\005

~4""r.,43

777773
040'(.44
2?0,/l4?
540034

A
R
R
R
R
R
V
V
R
R

~"0et6

idV"007
""'010

0v'011

~"012

R
R
R

440!i'4?

1~H~(i14"
44~044

0V020

R
R
R

0Hl?1
0"022

R
R

00'023

0400'47
2'?:004fl

0Ct:024
I{)v0?5

R
R

0fl0V!43

0HH3
ItH'014
0"015
il)v016
~V'0::17

0I
0-

1Zle'0(}'0V'1
2?0(;100

~v0~0

60~H"3(]1
~409i5Q1

6007:H'
2~1Zl'i'47

744V'10

A
V
V
A
R
R
R
A
V

740~HI

0~0?6

44V!~43

{)(1'0?7

6(71000(-

~v030

R
R

77777~

liHIt131
""032
0"033
It1v034
0V035
vlV036

(137
!i:iv1.140
ith 1t'J41
(.1PvJ42
'1(1

1(j(1043

I()v044

R
R

140V'5C11
540')\44
6i)v.J~1~

777777

36V1'?l0~

74~i?01

340 1.11 43
44""00"
62100.00

R
R

Vi0 kH"0. VI
frW 171 ,,\ [{Hi'
IJv'M'00!
0(11~I7I~H~

R
A
R
A
R
R
R
A
A
A

iSUBROUiiNF PACK, 7-RIT LEFT-ADJ~STED CHARS TO NON-HEADERED lOPS
IASCII. ON RETUR"J, AC HOLDS TOTAL WORDS OCCUPIED BY PACKED ARRAY.
IA WORD OF ALL l'S MUST TERM I NA!..[ THE INPUT (UNPACKED) ARRAY.
ICALL:
JMS PACK
I
FROM
1ST ART OF INPUT ARRAY.
I
TO
1ST ART OF OUTPUT ARRAY.
.GLORL PACK, PRAL7, PWRD1, PWR02, PWRD3
PACK
V'I
LACo PACK
IG[T FROM ADDRESS.
OAC PFROt-l
IGIVE TO FROM POINTER.
ISr PAf".:K
IBUMP TO "TO" ADDRESS.
LACo PACK
IGETADDRESS OF TO ARRAY.
OAC PTn
IGIVE TO OUTPUT POINTER.
'LA~ 17773
PLOOPl
ISfT UP
DAC PK'5CHR
15-CHARACTER COUNTER.
PLOOP2
LACo PFROM
/GfT NEXT WORD IN INPUT ARRAY.
SAO ENf)CHR
ITrRMINATOR?
JMP PCLOS
IYP::S, GO CLOSE OUTPUT ARRAY.
rSil PFROt-l
IPOINT TO NEXT WORD.
OAC PWRD3
ISfT UP TO ROTATE.
PLOOP7
JMS PRA.L7
ISl PK'5CHR
15 CHARS IN?
JMP PLOOP2
INO, GET ANOTHER.
LAC PWRD?
IWOR!) PAIR COMPLETE.
RAL:CLL
ICLEAR PAIR RIT 35.
OAC PwRD2
LAr Pn R Dl
IGEi FiRST WD OF PAIR.
RAL
IBIT
OF WD 2.
DACO PTO
IINSF.RT FIRST WD IN OUT ARRAY.
1St: PTn
IRUMP OUT ADDRESS.
JMP PLOOPl
IGO SE.T UP NEXT PAIR.
PCLOS
LAi.; 17773
IMAKE SURE PAIR IS COMPLETE.
nt~ PWRD3
IFILL PAIR WITH lERO[S.
SAD PK'5CHR
JMP PLOOP7
IINCOMPLrTE PAIR.
LAW -1
fNOCYR
IFORM WORD PAIR COUNT.
TAn* PACK
1ST ART ADDRESS.
CMA
TA('1 PTn
ILESS ENI1 ADDRESS.
IS2 PACK
JMP* PACK
IRE TURN TO CALLER.
v;
PFRO"1
PTO
0
PK'5C'-IR
'.ENO
"

Figure 6-4

File Resulting From Editing Session

-0

0
-0
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

Line Number*

Section

n/a

Transfer control to Monitor.

124

4.24

Line Number

Section

File Housekeeping
Abbreviation

Activity

OPEN nm ext

n/a

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

4. 1

n/a

Terminate editing on input file.

121

4.2

Command

Locative Requests
FIND string

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

3,68

4.5

LOCA TE string

Bring first line containing "string"
to work area.

12,52

4.6

Bring next consecutive line to
work area.

15,70

4.3

BOTTOM

Bring last Iine of fi Ie 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

Manieulative Reguests
DELETE

Discard the current line.

47,61

4.7

RETYPE string

Replace current line with "string".

71,94

4.9

INSERT string

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

4.10

Replace, in the current line, the
first occurrence of "string 1" with
"string2" .

25,27,38

4.13

CHANGE /string 1/string2/
C
OVERLAY

Replace multiple lines.

5, 102

4.16

APPEND string

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

14,16,19

4.17

*Entries under II Line Number" refer to Iine 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,
LOCATE, 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 file.

4.22

GET

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

4.12

Mis ce II a neous Reg uests
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 Alphanumeric (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 Ie (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) .............................................. .

.04.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

Section

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 .......••.....................•............

'10

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

'10

5
5.1
5. 1 . 1

Copying Fi les

5.1 .2

Creating Fi les

5.1 .3

Li stin g Fi Ie s

........................".......................

5.1.4

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

5.1.5

Using the C or E Switches ..... . ............................. .

5.1.6

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

5.1.7

Using the W Switch

5.1.8

Using the Y Switch

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

13
13

5.2

Verify Fi Ie (V)

5.3

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

5.4

Li s t Di re c to ry (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

(Control Key P) ............................................. .

6.2

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

6.3

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

6.4

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

APPENDIXES
Appendix

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

A1-1

PIP-9 ERROR MESSAGES

A2-1

.............................. " ..........•...

TAB LE S
Table

3-1

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

3-2

PIP-9 Device Names

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

4-1

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

4-2

Lega I 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 only)

Te letype (KSR 33 or KSR 35)

Card Reader (CROl E or CR02B)

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

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

signed to positive slots in the Monitor's Device Assignment Table. This is for use by PIP. V.,lhen 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 appropriate handlers are included 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
10

DTAO
DTA1
DTA2
TTAO
PRAO
PPAO
DTAl
DTA2

PIP-9 COMMAND STRING: GENERAL
Once in core memory I 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 pri ntou·t exami nation. PIP command
strings are of the following general form:
a ddl :

lfnamer

~PAC~

where,

lext (x) .... sdf

~PACEJ

: Jfnamer

~PACE

lext (x)r~
[t.LT MOD~

~PAC!U

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 for another 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:

T L....JDTl ~ NEWNAM BIN (B) ..... L...JDT2 ,-,OLDNAM I-JBIN~

DT1:NEWNAM;BIN

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

The elements in the preceding example are:

PIP-9 Transfer File operation

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)

3. 1 (

Swi tch 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 File
Block Copy
New Directory

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

some peripherals, a 2-Ietter 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 periph-

erals, e.g., DECtape, the unit number, 0-7, appears after the device manemonic, e.g., DT?
device name delimiter must be a colon (:) or a space.

The

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

DECtape~

(DT)
(MT) Magnetic Tape
(CD) Card Reader
(DK) Disk

Paper Tape Reader
Paper Tape Punch
Teletype
Line Printer

~----------------------------------------------,

3.3

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

file-name delimiter is a semicolon (;) 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 ( I ) . 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 files)

or DT5 FILEA, FILEB SRC

PR:, ,

(3 fi les)

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, (:), (;), (,), (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 with the source device
information. PIP-9 switch options are divided into two c lasses: (I) 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 d i rec tory

(Y)

Segment fi Ie

(W)*

Combine several source files, or tapes, stripping .EOrs 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 File,

(2) Verify File, (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 combi ned 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.

Th is function is particularly usefu I for verifying paper tapes copied with the T command.

4.1.3

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

whose unwieldy bulk makes two or more smaller tapes desirable. AI I PIP-9 operation command:) 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 c"lows
for up to sixteen segmentation points or character strings (1-5 characters) at the beginning of lines at
which 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
-

Lega I Swi tches

Transfer File (T)

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

Verify File (V)

A or B

Segment Fi Ie (S)

(None)

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

I
I

PIP-9

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

4.2.1

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 detai led discussion of lOPS ASCII.) If for some reason th is is undesirable to the user, a data mode
of (I) is recommended.
Bad Parity Correction (G) - Whenever data modes (A) or (B) are specified during a Transfer

4.2.4

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 lines 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 I ine may be replaced from the keyboard. The option to restart ('f'P) is cdways
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 mu Itiple spaces on an input fi Ie into horizonta I tabs on the output fi Ie. Trail ing 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 fi Ie 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 paper 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 fi les, 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. EaT'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 operations

with PIP-9.

In addition to the ~ransfer, '!.erify and ~egment file operation, the following are available:

(1 ) _~ist Directory, (2) ~ew Directory, (3) pel ete 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 listed on

teleprinter or line printer with the L command. The file name, extension, starting block number and
number of blocks occupi ed, are pri nted 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 opera-

tion is employed. Deletion implies removing references to the file from both the Directory and File Bit
Map blocks.
4.3.4

Rename File (R) - Renaming one or more fi les requires an R command. Only the name and

extension in the Directory are changed.
4.3.5

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

system tapes) in their entirety. Programmed read-after-write verification is performed. Differences in
file structuring wi II be accounted for in the transfer from one type of devi ce 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 operation.
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 additional switch options are available in a Keyboard Monitor environment. Two are

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

New Directory (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, B, 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 Fi Ie
Switches

~ I
j
~ I

j
j

I ~

j
j

4.4. 1

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
(once 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 DEC tape copy.

Later examples wi II illustrate

this use of H mode.

4.4.2

Dump Mode (D) - Files recorded in dump mode may cust'omarily 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 switch 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 DAT slot one (1) must be assigned to the system device in order to use the S switch.

Basic

system tape refers to the Directory, Fi Ie 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 (i) delimiters for use of which the
reader may refer to Section 3, page 3.
5. 1

Transfer Fi Ie (T)
Under the T command are included the tasks of listing, copying, creating, combining and

segmenting files.

An input and an output device are required in the command string as well as one of

the five (5) data modes. Fi Ie names must be spec ified only for fi Ie structured devices.
5. 1 • 1

Copying Files - The command:
T DT7 FILEA SRC (A) 4 - PR,J

copies a single tape from the paper tape reader to DECtape unit 7 in lOPS ASCII mode.
The command:
T DT7 FA SRC,FB SRC,FC SRC (A)4- PR,,;
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) ...--DT 1 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 facilities 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+D (Control Key D) must be typed.

5.1.3

Listing Files 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 typed.

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

(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)4-PR~
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)...-DT2 FILEB SRC~
effects a transfer of FILEB SR<: 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)..e----PR,l
initializes the Directory and File Bit maps of DECtape unit 4 and, subsequently, transfers the paper tape
fi Ie to DECtape in image ASCII mode.
Given a DAT slot 1 assignment of DTAO and PDP-9 Advanced Software System tape on DECtape unit 0, the command:
T DT4 FILEA BIN (BS)+-PR#.
copies system programs and Directory information from DECtape unit 0 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 file.

The W switch performs this function. It is legal with

data modes A or B and conflicts with the Y switch.
The command:
T DTl FILEA SRC (AW)"'- PR"" ~
transfers five (5) ASCII paper tapes to DECtape unit 1 as the single file, FILEA SRC.

Because inter-

mediate. EOT 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 file.

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-Fi les 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 conflicts with the W
switch.

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

will 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 SRC4-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

fi Ie was so large as to require segmentation, time for operator management of the segments seems appropriate.

5.2

Verify File (V)
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, verifica-

tion 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 names,

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 com-

mand, if a Y switch is specified, PIP-9 will examine the beginning of every line for the specified segmentation points in order of occurrence. Vertical form control characters at the beginning of a line
are exc luded from the string search. As each segmentation point is found, PIP-9 wi II c lose the current
output file segment I appending the pseudo op, . EOT, at the end of the segment. The next segment wi II
start with the line which begins with the current segmentation point.
The command:
S TAGA, TAGB, TAGC, TAGD*
sets up the four segmentation points TAGA, TAGB, TAGC, and TAGD for the immediately following
command:
T PP 1111 (AY) 4-DT3 FILBIG SRC~
the end result is five paper tapes, all but the last of which are terminated with .EOT. The last four
begi n with the lines TAGA---, TAGB---, etc.
As each segment is completed,

f P will be output on the teleprinter allowing time to remove

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:

results in a printout such as the one below:
DIRECTORY LISTING

1st Block of Fi Ie

MACRO ONE

4/ 2264-# of Blocks Occupied

MACRO TWO

140

MACRO SRC

365

4 SYS PGM BLKS

121 FREE BLOCKS
14

PIP-9

s.s

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 operati:on) will
appear as fo Ilows:
DIRECTORY LISTING
4 SYS PGM BLKS
1074 FREE BLOCKS
The four system program blocks are the Directory and three Fi Ie Bit Map blocks.

S.6

Delete Fi Ie (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 de lete both FILEA and FILE B from DECtape un it 3.
S .7

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

any 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.

S.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:
C DTS (H)+-DT3,l

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 DT5+-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) .--DT3

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

Use of the S Switch:
C DT5 (S) + - 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 devi ce.
5.9

_Block Copy (B)
To copy one or more blocks of one DECtape onto another, the B command is used. Switches

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 desti nation 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 .--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.

_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 string
information after a PIP-9 error message are others.

PIP-9
6. 1

4p (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 loadi ng 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 de leted 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

t U (Control Key U)
At any point whi Ie 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).- PR~
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

'U.

Appendix II contains a complete list of PIP-9 error messages. Hence only two exclmples are
cited here. Suppose a user intends to transfer an lOPS ASCII file from paper tape to DECtape. He
types:
T DT2 FILEA SRC (F)4-PR,l

PIP-9

Recognizing F as an illegal switch option, PIP-9 types:
INVALID SWITCH OPTION
T DT2 FILEA 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.
[f a DECtape handler and unit are not assigned to any of the positive .DAT 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. DAT
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 Fi Ie

Yes

Verify File
Segment Fi Ie

V
S

No
No

Yes
No

No
No*

Legal Switches
A,B,I,IE,
G,C,'N,Y
A or B
None

Keyboard Monitor Environment:
Command

Abbrev.

Dest. Dev.

Transfer Fi Ie

Yes

Verify File
Segment Fi Ie
list Directory
New Di rec tory
Delete File
Rename File
Copy Tape
Block Copy

V
S
L
N
D

No
No
Yes
Yes
No
Yes
Yes
Yes

R
C
B

File Names

Legal Switches

Yes

Yes
No
Yes
No
Yes
Yes
Yes
Yes

Yes
No*
No
No
Yes
Yes
No
No**

A,B,I,IH,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 fi Ie names.

Al-l

PIP-9
Appendix II
PIP-9 Error Messages

Command String Too Long, Try Again

Retype command string

III. Function

Retype from function character on.

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

Retype from deyice name on.

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

Type
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.
Source Fi Ie Not on Dey.
t

Too Many Source Files
Too Many Dest. Files

Name}

}

Retype from Fi Ie Name
on.
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 Dey.
)
III. Switch
Switch Conflict
Switch III. for Function

Retype from swi tch on.

III. Terminator

Retype from terminator 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

Check data

III. Blk.

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. Files for # of Segment Points

Retype command string with correct # of destination files. (l more than # of segmentation points).

A2-1

LINKING LOADER

LINKING LOADER
CONTENTS
Section
1.

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

DEFINITIONS .••••••.•••••••..•.••••..•••.••.••••••••••.••••••..•.,.

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

7.2

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

7-4

MEMORY MAPS .••.••••.••••.••••..•.•.•••••••••••..•.••••••••••. ".

8-1

8. 1

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

8-1

8.2

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

8-3

A-1

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

A1-1

A-2

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

A2-1

7. 1

iii

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 linking relocatable and absolute units.

For

FORTRAN and Assembler generated program units, the Loader al so assigns the common data storage area.
The input medium may be any input device.
Initially the loader will load all 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 Loaaer automatically loads and I inks all requested and unresolved library subprograms.

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

that order).

After both Iibraries have been exam ined for requested subprograms, the loader displays the

names of all subprograms which have not been found.

If the user requires I/O handlers that are already

'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 wi II prevent this type of loading.
!~ram in the next memory bank.

The Loader wi II, however, load (and I ink) 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-line 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 valu,e 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 consist's 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
Code 1

11
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 qetermine whether
the program wi" fit within the unused locations of any avai lable 8K memory
bank.

Loading terminates with an appropriate error message if the program can-

not 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; th is 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).

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 spec ifi4gs 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 absolu'te address

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

Data Word

Load Address

{O,

relative load address

1, absolute load address
03

Re locatable 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

[Op Code

----------I~-----u-n-r-e-I-oc-a-t-e-d------~

Data Word

Memory Address

Absolute Instruction/Constant/Address
The data word is either a non-memory referencing instruction, a non-relocatable memory referencing instruction, an tJbsolute address, or a constant.

The

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

o
Data Word

17
Non-Re locatable 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.

o
Data Word

2 3

r-o- o

17
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.

Storage allocation begins at the address spec ified

The load address is incremented by this number.

The

block of memory is not cleared.

o
Data Word
07

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
8
(see appendix 1), The data word is saved by the loader for future reference.

4-2

LINKING LOADER

Loader Action

Code

012

Ixlo i
L {o,

Data Word

Symbol
1- to 3-character symbol

1, 4- to 6-character symbol
08

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 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 lrhe 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 l.oader
symbol dictionary as a request for subprogram loading.

This action automati-

cally forces the Loader into a library 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

17
SUB {radix 508)

1010 I

TVADD

2 3

and SUB defined internally as TVADD.
JMS* SUB

4-3

17
17
TVADD
Subroutine calls are made via

TVADD

LINKING LOADER

Loader Action

Code

o
Data Word

10
Transfer Vector Address
~~--------"

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 dictionary, 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 units
until the next internal global symbol definition is found (library search mode).
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
Data Word

[0 I

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.

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, the

assignment of memory space for the common block is deferred until all requested
Iibrary 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 starting 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 associated

LINKING LOADER

Code

Loader Action
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 wi II 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 assil:Jned 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 symbc)1 is calculated (block address plus relative position) and placed in T. V. loccltion
(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 0:7 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 (c:ode 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

17
Address of Vector

Data Word
15

Data In itia Iization 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).

o
Data Word
16

[

Data Constant

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

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

o
Data Word
17

17
Data Constant

[

---------'

Data Initial ization 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).

o
Data Word

17
Data Constant

[

--------------------~

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

The load address is incremented by the

current relocation factor (modulo 15 bits) if the constant initial izes a noncommon 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.

o1 2 3
Data Word

~ XX

OO, mode = integer (1 word)
_

Load Address

01, mode = reol

(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 conditionally (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.

o 1

Data Word

Symbol Definition

L {O, internal symbol
1, program name -- from FORTRAN IV or
MACRO-9 comm,ond 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 115 bits) ad-

dress is saved by the Loader for future use (code 21).

o
Data Word
21

3
0

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 replaced with this address (relocated modulo 13 bits).

Data Word
22

4 5

1 0-

0 1

Replacement Address

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

The Loader defers loading of any I/O routines until

all other subprogram loading has been completed; when subprogram loading is
complete, the system I ibrary is searched for a II 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 Acti on

Code

o
Data Word

Unit Number

t{ =

L 2's complement when
0 single uni't
negative
1 = all units
(. IODEV ALL) all
posi tive • 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 to be
used when control is given to the user.

Only the first start address encountered

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 address 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 I ibraries, the end unit

causes the Loader to examine the next I ine buffer for the end-of-file condition.
When the e nd-of-fi Ie for the externa I I ibrary is obta ined, the Loader automatically begins searching the system library to resolve any remaining globals.
Upon encountering the end-of-file of the system library, the Loader announces
any unresolved global names.

When 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

- - . . J -_ _ _ _- - - - - '

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 12, 13 and 14)
NON-COMMON STORAGE (code 06)
Array Declaration Information
Equivalenced Arrays and Variables
Non-Equivalenced Arrays
PROGRAM BODY

Instructions

Codes
3
04

Codes

07 }
08
09

Symbol
External Symbol
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 1 does not include 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)
NO N-COMMO N STORAGE (code 06)
Array Declaration Information
Equivalenced Arrays and Variables
Non-Equivalenced Arrays
PROGRAM BODY
Codes
Codes

07
08

Instructions

{

04
05

Constants
Non-Equivalenced Variables
Literals
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

L1NKI NG LOADER

SECTION 6
DEFINITIONS
!.oadable Program Unit

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

Transfer Vector

A core location containing the address of a 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 util izing 508 characters as a "'number"
set each with a unique value between and including to 47 , The sym8
bol ("number") is converted using standard base conversion methods
(see appendix 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 fla~J.

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 (AL T 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 fi Ie name is terminated by a comma (,), a carriage return (~), or AL T mode.

Unti I 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.
AL T mode terminates the command string. When the input device is not fi Ie oriented, N
commas, followed by the ALT mode wi II 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: .LIBR

,---___________ _ ______________

PROGRAM
UNIT

~A~

______________ .______________

1-- ----I

PROGRAM
UNIT

PROGRAM SIZE
DESCRIPTOR

PROGRAM UNIT
r -________

INTERNAL
GLOBALS

~A~

__________

LOAD ADDRESS
DESCRIPTOR
PROGRAM
UNIT
DATA
TWO-WORD
HEADER

VIRTUAL
GLOBALS
END CODE

Cn'"Z31O TERMINATES
A PROGRAM UNIT. THE
NEXT UNIT MUST BEGIN
A NEW IOPS BINARY
BUFFER.

48 10
WORDS

0-89-17
WORD 0
WORD 1

I----...L.----t}

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

END-OF-FILE UNIT ONLY PRESENT
AT END' OFLIBR 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 ad-

dresses) of all the programs requested in the command string, followed by the required I ibrary routines
in the following format:
NAME1
NAME2
NAME3
NAME4
NAME5
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 t P on the te leprinter. To continue, place
more input in the device, and if the paper tape reader momentari Iy depress the
tape feed contro I, and type t P on the keyboard.
7. 1 .3

Error Messages
The Loader will output to the teleprinter· LOAD followed by the pertinent error code and

then it wi II halt.
Error Code

Mean i ng
Memory overflow - the Loader1s symbol table and the user1s program have overlapped. The loader memory map will contain printouts of all programs successfully 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 error, checksum error, illegal data code or buffer overflow (input line bigger than Loader1s 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 Monitor 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 1'S on the keyboard will give
control to the starting address of the user1s 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 vi a the . EXIT command,
the computer wi II 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 WClnts, 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 wi II not make use of th is feature, he should ASSIGN NO NE 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 loading
with the DDTNS keyboard command.
$ASSIGN

For example,

NONE

-6, -10

$DDTNS
This feature gives the user more operating space but deprives him of symbolic references 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 library 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 start'ing address of DDT.

7-4

LINKING LOADER

When the user program has completed its operation and terminated via the • EXIT command I
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 Loadinu.

GLOBAL
SYMBOL
TABLE

•

SCOM +2

•

SCOM +1

LINKING LOADER

PAPER TAPE
READER HANDLER

110 MONITOR
WITH TELETYPE -IN
AND
TELETYPE-OUT
DEVICE HANDLERS

8-1

LINKING LOADER

DDT Tape
8K or 16K or

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.

USER
PROGRAMS

GLOBAL AND
DDT
SYMBOL TABLES

• SCOM +2

LINKING
LOADER

Paper Tape Punch Handler is only present in
version of DDT with patch file capabilities.

PAPER TAPE
PUNCH HANDLER
PAPER TAPE
READER HANDLER
•

SCOM + I

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
BOOTSTRAP

The System Loader learns which I/O handlers
are required by the Linking Loader, loads
them relocatably and then loads the Linking
Loader relocatably.

• SCOM AND. SCOM +3

The Linking Loader, during loading of user
programs down from • SCOM+3 bui'lds the
loader (GLOBAL) and DDT (if DDT) symbol
tables up from .SCOM+2.

If a DDT load, 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 c] 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-in itial ize 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
bui I t.

DDT
SYMBOL

-----TABLE
COMPACT DDT {
SYMBOL TABLE

fllllllllllllllj
LINKING LOADER
DEVICE HANDLER
LINKING LOADER
DEVICE HANDLER

Non BLOCK DATA COMMON (FORTRAN IV
or MACRO-9 output) may make use of core
as low as the compact DDT symbol table (DDT
only retclins certain symbol table entries).
However, the user must be careful about
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 requests.

8-4

LINKING LOADER

Phase 2 ( Not DDT or DDTNS)
8K or 16K or
24K or 32K

RESIDENT
SYSTEM
BOOTSTRAP

•

SCOM

•

SCOM +3

. 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+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

1--------.
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.1

RESIDENT
KM-9
(INCLUDING
TELETYPE
HANDLER)

8-5

LINKING LOADER

APPENDIX 1
SYMBOL CONCATENATION - RADIX 508 FORMAT
Radix 508 is a technique used by the MACRO-9 Assembler and the FORTRAN IV Cc:>mpiler
to condense the binary representation of symbolic names in symbol tables. Three characters plus two
symbol classification bits are contained in each lS-bit word. A symbol is defined as a string c:>f one
to six characters, i.e. I

where C. is defined as
I

Character

6-bit octal code

Space

9
#

The symbol is concatenated as follows:
((C * 508) +C 2 ) 50 +C
1
S
3

Word 1
Word 2

For example: The symbol SYMNAM would be entered in the Loader's symbol table as:
Word 1

((23 * 5°8)+31 8 )5°8+ 15 8
8

475265*

Word 2

((168 * 5°8)+1)5°8+ 15 8

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

I D = 7 when not defined

Block Size

ID = 3 when defined

Name (2A)

Symtab address of last entry in chain

Block Definition
II

o if no entries
o if not defined

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 j's needed
in the symbol table.
Virtual Global (internal)

Definition
Name (2A)

Definition (Virtual) = Absolute Address of last TV in chain

Virtual

Definition (Internal) = Absolute Address of Symbol

Internal ID = 5

ID = 1

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

On Iy 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 Mon itor (paper tape system) or the Keyboard Mon itor (DECtape or other mass storage systems).
Basicall y, th is program converts statements in the input PDP-7 program to equ iva lent
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

Iisted below.
ANALEX

FIODEC

NOSYMBOLS

SYMBOLS

BAR

FIX

PUNCH

TELETYPE

CHAR

FLEX

PUNDEF

TEXT

EXPUNGE

NOINPUT

VARIABLES

Since MACRO-9 does not allow mu Itiword variables, the dollar sign ($) shou Id 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 sem icolon

delimiter as required 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 *, as LAC

A to LAC'" A.

Normally, the converter does not produce a printed I isting, and term inates programs with an
.END statement. The user may make command string entries, however, to request the following 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

terminator

filel

file2

• (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, control 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 terminator. 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 Mon itor
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 -114, 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 operation of adjusting statement format from that of the Basic Assembler to that of MACRO-9. If any of the pseudo-ops listed 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 converter.

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 converter.

Edit
1.

revise coding to remove pseudo-ops which MACRO-9 cannot handle.

revise input/output procedures to utilize 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? ________________________________________---:-_

Did you find this manual easy to use? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

What is the most serious fault in this manual? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

Did you find errors in th~ manual? Please describe. _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _~

Please describe your position. _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _-;--_
Name, _________________________

OrganizationL--______________._________

Street

State ______________________

Zip'---_ _ ___

••......•.........•....••..•••......................•............•........................ Fold Here ....................................................................................... .

............................................................................ Do Not T.ear - Fold Her.e and Staple ............................................................. ..

FIRST CLASS
PERMIT NO. 33
MAYNARD, 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

To The Reader
Notification of changes and revis ions 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. II
Revised software products and documents are shipped only after the Program
Library receives a specific 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 wi II be placed on the mai ling list.

_ ....... _ _ _ _ _ _ . _ _ _ ..-,-" _ _ _ --..-. _ _ -.-r ......... _ _ _ _

To:

. . . ........, - . . . . . _ _

.a _ _ _

~-~-~

- . -. . . . . .

---a.---...-...- .......

--~

...- .... -.-.- "':II.oi., ...... - .....- , . . . . . . . . -."-...,... ...... '"'--"- -

DECUS Office,
Digital Equipment Corporation,
Maynard, Mass. 01 754

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)

•• .- - - -

_ ..

[)IGITAL EQUIPMENT CORPORATION. MAYNARD, MASSACHUSETTS
Printed in U.S.A.