Digital PDFs

DEC-S8-OSSMB-A-D

December 1974

127 pages

Original

3.0MB

Document:	OS8 v3ssup
Order Number:	DEC-S8-OSSMB-A-D
Revision:
Pages:	127
Original Filename:	https://svn.so-much-stuff.com/svn/trunk/pdp8/src/dec/dec-s8-ossmb/dec-s8-ossmb-a-d.pdf

OCR Text

mmsm

soFtuuare

support manual

digital equipment corporatbn

OS/8 SOFTWARE SUPPORT MANUAL

(Version

DEC-S8-0SSMB-A-D

Order additional copies as.- directed on the Software
Information page at the back of this document.

digital equipment corporation • maynard. massaclnusetts

First Printing, January 1973
Revised, June 1974

The information in this document is subject to change without notice
and should not be construed as a coiranitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this manual.

The software described in this docximent is furnished to the purchaser
under a license for use on a single computer system and can be copied
(with inclusion of DIGITAL'S copyright notice) only for use in such
system, except as may otherwise be provided in writing by DIGITAL.

Digital Equipment Corporation assumes no responsibility for the use
or reliability of its software on equipment that is not supplied by
DIGITAL.

The HOW TO OBTAIN SOFTWARE INFORMATION page, located at the back of
this document, explains the various services available to DIGITAL
software users.
The postage prepaid READER'S COMMENTS form on the last page of this
dociiment requests the user s critical evaluation to assist us in
preparing future documentation.
'

The following are trademarks of Digital Equipment Corporation:
CDP
COMPUTER LAB
COMSYST
COMTEK
DDT
DEC
DECCOMM
DECTAPE
DIBOL

DIGITAL
DNC
EDGRIN
EDUSYSTEM
FLIP CHIP
FOCAL
GLC-8
IDAC
IDACS

INDAC
KAIO
LAB-8
LAB-8/e
LAB-K
OMNIBUS
OS/8
PDP
PHA

PS/8

QUICKPOINT
RAD-8
RSTS
RSX
RTM
RT-11
SABR
TYPESET 8
UNIBUS

PREFACE

(OS/8)
an extremely powerful program
is
The 8K Operating System
OS/8 greatly expands the capabilities of any 8K
development system.
PDF- 8, 8/1, 8/L, 8/E, or PDP-12 computer having the necessary disk or
is described in detail in the OS/8
Use of OS/8,
DECtape storage.
HANDBOOK (DEC-S8-0SHBA-A-D)

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 are 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
Chapter 4 explains the use and
program can employ its services.
Chapter 5 covers the
operation of the device handlers in detail.
details of "custom tailoring" a system, including how to write a
device hemdler for a non-standard device.

HANDBOOK, as well as this manual, can be found in the Appendices.
Appendix A details the OS/8 directory structure and gives standard
file format. Appendix B describes the system data base and gives the
layouts of the system areas. Appendix C gives a complete list of
Appendix D illustrates some useful advanced
system error messages.
techniques and programming "tricks" for use with the OS/8 system.
Appendix E is a complete list of the standard ASCII character codes
meaningful to OS/8. Finally, Appendix F describes a set of generalized
T /n

^^^^%^4' A r>£\t*

f^^>**

iic?^

iTMr^ci**

4-Kja

OC /Q

cfxtm^tstm

111

zy,Ti

i-age

CHAPTER 1
1.1

OS/8 CONCEPTS A^ID TERMINOLOGY

1-1

SOFTWARE COMPONENTS OF OS/8

1-1
1

»^

irlljiii!

File Names and Extensions
File Structured Devices
File Types
File Directories and Additional
Information Words

1-2
1-2
1-3

CORE CONTROL BLOCK
Program Starting Address
Job Status Word
Software Core Size

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

DEVICE NAMES AND DEVICE NUMBERS

1-6

1.5

THE DEVICE AND FILENAME PSEUDO-OPS

1-7

USER SERVICE ROUTINE

2-1

2 .1

CALLING THE USR
Standard USR Call
Direct and Indirect Calling Sequence

2-1
2-1
2-2

SUMMARY OF USR FUNCTIONS
FETCH Device Handler
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 (INQUIRE)
RESET System Tables

2-3
2-4
2-5
2-6
2-8
2-9
2-10
2-11
2-12
2-12
2-13
2-14

THE COMMAND DECODER

3-1

3.,1

COMMAND DECODER CONVENTION

3-1

3.2

COMMAND DECODER ERROR MESSAGES

3-3

3.3

CALLING THE COMMAND DECODER

3-3

3.4

COMMAND DECODER TABLES
Output Files
Input Files
Command Decoder Option Table
Example

3-4
3-4
3-5
3-6
3-7

1.3
1.3,
1.3,
1.3,

CHAPTER

2,.1,.1

2,.1,.2

2,.2
2,.2..1

2,.2..2
2,.2..3
2,.2..4
2.,2.,5
2..2..6

2..2.,7
2..2.,8

2.,2.,9
2..2.,10

2.,2.,11

CHAPTER 3

3.4.1
3.4.2
3.4.3
3.4.4

1-3

Page

3.5
3.5.1
3.5.2

SPECIAL MODE OF THE COMMAND DECODER
Calling the Command Decoder Special Mode
Operation of the Command Decoder in Special
Mode

3-8
3-9

3.6

CCL AND THE COMMAND DECODER

3-10

3.7

USEFUL LOCATIONS IN BATCH

3-10

3.8

CCL TABLES

3-10

USING DEVICE HANDLERS

4-1

4.1

CALLING DEVICE HANDLERS

4-1

4.2
4.2.1
4.2.2
4.2.3
4.2.4
4.2.5
4.2.6
4.2.7
4.2.8
4.2.9
4.2.10

DEVICE DEPENDENT OPERATIONS
Teletype (TTY)
High-Speed Paper Tape Reader (PTR)
High-Speed Paper Tape Punch (PTP)
Line Printer (LPT)
Cassettes
Card Reader (CDR)
TM8E Handler
File Structured Devices
TD8E DEC tape
KL8E Teletype Handler

4-4
4-4
4-4
4-5
4-5
4-6
4-7
4-8
4-11
4-11
4-12

RECONFIGURING THE OS/8 SYSTEM

5-1

5.1

WRITING DEVICE HANDLERS

5-1

5.2

INSERTING DEVICE HANDLERS INTO OS/8

5-5

OS/8 FILE STRUCTURES

A-1

A. 1.1
A. 1.2
A. 1.3

FILE DIRECTORIES
Directory Entries
Number and Size of OS/8 Files
Sample Directory

A-1
A-2
A-3
A-3

A.
A. 2.1
A. 2.
A. 2.

FILE FORMATS
ASCII and Binary Files
Core Image (.SV format) Files
Relocatable FORTRAN Library File

A-4
A-4
A-5
A-7

DETAILED LAYOUT OF THE SYSTEM

B-1

B.l

LAYOUT OF THE SYSTEM DEVICE

B-1

B.2

LAYOUT OF THE OS/8 RESIDENT PROGRAM

B-2

B.3
B.3.1
B.3.
B.3.
B.3.
B.3.
B.3.

SYSTEM DEVICE TABLES
Permanent Device Name Table
User Device Name Table
Device Handler Residency Table
Device Handler Information Table
Device Control Word Table
Device Length Table

B-4
B-4
B-4
B-5
B-5
B-6
B-7

CHAPTER 4

4.2.2

CHAPTER 5

APPENDIX A
A.l

APPENDIX B

3-9

Page

APPENDIX C

SYSTEM ERROR CONDITIONS AND MESSACjjES

C.l

SYSTEM HALTS

C-1

C-2

USR ERRORS

C-2

C.3

KEYBOARD MONITOR ERRORS

C.4

CCL ERROR MESSAGES

C-4

C.5

COMMAND DECODER ERRORS

C-7

PROGRAMMING NOTES

D-1

D.l

THE DEFAULT FILE STORAGE DEVICE, DSK

D-1

D.2

MODIFICATION TO CARD READER HANDLER

D-2

D.3

SUPPRESSION OF CARRIAGE RETURN/LINE FEED
IN FORTRAN

D-4

ACCESSING THE SYSTEM DATE IN A FORTRAN
PROGRAM

D-4

DETERMINING CORE SIZE ON PDP-8 FAMILY
COMPUTERS

D-5

USING PRTC12-F TO CONVERT OS/8 DECTAPES
TO OS/12 LINCTAPES

D-6

D.7.

NOTES ON LOADING DEVICE HANDLERS
Problem with Multiple Input Files
Dynamically Loading Device Handlers

D-7
D-7
D-7

D.8

AVAILABLE LOCATIONS IN THE USR AREA

D-S

D.9

ACCESSING ADDITIONAL INFORMATION WORDS

D..9.1
D,.9.2

After a LOOKUP or ENTER
After a CLOSE
Rewriting the Current Directory Segment

APPENDIX D

D.4

D.5

D.6

D.7
D.7.1

IN OS/8

D,.9.3
D,.10
D..10.1
D.,10.2

SABR PROGRAMMING NOTES
Optimizing SABR Code
Calling the USR and Device Handler
SABR Code

D-9
D-9
D-9
D-9

D-10
D-10
'

from

D-12

APPENDIX E

CHARACTER CODES AND CONVENTIONS

E-1

APPENDIX F

OS/8 INPUT/OUTPUT ROUTINES

F-1

F.,1

GENERAL DESCRIPTION

F-1

F. 2

SUBROUTINE FUNCTIONS

F-1

F. 3
F. 3.1
F. 3.2

SUBROUTINE PARAMETERS
Example
Subroutine Listing

F-3
F-3
F-5

Vll

CHAPTER 1
OS/8 CONCEPTS AND TERMINOLOGY

Before examining the details of the OS/8 system, the reader should
first be familiar with the simpler techniques and terms used within
The material in this chapter, along
the freimework of the OS/8 system.
with that contained in the OS/8 HANDBOOK, provides the tools needed to
pursue the later chapters.

1.1

SOFTWARE COMPONENTS OF OS/8

There are four main components of the OS/8 system:
1.

The Keyboard Monitor performs commands specified by the user
at the keyboard console.
The nine Keyboard Monitor commands
(ASSIGN, DEASSIGN, GET, SAVE, ODT, RUN, R, START,
and DATE)
are explained in Chapter 1 of the OS/8 HANDBOOK.

User programs can exit to the Keyboard Monitor by executing a
to location 7600 in field 0. All JMPs to 7600 must be
made with the DATA FIELD set to zero.
This saves the
contents of locations 0000 to 1777 in field
cuid 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*
•IMP

Existing system programs, device handlers, and the Command
Decoder test for the CTRL/C character in the terminal 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.
2.

Device hemdlers, which are subroutines for performing all
device-oriented input/output operations , can be utilized by
any program.
These subroutines have
standard
calling
sequences and "mask"
from the user program the special
characteristics of the I/O device.
device
In
this way,
independent I/O is achieved.
A detailed description of
device handlers is found in Chapter 4.

The User Service Routine (USR)
is
to a program what the
Keyboard Monitor is to the user. For example, progreims can
request the USR to fetch device handlers, perform file
operations on any device, chain to another program, or call
the Command Decoder.
A full description of the USR functions
is found in Chapter 2.

1-1

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 1
The Command Decoder removes the burden
of the OS/8 HANDBCX3K.
of this repetitive operation from the user's program, A full
description of the Command Decoder's function is found in

Chapter
5.

1.2

Two other components, ABSLDR and ODT, are not logically part
However, in the sources and listings,
of the OS/8 system.
ABSLDR is combined with the Keyboard Monitor and USR. ODT is
combined with the command decoder.

FILES

Files are basic units of the OS/8 system, and a thorough understanding
of file structure is required for its use. A file is any collection
The format of this data is
of data to be treated as a unit.
can manipulate several standard
for example, OS/8
unimportant;
formats, including ASCII files, binary files, and core image files.
The important consideration is that the data forms a single unit
within the system.

1.2.1

File Names and Extensions

The
An individual file is identified by its file name and extension.
optionally
characters,
alphanumeric
six
up
to
consists
of
name
file
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.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
file
are
Disks and DECtapes
called file structured devices.
structured devices while a paper tape reader or terminal is not.

Cassettes and magnetic tapes form an intermediate case. They may be
treated directly as non-file structured devices, or the program MCPIP
may appear to be file structured.
The system device (SYS) in any OS/8 system is always file
as is the default storage device, DSK.

structured,

All OS/8 file structured devices must be logically divided into these
256 words is considered the st«uidard OS/8
Hence,
256-word blocks.
block size. Some devices, like RK8, DECtape, 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 OS/8

1-2

block consists of the first 128 words of two consecutive physical
DECtape blocks. The 129th word of every DECtape block is not used by
words per
OS/8. Similarly, LINCtapes are formatted with 129 (or 128)
block but never 255, as this format is unacceptable to OS/8.
A i-T-iTron DC: /fl fi To con e i c c of fin*» irr mri]-p»
cprtiien-t-i a.1
hlQclfs
of ^Rfi
(consecutively numbered) . A minimum of one block per file
words each
on
is required, although a single file could occupy all of the blocks
a device.
<-

File Types

1.2.3

Three different types of files exist in the OS/8 system:
1.

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

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.

Empty

To further understand file types, consider what occurs when a file is
Normally, the User Service Routine, in creating a tentative
created.
file, first locates the largest empty file available and creates a
i.i«jus estabxxshes ^hQ maxxmum space xnto
usn^auive j.a.a.e xn ui^au space.
which the file can expand. The user progreim then writes data into the
tentative file. At the end of the data, the program calls the USR to
close the tentative file, making it a permanent file. The USR does so
and allocates whatever space remains on the end of the tentative file
to a new, smaller, empty file.

Tr'4T«.

n^«-^«^4>«>*--««K0

-ai-ttf^

^j^^i

To maintain records of the files on a device, OS/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 files and the tentative
For a detailed description of the entries in the
file, if one exists.
file directory, see Appendix A.
Each entry in a directory can, optionally, have extra storage words
Additional Information Words.
called
The number of Additional
Information Words is determined at the time the directory is initially
(normally by using the /S or /Z features of PIP;
created
see Chapter
1 of the OS/8 HANDBOOK.

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. OS/8 automatically uses one extra word per
entry for the date.
This value is set by executing a DATE command

1-3

(see Chapter 1 of the OS/8 HANDBOOK) which codes the current date into
memory location 07666 in the following format:

J2f

MONTH

DAY
(l-37„)

(l-14g)

YEAR-19 70
(0-7)

implies that no DATE command has been executed
A date word of
the system initialization.

since

The values of Additional Information Words beyond the first are
See Appendix D for further information on Additional
user-defined.
Information Words.

1,3

CORE CONTROL BLOCK

a block of data
is
Associated with each core image file (SV file)
Block
Control
is a table of
The
Core
Block.
Control
Core
the
called
information containing the program's starting address , areas of core
into which the program is loaded, euid the program's Job Status Word.
The Core Control Block is created at the time the program is loaded by
ABSLDR or other means 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. Note that
specifying arguments to the SAVE command as described in Chapter 1 of
the OS/8 HANDBOOK, can alter the contents of the target program's Core
Control Block.

When a program is loaded, the starting address and Job Status Word are
read from the Core Control Block and saved in core. The Core Control
Block itself is saved in the last 200 (octal) words of block 37 on the
system device unless the progreun 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 07744 and 07745. The format of these words is:

NOTES

LOCATION

CONTENTS

07744

62n3

n is the field in
which to start.

07745

nnnn

Starting address of
the program.

1-4

1.3.2

Job Status ivord

affect
OS/8
certain flags that
The Job Status Word contains
loading
the
USR
or
when
save
core
v/hether
to
sucn
as
operations,
The Job Status Word for the program currently in
Command Decoder.
at
location 07746 and contains the following
saved
is
core
information:
Bit Condition

Meaning

Bit

0=1

File does not load into locations

000 00

Bit

1=1

File does not load into locations
to ^1777.

AOOOO

Bit

2=1

Program must be reloaded before
be restarted.

Bit

3=1

Program does not destroy the contents of
the highest existing memory field, an
optimization for the Batch system.

Bits

thru

can

Reserved for future use.

Bit 10 =

Locations 00000 to 01777 need not be
saved when calling the Command Decoder.

Bit 11 =

Locations 10000 to 11777 need
saved when calling the USR.

When bit 2 of the Job Status Word is 1, any attempt to perform
(without an explicit address) results in a

not
a

START

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
This could be
restartable.
(in location 7746) if a program is not
done as follows

CDF
TAD I (7746
AND (6777
TAD (1000
DCA I (7746

/LOAD JOB STATUS WORD
/JOB IS NOT RESTARTABLE

The Job Status Word can be updated from the user's program or with the
ABSLDR /P option, thus providing optimization of tape (disk) motion.
More information on the Core Control Block can be found in the
description of Core Image (SV) files found in Appendix A.

ait 3 of the JSW (Job Status Word) is used as an optimization for the
If a program can never cause the highest
Batch operating system.
For
existing memory field to be altered, this bit should be set.
and SABR can never use memory above 8K.
example, EDIT, PIP, FORT,
Programs such as ABSLDR,
Thus, they should set bit 3 of the JSW.

1-5

They should perhaps not
LOADER, PALS and CREF can alter all of core.
Note that the more core that exists , the more unlikelyhave bit 3 on.
Thus, on 28K systems,
that a program will destroy upper core.
it is
in general,
only the largest FORTRAl^l programs can alter field 6 and,
bit 3 should be set.

1.3.3

Software Core Size

Location 07777 contains the software core size in bits 6-8. This
represents the highest memory field available for use by OS/8. If bits
Most OS/8 cusps
6-8 contain 0, all of the available memory is used.
interrogate this word to determine how much memory is available. The
other bits of this location are reserved for use by BATCH and should
not be touched by user programs.

1.4

DEVICE NAMES AND DEVICE NUMBERS

In Chapter
The OS/8 system can accommodate up to 15 separate devices.
of the OS/8 HANDBOOK the reader is introduced to the concept of
1
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
The system insures that the user-defined device
an ASSIGN command.
name takes precedence. For example,

.ASSIGN DSK DTA4

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 1 to 17 (octal) assigned at the time
Thus, user programs have the choice of
the system is generated.
referring to a device by either name or number. Referencing a device
by name is preferable, as it maintains device independence for the
program.

Accessing devices by number should be done only when the appropriate
number has been obtained from a USR INQUIRE CALL. Except for SYS and
instead, device
DSK, the OS/8 peripherals do not have fixed numbers;
numbers vary whenever BUILD is used to modify a system. Thus, it is
suggested that reference by name be used whenever possible.
To determine whether a device name is recognized in the system,
For example, to determine whether
attempt to ASSIGN that device.
LINCtape handlers are called LTA or DTA, perform:
.

DEASSIGN

.AS LTAO

If the system responds with a dot (.), LTAO does indeed exist.
system responds with:

1-6

If the

LTAO NOT AVAILABLE

no device named LTAO is present.

1.5

THE DEVICE AND FILENAME PSEUDO-OPS

Several of the USR functions take device names or file names as
To simplify the task of generating these arguments, the
argiiments.
DEVICE and FILENAME pseudo-ops have been added to the PALS Assembler.
four
A device name consists of a two word block, containing
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
0161

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:
2011
2000
0000
2326

Note that positions for characters

The DEVICE and FILENAME
following chapters.

pseudo-ops

1-7

through
are

used

are filled with zeros.
in

examples

the

CHAPTER 2
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, program chaining, and calling the Commamd Decoder. The USR
provides these fionctions not only for the system itself, but for all
progreims running under the OS/8 system.

2.1

CALLING THE USR

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

In the remainder of this chapter, the following
referenced

calling

sequence

TAD VAL

The contents of the AC is appliCcUsle
some cases only.

CDF N

Where N is
tirutjj.Guu

GIF 10
JMS I (USR

the

value

J.J.CJ.U iiiuj.L.j.t>JLXBu

of the current
uy J.U vuui.ax; •

Where USR is either 7700 or
section 2.1.2}

0200,

(see

FUNCTION

This word contains an integer from 1 to
13
(octal)
indicating
which
USR
operation is to be performed.

ARG{1)

The number and meaning of these argument
words varies with the particular USR
function to be performed.

error return

When applicable, this
address for all errors.

normal return

The operation was successful. The AC is
cleared and the data field is set to
current field.

2-1

the

return

For
from function to function.
This calling sequence can change
some functions take no value in the AC and others have fewer
example,
this
format
Nonetheless,
is
or greater numbers of arguments.
generally followed.
The value of the data field preceding the JMS to the USR is
The data field MUST be set to the current
exceedingly important.
field, and the instruction field MUST be set to 1. Note that a CDF is
not explicitly required if the data field is already correct. When a
doubt exists as to the data field setting, an explicit CDF should be
executed.

There are three other restrictions which apply to all
follows
1.

USR

calls ,

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

MONITOR ERROR 4 AT xxxxx

10000

(ILLEGAL USR CALL)

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

These
Several USR calls take address pointers as arguments.
pointers always refer to data in the same memory 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.

2.1.2

Direct and Indirect Calling Sequence

A user program can call the USR in two ways. First, by performing a
JMS to location 17700 In this case, 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 the most
When USR operations have been
efficient way of calling the USR.
completed, the program restores locations 10000 to 11777 to their
(see
initial state by executing the USROUT function, if necessary
section 2.2.9)

2-2

2.2

Summary of USR Functions

Function
Code

Name

Operation

Returns
handler.
LOOKUP

the

entry

address

the

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.

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

DECODE

Calls the Command Decoder. The function
of the Command Decoder is described in

Chapter

CHAIN

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

ERROR

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

USRIN

Loads the USR into core.
Subsequent
calls to the USR are by an effective JMS
to location 10200.

USROUT

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

from

core.
13

14-17

RESET

Resets system tables
cleared state.

their

initial

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

An attempt to call the USR with a code greater than 13
(octal)
will
currently cause a Monitor Error 4 message to be printed and the
program to be aborted.

2-3

Function Code -

FETCH Device Handler

2.2.1

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

The FETCH function takes two distinct forms:
1.

Load a device handler corresponding to a given device name.

Load a device handler corresponding to a given device number.

First, the following is an example of loading a handler by
memory field

from

name

CLA
CDF
GIF 10
JMS I (USR

/AC MUST BE CLEAR
/DF = CURRENT FIELD
/IF = 1

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

DEVICE DTA3

/ARG(3)

6001
JMP ERR

/ERROR RETURN
/NORMAL RETURN

If the
is changed to the device number
normal return is taken, ARG(2)
ARC (3) contains the following
corresponding to the device loaded.
information

ARGd) and ARG{2) contain the device name in standeurd format.

to
Bits
loaded.

Bit 11 is
handler.

contain the page number into which the handler is
if the user program

can

only

1-page

Bit 11 is 1 if there is room for a 2-page handler.
Notice that in the example above, the handler for DTA3 is to be loaded
into locations 6000 to 6177. If necessary, a two page handler could be
the second page would be placed in locations 6200 to 6377.
loaded;
return, ARG(3) is changed to contain the entry point of
normal
After a
the handler.

A different set of arguments is used to fetch a device
number. The following is an example of this form:
TAD VAL
CDF
CIF 10
JMS I (USR

/AC IS NOT ZERO
/DF = CURRENT FIELD
IF = 1

/FUNCTION CODE =

6001
JMP ERR

/ARG(l)

/ERROR RETURN
/NORMAL RETURN

2-4

handler

On entry to the USR, the AC contains the device number in bits 8 to 11
to 7 are ignored). The format for ARG(l) is the same as that
{bit
Following a normal return ARG(l)
for ARG(3) in the previous example.
is replaced with the entry point of the handler.
are as follows :
1.

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

.An

attempt was made to load a two "a^e handler into one paQs«
this is an attempt to load the handler by name, the
contents of ARG{2) have been changed already to the internal
device number.
If

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

can

printed,

Meaning

Error Message

MONITOR ERROR 4 AT xxxxx
(ILLEGAL USR CALL)

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

MONITOR ERROR 5 AT xxxxx
(I/O ERROR ON SYS)

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

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

Device handlers are always loaded into memory field 0.

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 xnto the 76G0 page or xnto
page 0. Never load a two page handler into the 7400 page.

For more information on using device handlers, see Chapter 4.

NOTE
more
device
handlers
or
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.

Two
"

2.2.2

Function Code =

LOOKUP Permanent file

This request locates a permanent file entry on a given device, if
exists. An example of a typical LOOKUP would be:

2-5

one

TAD VAL
CDF
GIF 10
JMS

/LOAD DEVICE NUMBER
/DF=CURRENT FIELD
/IF = 1

(USR

/FUNCTION CODE = 2
/ARG(l), POINTS TO FILE NAME
/ARG{2)
/ERROR RETURN
JMP ERR
/NORMAL RETURN
FILENAME PROG. PA
2

NAME

NAME,

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 bit
Note that the
8 to 11. ARG(l) contains a pointer to the file name.
file name block must be in the same memory field as the call, and that
it cannot be in locations 10000 to 11777. The device handler must have
If the normal return is taken,
been previously loaded into core.
ARG(l) is changed to the starting block of the file and ARG(2)
If the
contains the file length in blocks as a negative number.
(for
device specified is a readable, non-file structured device
then ARG(l) and ARG(2) contain the
the papertape reader),
example,
If the device specified
file length in blocks as a negative nxoraber.
is a readable, non-file structured device (for example, the paper tape
reader), then ARG(l) and ARG(2) are both set to zero.
If the error return is taken, ARG(l) and ARG(2)
following conditions cause an error return:

are

The device specified is a write-only device.

The file specified was not found.

specifying illegal argvunents
In addition,
following monitor errors, followed by a
Monitor:

unchanged.

can cause
return to

The

one of the
the Keyboard

Meaning

Error Message

MONITOR ERROR 2 AT xxxxx
(DIRECTORY I/O ERROR)

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

MONITOR ERROR 3 AT XXXXX
(DEVICE HANDLER NOT IN CORE)

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

MONITOR ERROR 4 AT xxxxx
(ILLEGAL USR CALL)

Results if bits
are zero.

the

to 11 of

The LOOKUP function is the standard method of opening a permanent file
for input.

2.2.3

ENTER Output (Tentative) File

Function Code =

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

TAD VAL
CDF
CIF 10

/AC IS NOT ZERO
/DF = CURRENT FIELD
/IF = 1

2-6

JMS

(USR

N'AME

/FUNCTION CODE = 3
/ARG(l) POINTS TO FILE NAME
/ARC 2
/ERROR RETURN
{

JMP ERROR

/MnRMAT. RPTTTTJM

NAME,

FILENAME PROG.LS

Bits 8 to 11 of the AC contain the device niunber of the selected
the device handler for this device must be loaded into core
device;
to 7 of the AC are
If bits
before performing an ENTER function.
non-zero, this value is considered to be a declaration of the maximimi
length of the file. The ENTER function searches the file directory
for the smallest empty file that contains at least the declared number
zero,
the ENTER function
to 7 of the AC are
If bits
of blocks.
locates the largest available empty file.
are replaced with the
On a normal return, the contents of ARG{1)
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
If the file
replaces ARC (2).
greater than the requested length)
directory contains any Additional Information Words, the system DATE
is written as the first Additional Information Word
(location 17666)
of the newly created tentative file at this time.

NOTE

selected device is not file
If the
structured but permits output operations
(e.g., the high speed punch), the ENTER
In this
operation
always succeeds.
case, ARGCl) and ARG(2) are both zeroed
on return.
If the error return is taken, ARG.(l) and ARG(2)
follov;ing conditions cause an error return:
X.

are

unchanged.

me utiviue ^peuxxxeu jjy ijj.t& o tu ij. ui. cuts tw, ±a

The

device.

requested

length

No empty file exists which
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

satisfies

the

(an illegal file name).

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

occur,

followed

Meaning

Error Message

MONITOR ERROR 2 AT xxxxx
(DIRECTORY I/O ERROR)

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

MONITOR ERROR 3 AT XXXXX
(DEVICE HANDLER NOT IN CORE)

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

2-7

Meaning

Error Message

to 11 are

MONITOR ERROR 4 AT xxxxx
(ILLEGAL USR CALL)

Results if AC bits

MONITOR ERROR 5 AT XXXXX
(I/O ERROR ON SYS)

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

MONITOR ERROR 6 AT xxxxx
(DIRECTORY OVERFLOW)

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

Function Code =

The CLOSE Function

2.2.4

zero.

first, it is used to close the
The CLOSE function has a dual purpose:
Second,
making
it a permanent file.
file,
tentative
active
current
when a tentative file becomes permanent it is necessary to remove any
permanent file having the same name; this operation is also performed
by the CLOSE function. An example of CLOSE usage follows:

/GET DEVICE NUMBER
/DF=CURRENT FIELD
/IF=1

TAD VAL
CDF
GIF 10
JMS I (USR
4

NAME
15

JMP ERR

/FUNCTION CODE =

/ARG(l)
/ARG(2)

/ERROR RETURN
/NORMAL RETURN

FILENAME PROG.LS

NAME,

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

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

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.

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

After a normal return from CLOSE, the active tentative file is
permanent and any permanent file having the specified file name
If the specified device is a
already stored on the device is deleted.
non-file structured device that permits output (the paper tape putnch,
for example) the CLOSE function will always succeed.

2-8

;:oTE

The user must be careful to specify the
file names
to the ENTER and the
same
Failure to do so can
CLOSE functions.
several
permanent files with
cause
the
appear
in
identical names to
If CLOSE is intended only to
directory.
be used to delete some existing file,
then the number of blocks, ARG(2) should
be zero.
The following conditions cause the error return to be taken:
to 11 of the AC is a read only

The device specified by bits
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.

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

Meaning

Error Message

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

MONITOR ERROR 1 AT xxxxx
(CLOSE , ERROR)

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

MONITOR ERROR 2 AT xxxxx
(DIRECTORY I/O ERROR)

2.2,5

MONITOR ERROR 3 AT xxxxx
(DEVICE HANDLER NOT IN CORE)

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

MONITOR ERROR 4 AT xxxxx
(ILLEGAL USR CALL)

Results if AC bits
zero.

Call Command Decoder (DECODE)

to 11 are

Function Code =

The DECODE function causes the USR to load and execute the Command
The Command Decoder accepts (from the Teletype) a list of
Decoder.
The
input and output devices and files, along with various options.
Command Decoder performs a LOOKUP on all input 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
shoud be read before attempting to use the DECODE function.

A typical call to the Command Decoder looks as follows:
/DF=CURRENT FIELD
/IF=1

CDF
GIF 10
JMS
5

(USR

/FUNCTION CODE =

/ARG(2), ZERO TO PRESERVE ALL
/TENTATIVE FILES
/NORMAL RETURN

2-9

ARG(l) is the assumed input extension, in the preceding example it is
On return from the Command Decoder, information is stored in
".PA".
tables located in the top page of memory field 1. The DECODE function
also resets all system tables as in the RESET function (see RESET
all currently active
if ARG(2)
is
function, section 2,2,11)
non-zero
all tentative
is
open;
if
ARG{2)
remain
files
tentative
instead of
files are deleted and the normal return is to ARG{2)
ARG(2)+1.

The DECODE function has no
messages are given in Chapter
can occvir:

error return (Command Decoder error
However, the following Monitor error

3) .

Meaning

Error Message

MONITOR ERROR 5 AT xxxxx
(I/O ERROR ON SYS)

2,2.6

CHAIN Function

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

Function Code = 6

The CHAIN function permits a program to load and start another program
with the restriction that the progrcim chained to must be a core image
CSV) file located on the system device. A typical implementation of
the CHAIN function looks as follows:

CDF
GIF 10
JMS I (USR

/DF=CURRENT FIELD
/IF=1

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

BLOCK

There is no normal or error return from CHAIN,
monitor error cam occur:

However, the following

Meaning

Error Message

MONITOR ERROR 5 AT xxxxx
(I/O ERROR ON SYS)

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

CHAIN ERR

If an attempt is made to CHAIN to a
file which is not a core image
Control returns to the
(.SV) file.
keyboard monitor.

The CHAIN function loads a core image file located on the system
device beginning at the block number specified as ARG(l) (which is
normally determined by performing a LOOKUP on the desired file name)
Once loaded, the program is started at an address one greater than the
starting address specified by the program's Core Control Block.
to
CHAIN automatically performs a USROUT function (see section 2.2.9)
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 file loaded by
CHAIN. The Core Control Block for the file is set up by other ABSLDR
It can be modified by performing a SAVE command
or LOADER programs.
with specific arguments. Every page of core in which at least one

2-10

If the
page is one of the "odd
location was saved is loaded.
numbered" pages (pages 1, 3, etc,; locations 0200 to 0377, 0600
to
the previous page is always loaded.
In addition, CHAIN
etc.),
0777,
always alters the contents of locations 07200 to 07577.

NOTE
CHAIN destroys a necessary part of the
ODT resident breakpoint routine. Thus
never
be
an ODT breakpoint should
maintained across a CHAIN.
With the above exceptions, programs can pass data back and forth in
For example, FORTRAN programs normally leave the
core while chaining.
COMMON area in memory field 1 unchanged. This COMMON area can then be
accessed by the program activated by the CHAIN.
2.2.7

Signal User ERROR

Function Code =

The USR can be called to print a user error
The following is a possible ERROR call:

message

CDF
GIF 10
JMS I (USR

/DF = CURRENT FIELD
/IF = 1

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

for

program.

THE ERROR function causes a message of the form:

USER ERROR n AT xxxxx
Here n is the error number given as ARG(l); n must be
to be printed.
(octal),
and xxxxx is the address of ARG(l). I£
and 11
between
the
ARG(l) in the sample call above was at location 500 in field 0,
message:

USER ERROR 2 AT 0050

would be printed. Following the message, the USR returns
the Keyboard Monitor, preserving the user program intact.
The error number is arbitrary.
meanings

Two numbers

Error Message

USER ERROR

have

control

currently

assigned

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.

2-11

2.2.8

Function Code = 10

Lock aSR in Core (USRIN)

When making a nximber 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 (7700

/DF = CURRENT FIELD
/IF = 1

/FUNCTION CODE = 10
/NORMAL RETURN

THE USRIN function saves the contents of locations 10000 to 11777 on
the system scratch blocks , provided the calling program loads into
then
this area as indicated by the current JSW, and loads the USR,
program.
user
the
to
control
returns
.

NOTE
If bit 11 of the current Job Status Word
the USRIN function will not
is a one,

save the contents
thru 11777.

2.2,9

locations

10000

Function Code = 11

Dismiss USR from Core (USROUT)

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 locations 10000 to 11777. The
calling sequence for the USROUT function is as follows:
CDF
GIF 10
JMS I (200
11

/DF = CURRENT FIELD
/IF = 1
/DO NOT JMS TO 17700!!
/FUNCTION CODE = 11
/NORMAL RETURN

complementary
are
The USROUT function and the USRIN function
Subsequent calls to the USR must be made by performing a
operations.
JMS to location 7700 in field 1.
NOTE
If bit 11 of the current Job Status Word
the contents of core are not
a 1,
is
In this
changed by the USROUT function.
case USROUT is a redundant operation

since core was
USRIN function.

not

preserved

2-12

the

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 actually performing
Trr-T^inH
IN'^UIRE '^erform.s these operations for the user»
oTseration.
The function call for INQUIRE closely resembles the FETCH handler

call.

INQUIRE, like FETCH, has two distinct forms:
1,

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

Determine if the handler
niimber is in core.

corresponding

given

device

An example of the INQUIRE call is shown below:

CLA
CDF
GIF 10
JMS I (USR

/AC MUST BE CLEAR
/DF = CURRENT FIELD
/IF = 1

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

DEVICE DTA3
JMP ERR

When
ARG(l) and ARG(2) contain the device name in standard format.
the normal return is teUcen ARG(2) is cheuiged to the device number
corresponding to the given name, and ARG(3) contains 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.

A slightly uXi.i.erent set Ci. arguments

1.3

useu

i-n^i

device by its device number:

/AC IS NON-ZERO
/DF = CURRENT FIELD
/IF = 1

TAD VAL
CDF
GIF 10
JMS

(USR

/FUNCTION CODE =12

/ARG(l)

/ERROR RETURN
/NORMAL RETURN

JMP ERR

On entry to INQUIRE, AC bits

to 11 contain the device number.

2-13

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

MONITOR ERROR 4 AT XXXXX
message is printed and program execution
is terminated.
On nontial 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

Function Code =13

RESET System Tables

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

CDF
GIF 10
JMS I (USR
13

/DF = CURRENT FIELD
/IF = 1

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

RESET zeros all entries except the one for the system device in the
(see section B.3.3, removing all
Device Handler Residency Table
device handlers, other than that for the system device, from core.
This should be done anytime a user program modifies any 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). This is
accomplished by zeroing bits 9 through 11 of every entry in the Device
Control Word Table (see section B.3.5).
fashion, to delete all active
If RESET is to be used in this last
tentative files, then ARG(l) must be non-zero and the normal return is
the' following call
to ARG(l) rather than to ARG(1)+1. For example,
would serve this purpose

CDF
CIF 10
JMS I (USR
13

CLA CMA

/DF: CURRENT FIELD
/IF = 1

/FUNCTION CODE =13
/NON-ZERO:

The normal return would execute the CLA CMA and all active tentative
files on all devices would be deleted. The Keyboard Monitor currently
If user programs which do not call
does not reset the Monitor tables.
it is wise to do a RESET operation
the Command Decoder are used,
before loading device handlers. The RESET will ensure that the proper
handler will be loaded into core.

2-14

CHAPTER 3
THE COMMAND DECODER

OS/8 provides a powerful subroutine called the Command Decoder for use
by all system programs. The Command Decoder is normally called when a
program starts rvinning. When called, the Command Decoder prints an *
and then accepts a command line from the console Teletype that
file names , and various option
includes a list of I/O devices ,
The Command Decoder validates the command line for
specifications.
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 OS/8 programs. Also, since commeind
lines all have a standard basic structure, the Command Decoder makes
learning to use OS/8 much easier.

COMMAND DECODER CONVENTIONS

3.1

Chapter 1 of the 03/8 HANDBOOK describes the syntax j.or the cominanu
A brief synopsis is given here only to clarify the
line in detail.
later discussion in this chapter.
The command line has the following general form:

output files < input files/ (options)
There

Ccin

output files and

input files specified.

Meaning

Output File Format
EXPLE.EX

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

LPT:

Output to the LPT.
specifies
generally
structured device.

This
a

format
non-file

DTA2: EXPLE.EX

Output to a file named EXPLE.EX
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:

3-1

Meaning

Input File Format
DTA2 INPUT

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

DTA2: INPUT. EX

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

INPUT. EX

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

PTR:

Input from device PTR;
for
needed
name
is
structured devices.

DTA2;

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

no file
non-file

*TTy:/L<DTA2:
In both of the last two foirmats, no
LOOKUP operation is performed since
assumed
to
be
the device is
non-file structured.

null

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

<PTR:,,

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

NOTE

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

3-2

specified device names,
file
The Command Decoder verifies that the
names, and extensions consist only of the characters A through Z and
through 9. If not, a syntax error is generated and the command line is
considered to be valid.
first,
There are two kinds of options that can be specified:
alphanumeric option switches are denoted by a single alphanumeric
character preceded by a slash (/) or a string of characters enclosed
secondly, a numeric option can be specified as an
in parentheses;
(=) .
These
octal number from 1 to 37777777 preceded by an equal sign
options are passed to the user program and are interpreted differently
by each prograun.

Finally, the Command Decoder permits the command line to be terminated
This information is also passed
by either the RETURN or ALT MODE key.
to the user program.

3.2

COMMAND DECODER ERROR MESSAGES

If an error in the command line is detected by the Command Decoder,
After the error
is printed.
one of the following error messages
message, the Command Decoder starts a new line, prints an *, and waits
The erroneous command is ignored.
for another command line.

Error Message

Me£ming

ILLEGAL SYNTAX

The command
incorrectly

TOO MANY FILES

More than three output files or
nine input files were specified.
(Or in special mode,
more them 1
output file or more than 5 input

line

fonnatted

files.}

3.3

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 neime was
not found on the selected device.

CALLING THE COMMAND DECODER

The Command Decoder is initiated by the DECODE function of the USR.
DECODE causes the contents of locations
to 1777 of field
to be
saved on the system scratch blocks, and Command Decoder to be brought
When the command line has been
into that area of core and started.
entered and properly interpreted, the Command Decoder exits to the
USR, which restores the original contents of
to 1777 cUid returns to
the calling progrcim.

3-3

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
to 1777,
do not occupy locations

The DECODE call Ceui reside in the area between 0000 to 1777 and
function correctly. A typical call would appear as follows:

still

/SET DATA FIELD TO CURRENT FIELD
CDF
/INSTRUCTION FIELD MUST BE 1
GIF 10
JMS I (USR /USR=7700 IF USR IS NOT IN CORE
/OR USR=0200 IF USRIN WAS PERFORMED
/DECODE FUNCTION = 5
5
/ARG(l) ,ASSUMED INPUT EXTENSION
2001
/ARG(2),ZER0 TO PRESERVE
/ALL TENTATIVE FILES
/NORMAL RETURN

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

to
DECODE perfoinos an automatic RESET operation (see section 2.2.11}
remove from core all device handlers except those equivalent to the
zero all
is
system device. As in the RESET function, if ARG(2}
If ARG(2}
is
active tentative files are preserved.
ciirrently
non-zero, all tentative files are deleted and DECODE returns to ARG(2)
instead of ARG(2)+1.

As the Command Decoder normally handles all of its own
is no error return from the DECODE operation.

3.4

errors,

there

COMMAND DECODER TABLES

The Command decoder sets up various tables in the top page of field
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 teible that begins
at location 17600. Each entry is five words long and has the following
format

3-4

10 11

BIT-DEVICE
NUMBER

WORD 1

USER SPECIFIED
FILE LENGTH

WORD

PILE NAME
CHARACTER 1

FILE NAME
CHARACTER 2

WORD

FILE NAME
CHARACTER 3

FILE NAME
CHARACTER 4

WORD 4

FILE NAME
CHARACTER 5

FILE NAME
CHARACTER 6

WORD

PILE EXTENSION
CHARACTER 1

PILE EXTENSION
CHARACTER 2

OUTPUT FILE NAME
6 CHARACTERS

FILE EXTENSION
2 CHARACTERS

if the
to 7 of word 1 in each entry contain the file length,
Bits
file length was specified with the square bracket construction in the
command line. Otherwise, those bits are zero.

The entry for the first output file is in locations 17600 to 17604,
the second is in locations 17605 to 17611, and the third is in
locations 17612 to 17616. If word 1 of any entry is zero, the
corresponding output file was not specified, A zero in word 2 means
that no file name wets specified.
Also, if word 5 of any entry is zero no file extension was specified
It is left to the user program to take
for the corresponding file.
the proper action in these ccises.

These entries are
function.

3.4.2

format

that

acceptable

the

ENTER

Input Piles

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

01234567

10 11

4-BIT DEVICE
NUMBER

WORD 1

MINUS FILE
LENGTH

WORD

STARTING BLOCK OF PILE

of word 1 contain the file length as a negative number.
in these bits is a length of one block, 376 (octal)
etc.
If bits
to 7 are zero, the
is a length of two blocks,
specified file has a length greater than or equal to 256 blocks or a
non-file structured device was specified.
Bits
Thus,

377

(octal)

3-5

NOTE
This restriction to 255 blocks of actual
specified size can cause some problems
if the program has no way of detecting
For example,
end-of-file conditions.
PIP cannot copy in image mode any file
on a file structured device that is
greater than 255 blocks long, although
it can handle in /A or/B modes (ASCII or
In /A
Binary) files of unlimited size.
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 Commcmd Decoder
described in section 3.5 ard parform its
own LOOKUP on the input files to obtain
the exact file length.

The two-word input file list entries beginning at odd numbered
If location 17617 is zero,
locations from 17617 to 17637 inclusive.
no input files were indicated in the command line. If less than nine
input files were specified, the unused entries in the input file list
are zeroed (location 17641 is always set to zero to provide a
terminator even when no files are specified)

3,4,3

Command Decoder Option Table

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

10 11

HIGH ORDER 11 BITS F
= N OPTIONS

17642

17643 A

17644 M

17645 Y

17646 LOW ORDER 12 BITS OF =

OPTIONS

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

3-6

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

if the
of location 17642 is
terminated by a
was
line
carriage return, 1 if it was terminated
by an ALT MODE.

Bit

consmand

3.4.4

Example

TO clarify some of the preceding, consider the interpretation
following command line:

the

*BIN [ 10 ]<PTR:,,DTA2: PARA, MAIN /L=14200$

assembly of a
tapes, one file
paper
two
parts:
program consisting of four separate
(or
MAIN. PA
named
file
one
and
DTA2,
on
PARA)
just
named PARA. PA (or
also on DTA2. The binary output is placed on a file named
iust MAIN)
No
BIN.BN on device DSK, for which only 10 blocks need be allocated.
the binary
of
loading
automatic
addition,
In
generated.
is
listinq
address given
output 'is specified by the /L option, with the starting
ALTMODE key
the
by
terminated
is
line
the
Finally,
1.
field
as 4200 in
after the
Monitor
Keyboard
to
the
(which echoes as $) causing a return
loaded.
progr2ua is
cause
If this command line is typed to PALS, it would

to PALS
In the case of this example, the Command Decoder returns
the following values in the system tables:

NOTE
The entries for PTR (where no input file
ncune is specified) have a starting block
This is
number and file size of zero.
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-7

with

17600

242

DSK:IS DEVICE NUMBER

0211
1600

'file name is bin

0000

17604

NULL EXTENSION

0000

17605

^ IN

ENTRIES
ar > REMAINING
OUTPUT TABLES
(are ZERO

17616
17617
0016

FIRST PTR INPUT

00 00

17620
17621
0016

SECOND PTR INPUT
00 00

17622
17623

DAT2: PARA PA IS 5 BLOCKS LONG,
BEGINNING AT 100(8)

7667
0100

17624
17625
0007
>

DTA2: MAIN PA IS 256(10) OR MORE
BLOCKS LONG, BEGINNING AT BLOCK 105(8)

0105
17626
17627

REMAINING ENTRIES
INPUT TABLES
ARE ZERO.

i?i}lii

17641
17642

4001

17643

0001

17644

0000

LINE WAS TERMINATED BY ALT MODE

yL WAS ONLY OPTION SWITCH
SPECIFIED

3.5

17645

0000

17646

4200

— =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 the user
program itself. Programs such as format conversion routines which
If
access non-standard file structures could use this special format.
the input files were not OS/8 format, a command decoder LOOKUP
operation would fail. The capability to handle this case is provided

3-8

in the OS/8 Command Decoder.
as the "special mode" of the

This capability is generally referred to
Command Decoder.

Calling the Command Decoder Special Mode

3.5.1

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
Therefore, the
an assumed extension of ".*", which is illegal.
conflicts
with the
way
Decoder
in
no
Command
of
the
mode
special
normal mode.

Operation of the Command Decoder in Special Mode

3.5.2

a
command
In special mode the Command Decoder is loaded and inputs
The appearance of the command line is altered by the
line as usual.
special mode in these respects:
1.

Only one output file can be specified.

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

are legal
The characters asterisk (*) and question mark (?)
and extensions, both in input files and on
in file names
output files. It is strongly suggested that these characters
be tested by the user program and treated either as special
options or as illegal file naunes. The user program must be
careful not to ENTER an output file with cin asterisk or
question mark in its name as such a file cannot easily be
ra^mipulated or deleted by the standard system programs.

rather

than

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

WORD

VJORD 2

FILE NAME
CHARACTER 1

FILE NAME
CHARACTER 2

WORD

FILE NAME
CHARACTER

FILE NAME
CHARACTER 4

BITS 0-7 ARE

4-BIT DEVICE
NUMBER

WORD

FILE NAME
CHARACTER 5

FILE NAME
CHARACTER 6

WORD

FILE EXTENSION
CHARACTER 1

ALWAYS

INPDT FILE NAME
6

FILE EXTENSION
2 CHARACTERS
i

3-9

CHARACTER

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

The OS/8 batch generating system
decoder in special mode.

3.6

will

allow

calls

the

command

CCL AND THE COMMAND DECODER

CCL uses its own copy of the Command Decoder instead of the copy
available from the monitor. Thus, the CCL Commcind Decoder has several
options not available via standard USR calls to the OS/8 Command
Decoder, e.g., multiple default extensions.

3.7

USEFUL LOCATIONS IN BATCH

BATCH will run whenever bit
of location 07777 is a 1. The user may
wish to access the following useful locations in BATCH. The locations
are in the highest memory field availedsle to OS/8:

3.8

BATERR = 7000

JMP here to abort BATCH.

BATOUT = 7400

JMS here to print character
in AC in BATCH log,

BATSPL = 7200

JMS here to permit spooling
with default extension in AC.

CCL TABLES

A description of all tables used by CCL is included in the file CCL. PA
supplied to all users of OS/8 version 3.

3-10

CHAPTER 4
USING DEVICE HANDLERS

A device handler is a system subroutine that is used by all parts of
the OS/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 maisk the unique characteristics of
different I/O devices from the calling progreun;
thus, progreuns that
use device handlers properly are effectively "device independent".
Changing devices involves merely changing the device handlers used for
I/O.

OS/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 bks of data to be transferred without
stopping the tape motion.
On a disk, a single operation could
treUisfer an entire track or more.
This capeUaility significantly
increases the speed of operation of OS/8 programs, such as PIP, that
have large buffer areas.

NOTE
The word "record" is defined to mean 128
words of data;
thus,
an OS/8 block
consists of two 128 word records.

4.1

CALLING DEVICE HANDLERS

Device handlers are loaded into a user selected area in memory field
by the FETCH function. FETCH returns in ARG(l) the entry point of the
handler loaded. The handler is called by performing a JMS to the
specified entry point address.
It has the following format:

CDF N

CIF
JMS I ENTRY
ARG(l)
ARG(2)
ARG(3)

/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

4-1

/ERROR RETURN
/NORMAL RETURN (I/O TRANSFER COMPLETE)

JMP ERR

/ENTRY CONTAINS THE ENTRY POINT OF THE
/HANDLER, DETERMINED WHEN LOADED BY^TCH

ENTRY 'o

As with calls to the USR, it is important that the data field is
to the current program field before teldevice handler is called.
exit from the device handler, the data field will remain set to
current program field.
ARG(l) is the
information:

function

control

word,

and

contains

the

set
On
the

following

Contents

Bits

for an input operation,
operation.

Bit

for

output

Bits

to 5

be
to
The number of 128 word records
1-5 are zero and the
If bits
transferred.
device is non-file structured (i.e., TTY,
LPT, etc.) the operation is device dependent.
(SYS,
file structured
If the device is
DECtape, disk, etc.), a read/write of 40
(octal) pages is performed.

Bits

The memory field in which the transfer is
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
If bit 11 is 0, the tape
tape is started.
starts in reverse. If bit 11 is 1, the tape
All other handlers ignore
starts forward.
these bits at present (except TM8E and TA8E)

NOTE

Starting forward saves time as long as
the block nvimber, ARG(3) , is about seven
or more blocks greater them the number
of the block at which the tape is
currently positioned,
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
After each transfer the user program
LOOKUP or ENTER operation.
current block number the actual number of
the
to
add
should itself
blocks transferred, equal to one-half the number of 128 word records
specified, rounded up if the number of records was odd.

When an
fatal and non- fatal.
There are two kinds of error returns:
error
the
negative,
are
the
AC
of
contents
and
the
occurs
return
error
a
input,
on
error
parity
a
A fatal error can be caused by
is fatal.
read-only
a
write
on
to
attempt
output,
or
an
on
error
write lock

4-2

device (or vice versa) . The 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 an error return occurs and the contents of the AC are greater
This error
than or equal to zero, a non- fatal error has occurred.
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 the error exit with the
While all non-file structured input devices can
AC equal to zero.
detect the end-of-file condition, no file structured device can;
furthermore, no device handler takes the non- fatal error return when
doing output.
The following restrictions apply to the use of device handlers:
1.

function control word, ARG(l), are
If bits 1 to 5 of the
40
zero,
a transfer of
(octal) pages or an entire memory
field is indicated.
Care must be used to ensure that the
handler is not overlaid in this call. This only applies to
file-structured handlers.

The user program must never specify an input into locations
07600 to 07777,
17600 to 17777, or 27600-27777, or the
page(s) in which the device handler itself resides.
In
general, 7600-7777 in every memory field are reserved for use
by system software. Those areas should be used with caution.

Note that the amount of data transferred is given as a number
of 128 word records, exactly one half of an OS/8 blodc.
Attempting to output an odd number of records can change the
contents of the leist 128 words of the last block written.
For example, outputting 128 words to a block on the RK8 disk
causes the last 128 words of the block to be filled with
zeroes

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" memory = For example, a
write of 2 pages starting at location 07600 would cause
locations 07600-07777 and 00000-00177 of field
to be
written.

If bits 1-5 of the function control word ARG(l) are
zero, a
device-dependent operation occurs. Users should not expect a
40-page (full field) transfer of data. The CLOSE operation
of the USR calls the handler with bits 1-5 and 9-11 of the
function control word 0. This condition means
'perform any
special
close
operations desired'. Non-file structured
handlers which need no special handling on the conclusion of
data transfers should treat this case as a NOP. Examples of
usage of such special codes

LPT - perform a form feed
CSAn, MTAn - write two file marks

4-3

4.2

DEVICE DEPENDENT OPERATIONS

This section describes briefly the operation of certain standard OS/8
any
special
operation,
normal
including
handlers,
device
initialization operations for block 0, terminating conditions, and
Further
response to control characters typed at the keyboard.
information on device h^lndlers can be found in Chapter 5.

1-Page Terminal (TTY)

4,2.1
1.

(AS33)

Normal Operation
This handler inputs characters from the terminal keyboard and
packs them into the buffer or unpacks characters from the
buffer cind outputs them to the console terminal.

Following
On input, characters are echoed as they are typed.
into the
inserted
is
character
feed
line
a
return,
carriage
a
input buffer and printed on the terminal.
2.

Initialization for Block
None.

Terminating Conditions
(octal code
On input, detection of a CTRL/Z causes a CTRL/Z
232) to be placed in the input buffer, the remaining words of
the buffer to be filled with zeros, and a non- fatal error to
On output, detection of a CTRL/Z character in
be returned.
causes output to be terminated and the
buffer
the output
There are no fatal errors
normal return to be taken.
associated with the 1-page terminal handler.

Terminal Interaction

CTRL/
CTRL/C forces a return to the Keyboard Monitor,
terminates
CTRL/0
(see
input
.
on
3)
end-of-file
an
forces
printing of the contents of the current buffer on output.

High-Speed Paper Tape Reader (PTR)

4,2.2
1,

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

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

4-4

;;oTE

On some terminals , up-arrow is replaced
'
character.
by the circumflex
)

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

Terminal Interaction

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

High-Speed Paper Tape Punch (PTP)

4.2.3
1.

Normal Operation
This handler unpacks characters from the
punches them on the paper tape punch.

output

buffer

and

Initialization for Block
None.

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

Typing CTRL/C forces a return to the Keyboard Monitor, but
only when actual punching has begun, or if tC is typed before
only
tC
is
punching commences. If the punch is off line,
effective immediately before punching would begin.

Line Printer (LPT)

4.2.4
1.

(LPSV)

Normal Operation
This handler unpacks characters from the buffer and prints
The characters horizontal tab
them on the line printer.
causes sufficient spaces to be inserted to
(ASCII 211)
position the next character at a "tab stop" (every eighth
(ASCII
column, by definition) . The character vertical tab
causes a skip to the next paper position for vertical
213)
that
teibulation if the line printer hardware provides
The character form feed (ASCII 214) causes a skip
feature.
Finally, the handler maintains
to the top of the next page.
a record of the current print column and starts a new line
This heindler
after 80 or 128 columns have been printed.
4-5

properly only on ASCII data. The handler for the
fiinctions
LS8E line printer handler utilizes the expcuxded character
216 (CTRL/N) character
If a
capability of the printer.
the entire line is
appears anywhere in a line of text,
printed in the expanded character mode. The 216 must be used
on a line-by-line basis,
2.

Initialization for Block
Before printing begins, the line printer handler
form feed to space to the top of the next page.

issues

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

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

Patching the LPSV Handler
The following patches are available for the LPSV line printer
h2mdler.
rel. loc 0: set to -printer width-1

rel, loc

(i.e. set to -121 (octal)
for an 80 column line
printer)

LV8E
the
for
printers
for the LPOE and
printers

1: set to 4

set to 14

line

LS8E

to convert lower case to
upper case
if your printer can print
lower case

rel. loc 2; set to -40

set to

Cassettes

4.2,5
1,

Normal Operation
This handler performs character I/O between the cassettes and
cassettes as a non-file structured
It treats
the buffer.
device. Data appears on cassette in 192-byte records.

Initialization for Block
On input the cassette is rewound. On output the cassette
rewovind and a file gap is written.

Terminating Condition

4-6

An end-of-file on input is a software error.
4.

Terminal Interaction

Special Codes (device dependent features)

function word
If the handler is called with bits 1-5 of the
The meaning of these codes
=0, then bits 10-11 are examined.
are as follows s
1
2
3

write a file gap
rewind also, then write a file gap if bit 0=1
space backwards one record
skip one file (direction depends on bit 0)

NOTE
The handler neither reads nor writes
It is merely a paper
standard files.
raw data
It writes
tape replacement.
(organized into 192-byte records) onto
the cassettes starting at the beginning;
and then later reads it back.
The source is already in OS/8 BUILD format. The hauidler has only two
entry points (for drives A and B of a controller). The decision as to
which controller it uses is made at assembly time by changing the
symbol code. The result is as follows:

DEVICE NAME

HANDLER

DEVICE CODE

TA8A

A:CSAO
B:CSA1

TA8B

A:CSA2
B:CSA3

TA8C

A:CSA4
B:CSA5

TA8D

ASCSA6
B:CSA7

CODE

2-12
(see Table
The handler has the internal device code of 27
Chapter 2 of the OS/8 HANDBOOK. The handler is two pages long.

Card Reader (CDR)

4.2.6
1.

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

4-7

Initialization for Block

None.
3.

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

Terminal Interaction
Typing CTRL/C forces a return to the Keyboard Monitor.
Typing CTRL/Z forces an end-of-file to occur (see 3.)-

TM8-E Handler

4.2.7
1.

Normal Operation:

When the handler is used in its normal mode, single-file
It starts at
mode, magtapes may consist of exactly one file.
the beginning of the tape euid consists of consecutive records
In this sense, a
until an end-of-file mark (EOF) is reached.
magtape is similar to one big paper tape. This is the same
way that OS/8 currently treats ceissettes.
Since the capacity of magtapes is so big, provisions have
been made for storing multiple files per tape. In such a
structure, several files may exist on one magtape. They are
unlabeled and are separated from each other by a single file
Each
The last one is followed by two file marks.
mark.
It is referenced in a
like a paper tape.
looks
•file'
The magtape handler must be
non-file structured memner.
altered first to work in file mode. Then the magtape must bepositioned to exactly the correct spot where the read or
This may be done with any
write operation will commence.
program using the auxilieiry capabilities of the magtape
handler (described below) , or the positioner program, CAMP.
To read a file, the handler must be positioned to just before
the first data record of that file. To write file #1, rewind
the
(n>l)
To write file #n,
the tape (i.e., be at BOT) .
handler should be positioned after the (n-l)st file mark on
Previous file n and all files past it then become
the tape.
unreadable (non-existent)
A.

Device-Dependent Capabilities:
The TM8-E hcuidler has several auxiliary features which
may be invoked by a user program which calls the handler
in a device-dependent meuiner. These features all rely on
the contents of bits 9-11 of the function word (argument
require argument 3 in
1 of the handler call) and some
addition.

4-8

These features are brought to life whenever the handler
(bits 1-5 of the
called with a page count of
is
the
function word). Call bits 9-11 of the ftinction word,
Special Function Register (SFR) for short, and also refer
If
of the function word as the direction bitto bit
the contents of the SFR is
the page count is not
,
ignored.
If the page count is 0, then the SFR together with the
(and possibly argument 3) determine what
direction bit
special function to perform, as follows:

OPERATION

SFR

Write two EOF's.

CLOSE.

Rewind.

The direction to
Space forward/reverse records.
space is determined by the direction bit (0 means
space forward, 1 means space reverse) . The negative
complement) of the number of records to space
(two's
(-1
over is given by argument 3 of the handler call,
means 4096 records.)
means space past one record,
The error return is taken if either a file mark or
BOT is encountered.
In such cases, you would be left
positioned at the beginning of a file.

Space forward/reverse files. The direction to space
is determined by the direction bit (0 means space
forward, 1 means space reverse) . The negative of the
number of file marks to space past is given by
argument 3 (-1 means space past one file mark;
means 4096 file mcurks). In reverse mode, the tape is
an error is
left positioned at the end of a file;
In forward mode, the
given if BOT is encountered.
tape is left positioned at the beginning of a file.
If EOD is reached, the handler automatically performs
marks;

no error is given.

Rewind the unit and put drive off-line.

Write a single EOF.

(as
Special read/write function. The direction bit
determines read or write
(0 means read, 1
is
operation
I/O
means write) .
The specified
(start is
performed
between
the user's buffer
specified by argument 2) and the very next magtape
record.
Only one record is transferred and the
user's buffer must be large enough to contain it.
The record length is specified by the negative of
meeuis
argument 3 (in words).
a record length of

usual)

4096.
7=

Unused,
Reserved for future usee
currently acts as a NO-OP.

the

In each case, the unit affected is determined
point.

4-9

specified,

handler

entry

Other Common Operations:

(a)

To backspace n files, use special code 3 to pass over
n+1 file marks backwards, then use special code 2 to
the
advcuice (forward) over one record (EOF) ignoring
EOF error,

(b)

To advance to EOD, first perform a backspace of one
record
(or perform a rewind to play safe) then use
special code 3 to advance over 4096 files in the
forward direction (argioment 3=0) .

Special Handling for Block
it will
0,
If the handler is called to read or write block
first perform a rewind. This feature can be patched out if
to a 1. This
desired by altering relative location 1 from a
altered handler should be operating in file mode. The
original handler should be operating in single- file mode.
A.

Special Handling for CLOSE:

A close operation is signaled to the handler by calling
(bits
it with a function word which heis a page count of
This is how the
1-5) and which has bits 9-11 all zeroes.
USR CLOSE operation calls the heuidler (OS/8 V3 only.
This causes the handler to write two successive file
marks on the tape. Two successive EOF's is the software
indication of end-of-data (EOD)
B.

Restrictions

should not have more than 4095
In single-file mode,
blocks because on trying to write the 4096th block, the
and perform a
handler will think it's writing block
This restriction does not apply when using the
rewind.
handler in file-mode; but beware, same cusps, such as
PIP, are suspected to behave strangely on block 4096 of
non- f i le- s true tured de vi ces
3.

Terminating Conditions
None.

Keyboard Interaction:
Typing tC on the keyboard while the handler is in operation
causes the handler to abort and return to the OS/8 keyboard
monitor via location 7600. Such action is ill-advised since
it leaves the magtape without an end-of-file indicator.

Error Conditions:
On a hard error, the handler taUces the error return (with a
and the AC contains the contents of the main
negative AC)
status register, as follows:

4-10

Meaning

Bit on

1
2
3
4

Error flag
Tape rewinding
Bor
Select error
Parity error (vertical, longitudinal, or
CRC)

5
6

7
8

10
11

EOF
Record length incorrect
Data request late
EOT
File protect
Read compare error
Illegal function

File-Structured Devices

4.2.8
1.

Normal Operation
(DECtape, LINCtape, TD8E DECtape, DF32, RF08, and RK8, RK8E)

These handlers transfer data directly between the device
the buffer.
2,

and

Initialization for Block
None.

Terminating Conditions

A fatal error is returned whenever the trcuisfer causes one of

For
the error flags in the device status register to be set.
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 eind retiurning a fatal error.
There are no non-fatal errors associated with file structured
devices.

Terminal Interaction

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

NOTE
The system device handler
respond to a typed CTRL/C.

4.2.9

does

NOT

TD8E DECtape

TD8E DECtape is the new accumulator treuisfer DECtape. Since OS/8 is a
noninterrupt driven system, TD8E DECtape has data transfer rates
equivalent to those for TC08 DECtape; however, the interrupt should
never be used with the TD8E. Device handlers for TD8 DECtape are
supplied as a standard part of OS/8. Each pair of drives (0, and 1, 2
requires a 2-page device handler. Thus, to have all
and 3, etc.)

4-11

eight TD8E drives in the system at one time will require four separate
Thus for TD8E, it is wise to restrict usage to those units
handlers.
that physically exist. Also, the tape drives are hardwired to select
thus, the first pair of drives
one of two possible unit numbers;
installed must be called units
to 1. Any others numbers will cause a
case,
the computer hangs until the correct
In this
SELECT error.
drive is selected.

4.2.10

KL8E Terminal Handler

Listed are the features of the KL8E
conditional are marked by an asterisk:

handler.

Those

that

are

Whenever the user types CR, it
It reads a line at a time.
and then
enters CR, LF into the buffer; it echoes CR, LF;
pads the remainder of the buffer with nulls and returns to
The characters get put into the buffer,
the calling program.
Thus every third character is a null
one character per word.
as far as OS/8 is concerned.

RUBOUT deletes the previous character.
It echoes as either a
back slash
(\) or as the character rubbed out, depending on
eissembly parameters.
RUBOUT at the beginning of a line acts
as tU.

CTRL/U echoes as tU £uid erases the current line, allowing the
user to retype it.
(It also echoes CR, LF.) The buffer
pointer is reset to the beginning of the buffer.

CTRL/Z echoes as
tZ
(followed by CR, LF)
and signals
end-of -input.
The tZ enters the buffer and the remainder of
the buffer is padded with nulls. The error return is taken
with a positive AC (non-fatal error)

Nulls are ignored.

*6.

The altmode characters (octal 175 and 176) are
escapes (octal 33)

*7.

Lower-case characters typed may be automatically converted to
upper case.

CTRL/C echoes as tC and returns
monitor via location 07600.

On output;

control

converted

the

keyboard

(either normal output or when echoing input)

CTRL/C on keyboard echoes as tC and returns
keyboard monitor via location 7600.

CTRL/0 on keyboard stops further echoing. All echoing ceases
(through possibly many buffer loads) until either the handler
is reloaded into core or the user
types a character other
than to on the keyboard. Not operative during input.

tS causes the hcuidler to stop sending to
No
the terminal.
characters are lost and outputting resumes when a tQ is
typed.
tS
and tQ do not echo.
These characters are

4-12

control

the

operative only upon output. On input, they are treated like
any other input characters. This is very useful on high
speed CRT displays.
4.

Nulls are ignored.

*5.

Lower case characters may be optionally printed as upper case
and flagged with an apostrophe.

*6 .

Tabs may be handled in one of three manners

Output as actual tabs

Output as actual tab followed by padding of two rubouts,

Output as the correct number of spaces to bring the
to the start of the next tab stop.

text

Whenever the output line reaches the end of the physical line
(length set at assembly time) ,
the handler automatically
performs a carriage-return line-feed.

*8.

The escape character (octal 33) prints as a dollar sign,

*9.

The handler may be set to delay about 16 ms after typing any
character
(specified at assembly time) , for example, line
feed.

*10.

Control characters are printed as their corresponding
preceded by an up-arrow. Thus CTRL/K prints as tK,

4-13

letter

CHAPTER 5
RECONFIGURING THE OS/8 SYSTEM

It is sometimes necessairy to construct an OS/8 system from scratch, or
to make a new peripheral device available to OS/8. Both of these tasks
OS/8 BUILD, which is
are a part of reconfiguring the OS/8 system.
described in detail in Chapter 2 of the OS/8 HANDBOOK, allows the user
quickly and easily to build a new system or to alter the device
complement of an existing system.

5.1

WRITING DEVICE HANDLERS

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

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

0=1

BUFFER
BLOCK
ERROR
NORMAL

number of 128 word records
a
The device hcuidler reads or writes
In general, device handlers should
beginning at the selected block.
conform to the following standards:
1.

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 significcmce only
for file structured devices , handlers for non-file structured
devices can check the block number and perfoinn initialization
For example, the line printer
if the block number is zero.
the
handler outputs a form feed before printing when
specified block number is zero.

Handlers should be written to be as foolproof as possible
checking for the most common errors in the calling program.

5-1

calling handler wxth
Examples of typical user errors are:
handler); trying to
the
in
CLA
a
perform
(always
non-zero AC
wrxte on a read
to
trying
read on a write only device, or
pages
specifying
return)
error
?
fatal
a
(gives
only device
transfer is to
to be transferred (accept as meaning no actual
or attempting to access a nonexistent block
place);
talce
return)
error
fatal
a
(gives
4.

Device handlers normally check to see if a CTRL/C (ASCII 203)
If one
has been typed at the system console by the user.
location
7600
to
JMP's
and
I/O
aborts
handler
has, the
field 0. The seven low order bits of the keyboard should be
checked for a 3 so as to allow parity terminals. KRS should
be used over KRB so that any paper tape in the reader will
not be advanced if its character is not tC.

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

10.

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

Remember that the user specifies a multiple of 128 words to
transfer, whereas the transfer starts at the beginning of a
128 or 256 word block. This means that the handler must
provide that capability of reading or writing the first half
of a block, writing the first half of the block causes the
contents of the second half of the block to be altered. For
example, writing 128 words to the RK8 disk (256 word blocks)
causes the second half of the block to be filled with zeroes.
This is usually done by the hardware controller.
The entry point to a two page device handler must be
first page.

the

A number of handlers (maximum of 15 decimal) can be included
Where more than one handler
in the one or two pages of code.
are
is included in a single handler subroutine, the handlers
brought
always
are
handlers
Co-resident
called co-resident.
into core together. For example, all eight DECtape handlers
hence, the DECtape handlers are
one page;
into
fit
on co-resident handlers is that
restriction
One
co-resident.
if they are two pages long all entry points must be in the
first page^
The USR, while doing file op rations, maintains in core the
last directory block read n order to reduce the number of
fxinctioning of this
Ihe proper
directory reads necessary.
feature depends on the fact that every handler for a

5-2

file-structured device on a single system has a unique entry
point relative to the beginning of the handler. The relative
entry points currently assigned for file structured handlers
are:

Relative Entry foints

Device Handlers

11.

System Device Handler
DEC tape, LINCtape or TD8E DECtape

10 to 17

RKAO
RKAl
RKA2
RKA3
RK08 or DF32
Reserved for user

21
22
23
24
40 to 67

DECtape, LINCtape,
If the device is block oriented (such as
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
into the buffer on
hcindler is required to pack characters
input and unpack them on output. The standard OS/8 character
packing format puts three 8-bit characters into two words as
follows
WORD

CHARACTER 3
BITS 0-3

WORD

CHARACTER 1

CHARACTER 3
BITS 4-7

CHARACTER 2
11

For example, the 3 characters 'ABC' would be
words as follows:

packed

into

Word 1: 6301
Word 2i 1702
When packing characters on input, the character CTRL/Z (octal
is inserted at the logical end-of-file (for excunple, at
232)
the end of the tape in the paper tape reader handler)
Following CTRL/@ the remaining words of the input buffer
should be zeroed.
12.

A close operation should be performed by non-file structured
handlers if bits 1-5 and 9-11 of the function word are 0.

The device handler, whether one or two pages long, must be completely
it must be capable of executing in any page(s) in
page independent:
and 7600 to 7777. Page independent code can
field 0, except page
have no address constants. Writing one page handlers is relatively
easy, since the addressing structure of the PDP-8 is essentially page
independent. Writing page relocatcible code for two pages, however, is
The
considerably more difficult, as the two pages must communicate.
usual technique utilized in writing two page heindlers is to include
This replaces that
some initialization code which includes a JMS.
Using
location by an address on the page the heuidler was loaded on.
code
of
pieces
relevant
the
where
determine
this, the handler can then
core.
in
are

5-3

As ein example, the following is the initialization procedure performed
by the TD8E DECtape routine. This is by no means the only technique
that is possible, but it is a workaible solution.
*200

/EXECUTED CODE
JINIT,

JMP INIT

/START INITIALIZATION

INIT,
BASE,

JMS.
TAD CRDQAD

/FOUND OUT WHERE WE ARE.
/INIT GETS ADDRESS OF BASE
/NEGATIVE TERMINATES LIST
/INITIALIZE SECOND PAGE
/NOW UPDATE THE LIST OF
/ADDRESS DEPENDENT LOCATIONS
/POINT TO NEXT ELEMENT
/NEXT INPUT VALUE
/LOOP OVER INPUT TABLE.

SPA
JMP NXINIT
TAD INIT
DCA CRDQAD
ISZ .-1
ISZ BASE
JMP BASE

/THESE ARE ALL POSITIVE DIFFERENCES,
/SINCE THE ROUTINES INDICATED ARE
/IN THE SECOND AGE. AFTER
/INITIALIZATION, CRDQAD POINTS TO
/THE ACTUAL ADDRESS OF R4LINE, ETC.
/THE 4000 IN BUFF TERMINATES
/THE FIRST INITIALIZATION,
/MORE PAGE INDEPENDENT CODE

CRDQAD,
CINIT2,
CSELCT,
CXUNIT,
BUFF,

R4LINE-BASE
INIT2-BASE
SELECT-BASE
XUNIT-BASE

NXINIT
BASE2,

JMS I CINIT2 /INITIALIZE SECOND PAGE
DCA JINIT
/CLEAR OUT JINIT. NO MORE
/RELOCATING IS NEEDED UNTIL THE
JMP JINIT
/HANDLER IS LOADED INTO CORE GAIN.
*400
/SECOND PAGE OF HANDLER

INIT2
INIT3

4000

/ADDRESS OF BASE2 GOES HERE

TAD CTRY3
SNA
JMP I INIT2
TAD INIT2
DCA CTRYS
ISZ .-1
ISZ INIT3
JMP INIT3

CTRY3,
CRWCOM,
XBUFF,

TERMINATES THIS LIST

/ADD VALUE OF BASE2 TO LIST
/PUT BACK INTO LIST
/NEXT LOC. TABLE

TRY3-BASE2
/THIS LIST GETS VALUE OF BASE
TRWC0M-BSSE2 /ADDED IN TO POINT TO THE REAL
/ROUTINE.

5-4

Writing 2 page independent code can be expensive in terms of core
The routines should be set up in such a way as to minimize
required.
Some other points to keep in
communication between the two pages.
mind are:
1.

5.2

Relocation code is once-only code. It is done once when the
handler is loaded and need never be done again until the
For this
handler is re-loaded from the system device.
reason, the relocation code can be placed in a buffer area or
setup in temporary scratch locations which are later used as
temporary storage.

A useful hint is that a JMP into the next page of code is not
The code can just as easily fall through 377 into
required.
400, This may save a few locations of relocation code.
Useful techniques for writing 2-page handlers can be found in
the source of the KL8E handler.

INSERTING DEVICE HANDLERS INTO OS/8

After the handler has been written and thoroughly debugged as a
stand-alone routine, it can be integrated into the OS/8 Monitor, where
the
To accomplish
it will become a resident device handler.
section
BUILD
the
in
thoroughly
described
BUILD,
integration, use OS/8
in Chapter 2 of the OS/8 HANDBOOK.
Notes for writing system handlers system handlers may be integrated
into BUILD just like non-system handlers with the following additional
notes
1.

Body of system handler should be origined to 200 but must
start with a 2 BLOCK 7. Entry point must be at relative
location 7 (corresponds to location 7607).

Name of system handler must be SYS.

Each handler entry point has eUi 8-word handler
associated with it. The following additions, apply:
a.

word

block

bits 9-11 should normally be 0.

(like RF08)
If the device can have multiple platters
then this field specifies maximum number of platters

Each platter above first
allowed.
code by 1.

bumps

internal

DCB

word 6: bit 0=1 means system device is two pages long.
The second page is origined into 400 but resides in
field 2 location 7600. Bit 1=1 if entry point is SYS.
Bit 2=1 if entry point is coresident with SYS.

word 7:

must be

Immediately
word 10: number of blocks in device.
for the
the
code
records
is
header
the
following
This is preceded by minus the
device's bootstrap.
number of words in the bootstrap. No origins may appear
It must be less them 47 locations long.
in this code.

5-5

APPENDIX A
OS/8 FILE STRUCTURES

A.i

iJ± KiiL-TUKii. £J

the
Blocks 1 through 6 on all file structured devices are reserved for
allocated,
always
are
blocks
Six
file directory of that device.
To minimize
though all are not necessarily active at any given time.
OS/8 fills one
the number of directory reads and writes necessary,
directory block completely before overflowing onto a second block.
LOOKUPS and
Thus the user with only a few files can perform directory
files.
many
ENTERS faster than one with
The directory blocks are each structured according
format
ENTRY

the

following

MINUS THE NUMBER OF ENTRIES
IN THIS SEGMENT
THE STARTING BLOCK NUMBER
OF THE FIRST FILE IN THIS
SEGMENT

LINK TO NEXT SEGMENT-ZERO
ir NO NEXT SEGMENT
FLAG WORD-POINTS TO LAST WORD
OF TENTATIVE FILE ENTRY IN
THIS SEGMENT
DIRECTORY SEGMENTS ARE ALWAYS
LOADED INTO LOCATIONS 11400
TO 117777 BY THE USR; THIS
OR BETWEEN
POINTER IS EITHER
1400 TO 1777.
MINUS THE NUMBER OF
ADDITIONAL INFORMATION WORDS
THE NUMBER OF ADDITIONAL
INFORMATION WORDS SPECIFIED
MUST BE THE SAME IN ALL
DIRECTORY SEGMENTS

BEGINNING OF FILE ENTRIES
*

377

ds>

END OF DIRECTORY BLOCK

(8)

Locations
header.

through

of each directory block are called

A-1

the

segment

A. 1.1

Directory Entries

There are three types of file directory entries. They are PERMANENT
FILE ENTRY, EMPTY FILE ENTRY, and TENTATIVE FILE ENTRY. A permanent
file entry appears as follows

Location

Contents

FILE NAME
CHARACTER

Jotes
Pn

FILE NAME
CHARACTER

FILE NAJ'IE
CHARACTER

THE FILE NAME AND EXTENSION
ARE PACKED IN SIXBIT ASCII
{i.e. ,

FILE EXTENSION FILE EXTENSION
CHARACTER 2
CHARACTER 1

"A" would be 01)

;

THE NUMBER OF ADDITIONAL
INFORMATION WORDS, IS GIVEN
BY WORD 4 OF THE DIRECTORY
^' \ HEADER.
WORD 4 OF THE ENTRY
OR THE CREATION
IS EITHER
DATE OF THE FILE.
N,

ADDITIONAL
INFORt-IATION

WORDS

NOTE
If word

is zero, the given file has

null extension.

An empty file entry appears as follows:
Contents

Location

ENTRY IS ALWAYS 0000
MINUS THE NUMBER OF BLOCKS
IN THIS EMPTY FILE

A tentative file entry appears as a permeinent file entry with a length
It is always immediately followed by an empty file entry.
of zero.
file is entered in a directory, location 3 in the
tentative
When the
segment header becomes a pointer to this entry. The CLOSE function
inserts the length word of the tentative file entry, raeUsing 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) not the contents of location 3 in the
Zeroing these bits in the Device Control Word Table
segment header.
makes the active tentative file on the device inactive. The next time
that the system has to write the directory segment, the inactive

A-2

The distinction between active and
tentative file entry is removed.
inactive tentative files is made so that OS/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 OS/8 Files

All files on an OS/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 deduced 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
if N is the number of
of Additional Information Words). Thus,
Additional Information Words the maximum number of permanent file
entries in any one segment is
256-7 - (N+5)

MIN =

244-N
]

[

]

N+7

with N=l, MAX=40, and MIN=30. Since there are six segments in the
directory, the maximiom number of files possible (with N=l) would be
240.

Finally, OS/8 devices are limited to 40 95 blocks, each block being 256
words long. Thus, the maximum size of any single oS/8 file structured
through 6 of the device are
device is 1,048,320 words. Blocks
unavailable for file storage; therefore, the largest possible file is
4088 blocks long, or 1,046,528 words.

A. 1.3

Sample Directory

The initial directory written when the OS/8 system is built
follows

A-3

looks

;tes

Locatiicn
T.\C

EMTRIES

FILE STORAGE STARTS AT BLOCK 70 g*
NO ADDITIONAL DIRECTORY SEGMENTS

SEGMENT
HEADER

TENTATIVE FILES.
ONE ADDITIONAL INFORi'IATION

N"0

'WORD

i'5
[

FILE NAME IS "ABSLDR"

PERMANENT
FILE
ENTRY

FILE EXTENSION IS .SV
DATE IS 10/31/70
LENGTH IS FIVE BLOCKS

(13

EMPTY FILE

EMPTY
FILE
ENTRY

LENGTH IS 12448 (676lo) BLOCKS THIS IS DEPENDENT ON THE SYSTEM
676 IS THE VALUE
DEVICE USED.
FOR A DECTAPE SYSTEM

;i4

377,

A. 2

*This leaves room for the OS/8 System
Areas.

FILE FORMATS

file

There are three different standard
associated system programs:

used

OS/8

and

(LIB8.RL

the

only

formats

ASCII and Binary files.

Core Image files (.SV format).

Relocatable FORTRAN library files
current example of this format)

NOTE
Binary files can contain either absolute
binary data (i.e., output from PALS) or
output
(i.e.,
relocateible binary data
from SABR)
A. 2.1

ASCII and Binary Files

characters into two words,
ASCII and Binary files are packed three
follows:
CHARACTER 3
CHARACTER 1
WORD 1
BITS G-3
WORD

CHARACTER
2

CHARACTER 2

BITS 4-7
3

OS/8 system programs:
The following conventions are used by
i^ ^^^^^^
(ASCII 000)
In ASCII files the character NULL
1.
low-order
7 bits, in
the
examine
ignored. Most programs only
do not
ignored;
ASCII files. The parity bit is usually
will
transfers
data
that
or
assume Sa; this bit is set
it).
preserve
always
transfers,
mode
(image
preserve it
A-

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

V~ ^ «.

SJA,ritXJ,y

f^l.-.^l
i-xXca/
f

...
u-i,

^1
\uCua^/
f

-inn

/ .^f^,^

_Jtlu

v.r^^'^Vi

i r^
WU^v^iA ^ij

3w^

ci±i

<»k-*--tf-r^ii

\j*.J~'^J,ii

c-^4-4>^«^«-r
K>5ww^ii«^»

The end of binary data is indicated by one or more frames
leader/trailer code.

ASCII and Binary files are terminated by a CTRL/Z code (ASCII
code data rather than
a CTRL/Z
In binary files,
232).

Core Image (.SV Format) Files

A. 2. 2

The
A core image file consists of a header fay the actual core image.
header block is called the Core Control Block. The Core Control Block
consists of the first 128 words of the 256 word block reserved for
The second 128 words are unused. The Core Control
that purpose.
Block is formatted as follows:

Location

Notes

Contents
CORE CONTROL BLOCK

MINUS THE NUMBER OF CORE SEGMENTS
1

CDF CIF (STARTING FIELD)

STARTING ADDRESS

JOB STATUS VJORD

CORE SEGMENT
CONTROL DOUBLE WORDS

(K IS THE NUMBER OF
CORE SEGMENTS)

2K +3
377

6 2N3 WHERE N IS THE
STARTING FIELD

REMAINDER OF BLOCK

^ IS

»r

A-

UI'TUSED

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.

1777

Bit

1=1

File does not load into locations
in field 1.

1777

Program must be reloaded
restarted.

Bit 2 = 1
Bit

Program never uses above 8K. This
when Batch processing is active.

= 1

before

can
is

used

Bit 10 =

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

Bit 11 =

to 1777 in field 1 need
Locations
preserved when the USR is called.

not

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

MULTIPLE OF 400
8
BITS
AND 9-11
ARE ZERO

CORE ORIGIN

1
2

Notes

Contents

Location

FIELD

NUMBER OF PAGES
TO LOAD
1

TO LOAD
5

The core origin must be a multiple of 400 (octal) . The Core Segment
Control Doublewords are sorted within the header block in order of
There
decreasing field and increasing origin within the same field.
in
Doublewords
Control
Segment
Core
(decimal)
32
than
more
be no
ccin
any Core Control Block.
The Core Control Block for the program at the time it is loaded into
core is always saved in words 200 (octal) through 377 (octal) of block
37 (octal) (one of the system scratch blocks) on the system device.
It is 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
in that the program's Core
command
Control Block is not written onto the
scratch area when using the R commcind.
In order to SAVE a program that has been
loaded by the R command all of the
arguments of the SAVE commemd must be
explicitly stated.

A-6

A. 2. 3

Relocatable FORTRAIi Library File

A relocatable FORTRAN library consists of a library directory block
followed by relocatable binary segments. The directory block has the
following format:
Notes
Contents
Location
CHI

CH2

CH3

CH4

NAME OF ENTRY IN
SIXBIT ASCII PADDED
VJITH TPAILING BLANKS

CH6
LOAD POINTER

'additional entries

}

DENOTES END OF
NAME ENTRIES

t:^.

-LOADER CONTROL WORD(S)
.END OF LOADER CONTROL
WORDS FOR THIS ENTRY
377,

which points
(octal)
and 377
The Load Pointer is a number between
Control
of
Loader
array
to
an
block)
of
the
beginning
the
(relative to
Words. The Loader Control Words have the following information:

NUMBER OF PAGES OCCUPIED
BY THIS SEGMENT AFTER LOADING

(STARTING BLOCK OF RELOCATABLE BINARY DATA)
(DIRECTORY BLOCK #)-l

The
There can be one or more Loader Control Words for each entry.
Loader Control Words for an entry are teirminated by a word of zero.
The following is a simple directory block.

A-7

Location

Contents
1117

1040

4040

0530

lOH"
"

4040

LOAD POINTER FOR "EXIT"

0373

0000

LOADER
CONTROL f373
WORDS FOR/-

0207

0411

»'*
^375

0000

"lOH*

NAME OF ENTRY IS "EXIT

1124

LOADER
CONTROL J376
WORDS F0r("377

LOAD POINTER FOR

0376

"EXIT"

NAME OF ENTRY IS "lOH

2400
8

0000

A-8

MARKS END OF ENTRIES

(RELATIVE BLOCK 10 „) (ONE
PAGE LONG)
(TWO
(RELATIVE BLOCK 12„)
"
PAGES LONG)
(RELATIVE BLOCK 1) {12g PAGES
LONG)

APPENDIX B
DETAILED LAYOUT OF THE SYSTEM

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

B.l

LAYOUT OF THE SYSTEM DEVICE

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

Block (s) in
1-6
7-12

13-15
16-25
26

27-50
51-53
54-55
56
57

60-63
64
65
66
67

Octal

are

Contents

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
CCL Reminiscences
12K TD8E Resident code
CCL Overlay

File storage begins with block 70 (octal).
The system scratch blocks are used for preserving the contents of core
when the Keyboard Monitor, USR, Commeind Decoder, or ODT are loaded.
Most
In addition, various system programs use the scratch area.
importantly, the SAVE command expects the Core Control Block to be
The
(octal).
loaded in words 200 (octal) to 377 (octal) of block 37
Core Control Block is stored at those locations by the GET or RUN
command or by the ABSLDR or LOADER program.

B-1

A detailed breakdown of system scratch block usage follows:
Contents

Block (s) in Octal
27-32

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

33-36

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

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

B,2

the

40-47

Used as scratch storage
LOADER programs.

Reserved for future expansion.

ABSLDR

and

LAYOUT OF THE OS/8 RESIDENT PROGRAM

The top core pages in fields 0, 1, and 2 are used by the resident
portion of OS/8 and are not accessable by the user. As a general
rule, system and user programs should never destroy the contents of
locations 7600 to 7777 of any field.
The resident portion of OS/8 is structured as follows:

Location

Contents

Notes

7600

WRITE OPERATION

*\ NON-DESTRUCTIVE
ENTRY TO PS/

JMP TO FIELD 1 FOR READ

7605

7607

SYSTEM DEVICE HANDLER

—DESTRUCTIVE
ENTRY TO PS/8
*\ ENTRY TO SYSTEM
DEVICE HANDLER

7743
7744
7745
7746

CURRENT STARTING ADDRESS
JOB STATUS WORD

MUST ALWAYS BE ZERO

7747
7750

RESERVED FOR DATA BREAK
LOCATIONS
7755
7756

PROGRAM SETUP AREA
7777

H
B-2

-THE KEYBOARD MONITOR
AND ODT MODIFY THIS

AREA

TOP PAGE OF FIELD

,4*"

7615
7617

ENTRitS).

-0 MARKS END

OF LIST

BIT 0=1
IF COMMAND
LINE TERMINATED BY
ALTMODE

SPECIFIED OPTIONS
LOW 12 BITS OF =N

DEVICE HANDLER
RESIDENCY TABLE
SYSTEM DATE WORt)

7665
7666
7667

COMMAND
DECODER
awFa

READ OPERATION
(LOAD KEYBOARD MONITOR)

7677
7700

7776
7777

HxGH 11 BITS OF —

7645
7646
7647

7757
7760

OUTPUT FILE LIST

INPUT FILE LIST
(MAXIMUM 9 ENTRIES)

7641
7542
7643

7740
7741

Notes

Contenrs

Location
7500

USR CALL AND RETURN AREA

-ENTRY TO USR

USER DEVICE
NAME TABLE

DEVICE CONTROL WORD TABLE

NOTE
SYSTEM ODT DESTROYS
CONTENTS OF THIS TABLE
WHEN SETTING BREAKPOINTS

RESERVED FOR FUTURE USE

UNUSED

Read-Only-Memory option
Systems built around TD8E DECtape without the
devxce handler.
system
the
use 7600 in field 2 as an extension of
TOP PAGE OF FIELD 2.

7«;oo

TD8E
12K
for
only
used
system
of
Part
systems.
hiuidler resides here in that
case.
7773
7774

Four words reserved for BATCH
use if machine has exactly
into
12K. Contains pointers
input file.
7777

location
If the machine has more than 12K, the top 4
BATCH.
use
by
for
reserved
the last field are

(7774-7777)

an 8K TD8E system,
is being used with
to the user. That
inaccessible
are
7
field
of
7400-7777
locations
functions.
core is used for system handler
If a ROM (Read-Only-Memory)

B-3

SYSTEM DEVICE TABLES

B.3

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

B,3,l

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

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 1: 2024
WORD 2: 2200
Note that when the device name is left
inserted to fill four characters.

justified;

O's

are

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

the

corresponding

Conventionally, device names
consist
only of the characters A to Z and
to
9. The first
character 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 able is fifteen locations long; it 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
10036.

B,3.2

User Device Name Table

Entries are made in this table whenever the user performs an 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

B.3.3

Device Handler Residency Table

When a device handler is loaded by the USR, the entry in this table
are
for the device loaded (and entries for all devices whose handlers
co-resident, if any) is set to contain the entry point^for the device
Entries other than those that contain an address above 7600
handler.
when a RESET,
to the system handler) are restored to
referring
(thus
exits to the
program
a
When
executed.
DECODE or CHAIN fmiction is
Monitor
Keyboard
The
cleared.
not
is
table
this
Monitor
Keyboard
Commands GET, RUN, R, SAVE, and START (with no explicit address) clear
this table.

NOTE
is
Since the system device handler
always resident the first entry (SYS is
in the Device
always device number 1)
Handler Residency Table is always 7607
system device
(the entry point of the
handler)

The Device Handler Residency Table resides in locations 17647
17665.

B.3.4

through

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

Bit Condition

Meaning

0=1

If this is a two page device handler.

Bits

Bits 1 to

Bits

to 11

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

Contain the offset of the handler entry
point from the beginning of the page.
all
Note that the entry points to
handlers must be in the first page.

the corresponding device handler is not saved in any
entry is
storage blocks. This is always true of device
handler
device
of the
number 1 (the system device) and for all device numbers that are not
used in a given configuration. The Device Handler Information Table
When the USR is in core
is 15 locations long and resides in the USR.
location the address of
at
a
field
1
table
is
in
the beginning of the
which is contained in location 10037.
If

ein

B-5

B,3.5

Device Control Word Table

device
characteristics,
Entries in this table specify special
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

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

Bits

to 11

Contain the physical
(described below) ,

1
2
3
4

5
6
7

10
11
12

13
14
15
16
17
20
21
22
23
24

25-26
27
30

31-37
40-57

type

code

For file structured devices, these bits
contain the directory block ninnber of
If
the currently active tentative file.
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,
(with
explicit
no
R,
SAVE, START
address)
and optionally by the CISR
functions RESET and DECODE.

The device type is a number between
are currently
(octal)
through 20
follows
Device Code

device

and 77 (octal) , of which
assigned to existing devices, as

Device
Teletype
High-speed paper tape reader
High-speed paper tape punch
Card Reader
Line Printer
RK8 Disk
256K Disk (RF08)
512K Disk (RF08 + RS08)
768K Disk (RF08 + 2 RSOS's)
1024k disk (RF08 + 3 RS08«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)
TM8E Magnetic Tape
TD8E DECtape
BATCH handler
RK8E Disk
NULL
reserved for future disks
TA8E Cassette
VR12 Scope
reserved for future use by DEC
reserved for use by users

B-6

The Device Control Word
17776.

Table

resides

locations

17760

through

There is a sixth table that is not normally considered part of the
This is the Device Length Table and is used only by
system tables.
(compress device)
and /S
(zero directory)
PIP to perform the /Z
for each possible
one
entry
locations
long,
64
table
is
This
options.
means that the corresponding
device type. In this table an entry of
otherwise the entry contains the
device is non-file structured;
negative of the number of available 256-word blocks on the device.

For example, the entry for a 256K disk would be 6000
2000 (octal), or 1024 (decimal), 256-word blocks).

(octal)

(minus

The Device Length Table resides in PIP, When PIP is brought into core
the Device Length Table is in locations 13600 to 13677. When new
device types are added to the system this table should be patched with
ODT to reflect the device length of the new device.
It
A similar table occurs in RESORC which the user may wish to patch.
four-word
64
contains
2000-2377
and
locations
field
in
located
is
entries; one entry for each device type. Words 1 and 2 of an entry
the names of the device (in sixbit) and word 3 is the negative of
cire
for non-standard devices.
the number. Word 4 of the entry should be

B-7

APPENDIX C
SYSTEM ERROR CONDITIONS AND MESSAGES

This is a summary of all error messages that are a result of system
These errors are also described in the relevant sections of
errors.
this manual and in the OS/8 HANDBOOK.

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:

Value of PC

^te^ming

occurared while attempting to
load ODT. Return to the Keyboard Monitor by
restarting at 07605.

QQ501

A read error

07461

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

07605

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

07702

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

07764

07772

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

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

C-1

10066

10256

17676

An input error occurred while attempting to
Return to the Keyboard
restore the aSR.
Monitor by restarting at 07605,

A read error occurred while attempting to
load the Monitor by restarting at 07605.
An error occurred while attempting to read
the Keyboard Monitor from the system device.
Try again be restarting at location 07605. DO
NOT 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
Return to
the USR from the system device.
the Keyboard Monitor by restarting at 07605.

17736

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

Also, there is one halt in the LOADER program:

A parity error occurred when attempting to
overlay the LOADER from the system scratch

00005

blocks. Return to the Keyboard Monitor
restarting at 07605, and try again.

After retrying the operation which caused the failiure, if the error
persists, it is the result of a hartware malfunction or a parity error
Run the appropriate diagnostic program to check
in the system area.
the device cuid rebuild the system.

C.2

USR ERRORS

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

MONITOR ERROR n AT xxxxx
In these cases, the value "n" describes the error and
to be printed.
is the address of the call to the USR that caused the error.
'xxxxx""
The six Monitor errors are:

Meaning

Message

MONITOR ERROR 1 AT XXXXX
[CLOSE ERROR]

MONITOR ERROR 2 AT xxxxx
[DIRECTORY I/O ERROR]

File length
too large.

in CLOSE

function is

An I/O error occurred while ata
write
or
tempting to read
directory block. This is generally
caused by the device being WRITE
LOCKed.

C-2

MONITOR ERROR 3 AT XXXXX
[DEVICE HANDLER NOT IN CORE)

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

MONITOR ERROR 4 AT XXXXX
[ILLEGAL USR CALL]

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 ON SYS]

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

MONITOR ERROR 6 AT XXXXX
[DIRECTORY OVERFLOW]

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

In addition to the MONITOR ERROR messages, system
can use the USR to print:

and

user

progreuns

USER ERROR n AT xxxxx
case the value of
In this
by using the ERROR function.
user-defined and "xxxxx" is the address of the call to the USR.

Currently, two USER ER1W3R numbers have been assigned:

Meaning

Message

USER ERROR

AT xxxxx

USER ERROR 1 AT XXXXX

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

FORTRAN

SABR

an attempt was made to
progrcUQ,
call a subroutine that had not been

loaded ^
If an I/O error is made during the monitor CHAIN function the message

CHAIN ERR
is generated, and control returns to the keyboard.

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

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

C-3

Meaning

Message
aaaa?

The Keyboard Monitor cannot interpret
the command "aaaa". For exaunpie if the
user types HELLO the system will respond
HELLO?

BAD ARGS

SAVE
a
Arguments to
inconsistent, or illegal.

BAD CORE IMAGE

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

BAD DATE

In^roper synteuc in a DATE command.

device NOT AVAILABLE

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

ILLEGAL ARG

The SAVE command
correctly.

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.

NOll

was

command

not

are

expressed

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

C.4

but

NO CCLl

Command was a valid CCL command
CCL.SV is not on the system.

SAVE ERROR

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

SYSTEM ERR

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

TOO FEW ARGS

An argument
command

has

been

omitted

from

CCL ERROR MESSAGES

Meaning

Message
BAD DEVICE

The device specified in a CCL command is
(e.g.,
form,
correct
of
the
not
DTAO.PA:)

BAD EXTENSION

specified
was
extension
Either an
without a file name (e.g., DTAli.PA) or
(e.g.,
two extensions were specified
DTA1:FILE.PA.BN)

C-4

The version of the Keyboard Monitor
being used is not compatible with CCL.
A new version of the monitor must be
obtained from Digital before CCL can be

BAD MONITOR

used.

BAD NUMBER

the
uses
#
which
A CCL command
full
the
have
not
does
construction
16-digit specification that is required.

BAD RECOLLECTION

An attempt was made to use a previously
reiaeinbered argument when no argument was
no
when
This error occurs
saved.
argument was previously saved or when
the DATE command has been used since the
argument was saved.

BAD SWITCH OPTION

to
(/)
The character used with a slash
an option is not a legal
indicate
option.

CANNOT CHANGE CORE
CAPACITY WHILE RUNNING
BATCH

A CORE command was issued while the
BATCH program was running.

%CANT REMEMBER

The argvunent specified in a CCL command
line is too long to be remembered or an
I/O error occurred.

CCL 3X OVERLAY &
MONITOR INCOMPATIBLE

The version of CCL being used is not
ctMopatible with the Keyboard Monitor
present on the system. Type R CCL to
retry.

COMMAND LINE OVERFLOW

The command line specified with the @
construction is more than 512 characters
in length.

COMMAND TOO LONG

The length of a text argument in a
conoaand xs too xcng.

CONTRADICTOR SWITCHES

Either two CCL processor switches were
in the seime command line
specified
(e.g., FILE-PA-FT) or the file extension
and the processor switch do not agree
(e.g., FILE.FT-BA).

name DOES NOT EXIST

The device with the name given
present on the OS/8 system.

ERROR IN COMMAND

A command not entered directly from the
console terminal is not a legal CCL
command. This error occurs when the
argiiment of a UA, UB, or UC commsuid was

MUNG

not

not a legal command.
ILLEGAL

An * or- ? was used in a CCL command that
card
wild
the
accept
not
does
that
commands
CCL
Only
construction.
run FOTP or DIRECT allow the wild card
cons truetion

C-5

line

was

formatted

ILLEGAL SYNTAX

The CCL command
incorrectly.

INPUT ERROR READING
INDIRECT FILE

CCL Ceuinot read the file specified with
the @ construction.

I/O ERROR ON SYS:

An error occurred while doing I/O to the
be
The system must
device.
system
7605.
Do
or
7600
at
restarted
surely
not press CONT. as that will
cause further errors.

I/O ERROR TRYING TO
RECALL

An I/O error occurred while CCL was
trying to renumber an argument*

NO CCLl

CCL.SV is
device.

NOT ENOUGH CORE

The nvanber specified in a CORE commauid
larger than the ntmber of 4K core
is
banks on the system.

name NOT FOUND

The file with the name given is not
present on the specified device, or the
user tried to input from an output-only
device.

%SUPERCEDED

The file specified in a MAKE ctxnmand
This is a warning
exists.
ed-ready
nessage indicating that the file is
being replaced.

SWITCH NOT ALLOWED HERE

Either a CCL option was specified on the
left side of the < or was used when not
allowed. For exan^le: COMPARE FILE-NB.

TOO MANY FILES

To xaany files were
command

C-6

not

present

included

the

system

CCL

C.5

COMMAND DECODER ERRORS

After the
Decoder.
The following errors are printed by the Command
prints
a * and
line,
new
error message, the Command Decoder starts a
_j^_ n
-«-«4.i,«-.- /^^rnmanH 1 1 n<a .
The erroneous command is ignored.

Meaning

Message

line

formatted

ILLEGAL SYNTAX

command
The
incorrectly.

TOO MANY FILES

More than three output files
files were specified
input
or > 1 output or >
mode)
(special mode)

or nine
(regular
input
5

name NOT FOUND

The specified input file name
foiind on the device indicated.

was

C-7

not

APPENDIX D
PROGRAMMING NOTES

This appendix is a potpourri of ideas and techniques that have proven
useful in programming the PDP-8. OS/8 users may find some use in their
own progreims 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

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

D.7

Notes on Loading Device Handlers

D.8

Available Locations in the USR Area

D.9

Accessing Additional Information Words in OS/8

D.IO SABR Programming Notes

D.l

THE DEFAULT FILE STORAGE DEVICE, DSK

The Command Decoder, as noted earlier, makes certain assumptions about
Neunely, on all output
the I/O device where none is explicitly stated.
On
files where no device name is given, the device DSK is assumed.
the first input file where no device name is given, DSK is assumed.
Subsequent input files assume the same device as the previous input
This convention was adopted to simplify typing command lines.
file.
The permanent device name DSK is assigned when the system is built.
On all standard systems, DSK is equivalent to SYS. A useful technique
to use the ASSIGN commauid to redefine the meeuiing of DSK
is
For example, where device DTAO is equivalent to DSK and
temporarily.

D-1

it becomes desirable to change DSK to DTAl, the following command
be given:

can

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

then 'DSK*
If 'DSK' has not been assigned via the ASSIGN command,
always exists and has internal device number 2. User programs wishing
to use DSK should do an INQUIRE to find its number in case the
operator has re-assigned it.

D.2

MODIFICATION TO CARD READER HANDLER

The standard card reader handler for OS/8 uses the DEC029 standard
Some installations may prefer to use the DEC026 codes
card codes.
This can be done by changing the card conversion codes with
instead.
the BUILD command ALTER.
1.

Call OS/8 BUILD by typing:
RUN SYS BUILD
in response to the dot printed by the Keyboard Monitor.

Load the card reader handler as described on page 2-42 of the
OS/8 HANDBOOK.

Use the ALTER command (see page
iges:
to make the following chcinges:
!

2-49 of the

FROM

104
105
106

3203
4007
3502

7735
4076
0774

114
115
116

7514
0577
3637

3314
1002
0305

124
125
126
127

0104
1211
3374
0641

3204
1273
3606
1341

134
135
136

7316
3410
1376

CHANGE RELATIVE LOCATION

•

OS/8

HANDBOOK)

3716
1175
3401

The new system will have modified card codes.
Note that this procedure does not affect FORTRAN rtin time card input
with READ (3,n). The conversion table for FORTRAN is UTILTY.SB on
source DECtape #2. (DEC-S8-OSyE3-A-UA2)

D-2

026 PUNCH CARD CODES

tal 8-bit
CODE

DEC026
CODE

240
241
242
243
244
245
246
247

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

250
251
252
253
254
255
256
257

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

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

CHARACTER
SPACE
1

$
%

8-6

0-8-3
11
12-8-3
0-1

1
2
3
4
5
6
7
8

•

(
)

+
1

•

/
1
2
3
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

300
301
302
303
304
305
306
307

8-4
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

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

A card containing an 8-2 in column 1
with all remaining columns blank is an
end-of-file card.

D-3

8-5
8-2

C HARAi
@

A
B
C
D
E
F
G
H
I

J
K
L

M
N
P
Q

R
S

T
a

V
w
X
Y
z
[

\
]

D.3

SUPPRESSION OF CARRIAGE RETURN/LINE FEED IN FORTRAN

return/line
It is often desirable to suppress the automatic carriage
following FORTRAN WRITE statements to achieve an easily
(CR/LF)
feed
readable text. The following three methods in OS/ 8 FORTRAN can be
used to achieve this result:
1.

Follow the I/O list of a WRITE statement with a comma.
the following statements:
100

101

WRITE (1,100) N,
FORMAT (1X,15HTHE VALUE OF A(,I2,5H)4IS
READ (1,101)A(N)
FORMAT (F8.4)

Thus,

)

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

THE VALUE OF A(12) IS 147.83
2.

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:
102

WRITE (1,102) IDUMMY,
FORMAT ('DESIRED TEXT ',10)

READ statement using break character, as follows:
101

READ (1,101) IA,IB,IC
FORMAT (•A=',I1»'B=',I1,'C=1,I1)

results in no CR/LF after each phrase is printed.
the output is all printed on a single line.

D.4

That

is,

ACCESSING THE SYSTEM DATE IN A FORTRAN PROGRAM

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

100

PROGRAM PRINTS THE CURRENT DATE
DUMMY DATE
TAD I DATE
DCA TEMP
TAD TEMP
AND (7
DCAXIYR
TAD TEMP
RARjRTR
AND (37
DCA \IDAY
TAD TEMP
CLL RAL;RTL;RTL
AND (17
DCA \IMO
WRITE (1,100) IMO,IDAY,IYR
12 -12-197 11/)
FORMAT (/'DATE:
'

D-4

SDATE

CALL EXIT
CPAGE 2
6211

7666

STEMP,

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 OS/8 system programs
Because
of
and CREF perform this calculation.
LOADER, PALS,
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:
1.

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

CDF 70
TAD I(X)
HLT

/NONEXISTENT FIELD
/EXECUTED LOCATION X
/THIS INSTRUCTION SKIPPED

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

On a PDP-12 with an odd number of 4K banks (12K, 20K, 28K)
Reads
all reads in the first nonexistent field load zeros.
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
(It
tests bits 6 to 7 of all CDF and GIF
NOP's.
as
However,
instructions for O's before executing the lOT.)
there is a special 12K option for the PDP-8/L called a BM08.
With this option a CDF to field 2 is valid, but a 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 computers. For
the purpose of this example, it is assembled at 00200.

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

/NOTE

— THIS ROUTINE MUST BE PLACED IN FIELD

D-5

0200 0000
0201 7300
0201 6201
0203 1237
0204 7006
0205 7004
0206 0217
0207 1232
0210 3211
0211 6201
0201 1635
0213 7000
0214 3211
0215 1213
0216 3635
0217 0070
0020 1635
0221 7400
0022 1221
0223 1236
0224 7640
0225 5232
0226 1211
0227 3635
0230 2237
0231 5202

CORE,
CORO,

CORl,

C0R2,

COR70

CLA CLL
CDF
OCRS I
TAD
RTL
RAL
COR70
AND
COREX
TAD
.+1
DCA
\N
CDF
CORLOC
TAD I
NOP
CORl
DCA
C0R2
TAD
CORLOC
DCA I
70

TAD I
CORX,

CORLOC

7400

CORX
TAD
CORV
TAD
SZA CLA
COREX
JMP
CORl
TAD
CORLOC
DCA I
CORSIZ
ISZ
CORO
JMP
CDFO
TAD
JMP I
CORLOC, CORX
1400
CORV,
C0RSI2, 1
COREX,

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

/MASK USEFUL BITS
/SET UP CDF TO FIELD
/N IS FIELD TO TESV
/SAVE CURRENT CONTENTS
/(HACK FOR PDP-81)
/7000 IS A "GOOD" PATTERN

/(HACK FOR PDP-8., NO-OP)
/TRY TO READ BACK 70 00
/(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
0235
0236
0237

6201
1237
5600
0221
1400
0001

D.6

USING PRTC12-F TO CONVERT OS/8 DECTAPES TO OS/12 LINCTAPES

CORSIZ
CORE

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

Many users of OS/8 on the PDP-12 will be interested in the fact that,
since OS/8 uses an identical file structure on all devices, PDP-8
DECtape in OS/8 format may be directly copied to OS/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 must be read
before attempting to use PRTC12-F. The operations that convert OS/8
format DECtapes are as follows?
LINCtape

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

When the READ questionnaire is displayed, respond as follows
stands for
the character J
(responses are underlined;
stands for line feed)
carriage return and i
BLOCKS
READ 1777 J
UNIT 1 )
TAPE FORMAT A )

D-6

STARTING WITH BLOCK

etc.
3.

the
follows

l^fhen

WRITE

questionnaire

displayed,

respond

WRITE THE RESULT
ON UNIT 2J
IN TAPE FORMAT Bj
STARTING AT BLOCK 0^4etc.

NOTES ON LOADING DEVICE HANDLERS

D.7

Problem With Multiple Input Files

D.7.1

There is a problem associated with reusing Device Handler
OS/8, This problem is best illustrated by an example:

areas

Assume a program has reserved locations 1000-1377 for its input
handler and locations 7400-7577 for its output handler. If the
progreun gives a USR FETCH command to load the DTAl handler as an input
device handler, all 8 DECtape handlers will load into 1000-1377, since
If another FETCH is issued to load the DTA2
they are all co-resident.
handler as an output device handler, that handler will not be loaded,
because it shares space with the DTAl handler currently in core. This
however, if the user now switches input devices and FETCHes
is fine
the paper tape reader handler as an input device hamdler it will
destroy the DTA2 handler and the next attempt to output using the DTA2
There are two ways to get around this
heuidler will produce errors.
problem.

Always assign the hemdler which you expect to stay in core
the longest first, Mosi: programs Ceui process more than one
input file per program step (e,g, , an aaseidbly pass is one
program step) but only one output file; therefore, they
assign the output handler before any of the input handlers.
In the above example, the problem would be eliminated if the
DTA2 handler were assigned first.

Obviously,
Always give a USR RESET call before each FETCH.
This
this call should not delete any open output files.
means that the USR will always load the new handler, even if
The user must FETCH the output
another copy is in core.
handler again before issuing the USR CLOSE call, otherwise
the 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
time.

D.7 .2

run

Dynamically Loading Device Handlers

Some programs which use dyncimic core allocations will want to use OS/8
handlers but cannot afford to always allocate the maximum of
two pages per handler. The following is a subroutine which loads a
It assumes
device handler dynamically, returning its entry in the AC.
and a
that the name of the handler is in locations NAMEl and NAME2,
De'" ce

D-7

cottom or
subroutine GETPAG exists uhich gets a page rrom rhe
.his
AC.
rhe
address
its
of storage and rsrurns
available field
field
from
callea
be
only
can
and
1
field
in
runs
example subroutine
possibility.
1, but can be rewritten for any other

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

/MOVE DEVICE NAME INTO "INQUIRE" COiMMAND

/USRIN - FORCE USR INTO CORE

JMS I (200

/INQUIRE

Nl,
N2,
LOCI,

/NO SUCH DEVICE - QUIT
JMP ASSERR
TAD LOCI
/IS THE HANDLER ALREADY IN CORE?
SZA
- RETURN ITS ENTRY POINT
/YES
ASSIGN
JMP I
/GET A PAGE DYNAMICALLY
JMS GETPAG
DCA L0C2
/LOAD DEVICE NUMBER
ASSTRY, TAD N2
JMS I (200
/FETCH
1
/PAGE TO FETCH INTO
I.0C2,
/FAILED - MUST BE A TWO-PAGE HANDLER
JMP TWOPAG
TAD L0C2JMP I ASSIGN /RETURN ENTRY POINT
/GET ANOTHER PAGE
TWOPAG, JMS GETPAG
/SET "TWO PAGE HANDLER ALLOWED" BIT
ISZ L0C2
CLA
/FETCH WILL SUCCEED THIS TIME
JMP ASSTRY
ROUTINE
/ERROR
ASSERR, • « • •
«1

D.8

AVAILABLE LOCATIONS IN THE USR AREA

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

storage

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

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

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

storage

with

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 Jcey specifying
which segment of which device is currently in core.

D-8

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

D.9

ACCESSING ADDITIONAL INFORMATION WORDS IN OS/8

In all of these cases, the USR must have been previously brought
core with the USRIN function.

D.9.1

into

After a LOOKUP or ENTER

After a LOOKUP or ENTER, location 10017 points to the length word of
the file entry. To get a pointer to the first Additional Information
word, a program would execute the following code;
CDF 10
TAD I (1404
SNA
JMP NONE
TAD I (0017
DCA POINTER

/GET # OF ADDITIONAL INFORMATION WORDS
/FROM DIRECTORY

/NO ADDITIONAL INFORMATION WORDS

POINTER" now points to the first Additional Information Word.

D.9. 2

After a CLOSE

Because CLOSE is a legal operation even if no output file is

present,

following a CLOSE. To alter the Additional Information Words of a
permanent file, do a LOOKUP to get the directory segment into core,
then alter the words and rewrite the directory segment.

D.9. 3

Rewriting the Current Directory Segment

Whenever a user program changes the Additional Information Words of a
file, it must rewrite the directory segment containing that file entry
in order to make sure the changes are permeinently recorded.
The following code, which must be in field 1, will rewrite the current
directory segment:
CDF 10
TAD 7
AND (7
DCA SEGNO
CIF
JMS I 51

/CODE IS IN FIELD 1
/GET DIRECTORY KEY WORD
/EXTRACT SEGfffiNT NUMBER
/LOC 51 POINTS TO THE DEVICE HANDLER

D-9

4210
1400

/WRITE OPERATION
/DIRECTORY SEGMENT CORE ADDRESS

JMP ERROR

/ERROR REWRITING DIRECTORY

SEGNO ,

Location 10 051 will always point to the device handler entry point
used to read in the last directory segment, following a LOOKUP or
ENTER operation.

D.IO

SABR PROGRAMMING NOTES

D.10.1

Optimizing SABR Code

There are two types of lasers who will be using the SABR assembler
code
and
page-boundary-independent
those who like the convenience of
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
This is done by using the LAP (Leave Automatic Paging)
Yourself.
This
pseudo-op and the PAGE pseudo-op to force paging where needed.
page
the
of
elimination
from
page
per
instructions
4
saves 2 to
In addition, the fact that the program must be properly
escape.
segmented may save a considereible amount.

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

ANDI
TADI
ISZI
DCAI

0400
1400
2400
3400

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,
DCA X

SZA

is assembled by SABR into

LABEL,

SZA
JMS 45
SKP

DCA I

(X)

or four instructions and one literal.

D-10

The sequence
PX,

LABEL,

SZA
DCAI PX

Note,
assembles into three instructions for a saving of 40 percent.
however, that the user must be sure that the data field will be
Also note that the
correct when the code at LABEL is encountered.
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 X

SUBR,

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

BLOCK 2

This code requires 19 words of core and takes
microseconds to execute. The following sequence:

several

Code
I ARC,
SUBR,

BLOCK 2
TAD I SUBR
DCA X
INC SUBR#
TADI SUBR#
DCA lARG
INC SUBR#
HLT
/THIS IS A CDF
TAD I lARG
DCA lARG

takes only 14 wurds

cuid

executes

j.u

apprcxxniatej.y

D-11

^.^3

tus txmet

hundred

D.10.2

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 1
or above location 2000 in field 1. To call the USR from SABR use the
sequence

CPAGE n
6212
JMS 7700
REQUEST
ARGUMENTS
ERROR RETURN

/N«7+{# OF ARGUMENTS)
/GIF 10
/OR 200 IF USR IN CORE

/OPTIONAL DEPENDING ON REQUEST
/OPTIONAL DEPENDING ON REQUEST

To call a device handler from SABR use the sequences

CPAGE12
6202
JMS I HAND
FONCT
ADDR
BLOCK
ERROR RETURN
SKP
HAND,

/lO IF "HAND" IN PAGE
/GIF
/DO NOT USE JMSI

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

D-12

APPENDIX E
CHARACTER CODES AND CONVENTIONS

Table E-1 contains a list of the control characters used by OS/8 and
Table E-2 contains the OS/8 character
eissociated system programs.
set, which is a subset of the complete ASCII code, the unlisted codes
are generally not used by OS/8 or the system programs. Note the
following:
1.

On some terminals, the chsuracter back-arrow {-) is replaced
character, and the up-arrow (t) is
by an underline
(_)
replaced by circumflex C)

Some terminals use parity codes rather than forcing the
leading bit of the 8-bit character code to be a 1, To avoid
problems, OS/8 system programs always ignore the parity bit
during ASCII input.

OS/8 does not handle lower case characters (octal codes 341
through 372). The exceptions to this are the editors, EDIT
and TECO. The KL8E and LPSV handlers can be modified to
heuidle lower case.

Table E-1
OS/8 Control Chcuracters
Octal
8-bit
Code

Character
Name

Remarks

000

null

Ignored in ASCII input.

200

leader/trailer

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

203

CTRL/C

OS/8 break character, forces return
to Keyboard Monitor, echoed as tC,

207

BELL

CTRL/G.

211

TAB

CTRL/I, horizontal tabulation.

212

LINE FEED

Used as a control character by
Command Decoder and ODT.

213

CTRL/K, vertical tabulation.

214

FORM

CTRL/L, form feed.

E-1

the

Table E- 1 (Cont.)
05/8 Contrc 1 Characters
Octal
8-bit
Code

215

Character
Name

RETURN

Remarks

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

Used only on LS8E
Puts current line
cheuracter mode.

216

printer.
expanded

217

CTRL/0

Break Character, used to suppress
Teletype output, echoed as to.

225

GTRL/U

Delete current input

line ,

echoed

as tU.

232

CTRL/Z

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

233

ESC

ESCape replaces ALTMODE on sane
Considered equivalent
terminals.
to ALTMODE,

375

ALTMODE

break
Special
Teletype input.

376

PREFIX

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

377

RUBOUT

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

E-2

character

for

Table c-2
ASCII Character Codes

Octal
8-bit
Code
240
241
242
243
244
245
246
247

250

251
252
253
254
255
256
257

6-bit
Code

41
42
43
44
45
46
47

50
51
52
53
54
55
56

Punched
Card
Code

blank
11-8-2

Character
Representation

8-7
8-3

11-8-3
0-8-3

12
8-5

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

&
1

(
)

+
t

12-8-3
0-1

•

260
261
262
263
264
265
266
267

60
61

270
271
272
273
274
275
276
277

70
71
72
73
74
75
76
77

300
301
302
303
304
305
306
307

B
C
D
E
F
G

310
311

10
11

12-8

12-9

62
63
64
65
66
67

02
03
04
05
06
07

1
2
3
4
5
6
7

Remarks

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

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

1
2
3

5
6
7

8
9

8-2

•

11-8-6
12-8-4

•

8-6

0-8-6
0-8-7

colon
semicolon
less than
equals
greater than
question mark

8-4

at sign

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

E-3

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

6-bit
Code

Punched
Card
Code

312
313
314
315
316
317

12
13
14
15
16
17

11-1
11-2
11-3
11-4
11-5
11-6

320
321
322
323
324
325
326
327

20
21
22
23
24
25
26
27

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

330

331
332
333

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

32
33
34
35
36
37

334
335
336
337

Character
Representation

Remarks

J
K
L

M
N
O
P

Q
R
S

T
U

V
w
X
Y
Z

opening bracket, SHIFT/K
backslash, SHIFT/L
closing bracket, SHIFT/M

[

circtimflex

underline - EOF signal

NOTES
1.

These are the DEC029 stcuidard Ccurd codes.

On most DEC Teletypes circumflex is replaced by up-arrow (t).

A card containing 0-8-5 in column
columns blank is an end-of-£ile ceird.

On most DEC Teletypes underline

On some IBM 029 keyboards
cent sign (<=)

[

with

all

remaining

replaced

back-arrow

is graphically represented

On some IBM 029 keyboards \
logical NOT (-)

graphically

represented

On some IBM 029 keyboards
vertical bar

is graphically

represented

(

)

On a very few LP08 line printers, the character
is printed instead of backslash.

On a very few LP08 line printers, the character heart
printed instead of underline.

10.

The character number sign on some terminals
pound sign (#)

E-4

diamond

(0)

(c)

replaced

APPENDIX F
OS/8 INPUT/OUTPUT ROUTINES

Appendix F describes a set of generalized I/O routines for use under
the OS/8 system. The routines presented here are used in all the OS/8
CUSPS (Commonly Used System' Programs) in more or less this form.
Variations are made depending on the particular application and how
errors are to be handled. The routines, as indicated, will work as
The routines work most efficiently in field 1, since GIF
presented.
and the Commcuid
10 's are not necessary when addressing the Monitor,
Decoder tables are similarly available. Obviously the routines can be
modified to run in any memory field or core locations.

F.l

GENERAL DESCRIPTION

These subroutines assume that the Command Decoder tables have been set
up to indicate the proper I/O devices. The routines handle device
All I/O is done by
hemdler assignment without user interference.
The user program never needs to interface
simple subroutine calls.
All buffering and internal
with the Monitor or device handlers.
bookkeeping are performed by the routines. In these routines, it is
OOB Mill^rM

WAft«»te

V^««JkJf

%^AA^

\f%A*mff\A W

%A^ V ^««^

^tS

V*^«^«A

«.*

W^*M«.» f

^ « «« « f

*m*-b*

output routine does not automatically set up for the next output
device. This modification can be made if desired. As many as nine
When input from one device is
inputs are hcuidled automatically.
exhausted, the input routine will automatically utilize the next
device specified in the CcHimand Decoder list of inputs.

Following is a brief list of the subroutines and their functions.
ICHAR - Character input routine.
Call sequence:

JMS ICHAR
ERROR RETURN
NORMAL RETURN

F-1

Error:
No more
If AOO, an EOF on input has occurred.
If AC<0, a device error has
input is available.

occurred.

Nonnal
8

bit character is in the AC.

OCHAR - Character output routine.
Call:

TAD CHAR /8 BIT CHARACTER
JMS OCHAR
ERROR RETURN
NORMAL RETURN
Error:

AC<0 implies a fatal error.
implies that the hole
AC > or =
output was exceeded.

allotted

for

Normal:

The character heui been put into the device
output buffer.

AC««0.

lOPEN - Input initialize routine.
Call:

JMS lOPEN
RETURN
Return:

Input pointers reset. The next cetll to ICHAR
will read from the first device in the Command
Decoder input list.

OOPEN - Output initialize routine.
Call:
JMS OOPEN
ERROR RETURN
NORMAL RETURN

Error
If AC > or = 0, no output device was specified.
If AC<0, an error occurred opening the file.

Normal

No action
An output file has been opened.
the output was a non-file structured device.

F-2

OCLOSE - Output close routine.
Calls
JMS OCLOSE
ERROR RETURN

NORMAL RETURN
Error:

Either the closing length is too large for the
space allotted or an output error has occurred.
Normal
The output file is now a pemicuient file
output device.

F,3

the

SUBROUTINE PARAMETERS

These subroutines hcindle device assignment and internal buffering
automatically. To accomplish this, certain parameters must be defined
These parameters specify all details of handler
at assembly time.
location, and buffer size for the routines.

Parameter

Definition

INBUP =

Address of input buffer,

INCTL =

See the section on
Input buffer control word.
using device handlers for details of the control
word format,

OUBUF =

Output buffer address.

OUCTL =

This must be
Output buffer control word.
negative nuinber to indicate a wrxte operation,

INRECS =

Number of input records in input buffer.
INCTL/256 (DECIMAL),

INDEVH =

Address of input device handler.

OUDEVH =

Address of output device handler.

INRECS =

The parameters can either be a part of the actual subroutine source,
or they can be contained in a separate parameter file to be assembled
The latter approach provides greater
with the subroutine file.
flexibility in using the routines.

F.3.1

Example

simply calls the Command Decoder, and transfers input from the input
devices to the output file, closes the output, and exits.

F-3

FIELD 1
*2000
JMS I (7700

/LOCK MONITOR INTO CORE.

CALLCD,

/CALL COMMAND DECODER
/TO PICK OPTIONS.

JMS I (200
5

JMS I

/SETUP TO START LOOKING AT
/CD INPUT FILE.
/OPEN UP AN OUTPUT FILE.
/IF AC<0, WE HAD A FATAL
/TYPE ERROR. AOO IS O.K.
/ERROR.

(I OPEN

JMS I (OOPEN

OK,

TSTEOF

CLOSE,

OUTERR,
CLERR,

SMA CLA
JMP OK
JMS TERR
TEXT /OPEN FAILED/
JMS I (ICHAR
JMP TSTEOF

/EITHER ERROR OR EOF.
/SAVE IT.
/TRANSFER THE CHARACTER
/OUTPUT ERROR
/TRANSFER UNTIL EOF FOUND,
/IF NEC, FATAL
/EOF. CLOSE OUTPUT

JMS I (OCHAR
JMP OUTERR
JMP OK
SMA CLA
JMP CLOSE
JMS TERR
TEXT /READ ERROR/
JMS I (OCLOSE
JMP CLERR
JIfP CALLCD
JMS TERR
TEXT /OUTPUT ERROR/
JMS TERR
TEXT /CLOSE ERROR/

/CLOSE OUTPUT FILE.
/CLOSE ERROR
/NEXT,

TERR,

TAD I TERR
RTR;RTR;RTR
JMS TYPIT
TAD I TERR
JMS TYPIT
ISZ TERR
JMP TERR+1
TYPIT,

CRLF,

AND (77
SNA
JMP CRLF
TAD (300
JMS TTYOUT
JMP I TYPIT
TA (215
JMS TTYOUT
TAD (212
JMS TTYOUT
JMP CALLCD

TTYOUT,
TLS
TSF
JMP.-l; CLA; JMP

TTYOUT

F-4

F.3.2

Subroutine Listing

A listing of the routines follows. The parameters are set up in such
Another
to allow them to be put into a separate file.
as
a way
parameter, ORIGIN, determines the location of the routines.

F-5

PAL8-V7

12/27/72

P*GE

/PA««MtTfeH ntHNITlOlsii

iOnn
bhat^

OUHUF= 500H
OUCTL* 420M
QUDEVH sb60U

buid!^

INdUf-" 5«i5l)

Ziva
0001

INCTL* 0200
INRECS Bl
INUEVH 7000
OHIGIN 6600
UC8=7760

Ud,)Vi

700f')

bbUd
/7b<?
HI' 01

FIELD

bbiifl
0titU)

•ORIGIf

7UH('1

H.b01
ibboa

BHUt!

lh^Pi3
ifab^a
IbbtiS

TAU
OCA
JMK

Ifabll

(IIH.'C'

lb612

OQvia

1C613
lbbl4
Ib6l5
Ibblb
lbbl7
lb620
lbb?l

Bgtin

7bO0
b2ia
l?a5
3331

bam

lbb?3

2360
2333
53H0

lhfci;4

12113

IbbeS
lbb2b
lbb27

7bba
5231
«33J
b2/7
12H1

IbbSPl

Ibbil

16632
16633
ibbsa
16635
lbb3b
16637

/INITIALIZE INPUT

1-3 7 7

eno0

7uin
13/6
7420
3201

DC A
ISZ

INtOK,
INFPTH,
INPTH,

a
B

ICmAH,
lN7bU0,

INCHAR,

Gf, rNtw,

INIjHuF,

INCHCT
INEOF
C7617
INFPTR
lOPEN

/SET TO READ FROM NEW DEVICE.
/FORCE A NEW INPUT FILE.
/POINT TO CD INPUT LIST.

TbUZ
HDF
TAD
OCA
COF
ISZ
iSZ

IMJMPP,

/INPUT BUFFER FILED
/OUTPUT BUFFER FIELD

Tiidl'i

CLA CMA

3H11
5hei

Ibb?.?

iN7«wn,
lOPEN,

ratp
3333
2210

IhbUb
ibbe7
IbblB

1
I

INFLD« INCTL&70
nuFLn»iOUCTL«70

HUil^
IfebCip

/OUTPUT BUFFER STARTS AT 05000.
/AND IS 2 PAGES LONG.
/OUTPUT HANDLER GETS LOADED AT 6600. WE
/ALLOW TWO PAGE HANDLERS,
/INPUT BUFFER STARTS AT 05400
/ALSO TWO PAGES LONG.
/2 PAGES « 1 RECORD
/ALLOW 2 PAGE INPUT HANOLtR AT 7000.
/THE SUBROUTINES RESIDE AT 16600,
/DEVICE CONTROL TABLE

JMP
TAD
SNA
JMP
JMS
JMP
TAD

7 4 30

CUL
TAD
SNL
OCA
bZL

2210

iSZ

/INPUT

CHARACTER.

/SAVE CALLING FIELD FOR RETURN
INCDIF
INHTRN
INFLD
INJMP
INCHCT
INJMP
INtOF
CLA
INGBUF
INNEwF
EOFtRR
INCTR

/DATA FIELD TO FIELD OF BUFFER
/3 - WAY UNPACKING SWITCH
/INPUT BUFFER EXHAUSTED?
/NO. .UNPACK THE NEXT CHAR.
/DID LAST READ GIVE EOF ON THIS DEVICE?
/NO. CONTINUE READING.
/VES..GET NExr INPUT IF IT EXISTS.
/TAKE EOF EXIT FROM ICHAR.
/INCTR HOLDS THE CURRENT LENGTH OF
/The INPUT FILE. WHEN THE AMOUNT REMAINING
/TO READ IS LESS THAN THE SIZE OF THE
/INPUT BUFFER, AN EOF IS SIGNALLED,

(INWtCS
INCTR

/UPDATE REMAINING LENGTH

INEOF

/AND SIGNAL EOF FOR NEXT READ.

PALfl-V7
tht-ad
Ihbttl

7172

lhh«2
lhh«3

7012
lS7b

/fll2

CLU CML CMA RTR
RTR
RTR
TAD
CINCTL*1
OCA
INCTLW

12/27/72

PACE l-l

/CONSTRUCT A CONTROL WORD FOR THIS
/READ FROM THE OVERFLOW, IF ANY,
/AND THE STANDARD CONTROL WORD.

PALfl-VT

lhfc«5
166<lf>

Ibba?
Ib650
IbfeSl
IbfcSS

16653
lb65a
lt.b55
lh«»bb

lbb57
IbbbB
Ibbbl
Ihbba
lbb63
Ibbba
IbbbS
Ihfebb
IbfcbT

6203
6211
Hint
0000
5a00
0000
5273
1252
137b
325?
1250
0214
7104
125H

1251

3212

lbb72
1bb73
lbb74
)bb75
lb67b
lb677
lb7B0
IbTBl

52<;0

lh703

2210
7700
5254
7330
5331
740a
5322
531b
1223

lfa704

33U(d

1670S
lb70b
lb707
lh/10
)b7lJ
Ib7j2
16713

lh7m

1613
0200
7112
7012
1?S0
70 1?
7012
2212

Ib?!^
Ib7lb
16717
167?0
lb7dl
lh7?a

5323
1612
0200
3250
2212
161?

lb7«?3
167iea

13574

16725

7450
5227
1372
2213

167t'6

INBRtC,

7040
3333
1223
3300

lfab7l

lbfe7
16730

INCTLW,
INBUKP,
INREC,

02l<*

lbb70

lb7P)3

iNCOiF,

157 3

INERKX,

INERK,
EOKEKR,
INJMP,

ICHAK3.

INg00,

ICHArt?,

IChAKl,
INCOMN,

GIF COF
CDF
JM5 I

INHNOL

PAGE

/NOW DO A CALL TD THE INPUT HANDLER
/WE ARE IN FIELD 1, HANDLER IN FIELD

/INPUT CONTROL WORD
/INPUT BUFFER ADDRESS
/POINTER TO INPUT RECORD

INrtuF

JMP
TAU
TAD
OCA
TAO
AND
CLL
TAD
ANU
CMA
DCA
TAD
OCA
TAO
OCA
JMP
ISZ
SMA
JMP
CLA
JMP
MLT
JMP
JMP
TAU
OCA
TAD
AND
CLL
HTH
TAO
HTR
RTR
ISZ
JMP
TAU
ANU
DCA
iSZ
TAD
AND
TAU
SNA
JMP
TAO
ISZ

ia/27/7a

INtRRX
INREC
(INRtCS
INREC
INCTLW
1N76B0

/UPDATE POINTER INTO FILE
/NOW COMPUTE THE NUMBER OF CHARACTERS
/INTHIS INPUT OUPFER

RAL

INCTUW
IN7600
INCHCT
INJMPP
INJMP
INBUFP

/NEW NUMBER OF CHARACTERS.
/RESET 3 WAY StilTCH

INiPTH

/AND BUFFER POINTER
/NOW READ THE BUFFER
/SET EOF JUST IN CASE
/IF <0, A PHYSICAL ERROR
/EOF ON INPUT
/FATAL
/GET OUT
/3 WAY UNPACK SWITCH
/GET 1ST OF 3

INCHAH
INtOF
CLA

INOKEC
CLL CML RAR
INRTRN

ICMAHl
ICHAHa
INJMpP
INJMP
INPTR
IN7400

RTh

/SECOND
/SET FOR FIRST CHAR, NEXT
/THE THIRD WORD IS MADE QF THE HIGH
/ORDER FOUR BITS OF THE FIRST
/TWO,

INCTLW
INPTH
INCOMN
INPTR
I
IN7400
INCTLW
INPTR
I
INPTH

/POINT TO NEXT WORD
/GET OUT WITH CHAR IN AC
/SAVE HIGH ORDER FOR THIRD WORU

(377
C-232

/IS IT

GETNEW

/YES. .LOOK AT NEXT INPUT

-Z

(EOF)?

(232

ICHAR

/TAKE NORMAL RETURN

PAL6-VT
INkTKN,

1(>733

777 7

lh73i(

6733
bil\

INNEwF, -I
INCHCTa INNthF
CDF
10
(INDtVH*!
TAD
INHNRL
DC*
TAD I INFPTH
SNA
INNEWF
JMP I
iNgee
JMS I

Jfc.7i5

1371

lh736

33<t4

lt-7i7
Ifr7il0

1611
7«5«

lb7<H

5733

lfc7aa

it70h

Ib7u3
lh744
Ih7u5
1^746
Ib7u7

0001
0000
7^02
1611
0370
7440
1367
7132
7012

\hTi?i

16751
\hT33
1^753
Ih/Sa
lh7!55

lh756
16757
16760
16761
1676?
16763
16767
16770
16771
1677?
16773
1677a
16775
16776
16777
17 000
1 7CT01

17nM2
17H03
170B«
17005
17 006
17007
17010
17011
17012
17013
170ia
17015

PAGE

/CIF CDF N.

0000
5613

16731
lb73a

ia/27/72

JMP

IChArt

/INITIALIZE IN CASE wE NEEU
/MORE INPUT?

NEW

/NOPE
/CALL MONITOR TO GET HANDLER

INHNULf
/VERY UAOl

HLT
INI-PTH
TAD I
AND
(7760
SZA
TAD
C17
CLL CML RTR
RTR
DCA
INCTH
INFPTR
ISZ
INFPTR
TAO I
DCA
INHEC
INFPTR
ISZ
OCA
INEOF
INNElvF
ISZ
JMP I
INNEwF
INCTRiilOPEN

3?fcl
£«ill

1611
32^2
2211

3210
2333
5733
6601
0017
7760
7001
0232
7546
0377
0201

/GET INPUT FILE LENGTH

/NEGATIVE OF FILE LENGTH
/POINT TO STARTING BLOCK

/STORE IN HANDLER CAUL
/NEXT INPUT,
/CLEAR EOF FLAG.

O0l'il

7617
70P0
0000
7600
lidl
3221
1377
3214
1601
0376
7050
524a
4775
0001
0000
740P

PAGE
OOPEN,

/OPEN OUTPUT FILE
7600
TAO
OCA
TAO
DCA
TAD I
AND (17
SNA
JMP
JMS 1

OIJ76U0,

UU7601
OUHUK
(OUDtVh+1
OUHNQL
OU7600

/POINT TO OUTPUT FILE NAME IN CD
/AREA

/INITIZLIZt OUTPUT DEVICE HANDLER
/PICK UP OUTPUT DEVICE NUMBER

ONOFIL

/IS THERE ONE?
/NO, .INHIBIT OUTPUT

(200

/FETCH OUTPUT HANDLER

OUHNUL

•

hLT

/BAD THING

PALB-VT
170^2
170P3
17024
17025
17026

00(90

J7e'?7
17(130

ClOHETN,

17P31

2200
6213
5600

17(332

1601

OtFAiLf

i?e:<i3

0372
7650
5242

17034
17^35
17036
17037
7040
17041
17042
17043
17044
17045
17046
17047
17050
17051
17052
17053
17054
17055
17056
17057
17060
17061
17062
17063
17064
17065
17066
17067
17070
1

IV 071

17072
17073
17074
^075
17076
17077
17100
17101
1

1710-^

17103
17104
n\h'-:

OUfcLtN,

5232
3350
3774
47 7 3

1601

0376
3601
5216
7330
5230
2774
5230
0000
3300
6211
17 7 4

7640
5304
1350
7450
2300
1221

3302
1300
7106
7006
7006
0376
1350
3350
1350
7120
1222
7660
5646
6203
6211
4614
0000
5000
0000
74 10

2246
5646
0020

ONTEKRi
ONOFIL*

JMH
OEFAIL
OCA
OUCCNT
OCA I
(DIJTINH
JMS I
(OIJStTP
ISZ
OOPEN
CDF CIF 10
JMF I
OOPEN
TAU I
OU7600
AND
(7760
SNA CUA
JNP
ONTEKR
TAO I
OU7600
AND
(17
OCA I
OU7600
JMP
OUENTR
CtA CLL CML RAH
JHP
OOKF-TN
ISZ I
(OUTINH
JMP
OORETN

DUTOnP,
OCA
OUCTtW
CDF
10
TAO I
(OUTINH
SZA CLA
JMP
UUNOtuR
TAD
OUCCNT
SNA
ISZ
OUCTLW
TAD
OUBLK
OCA
OUREC
TAU
OUCTLW
CLL
RTL
RTU
RTL
ANU
(17
TAD
OUCCNT
OCA
OUCCNT
TAO
OUCCNT
CLl. CML
TAO
OUELEN
SNL SZA CLA
JMP I
OUTDMP
oiicinF, CIF CDF
COF
10
JMS I
OUHNOL
OUCTLW,
OUbUF
OUREC,
a
SKP
OUnOi»(R. ISZ
nUTOMP
JMP I
UUTOMP
PTpi0020

12/27/72

CAGE

/GETS SUE OF HOLE AVAILABLE
/FAILURE. SEE HHAT WE 010,
/CLEAR CLOSING LENGTH
/CLEAR OUTPUT INHIBIT
/SET UP POINTERS

/RETURN O.K.
/IF LENGTH»8, GIVE OPEN ERROR
/IF NOT, MAKE IT
AND TRV AGAIN
/MAS 0. FAILED

/MAKE IT a
/AND TRY AGAIN

/INHIBIT OUTPUT
/DUMP OUTPUT BUFFER
/STORE CONTROL WORD
/IS OUTPUT INHIBITED?

/VEP.
/IF THIS IS FIRST WRITE, START THE
/SEARCH FORMARD ON OECTAPE

/GET STARTING BLOCK OF THIS
/TRANSFER

/COMPUTE

OF RECORDS TO OUTPUT

/UPDATE CLOSING LENGTH
/SEE IF CLOSING LENGTH WILL BE
/BIGGER THAN OUTPUT HOLE

/WILL BE TOO BIG
/DO THE WRITE

/ERROR
/TAKE NORMAL RETURN

PALa-V7
1701t.

160J

17Bt7
17020
17021

4775
0003
7601

OUtNTH,

T40
JMS

OU7fcl>10

(2ea

X2/27/72

PAGE 3-1

/ENTER THE OUTPUT FILE

OUl^L^,

7faBl

/GETS STARTING BLOCK DF HOLE

P*L8-V7
1711^6

171M7
17110
57111
17112
17113
17111
nii-j
1711b
17 117
17 120

17121
17122
17123
17124
1712b
17126
17127
17130
17131
17132
17153
171 Jfl

17135
17 lib
17 137

17140
17141
17142
17143
17144
17145

0000
6211
1774
7640
5352
4771
03 7

1372
7640
1367
4766
5353
4766
5353
4766
5353
4771
7710
1365
1364
0763
7640
5324
1763
137S
745D
5344
1362
4246
5353
1601

17153
17154

4775
0004
7601
0000
7410
2306
6213
5706

171 fc2

<40?!0

17163
17164
17165
17166
17167
17170
17171
17172
17173
17174
17175
17176
17177

7272
0077
0160
7211
0232
0770
7274
7760
7200
7373
0200
0017
6601

1714«)

17147
17150
17151
17 152

OCLOSjEi

12/87/72

PAGE

/CL50E OUTPUT FILE

COP
10
TAD I
(OUTINH
SZA CUA
JMP
OCISZ
JMS I
(OTVPE
AND
(770
TAO
(-PTP
SZA CLA
TAO
C232
(OCHAN
JMS I
JMP
OCRET
JMS I
(OCHAK
JMP
OCRET
CQCHAR
FILWIP. JMS I
JMP
OCRET
JMS I
(OTYPE
SPA CLA
TAO
(100
TAD
(77
AND I
(OUDWCT
S7.A CLA
JMP
KILLIP
TAD I
(OUDtHCT
TAD
(OUCTL»3T00
SNA
NODUMP
JMP
TAO
caeBie^ouFLD
OUTOMP
JMS
JMP
OCRET
NOOUMP» TAD I
DU7600
JMS I
IZZHS

/IF OUTPUT INHIBITED, CLOSE IS

7601

OUCCNT,
OCISi,
OCRET,

SKP
ISZ
OCLCISE
CDF CIF 10
JMP I
QCLQSE

NOP,

/A NOP

/DETERMINE IF OUTPUT IS TO PTP
/IF IT IS, DON'T OUTPUT A "Z,
/NOT PTP, OUTPUT -Z *S EOF

/ERROR RETURN
/FILL WITH a CHARACTERS
/FILL TO BOUNDARY WITH
/IF OUTPUT IS DIRECTORY DEVICE, FILL

/MHOLE RECORD, ELSE HALF RECORD
/ARE WE UP TO BOUNDARY YET?
/NO
/IS THERE A FULL WRITE LEFT?

/YES. BUT DON'T DO IT,

AS "Z

/DUMP LAST BUFFER
/GET DEVICE NUMBER
/CLOSE THE OUTPUT FILE

0U76k)1,

/POINTER TO FILE NAME
/CLOSING FILE LENGTH HERE
/ERROR
/NORMAL RETURN
/RESTORE CALLING FIELDS

IS OUT.

PAL8-V7
7203
17200
17201
I7afi2

172P3
17204
17205
172Plh

17?H7
17210

awn
1377
7041
3272
1376
3270
1271
3224
5<J0W

12/27/72

PAGE 5-1

PAGE
OUSETP,
TAD
CIA
DCA
TAO
DCA
TAD
DCA
JMP

/INITIALIZE OUTPUT POINTERS
(OUCTL&370B

OUDKCT
(OUBUF
OUPTR
OUJMHE
OUJMP
OUSETP

/DOUBLE WORD OUTPUT COUNT
/INITIALIZE WORD POINTER
/3 WAY UNPACK Sv^ITCH

PAL«-V7

i7?n

BBHOI

17?18
17213
17211

0375

17-'1'3

1721b
17217
17220
17221
17222

32fcb

6211
1371
3261
127 i
761^1

172,'^

5263
6201
2221

1722a

7iia2

1722'3

5261
5256
1266
7106
70ph

17226
17227
172ii^

17251
17252
17233
17231
17235
17236
17 2 3 7

17210
172U1
17212
17243
172U1
172l'5
172146

17217
172I5B

172S1
172-32

17253
17251
172'35

17256
17257
172»,0

17261
17262
17?63
17261
17265
17266
1726/
17270
17271

17272
1/2/3
17271
172/5

0CH4K,

k3373

1667
3667
1266
7112

7012
raid
^iJi
167H
3b7H
1271
3221
22;n
2272

5263
1372
1/71
5261
420Cil

5263
127H
3267
2270
1266
36/H
2211
7102
5611
00U)0
apitu
MOtiO

5221

OUPOLO,
OUPTK,

OkH'.l
0Mf1C.)

OTYPt,

6211

CCie-

CDF

DCa
OUCRtT
TAD
OUTIhH
SZA CL*
JMp OUCOHN
nUCHAH, CDK
OUFLU
OUJMP
ISl
OIIJMH,
MLT
OChAwi
J MP
JMP
0CHAH2
DCMAf<3f TAD
OUT e MP
CLU RTU
WTL
AND
(7100
TAD I
OUPOI.D
QUA I
OUPDI.D
TAD
CUTEMP
CLU KTH
RTW
RAK
AND
(7 4011
TAO I
OUPT«
DCA I
UUPTK
TAO
CjUJMiPE
OCA
OUJMP
OUPTP
ISZ
ISi
01)Ul»CT

niJJMPE.
OIJDWCT,
OUTIivH,

acipti

QUTEMP

RDF
TAU

(37/

PAGE 6

/OUTPUT CHARACTER ROUTINE
/ISOLATE EIGHT BITS

AND
OCA

JMP
TAD
JMS
JMP
JMS
JMP
DCM4H2, TAU
OCA
ISZ
OCHAKl
TAD
OCA
aiJCOMM. ISZ
OUCHtT, HLT
JMH
OUTEMP. a

12/27/72

OUCOMN
(uuCTt
(OuTDMP
DUCKET
OUSETP
OUCOMN
OUPtH
OUPOLD
OUPTR
OUTEMP
OUPTR
OCHAR

/GET FIELD WE wERE CALLED
/FROM

/OUTPUT INHIBITEO?
/YES, NOP,
/GO TO DATA FIELD OF SUFFER
/BUMP CHARACTER SWITCH
/GETS JMP., JMP. I, ETC.

/ThiKO CHAR
/HIGH ORDER BITS GO INTO THE
/HIGH ORDER a HITS OF THE
/FIRST OF TWO WORDS
/THE SECOND DOUBLE WORD GETS
/THE LOW ORDER BITS OF
/THE THIRD CHAR

/RESET CHARACTER SkilTCh
/POINT TO NEXT BUFFEH WORD
/BUMP DOUBLE COUNT AFTER
/3 CHARS.
/GET OUT
/RtADV TO OUTPUT A BUFFER
/OUTPUT IT
/AN ERROR
/RESET OUTPUT POINTERS
/POINT TO FIRST DOUBLE WORD

/POINT OuPTR TO SECOND

/NORMAL EXIT

OChAH

JMP

RDF

OUJMP

/OTYPE LOOKS AT THE OUTPUT DEVICE

»,

PAU8-V7
J7?7fe

137a

17277
17300
17301
1730?
17303
1730a
173H5
1730h
17307

iiiib

6?11
177a
k33fc7

1366
3266
1666
IDS?.

S67a

OTHTN,

TAD (CIF CUF
OCA
OTHTN
CDr
IB
TAD I
(761^0
AND
(17
TAO
(OCB-1
OCA
OIJTtMP
TAD I
OUTfcMP
HUT
JMP I
OTYPt

12/27/72

PAGE 6-1

/AND LOOKS UP THE OCB WORD FOH
/THAT DEVICE.
/GET OCB ENTRY

PAua-VT
173t.b

77b/

l/3b7
W37C1

10017

)7W1

IVUh
a£0O
7U00
6203
0377

17372
173 7 3

1737a
)7i75
J7376
17377

0?0:i)

FIELD
•20e)0

12tl(i0

<J777

mnw

JMS

laptii
Ir'flkia

4776

l?klH3

aP!t55

12«H4

i/)ak)0

12^115

4775
«774
77K0
522d
4263
1720

12P10
12011
12012
12G13
12014
12015
12?lb
12C!ilT

12P20
12l121

12022
12023
12li'24

121325

12P26
12027
12030
12031
12B32
121.133

12P'34

12035
l2M3fe
12(»37

SBCiW

aiicii?

ler'B7

P*GE

7bCilB

anei

12PH6

12/2;/72

(7700

/LOCK MONITOR INTO CORE

(200

/CALL THE COMMAND DECOOER

CALLCD,

JM3
5

JMS I (lOPEN
/SETUP INPUT POINTERS
JMS I (OOPEN
/OPEN OUTPUT FILE
SMA CLA
/ERROR, IF AC<0, IT WAS KATAL
JMP OK
/NON FILE STRUCTURED OUTPUT
JMS TERR
TEXT /OPEN FAILED/

0?.16
40k)6

0111

MBS
04^0
4773
S227
/4b0
322a
4772
5243
5223
770(?)

OK,

TSTEOF,

5240
4263
22a5
0104
4005
2222
1722

JMS I (ICHAR
/READ A CHARACTER
jMp TSTEOF
/ERROR, SEE IF EOF.
SNA
/IGNORE BLANKS
JMP OK
JMS I (OCHAR
/AND OUTPUT THE CHARACTER
JMP OUTERR
JMP OK
/CONTINUE UNTIL EOF.
SMA CLA
/WAS IT FATAL?
JMP CLOSE
/NO, .EOF. CLOSE OUTPUT
JMS TERR
TEXT /HEAD ERROR/

00Hti

12P40
12P41
12042

4771
5253

12K43
12044
12045
12046
12047
12050

4263
1725
2420

CLOSL,

5202

eiStfa

4005
2223

OUTEKW,

JMS 1 (OCLOSE
JMP CLERR
JMP CALLCD

/FILE CLOSE FAILED
/NEW INPUT,

JMS TERR
TEXT /OUTPUT EHROR/

PAL8-V7
laCbl

l<?Hb3

4263

12054
12355

13314

124156

1T23
0540

12H57

06(:il

12Phl?l

1114
0504
0000

120^3
12064
12065
l?nb6
12P67
12070
12071
12072
12073
12074

0tnio

12P175

0C1(1H

12076

0370
7 450
5304

1?P!77
121(7)0

J2tHl

l^\v^
12103
12104
12105
12U16
12107
12110
12111

12H2

PAGE 7-1

1722

125152

120^1
12062

12/27/75

CLERK,

TEKR,

1663
7012
7012
7012
4275
1663
4275
2263
5264

60i«l

12165
12166
12167
12170
12171
12172
12173
12174
12175
12176
12177

0212
0215
0300

5313
721^0

5711

TErtH

JMS
T40
JMS
ISZ
JMH

TYPIT
TEXH
I
TYPIT
TERR
TERR+1

/TYPE THE CHARACTER

ANO
SNA
JMf
TAO
JMS
JHP
TAD
JMS
TAO
JMS
JMH

(77

/ISOLATE THE CHARACTER

CRLF

/0 TERMINATES

TYPIT,

CSUF,

5202

12113
12114
12115
12116

RTH>RTP>RTR

4 311

0000
6046

/ROUTINE TO PRINT ERROl
TAD

.1367
4311

5675
1366
4311
1365

JMS TERR
/CLOSE FAILURE
TEXT /CLOSE FAIUEO/

(30(9

TTYOUT
TYPIT
I
(215

TTYOUT
(212

TTYOUT
CALLCD

TTYOUT,
TLS
TSF
JMP .-1
CLA
JMP I TTYOUT

^1077
71 £6

7211
66 1 i
7000

6601
0200
7700
sss-^txisss

PAL6-V7
CALLCD aaea
Cl.fcHR
3053
CLOSE acsaa
CKI.F
Hiaa
77bia
0C&
EUFt«R 6f>77
FILLIP 712«
GtTNtW 6627
ICHAR 6613
ICHARl 6732
ICHAR2 6716
ICHARS 6703
INBREC 665a
iNoijF
saeo
INBUFP 6651
INCDIF 66a'5
INCHAR 662(1
INCMCT 6733
INCOMN 6753
INCTL 02Pm
INCTLw 6650
INCTR 6601
INOtVH 7000
INEtlF
66ia
INEHR 6676
INtHRX 6673
INFLO 0000
INKKTH 6611
iNGhUh 6631
INHNOL 67fta
INJMP 670(1
INJMPP 6633
INNEWF 6733
INPTR 6612
6652
INReC
INRECS tlHtJl
INRTRN 6731
6706
IN2t10
IN7«0W 66013
IN7600 661«
lOPEN 6601
NOOuMP 7ioa
OCHAR
72J1
DCHARl 7261
QCHAR3 7356
OCHArtS 7237

OCISZ
OCLOSE
OCRtT
OEFAIL

7152
7106
7l5i
7M32
Ors
3020
ONDt-IL 70au
ONTERR 7042
OOPEN 71100
OORtTN 7030

ORIGIN 6600
UTr^TN
7306
OTYPE 7274
7021
OUOLK
OUbUF 5000
OUCCNT 715H
UUCDIF 7075
UUCHAR 7223
UUCOMN 7363
OUCRET 736<l
OUCTL 4200
OUCTLW ri00
OUUEVH 6600
OlJOhCT

OUkLEN
UUtNTR
OUKLU
OUHNDL
UUJMP
UUJMPt

7272
7032
T016
CII000

70ia
7224
7271
UIJNOInR 7104
uukolo 7267
OIIPTH
7370
(JUKEC
7103
ODSETP 7200
0UTI1MP 7046
UUFEnP 7266
OUIEHH 2043
UUt INH 7373
UU760O 7001
uu76ai 7147
PTP
0030
TERR
2063
TSTEOF 2037
TTtOUT 2111
nPlT 3075

ia/27/72

PAGE 7-2

INDEX
Additional information words, 1-3,
•3-7
n-Q
^ Alphanumeric option. Command
Decoder, 3-3
switches, 3-6
ALTMODE key, 3-3
Ascertain device information
(INQUIRE function) , 2-13
ASCII character codes, E-2, E-3
ASCII files format, A-4
ASSIGN command, 1-6
Asterisk, caution in using, 3-9
-

Batch mode, 3-10
Batch operating system, 1-5
Binary file format, A-4
Block, core control, 1-4
Blocks
directory, A-1
system scratch, B-1
Blocks of words, 1-2, 1-3
BUILD program, 5-1

Call Command Decoder (DECODE
9— in. ?-?
in Special Mode, 3-9
«,,-_4.^nn\

Calling device handlers, 4-1
Calling USR and device handlers
from SABR code, D-13
Card codes, DEC029, 4-7
Card Reader (CDR) operation, 4-7
Card Reader handler modification,
D-2

Carriage return/line feed suppression in FORTRAN, D-4
Cassettes operation, 4-6
CCL, 3-10
CCL error messages, C-4
CHAIN f.miction, 2-10
Character codes
ASCII, E-2. E-3
OS/8, E-1
Character mode, expanded, 4-6
Character packing format, 5-8
Characters, lower case, E-1
character, 4-5
Circumflex
CLOSE function, 2-8, D-9
Code, non-paged, D-10
Command Decoder
calling, 3-3
conventions, 3-1
error messages, 3-3
errors summary, C-7
example, 3-6
options, 3-3

output files, 3-4
special mode, 3-8, 3-9
tables, 3-4
COMMON area, 2-12
Control characters, OS/8, E-1
Conventions
Command Decoder, 3-1
OS/8, E-1
Core control block, 1-4, 2-11, A-5
Core image files (.SV format), A-5
Core origin, A-6
Core segment doublewords, A-6
Core size, PDP-8 computers, D-5
software, 1-6
Co-resident device handlers, 2-6
Creating files, 1-3
Data exchange in core, 2-12
Data field value, 2-2
Data transfer, 4-1, 4-2
DATE command, 1-3, 2-7
DECODE function, 2-9
DECtape operation, 4-1
Default file storage device, DSK,
D-1
Deleting tentative files, 2-14
Device control word table, B-6
Device dependent operations, 4-4
Device handler
entry point, 2-14, 5-8
information table, B-5
residency table, 2-15, B-5
Device handlers
device dependent operations, 4-4
Card Reader (CDR) , 4-7
Cassettes operation, 4-6
High-Speed Paper Tape Punch
(PTP) , 4-5
High-Speed Paper Tape Reader
(PTR) , 4-4
file structured devices operation,
4-11
TD8E DECtape, 4-11
TM8E Magtape, 4-8
Device handlers, 1-1
calling, 4-1
co-resident, 2-6
inserting into OS/8, 5-5
loading dynamically, D-7
notes on loading, D-7
writing, 5-1
Device length table, B-7
Device names and numbers, 1-6
DEVICE pseudo-op, 1-7
Devices, file structured, 1-2
DF32 disk operation, 4-11

INDEX-1

Direcr calling sequence, 'JSR, 2-2
Directories, file, 1-3
Directory block structure format,
H-1
Directory entries, A-2
Directory example, A-3
Directory segment, rewriting, D-9
Directory, system, 5-4
Dismiss USR from core, 2-12
Dot (.) used as system response, 1-6
Doublewords, core segment, A-6

Form feed, 4-5
FORTRAN Library File Format, A-7
Functions, USR see USR functions

High-Speed Paper Tape Punch (PTP)
operation, 4-5
High-Speed Paper Tape Reader (PTR)
operation, 4-4
Horizontal tab, 4-5

Indirect calling sequence, USR, 2-2
Information words, additional, 1-3,

Empty file entry, A-2
Empty files, 1-3
End-of-file card, 4-7
End-of-file condition, 4-2, 4-3
ENTER output (tentative) file
function, 2-6, D-9
Entry points for device handlers,

2-7

accessing, D-10
Input file format, 3-2
Input files. Command Decoder, 3-5
Input/output routines, F-1
Input table. Command Decoder, 3-9
INQUIRE function, 2-13
Inserting device handlers into
OS/8, 5-10

5-2

ERROR function, 2-11
Error messages, Command Decoder,
3-3

Error messages summary, C-1
Error returns, device handler, 4-2
Exit to Keyboard Monitor, 1-1
Expanded character mode, 4-6
Extensions of file names, 1-2

FETCH device handler function, 2-4,
4-1
File creation, 1-3
File directories, A-1
block format, A-1
entries, A-2
example , A-4
formats, A-4
number A.-3
size, A-3
File extension, omission of, 3-2
File length restriction. Command
Decoder, 3-5
FILENAME pseudo-op, 1-7
Files, 1-2
additional information words, 1-3
devices, 1-2
directories, 1-3
names, 1-2
types, 1-3
File' structured devices operation,
4-11
Formats for
character packing, 5-3
command line, 3-1
directory block structure, A-1
files, A-4
FORTRAN Library File, A-7
input file, 3-2
Job Status Word A-6
,

INDEX-

Job Status Word, 1-5, A-6

Keyboard Monitor, 1-1
error summary, C-3
KL8E terminal handler, 4-12
LAP pseudo-op, D-10
Layouts for OS/8 system, B-1
LING tape operation, 4-7
Line Printer (LPT) operation, 4-5,
4-6
Load and start subprogram, 2-11
Loading device handlers dynamically,
D-7
2-12
Lock USR in core (USRIN)
Logical blocks, 1-2
LOOKUP permanent file function, 2-5,
D-9
Lower case characters, E-1
,

Names of devices, 1-6
Names of files, 1-2
Number and size of OS files, A-3
Numbers of devices, 1-6
Numeric option, Command Decoder, 3-3
ODT breakpoint, 2-11
Operations, device dependent, 4-3
Options
Command decoder, 3-3, 3-6
Origin of core, A-6
Output files, Command Decoder, 3-4

PAGE pseudo-op, D-10
Permanent device name table, B-4
Permanent file, 1-3
deletion, 2-8, 2-9
entry, A-2
Physical blocks, 1-2

Tables
Command Decoder, 3-4
device control word, B-6
device handler information, B-5
device handler residency, B-5
device length, B-7
permanent device name, 3-4
system device, E—
user device name, B-4
TD8E DECtape
operation, 4-11
Teletype operation, 4-4
Tentative files, 1-3
closing, 2-8
deletion, 2-4
entry, A-2
Terminal handlers
1-page, 4-4
2-page, 4-12

3-5
Procram, see 3pecij.ic suoject
Prcgramiaing notes, D-1
PRTC12-F used to convert DECtapes
to LINCtapes, D-6
Pseudo-ops
DEVICE, 1-7
PIP,

Punch card codes, DEC026, D-3
Records (definition) , 4-1
outputting odd number of, 4-3
RESET system table, 2-14
Resident program layout, B-2
RESORC, B-7
Restrictions to USR calls, 2-2
RETURN key, 3-3
RF08 disk
operation, 4-11
RK8E handlers, 4-11
ROM (Read -Only-Memory)
B-3

Up arrow (+) character, 4-4
User device name table, B-4
1-1,
User Service Routine (USR)
,

2-1

available location in area, D-9
calling, 1-6, 2-1
calling sequences, 2-2
errors summary, C-2
restrictions on standard call,

SABR programming notes, D-10
SAVE command, 1-4, 2-11
Scratch blocks, B-1, B-2
Signal user ERROR function, 2-11
Size of OS files, A-3
Software components, 1-1
Software core size, 1-6
Special mode of Command Decoder,
3-8

calling, 3-9
operation, 3-9
Standard USR call, 2-1
restrictions, 2-2
START command, 1-4
Starting address of program, 1-4
Storage space, additional, D-9
Storage words, 1-3
Subroutine
examples, F-4
functions, F-1, F-2
listing, F-5
parameters, F-3
Summary of USR functions, see USR
functions
•SV file, 1-4
System DATE, 2-7
System device layout, B-1
System devices, 1-6
System device table, B-4
System halts error messages
summary, C-1
System table values, Command
Decoder, 3-7

2-2

USR functions
CHAIN, 2-10
CLOSE, 2-8
DECODE, 2-9
ENTER, 2-6
ERROR, 2-11
FETCH, 2-4
INQUORE, 2-13
LOOKUP, 2-5
PJ:SET,

2-14

summary , 2-3
USRIN, 2-3, 2-12
US ROUT,

2-2

Vertical tab, 4-5

Wrap around memory, 4-3
Writing device handlers, 5-1
Word blocks, 1-2

INDEX -3

OS/8 Software Support Manual
DEC-S 8-OSSMB-A-D

READER'S COMMENTS

NOTE:

iTODxems
This form is for document comments oniy.
with software should be reported on a Software
Problem Report (SPR) form (see the HOW TO OBTAIN
SOFTWARE INFORMATION page)

Did you find errors in this manual?

If so, specify by page.

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for im.provement

Is there sufficient documentation on associated system programs
required for use of the software described in this manual? If not,
what material is missing and where should it be placed?

Please indicate the type of user /reader that you most nearly represent.

Assembly language programmer

I
I

Q Higher-level language programm.er
I

|~)
I

Occasional programmer (experienced)
User with little programming experience
Student programmer
Non-programmer interested in computer concepts and capabilities
Date

Name
Organization^

—

——

Street
City

—State

Zip Code
or

Country
If you do not require a written reply, please check here.

-Fold Here -

— Do Not Tear

•

Fold Here and Staple

FIRST CLASS

PERMIT NO. 33

MAYNARD, MASS.
BUSINESS REPLY MAIL

NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES
Postage will be paid by;

Software Conmninications
P. 0. Box F

Maynard, Massachusetts

01154,