Digital PDFs

DEC-08-MEXB-D

December 1972

138 pages

Original

2.7MB

Document:	PS8 SWSupMan
Order Number:	DEC-08-MEXB-D
Revision:
Pages:	138
Original Filename:	https://svn.so-much-stuff.com/svn/trunk/pdp8/src/dec/dec-08-mex/dec-08-mexb-d.pdf

OCR Text

mmm

soPtuuare support

manual

digital equipment corporation

PS/ 8 SOFTWARE SUPPORT MANUAL

For additional copies, order No. DEC-0 8-MEXB-D from the
Program Library, Digital Equipment Corporation, Mayneird,
Massachusetts, 01754.
Price; ^MB^

First edition, July 1970
Second edition, April 19 71

19 70,

19 71^ 1972 by

Digital Equipment Corporation

The following are trademarks of Digital Equipment
Corporation, Maynard, Massachusetts:
DEC

PDP

COMPUTE RLAB

FLIP CHIP

FOCAL

DIGITAL

UN IB US

OMNIBUS

CONTENTS

CHAPTER

PS/ 8 CONCEPTS AND TERMINOLOGY

1-1

1.1

1-1

Software Components of PS/
Files

1.2

1.2.1
1.2.2

1.2.3

1.2.4
1.3

1.3.1
1.3.2
1.4

File Types
File Directories and Additional
Information Words
Core Control Block
Program Starting Address
Job Status Word

Device Names and Device Numbers
The DEVICE and FILENAME
Pseudo-ops

1.5

CHAPTER

File Names and Extensions
File Structured Devices

1-2
1-2

1-3
1-3

1-4
1-5
1-6
1-6

1-7
1-8

USER SERVICE ROUTINE
2.1
Calling the USR

2--1

2.1.1

Standard USR Call

2--1

2.1.2

Direct and Indirect Calling
Sequence

2.2

2.2.1
,1
,2

3
4

.2.5
.2.6

.2.7
,2.8
.2.9

,2.10

Summary of USR Functions
FETCH Device Hahdler

LOOKUP

Permanent File
ENTER Output (Tentative) File
The CLOSE Function
Call Command Decoder (DECODE)
CHAIN Function
Signal User ERROR
Lock USR in Core (USRIN)
Dismiss USR from Core (USROUT)
Ascertain Device Information

2--1

2--3
2--4

2--7
2-

2-10

2-12

2-13

2-14
2-15
2-•16

2-17

(INQUIRE)

2.2.11

RESET System Tables

2-18

THE COMMAND DECODER
Coininand Decoder Convention
3.1
Command Decoder Error Messages
3.2

CHAPTER 3

3.3

3.4

3.4.1
3.4.2
3.4.3

3.4.4
3.5

3.5.1
3.5.2

CHAPTER 4

4.2.3

Input Files
Command Decoder Option Table

Example
Special Mode of the Command Decoder
Calling the Command Decoder
Special Mode
Operation of the Command
Decoder in Special Mode

USING DEVICE HANDLERS
4.1 Calling Device Handlers
Device Dependent Operations
4,
4.

CHAPTER

Calling the Command Decoder
Command Decoder Tables
Output Files

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

3-5
3-6

3-7

3-8
3-9

3-10
3-10

4-1
4-1
4-4

Teletype (TTY)
High-Speed Paper Tape
Reader (PTR)
High-Speed Paper Tape
Punch (PTP)
Line Printer (LPT)

4-4

Card Reader (CDR)
File Structured Devices

4-7

RECONFIGURING THE PS/8 SYSTEM
Conditional Assembly of CONFIG
5.1
System Device Selection
5.1.1
Optional Device Parameters
5.1.2

4-5

4-5
4-6

4-7

5-1
5-1
5-2

5-3

5.1.3

Other Options

5-5

5.1.4

Example

5-6

5.2
3

,3.1
,3.2

Building a System on DECtape
or LINCtape
Adding New Device Handlers
Writing Device Handlers
Editing Device Handlers Into
CONFIG
11

5-7
5-7
5-8

5-12

APPENDIX A

PS/8 FILE STRUCTURES
A.l
/\ « X • X

A. 1.2
A. 1.3
A.

APPENDIX B

Number and Size of PS/8 Files
Sample Directory
File Formats

A-2

A-3
A-

A-5

ASCII and Binary Files

A-5

A. 2.

Core Image {.SV format) Files

A-6

A. 2.

Relocatable FORTRAN Library
File

A-

DETAILED LAYOUT OF THE SYSTEM
B.l
Layout of the System Device
B.2
Layout of the PS/8 Resident
Program
B,3
System Device Tables

B-3

B.3.1

Permanent Device Name Table
User Device Name Table
Device Handler Residency Table
Device Handler Information
Table

B-3

Device Control Word Table
Device Length Table

B-6

B.3.3

B.3.4
B.3.5
B.3.6

APPENDIX D

Directory Entries

A-1

A. 2.1

B.3.2

APPENDIX C

File Directories

A--1

B-1
B-1
B-2

B-4
B-5
B-5

B-7

SYSTEM ERROR CONDITIONS AND MESSAGES
C.l
System Halts
USR Errors
C.2
Keyboard Monitor Errors
C.3
Command Decoder Errors
C.4

C-1

PROGRAMMING NOTES
The Default File Storage
D.l
Device, DSK

D-1

D.2
D.3

D.4

Modification to Card Reader
Handler
Suppression of Carriage Return/
Line Feed in FORTRAN
Accessing the System Date in a
FORTRAN Program

ixx

C-1
C-2

C-4
C-5

D-2

D-2
D-5
D-6

D.5
D.6

D.7
D.8
D.9

D.IO

D.ll

Determining Core Size on PDP-8
Family Computers
Relocating Code
Using PRTC12-F to Convert PS/8
DECtapes to PS/12 LINCtapes
Notes on Loading Device Handlers

D-7

Available Locations in the USR
Area
Accessing Additional Information
Words in PS/
SABR Programming Notes

D-13

D-9

D-10

D-11

D-14
D-16

APPENDIX E

CHARACTER CODES AND CONVENTIONS

E-1

APPENDIX F

DOCUMENTATION UPDATE FOR THE 8K
PROGRAMMING SYSTEM USER'S GUIDE

F-1

F.l

F.1.1
F.l.

F.l.
F.l. 4;

F.2

F.2.1
F.2. 2

F.2. 3
F.2. 4
F.2. 5

CREF, Cross-Reference Program
(DEC-P8-YRXA-PB)
Loading, Calling, and Using
CREF

F-1

Interpreting CREF Output
CREF Pseudo-ops

F-3

Restrictions
LIBSET (DEC-P8-SYXB-PB)
Loading, Calling, and Using
LIBSET
Examples of LIBSET Usage

F-6

Subroutine Names
Sequence for Loading
Subroutines
LIBSET Error Messages

F-1

F-5
F-9

F-9

F-10

F-11

F-11
F-12

INTRODUCTION
The 8K Programming System PS/8, is an extremely powerful

program development system. PS/8 greatly expands the capabilities of any 8K PDP-8, 8/1, 8/L, 8/E, or PDP-12 computer
having the necessary disk or DECtape storage. Use of PS/8
is described in detail in the 8K Programming System User's
Guide with which the reader should be familiar.
,

This manual covers a wide range of advanced topics pertinent
to the experienced user.
In Chapter 1 the various basic
system concepts are described and terms defined. Chapter 2
explains the process by which user programs call upon the

system for the performance of important operations; including loading device handlers, opening and closing files, and
chaining to other programs
Chapter 3 covers the functions
of the Command Decoder and the means by which the user program
can employ its services.
Chapter 4 explains the use and opera.

tion of the device handlers in detail.

Chapter

covers the

details of "custom tailoring" a system, including how to
write a device handler for a non-standard device.

Technical information, intended to enhance the information in
the 8K Programming System User's Guide as well as this manual,
can be found in the Appendices. Appendix A details the PS/8
directory structure and gives standard file formats. Appendix
B describes the system data base and gives the layouts of the

system areas.

Appendix C gives a complete list of system error
messages. Appendix D illustrates some useful advanced techniques
and programming "tricks" for use with the PS/8 system.
Appendix
E is a complete list of the standard ASCII character codes meaningful to PS/8. Finally, Appendix F contains additions to the
8K Programming System User's Guide, sections covering the CREF
and Library Setup programs that will be included in later editions of the User's Guide.

Since it runs
PS/8 does not attempt to solve all problems.
with the interrupt disabled, any calls to the system must be
made with the interrupt turned off. Nonetheless, PS/8 provides a powerful means to solve the most frequently encountered

problems in developing software for PDP-8 family computers.

CHAPTER

PS/8 CONCEPTS AND TERMINOLOGY

Before examining the details of the PS/8 system the reader
should first be familiar with the simpler techniques and terms
used within the framework of the PS/8 system.
The material in
this chapter, along with that contained in the 8K Programming
System User's Guide provides the tools needed to pursue the
later chapters
,

1.1

Software Componenets of PS/8

There are four main components of the PS/8 system:
a.

The Keyboard Monitor performs commands specified by
the user at the console.
The nine Keyboard Monitor
commands (ASSIGN, DEASSIGN, GET, SAVE, ODT, RUN, R,
START, and DATE) are explained in Chapter 2 of the 8K
Programming System User's Guide
.

User programs can exit to the Keyboard Monitor by
executing a JMP to location 7600 in field 0.

NOTE
All JMPs to 7600 must be made
with the DATA FIELD set to zero.

This saves the contents of location
to 1777 in field
and loads the Keyboard Monitor which could be called
by a JMP to location 7605 in field 0.
In this latter
case the contents of core are not saved, which conserves
some time

Existing system programs, device handlers, and the Command
Decoder test for the CTRL/C character in the Teletype*
input buffer and on finding this character abort the
current operation and perform a JMP to 7600 in field 0.
Thus, typing CTRL/C is the conventional method of calling the Keyboard Monitor from the console.
*Teletype is a registered trademark of the Teletype Corporation.

1-1

Device handlers, which are subroutines for performing all device-oriented input/output operations,
These subroutines
can be utilized by any program.
"mask" from the
and
sequences
have standard calling
of the I/O
characteristics
user program the special
I/O is
independent
device
In this way,
device.
handlers
device
of
description
achieved. A detailed
4.
is found in Chapter
The User Service Routine (USR) is to a program what
For example,
the Keyboard Monitor is to the user.
handlers,
device
fetch
to
USR
the
programs can request
to another
chain
device,
any
on
operations
perform file
descripfull
A
Decoder.
Command
program, or call the
2.
Chapter
in
found
is
functions
tion of the USR
The Command Decoder interprets a command line typed
by the user to indicate input and output files and
various options. The command line format is described
in detail in Chapter 3 of the 8K Programming System
The Command Decoder removes the burden
User's Guide
of this repetitive operation from the user's progrtim.
A full description of the Command Decoder's function
is found in Chapter 3.
.

1.2

Files

Files are basic units of the PS/8 system, and a thorough understanding of file structure is required for its use. A file
The format
is any collection of data to be treated as a unit.
of this data is unimportant;

for example, PS/8 can manipulate

several standard formats, including ASCII files, binary files,
The important consideration is that
and core image files.
the data forms a single unit within the system.
1.2.1

File Names and Extensions

An individual file is identified by its file name and extension.
The file name consists of up to six alphanumeric characters,
optionally followed by a two character extension. The extension
is often used to clarify the format of the data within the file.
For example, an ASCII file used as input to PALS might be given
a .PA extension, while a core image file has a .SV extension.

1-2

1.2.2

File Structured Devices

Devices that can be logically divided into a number of 256
word blocks and have the ability to read and write from any

desired block are called file structured devices. Disks and
DECtapes are file structured devices while a paper tape reader
or Teletype is not.
The system device (SYS:) in any PS/8 system is always file

structured.

All PS/8 file structured devices must be logically divided
into these 256 word blocks.
Hence, 256 words is considered
the standard PS/8 block size.

Some devices, like RK8, DEC-

tape, and LINCtape, are physically divided into blocks.

These physical blocks should not be confused with the logical
256-word blocks. For example, DECtapes must be formatted with
standard 129 word physical blocks. A logical PS/8 block consists of the first 128 words of two consecutive physical DECtape blocks.

The 129th word of every DECtape block is not

used by PS/8.

Similarly, LINCtapes are formatted with 129
(or 128) words per block but never 256, as this format is

unacceptable to PS/8.

A given PS/8 file consists of one or more sequential blocks
of 256 words each (consecutively numbered)
A minimum of one
block per file is required, although a single file could
occupy all of the blocks on a device.
.

1.2.3

File Types

Three different types of files exist in the PS/8 system:

An empty file is a contiguous area of unused blocks,
Empty files are created when permanent files are
deleted.

1-3

A tentative file is a file that is open to accept
output and has not yet been closed. Only one tentative file can be open on any single device at one
time.

A permanent file is a file that has been given a
fixed size and is no longer expandable. A tentative file becomes permanent when it is closed.

To further understand file types, consider what occurs when
Normally, the User Service Routine in
a file is created.

creating a tentative file first locates the largest empty
file available and creates a tentative file in that space.
This insures the maximum space into which the file can expand.
The user program then writes data into the tentative file.
At the end of the data, the program calls the USR to close
The USR
the tentative file, making it a permanent file.
does so and allocates whatever space remains on the end of
the tentative file to a new, smaller, empty file.
1.2.4

File Directories and Additional Information Words

To maintain records of the files on a device, PS/8 allocates
blocks 1 through 6 of each file structured device as the file
directory. Entries in this directory inform the system of
the name, size, and location of each file, including all empty
For a detailed
files and the tentative file, if one exists.

description of the entries in the file directory

see Appendix

Each entry in a directory can, optionally, have extra storage
words called Additional Information Words. The number of
Additional Information Words is determined at the time the
directory is intially created (normally by using the /S or
/Z features of PIP; see Chapter 6 in the 8K Programming System
User's Guide.

1-4

Whenever Additional Information Words are used, the first one
for each file entry is used to store the value of the System
Date Word at the time the file was created. This value is
set by executing a DATE conmiand (see Chapter 2 in the
8K Programming System User's Guide
)

NOTE
The value of the system DATE word is contained in
location 7666 in field 1; this word has the following format:
34

MONTH

DAY

YEAR- 19 70

(l-14g)

(l-37g)

(0-7)

A date word of
implies that no DATE command has been executed
since the system intialization.
The values of Additional Information Words beyond the first
are user-defined.
See Appendix D for further information on

Additional Information Words.
1.3

Core Control Block

Associated with each core image file (.SV file) is a block of
data called the Core Control Block.
The Core Control Block
is a table of information containing the program's starting
address, areas of core into which the program is loaded, and
the program's Job Status Word.
The Core Control Block is
created at the time the program is loaded by the ABSLDR or
LOADER program and is written onto the SV file by the SAVE
operation. More information on the Core Control Block can be
found in the description of core image files in section A. 2. 2.
.

'"^m^

1-5

NOTE

Specifying arguments to the SAVE command as described
in the 8K t>rogramming System User's Guide can alter
the contents of that program's Core Control Block.

When a program is loaded the starting address and Job Status
Word are loaded from the Core Control Block and saved in
The Core Control Block itself is saved in one of the
core.
system scratch blocks unless the program was loaded with the
R (rather than GET or RUN) command.
1.3.1

Program Starting Address

The current starting address (used by the START command) is
stored in two words at locations 7744 and 7745 in field 0.
The format of these words is:

1.3.2

NOTES

LOCATION

CONTENTS

7744

62N3

N is the field in which
to start

7745

addr

Starting address of the
program

Job Status Word

The Job Status Word contains certain flags that affect PS/S
operations, such as whether to save core when loading the
USR or Command Decoder. The Job Status Word for the program
and
currently in core is saved at location 7746 in field

contains the following information:

Bit Condition

Meaning

Bit

= 1

File does not load into locations
to 1777 in field 0.

Bit

1=1

File does not load into locations
to 1777 in field 1.

Bit

2=1

Program must be reloaded before it
can be restarted.

1-6

Bit Condition

Meaning

Bits 3-9

Reserved for future use.

Bit 1^ =

Locations
to 1777 in field
need not be saved when calling
the Command Decoder.

Bit 11 =

Locations
to 1777 in field 1
need not be saved when calling
the USR.

More information on the Core Control Block can be found in
the description of Core Image (.SV) files found in Appendix A.

NOTE

When bit 2 is 1, any attempt to perform a
START (without an explicit address) results
in a
NO!

error message being printed. As this bit is
always zero in the Core Control Block, the
user program is expected to internally set
this bit (in location 7746) if a program is
not restartable. This could be done as follows

CDF
TAD 7746
AND (6777
TAD (.1000
DCA 7746
1.4

/LOAD JOB STATUS WORD
/JOB IS NOT RESTARTABLE

Device Names and Device Numbers

The PS/8 system can accommodate up to 15 separate devices.
In the 8K Programming System User's Guide the reader is intro-

duced to the concept of device names. Briefly, each device on
the system is recognized by either a permanent device name
(such as PTR or DTAl) which is created when the system is

built, or a user-defined device name determined by an ASSIGN

The system insures that the user-defined device
name takes precedence. For example,
command.

.ASSIGN DSK DTA4
1-7

causes all future references to DTA4 to address the device DSK.
In calling the User Service Routine, a device can be alternatively recognized by a device number. Each device on the

system has a unique predefined number in the range
assigned at the time the system is generated.

1 to 15

(17 g)

Thus, user programs have the choice of referring to a device
Referencing a device by name is
by either name or number.
preferable as it maintains device independence for the program.
1.5

The DEVICE and FILENAME Pseudo-ops

Several of the User Service Routine functions take device
To simplify the task of
names or file names as arguments.
generating these arguments, the DEVICE and FILENAME pseudo-ops
have been added to the PALS Assembler.

A device name consists of a two word block, containing four
alphanumeric characters in six-bit ASCII format. A block in
this format can be created by the DEVICE pseudo-op as follows:
DEVICE DTAl
generates the following two words:
0424
J2fl61

Similarly, the FILENAME pseudo-op creates a four word block,
the first three words of which contain the file name and the
fourth word of which contains the file extension. For example:

FILENAME PIP.SV
generates the following four words

1-8

2^11

2000

0000
2326

Note that positions for characters
zeros

through

are filled with

The DEVICE and FILENAME pseudo-ops are used in examples in the
following chapters.

1-9

CHAPTER

User Service Routine

The User Service Routine, or USR, is a collection of subroutines which perform the operations of opening and closing
files, loading device handlers, chaining programs together,
and calling the Command Decoder.
It provides these functions

not only for the system itself, but for all programs running
under the PS/ 8 system.
2.1

Calling the USR

Performing any USR function is as simple as giving a JMS
followed by the proper arguments. Calls to the USR take a
standardized calling sequence. This standard call should be
studied before progressing to the operation of the various USR
functions
2.1.1

Standard USR Call

In the remainder of this chapter, the following calling
sequence is referenced:

TAD VAL
CDF N
CIF 10
JMS I (USR

FUNCTION
ARG(l)
'.

error return

The contents of the AC is applicable in
some cases only.
Where N is the value of the current program field multiplied by 10 octal.

Where USR is either 7700 or 0200, see
section 2.1.2)
This word contains an integer from 1 to
13 octal indicating which USR operation
is to be performed.
The number and meaning of these argument
words varies with the particular USR
function to be performed,
When applicable, this is the return
address for all errors,

normal return

2-1

function.
This calling sequence can change from function to
For example, some functions take no value in the AC and others
have fewer or greater numbers of arguments. Nonetheless, this

format is generally followed.

NOTE
The CDF and GIF instructions preceding the JMS
to the USR in the calling sequence are very imThe DATA FIELD must be set to the curportant.
rent field and the INSTRUCTION FIELD must be set
In the examples given
to 1 when calling the USR.
in this chapter, it is arbitrarily assumed that
On
the call to the USR is made from field 0.
return from any USR function the DATA FIELD remains set to the current field and the AC is zero.

There are three other restrictions which apply to all USR
calls, as follows:
a.

The USR can never be called from any address between
Attempting to do so results in
10000 and 11777*.
the
of
printing
the

MONITOR ERROR 4 AT xxxxx
message and termination of program execution. The
value of xxxxx is the address of the calling sequence (in all such MOIIITOR ERROR messages)
.

2.1.2

Several USR calls take address pointers as arguments.
These pointers always refer to data in the same field
as the call.

When calling the USR from field 1, these address
pointers must never refer to data that lies in the
area 10000 to 11777.
Direct and Indirect Calling Sequence

First, by perA user program can call the USR in two ways.
adforming a JMS to location 17700 (location 7700 in field 1)
In this case.
dresses in field 1 are written in this format).
,

*Where five digit addresses are given the leading digit refers
Thus, 11777 is location 1777 in field 1.

to the field.

2-2

locations 10000 to 11777 are saved on a special area on the
system device, and the USR is then loaded into 10000 to 11777.
When the USR operation is completed, locations 10000 to 11777
are restored to their previous values.

NOTE
By setting bit 11 of the Job Status Word to
a 1, the user can avoid this saving and restoring of core when preserving core is unnecessary.

Alternatively, a program can opt to keep the USR permanently
resident in core at locations 10000 to 11777 by using the USRIN
function (see section 2.2.8).
Once the USR has been brought into
core, a USR call can be made by performing a JMS to location 10200,
This is a more efficient way of calling the USR.
When USR operations have been completed, the program restores locations 10000
to 11777 to their initial state by executing the USROUT function
(see section 2.2.9).

Summary of USR Functions

2.2

Function
Code

Name

Operation

FETCH

Load a device handler into core.
entry address of the handler.

LOOKUP*

Searches the file directory on any device
to locate a specified permanent file.

ENTER*

Creates and opens for output a tentative
file on a specified device.

CLOSE*

The currently open tentative file on the
specified device is closed and becomes a
permanent file. Also, any previous permanent file with the same name is deleted.

Returns

*If the specified device is not file structured, the LOOKUP, ENTER,
and CLOSE functions verify only that the device is acceptable for
input in the case of LOOKUP, or output in the case of ENTER or CLOSE.
For example, ENTERing a file on the paper tape punch is a legal function.

2-3

Function
Code

Operation

Name
DECODE

The function
The Command Decoder is called.
in Chapdescribed
of the Command Decoder is
ter 3.

CHAIN

Loads a specified core image file from the
system device and starts it.

ERROR

Prints an error message of the form
USER ERROR n AT LOCATION xxxxx

USRIN

Subsequent
The USR is loaded into core.
to 10200.
JMS
a
are
by
USR
the
to
calls

US ROUT

Dismisses the USR from core and restores
the previous contents of locations 10000
to 11777.

INQUIRE

Ascertains whether a given device exists
and, if so, whether its handler is in core.

RESET

Resets system tables to their initial cleared
state.

Not currently used, these request numbers
are reserved for future use.

14-17

Function Code =

FETCH Device Handler

2.2.1

Device handlers must be loaded into core so as to be available to the USR and user program for I/O operations on that deBefore performing a LOOKUP, ENTER, or CLOSE function on
vice.
any device, the handler for that device must be loaded by FETCH,
The FETCH function takes two distinct foirms
a.

Load a device handler corresponding to a given
device name and
,

Load a device handler corresponding to a given
device number.

2-4

First, the following is an example of loading a handler

by name:

CLA
CDF
GIF 10
JMS I (USR

/AC MUST BE CLEAR

/FUNCTION CODE = 1
/GENERATES TWO WORDS: ARG(l)
/AND ARG(2)
/ARG 3
/ERROR RETURN
/NORMAL RETURN

DEVICE DTA3
6i2f|2(l

(

JMP ERR

contain the device name in standard format.
If the normal return is taken, ARG (2) is changed to the device
number corresponding to the device loaded. ARG(3) contains the
ARG(l)

and ARG (2)

following information:
Bits
to 4 contain the page number into which the
handler is loaded.

Bit 11 is
if the user program can only accept a
one page handler.

Bit 11 is

if there is room for a two page handler.

Notice that in the example above, the handler for DTA3 is to be
loaded into locations 60 00 to 6177.
If necessary, a two page
handler could be loaded; the second page would be placed in
locations 62 00 to 6377. After a normal return, ARG (3) is changed
to contain the entry point of the handler.

A different set of arguments is used to fetch a device
handler by number
The following is an example of this form:
.

TAD VAL
CDF
CIF 10
JMS I (USR

/AC IS NOT ZERO

1
60)31

/FUNCTION CODE =

JMP ERR

/ERROR RETURN
/NORMAL RETURN

/ARG(l)

2-5

On entry to the USR the AC contains the device number in bits
to 7 are ignored)
8 to 11 (bits
The format for ARG(l)

is the same as that for ARG(3)

in the

previous example. Following a normal return ARG(l) is replaced
with the entry point of the handler.
The conditions that can cause an error
both cases are as follows

return to occur in

There is no device corresponding to the given
device name or device number, or

An attempt was made to load a two page handler
If this is an attempt to load
into one page.
the handler by name, the contents of ARG(2)
have been changed already to the internal device number.

In addition, one of the following Monitor errors can be
printed, followed by a return to the Keyboard Monitor:

Meaning

Error Message

Results if bits 8 to 11 of the
to 7 are
AC are zero (and bits
non-zero)

MONITOR ERROR 4 AT xxxxx

Results if a read error occurs
while loading the device handler.

MONITOR ERROR 5 AT xxxxx

The FETCH function checks to see if the handler is in core,
and if it is not, then the handler and all co-resident* handlers
are loaded. While the FETCH operation is essentially a simple
one, the user should be aware of the following points:

Device handlers are always loaded into field

*Two or more device handlers are "co-resident" when they are both
included in the same one or two core pages. For example, the
paper tape reader and punch routines are co-resident, as are the
eight DECtape handler routines.

2-6

The entry point that is returned may not be on
the page desired.
This would happen if the handler
were already resident.

Never attempt to load a handler into 7600 or into
page 0.
Never load a two page handler into 7400.

For more information on using device handlers, see Chapter

LOOKUP Permanent File

2.2.2

Function Code =

This request locates a permanent file entry on a given

device, if one exists.

An example of a typical LOOKUP would be:

TAD VAL
CDF
CIF 10
JMS I (USR

/LOAD DEVICE NUMBER

/FUNCTION CODE = 2
/ARG(l)
POINTS TO FILE NAME

NAME

/ARG(2)

JMP ERR

/ERROR RETURN
/NORMAL RETURN

NAME, FILENAME PROG. PA
This request looks up a permanent file entry with the name PROG. PA.

The device number on which the lookup is to be performed is in AC
bits 8 to 11. ARG(l) contains a pointer to the file name; note

that the file name block must be in the same field as the call,
and that it cannot be in locations 10000 to 11777.
The device
handler must have been previously loaded into core.
If the normal return is taken, ARG(l) is changed to the starting block of
the file and ARG(2)

tive number.

contains the file length in blocks as a nega-

If the device specified is a readable, non-file

structured device (for example, the paper tape reader), then ARG(l)
and ARG(2) are both set to zero.
and ARG(2) are unchanged.
The following conditions cause an error return:

If the error return is taken, ARG(l)

2-7

The device specified is a write-only device.

The file specified was not found.

In addition, specifying illegal arguments can cause one of the

following monitor errors, followed by a return to the Keyboard
Monitor:

Meaning

Error Message

MONITOR ERROR 2 AT XXXXX

MONITOR ERROR 3 AT xxxxx

MONITOR ERROR 4 AT xxxxx

Results if an I/O error
occurred while reading the
device directory.
Results if the device handler
for the specified device is
not in core
Results if bits 8 to 11 of
the AC are zero.

The LOOKUP function is the standard method of opening a perma-

nent file for input.

ENTER Output (Tentative) File

2.2.3

Function Code =

The ENTER function is used to create a tentative file entry to
be used for output.
An example of a typical ENTER function is
as follows:

TAD VAL
CDF fi
GIF Ij?
JMS I (USR

/AC IS NOT ZERO

/FUNCTION CODE = 3
/ARG(l) POINTS TO FILE NAME

NAME

/ARG(2)

JMP ERROR

/ERROR RETURN
/NORMAL RETURN

NAME, FILENAME PROG.LS

Bits

to 11 of the AC contain the device number of the selected

device; the device handler for this device must be loaded into
If bits
to 7 of the
core before performing an ENTER function.

AC are non-zero, this value is considered to be a declaration of

2-8

the maximum length of the file.

The ENTER function searches

the file directory for the smallest empty file that contains at

least the declared number of blocks.

If bits

of the AC

are zero, the ENTER function locates the largest available empty
file.

On a normal return, the contents of ARG(l) are replaced with the
starting block of the file. The 2's complement of the actual

length of the created tentative file in blocks (which can be

equal to or greater than the requested length) replaces ARG{2)
If the file directory contains any Additional Information Words,
the system DATE (location 17666) is written as the first Additional

Information Word of the newly created tentative file at this time.

NOTE
If the selected device is not file structured
but permits output operations (e.g., the high
the ENTER operation always sucspeed punch)
ceeds.
In this case, ARG(l) and ARG(2) are
both zeroed on return.
,

If the error return is taken, ARG(l)

and ARG(2)

are unchanged.

The following conditions cause an error return:
a.

The device specified by bits
is a read only device.

No empty file exists which satisfies the requested
length requirement.

Another tentative file is already active on this
device (only one output file can be active at
any given time)

The first word of the file name was
file name)

to 11 of the AC

(an illegal

In addition, one of the following monitor errors can occur,

followed by a return to the Keyboard Monitor:

2-9

Meaning

Error Message

MONITOR ERROR 2 AT xxxxx

Results if an I/O error occurred
while reading or writing the device directory.

MONITOR ERROR 3 AT xxxxx

Results if the device handler for
the specified device is not in
core

MONITOR ERROR 4 AT xxxxx

Results if AC bits

to 11 are

zero.

MONITOR ERROR 5 AT xxxxx

Read error on the system device
while bringing in the overlay
code for the ENTER function.

MONITOR ERROR

Results if a directory overflow
occurred (no room for tentative
file entry in directory)

AT xxxxx

Function Code =

The CLOSE Function

2.2.4

first, it is used to
The CLOSE function has a dual purpose:
close the current active tentative file, making it a permanent

Second, when a tentative file becomes permanent it is
necessary to remove any permanent file having the same name;
file-

this operation is also performed by the CLOSE function.
example of CLOSE usage follows

TAD VAL
CDF
CIF 10
JMS I (USR

/GET DEVICE NU]

/FUNCTION CODE =

NAMI
15

/ARG(l)
/ARG(2)

JMP ERR

/ERROR RETURN
/NORMAL RETURN

•

NAME, FILENAME PROG.LS

The device number is contained in AC bits 8 to 11 when calling
ARG(l) is a pointer to the name of the file to be dethe USR.
leted and ARG(2) contains the number of blocks to be used for
the new permanent file.

2-10

The normal sequence of operations on an output file is:
a.

FETCH the device handler for the output device.

ENTER the tentative file on the output device,
getting the starting block and the maximum
number of blocks available for the file.

Perform the actual output, using the device
handler, keeping track of how many blocks are
written, and checking to insure that the file
does not exceed the available space.

CLOSE the tentative file, making it permanent.
The CLOSE operation would always use the same
file name as the ENTER performed in step b.
The closing file length would have been computed in step

After a normal return from CLOSE, the active tentative file is
permanent and any permanent file having the specified file name
already stored on the device is deleted
If the specified de.

vice is a non-file structured device that permits output (the
paper tape punch, for example)
the CLOSE function will always
,

succeed.

NOTE
The user must be careful to specify
the same file names to the ENTER and
the CLOSE functions.
Failure to do
so can cause several permanent files
with identical names to appear in the
directory.
If CLOSE is intended only
to be used to delete some existing
file, then the number of blocks, ARC (2)
should be zero.

The following conditions cause the error return to be taken:
a.

The device specified by bits
AC is a read only device.

There is neither an active tentative file to
be made into a permanent file, nor a permanent
file with the specified name to be deleted.

2-11

to 11 of the

In addition, one of the following Monitor errors can occur:

Meaning

Error Message

MONITOR ERROR 1 AT xxxxx

Results if the length specified
by ARG(2) exceeded the allotted
space.

MONITOR ERROR 2 AT xxxxx

Results if an I/O error occurred
while reading or writing the device directory.

MONITOR ERROR 3 AT xxxxx

Results if the device handler for
the specified device is not in core.

MONITOR ERROR 4 AT xxxxx

Results if AC bits

Call Command Decoder (DECODE)

2.2.5

to 11 are zero.

Function Code =

The DECODE function causes the USR to load and execute the Command Decoder. The Command Decoder accepts (from the Teletype)
a list of input and output devices and files, along with various
The Command Decoder performs a LOOKUP on all input
options.
files, sets up necessary tables in the top page of field 1, and
returns to the user program. These operations are described in
detail in Chapter 3, which should be read before attempting to

use the DECODE function.
A typical call to the Command Decoder looks as follows:
CDF
CIF 10
JMS I (USR
5

2001

ARG(l)

/FUNCTION CODE = 5
ASSUMED INPUT EXTENSION
/ARG(l)
/ARGC2), ZERO TO PRESERVE ALL
/TENTATIVE FILES
/NORMAL RETURN
,

is the assumed input extension, in the above example

on return from the Command Decoder, information
The
is stored in tables located in the top page of field 1.
it is ".PA".

2-12

DECODE function also resets all system tables as in the RESET
function (see RESET function, section 2.2.11) if ARG(2) is
all currently active tentative files remain open; if ARG(2)
is non-zero all tentative files are deleted and the normal

return is to ARG(2) instead of ARG(2)+1.
The DECODE function has no error return (Command Decoder error
messages are given in Chapter 3)
However, the following Monitor
.

error can occur:

Error Message

MONITOR ERROR 5 AT xxxxx

Meaning
I/O error occurred while reading
or writing on the system device.

CHAIN Function

2.2.6

Function Code =

The CHAIN function permits a program to load and start another
program with the restriction that the program chained to must
be a core image (.SV) file located on the system device.
A
typical implementation of the CHAIN function looks as follows:
CDF
CIF 10
JMS I (USR
6

BLOCK

/FUNCTION CODE = 6
/ARG(l), STARTING BLOCK NUMBER

There is no normal or error return from CHAIN.
following monitor error can occur:

Error Message

MONITOR ERROR 5 AT XXXXX

However, the

Meaning
I/O error occurred while reading
or writing on the system device.

The CHAIN function loads a core image file located on the system
device beginning at the block number specified as ARG(l)
(which

2-13

normally determined by performing a LOOKUP on the desired
Once loaded, the program is started at an address
file name)
one greater than the starting address specified by the program's
is

Core Control Block.
CHAIN automatically performs a USROUT function (see section
2.2.9) to dismiss the USR from core, and a RESET to clear all
system tables (see section 2.2.11), but CHAIN does not delete

tentative files.
The areas of core altered by the CHAIN function are determined
by the contents of the Core Control Block of the core image
The Core Control Block for the file is
file loaded by CHAIN.
It can be modified
set up by the ABSLDR or LOADER programs.

Every
by performing a SAVE command with specific arguments.
page of core in which at least one location was saved is loaded.
If the page is one of the "odd numbered" pages (pages 1, 3, etc.
locations 0200 to 0377, 0600 to 0777, etc.), the previous page
In addition, CHAIN always alters the contents
is always loaded.
of locations 07200 to 07577.

NOTE
CHAIN destroys a necessary part of the ODT resiThus an ODT breakpoint
dent breakpoint routine.
across a CHAIN.
maintained
should never be

With the above exceptions, programs can pass data back and forth
For example, FORTRAN programs normally
in core while chaining.
This COMMON area
leave the COMMON area in field 1 unchanged.
can then be accessed by the program activated by the CHAIN.
Function Code =

Signal User ERROR

2.2.7

The USR can be called to print a user error message for a proThe following is a possible ERROR call:
gram.

CDF
CIF
JMS
7

IjS

CUSR

/FUNCTION CODE = 7
/ARG(l)
ERROR NUMBER
,

2-14

The ERROR function causes a message of the form:

USER ERROR n AT xxxxx
to be printed.

Here n is the error number given as ARG(l)

and Up/ and xxxxx is the address of ARG(l).
in the sample call above was at location 500 in field 0,

n must be between
If ARG(l)

the message:

USER ERROR 2 AT 00500
would be printed. Following the message, the USR returns control to the Keyboard Monitor, preserving the user program intact.

The error number is arbitrary.

Two numbers have currently as-

signed meanings
Error Message

USER ERROR

Meaning

AT xxxxx

During a RUN, GET, or R command,
this error message indicates that
an error occurred while loading
the core image.

USER ERROR 1 AT xxxxx

While executing a FORTRAN or SABR
program, this error indicates that
a call was made to a subroutine
that was not loaded.

Lock USR in Core (USRIN)

2.2.8

Function Code = 10

When making a number of calls to the USR it is advantageous for
a program to avoid reloading the USR each time a USR call is
made.
The USR can be brought into core and kept there for subsequent use by the USRIN function.
The calling sequence for the
USRIN function looks as follows:
CDF
GIF 10
JMS I (77|2fj3
10
I

/FUNCTION CODE = 10
/NORMAL RETURN
2-15

The USRIN function saves the contents of locations 10000 to
11777 on the system scratch blocks, loads the USR into this

area in core, and returns control to the user program.

NOTE
If bit 11 of the current Job Status Word is a one,
the USRIN function will not save the contents of
locations 10000 to 11777.

Subsequent calls to the USR can be made directly by performing
a JMS to location 02 00 in field 1, saving the time necessary
to reload the USR each time it is called.
Function Code = 11

Dismiss USR from Core (USROUT)

2.2.9

When a program has loaded the USR into core with the USRIN
function and no longer wants or needs the USR in core, the
USROUT function is used to restore the original contents of
The calling sequence for the USROUT
locations 10000 to 11777.
function is as follows
CDF
GIF 10
JMS I {200
11
:

/DO NOT JMS TO 11100
/FUNCTION CODE = 11
/NORMAL RETURN

The USROUT function and the USRIN function are complementary
Subsequent calls to the USR must be made by peroperations.

forming a JMS to location 7700 in field

NOTE
If bit 11 of the current Job Status Word is a
1, the contents of core are not changed by the
In this case USROUT is a reUSROUT function.

dundant operation since core was not preserved
by the USRIN function.

2-16

2.2.10

Ascertain Device Information (INQUIRE) Function Code = 12

On some occasions a user may wish to determine what internal
device number corresponds to a given device name or whether the
device handler for a specified device is in core, without acINQUIRE performs these
tually performing a FETCH operation.

operations for the user. The function call for INQUIRE closely
resembles the FETCH handler call.
INQUIRE, like FETCH, has two distinct forms:
a.

Obtain the device number corresponding to a
given device name and determine if the handler
for that device is in core (example shown below)
and

Determine if the handler corresponding to a
given device number is in core.

An example of the INQUIRE call is shown below:

CLA
CDF
CIF 10
JMS I (USR

/AC MUST BE CLEAR

/FUNCTION CODE = 12
/GENERATES TWO WORDS
/ARG(l) AND ARG(2)

DEVICE DTA3

/ARG(3)

JMP ERR

/ERROR RETURN
/NORMAL RETURN

and ARG(2) contain the device name in standard format.
When the normal return is taken ARG(2) is changed to the device
number corresponding to the given name, and ARG(3) contains
ARG(l)

either the entry point of the device handler if it is already
in core, or zero if the corresponding device handler has not yet
been loaded.

2-17

A slightly different set of arguments is used to inquire
about a device by its device number:
TAD VAL
CDF
CIF lj2f
JMS I (USR

/AC IS NON-ZERO

/FUNCTION CODE

=12

/ARG(l)

/ERROR RETURN
/NORMAL RETURN

JMP ERR
:

On entry to INQUIRE, AC bits

number (bits

to 11 contain the device

are ignored)

NOTE
to 7 are non-zero, and bits 8
If AC bits
to 11 are zero (an illegal device number) a:

MONITOR ERROR 4 AT xxxxx
message is printed and program execution is
terminated.
On normal return ARG(l) is set to the entry point of the device
handler if it is already in core, or zero if the corresponding

device handler has not yet been loaded.
The error return in both cases is taken only if there is no
device corresponding to the device name or number specified.

2.2.11

RESET System Tables

Function Code = 13

There are certain occasions when it is desired to reset the
system tables, effectively removing from core all device
An example of the RESET
handlers except the system handler.
function is shown below:

2-18

CDF
CIF 10
JMS I (USR

/FUNCTION CODE = 13
/0 PRESERVES TENTATIVE FILES
/NORMAL RETURN

13
:

RESET zeros all entries except the one for the system device in
the Device Handler Residency Table (see section B.3.3), removing
all device handlers, other than that for the system device, from

This should be done anytime a user program modifies any

core.

page in which a device handler was loaded.

RESET has the additional function of deleting all currently active tentative files (files that have been entered but not closed)

through 11 of every entry
in the Device Control Word Table (see section B.3.5).

This is accomplished by zeroing bits

If RESET is to be used in this last fashion, to delete all active

tentative files, then ARG(l) must be non-zero and the normal return is to ARG(l) rather than to ARG(1)+1.
For example, the following call would serve this purpose:
CDF
CIF 10
JMS I (USR
13

CLA CMA

/FUNCTION CODE
/NON-ZERO!

=13

The normal return would execute the CLA CMA and all active
tentative files on all devices would be deleted.

2-19

CHAPTER 3
THE COMMAND DECODER

PS/8 provides a powerful subroutine called the Comniand Decoder
for use by all system programs.
The Command Decoder is normally called when a program starts running.

Command Decoder prints a

When called, the

and then accepts a command line from

the console Teletype that includes a list of I/O devices, file

names, and various option specifications.

The Command Decoder

validates the command line for accuracy, performs a LOOKUP on
all input files, and sets up various tables for the calling
program.

The operations performed by the Command Decoder greatly simplify
the initialization routines of all PS/8 programs.
Also, since

command lines all have a standard basic structure, the Command
Decoder makes learning to use PS/8 much simpler.
3 . 1

Command Decoder Conventions

Chapter

in the 8K Programming System User's Guide describes

the syntax for the command line in detail.

A brief synopsis
is given here only to clarify the later discussion in this
chapter.
The command line has the following general form:
*

output files

There can be

input files (options)

output files and

input files speci-

fied.

Output File Format

EXPLE.EX

Meaning

Output to a file named EXPLE.EX on
device DSK (the default file storage
device)
3-1

Meaning

Output File Forma t
LPT:

Output to the LPT. This format generally
specifies a non-file structured device.

DTA2:EXPLE.EX

Output to a file named EXPLE.EX on device
DTA2.

DTA2:EXPLE.EX[99]

Output to a file named EXPLE.EX on device
DTA2.
A maximum output file size of 99
blocks is specified.

null

No output specified.

An input file specification has one of the following forms

Meaning

Input File Format
DTA2 INPUT

Input from a file named INPUT. df on de"df" is the assumed input
vice DTA2.
file extension specified in the Command
Decoder.

DTA2: INPUT. EX

Input from a file named INPUT. EX on device
In this case .EX overrides the asDTA2.
sumed input file extension.

INPUT. EX

If
Input from a file named INPUT. EX.
there is no previously specified input
device, input is from device DSK, the
default file storage device; otherwise,
the input device is the same as the last
specified input device.

PTR:

Input from device PTR; no file name is
needed for non-file structured devices.

DTA2

Input from device DTA2 treated as a
non-file structured device, as, for
example, in the PIP command line:

*TTY /L < DTA2
:

*Whe never a file extension is left off an input file specification, the Command Decoder first performs a LOOKUP for the given
If that LOOKUP
name appending a specified assumed extension.
fails, a second LOOKUP is made for the file appending a null
(zero) extension.

3-2

Input File Format

Meaning
In both of the last two formats, no
LOOKUP operation is performed since the
device is assumed to be non-file structured.

Repeats input from the previous device
specified (must not be first in input
list, and must refer to a non-file
structured device).
For example:

null

< PTR: ,

(two null files) indicates that three
paper tapes are to be loaded.

The Command Decoder verifies that the specified device names,
file names, and extensions consist only of the characters A

through

and

If not, a syntax error is generated
through 9.
and the command line is considered to be invalid.
Z

There are two kinds of options that can be specified:
first,
alphanumeric option switches are denoted by a single alphanumeric
character preceded by a slash (/) or a string of characters enclosed in parentheses; secondly,
fied as an octal number from 1 to

numeric option can be speci-

preceded by an equal
sign (=)
These options are passed to the user program and
are interpreted differently by each program.
3 77 77 77 7

Finally, the Command Decoder permits the command line to be

terminated by either the RETURN or ALT MODE key.
tion is also passed to the user program.
3.2

This informa-

Command Decoder Error Messages

If an error in the command line is detected by the Command De-

coder, one of the following error messages is printed.

After

the error message, the Command Decoder starts a new line,

prints a

and waits for another command line.

command is ignored.

3-3

The erroneous

Meaning

E rror Message

ILLEGAL SYNTAX

The coirmand line is formatted incorrectly.

TOO MANY FILES

More than three output files or nine
input files were specified.

device DOES NOT EXIST

The specified device name does not
correspond to any permanent device
name or any user assigned device name.

name NOT FOUND

The specified input file name was not
found on the selected device.

3.3

Calling the Command Decoder

The Command Decoder is initiated by the DECODE function of the
to 1777 of
DECODE causes the contents of locations
USR.
to be saved on the system scratch blocks, and the Comfield

mand Decoder to be brought into that area of core and started.
When the command line has been entered and properly interpreted,
the Command Decoder exits to the USR, which restores the original
to 1777 and returns to the calling program.
contents of
NOTE
By setting bit 10 of the Job Status Word to a 1
the user can avoid this saving and restoring of
core for programs that do not occupy locations
to 1777.

and 1777 in
The DECODE call can reside in the area between
A typical call would
and still function correctly.
field

appear as follows
CDF
CIF
JMS
5
2j2fj2fl

lj3

(USR

/SET DATA FIELD TO CURRENT FIELD
/INSTRUCTION FIELD MUST BE 1
/\5SR=n00 IF USR IS NOT IN CORE
/OR USR=J2f2j2(0 IF USRIN WAS PERFORMED
/DECODE FUNCTION = 5
ASSUMED INPUT EXTENSION
/ARG(l)
/ARG(2), ZERO TO PRESERVE
/ALL TENTATIVE FILES
/NORMAL RETURN
,

3-4

ARG(l)

If an input file name

is the assumed input extension.

with no specified extension, the Command Decoder
first performs a LOOKUP for a file having the given name with
If the LOOKUP fails, the Command Dethe assumed extension.
coder performs a second LOOKUP for a file having the given name
In this example, the assumed input
and a null (zero) extension.
is given

extension is ".PA".
DECODE performs an automatic RESET operation (see section 2.2.11)
to remove from core all device handlers except those equivalent
to the system device.

As in the RESET function, if ARC (2)

zero all currently active tentative files are preserved.

ARC (2) is non-zero, all tentative files are deleted and DECODE
returns to ARC (2) instead of ARG(2)+1.
As the Command Decoder normally handles all of its own errors,

there is no error return from the DECODE operation.
3.4

Command Decoder Tables

The Command decoder sets up various tables in the top page of
field 1 that describe the command line typed to the user program.
3.4.1

Output Files

There is room for three entries in the output file table that
Each entry is five words long and
begins at location 1760i2(.
has the following format:

WORD

WORD 2

23456789

FILE

NAME

CHARACTER
FILE

FILE

CHARACTER 2
FILE

NAME

WORD 3

CHARACTER

CHARACTER 4

WORD 4

CHARACTER 5

CHARACTER 6

WORD 5

FILE EXTENSION

CHARACTER 1

CHARACTER 2

FILE

NAME

NUMBER
NAME

NAME

4-BIT DEVICE

USER SPECIFIED
FILE LENGTH

OUTPUT FILE NAME
6 CHARACTERS

FILE NAME

3-5

FILE EXTENSION
2 CHARACTERS

Bits

of word 1 in each entry contain the file length,

if the file length was specified with the square bracket con-

Otherwise, those bits are zero.

struction in the command line.

The entry for the first output file is in locations 17600 to
17604, the second is in locations 17605 to 17611, and the
If word 1 of any entry
third is in locations 17612 to 17616.
A
is zero, the corresponding output file was not specified.
zero in word 2 means that no file name was specified.

Also, if word

of any entry is zero no file extension was

It is left to the user
specified for the corresponding file.
program to take the proper action in these cases.

These entries are in a format that is acceptable to the ENTER
function.
3.4.2

Input Files

There is room for nine entries in the input file table that
begins at location 17 617. Each entry is two words long and
has the following format:

12
WORD

MINUS FILE
i

NUMBER

LENGTH

WORD 2

4-BIT DEVICE

STARTING BLOCK OF FILE

contain the file length as a negative
number.
Thus, 377p. in these bits is a length of one block, 376
is a legnth of two blocks, etc.
If bits
to 7 are zero, the
specified file has a length greater than or equal to 256 blocks
or a non-^file structured device was specified.

Bits

of word

3-6

NOTE
This restri ction to 255 blocks of actual specified size c an cause some problems if the program has no way of detecting end-of-file conditions.
For example, PIP cannot copy in image
mode any fi le on a file structured device that
is greater than 255 blocks long, although it
can handle in /A or /B modes (ASCII or Binary)
files of un limited size.
In /A or /B modes PIP
will detect the CTRL/Z marking the end-of-file.
If this is liable to be a problem, it is suggested that the user program employ the special
mode of the Command Decoder described in section
3.5 and perform its own LOOKUP on the input files
to obtain the exact file length.

The two word input tables begin in locations 17617, 17621, 17623,
17625, 17627, 17631, 17633, 17635, and 17637.
is

If location 17617

zero no input files were indicated in the command line.

less than nine input files were specified, the unused entries
in the input file list are zeroed (location 17641 is always set
to provide a zero terminator even when nine files are specified)

Command Decoder Option Table

3.4.3

Five words are reserved beginning at location 17642 to store
the various options specified in the command line.
The format
of these five words is as follows:

3 4 5 6 7 e 9 10
HIGH ORDER 11 BITS OF
= N OPTIONS

17644

17645

17646

LOW ORDER 12 BITS OF-N OPTIONS

17642

17643

*Bit

of location 17642 is

if the command line was
terminated by a carriage return, 1 if it was terminated
by an ALT MODE.
3-7

Each of these bits corresponds to one of the possible alphanumeric option
switches.
The corresponding bit is 1 if the switch
was specified,
otherwise.

NOTE
If no =n option is specified, the Command Decoder zeroes 17646 and bits 1 to 11 of 17642.
Thus, typing =0 is meaningless since the user
program cannot tell that any option was specified.

Example

3.4.4

To clarify some of the preceding, consider the interpretation
of the following command line:
*BIN[lj3] ,<PTR: , ,DTA2 : PARA, MAIN /h=lA200$

If this command line is typed to PALS, it would cause assembly

of a program consisting of four separate parts

two paper

and one file named
MAIN. PA also on DTA2.
The binary output is placed on a file
named BIN.BN on device DSK, for which only 10 blocks need be
In addition, automatic
allocated. No listing is generated.
tapes, one file named PARA. PA on DTA2

loading of the binary output is specified by the /L option,
Finally,
with the starting address given as 4 200 in field 1.
the line is terminated by the ALT MODE key (which echoes as $)
causing a return to the Keyboard Monitor after the program is
loaded.
In the case of this example, the Command Decoder returns to

PALS with the following values in the system tables:

NOTE
The entries for PTR (where no input file name is
specified) have a starting block number and file
size of zero.
This is always true of the input
table for a non-file structured device, or a file
structured device on which no file name is given.

3-8

17600

DSKI IS DEVICE NUMBER 2

0242
0211

1600

) FILE

NAME

BIN

000(2

17604

0000

-NULL EXTENSION

17605

REMAINING ENTRIES

OUTPUT TABLES
ARE ZERO
IN

17616
17617

0016
FIRST ptr; input

17620
17621

0000
0016

SECOND ptr; input
17622
17623

17624
17625

0000
0127

DTA2: PARA. F% IS 5 BLOCKS LONG,
BEGINNING AT 1008

0100
0007

DTA2:MAIN.PA is 256(0 or MORE BLOCKS
LONG, BEGINNING AT BLOCK 1058-

17626
17627

0105

n REMAINING ENTRIES
t

IN INPUT TABLES
ARE ZERO.

17641

3.5

17642

4001

17643

0001

17644

0000

17645

0000

17646

4200

LINE WAS TERMINATED BY ALT

MODE

/L WAS ONLY OPTION SWITCH SPECIFIED

14200 WAS SPECIFIED

Special Mode of the Command Decoder

Occasionally the user program does not want the Command Decoder
to perform the LOOKUP on input files, leaving this option to
For example CONVRT, which translates
the user program itself.
Disk Monitor format DECtapes to PS/8 format DECtapes, cannot
permit an erroneous LOOKUP to occur on DECtapes that are not
The capability to handle this case is provided
in PS/8 format.
in the PS/ 8 Command Decoder.

This capability is generally re-

ferred to as the "special mode" of the Command Decoder.

3-9

3.5.1

Calling the Command Decoder Special Mode

The special mode call to the Command Decoder is identical to
the standard DECODE call except that the assumed input file

extension, specified by ARG(l)

is equal to 5200.

The value

5200 corresponds to an assumed extension of ".*", which is
illegal.
Therefore, the special mode of the Command Decoder
in no way conflicts with the normal mode.

3.5.2

Operation of the Command Decoder in Special Mode

In special mode the Command Decoder is loaded and inputs a

command line as usual. The appearance of the command line is
altered by the special mode in these respects:
a.

Only one output file can be specified.

No more than five input files can be specified, rather than the nine acceptable in
normal mode.

The character asterisk (*) is legal in file
names and extensions, both in input files
and on output files.
It is strongly suggested
that this character be tested by the user program and treated either as a special option
or as an illegal file name. The user program
must be careful not to ENTER an output file
with an asterisk in its name as such a file
cannot be manipulated or deleted by the standard
system programs.

The output and option table set up by the Command Decoder is
not altered in special mode.
Entries in the input table are
changed to the following format:

WORD

2345678910

BITS 0-7 ARE
ALWAYS

4 -BIT DEVICE
1

WORD 2

FILE

NAME

CHARACTER
FILE NAME
CHARACTER 3
1

WORD 3

WORD 4
WORD 5

FILE

NAME

CHARACTER 5
FILE EXTENSION
CHARACTER 1

NUMBER
FILE NAME
CHARACTER 2
FILE NAME
CHARACTER 4
FILE

INPUT FILE NAME

6 CHARACTER

NAME

CHARACTER 6
FILE EXTENSION

CHARACTER

3-10

FILE EXTENSION
2 CHARACTERS

The table entry for the first input file is in locations 17605
to 17611; the second in locations 17612 to 17616; the third
in locations 17617 to 17623; the fourth in locations 17624
A zero
to 17630; and the fifth in locations 17631 to 17635.
If word
in word 1 terminates the list of input files.
an entry is zero, no input file name was specified.

3-11

CHAPTER 4
USING DEVICE HANDLERS

A device handler is a system subroutine that is used by all
parts of the PS/8 system and by all standard system programs
to perform I/O transfers.
All device handlers are called in
the same way and they all perform the same basic operation:
reading or writing a specified number of 128 word records*
beginning at a selected core address.
These subroutines effectively mask the unique characteristics
of different I/O devices from the calling program; thus, pro-

grams that use device handlers properly are effective "device
Changing devices involves merely changing the
independent"
device handlers used for I/O.
.

PS/8 device handlers have another important feature.

They are

able to transfer a number of records as a single operation.
On a device like DECtape this permits many blocks of data to
be transferred without stopping the tape motion.

On a disk,

a single operation could transfer an entire track or more.

This capability significantly increases the speed of operation
of PS/8 programs, such as PIP, that have large buffer areas.
4.1

Calling Device Handlers

Device handlers are loaded into a user selected area in field
FETCH returns in ARG(l) the entry
by the FETCH function.

point of the handler loaded.

The handler is called by perform-

*The word "record" is defined to mean 128 words of data; thus,
a PS/8 block consists of two 128 word records.

4-1

ing a JMS to the specified entry point address.

It has the

following format:
CDF N
CIF
JMS I ENTRY
ARG(l)

ARC (2)
ARC (3)
JMP ERR

/WHERE N IS THE VALUE OF THE CURRENT
/PROGRAM INSTRUCTION FIELD TIMES 10 (OCTAL)
/DEVICE HANDLER ALWAYS IN FIELD

/FUNCTION CONTROL WORD
/BUFFER ADDRESS
/STARTING BLOCK NUMBER
/ERROR RETURN
/NORMAL RETURN (I/O TRANSFER COMPLETE)
/ENTRY CONTAINS THE ENTRY POINT OF THE
/HANDLER, DETERMINED WHEN LOADED BY FETCH

ENTRY,

As with calls to the USR, it is important that the Data Field is

set to the current program field before the device handler is
On exit from the device handler, the Data Field will

called.

remain set to the c\xrrent program field.
ARG(l) is the function control word, and contains the following

information:
Bit (s)

Contents

Bit
1

for an input operation^
for an output operation.

Bits

The number of 12 8 word records to be
transferred must not be 0.

Bits

The memory field in which the transfer
is to be performed.

Bits

to 11

Device dependent bits, can be left zero.
Currently only bit 11 is used; on DECtape bit 11 determines the direction in
which the tape is started.
If bit 11 is
the tape starts in reverse.
If bit 11
is 1 the tape starts forward.*
All
other handlers ignore these bits at
present.

*Starting forward saves time as long as the block number, ARG(3)
is seven or more blocks greater than the number of the block at

which the tape is currently positioned.

4-2

ARG(2) is the starting location of the transfer buffer.
ARG(3)

is the number of the block on which the transfer is to

begin.

The user program initially determines this value by

performing a LOOKUP or ENTER operation. After each transfer
the user program should itself add to the current block
number the actual number of blocks transferred, equal to onehalf the number of 128 word records specified, rounded up if
the number of records was odd.
fatal and non-fatal.
There are two kinds of error returns:
When the error return occurs and the contents of the AC are

negative the error is fatal. A fatal error can be caused by
a parity error on input, a write lock error on output, or an
The
attempt to write on a read-only device (or vice versa)
.

meaning can vary from device to device, but in all cases it is
serious enough to indicate that the data transferred, if any,
is invalid.

When the error return occurs and the contents of the AC are
greater than or equal to zero, a non-fatal error has occurred.
This error always indicates detection of the logical end-of-file.
For example, when the paper tape reader handler detects the end
of a paper tape it inserts a CTRL/Z code in the buffer and takes

While all non-file
structured input devices can detect the end-of-file condition,
no file structured device can; and no device handler takes the
the error exit with the AC equal to zero.

non-fatal error return when doing output.
The following restrictions apply to the use of device handlers:
a.

Bits 1 to 5 of the function control word, ARG{1)
must not be zero as this value is currently undefined.

The user program must never specify an input into
locations 7600 to 7777 or 17600 to 17777 or the
page(s) in which the device handler itself resides.

4-3

4.2

Note that the amount of data transferred is given
as a number of 128 word records, exactly one half
of a PS/ 8 block.
Attempting to output an odd number of records can change the contents of the last
128 words of the last block written.

The specified buffer address does not have to begin
at the start of a page.
The specified buffer cannot
overlap fields, rather the address will "wrap around"
in a single field.
For example, writing two records
from location 07600 would output 07600 to 07777 and
page
of field 0, not field 1.

Device Dependent Operations

This section describes briefly the operation of each of the stan-

dard PS/8 device handlers, including normal operation, any special

initialization operations for block 0, terminating conditions,
Further
and response to control characters typed at the keyboard.
information on device handlers can be found in Chapter 5.
Teletype (TTY)

4.2.1

Normal Operation

This handler inputs characters from the Teletype keyboard and packs them into the buffer or unpacks characters from the buffer and outputs them to the teleprintejr
It functions properly only on ASCII data.

FolOn input, characters are echoed as they are typed.
lowing a carriage return, a line feed character is inserted into the input buffer and printed on the Teletype.
b.

Initialization for Block

None.
c.

Terminating Conditions

On input, detection of a CTRL/Z causes a CTRL/Z to be
placed in the input buffer, the remaining words of the
buffer filled with zeros, and a non-fatal error to be
returned.
On output, detection of a CTRL/Z character
in the output buffer causes output to be terminated and
the normal return to be taken.
There are no fatal errors
associated with the Teletype handler.

4-4

Teletype Interaction

CTRL/C forces a return to the Keyboard Monitor. CTRL/Z
CTRL/0 termiforces an end-of-file on input (see c)
nates printing of the contents of the current buffer on
output.
.

High-Speed Paper Tape Reader (PTR)

4.2.2
a.

Normal Operation

This handler inputs characters from the high-speed paper
tape reader and packs them into the buffer.
b

Initialization for Block

The handler prints an up-arrow (t)* on the teleprinter
and waits for the user to load the paper tape reader.
By typing any single character (except CTRL/C) the user
initiates reading of the paper tape.
c.

Terminating Conditions

Detection of an end-of-tape condition, indicated by the
failure to get a character in a specified period of time,
causes a CTRL/Z to be entered in the buffer, the remaining words of the buffer to be filled with zeros, and a
non-fatal error to be returned. Attempting to output to
the paper tape reader causes a fatal error to be returned.
d.

Teletype Interaction

Typing CTRL/C forces a return to the Keyboard Monitor.

High-Speed Paper Tape Punch (PTP)

4.2.3
a.

Normal Operation

This handler unpacks characters from the output buffer
and punches them on the paper tape punch.
b.

Initialization for Block

None.
*0n some Teletypes
character.

up-arrow is replaced by the circumflex
4-5

(

Terminating Conditions

Attempting to input from the paper tape punch causes a
fatal error to be returned. There are no non-fatal
errors associated with this handler.
d-

Teletype Interaction

Typing CTRL/C forces a return to the Keyboard Monitor.
Line Printer (LPT)

4.2.4

Normal Operation

This handler unpacks characters from the buffer and
The characters horiprints them on the line printer.
zontal tab (ASCII 211) causes sufficient spaces to be
inserted to position the next character at a "tab stop"
The character
(every eighth column, by definition)
vertical tab (ASCII 213) causes nine line feeds to be
output.
The character Form Feed (ASCII 214) causes
Finally, the
a skip to the top of the next page.
handler maintains a record of the current print column
and starts a new line after 80 columns have been printed.
This handler functions properly only on ASCII data.
.

Initialization for Block

Before printing, the line printer handler issues a
form feed to space to the top of the next page.
c.

Terminating Conditions

On detection of a CTRL/Z character in the buffer, the
line printer handler issues a form feed and immediately
takes the normal return. Attempting to input from the;
Also
line printer forces a fatal error to be returned.
is
error
fatal
printer
error
flag
is
set
a
if the line
with
errors
associated
no
non-fatal
There
are
returned.
the line printer handler.
d.

Teletype Interaction

Typing CTRL/C forces a return to the Keyboard Monitor.

4-6

Card Reader (CDR)

4.2.5
a.

Normal Operation

This handler reads characters from the card reader and
packs them into the input buffer. Trailing spaces (blank
The handler
columns) on a card are deleted from input.
can accept only alphanumeric format data on cards (the
DEC029 standard card codes are used)
b.

Initialization for Block

None.

Terminating Conditions

A card which contains an underline character in column 1
(an 0-8-5 punch) with the remaining columns blank is an
end-of-file card. In addition, after reading each card
the handler checks to see if a CTRL/Z was typed at the
After either an end-of-file card or a CTRL/Z
keyboard.
being typed, a CTRL/Z is inserted in the buffer, the
remaining words of the input buffer are filled with zeros,
Attempting to output
and a non- fatal error is returned.
causes
a
fatal
error
to be returned.
card
reader
to the
d.

Teletype Interaction

Typing CTRL/C forces a return to the Keyboard Monitor.
Typing CTRL/Z forces an end-of-file to occur (see c)
File Structured Devices

4.2.6
a.

Normal Operation (DECtape, LINCtape, DF32,

RFJ3f8,

and

RK8)

These handlers transfer data directly between the device
and the buffer.
b.

Initialization for Block

None.

4-7

Terminating Conditions

A fatal error is returned whenever the transfer caused
one of the error flags in the device status register to
be set.
For example, a fatal error would result if a
parity error occurred on input, or a write lock error
occurred on output. The device handlers generally try
three times to perform the operation before giving up
and returning a fatal error.
There are no non-fatal
errors associated with file structured devices.
d.

Teletype Interaction

Typing CTRL/C forces a return to the Keyboard Monitor,
NOTE
The system device handler does NOT respond to a typed CTRL/C.

4-8

CHAPTER 5
RECONFIGURING THE PS/8 SYSTEM

In the instructions on building PS/8 in the 8K Programming
*
mention is made of the several paper
System User's Guide
,

Each PS/8
tapes marked CONFIG distributed with each system.
system contains the source file CONFIG. PA, either on DECtape,

CONFIG contains all
or LINCtape.
paper tape (in two parts)
configuration dependent parts of the PS/8 system, including
all device handlers, device dependent system tables, bootstrap
,

routines, and system device handlers.
The problem of changing the system configuration is reduced
to editing the CONFIG file and assembling the result to proThis new binary tape is then used in
duce a new binary tape.

building a modified system. The following chapter describes
in detail the ways in which CONFIG can be modified.
5.1

Conditional Assembly of CONFIG

The source file CONFIG. PA contains a number of conditional
These are symbols that, in conjunction with some
symbols.
IFDEF, IFNDEF, IFZERO, or IFNZRO pseudo-ops, cause various sec-

Creating
tions of the program to be assembled with PALS.
standard system variations requires the proper definition of
one or more of these parameters.

Although it is not explicitly stated, the instructions given
could also be used to create a PS/8 System DECtape. Mount the
tape to be built on Unit j3 WRITE ENABLEd, and follow the instructions given. The binary tape marked "DECtape CONFIG"
would be used in place of one of the disk CONFIG' s.
,

5-1

System Device Selection

5.1.1

One and only one of the system device parameters can be

defined and assigned a non-zero value.
a.

RF08 Disk System

Defining RFj38 = n, where n is 1,2,3, or 4
causes an n disk RFj38 to be the system device.
For example:
RFjef8=2

would generate a 512K RF/RS08 system.
b.

DF32 Disk System

Defining DF3 2 = n, where n is 1,2,3, or 4
causes an n disk DF3 2 to be the system device.
For example
DF3 2=2

would generate

a 64K

DF/DS32 system.

NOTE

Because PS/8 alone takes 14K of the
system device, it is felt that a
single disk DF32 has insufficient
storage for PS/8.
The system is
not supported by DEC on a 32K disk.
c.

RK8 Disk System

Defining RK8=1 causes an RK8 disk to be the
system device, generating an RK8 system.
d.

PDP-12 LINCtape System

Defining LINCSyS=n, where n is 1 or 2 causes
to be the system device.
If
LINCtape unit
LINCSYS=1, the default file storage device
If
(device DSK) is also LINCtape unit 0.
LINCSYS=2, the default file storage device
is LINCtape unit 1, which is to be preferred
as it minimizes tape motion.

5-2

NOTE

When LINCSYS is the specified system parameter,
the user must be certain to explicitly specify
LINCTAPE=1 (see section 5.1.2), otherwise DECtape rather than LINCtape handlers would be included in the system.
e.

DECtape System
If no other system device parameters are speciis the default system defied, DECtape unit
One can also define DECTAPE=n, where n
vice.
to be the
is 1 or 2 to cause DECtape unit
system device. If DECTAPE=1 , the default file
storage device (device DSK) is DECtape unit 0.
If DECTAPE=2, the default file storage device
is DECtape unit 1, which is to be preferred as
it minimizes tape motion.

5.1.2

Optional Device Parameters

The standard system, generated by defining one of the system
device parameters, contains the following device handlers:

Meaning

Device Code
SYS

Selected system device

TTY

Teletype

PTR

High-speed paper tape reader

PTP

High-speed paper tape punch

CDR

Card reader (CR8 or CMS)

LPT

LPjelS

DTAj2(-DTA7

Handlers for eight DECtape drives

DSK

Default file storage device, always the same
as the system device unless LINCSYS=2 or
DECTAPE=2 are used.

Line printer

These device handlers can be replaced by others by defining one
of the following parameters:

5^3

LINCtape handlers
If the computer is a PDP-12, it is necessary
to replace the standard DECtape handlers with
LINCtape handlers. This must be done explicitly

by defining LINCTAPE=1.

LP12 Line Printer, Type 645

A small number of systems have the old style
line printer rather than the new LPj2f8.
Defining LP08=0 causes a device handler for the LP12
(Type 645) line printer to replace the standard
LP08 handler.
NOTE
The FORTRAN run time I/O routines, with
the exception of the device-independent
I/O routines, do not use PS/8 handlers.
Therefore, in FORTAN use the statement
WRITE (3,n) only works on the LPj2i8 line
printer.
To use a different printer the
FORTRAN subroutine UTILTY.SB (available
on source DECtape #3) must be modified.

Low-Speed Paper Tape
The standard Teletype handler (TTY) checks for
-tC and +Z control characters
(CTRL/C and CTRL/Z) .
To enable the handler to work on terminals that
utilize parity ASCII, the handler ignores the
leading bit when checking for these characters.
For this reason non-ASCII input is not acceptable
to the Teletype handler.

While this is no problem to systems having a
high-speed paper tape reader, those who lack one
would be unable to load any binary paper tapes
under PS/8.
For this reason there is a special
low-speed paper tape handler available in CONFIG.
To assemble this option, define the following:
N0HSPT=1
When N0HSPT=1 is used the PTR and PTP handlers
are replaced with new Teletype routines.
(The
names of the new handlers remain PTR for input
and PTP for output.

5-4

WARNING!
The source of CONFIG released in November
1970 contains an error in this 1 ow- speed
paper tape routine.
To correct this insert the following code immediately before
the terminating $ in CONFIG. PA:
,

IFNZRO NOHSPT <*6522
RTL
RTL
DCA PTR
TAD PTR >
This omission will be corrected in later
releases of CONFIG

Like the high-speed paper tape reader handler, the
low-speed handler prints a f character before
reading a tape. The user then loads the tape to
be read in the low-speed reader and sets the Teletype reader switch to START. While reading from
the low-speed reader, do NOT type anything on the
keyboard.
At the end of the reading process, turn
the Teletype reader control switch to STOP and remove the tape.
The PTR and PTP handlers differ from the standard
TTY handler in that they ignore control characters.
The PTR handler recognizes an end-of-tape condition
by "timing out" the low- speed reader - it expects
the keyboard/reader flag to be reset within 150 ms
and if it is not, an end-of-file occurs. At the
end-of-file a CTRL/Z is automatically inserted in
the buffer following the last character read.

5.1.3

Other Options

There is one more option that can be used in building a nonstandard PS/8 system. The parameter DIRECT determines whether
or not the system directory is to be zeroed when the system is
Defining DIRECT=1 causes a new system to be built
rebuilt.

without zeroing the old directory. This feature is useful
when reconfiguring a system to avoid having to reload all of
the files currently on the system device.

5-5

Example

5.1.4

As an example of reconfiguring a PS/8 system, suppose a machine

has the following configuration:

PDF- 8/1 computer

DECtape

RFjZfS

Type 645 line printer (LP12)

High-speed reader/punch
Card reader

disk with two RSj38's (768K of storage)

The following steps would be taken to build a system tailored
to the above configuration.

Build the system in the usual manner using the
RFj2f8 CONFIG provided and the instructions in
the 8K Programming System User's Guide
.

Use PIP to put the file CONFIG. PA on the disk.

Execute the following commands:
.R EDIT
*PARA.PA <

/PARAMETER FILE
RFjEiS SYSTEM
/OLD STYLE LINE PRINTER
/PRESERVE SYSTEM DIRECTORY

/3 PLATTER

RFJ08=3
LPjaf8=J2r

DIRECT=1
#E

R PAL8
*PTP:< PARA, CONFIG
•

Use the paper tape punched by PAL8 as the CONFIG
binary in building a new system.

Finally, since the DIRECT parameter prevented the new size o
the system device (changed from 256K to 768K for this example) from being automatically written in the directory,
it must be updated by the following operation:
.R PIP
*SYS: < SYS:/S=1

ARE YOU SURE?
YES
5-6

5.2

Building a System on DECtape or LINCtape

To avoid the time involved in rebuilding the system off paper
tape each time it is changed, the binary tapes of PS/8, the
and CONFIG can be placed on DECtape (or
Command Decoder (CD)
LINCtape) and the system built by the following procedure:
,

and the tape,
Put the system tape on unit
containing the binary files PS8.BN, CD.BN,
and CONFIG. BN on unit 1 (where CONFIG. BN corresponds to the system configuration)

Bootstrap the DECtape (or LINCtape) system
and execute the following command:
.R ABSLDR

*DTA1 PS 8 CONFI G/G
:

The system should halt with 7777 in the AC
(if not, an error has occurred, try again
press CONTINUE to proceed.
from step b)
If the system device is not being changed,
the build is complete at this point, otherwise execute the following command:
;

.R ABSLDR

*DTA1 :PS 8 CONFIG ,CD/G
,

The new system is built and responds to the
RETURN key by printing a dot when ready to
accept input. Now, if necessary, transfer
files to the new system device with PIP.

Of course the above procedure is not limited to DECtape or LINCtape.
The files PS8.BN, CD.BN, and CONFIG. BN could just as
The example
easily be placed on a disk and loaded from there.
is intended to illustrate a useful alternative technique for

building a system.
5.3

Adding New Device Handlers

PS/8 system programs have been organized so that all nonTeletype I/O is done via calls to standard system device

Any new device for which a handler is written can
be added to the system by changing CONFIG and rebuilding the
handlers.

5-7

Once this is done, all existing system programs are
This flexibility is one of the
able to use the new device.

system.

most important features of the PS/8 system.

NOTE
In the November 19 70 version of PS/8 the following cannot use devices that require two page de-

vice handlers:
and SAVE operations,

GET, RUN,

CONVERT output device must have a one-page
handler

PIP cannot perform /Z or /D operations on
devices requiring two page handlers,

SABR cannot use two page handlers, and

General I/O in FORTRAN, READ (4, n) and WRITE
(4,n), cannot use two page device handlers.

Future versions of PS/8 will not contain these
restrictions
The following sections describe in detail how to add a new device handler. For further information on device handlers, the

Examples of standard handlers
reader should consult Chapter 4.
can be found in the listing of CONFIG which can be ordered from
the DEC Program Library (DEC-P8-MW3A-LA)

5.3.1

Writing Device Handlers

A device handler is a page-independent one or two page long
subroutine. The device handler must run properly in any single
(except 0000 to 0177
page or two contiguous pages in field
All device handlers have the same calling
or 7600 to 7777)
.

sequence

5-8

CDF N
GIF
JMS I ENTRY
FUNCTION

BUFFER
BLOCK
ERROR
NORMAL

/N IS CURRENT FIELD TIMES 10 (OCTAL)
/DEVICE HANDLER LOCATED IN FIELD
/ENTRY IS DETERMINED BY USR "FETCH"
/FUNCTION IS BROKEN DOWN AS FOLLOWS:
FOR READ
/ BIT
"
1
FOR
WRITE
BIT
/
=
NUMBER OF PCS TO TRANSFER
5
BITS
1
TO
/
=
BITS
8
FIELD FOR TRANSFER
6
TO
/
=
DEVICE DEPENDENT BITS
11
BITS
9
TO
/
/CORE ADDRESS OF TRANSFER BUFFER
/STARTING BLOCK NUMBER FOR TRANSFER
/ERROR RETURN, AC>=;2( MEANS END-OF-FILE
AC<;af
MEANS FATAL ERROR
/
/NORMAL RETURN

0=0

The device handler reads or writes a number of 128 word records
In general, device handlers
beginning at the selected block.

should conform to the following standards:
a.

On normal return from a device handler the AC is
zero and the DATA FIELD is always restored to
its original entry value.

Although the starting block number has true significance only for file structured devices,
handlers for non-file structured devices can
check the block number and perform initialization
For example, the
if the block number is zero.
line printer handler outputs a form feed before
printing when the specified block number is zero.

Handlers should be written to be as foolproof as
Examples of typical user errors are:
possible.
calling handler with non-zero AC (always perform
trying to read on a writea CLA in the handler)
only device, or trying to write on a read-only
specifying
device (give a fatal error return)
pages to be transferred (accept as meaning no acor attempting to
tual transfer is to take place)
access a nonexistent block (give a fatal error re;

;

turn) .
d.

Device handlers normally check to see if a CTRL/C
If one
(ASCII 203) has been typed by the user.
has, the handler aborts I/O and JMP s to location
7600 in field 0.
'

5-9

Device handlers should be able to detect standard
error conditions like checksum or parity errors.
Whenever possible, several attempts to perform
the transfer should be made before aborting I/O
In addition, when
and taking the error exit.
operator intervention is required, the handler would
normally wait for the action rather than take a
For example, if the paper tape
fatal error exit.
punch is not turned on, the PTP handler waits for
the punch to be turned on.

By convention, in any handler for a device (like
DECtape) that can search either forward or backward for a block, Bit 11 of the function word (one
of the device'-dependent bits) controls the startBit 11 is a 1 if
ing direction of the search.
if it
is
forward
and a
direction
the starting
bits
dependent
device
other
two
reverse.
The
is
present
significance
at
the
any
assigned
are not
time.

Remember that the user specifies a multiple of
128 words to transfer, whereas the transfer starts
This means
at the beginning of a 256 word block.
that the handler must provide the capability of
reading or writing the first half of a block.
When writing the first half of the block, the contents of the second half of the block can be
altered.

The entry point to a two page device handler must
be in the first page.

A number of handlers can be included in the one or
two pages of code. Where more than one handler is
included in a single handler subroutine, the handlers
Co-resident handlers are
are called co-resident.
always brought into core together. For example,
all eight DECtape handlers fit into one page; hence,
One restricthe DECtape handlers are co-resident.
if
they are
tion on co-resident handlers is that
in the first
points
must
be
two pages long all entry
page.

The USR, while doing file operations, maintains in
core the last directory block read in order to reThe
duce the number of directory reads necessary.
proper functioning of this feature depends on the
fact that every handler for a file-structured device
on a single system has a unique entry point relative
The relative entry
to the beginning of the handler.
points currently assigned for file structured handlers
are

5-10

Device Handlers

Relative Entry Points

MAGtapes
System Device Handler
DECtape or LINCtape

10 to 17
20

RKAJ2(

RKAl
RKA2
RKA3

21
22
23

If the device is block oriented (such as DECtape,
LINCtape, or disk), then the handler transfers
data directly with no alteration. However, if
the device is character oriented (such as a paper
tape reader. Teletype, or line printer)
the
handler is required to pack characters into the
buffer on input and unpack them on output. The
standard PS/8 character packing format puts three
8-bit characters into two words as follows
,

WORD *

CHARACTER 3
BITS 0-3

CHARACTER

WORD 2

CHARACTER 3
BITS 4-7

CHARACTER 2

When packing characters on input, the character
CTRL/Z (octal 232) is inserted at the logical
end-of-file (for example, at the end of the tape
in the paper tape reader handler)
Following
CTRL/Z, the remaining words of the input buffer
should be zeroed.
.

The device handler, whether one or two pages
long, must be completely page independent: it
can be loaded and executed in any page in field
except page
and 7600 to 7777. Page independent code can have no address constants.
For example, the following routine illustrates how a
table lookup would be performed in page independent and non-page independent code

Non-Page Independent Code

Page Independent Code

TAD INDEX
TAD (TABLE)
DCA TEMP
TAD I TEMP
INDEX,
TEMP
TABLE

TAD INDEX
TAD (TAD TABLE)
DCA .+1

INDEX,
TABLE

5-11

The page independent method works only because
the table must be in the same page. Writing
page independent code for one page handlers is
Two page handlers are considerably
quite easy.
more difficult, since communication between the
two pages requires the handler to determine where
Specifically, two page
in core it was loaded.
handlers often include one-time initialization
code that performs a JMS to determine where it
is.
The card reader handler in CONFIG should
be studied by anyone who writes a two page
handler.

Editing Device Handlers Into CONFIG

5.3.2

Once a new handler has been written and thoroughly debugged as
a stand-alone subroutine, it can be added to the system by editing the handler into CONFIG. PA, changing certain sections in
CONFIG, reassembling the result, and building a new system from
the binary tape produced.

Follow the following steps to build a

new PS/8 system:
a.

Edit the handler into CONFIG. The handler should
be origined into the areas of core between 4400
to 5577 or 14000 to 17577.

Select a system block on which to write the handler.
The first device handler storage block is "DVHORG"*,
and the last available block for device handlers
is "DVHORG" + 7 (blocks 16 [octal] to 2 5 [octal] in
Existing device handlers rethe current system)
quire blocks "DVHORG" through "DVH0RG"+4.
.

In the generation section of CONFIG (the subroutine
"WRDEVH") edit in a call to the system handler to
write the desired device handler onto the selected
device handler storage block. The calls already
included in this subroutine should provide suffi-

cient examples.
d.

Select a device number for the new device. The
number must be in the range 3 to 15 because device
number 1 is reserved for SYS and device number 2
The number selected will reis reserved for DSK.
move some standard device from the system; the device removed should be a "useless" one (for example,
remove DTA7 if the system has less than 8 DECtape

*Names in quotes refer to symbols used in CONFIG. PA.
5-12

If the handler contains co-resident
drives)
device handlers several device numbers must be
selected (not necessarily consecutive numbers)
.

Edit into CONFIG the new entries for the Permanent Device Name Table ("SDNAME") and the Device
In both
Handler Information Table ("SDVHND").
cases the device number is an index to the table
See Appendix B for informaentry to be changed.
Remember
tion about entries in these tables.
that entries must be made for all co-resident
handlers.

NOTE

When considering a name for the device,
be certain to select one that does not
conflict with an existing device name.
See section B.3.1.
f.

Check the device Type Table explained in section
B.3.5.
If the new device is similar to an existing device then assign the new device the same
(If the
device type code as the existing device.
similar
is
file
structured,
it
can
only
be
device
Otherwise select
to devices of the same size.)
in
range
21 to 77 (octal)
device
type
the
a new
Now edit into CONFIG a new entry in the Device
Control Word Table ("DCB"), see section B.3.5
Again, entries
to get the format for an entry.
must be made for all co-resident handlers.

If there is any device other than the system device that should be the new default file storage
change the entries for device numdevice (DSK)
ber 2 in the Device Handler Information Table
("SDVHND") and the Device Control Word Table ("DCB")
to be identical to the entries for the selected
device.
,

NOTE
The new device DSK will no longer be
equivalent to the system device, hence
its device handler will no longer be
permanently resident. The entry in the
Device Handler Residency Table (see section B.3.3) must be zeroed. This is done
by editing the following code into the
end of CONFIG:
*1^50',0

/DSK IS NON-RESIDENT

*Names in quotes refer to symbols used in CONFIG. PA.

5-13

All the edits to CONFIG are now complete.
Assemble the new source of CONFIG and rebuild the system by following the instructions given in section 5.1.

Finally, if the new device is a file structured device for which it was necessary to
select a new device type code in step f,
the Device Length Table in the file PIP.SV
must be patched so that PIP can perform /Z
and /S operations on the device correctly.
This can be done easily by using the system
ODT as follows

Teleprinter Output

Notes

.GET SYS: PIP
.ODT
13 6nn/0jZfj3|2f xxxx

+C
.SAVE SYSrPIP

where nn is the new device type code in octal
and xxxx is minus the
highest PS/8 block number for the device, also
in octal.

5-14

APPENDIX A
PS/8 File Structures

A.l

File Directories

Blocks

through

on all file structured devices are re-

served for the file directory of that device.

Six blocks

are always allocated but all are not necessarily active at

any given time.

To minimize the number of directory reads

and writes necessary, PS/8 fills one directory block com-

pletely before overflowing onto a second block. Thus the user
with only a few files can perform directory LOOKUPS and
ENTERS faster than one with many files.
The directory blocks are each structured according to the

following format:

ENTRY
MINUS THE NUMBER OF ENTRIES
IN

THIS SEGMENT

THE STARTING BLOCK NUMBER
OF THE FIRST FILE IN THIS

SEGMENT
TO NEXT SEGMENT- ZERO
NO NEXT SEGMENT.

LINK
IF

{DIRECTORY SEGMENTS ARE ALWAYS
LOADED INTO LOCATIONS 1400
TO 11777 BY THE USR.THIS
POINTER IS EITHER
OR BETWEEN
1400 AND 1777

FLAG WORD- POINTS TO LAST WORD
OF TENTATIVE FILE ENTRY IN
THIS SEGMENT

MINUS THE NUMBER OF
ADDITIONAL INFORMATION WORDS

TtHE NUMBER OF ADDITIONAL
INFORMATION WORDS SPECIFIED
MUST BE THE SAME IN ALL
DIRECTORY
SEGMENTS
L

BEGINNING OF FILE ENTRIES

:*
3778

f
END OF DIRECTORY BLOCK

through 4 of each directory block are called the
segment header.

Locations

A-l

A. 1.1

Directory Entries

There are three types of file directory entries
file entry appears as follows:
Location

FILE

FILE
1

Notes

Contents

FILE NAME
CHARACTER Z

NAME

CHARACTER

NAME
CHARACTER 4

NAME

FILE

CHARACTER 3

THE FILE NAME AND EXTENSION
S

FILE

CHARACTER 5

CHARACTER 6

FILE EXTENSION

CHARACTER

CHARACTER 2

FWCKEO IN SIXBIT ASCII

(i,e.,"A"WOULD BE 01).

NAME

FILE NAME

A permanent

N.THE NUMBER OF ADDITIONAL
i

ADDITIONAL
INFORMATION

WORDS

INFORMATION WORDS, IS GIVEN
BY WORD 4 OF THE DIRECTORY
HEADER. IF N # . THEN WORD
4 OF THE ENTRY IS THE
CREATION DATE OF THE FILE.

N+3

N+4

MINUS FILE LENGTH IN BLOCKS

Note - if word

is zero, the given file has a null extension,

An empty file entry appears as follows:
Location

ENTRY

Contents

ALWAYS 0000

MINUS THE NUMBER OF BLOCKS
IN THIS EMPTY FILE

A-

A tentative file entry appears as a permanent file entry with
It is always immediately followed by an
a length of zero.
empty file entry. When the tentative file is entered in a
directory, location 3 in the segment header becomes a pointer
The CLOSE function inserts the length word of
to this entry.
the tentative file entry, making it a permanent file, and adjusts the length of the following empty file entry (deleting
that entry if the length becomes zero)
Whether or not there is a tentative file open on any device
is determined by examination of bits 9 to 11 of the system Device
Control Word Table (see section B.3.5) no t the contents of
location 3 in the segment header.
Zeroing these bits in the
Device Control Word Table makes the active tentative file on
the device inactive.

The next time that the system has to
write the directory segment, the inactive tentative file entry
is removed.

The distinction between active and inactive tenta-

tive files is made so that PS/8 can avoid spending the time

required to perform an extra read and write of the device directory.
A. 1.2

Number and Size of PS/8 Files

All files on a PS/8 device must occupy a contiguous group of

blocks on the device.

The length of any file is indicated in

its directory entry, and the starting block of the file is de-

duced by adding together word 1 of the segment header and the
lengths of all files whose entries precede it in the directory
segment.

Each directory segment must have enough unused words at the end
to accommodate a permanent file entry (N+5 words, where N is the
number of Additional Information Words). Thus, if N is the number
of Additional Information Words the maximum number of permanent
file entries in any one segment is
MAX = r

256-5 -

(N+5)i

246-N ]

A-3

Directory fragmentation (alternation of permanent file entries
with empty file entries) reduces this maximum, and in the worst
case the number of permanent file entries in any one segment is

limited to
r 256-7 - (N+5) 1 =
MIN - L
J
1^+7

r 244-N

N+7

with N=l, MAX=40, and MIN=30. Since there are six segments in
the directory, the maximum number of files possible (with N=l)
would be 2 40.
Finally, PS/8 devices are limited to 4095 blocks, each 256
words long. Thus, the maximum size of any single PS/8 file

Blocks

structured device is 1,048,320 words.

through

of the

device are unavailable for file storage; therefore, the l£irgest
possible file is 4088 blocks long, or 1,046,528 words.
A. 1.3

Sample Directory

The initial directory written when the PS/8 system is built
looks as follows

Location

Contents

Notes
TWO ENTRIES
FILE STORAGE STARTS AT BLOCK 709*

SEGMENT
HEADER

/
^

NO ADDITIONAL DIRECTORY SEGMENTS
NO TENTATIVE FILES
ONE ADDITIONAL INFORMATION WORD

FILE NAME

"ABSLDR"

PERMANENT
FILE

ENTRY

FILE EXTENSION IS .SV

DATE IS 10/31/70
LENGTH IS FIVE BLOCKS

EMPTY FILE

EMPTY
FILE

ENTRY

IS 12448 <676,q) BLOCKS DEPENDENT ON THE SYSTEM
DEVICE USED, 676 IS THE VALUE FOR
A OECTAPE SYSTEM.

LENGTH
THIS

3778

* THIS LEAVES ROOM FOR THE
PS/8 SYSTEM AREAS

A-

A. 2

File Formats

There are three different standard file formats used by PS/8
and associated system programs:
ASCII and Binary files*
Core Image files

(.SV format)

Relocatable FORTRAN library files (LIB8.RL is the
only current example of this format)
ASCII and Binary Files

A. 2.1

ASCII and Binary files are packed three characters into two
words, as follows:

WORD

CHARACTER 3
1

WORD Z

CHARACTER

BITS 0-3

CHARACTER 3
BITS 4-7

CHARACTER 2
4

The following conventions are used by PS/8 system programs:
In ASCII files the character NULL (ASCII

0)2(0)

is always ignored.

In Binary files the binary data must be preceded by one or more frames of leader/trailer
code (ASCII 2)2^0 code)
The first character of
binary data must be either 100 to 177 octal (an
origin setting for absolute binary files) or
240 to 257 octal (a COMMON declaration frame
for relocatable binary files)
The end of binary
data is indicated by one or more frames of leader/
trailer code.
.

ASCII and Binary files are terminated by a CTRL/Z
code (ASCII 232).
In binary files, a CTRL/Z code
occurring before the trailer code is treated as
data rather than end-of~file.

*Binary files can contain either absolute binary data (i.e.,
output from PALS) or relocatable binary data (i.e. output from
,

SABR) .

A-

A. 2. 2

Core Image (.SV format) Files

A core image file consists of a header block followed by the
The header block is called the Core Conactual core image.
The Core Control Block consists of the first 128
trol Block.
words of the 256 word block reserved for that purpose. The
The Core Control Block is format-

second 12 8 words are unused.
ted as follows
Location

Notes

Contents
CORE CaVTROL BLOCK
MINUS THE NUMBER OF CORE SEGMENTS

62N3 WHERE N IS THE

CDF CIF (STARTING FIELD)

"STARTING FIELD

STARTING ADDRESS

JOB STATUS WORD

CORE SEGMENT

«:

)

CONTROL DOUBLEWORDS
(K IS THE NUMBER OF

2K+3

CORE SEGMENTS

REMAINDER OF BLOCK
IS

3778

UNUSED

The format of the Job Status Word is as follows

Meaning

Bit Condition
Bit

0=1

File does not load into locations
in field 0.

to 1777

Bit

1=1

File does not load into locations
in field 1.

to 1777

Bit

2=1

Program must be reloaded before it can be
restarted.

A-

Meaning

Bit Condition

Bit 10 =

need not be
to 17 77 in field
Locations
preserved when the Command Decoder is called.

Bit 11 =

to 1777 in field 1 need not be
Locations
preserved with the USR is called.

The Core Segment Doublewords control the reading and writing of
The format of each entry is as
the associated areas of core.

follows

Location

Notes

Contents

MULTIPLE OF 4008

CORE ORIGIN
NUMBER OF PAGES
TO LOAD

AND 9-11
ARE ZERO
BITS

FIELD

TO LOAD

The Core Segment
The core origin must be a multiple of 400g.
Control Doublewords are sorted within the header block in order
of decreasing field and increasing origin within the same field.

There can be no more than 32, „ Core Segment Control Doublewords
in any Core Control Block.

The Core Control Block for the program at the time it is loaded
into core is always saved in words 200p through 377„ of block 37g
It is
(one of the system scratch blocks) on the system device.

placed there by the GET and RUN operations or by the ABSLDR or
LOADER programs. This Core Control Block is used when performing
a SAVE without arguments
NOTE
The R command differs from the RUN command in that
the program's Core Control Block is not written onIn
to the scratch area when using the R command.
order to SAVE a program that has been loaded by the
R command all of the argument of the SAVE command
must be explicitly stated.

A-

Relocatable FORTRAN Library File

A. 2. 3

A relocatable FORTRAN library consists of a library directory
block followed by relocatable binary segments. The directory

block has the following format:
Location

Notes

Contents
CH 1

CH 2

CH 3

CH 4

CH 5

CH 6

LOAD POINTER

NAME OF ENTRY

SIXBIT ASCII PADDED

WITH TRAILING BLANKS

/a
!

ADDITIONAL ENTR lES

•

e>
,

DENOTES END OF
NAME ENTRIES

•r

— *. LOADER CONTROL WORD(S)
OF LOADER CONTROL
— *-^ END
WORDS FOR THIS ENTRY
*

•

3770

which points
(relative to the beginning of the block) to an array of Loader
Control Words.
The Loader Control Words have the following
information:

The Load Pointer is a number between

and

377j,

D
-(STARTING BLOCK OF RELOCATABLE
BINARY DATA)- (DIRECTORY BLOCK #)-1

•NUMBER OF PAGES OCCUPIED
BY THIS SEGMENT AFTER
LOADING

A-

There can be one or more Loader Control Words for each
The Loader Control Words for an entry are termientry.

nated by a word of zero.
block.

The following is a simple directory

Location Contents

Notes

1117
1

1040

4040

0376

0530

1124

4040

0373

0000

*'r/Mj
NAME OF ENTRY IS"I0H

NAME OF ENTRY IS" EXIT.."

LOAD POINTER F0R"EXIT"

MARKS END OF ENTRIES

WORDS

LOAD POINTER F0R"I0H"

)

LOADER
CONTROL

(RELATIVE BLOCK lOsKONE PAGE LONG)

373

0207

(

374

0411

(

375

0000

(RELATIVE BLOCK 128XTW0 PAGES LONG)

FOR "EXIT"

LOADER
376
CONTROL
WORDS
F0R"I0H" 13773
1778

2400

(RELATIVE BLOCK 1)( 123 PAGES LONG)

0000

A-

APPENDIX B
DETAILED LAYOUT OF THE SYSTEM

the reserved areas on the
This appendix covers three topics:
system device, the resident portion of PS/8, and the various

system tables.

Layout of the System Device

B.l

The first 70oo blocks (14K words) on the system device are reserved by the PS/8 system. These blocks are used as follows:

Contents

Block (s) in Octal
pr

i-e

7-12
13--15
16-•25
26
27-50
51-•53
54--55

56
57
6 0--63

64--67

System Bootstrap Routine
Device Directory
Keyboard Monitor
User Service Routine
Device Handlers
ENTER Processor for USR
System Scratch Blocks
Command Decoder
SAVE and DATE Overlays
Monitor Error Routine
CHAIN Processor for USR
System ODT
Reserved for System Expansion

File storage begins with block 70g.

The system scratch blocks are used for preserving the contents
of core when the Keyboard Monitor, USRy Command Decoder, or ODT
In addition, various system programs use the scratch
are loaded.
Most importantly the SAVE command expects the Core Control
area.
Block to be loaded in words 200g to 377g of block 37g. The Core
Control Block is stored at those locations by the GET or RUN com,

mand or by the ABSLDR or LOADER program.

A detailed breakdown of system scratch block usage follows:

B-1

Block (s) in Octal

B.2

Contents

27-32

The contents of locations 10000 to 11777
are saved in this area when the USR is
loaded.

33-36

The contents of locations
to 1777 are
saved in this area when the Command Decoder, Keyboard Monitor, or ODT is loaded,

Words 200g to 377g of this block contain
the Core Control Block for the last program loaded by the GET or RUN command, or
the ABSLDR or LOADER program.

40-47

Used as scratch storage by the ABSLDR and
LOADER programs.

Reserved for future expansion.

Layout of the PS/8 Resident Program

The top core pages in fields
and 1 are used by the resident portion of PS/8 and are not accessible by the user.
Future expansion
of PS/8 may later require space to be allocated in the top page
of field 2.
As a general rule, system and user programs should
never destroy the contents of locations 7600 to 7777 of aii^
field.

The resident portion of PS/8 is structured as foil ows

Location

Contents

Notes

— ENTRY

7600

NON-DESTRUCTIVE
TO PS/e

WRITE OPERATION

JMP TO FIELD

7605

DESTRUCTIVE
ENTRY TO PS/8

FOR READ

7607
<

SYSTEM DEVICE HANDLER

r^ENTRY TO SYSTEM

DEVICE HANDLER

7743
7744

CURRENT STARTING ADDRESS
7745
7746

JOB STATUS WORD

— MUST ALWAYS BE ZE

7747

7750

RESERVED FOR DATA BREAK
LOCATIONS

7755
7756
!

— THE KEY BOARD

PROGRAM SETUP AREA

S 1

7777

B-2

MONITOR AND ODT
MODIFY THIS AREA

TOP PAGE OF FIELD

Location

Contents

Notes

7600
,

OUTPUT FILE LIST (3 ENTRIES)

7616
7617
INPUT FILE LIST

7641

7642

(MAXIMUM 9 ENTRIES)
e

-0 MARKS END
OF LIST

DECODER

AREA

HIGH 11 BITS 0F = N

-* BIT = IF
COMMAND LINE
1

7643
SPECIFIED OPTIONS

TERMINATED BY

ALTMODE

7645
7646

COMMAND

LOW 12 BITS OF =N

7647
DEVICE HANDLER

RESIDENCY TABLE

7665
7666

SYSTEM DATE WORD

7667

READ OPERATION
(LOAD KEYBOARD MONITOR)

7677
7700

USR CALL AND RETURN AREA

ENTRY TO USR

7740

NOTE
-SYSTEM ODT DESTROYS
CONTENTS OF THIS TABLE
WHEN SETTING BREAKPOINTS

7741

USER DEVICE
NAME TABLE
7757
7760
DEVICE CONTROL WORD

TABLE

7776
7777

B.3

RESERVED FOR FUTURE USE

UNUSED

System Device Tables

Each device is described to the system by entries in five sysEach of these tables is fifteen words long, where
tem tables.
The five tables
the device number is the index into the table.
are described below.

B.3.1

Permanent Device Name Table

Entries in this table specify the permanent name of each device.
The entries are computed by encoding the actual four-character

device name in a single word as follows
B-3

The device name is expressed as two words in
the standard DEVICE format.
For example, if
the device name were "PTR"
the two words would
,

be:

WORD
WORD

1:
2:

2024
2200

Note that when the device name is left justified;
O's are inserted to fill four characters.
b.

A single word is created by adding together these
two words

If word 2 is non-zero, bit
of the resulting word
is forced to be a one.
For example, the table
entry for "PTR" would be 4224.

An entry of zero means that there is no device for the corre-

sponding device number.
NOTE

Conventionally, device names consist only of the
characters A to Z and
The first characto 9.
ter of the device name should be alphabetic.
The
coding used makes all one and two character device
names unique; however, names of more than two
characters are not unique.
For example, "PTR"
and "RTP" have the same encoding.
The Permanent Device Name Table is fifteen locations long; it

When the USR is in core the beginning of
the table is in field 1 at a location the address of which is
contained in location 10 03 6.
resides in the USR.

B.3.2

User Device Name Table

Entries are made in this table whenever the user performs

cin

ASSIGN and are restored to zero by a DEASSIGN. These entries
have the same format as those in the Permanent Device Name
Table.
The User Device Name Table resides in locations 17741 through
17757.

B-4

NOTE
The User Device Name Table is used by ODT for
setting breakpoints.
For this reason the user
should never ASSIGN any user device names when
debugging with ODT.
B.3.3

Device Handler Residency Table

When a device handler is loaded by the USR, the entry in this
table for the device loaded (and entries for all devices whose

handlers are co-resident, if any) is set to contain the entry
point for the device handler. Entries other than those that
contain an address above 7600 (thus referring to the system
handler) are restored to
when a RESET, DECODE or CHAIN function
is executed.
When a program exits to the Keyboard Monitor this
table is not cleared.
The Keyboard Monitor Commands GET, RUN,
R,

SAVE, and START (with no explicit address)

clear this table.

NOTE
Since the system device handler is always resident, the first entry (since SYS is always device number 1) in the Device Handler Residency
Table is always 7607 (the entry point of the
system device handler)
The Device Handler Residency Table resides in locations 17647
through 17665.

B.3.4

Device Handler Information Table

Each entry in this table contains all the information needed by
the USR to load the corresponding handler.
The format of these
entries is as follows

B-5

Bit Condition

Mean ing

0=1

If this is a two page device handler.

Bit
Bits

Bits

to 11

Contain the relative block location of
the device handler record on the system
This is computed by subtracting
device.
15 octal (one less than thei first device
handler block) jrom the actual block numlser.

Contain the offset of the handler entry
point from the beginning of the page.
Note that two page device handlers must
have their entry points in the first page.

the corresponding device handler is not saved
This is always
in any of the device handler storage blocks.
true of device number 1 (the system device) and for all device
If an entry is

numbers that are not used in a given configuration. The Device
Handler Information Table is 15 locations long and resides in
the USR. When the USR is in core the beginning of the table is
in field 1 at a location the address of which is contained in
location 10037.
B.3.5

Device Control Word Table

Entries in this table specify special device characteristics,
including the physical device type. The entry format is as
follows:

Meaning

Bit Condition

0=1
Bit 1=1
Bit 2=1

If the device is file-structured.

Bit

Bits

If the device is read-only.
If the device is write-only.
8

Contain the physical device type
code (described below).

B-6

Bit Condition
Bits

to 11

Meaning
For file structured devices, these bits
contain the directory block number of
the currently active tentative file.
If bits 9 to 11 are zero, there is no
active tentative file on the device.
For non-file structured devices, bits
9 to 11 are always zero.
Bits 9 to 11
are reset to zero by the commands GET,
RUN, R, SAVE, START (with no explicit
address) and optionally by the USR functions RESET and DECODE.

The device type is a number between
and 77 „, of which
o
through 20g are currently assigned to existing devices, as
follows

Device Type
Code

Device

Teletype
High-speed paper tape reader
High-speed paper tape punch
Card Reader
Line Printer
RK8 Disk
256K Disk (RFj2f8)
512K Disk (RF|af8 + RSi2f8)

1
2
3
4
5
6
7

10
11
12
13
14
15
16
17
20

21-77

76 8K Disk CRF0Q + 2 RS08"s)
1024K Disk (RF08 + 3 RS/2f8's)
32K Disk (DF32)
64K Disk (DF32 + DS32)
96K Disk (DF32 + 2 DS32's)
128K Disk (DF32 + 3 DS32's)
DECtape
LINCtape (PDP-12 only)
Magnetic Tape
To be assigned

The Device Control Word Table resides in locations 17760
through 1777 6.

B.3.6

Device Length Table

There is a sixth table that is not normally considered part
of the system tables.
This is the Device Length Table and
is used only by PIP to

perform the /Z (zero directory) and /S
B-7

Ccompress device) options.

This table is 64 locations

long,,

In this
one entry for each possible physical device type.
means that the corresponding device is
table an entry of
non-file structured; otherwise the entry contains the negative

of the number of available 256-word blocks on the device.

For example, the entry for a 256K disk would be 6000g (minus
or 1024^Q, 256-word blocks).
2000
,

The Device Length Table resides in PIP. When PIP is brought
into core the Device Length Table is in locations 13600 to
When new device types are added to the system this
13677.
table should be patched with ODT to reflect the device length
of the new device.

B-8

APPENDIX C
SYSTEM ERROR CONDITIONS AND MESSAGES

This is a summary of all error messages that are a result of

system errors.

These errors are also described in the rele-

vant sections of this manual and in the 8K Programming System
User's Guide.
C.l

System Halts

Errors that occur as a result of a major I/O failure on the
system device can cause a system halt to occur. These are as
follows

Meaning

Value of PC
00601

A read error occurred while attempting to load
ODT.
Return to the Keyboard Monitor by restarting at 07605.

07461

An error occurred while reading a program into
core during a CHAIN.
Return to the Keyboard
Monitor by restarting at 07605.

07605

An error occurred while attempting to write the
Keyboard Monitor area onto the system scratch
blocks.
Verify that the system device is not
WRITE LOCKED and restart at location 07600 to
try again.

07702

A user program has performed a JMS to 7700 in
This is a result of trying to call
field 0.
As
the USR without first performing a GIF 10.
location 07700 has been destroyed, the user must
re-bootstrap the system!

07764

A read error occurred while loading a program.
Return to the Keyboard Monitor by restarting at
07605.

07772

A read error occurred on the system scratch area
while loading a program.
Return to the Keyboard
Monitor by restarting at 07605.

C-1

Meaning

Value of PC
10066

An input error occurred while attempting to
Return to the Keyboard Monirestore the USR.
tor by restarting at 7605.

10256

A read error occurred while attempting to load
Return to the Keythe Monitor Error routine.
board Monitor by restarting at 07605.

176 76

An error occurred while attempting to read the
Keyboard Monitor from the system device. Try
DO NOT
again by restarting at location 07605.
PRESS CONTINUE.

17721

An error occurred while saving the USR area.
Verify that the system device is not WRITE
LOCKED, and press CONTINUE to try again.

17727

An error occurred while attempting to read the
USR from the system device. Return to the Keyboard Monitor by restarting at 7605.

17736

An error occurred while reading the scratch
Return to
blocks to restore the USR area.
the Keyboard Monitor by restarting at 07605,,

Also, there is one halt in the LOADER program:

00005

A parity error occurred when attempting to
overlay the LOADER from the system scratch
blocks.
Return to the Keyboard Monitor by
restarting at 07605, and try again.

After retrying the operation which caused the failure, if the
error persists it is the result of a hardware malfunction or a
Run the appropriate diagnostic
parity error in the system area.

program to check the device and rebuild the system.
C. 2

USR Errors

Fatal errors that occur during operation of the USR cause the
message:

MONITOR ERROR n AT xxxxx
to be printed.

In these cases, the value "n" describes the

C-2

error and "xxxxx" is the address of the call to the USR that
caused the error.
The six Monitor errors are:

Message

Meaning

MONITOR ERROR 1 AT xxxxx

File length in CLOSE function is
too large.

MONITOR ERROR 2 AT xxxxx

An I/O error occurred while attempting to read or write a directory block.
This is generally
caused by the device being WRITE
LOCKED

MONITOR ERROR 3 AT xxxxx

The device handler required for
a file operation (LOOKUP, ENTER,
CLOSE) is not in core.

MONITOR ERROR 4 AT xxxxx

Illegal call to the USR; either
an attempt has been made to call
the USR from locations 10000 to
11777 or a device number of zero
was specified.

MONITOR ERROR 5 AT XXXXX

I/O error occurred while reading
or writing on the system device.
Verify that the system device is
not WRITE LOCKED.

MONITOR ERROR 6 AT xxxxx

Directory overflow occurred (see
section A. 1.2 for limitations on
number of directory entries)

In addition to the MONITOR ERROR messages,

system and user pro-

grams can use the USR to print:

USER ERROR n AT xxxxx
by using the ERROR function.

In this case the value of "n" is

user-defined and "xxxxx" is the address of the call to the USR.
Currently, two USER ERROR numbers have been assigned:

Message

USER ERROR

(ji

AT xxxxx

Meaning
An I/O error occurred while attempting to load a program with
the GET, RUN, or R command.

C-3

Meaning

Message
USER ERROR 1 AT xxxxx

While running a FORTRAN or SABR
program, an attempt was made to
call a subroutine that had not
been loaded.

Following either a MONITOR ERROR message or a USER ERROR message
the USR exits to the Keyboard Monitor; the current contents of
core are preserved and bit 2 of the Job Status Word is set to
a 1 to prevent continuing from the error.

C.3

Keyboard Monitor Errors

In addition to the USR errors described previously, the following errors can occur after a command is given to the Keyboard

Monitor:

Meaning

Message
aaaa;

The Keyboard Monitor cannot interFor expret the command "aaaa"
ample, if the user types HELLO,
the system will respond HELLO?
.

TOO FEW ARCS

An argiament has been omitted from
a command.

device NOT AVAILABLE

The permanent device name specified
in an ASSIGN, SAVE, RUN, or GET command does not exist.

name NOT FOUND

The file name specified was not
located on the device indicated.
This error can also be caused by
trying to RUN or GET from an output
only device.

BAD ARCS

Arguments to a SAVE command are inconsistent.

ILLEGAL ARC.

Illegal syntax in a SAVE command.

SAVE ERROR

An I/O error occurred while saving
The contents of core
the program.
remain intact.

C-4

Message

Meaning

BAD CORE IMAGE

The file requested with an R,
RUN, or GET command is not a
core image file.

NO!

A START command (with no address
specified) is prohibited when
bit 2 of the Job Status Word
(location 07746) is a 1.

BAD DATE

Improper syntax in a DATE command.

SYSTEM ERROR

C.4

An error occurred while doing
I/O to the system device.

Command Decoder Errors

The following errors are printed by the Command Decoder.

After
the error message, the Command Decoder starts a new line, prints
a *, and waits for another command line.
The erroneous command
is ignored.
Message

Meaning

ILLEGAL SYNTAX

The command line is formatted incorrectly.

TOO MANY FILES

More than three output files or
nine input files were specified.*

device DOES NOT EXIST

The specified device name does
not correspond to any permanent
device name or any user assigned
device name.

name NOT FOUND

The specified input file name was
not found on the device indicated,

*In the special mode of the Command Decoder this message would
be printed if more than one output file or five input files
were specified. See section 3.5.

C-5

APPENDIX D

PROGRAMMING NOTES

This appendix is a potpourri of ideas and techniques
that have proven useful in programming the PDP-8.

PS/8 users may find some use in their own programs
for the techniques mentioned here.

D.l

The Default File Storage Device, DSK

D.2

Modification to Card Reader Handler

D.3

Suppression of Carriage Return/Line Feed in FORTRAN I/O

D.4

Accessing the System Date in a FORTRAN Program

D.5

Determining Core Size on PDP-8 Family Computers

D.6

Relocating Code

D.7

Using PRTC12-F to Convert PS/8 DECtapes to PS/12 LINCtapes

D.8

Notes on Loading Device Handlers

D.9

Available Locations in the USR Area

D.IO

Accessing Additional Information Words in PS/8

D.ll

SABR Programming Notes

D-1

D.l

The Default File Storage Device, DSK

The Command Decoder, as noted earlier, makes certain assumptions
about the I/O device where none is explicitly stated. Namely,
on all output files where no device name is given, the device
DSK is assumed. On the first input file where no device name is

Subsequent input files assume the same
device as the previous input file. This convention was adopted
to simplify typing command lines.

given, DSK is assumed.

The permanent device name DSK is assigned when the system is
Changbuilt.
On all standard systems, DSK is equivalent to SYS.
ing the default file storage device is described in Chapter 5. A
useful technique is to use the ASSIGN command to redefine the

meaning of DSK temporarily. For example, where device DTA|2f is
equivalent to DSK and it becomes desirable to change DSK to DTAl,
the following command can be given:
.ASSIGN DTAl DSK

DTAl remains the default file storage device until it is assigned
This technique is
a new name or a DEASSIGN command is executed.
considerably easier to use than rebuilding the entire system.
D.2

Modification to Card Reader Handler

The standard card reader handler for PS/8 uses the DECj?29 standcird
Some installations may prefer to use the DECi^ae codes
card codes.
This can be done by changing the card conversion table
instead.
in CONFIG, reassembling CONFIG, and rebuilding the system, or by

rebuilding the system using the following procedure:
a.

Follow steps 1, 2, and 3 given in section 8.2 of the
8K Programming System User's Guide (if building a
DECtape system, mount the tape on which the system
is to be built on unit ffS, WRITE ENABLEd, and load
the DECtape CONFIG binary tape in step 3)

D-2

Make the following patch:
CHANGE LOCATION
FROM

5704
5705
5706

3203
4007
3502

7735
4076
0774

5714
5715
5716

7514
0577
3637

3314
1002
0305

5724
5725
5726
5727

0104
1211
3374
0641

3204
1273
3606
1341

5734
5735
5736

7316
3410
1376

3716
1175
3401

Now continue building the system with step 4 of
section 8.2 in the 8K Programming System User's
Guide.
The new system will have modified card
codes.

NOTE
This procedure does not affect FORTRAN
run time card input with READ (3,n)
The
conversion table for FORTRAN is
UTILTY.SB on source DECtape #3.
.

D-3

026 PUNCH CARD CODES

Octal 8-bit
Code

DECJ2(2 6

Code

Character

240
241
242
243
244
245
246
247

blank
12-8-7
0-8-5
0-8-6
11-8-3
0-8-7
11-8-7

SPACE

250
251
252
253
254
255
256
257

0-8-4
12-8-4^
11-8-4

8-6

0-8-3
11

12-8-3

260
261
262
263
264
265
266
267
270
271
272
273
274
275
276
277

#
$

%
&
I

(
)

•

0-1

1
2
3

3
4
5
6
7
8
9

4
5
6

7
8
9

11-8-2
0-8-2
12-8-6

8-3

11-8-6
12-8-2

•
•

Octal 8-bit
Code

DEC026
Code

Character

8-4

303
304
305
306
307

12-1
12-2
12-3
12-4
12-5
12-6
12-7

310
311
312
313
314
315
316
317

12-8
12-9
11-1
11-2
11-3
11-4
11-5
11-6

320
321
322
323
324
325
326
327

11-7
11-8
11-9
0-2
0-3
0-4
0-5
0-6

330
331
332
333
334
335
336
337

0-7
0-8
0-9
11-8-5
8-7
12-8-5
8-5
8-2^

300
301
302

B
C
D
E
F
G

J
K
L
.M

Q
R
S

T
U'

V
w
X
^
z
[

\
]
/v.

On some IBM 026 Keyboards this character is graphically represented as n
.

A card containing an 8-2 in column
blank is an end-of-file card.

D-4

with all remaining columns

D.3

Suppression of Carriage Return/Line Feed in FORTRAN

It is often desirable to suppress the automatic carriage return/
line feed (CR/LF) following FORTRAN WRITE statements to achieve

an easily readable text.

The following three methods in PS/8
FORTRAN can be used to achieve this result:
a.

Follow the
comma.
100
lj2fl

I/O, list of a WRITE statement with a
Thus, the following statements:

WRITE Cl,li2f)2f) N,
FORMAT (1X,15HTHE VALUE OF A(,I2,5H) IS
READ (1,1^2(1) A(N)
FORMAT CF8.4)

)

result in the following single line (assume N has
a value of 12 and a value of 147.83 is being input):

THE VALUE OF A (12)
b.

147.83

Use of an empty field print statement enables a text
to be printed without a following CR/LF when there
is no variable to be printed.
For example:
lj?2

WRITE (l,lJ3f2) I DUMMY,
FORMAT ('DESIRED TEXT" ,I|af)

READ statement using break character, as follows:
READ (l,lj2fl) IA,IB,IC
lj2fl
FORMAT ('A=' ,11, '6=' ,11, 'C=' ,11)
results in no CR/LF after each phrase is printed.
That is, the output is all printed on a single line.

D-5

D.4

Accessing the System Date in a FORTRAN Program

The availability of the system Date word in location 17666 is
useful to many PS/8 programs. The following FORTRAN program
illustrates how the Date can be accessed in SABR code:

C
C

PROGRAM PRINTS THE CURRENT DATE

S
S
S
S

DUMMY DATE
TAD I DATE
DCA TEMP
TAD TEMP
AND C7
DCA \ lYR
TAD TEMP
RAR;RTR
AND (37
DCA \IDAY
TAD TEMP
CLL RAL;RTL;RTL
AND C17
DCA \IM0
WRITE Cl,l|?|?) IMO,IDAY,IYR
12 - 12 -197 11/)
FORMAT (/'DATE:
CALL EXIT
CPAGE 2
6211

S
S
S
S
S
S
S
S
S
S
10fi

SDATE,

7666

STEMP

)2f

D-6

D.5

Determining Core Size on PDP-8 Family Computers

Many times system programs need to determine the amount of core
available to them at run time. For example, the PS/8 system
programs LOADER, PALS, and CREF perform this calculation. Because of differences in the extended memory control of PDP-8
family computers, subroutines that work on one machine might not
work on another
The following three conditions cause the most difficulty:
a.

On a PDP-8 with an extended memory control, addressing nonexistent memory from field J? causes the
following instruction to be skipped and the contents
of the corresponding field |? location to be executed.
For example:

/NONEXISTENT FIELD
/EXECUTED LOCATION X
/THIS INSTRUCTION SKIPPED

CDF 70
TAD I CX)
HLT

CLA CLL CML RAR

/LOAD 4000
the preceding code causes 4000 to be loaded into
the AC and the HLT instruction to be skipped when
executed on a PDP-8.
X,

On a PDP-12 with an odd number of 4K banks (12K,
20K, 2 8K)
all reads in the first nonexistent field
load zeros.
Reads to higher fields, as well as all
reads to nonexistent memory on a machine with an
even number of 4K banks load all one bits.
,

The PDP-8/L normally treats all CDF's to fields 2
through 7 as NOP s
(It tests bits 6 and 7 of all
CDF and CIF instructions for 0's before executing
the lOT.)
However, there is a special 12K option
for the PDP-8/L called a BMJ38.
With this option
a CDF to field 2 is valid, but a CDF to field 3 resets the Data Field to 0.
CDF's to fields 4
through 7 remain NOP s
'

For those who are interested, the following subroutine has been
tested on the PDP-8, 8/S 8/L, 8/1, 8/E, PDP-12, and LINC-8 com,

puters.

For the purpose of this example, it is assembled at

00200.

This is not essential, it can be in any 40

locations of any page in field 0.
D-7

(octal)

/SUBROUTINE TO DETERMINE CORE SIZE.
/THIS SUBROUTINE WORKS ON ANY PDF- 8 FAMILY
THE VALUE, FROM 1 TO IJ? (OCTAL),
/COMPUTER.
/OF THE FIRST NON-EXISTENT MEMORY FIELD IS
/RETURNED IN THE AC.

/NOTE
J?2J2fJ2f

i2f2j?l
J?2i2f2
J2(2j2f3

J?2|2(4
J2f2j2(5

J?2j2(6

02^1
021J?

0211
J3f212

0213
0214
0215
0216
0217
0220
0221
0222
0223
0224
0225
0226
0227
0230
0231

0000
7300
6201
1237
7006
7004
0217
1232
3211
6201
1635
7000
3211
1213
3635
0070
1635
7400
1221
1236
7640
5232
1211
3635
2237
5202

— THIS ROUTINE MUST BE PLACED IN FIELD ^

CORE,
COR0,

CORl,
C0R2,

CLA CLL
CDF
TAD
RTL
RAL
AND
TAD
DCA
CDF
TAD I

/MASK USEFUL BITS

/N
CORLOC

/SET UP CDF TO FIELD
/N IS FIELD TO TEST
/SAVE CURRENT CONTENTS
/(HACK FOR PDP-B:)

CORl
C0R2
CORLOC

/7000 IS A "GOOD" PATTE:E^

TAD
CORX,

CORLOC

740J2

CORX
TAD
CORV
TAD
SZA CLA
COREX
JMP
CORl
TAD
CORLOC
DCA I
CORSIZ
ISZ
COR0
JMP
CO REX,

CDF
TAD
JMP

/{NEEDED FOR PDP-8L)
/GET FIELD TO TEST

COR70
COREX

NOP

DCA
TAD
DCA I
COR70,

CORSIZ

/(HACK FOR PDP-8. , NO-OP)
/TRY TO READ BACK 7000
/(HACK FOR PDP-8, .NO-OP)
/GUARD AGAINST "WRAP AROUND"
/TAD (1400)

/NON-EXISTENT FIELD EXIT
/RESTORE CONTENTS DESTROYED
/TRY NEXT HIGHER FIELD

/LEAVE WITH DATA FIELD
/IST NON-EXISTENT FIELD

0232
0233
0234

62je}l

0235
0236

0221
1400

CORLOC,
CORV

CORX
1400

/ADDRESS TO TEST IN EACH FIELD
/7000+7400+1400 =

0237

0001

CORSIZ,

/CURRENT FIELD TO TEST

1237
5600

CORSIZ
CORE

D-8

D.6

Relocating Code

One useful programming trick is generating relocated code by
means of the ENPUNCH and NOPUNCH features of PALS.
In this case, relocated code is code that, for some reason,
is
to be loaded into an area of core different from the area in

which it is to be executed. For example, the system device handler
for PS/8 is loaded into 6600 through 6777, so as not to affect
the Binary Loader, and during the build process it is moved to the
top page of field
where it resides. Of course, it cannot be
simply assembled directly into 6600, since various address constants would be generated incorrectly.
The way around this
situation is to do two origins:
the first to the location in
which the code is loaded and the second to the location in which
j3r

it is eventually executed

The second origin is preceded by
a NOPUNCH so that no origin punch is put onto the binary
output
of PALS.
.

For example, if some code were to be loaded into 12 77 through 1476
but executed at 2000 through 2377, the following should appear
in the source file preceding the code:
*12 77

NOPUNCH
*2^00
ENPUNCH

/ADDRESS TO LOAD
/ADDRESS OF EXECUTION
/CODE BEGINS HERE

*1477

/RESET ACTUAL ASSEMBLY ORIGIN

This technique is used in several places in the source of PS/8.

NOTE
Code that is relocated in this fashion must not
use current page literals as they will be loaded
into the wrong area.
In addition, current page
literals should not be used in any code that
immediately precedes the relocated code, and
that is to be loaded onto the same page.
D-9

D.7

Using PRTC12-F to Convert PS/8 DECtapes to PS/12 LINCtapes

Many users of PS/8 on the PDP-12 will be interested in the fact
that, since PS/8 uses an identical file structure on all devices,
PDP-8 DECtape in PS/8 format may be directly copied to PS/8
LINCtapes by the PRTC12-F program.
The PRTC12-F program uses the PDP-12 TC12-F hardware option to
read DECtapes and convert these tapes to LINCtape. This hardware option is required to read DECtapes on the PDP-12.
The PRTC12-F program is described in the document DEC-12-YIYA-D.
This document describes the program operation in detail, and
The operations
must be read before attempting to use PRTC12-F.

that convert PS/8 format DECtapes are as follows:
a.

Mount the PS/8 DECtape on unit 1 and a PDP-12
LINCtape formatted with 129 words per block on
unit 2.

When the READ questionnaire is displayed,
respond as follows (responses are underlined;
the character ^ stands for carriage return
and
stands for line feed)
:

READ 1777J BLOCKS
TAPE FORMAT A J UNIT iJ
STARTING WITH BLOCK ^J^
etc.
c.

When the WRITE questionnaire is displayed, respond
as follows
WRITE THE RESULT
IN TAPE FORMAT B ) ON UNIT 2j
STARTING AT BLOCK j? J i
etc.

D-10

D.8

Notes on Loading Device Handlers

Problem with multiple input files
There is a problem associated with reusing Device Handler areas
in PS/8.
This problem is best illustrated by an example:
A.

Assume a program has reserved locations 1000-1377 for its input
handler and locations 7400-7577 for its output handler. If the
program gives a USR FETCH command to load the DTAl handler as
an input device handler, all

DECtape handlers will load into
1000-1377, since they are all co-resident.
If another FETCH is
issued to load the DTA2 handler as an output device handler,
that handler will not be loaded, because it shares space with
the DTAl handler currently in core.
This is fine
however, if
8

—

the user now switches input devices and FETCHes the paper tape
reader handler as an input device handler it will destroy the
DTA2 handler and the next attempt to output using the DTA2

handler will produce errors.
this problem.
1.

There are two ways to get around

Always assign the handler which you expect to
stay in core the longest first. Most programs can
process more than one input file per program step
assembly pass is one program step) but
only one output file; therefore, they assign the
output handler before any of the input handlers
(e.g.,

In the above example, the problem would be

eliminated if the DTA2 handler were assigned
first.
2.

Always give a USR RESET call before each FETCH.
Obviously, this call should not delete any open

output files. This means that the USR will always
load the new handler, even if another copy is in
core.

The user must FETCH the output handler again

before issuing the USR CLOSE call, otherwise the

D-11

USR will determine that the output handler is not
in core and give a MONITOR ERROR 3 message.
8K FORTRAN uses this second method for device-independent I/O

at run time

Dynamically Loading Device Handlers
Some programs which use dynamic core allocations will want to
use PS/8 Device handlers but cannot afford to always allocate
The following is a subthe maximum of two pages per handler.
routine which loads a device handler dynamically, returning its
It assumes that the name of the handler is in
entry in the AC.
locations NAMEl and NAME2, and a subroutine GETPAG exists which
gets a page from the bottom of available field j? of storage and

returns its address in the AC.
field

This example subroutine runs in

and can only be called from field

but can be re-

written for any other possibility.
ASSIGN,

J2f

TAD NAMEl
DCA Nl
TAD NAME
DCA N2
CDF CIF 10
JMS I (7700

/MOVE DEVICE NAME INTO "INQUIRE" COMTdAND

/USRIN

JMS

Nl,
N2,
LOCI,

/INQUIRE

j2f

FORCE USR INTO CORE

JMP ASSERR
TAD LOCI
SZA
JMP I ASSIGN
JMS GETPAG
DCA L0C2
ASSTRY, TAD N2
JMS I (200
L0C2,

(200

j3f

JMP TWOPAG
TAD L0C2
JMP I ASSIGN
TWOPAG, JMS GETPAG
ISZ L0C2
CLA
JMP ASSTRY
ASSERR,

/NO SUCH DEVICE - QUIT
/IS THE HANDLER ALREADY IN CORE?
/YES - RETURN ITS ENTRY POINT
/GET A PAGE DYNAMICALLY

/LOAD DEVICE NUMBER

/FETCH
/PAGE TO FETCH INTO
/FAILED - MUST BE A TWO-PAGE HANDLER

/RETURN ENTRY POINT
/GET ANOTHER PAGE
/SET "TWO PAGE HANDLER ALLOWED" BIT
/FETCH WILL SUCCEED THIS TIME
/ERROR ROUTINE
D-12

D.9

Available Locations in the USR Area

A few programs may need additional storage space in field 1
when the USR is in core. A number of locations in the USR area
ClOOOO to 11777) are available and may be used whenever the USR
is in core.

The locations are as follows:

Locations 10000 to 10006 are available for scratch
storage and/or ODT breakpoint usage, without restriction.

All auto-index registers (locations 10010 to 10017) may be
used, but these locations are destroyed by USR operations.

Location 10020 to 10037 may be used as scratch storage
with no restrictions.

Locations 11400 to 11777 are used by the USR to preserve
the last directory segment read while performing a LOOKUP,
ENTER, or CLOSE operation.
Location 10007 contains a key
specifying which segment of which device is currently in
core.

Any user program may use locations 11400 to 11777 as
scratch storage as long as location 10007 is set to
before the first use. Of course, the LOOKUP, ENTER, and
CLOSE operations will read a directory segment into 11400
to 11777 and set 10007 to a non-zero value again.

D-13

D.IO

Accessing Additional Information Words in PS/8

In all of these cases, the USR must have been previously brought

into core with the USRIN function.

After a LOOKUP or ENTER
After a LOOKUP or ENTER, location 10017 points to the length word
To get a pointer to the first Additional
of the file entry.
Information Word, a program would execute the following code:

CDF

IjH

TAD

C14j?4

SNA
JMP NONE
TAD I
(J^l^l?

/GET # OF ADDITIONAL INFORMATION WORDS
/FROM DIRECTORY
/NO ADDITIONAL INFORMATION WORDS

DCA POINTER

"POINTER" now points to the first Additional Information Word.

After a CLOSE
Because CLOSE is a legal operation even if no output file is
present, it is not suggested that Additional Information Words
To alter the Additional Informabe modified following a CLOSE.
tion Words of a permanent file, do a LOOKUP to get the directory

segment into core, then alter the words and rewrite the directory
segment.

Rewriting the Current Directory Segment
Whenever a user program changes the Additional Information Vfords,
of a file, it must rewrite the directory segment containing that
file entry in order to make sure the changes are permanently
C.

recorded.

rewrite the
The following code, which must be in field 1, will
current directory segment:

D-14

CDF Ipf
TAD 7
AND (7
DCA SEGNO
GIF
JMS I 51

/CODE IS IN FIELD 1
/GET DIRECTORY KEY WORD
/EXTRACT SEGMENT NUMBER

1400

/LOC 51 POINTS TO THE DEVICE HANDLER
/WRITE OPERATION
/DIRECTORY SEGMENT CORE ADDRESS

JMP ERROR

/ERROR REWRITING DIRECTORY

421J2f

SEGNO

Location 10051 will always point to the device handler entry point
used to read in the last directory segment, following a LOOKUP or

ENTER operation.

D-15

D.ll

SABR Programming Notes

Optimizing SABR Code
There are two types of users who will be using the SABR assembler those who like the convenience of page-boundary-independent code
and are willing to pay the price for it, and those who need a
relocatable assembler but are still very location conscious. These

optimizing hints are directed to the latter user.
One way to beat the high cost of non-paged code is to Page It
Yourself. This is done by using the LAP (Leave Automatic Paging)

pseudo-op and the PAGE pseudo-op to force paging where needed.
This saves 2 to 4 instructions per page from elimination of the
In addition, the fact that the program must be
page escape.
properly segmented may save a considerable amount.

Wasted core may be reduced by eliminating the ever-present CDF
instructions which SABR inserts into a program. This is done by
Define the following op codes:
using "fake indirects".
OPDEF
OPDEF
OPDEF
OPDEF

ANDI |2f4J2fJ?
TADI 14^ fH
ISZI 24J?|?
DCAI 3 4j2fJ2f

These codes correspond to the PDP-8 memory reference instructions
but they include an indirect bit. The difference can best be
appreciated by an example
If X is off-page, the sequence

LABEL, SZA
DCA

is assembled by SABR into

D-16

LABEL, SZA
JMS 45
SKP
DCA I (X)
or four instructions and one literal,

The sequence
FX, X

LABEL, SZA
DCAI PX

assembles into three instructions for a saving of 40 percent.
Note, however, that the user must be sure that the data field
will be correct when the code at LABEL is encountered. Also
note that the SABR assumes that the Data Field is equal to the
Instruction Field after a JMS instruction, so subroutine returns
should not use the JMPI op code.
The standard method to fetch a scalar integer argument of a
subroutine in SABR is:

Code
lARG,

DUMMY

SUBR,

BLOCK 2
TAD I SUBR
DCA X
INC SUBR#
TAD I SUBR
DCA X#
INC SUBR#
TAD I X
DCA lARG

BLOCK

This code requires 19 words of core and takes several hundred

D-17

microseconds to execute.

The following sequence:

Code
lARG,
SUBR,

BLOCK 2
TAD I SUBR
DCA X
INC SUBR#
TADI SUBR#
DCA lARG
INC SUBR#
HLT
TAD I lARG
DCA lARG

/THIS IS A CDF

takes only 14 words and executes in approximately 1/3 the time.

Calling the USR and Device Handlers from SABR code
One important thing to remember is that any code which calls the
USR must not reside in locations 10000 to 11777. Therefore, any
SABR routine which calls the USR must be loaded into a field
other than field 1 or above location 2000 in field 1. To call

the USR from SABR use the sequence:

CPAGE n
6212
JMS 7 7^?^
REQUEST
ARGUMENTS
ERROR RETURN

/N=7+(# OF ARGUMENTS)
/CIF lJ2f
/OR 2)2f0 IF USR IN CORE

/OPTIONAL DEPENDING ON REQUEST
/OPTIONAL DEPENDING ON REQUEST

To call a device handler from SABR use the sequence;
/l)2f IF "HAND" IN PAGE j?
CPAGE 12
/CIF
62p(2
/DO NOT USE JMS
JMS I HAND
FUNCT

ADDR
BLOCK
ERROR RETURN
SKP
HAND,

/"HAND" MUST BE ON SAME PAGE
/AS CALL, OR IN PAGE 01

D-18

APPENDIX E

CHARACTER CODES AND CONVENTIONS

Table E-1 contains a list of the control characters used by
PS/8 and associated system programs.
Table E-2 contains
the PS/8 character set, which is a subset of the complete

ASCII code, the unlisted codes are generally not used by
PS/8 or the system programs.
Note the following:
a.

On some terminals, the character back-

arrow

{<-)

is replaced by an underline

character, and the up- arrow
replaced by circumflex (^)
(_)

(+)

Some terminals use parity codes rather

than forcing the leading bit of the 8-

bit character code to be a

To avoid

problems, PS/8 system programs always

ignore the parity bit during ASCII input.
c.

PS/8 does not handle lower case characters (octal codes 341 through 372)

E-1

Table E-1
PS/8 Control Characters

Octal
8-bit
Code

200

Character
Name

Remarks

null

Ignored in ASCII input.

leader /trailer

Leader /trailer code precedes and
follows the data portion of binaryfiles.

2j2f3

CTRL/C

PS/8 break character, forces return to Keyboard Monitor, echoed
as fC.

2J37

BELL

CTRL/G.

211

TAB

CTRL/I

212

LINE FEED

Used as a control character by
the Command Decoder and ODT.

213

CTRL/K, vertical tabulation.

214

FORM

CTRL/L, form feed.

215

RETURN

Carriage return, generally echoed
as carriage return followed by a
line feed.

217

CTRL/0

Break Character, used conventionally
to suppress Teletype output, echoed

horizontal tabulation.

as to.

225

Delete current input line, echoed

CTRL/U

as fU.

232

End-of-File character for all ASCII
and binary files (in relocatable
binary files CTRL/Z is not a terminator if it occurs before the
trailer code)

CTRL/Z

E-2

Table E-1
PS/8 Control Characters

Octal
8-bit
Code

Character
Name

233

ESC

Remarks

Escape replaces ALTMODE on some termiConsidered equivalent to ALTMODE,

nals.
375

ALTMODE

Special break character for Teletype
input.

376

PREFIX

PREFIX replaces ALTMODE on some terminals.
Considered equivalent to ALTMODE,

377

RUBOUT

Key is labeled DELETE on some terminals,
Deletes the previous character typed.

E-3

Table E-2
ASCII Character Codes

Octal
8-bit
Code
24/3

241
242
243
244
245
246
247

25)3

251
252
253
254
255
256
257

26(?

261
262
263
264
265
266
267

270
271
272
273
274
275
276
277

300
301
302
303
304
305
306
307

Character
Representation

Punched
6-bit
Code

Card,^.

40
41
42
43
44
45
46

blank
11-8-2

50
51
52
53
54
55
56
57

60
61
62
63

Code^-^'

space (non-printing)
exclamation point
quotation marks
niimber sign (1^)
dollar sign
percent
ampersand
apostrophe or acute
accent

!
II

8-7
8-3

11-8-3
0-8-4

$
%

12
8-5

&
1

12-8-5
11-8-5
11-8-4
12-8-6
0-8-3

12-8-3
0-1

1
2

3
4
5
6
7

70
71
72
73
74
75

8
9

76
77

0-8-6
0-8-7

64
65
66
67

00
01
02
03
04
05
06
07

Remarks

opening parenthesis
closing parenthesis
asterisk
plus
comma
minus sign or hyphen
period or decimal point
slash

8-2

11-8-6
12-8-4
8-6
>

8-4

12-1
12-2
12-3
12-4
12-5
12-6
12-7

A
B
C

D
E-

F
G

E-4

colon
semicolon
less than
equals
greater than
question mark
at sign

Table E-2 (Cont'd)
ASCII Character Codes
Octal
8-bit
Code

31j3

311
312
313
314
315
316
317

12-8
12-9
11-1
11-2
11-3
11-4
11-5
11-6

10
11
12
13
14
15
16
17

320
321
322
323
324
325
326
327

20
21
22
23
24
25
26

330
331
332
333
334
335
336
337

Character
Representation

Punched
Card
Code (1)

6-bit
Code

H
I

J
K
L

M
N

11-7
11-8
11-9
0-2

Q
R
S

T
U

0-4
0-5
0-6

V
W

0-7
0-8
^"^
(5)
12-8-2;^'
11-8-7^^^
0-8-2
12-8-7^/'

31
32
33

34
35
36
37

Remarks

X
Y
Z
[

]

0-8-5^-^'

opening bracket, SHIFT/K
backslash, SHIFT/l(8)
closing bracket, SHIFT/M
circumflex (?) „>
'
underline

Footnotes
These are the DEC029 standard card codes.
On most DEC Teletypes circumflex is replaced by up-arrow (t).
A card containing 0-8-5 in column 1 with all remaining columns
blank is an end-of-file card.
On most DEC Teletypes underline is replaced by backarrow ("*")
(4)
On some IBM 029 keyboards this character is graphically repre(5)
sented as a cent sign (*).
On some IBM 029 keyboards this character is graphically repre(6)
sented as logical NOT (-.)
On some IBM 029 keyboards this character is graphically repre(7)
sented as vertical bar (|
o
On a very few LP08 line printers, the character diamond
(8)
is printed instead of backslash.
is
o
On a very few LP08 line printers, the character heart
(9)
printed instead of underline.
(10) The character number sign on some terminals is replaced by
pound sign
£

(1)
(2)
(3)

•

)

(

)

E-5

)

APPENDIX F
DOCUMENTATION UPDATE FOR THE
8K PROGRAMMING SYSTEM USER'S GUIDE

This appendix contains two sections on new PS/8 system programs:
PS/8 CREF, a cross reference listing program, and
LIB SET, a new program for building a library of FORTRAN subroutines
.

F.l

CREF, Cross-Reference Program (DEC-P8-YRXA-PB)

CREF is a PS/8 program which aids the programmer in writing,
debugging and maintaining assembly language programs.
CREF

provides the ability to pinpoint all references to a particular symbol in assembly language programs.
CREF operates on
output from either the PALS or SABR assemblers.
F.1.1

Loading, Calling, and Using CREF

In order to- load CREF, place the CREF binary tape
YRXA-PB) into the reader and load as follows:

(DEC-P8-

.R ABSLDR

*PTR:/9$

where the $ character indicates typing of the ALT MODE key.
When the f character is printed, type any keyboard character
to initiate reading the paper tape.
When reading is completed.
Keyboard Monitor responds with another dot. Type:
-SAVE SYS: CREF

and CREF is saved on the system device.

F-1

To call CREF from the system device, type:
•R CREF

The Comis the Keyboard Monitor active signal.
where the
mand Decoder is then loaded and replies with a star at the
left margin. The user then enters one output file specification and one input file specification.
.

NOTE
The input to CREF must be the listing pass
If this is
output from either assembler.
properoperate
not
will
CREF
case,
the
not
ly.

If no output file is specified, CREF assumes the output is to
If no input file extension is
be sent to the line printer.

If no input specispecified, the extension .LS is assumed.
fication is given, control returns to the Command Decoder until an input file is specified.

An example of calling CREF is shown below:
.R CREF
*PTEMP

The Command Decoder prints *, CREF assigns LPT: as the output
If the file PTENIP.LS
The input file is DSK:PTEMP.LS.
device.
is not found, a search for DSK:PTEMP is attempted.

Options which can be
No output file extensions are appended.
specified to CREF are described in Table F-1.
TABLE F-1
CREF OPTIONS

Meaning

Option Code
/X

For programs with too
many symbols and literals for CREF, this option
may create enough space for CREF to operate.
Do not process literals.

F-2

Option Code

Meaning

Interpret input as SABR code. Signal to CREF
to accept special SABR characters.
Also, if
R is used, /X is forced on.

Disables pass one listing output. The output
is re-enabled when $ (or END if SABR code) is
encountered.
Thus the $ (END) and symbol table
are printed if /P is used.

Examples of calling CREF are shown below.
.R CREF
*SBRLS/R

The line to the Command Decoder causes output to be sent to the
line printer.

The input is expected to be a SABR listing file

named SBRLS.LS or SBRLS from device DSK:.
.R CREF
*DTA1:LIST< DTA3 :PALIST/X

The above line to the Command Decoder causes output to be sent
to DECtape unit 1, to a file named LIST.
Input is expected to
be a PALS listing file called PALIST.LS or PALIST.

No literals

appear in the CREF output table.

F.1.2

Interpreting CREF Output

The output from CREF consists of two parts.

On the first pass

through the input file, CREF generates a sequence numbered listing of the file. The sequence numbers are decimal.
/P disables
this part of the output.
Following the listing, the cross reference table appears. This
table contains every user defined symbol and literal sorted
alphabetically.
For each symbol, there appears a list of numbers specifying the lines in which that symbol is referenced.

F-3

If CREF finds too many references to fit in core at one time,

multiple passes are required to process all symbols. The minimum number of passes is two. The maximum depends on two things:
a.

Size of the input file, and
Amount of core available

CREF calculates the number of core fields available and uses
If enough core is
all available space for reference tables.
not available, three or more passes are required.
For example, the current PS/8 SABR assembler (5518 source lines,
849 symbols) requires a total of four passes through CREF on
an 8K machine.

1
2
3
4
5
6
7
8
9

10
11
12
13
14
15
16
17
18

0200
0200
)2f2/2ll
|2f2)2(2

02/2(3

0204
J2f205
J2f2j3f6

J0207
i2(21i2f

0211
j2(212

0213
0377

1211
3212
7001
7104
2212
5203
3213
1377
7402
7400
0000
0000
7777

PAGE

PAL8-V6

/EXAMPLE CREF OUTPUT

/EXAMPIjE CREF out:
*200
/THIS IS WHAT TYP;

Al,
COUNT,
F2,

TAD Al
DCA COUNT
lAC
CLL RAL
ISZ COUNT
JMP .-2
DCA F2
TAD (7777
HLT
-400

/SET COUNTER

(FORM FEED)

PAL8-V6

/EXAMPLE CREF OUTPUT
Al
COUNT
F2

0211
0212
0213

Al
COUNT
F2

L0377

5
6

11
12

(FORM FEED)
14#
9
15#
16#
F-4

PAGE 1-1

Form feeds on the Teletype are converted to a series of carriage
return/line feeds and a dotted tear line. Notice that in the
CREF table the line where the symlsol is defined is followed by
Symbols defined by OPDEF or SKPDF in SABR and all literals
a #.
do not have a

F.1.3

following them.

CREF Pseudo-Ops

CREF recognizes the pseudo-ops of the assembler whose output it
Certain pseudo-ops cause CREF to perform actions
is processing.

similar to those taken by the assembler.

Action Taken by CREF

PAL8 Pseudo-Op

EXPUNGE

CREF purges its current symbol table of all
If any
permanent and user defined symbols.
literals were in the table they are not deleted.

FIXTAB

Causes all symbols (except literals) to be
marked as permanent symbols. After a FIXTAB,
no references to previously defined symbols
will be reported by CREF.

TEXT

Ignores characters between delimiters.

End of input signal.

A ction Taken by CREF

SABR Pseudo-Op
END

End of input signal.

OPDEF

Creates a new permanent symbol, a non-skip
type instruction.

SKPDF

Creates a new permanent symbol, a skip-type
instruction.

NOTE
Symbols entered by OPDEF and SKPDF are
processed by CREF. All references to
Howthese defined symbols are listed.
definiis
flagged
as
a
ever, no reference
followed
by
is
tion (i.e. no reference
in
the
CREF
listing)
a #
,

TEXT

Ignore characters between delimiters.

F-5

Restrictions

F.1.4

CREF has the following restrictions:
a.

—

CREF can only detect errors of a
Input format
If the input is
simple form (described below)
neither a PALS or SABR listing file, the results
of CREF are unpredictable in the cross reference
table.
.

CREF can handle a maximum of 896 (decimal) symbols,,
In 8K, PALS is limited to 89 7 symbols while SABR
If more than
is limited to fewer than 800 symbols.
896 symbols are found, an error message is generated.

If any symbol in the input file has more than 2044
(decimal) references, an error message is generated.

If more than 8192

If the /X option is used in PALS (to generate a DDT
compatible symbol table) and the output listing is
put through CREF, no symbol table listing will appear.

This is a restriction which,
Use of semi-colons
when not observed, could cause errors in the CREF
It is recommended that the user follow
table.
these suggestions when preparing source files to
insure a proper CREF listing.

(decimal) source lines are input,
to 4096, not 0.
numbers
return
sequence

—

Semi-colons should not be used on lines
In particular, a comwith pseudo-ops.
bination such as the following must not
be used:
*3j

TEXT

%ERROR%

;

TAD [42

In this case, CREF does not process the
page zero literal properly. A literal
is generated which is derived from the
expanded TEXT message. No error message
is generated, but the literal table entry
is meaningless.

F-6

When using conditional code a good rule to
observe is to not use semi-colons inside
For example:
conditional code.
EXOR =
IFNZRO EXOR <CLA;TAD B; HLT /ERROR>
/THIS IS THE NEXT LINE PAST IFNZRO
The conditional code is not assembled but
CREF does not realize that and does try to
process the bracketed instructions. As a
result of these semi-colons, extra symbols
may be processed and some valid references
If the code had been assembled,
missed.
however, CREF would operate properly.

There are two solutions to this restriction:

Write straight line code:

EXOR =
IFNZRO EXOR
CLA
TAD B
HLT ERROR

or use XLIST around conditional code, in the
above example:

IFZERO EXOR <XLIST>
IFNZRO EXOR <CLA;TAD B
IFZERO EXOR <XLIST>

;

HLT/ERROR>

XLIST turns off the listing if the code does
not assemble and turns it back on after the
conditional code.
h.

—

There are several output formats that can be
Formats
used in generating a PALS listing file:
/T

Form feeds converted to carriage return/
line feeds

No headings or form feeds generated

DDT compatible symbol table is generated.

For best results with CREF, none of these switches should
This generates a heading and form feeds in the
be used.
CREF automatically converts form feeds to carriage
output.
return/line feeds if output is to the Teletype.
_

F-7

F.1.5

CREF Error Messages

CREF errors are non-recoverable errors, and control returns
to the Keyboard Monitor through 07605 (no core saved)
CBEF
.

is not restartable and typing START results in

NO!

being printed as a reply.

Error Message

Meaning

SYM OVERFLOW

More than 896 (decimal) symbols and literals were encountered.

ENTER FAILED

Entering an output file was unsuccessful,
possibly output was specified to a read
only device.

OUT DEV FULL

The output device is full (directory devices only)

CLOSE FAILED

CLOSE on output file failed.

INPUT ERROR

A read from input device failed.

DEV LPT BAD

The default output device, LPT, cannot be
used as it is not available on this system.

2045 REFS

More than 2044 (decimal) references to one
symbol were made.

HANDLER FAIL

Fatal error on output.
Can occur if either
the system device or the selected input device is write locked.

F-8

F.2

LIBSET (DEC-P8-SYXB-PB)

LIBSET, the FORTRAN Library Setup program, creates a library
of subroutines from the relocatable binary output of SABR.
These library files can be quickly and efficiently scanned by
the Linking Loader saving a great deal of time in loading
How the LOADER uses relocatable
frequently used subroutines.
library files, including automatic loading the LIB8.RL file

and the /L option, is described in the 8K Programming System
User's Guide
.

F.2.1

Loading, Calling, and Using LIBSET

The LIBSET program is available from the Program Library on
In order to load LIBSET,
binary paper tape CDEC-P8-SYXB-PB)
place the binary tape into the reader and load as follows
.

.R ABSLDR
*PTR: = 1260j3$

where the character $ indicates typing of the ALT MODE key.
When the i character is printed, type any keyboard character
When reading is comto initiate reading of the paper tape.
Type:
pleted, the Keyboard Monitor responds with another dot.
.SAVE

SYS: LIB SET

and LIBSET is saved on the system device.
To call LIBSET from the system device, type:
•R LIBSET

F-9

in response to the dot printed by the Keyboard Monitor.

The

Command Decoder then prints a star at the left margin of the
teleprinter paper and waits to receive a line of input. The
general form of input required to build a library file is:
*output<( input file list)
* (additional input f iles)
No more than nine input files are allowed on any one line, but
several input lines can be entered.
The last input line must
end with the user typing the ALT MODE key (which echoes as $)
Only the first line can contain an output file.
If no output
file is specified a file named LIB8.RL is created on the sys-

tem device.

The assumed extension for both input and output

files is .RL.

NOTE
Files output from LIBSET are in a special relocatable library format and must not be copied
with the /B option in PIP. Instead they should
be copied by PIP in image (/I) mode.

TABLE F-2

LIBSET OPTIONS
Option Code

Meaning
The /S option means that all input files on a
line are to be regarded as containing more
than one relocatable binary file.
(This is
analogous to the /S option in ABSLDR.

NOTE
If /S is used on a line that contains no input files, input from PTR: is assumed.

F.2.2

Example

Examples of LIBSET Usage
1

*DTA2iSUBS<DTAl:SUBl,SUB2,SUB3,PTR;
*SYS FUNCl FUNC 2 V5 $
't'

F-10

This example creates a relocatable library file on DTA2 named
SUBS.RL. This library will contain six FORTRAN (or SABR) sub-

routines built by combining the relocatable binary file SUBl.RL,
SUB2.RL, and SUBS.RL from DTAl together with one relocatable
binary paper tape (note the i printed by PS/8 before loading
from PTR:) and the files FUNCl.RL and FUNC2.V5 from the system
device.

Example

* AS IN, ACQS
*/S$ +

Since no output file was specified this example creates a
relocatable library file LIB8.RL on the system device. This
produces a new FORTRAN Library including the subroutines con-

tained in the files ASIN and ACQS on device DSK, and several
subroutines combined on a single paper tape loaded from the

high-speed reader.
F.2.3

Subroutine Names

It is important to distinguish between the PS/8 file name of
a relocatable binary program and its assigned Entry Point Name.

The file name has meaning only to the Command Decoder, the
Entry Point Name (or Names) are the true subroutine names that
are meaningful to the LOADER.

Further details on the format of relocatable binary files and
relocatable library files can be found in Appendix A.
F.2.4

Sequence for Loading Subroutines

LIBSET can combine files in any sequence to form a relocatable
However, the subroutines in any single library
library file.
are loaded by the LOADER in the order in which they were origin-

F-11

ally specified to LIBSET.

Therefore, it is important to

make sure that subroutines are specified in order of size,

with the largest subroutine being loaded first. If this is
not done, cases can occur in which insufficient core is available in any single field to load a large subroutine, whereas
space would have been available if the subroutine had been
loaded earlier.
F.2.5

LIBSET Error Messages

All errors are fatal.

LIBSET recalls the Keyboard Monitor
upon encountering any of the following error conditions.
LIBSET must be rerun in order to try again.

Error Message

Meaning

BAD FORMAT OR CHECKSUM - TRY AGAIN

Error in reading relocatable binary file.

ERROR WHILE WRITING OUTPUT FILE

Fatal output error occurred.

INPUT ERROR

Parity error on input.

LIBRARY DIRECTORY OVERFLOW

Too many subroutines were
specified.
Every subroutine name in the input file
requires four words, and
every relocatable binary
file read requires two words.
If the total number of words
exceeds 250, the library
must be split into two separate files.

F-12

Additional Information
1-4, 1-5, 2-9, D-14
Words,
Alphanumeric options, command
3-3
decoder,
ASCII
character codes, E-4

error messages,
3-3, 3-4
errors,
C-5
example command line,
3-8
input file format,
3-2, 3-3
3-6
input files,
3-3
legal device names,
files,
A-5
3-7
option table,
ASSIGN entry, B-4
output file format,
3-1, 3-2
3-1, 3-10
asterisk symbol (*),
3-5
output files,
Auto-index registers, D-13
special mode,
3-9, 3-10
3-5
tables,
3-3
termination,
Binary files, A-5
3-1
Command line format,
Blocks
1-1
Components, PS/8 system,
1-5
core control,
Conditional assembly of CONFIG, 5-1
1-3
DEC tape,
CONFIG,
D-2
1-3
LINCtape,
5-1
CONFIG. PA source file,
1-3
logical,
5-1
conditional assembly,
1-3
physical,
5-3
device handler code,
1-3
standard size,
5-3
optional device parameters,
5-5
other options,
system device selection, 5-2
Calling
Control characters, E-2 E-3
3-4
command decoder,
Conversion PS/8 DECtapes to PS/12
command decoder special mode, 3-1
LINCtapes,
D-10
F-1
CREF,
5-10
Co-resident handlers,
4-1
device handlers,
Core
USR and device handlers
area, CHAIN,
2-14
from SABR code, D-18
image (.SV format) files, A-6
2-1, 2-3
User Service Routine,
segment doublewords format, A-7
Card Reader handler modificasize PDP-8 computers,
D-7
tion,
D-2
size, subroutine to determine,
D-8
Card Reader (CDR) operations, 4-7
Core control block,
1-5,-6,-7, A-6
Carriage return/line feed supformat,
A-6
pression in FORTRAN, D-5
1-5, 1-6
Job Status Word,
2-2
CDF instructions,
starting address,
1-5, 1-6
CDR,
see Card Reader
CREF, Cross Reference Program,
F-1
2-4, 2-13, 2-14
CHAIN function,
calling and loading, F-1
2-14
core area alteration,
error detection, F-6
2-14
data passing,
error messages, F-8
2-13
monitor error,
examples, F-2, F-3
Character codes and conventions, E-1
formats,
F-7
ASCII,
E-4
options, F-2, F-3
Characters, lower case, E-1
pseudo-ops, F-5
5-10
Checksum errors,
restarting, F-8
2-2
restrictions, F-6
CIF instructions,
Circumflex, E-1
using,
F-1
CLOSE function,
2-3, 2-10, 2-11,
1-1
CTRL/C,
2-12, A-3, D-14
Current directory segment, reCode relocation,
D-9
writing,
D-14
Command decoder subroutine
1-2
3-1, D-2
3-4
calling,
3-1
command line format,
3-1
conventions,
,

X-1

2-2
Data field,
2-14
Data passing, CHAIN,
DATE
1-5
command,
1-5, 2-9
system word,
D-6
system word (FORTRAN)
DEASSIGN corainand, B-4
D-2
DECj2f29 standard card code,
D-2, D-4
DEC026 standard card code,
2-4, 2-12, 2-13,
DECODE function,
,

3-4

2-13
monitor error,
2-13
normal return,
Decoder, Command see Command
decoder subroutine
DECtape to LINCtape conversion, D-10
DECtape
4-7
operations,
5-3
system,
system building, 5-7
1-8
DEVICE pseudo-op,
Device control word table, B-6
4-4
Device dependent operations,
Device handler
adding new,
5-7
call format,
4-2
call sequence,
5-8, 5-9
code,

5-3

editing into CONFIG,
5-12
errors,
5-9
information table format, B-5,-6
loading,
2-5, D-11, D-12
residency table, B-5
standards,
5-9, 5-10
writing,
5-8
1-2
utilization,
4-1
Device handler usage,
4-1, 4-2
calling device handlers,
4-7
card reader,
4-4
device dependent operations,
4-7
file structured devices,
4-5
high-speed paper tape punch,
high-speed paper tape
4-5
reader (PTR)
4-6
line printer,
,

TTY,

5-2
DF32 Disk system,
4-7
operations,
5-5
DIRECT option,
calling
Direct
sequence, USR, 2-2
Directory block
example, A-9
structure, A-1
Directory
entries, A-2
file,
A-1
fragmentation. Asample,
A-4
segment, rewriting current,
D-14
DSK, Default file storage device, D-^

Editing device handlers into
5-12
CONFIG,
1-4, A-2
Empty file,
End-of-file condition, command
3-7
decoder,
D-8
ENPUNCH,
ENTER function, 2-3, 2-8, 2-9, 3-6
D-14
2-9, 2-10
error return,
2-9
normal return,
ERROR function, 2-4, 2-14
Error messages
3-3, 3-4
command decoder,
CREF,
F-8
LIBSET, F-12
2-15
Monitor,
summary,
C-1
Error return
2-11, 2-12
CLOSE,
4-3
device handler,
2-9
ENTER,
2-6
FETCH,
2-18
INQUIRE,
2-7, 2-8
LOOKUP,
Errors
5-10
checksum,
command decoder, C-5
CREF,

F-6

keyboard monitor,
5-10
parity,

4-4

Device length table, B-7
5-3
Device parameters, optional,
1-3
structured,
file
Devices,
Device names, B-4
assumed,
D-2
3-3
command decoder,
1-7, 1-8
and numbers,
5-13
selection,

USR,

C-4

C-2

Example
3-8
command line,
5-6
reconfiguration,
1-1
system,
Exit,
Extensions, file names and,

X-2

1-2

Information words, additional, 1-4,

FETCH conunand,
D-11
2-3,-4,-5,-6, 4-1
FETCH function,
File
formats,
Anumber, A-3, A-4
size,
A-3, A-4
starting block, A-3
1-2
Files,
ASCII, A-5
core image (.SV format), A-6
data format,
1-2
directories,
1-4
empty,
1-3, Amultiple input, D-11
names and extensions,
1-2
permanent,
1-4, A-2
relocatable FORTRAN library. Asystem device (SYS:),
1-3
1-4, A-3
tentative,

1-5

Input file format, command
3-2, 3-3
decoder,
3-6
format,
3-7
Input tables, command decoder,
3-10
special mode,
2-4, 2-17, 2-18
INQUIRE function,
2-2
Instruction field,
Job Status Word,
format, A-6

Keyboard monitor,
1-1
calling,
errors,
C-4

1-6

1-1

1-3

types,

1-8
FILENAME pseudo-op,
1-3
File structured devices,
File structured devices operation

4-8

4-7,

LAP (Leave Automatic Paging
D-16
pseudo-op)
Layout of resident program, B-2
Layout of system, B-1
LIBSET, FORTRAN Library Setup
Program, F-9
calling, F-9
F-10
copying LIBSET files,
error messages, F-12
examples,
F-10, F-11
loading, F-9
loading sequence, F-11
options, F-10
subroutine names, F-11
F-9
using,

File structures, A-1
ASCII, A-5
binary
A-5
directories, A-1
formats,
A-5
relocatable FORTRAN library. AFormats
command decoder option table, 3-7
CREF,
F-7
1-2
file data,
FORTRAN
carriage return/line feed supD-5
pression,
8K,
D-12
library file, relocatable, A-8
Library Setup program, F-9
program system date, D-6
5-4
run time I/O routines,
,

Halt
LOADER program, C-2
system,
C-1, C-2
High speed paper tape punch (PTP)
4-5, 4-6
operation,
High speed paper tape reader
4-5
(PTR) operation,

Indirect calling seauence USR, 2-2

X-3

5-2, 5-3
LINCSYS,
LINCtape
5-4
handlers,
4-7
operation,
5-7
system building,
4-6
Line printer (LPT) operation,
LOADER program halt, C-2
Loader control words, A-8, A-9
Loading
F-1
CREF,
D-11
device handlers,
D-12
device handlers dynamically,
Logical end-of-file, device
4-3
handler,
2-3, 2-7, D-14
LOOKUP function,
Lower case characters, E-1
5-4
Low-speed paper tape,
5-4
type
645,
printer,
LP12 line

1-6
1-6
format,
1-6
START command,
program,
D-10
PRTC12-F
Pseudo-ops, CREF
PAL8, F-5
SABR, F-5
PTP see High-speed paper tape

Program starting address,

Masking,
1-2, 4-1
Maximum number of files, A-4
Maximum size of file, A-4
Monitor error,
2-13
CHAIN,
2-13
CLOSE,
2-15
ERROR,
Multiple input files, D-11

punch
see High-speed paper tape
reader
PUNCH feature, D-9

PTR
Names
device,

1-7, 1-8, B-4
1-8
Normal return,
2-11
CLOSE,
2-9
ENTER,
2-6
FETCH,
INQUIRE,
2-17, 2-18
2-7
LOOKUP,
2-19
RESET,
3-3
Null files,
Number and size of file, A-3
1-7, 1-8
Numbers, device,
Number symbol (#) , F-5
Niomeric options, command
3-3
decoder,

file,

2-14
ODT breakpoint, CHAIN,
D-13
ODT breakpoint usage,
Operating command decoder in
3-10
special mode,
Optional device parameters
5-3
CONFIG,
Options command line
3-3
alphanumeric,
3-3
numeric,
Option tables, command decoder, 3-7
3-10
special mode,
Output files, command decoder, 3-5
3-1, 3-2
format,
Output table, command decoder
3-10
in special mode,
,

D-16
PAGE pseudo-op,
F-5
PAL8, CREF pseudo-ops,
Parity
E-1
codes,
4-3
error, device handler,
5-10
errors,
5-2
PDP-12 LINCtape system,
Permanent device name table, B-3
1-4, 2-10, A-2
Permanent file,
Permanent file entry, 2-7

X-4

R command. A4-1
Record, definition of,
4-1
Record transfer,
5-1
Reconfiguration,
5-7
adding new device handlers,
building system on DECtcipe or
5-7
LINCtape,
editing device handlers into
5-12
CONFIG,
5-6
example,
writing device handlers, 5-8
Relocating code, D-9
2-4, 2-18, 2-19
RESET function,
deleting tentative files, 2-19
2-19
normal return,
Resident program layout, B-2
Restarting CREF, F-8
Restrictions
command decoder in special
3-10
mode,
4-3
device handlers,
2-2
USR calls,
Rewriting current directo3:y segment,
D-14
5-2
RF)2f8 disk system,
4-7
operations,
5-2
RK8 disk system,
4-7
operations,
RUN command. A(compress device) option,
SABR
/S

D-16
code,
code, calling USR and device

handlers, D-18
CREF pseudo-ops, F-5
programming notes, D-16
Sample directory, A-4
1-5, 1-6
SAVE command,
Segment header, A-1

B-8

Semicolons, CREF, F-6, F-7
Special mode of the command de-

5-5
f
Up arrow character
User device name tables, B-4, B-5
1-2
USR (User Service Routine)
D-13
area storage space,
2-1
calling,
2-2
direct calling,
ERROR,
C-3
2-3
function summary,
2-2
indirect calling,
2-2
restrictions,
USRIN function, 2-3, 2-4, 2-15, 2-16
2-4, 2-14, 2-16
USROUT function,
(

3-9, 3-10
coder,
START command,
1-6, 1-7
Storage space USR area,
D-13
.SV (core image)

file,

1-5, A-6

Subroutine to determine core
size,
D-8
2-3
Summary USR functions,
2-13
CHAIN,
2-10
CLOSE,
2-12
DECODE,
2-8
ENTER,
2-14
ERROR,
2-4
FETCH,
2-17
INQUIRE,
2-7
LOOKUP,
2-18
RESET,
2-15
USRIN,
2-16
USROUT,
Syntax error, command line,
SYS,

Write lock error, device handler,
4-3

/X option, CREF (PALS)
3-3

D-2

System
building on DECtape or LINC5-7
tape,
DATE,
1-5, 2-9
1-5
Date word,
Date word, FORTRAN,
D-6
device selection, CONFIG,
1-3
device (SYS:),
device tables, B-3
1-1
exit,
B-1
layout,
B-1, B-2
scratch blocks
1-1
software components

)

5-2

Tables
permanent device name, B-3, B-4
system device, B-3
user device name, B-4, B-5
5-11
Table lookup example,
4-4, 4-5
Teletype (TTY) operation,
Tentative file,
1-4, 2-10, A-3
2-19
deletion,
2-8
entry,
3-3
Termination, command decoder,
1-1
Terminology,
TTY see Teletype

X-5

F-6

Digital

Equipment Corporation

IVIaynard, IVIassachusetts

printed in U.S.A.

PIIIHIinilll

EIDSuDull