OS8_Handbook_Apr1974 OS8 Handbook Apr1974

OS8_Handbook_Apr1974 OS8_Handbook_Apr1974

User Manual: OS8_Handbook_Apr1974

Open the PDF directly: View PDF .
Page Count: 954

Download
Open PDF In Browser	View PDF

i!i••••

prepared
by
so~ware

documentation
so(:tware engineering department
digital equipment corporation

pdpa handbook series

FIRST PRINTING, APRIL 1974

The information in this document is subject to change without
notice and should not be construed as a commitment by Digital
Equipment Corporation. Digital Equipment Corporation assumes
no responsibility for any errors that may appear in this manual.
The software described in this document 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.
Copyright © 1974 by Digital Equipment Corporation
The following are trademarks of Digital Equipment Corporation:
DEC
DECtape
Digital
EduSystem

LAB-8
LAB-8/e
Omnibus
OS/8

PDP
PS/8
SABR
Unibus

Teletype is a registered trademark of the Teletype Corporation.
ERROR REPORTING
If you fin~ any errors in this handbook, or if you have any questions or comments concerning the clarity or completeness of this
handbook, please direct your remarks to:

Digital Equipment. Corporation
Software Communications, Parker Street
Maynard, Massachusetts 01754
ADDITIONAL COPIES

Additional copies of this handbook may be obtained by ordering DEC-S8-0SHBA-A-D. Please send your order to the address
below.
Digital Equipment Corporation
Communications Services, Parker Street
Maynard, Massachusetts 01754
11

The OS/8 Operating System is a sophisticated operating system
designed for the PDP-8/E computer. This system permits use of
a wide range of peripherals. and all available core up to 32K. OS/8
offers a versatile Keyboard Monitor that supervises a comprehen- .
sive library of system programs. These features make OS/8 a significant improvement in small computer operating systems.

OS/8 SYSTEM PROGRAMS
Besides the Monitor facilities, OS/8 includes a library 'of powerful system programs which allow the user to do program development using FORTRAN II or assembly language. A brief summary
of the system programs follows: .
1. Concise Command" Language (CeL)
CCL provides the user with an extensive set of terminal
commands. Typical commands available in CCL include:
COPY, DIRECTORY, HELP,'. RENAME, LIST, DELETE, etc.
2. Symbolic Editor (EDIT)
EDIT is used to create or modify source files for use as input to language processing programs such as P AL8, SABR,
or FORTRAN. EDIT contains powerful text manipulation
commands for quick and easy editing.
3. PAL8 Assembler
PAL8 is the assembler for the OS/8 system. PAL8 accepts
source files in the PAL language and generates absolute
binary files as output. PAL8 also generates listing files which
can be used as input to CREF.
4. Peripheral Interchange Program (PIP)
PIP allows the user to -transfer files between devices which
are in the OS/8 system. Complete file and directory maintenance functions are available in PIP.
11l

5. Absolute..Binary LoadeL(ABSLDR).
ABSLDR'accepts the binary output files pr0duced by PAL8
and loads them -into core.
6. Octal Debugging Technique (ODT)
ODT is a powerful octaL debugging tool. All of the features of older versions of ODT are implemented, but the
OS/8 version is designed. so that no user core is needed.
7. File-Oriented Transfer Program (FOTP)'
FOTP allows the ·user to transfel' groups of files between
two OS/8 file-structured devices with' minimal terminal
interaction and device .overhead, e.g' r all' ASCII files can
be transferred between a DECtape and odisk with one terminal command.
8. Cross Reference (CREF)
CREF operates on the listings produced by P AL8 and
SABR. It produces a sequence numbered listing and a table
indicating where each user-defined tag and literal is
'referenced.
9. DIRECT
DIRECT allows the user to print extended directory listings.
10. BOOT
The BOOT program loads the standard hardware bootstraps into core.
11. Cassette/Magtape Positioner (CAMP)
CAMP allows the user to manipulate cassettes and magnetic tapes.
12. Resources (RESORC)
RESORC integrates system monitor tables and prints a
listing of active device handlers.
13. Magtape/Cassette PIP (MCPIP)
MCPIP is a file transfer program to be used with cassettes
and magnetic tapes .
. 14. PIPIO
PIPIO is a file transfer program which reads and writes
PDP-IO ASCII DECtape files using a TC08 or TD8E
DECtape controller.
IV

15. FORTRAN II
The. OS/8system contains an extensive and powerful
FORTRAN package, consisting of the FORTRAN compiler, SABR assembler, Linking Loader, and Library function routines. Some of the many features of FORTRAN II
are:
a. FORTRAN II is very easy to use. If desired, a FORTRAN source program can be compiled, loaded, and
executed with a single terminal command.
b. Implied DO loops are permitted in FORTRAN II.
c. FORTRAN II contains fadlities to do program chaining; this technique can be used to increase the effective
program SIze.
d. Device independent I/O is available, as well as the standard devices ( console terminal, high-speed reader /
punch, card reader, and line printer).
16. Library Setup (LIBSET)
OSj8 LIB SET allows the user to create his own FORTRAN II run-time libraries. The standard library supplied
with the system is LIB8. By using LIBSET, the user can
write his own routines in SABR and create a library.
17. System Build (BUILD)
.
BUILD allows rapid and easy alteration of the device configuration in the system. New devices can be inserted by
simple keyboard commands. BUILD ago makes interfacing
user-coded device handlers a quick and easy job.
OTHER PROGRAMS A V AILABLE WITH OS/8
In addition to the standard OS/8 system programs listed previously, the following programs are available with OS/8:

BASIC
BATCH
TECO
FORTRAN IV
BASIC, BATCH, and TECO are provided in a single extension
kit. OS/8 BASIC is an interactive language )Vitha variety of applications. It contains such features as chaining, string manipulation,
and file-oriented input/output. Also included with BASIC are certain functions for use on the LAB-8/E.

OS/8 BATCH provides the user with a batch processing monitor that is integrated into the OS/8 Monitor structure. The system
is organized in such a way that it may be used in either a keyboard
input configuration or as a batch stream processor. BATCH permits the user to prepare his job on punched cards, high-speed
paper tape, or the OS/8 system device and leave it for the computer operator to start and run.
OS/8 TECO is a powerful text editing and correcting program
"that runs under the OS/8 operating system. TECO may be used
to edit any ASCII text such as program listings, manuscripts, correspondence, etc.
OS/8 FORTRAN IV provides full ANSI FORTRAN IV under
the OS/8 operating system. The system is highly optimized with
respect to memory requirements, and" an overlay feature is included that can permit programs requiring up to 300K of virtual
storage to run on a PDP-8 or PDP-12. The library functions permit the user to access a number of laboratory peripherals, to evaluate a number of transcendental functions, to manipulate alphanumeric strings, and to output to a standard incremental plotter.

OS/8 I/O DEVICES
OS/8 provides true device-independence. For the first time on
a PDP-8 computer, programs can be written without concern for
specific I/O devices. In running a program, the user can select the
most effective I/O devices available. Further, if the system configuration is altered, programs need not be rewritten to tak~ advantage of the new configuration.
The OS/8 system controls the copying of data from any medium
to any other medium by means of subroutine calls to execute I/O
routines. Logical names can be assigned to devices within the system to enable symbolic referencing of devices.
Variable length I/O buffers can be specified by the user program.
Large buffers ensure efficient use of storage devices and a minimum
of time spent in data transfer operations by minimizing disk and
tape motion. OS/8 takes full advantage of the RK8E disk pack for
fast bulk storage, yet full system services are possible with a single
DECtape.

HARDWARE CONFIGURATIONS
The OS/8 system can operate with a wide variety of devices as
the system device. 1 The devices which can be used are:
TCOI/TC08 DECtape
LINCtape (PDP-12)
TD8E DECtape
DF32/RF08 disk
RK8E disk
RK8 disk
TD8E DEGtape can be used either with 12K words of core
memory or with 8K word,s of core memory and 256 words of'
Read-Only-Memory (ROM).
If DF32 is the system device, at least 64K (2 platters) must be
available. In addition; if disk is the system device, cassettes or the
high-speed reader/punch provides a very useful tool.
The minimum OS/8 configuration is a PDP-8 series computer
~ith 8K words of core memory, one DECtape used as the system
device, and a console terminal. A multiple DECtape system performs appreciably faster than a single DECtape' system. The multiple DECtape system reduces DECtape motion since it is possible
to copy directly (without intermediate searching) from the system
DECtape to another DECtape (or vice versa) when editing or
assembling.
.
A typical medium-sized system might contain a PDP-8/E with
at least 8K words of core memory, TD8E D~Ctape and control,
and an RK8E disk pack and control. A disk system offers the additional convenience of easy and fast access to files and large
amounts of storage.
Up to 15 devices can be interfaced to a single OS/8 system.
These optional devices include:
~

As many as 8 DECtape units (TCOl/TU55, TC08/TU56, or
TD8E/TU56.
TA8E/TU60 cassette milts
TM8E/TUlOmagnetic tape units
The term system device refers to the device on which the OS/8 system
resides and which it utilizes for system functions. Thus, DECtape unit 0
is the system device for a DECtape-based system. A nonsystem device is
any peripheral not specifically used for system functions, such as LPT:,
PTR:, DTA2:, etc.
1

vii

High-speed paper tape reader/punch.
Up to four RK8E disks.
Up to four RK8 disks.
Up to four RS08 disks.
Up to four DF32 disks.
Card reader (optical mark or punched cards).
Line printer.
PDP-12 LINCtape.
PDP-12 scope.
Any other device for which it is impossible to write a device
handler in one or two pages of core.
SYSTEM SOFTWARE COMPONENTS
,
The main software components of the OS/8 system are five:
Keyboard Monitor
Command Decoder
Library of system programs
Device handlers
User-Service Routine (USR)
The Keyboard Monitor provides communication between the
user and the OS/8 executive routines by accepting commands from
the console terminal. The commands enable the user to create logical names for devices, run system and user programs, save programs, and call ODT.
The Command Decoder· allows the user to communicate with a
system library program by accepting a command string from the
keyboard indicating input/output files. Following the keyboard
command to run a system library program, the Command Decoder prints an asterisk (*) and then accepts the command line
containing the files to be used as input, file name, and destination
of output, etc.
The library of system programs contains the programs mentioned
previously and any of the extension programs chosen by the user.
D~vice handlers are subroutines designed to transfer data to
and from peripheral devices. OS/8 is able to interface with as many
as 15 different peripherals at a time. During system generation,
device handlers become an integral part of the system; both system
and user programs have access to any available device. (The
BUILD program allows quick and easy alteration of any available device.)
VIII

The User Service Routine (USR) control the directory operations
for the OS/8 system. A program can use the USR by means of
standard subroutine calls such as those used to activate device
handler subroutines. Some of the functions performed by the USR
are loading device handlers, searching file directories, creating and
closing output files, calling the Command Decoder, and chaining
of programs. The details on the operation and use of the USR are
contained in the OS/8 Software Support Manual (DEC-S8OSSMB-A-D). For normal OS/8 usage, the USR function is unseen by the user and need be of no concern.
When OS/8 is operating, the Command Decoder, Keyboard
Monitor, and USR are swapped into core from the system device
as required, and when their operation has been completed, the
previous contents of core are restored.
The core-resident portion of OS/8 is extremely small (256
words), allowing for a maximum use of core by user programs.

USING THE OSj8HANDBOOK
The OS/Handbook provides a complete user's guide for the
OS/8 operating system and system programs. The handbook is
divided into three parts. Part one contains detailed instructions for
getting a new OS/8 system running. Also included in part one are
the fundamentals of OS/8, including the Keyboard Monitor, Concise Command Language (CCL), Command Decoder, the Absolute Loader (ABSLDR), Octal Debugging Technique (ODT), and
Peripheral Interchange Program (PI~). The user must have a
complete understanding of the material contained in Chapter 1 to
use the OS/8 operating system.
Part two contains complete descriptions of the OS/8 utility
programs. These programs allow the user to perform a variety of
editing, I/O transfers, system generation, and file-oriented operations ..
Part three describes the assemblers available with OS/8: PAL8,
SABR, FLAP, and RALF.
Part four describes the higher-level languages which can be run
under OS/8: BASIC, FORTRAN II, and FORTRAN IV.

CHAPTER 1

OSj8 FUNDAMENTALS

Getting On Line With OS j 8 ................................................ 1-1

1-1
1-2
1-4
1-9
1-10
1-15
1-17
1-20
1-25
1-26
1-26
1-28
1-29

Keyboard Monitor ....................................................... ........ 1-30

System Conventions .................................... :...................
Permanent Device Names ......... ,...-: ..............................
File Names and Extensions ...........................................
Using the Keyboard Monitor ...........................................
Keyboard Monitor Commands ....................................
Keyboard Monitor Error Messages ..................... .............

1-30
1-30
1-32
1-33
1-35
1-42

Coinmand Decoder .............................................................. 1-45

Command Decoder Input String ......................................
Examples of Command Strings .....: ..............................
Input/Output Specification Options ............................
Command Decoder Error Messages ................. :..............
xi

1-45
1-48
1-49
1-51

1-52
1-53
1-53
1-54
1-55
1-56
1-57
1-75

1-78
1-78
1-79
1-80
1-82
1-82
1-83
1-83
1-84
1-89
1-91
1-92

Peripheral Interchange Program (PIP) ................................
Calling and Using PIP ......................................................
PIP Options ................................................................
Examples of PIP Specification Commands ..................
Additional Information Words in File Directories ..........
PIP Error Messages .. ............ ...... ........................... .........

1-97
1-97
1-98
1-102
1-105
1-106

Absolute Binary Loader (ABSLDR) ....................................
Calling and Using ABSLDR ............................................
ABSLDR Options ................................................. :......
Examples of Input Lines ......................................... .....
Notes on Using ABSLDR Correctly ................................
ABSLDR Error Messages ................................................

1-108
1-108
1-110
1-111
1-112
1-113

Octal Debugging Technique (ODT) .................................... 1-113
Features .......................................................................... 1-113
Calling and Using ODT .................................................. 1-114
xu

CHAPTER 2

1-115.
1-115
1;.117
1-117
1-121
1-121
1-121
1-122
1-122
1-122

UTILITY PROGRAMS

BITMAP .............. ................................................ ....... .......
Hardware and Software Requirements ......... ,..................
Loading BITMAP ...................................................... ~ .....
BITMAP Output .............................. ......... ........... ..........
BITMAP Error Messages ..............................................
Assembly Instructions ......................................................

2-26
2-26
2-26
2-28
2-30
2-30

BOOT ................................................................................... 2-32
Xlll

xiv

2-34
2-34
2-35
2-36
2-36
2-38
2-40
2-41
2-41
2-42
2-42
2-44
2-45
2-46
2-47
2-48
2-49
2-49
2-49
2-50
2-51
2-51
2-52
2-52
2-53
2-54
2-55
2-56
2-57
2-57
2-59
2-60
2-62
2-62
2-62
2-63
2-64
2-64
2-64

UNLOAD .......... """ ............. ,,.,," " ! . " .. " . " . . . . . . . . . . . . . . . . . . . 2-66
VERSION .................................................................. 2-66
.CAMP Error Message Summary ......... ...................... ..... 2-66

2-69
2-69
2-69
2-70
2-71
2-72
2-73
2-76

·DIRECT ..............................................................................
Calling and Using DIRECT .. .................... ......................
DIRECT Options ........................................................
DIRECT Examples ...... :...........
DIRECT Error Messages .........................................

2-77
2-77
2-78
2-79
2-81

! .................................
! ......

FOTP .................................................................................. 2-97

2-97
2-97
2-99
2-99
2-103
2-103
2-103
2-104
2-106
2-108

Magtape/Cassette Peripheral Interchange Prognun
(MCPIP) .............................................................................. 2-110

Calling and Using MCPIP .... :......................................... 2-110
MCPIP Options .......................................................... 2-111'
MCPIP Error Messages ................................................... 2-113
PIPIO .................................................................................. 2-l't6
/'

Calling and Using PIPI0 .. ............ ......... ............. ............
PIPI0 Options ................................................................
PIP 10 Examples ..............................................................
Error Messages ................................................................

2-116
2-117
2-118
2-119

RESORC ............................................................................. 2-121

Calling and Using RESORC ............................................
RESORC Options ............................................................
Fast Mode (IF Option) ................................................
Limited Mode (lL Option) ........................................
Extended Mode (IE Option) ........................................
RESORC Error Messages................. ................. ..............

2-121
2-122
2-122
2-122
2-124
2-127

Source Compare (SRCCOM) -.............................................. 2-128

SRCCOM Assembly Instructions ....................................
Loading SRCCOM ..............'............................................
SRCCOM Output ............................................................
Error Messages ................................................................
XVl

2-128
2-128
2-129
2-131

2-132
2-132
2-132
2-142
2-144
2-1462-147
·2-148
2-149
2-150
2-151
2-154
2-155
2-155
2-157
2-158
2-160
2-164
2-166
-2-167
2-168
2-172
2-177
2-178
2-183
2-184

CHAPTER 3 PAL8

Introduction ........................................................................ 3-1
Calling and Using PAL8 ......................................................

3~1

. Character Set ...................................................................... 3-5
XVll

Statements ..........................................................................
Labels ..............................................................................
Instructions ......................................................................
Operands ........................................................................
Comments ........................................................................

3-6
3-6
3-6
3-6 ,"
3-7

Format Effectors ..................................................................
Form Feed ......................................................................
Tabulations ..... ......... .................... ..................... ....... ........
Statement Terminators .....................................................

3-7
3-7
3-7
3-7

3-9
3-9
3-9
3-10
3-11
3-12
3-13
3-14
3-14

3-22
3-22
3-23
3-23
3-24
3-26
3-26

Pseudo-Operators .......................... :.................................... .
Indirect and Page Zero Addressing .............................. ..
Radix Control .............................................................. ..
Extended Memory ......................................................... .
End-of-File ..................................................................... .

3-26
3-27
3-27
3..:rJ
3-29

XVlll

3-29
3-29
3'::30
3-30
3-30
3-31
3-31
3-32
3-32
3-33
3-33

Link Generation and Storage .............................................. 3-35
Coding Practices .................................. :............................... 3-36
Program Preparation and Assembler Output ........................ 3-37
Terminating Assembly ......................................................... 3-38
P AL8 Error Conditions ......................................................

3~39

PAL8Permanent Symbol Table .......................................... 3-41 .
CHAPTER 4 SABR
Introduction ................. , .. ... . . . ..... .. .. ... ...... . ............................. 4-1

Calling and Using'OS/8 SABR ........... :............................ 4-1
OS/8 SABR Options .................................................. 4-2
Examples of OS/8 SABR I/O
Specification Commands .............................................. 4-3
The Character Set ................................................................ 4-4

Alphabetic .... :................................................. ;................. 4-4
Numeric ............................................. ,............................ 4-4
Special Characters ............................................................. 4-4
Statements ............................................................................ 4-5

Labels .............................................................................. 4-6
XIX

4-12
4-16
4-20
4-22

Subroutines ............................................... ,..........................
CALL and ARG .. .............. ........................ ......................
ENTRY and RETRN ......................................................
Example ..........................................................................

4-24
4-25
4-27
4-28

........

4-32
4-32
4-33
4-33
4-34
4-34
4-37
4-38
4-38
4-38

The Subroutine Library ......................................................
Input/Output ..................................................................
Floating-Point Arithmetic .......................................... ,.... :
Integer Arithmetic .................................................... ,.....
Subscripting ......................................................................
Functions ........................................................................

4-39
4-40
4-41
4-43
4-43
4-44

4-62
4-62
4-63
4-66
4-67

4-68
4-68
4-69
4-69
4-70
4-70
4-71

Library Programs ...... ................................ .......................... 4-71
Demonstration Program Using Library Routines ................ 4-73

CHAPTER 5 FLAP jRALF
Introduction

•••••••••••••• ••••••••• •••••••••• c ••••••••••••••••••••••••.••••••••••••••

5-1

Hardware Requirements ..................................................... . 5-1
·Statement Syntax ............................................................... . 5-2
Tags ............................................................................... . 5-2
XXI

':,e"

."1

T""1

1"\

5 -16
5-17
5-17
5-17
5. . 17
5-17
5-17
5-18
5-18
5-18
5-18
5-18
5-18

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

xxm

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

6-6
6-6
6-8
6-8
6-9
6-9
6-10
6-11
6-11
6-13
6-14
6-14
0-14

6-14
6-15
6-15
6-15
6-16
6-21
6-21
6-22
6-23
6-25
6-25
6-26

6-33
6-33
6-34
6-34

6-36
6-37
6-37
6-38
6-3'8
6-38
6-38
6-39
6-39
6-39
6-39
6-39
6-40
6-42
6-43
6-43
6-45

Alphanumeric Information (Strings) .................................... 6-46

6-46
6-46
6-46
6-47
6-49
6-50
6-50
6-50
6-51
6-52
6-53
6-53
6-54

Editing and Control Commands .......... ~ ......... ~................. _~. 6-54

Correcting Programs ........................................................ 6-55
Erasing Characters and Lines ..................................... ~ 6-55
The RESEQ Program .................................................. 6-55
The LIST and LISTNH Commands ................................ ' 6-56
The SCRATCH Command ............................................. ~ 6-57 '
The NEW Command ...................................................... ' 6-58
xxv

The
The
The
The
The

OLD Command ....................................................... .
NAME Command .................................................. ..
SAVE Command ..................................................... .
RUN and RUNNH Commands ............................... .
BYE Command, ....................................................... .

6-58
6-59
6-59
6-60
6-60

Files, File Statements, and Chaining ................................... .
General Information on- OS/8 BASIC Files ................... .
System Devices ........................................................... .
File Statements .............................................................. ..

6-60
6-60
6-60
6-61

6-69
6-69
6-70
6-71
6-71
6-72
6-73
6-73
6-73
6-74
6-75
6-76
6-76
6-77
6-77
6-78
6-79
6-80
6-80
6-81
6-85
6-85
6-85
6-86
6-87
6-87
6-88
6-88
6-90

XXVI

·OS/8 BASIC System Build Instructions .............................. 6-118
Optimizing System Performance ........................................... 6-121 .
LAB8/E Functions for BASIC ............................................ 6-124

Introduction ....................................................................
General Description ........................................................
Preparing BASIC for LAB8/E Functions ......................
Definition of LAB8/E Support Functions ..... ~................
LAB8/E Examples ..........................................................
Getting on the Air with BASIC ...... ~ ...............................
LAB8/E Function Summary ..........................................

6-124
6-124
6-125
6-126
6-136
6-147
6-148

CHAPTER 7 FORTRAN II
Introduction ................... ,................................. , .... .... .. .. .... .. 7-1

Calling and Using the OS/8 FORTRAN Compiler ........ 7-1
XXVll

FORTRAN Options ....................................................
Example Program ............................................ :...........
Examples of FORTRAN I/O
Specification Commands ..............................................
Using FORTRAN or SABR with the Interrupt On ........
Using PAL8 with SABR or FORTRAN ........................ "..

7-1
7-3
7-4
7-6
7-7

FORTRAN II Source Language.......................................... 7-8

7-14
7-15
7-16
7-16
7-17
7-21
7-29
7-29
7-30
7-30
7-32
7-32
7-33
7-34
7-34
7-35
7-35
7-36

Subroutine Subprograms .............................................. 7-37
Function Calls .................................................... :.......... 7-40
Function Library ...........................................'...... ................. 7-40
Floating-Point

Arithmeti~

.................................................... 7-42

Device Independent I/O and Chaining. ................................
The IOPEN Subroutine ..................................................
The OOPEN Subroutine ..................................................
The OCLOSE Subroutine ... :....... :..................................
The CHAIN Subroutine ..................................................
The EXIT Subroutine ....................................................

7-42
7-42
7-43
7-44
7-44
7-44

DECtape I/O RQutines ............................ ............................ 7-44
-..

FORTRAN' IV

FORTRAN IV System Overview ....................... ;............

8-1

The FORTRAN IV Compiler ..........................................
Examples ........... :............................................................
Compiler Error Messages ............................................

8-9
8-12
8-13

The RALF Assembler ......................................................
Examples ................................................... ..... ..............
RALF Assembler Error Messages ................................

8-15
8-19
8-20

XXIX

The Loader
Loader Error Messages ........................... : ................... .

8-20
8-29

FORTRAN IV Run-Time System (FRTS) ..................... .
Run-Time System Error Messages ............................... .

8-31
8-38

FORTRAN IV Library ................................................... .
Library Functions and Subroutines ............................... .

8-40
8-46

'FORTRAN IV Source Language ................................... .
Constants, Variables, and Expressions ....................... .
Constants ................................................................. ..
Variables ................................................................... .

8-65
8-67
S-67
8-70
8-72
8-76
8-77
8-78
8:. 80
8-80
8-82
8-83
8-86
8-88
8-88
8-88
8-88
8-89
8-100
8-101
8-106
8-107
8-107
8-112
8-114
8-114
·8-115
8-117
8-119
8-119.
8-120

Pv ....... roClC';nnc

L...J.l1.J:-'.l.\o.Ia.:J~.1V.1.1..03

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

••

Paper Tape Loading Instructions ........................ ~ ............ .

8-124

8-127
8-129
8-129
8-129
8-130
8-131
8-131
8-132
8-136
8-138
8-139
8-141
8-142
8-142
8-142
8-142
8-144

APPENDICES

Appendix
Appendix
Appendix
,Appendix
Appendix
Appendix
Appendix
Appendix

A Character Codes
B Loading Procedures ..................................... .
C Permanent Symbol Table .......................... ..
D OS/8 Demonstration Run ........................... .
E OS / 8 Error Message Summary .................. ..
F OS/8 File Name Extensions ......................... .
G OS /8 Device Handlers ............................... .
H Obtaining OS/8 Version Numbers .............. ..

A-l .
B-1
C-1
D-l
E-l
F-l
G-l
H-1

LIST OF TABLES

Table 1-1
Table 1-2
Table 1-3

TC01/TC08 DECtape Bootstrap ................
TD8E Initialization Error Messages ..........
12~ TD8E DECtape Bootstrap....... ...........
xx Xl

1-3
1-6
1-8

I
Table 1-4
Table 1-5
Table 1-6
Table 1-7
Table 1-8
Table 1-9
Table 1-10
Table 1-11
Table 1-12
Table 1-13
Table 1-14
Table 1-15
Table 1-16
Tabie 1-17
Table 1-18
Table 1-19
Table 1-20
Table 1-21
Table 1-22
Table 1-23Table 1-24
Table 1-25
Table 1-26
Table 1-27
Table 1-28
Table· 2-1
Table 2-2
Table 2-3
Table 2-4
Table 2-5
Table 2-6
Table 2-7
Table 2-8
Table
Table
Table
Table
Table
Table

2-9
2-10
2-11
2-12
2-13
2-14

Table
Table
Table
Table
Table
Table
Table
Table
Table
. Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
. Table
Table
Table
Table
Table
Table
Table
Table

2-15
2-16
2-17
2-18
2-19
2-20
2-21
2-22
2-23
2-24
2-25
2-26
2-27
2-28
2-29
2-30
2-31
2-32
2-33
2-34
2-35
2-36
2-37
2-38
2-39
2~40

2·,,41
2-42
2-43
2-44
2-45
3-1
3-2
3-3
4-1
4-2
4-3
4-4
4-5

xxxiii

2-76
- 2-78
2-81
2-89
2-93
2-104
2-108
2-111
2-114
2-123
2-125
2-127
2-129
2-142
2-145
2-146
2-147'
2-148
2-149
2-150
2-151
2-154
2-156
2-157
2-159
2-161
2-163
2-164
2-168
2-179
2-184
3-3
3-16
3-39
4-2
4-13
4-61
4-63
4-68

Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Tab1e
Table
Table
Table
Table
Table
Table
Table
Tab-Ie
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table
Table

4-6
4-7
5-1
5-2
5-3
6-1
6-2
6-3
6-4
7-1
7-2
7-3
7-4
7-5
7-6
7-7
8-1
8-2
8-3
8-4
8-5
8-6
8-7
8-8
8-9
8-10
8-11
8-12
8-13
8-14
8-15
8-16
8-17
8-'18
8-19
8-20

XXXIV

4-71
4-72
5-4
5-38
5-40
6-108
6-115
6-117
6-148
7-2
7-20
7-22
7-41
7-48
7-51
7-56
8-9
8-12
8-14
8-18
8-25
8-29
8-35
8-38
8-44
8-45
8-52
8-77
8-79
8-93
8-94
8-106
8-121
8-128
8-132
8-133

LIST OF ILLUSTRATIONS

Figure
Figure
Figure
Figure
Figure
Figure
Figure
_Figure

2-1
2-2
2-3
2-4
2.:5
2-6
2-7
2-8

xxxv

2-8
2-14
2-173
2-174
2-175
2-175
2-176
2-176
2-176
2~177

3-22
3-24
3-24
3-25
5-34
8-2
8-3
8-4
8-66
8-86
8-145
8-147

XXXVI

getting on line
keyboard monitor
command decoder
ccl
editor
•
pip
absldr
odt .

1
. 05/8 ~undamentals
GETTING ON LINE WITH OS/8
OS/8 software is distributed to the user in a form appropriate
for his particular hardware configuration. The general system
categories are DECtape (LINCtape), cassette, and paper tape.
This section provides the information that the user of any of these
types of systems needs to start using OS/8. The procedures for
bootstrapping a disk system and for restarting OS/8 are also contained in this section. To get on line with OS/8 when the system
is first installed, refer to the section on the specific distribution
m"edia.
DEC tape Systems
This category includes TC01/TC08, TD8E, and LINCtape
(PDP-12) hardware configurations. Since the software is supplied
on a system DECtape (or LINCtape), it is not necessary to build
. an initial system, as it is when using cassettes or paper tapes.
Two tapes are distributed with each DECtape (LINCtape)
system. System Tape # 1 contains the system programs and all
OS/8 Monitor functions. System Tape #2 contains TDINIT.SV
(used in TD8E system initialization) and two TD8E DECtape
monitor images (8K ROM and 12K). Other files on this second
tape are the device handlers in a format suitable for the OS/8
BUILD program. Each file contains a handler for a specific device
type. These files are to be used as input for the LOAD command
in BUILD and are described in the BUILD section of Chapter 2.
In addition to these files, the tape al~o contains relocatable binary .
files of the FORTRAN II library subroutines. LIBSET, the FORTRAN II librarian, is used to create a FORTRAN II library as
described in Chapter 7.
Finally, the tape contains several OS/8 help files (.HL extension). These help files are intended to provide the user with a

1-1

quick command summary for most OS/S programs. They can be
printed with either OS/S PIP or the CCL command HELP.
TCOI/TCOS DECTAPE USERS
The following short procedure is used to start OS/S on a
TCO 1/TCOS system:
1. Mount the system DECtape (DEC-SS-OSYSB-A-UCl) on
unit 0 (this appears as unit S on some DECtape units), making certain to wind at least 10 feet of tape onto the empty
reel. Set the tape unit switches to REMOTE and WRITE
LOCK.
2. Bootstrap the OS/S DECtape by following one of two methods.
If the system includes an MIS-E hardware bootstrap option:
a. Place the terminal on line. Raise the SING STEP switch
on the PDP-S/E console. Press the CONT switch. Then
lower and raise the HALT switch. At least one console
indicator lamp should light.
b. Having mounted the OS/S System Tape #1 on unit 0 as
described above, lower and raise the SW switch on the left
side of the console.
If the system does not include a hardware bootstrap, this
procedure will have no effect. In this case, execute step 1
above, place the terminal on line, and Jhen perform the switch
manipulations shown in Table 1-1. For each step in the table,
place each of the PDP-S/E console SWITCH REGISTER
switches numbered 0 to 11 either in the up position if the
corresponding table entry is a 1, or in the down position if
the corresponding table entry is a O. When aU 12 switches have
been set to correspond to a line in the table, follow the instructions in the right hand column and proceed to the next line. In
step 4, for example, place switches 2, 4, 7, and lOin the up
position; place switches 1, 3, 5, 6, S, 9, and 11 in the down
position; lift the DEP switch; and proceed to step 5. The
table also includes octal values of the binary switch settin"gs for
the benefit of users familiar with octal numbers.

1-2

Table 1-1 TCOllTC08 DECtape Bootstrap
STEP

#
I

2
3
4
5
6
7'
8
9
10
11
12
i3

14
15

OCTAL SWITCH REGISTER
SETTING
VALUES

0000
7613
6774
J222
6766
6771
5216
1223
5215
0600
0220
7754
7577
7577
7613

012
000
111
110
001
110
110
101
001
101
000
000
II1

345
000
110
111
010
III
III
010
010
010
110
010
111
III 101
111 101
I 1I 110

678
000
001
1I 1
'. 010
110
III
001
010
001
000
010
101

91011
000
all

100
010
110
001
110
all

101
000
000
100

ItI

III

1I I
001

all

I I1

AND THEN

press EXTD ADDR LOAD
pre,Ss ADDR LOAD
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEPKey
press ADDR LOAD
lift DEP key
lift DEP key
press ADDR LOAD and
press CLEAR and
press CONT

Either bootstrapping procedure first rewinds the DECtape on
. unit 0 to the end zone, then starts it moving forward, reading
block 0 into locations beginning at 7600 in field O. In block
o of the DECtape is a larger bootstrap which continues reading
the tape, installing the resident Monitor code, and finally
turning control over to the OS/8 Keyboard Monitor.
3. DECtape unit 0 will rock and the console terminal will respond
by printing a dot (.) at the left margin. At this point, OS/8 is
active; DECtape unit 0 must be set to WRITE ENABLE.

NOTE
If the terminal does not respond properly,
check that the bootstrap was loaded correctly, that unit 0 is selected and set to
REMOTE, that the correct tape is mounted,
and that the terminal is set to REMOTE or
LINE. If trouble persists, contact the local
Digital sales office.
1-3

TDSE DECTAPE USERS
OS/S supports TDSE DECtape hardware in two configurations:
TD8E DECtape and 12K or more core, and TD8E DECtape and
8K core and 256-word Read-Only-Memory (ROM).
TD8E DECtape users must run a special initialization program
before OS/S can be used. This program need only be run once to
create the proper configuration; thereafter, the appropriate TDSE
bootstrap (discussed shortly) can be used to start OS/8.
TD8E Initialization Program
Use the following procedures to initialize the TDSE DECtape
system.
1. Mount the binary DECtape (DEC-S8-0SYSB-A-UC2) on
llnit
-nFrt~ne
- - ---r
- - _. o. Set the tane unit switches to REMOTE and
WRITE LOCK.
2. Turn the console terminal to LINE or REMOTE.
3. Execute one of the TDSE bootstraps (see TD8E Bootstraps in
this section).
4. When the bootstrap is executed correctly, the message:
.1.

TDSE INITIALIZER PROGRAM \lERSlOO

is printed on the terminal. Then depending upon which type
of TD8E configunition is present, one of the following messages is printed to indicate the system on which OS/S will be
built.
a.

SK ROM SYSTEM

is printed if the user has the 256-word ROM.
b.

12K SY STEM

is printed if the user has no ROM but does have 12K or
more of core memory.

NOTE
If neither the ROM nor 12K of memory
exists, the message:
NEED ROM OR

12K

appears, and the machine halts. This indicates that the configuration is not suitable
for running the TDSE version of OS/ S.
1-4

5. After the message specifying the hardware configuration (a or
b above), the following instructions to the user appear:
MOUNT A CERTI FI ED DECTAPE CN Ut\lI T 1 WRI TE- ENABL ED
ALWAY S K EEPORI GI NAL SY STEM DECTAPES .wRi TE-L 'OCK ED
STRIKE A CHARACTER TO CCNTINUE

Perform the specified operations. At this point, the current
OS/8 Monitor is written onto a blank DECtape on unit 1.
Note that the original tape (on unit 0) is not written upon.
6. When the copy operation is complete, the following instructions are printed:
01 SMOUNT TAPE #2 FORM
MOUNT ORI GINAL SY STEM
PREPARE- TO COpy FILES
STRIKE A CHARACTER TO

UNI T 0 AND SAVE IT
TAPE ilION UNI1 0
OVER
CONTINUE

The system programs will now be copied from System Tape
#1 (DEC-S8-0SYSB-A-VC1) to the tape being created.
Perform the specified operations and type any character except
CTRL/Z to -continue. PREPARE TO COPY FILES OVER
means to expect copying to take place; no additional preparation is implied. The following message is printed:
C QPY I NG FI L E 5 FROM UN I T 0 T 0 UN I 1

and the system copIes the files and updates the DECtape
directory.
NOTE
If the user wishes to perform nonstandard
special processing, he can respond with a
CTRL/Z to the preceding dialogue. If
CTRL/Z IS typed, the following messages
appear:
TYPE 1
TYPE 2
TYPE 3
STRIKE

TO COpy FILES FRO'-1 UNI'I 0 TO UNI T 1
TO ZERO THE DIRECTORY -OF UNIT 1
TO LEAVE THE DI-RECTORY OF UNI T 1 ALONE
A CHARACTER TO CCNTINUE

1-5

Reply with either aI, 2, or 3 (which will
not echo) to indicate the desired option.
Typing any character other than those indicated will repeat the request message. One
of the following confirmatory messages will
appear, to indicate the options 1, 2, or 3,
respectively:
COPYING FILES FRO'-1 UNI T el TO 1
ZEROING THE DIRECTORY Q\J TAPE UNIT
01 RECTORY ON LNI T 1 PRESERVED

7. When the files have been copied, the following instructions
appear:
REMOVE AND SAVE TAPE ()\j UNI T 0
TAKE NEW TAPE (QIJ LNIT 1> WHICH WAS JUST CREATED
Al'JD PLACE I T ON UNI T 0
I T I SY OU R N EW OS 18 SY STEM TAP E
STRI K E A CHARACTER TO CONTI N UE

Remove the original OS/8 tape and save it for later use. Set
DECtape unit 0 to WRITE-ENABLE, and type any character
to continue. The tape on unit 0 will be initialized to a TD8E
configura ti on.
When the initialization is completed, a dot (.) is printed at the
left margin of the terminal. OS/8 is active on a TD8E based
system.
TD8E Initialization Error Messages
The messages listed in Table 1-2 may appear during the TD8E
- initialization process.
Table 1-2 TD8E Initialization Error Messages

Message

Meaning

FATAL 10 ERROR
MOUNT CORRECT TAPE ON UNIT 0
NEED ROM OR 12K
1-6

Unable to read from newly
copied system tape.
Cannot copy tape currently
mounted.
Improper hardware configuration.

Table 1-2, TD8E Initialization Error Messages (Cont.)

Meaning

Message
NOT ORIGINAL OS/8 SYSTEM
TAPE #2
STRIKE A CHARACTER TO
CONTINUE
TYPE ANY OTHER Cf{ARACTER ,{O
RETRY THIS I/O OPERATION
TYPE A TO ABORT AND
START OVER AGAIN

The tape copied from was
not an original OS/8 tape'
supplied by Digital.
An I/ O· error occurred on·
the DECtape. Type any
character to retry the operation.
First retry failed. Type any
other character to retry another time.
Return' to Step 1.

T D8E Bootstraps
8K ROM Bootstrap (PDP-8/E)

1. Set the switch register on the PDP-8/E console to 7470
(octal), i.e., set switches 0, 1, 2, 3, 6, 7, and 8 in the up position, and set switches 4, 5, 9, 10 and 11 ill" the down pos.ition.
2. Raise the SING STEP switch. Lower and raise the HALT
switch.
3. Press the EXTD ADDR LOAD, ADDR LOAD, CLEAR, and
CaNT switches. The tape bootstrap will be executed and a message will be printed (if initializing) orthe OS/8 Keyboard Monitor
will print a dot (.) to indicate that it is active. If initializing,
set DECtape unit 0 to WRITE-LOCK. If OS/8 is already
active, set DECtape unit 0 to WRITE ENABLE.

12K TD8E Bootstrap
The contents of the 12K TD8E bootstrap are included in Table
1-3.
The tape bootstrap will be executed and a message will be
printed (if initializing) or the OS/8 Keyboard Monitor will print
a dot (.) to indicate that it is active. If initializing, set DECtape
unit 0 to WRITE-LOCK. If OS/8 is already active, set DECtape
unit 0 to WRITE EN ABLE.

1-7

Table 1·3 12K TD8E DECtape Bootstrap
STEP OCTAL
# VALUES

7300
2
3
4
5
6
7
8
9

10
1I
12
13
14
15
16
17
18
19

20
21
22
23
24
25

1312
4312
4312
6773
5303
6777
3726
2326
5303
5732
2000
1300
6774
6771
5315
6776
0331
1327
7640
5315
2321
5712
7354
7756

SWITCH REGISTER
SETTING

012 345
I I I 011
001
100
100
110
101
110
011
010
101
101
010
001
110
110
101
110
000
001

011
011
011

678
000

001
001
001
III 111
011 000
11I 1I 1
III 010
011 010
011 000
III 011
000 000
011 000

AND THEN

91011

000
010
010
010
011
all

111
110
110
01 1
010
000
000
III III 100
I I I I 11 001
011 001 101
I I I I 1I 110
Oll 011 001
011 010 111
111 110 100 000
101 011 001 101
010 011 010 001
101 111 001 010
11 1 011 101 100
11 I III 101 110

1-8

press ADDR LOAD and
press EXTD ADDR LOAD
. lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key

Table 1-3
STEP OCTAL
# VALUES
26··
27
28
29

7747
0077
7400
7300

12K TD8E DECtape Bootstrap (Cont.)

SWITCH REGISTER
SETTING

111
000
111
11]

111
000
100
011

100
111
000
000

111
111
000
000

AND THEN
lift DEP key
lift DEP key
lift DEP key
press ADDR LOAD and
press CLEAR and
press CONT

Both the 8K ROM and 12K TD8E bootstraps perform the
same function, reading record 0 of the system tape into memory
and then starting it at location 7400 in field o. The code that is
read into 7400 is a larger bootstrap which installs all resident
tables and then turns control over to the OS/8 Keyboard Monitor
or the TD8E initialization program. The 12K system must move
down to tape block 154 to accomplish the full bootstrap, which explains the extra tape motion.
When the TD8E system (either 8K ROM or 12K) is initialized,
only TD8E DECtapes 0 and 1 (DTAO, DTAl) are available on
the system. The others (DTA2-DTA7) are not in the system. To
make other drives available, the user must run the BUILD program. Reference the' BUILD section of Chapter 2 for details .concerning reconfiguring a system.
LINCTAPE (PDP-12 USERS)
The following is the bootstrap procedure for PDP-12 'systems:
1. Mount the system LINCtape (DEC-12-0SYSB-A-ACl) on
LINCtape 'unit o. Set the LINCtape switches to WRITE LOCK
and REMOTE. Set the terminal to LINE or to REMOTE.
2. Set the left switches to 0700. Set the right switches to 0000.,
Set the MODE key to LINC.
3. 'Press I/O PRESET.
4. Press DO.
The LINCtape bootstrap will be executed, causing unit 0 to
move. When tape movement stops, ensure that the AC contains -1 (has all lights on). If the AC does not contain -1,
return to step 1 above.
,1-9

5. Press the START 20 key.
The LINCtape on unit 0 will move again, and a dot (.) will
be printed at the left margin of the terminal. OS/8 is now
active.
6. Set LINCtape unit 0 to WRITE ENABLE.
Building OS /8 From Cassette

,
When OS/8 software is supplied on cassettes, the BUILD system library program is used to create the initial OS/8 system. The
following procedures are used to build OS/8 onto a mass storage
device.

1. The OS/8 cassette containing BUILD (DEC-S8-0SYSB-ATCl) supplied by Digital is WRITE protected (lugged red
tabs' expose write protect holes). Open th~ locking bar on the
right side of cassette transport unit 0 by pushing it to the right.
Hold the cassette so that the DIGITAL trademark in large
letters is upright and to the front. Insert the cassette into transport unit 0, rotating it over the drive sprockets without forcing
it, so that the locking bar closes over the back edge.
Press the rewind button on the cassette transport unit once
to rewind the tape to the beginning of its leader/trailer segment. When the unit stops moving, the tape is positioned for
data transfer operations.
2. Bootstrap the OS/8 cassette by following one of two methods.
If the system includes an MI8-E hardware bootstrap option:
a. Place the terminal on line. Raise the SING STEP switch
on the PDP-8/E console. Press the CONT switch. Then
lower and raise the HALT switch. At least one console
indicator lamp should light.
b. Having mounted the OS/8 system cassette on unit 0 as
described above, lower and raise the SW switch on the
left side of the console.
If the system does not include a hardware bootstrap, this pr9cedure will have no effect. In this case, execute step 1· above
and then perform the switch manipulations in Table 1-4. For
each' step in the table, place each of the PDP-8/E console
SWITCH REGISTER switcbes numbered 0 to 11 either in
the up position if the· corresponding table entry is a 1,. or in
the down position if the corresponding table entry isa O.
When all twelve switches have been set to correspond to a line
1-10

in the table, follow instf.uctions in the right hand column and
proceed to the next line. In step 3, for example, place switches
2, 4, 9, and lOin the up position; place switches 0, 1, 3, 5, 6,
7, 8, and 11 in the down position; lift the DEP switch; and
proceed to step 4. The table also inc1udes octal values of' the
binary switch settings for the benefit of users familiar with
octal numbers.
Table 1-4 .Cassette Bootstrap
STEP OCTAL
# VALUES

SWITCH REGISTER
SETTiNG

4000-

012
100

2
3
4
5
6
7

1237
1206
6704
6706
6703
5204
7264
6702
7610
3211
3636
1205
6704
6706
6701
52i6
7002
7430
1636.
7022
3636
7420
2236
2235
5215
7346
7002
3235
520.1
7737

001 010
001 010
110 I 1I
110 11 I
110 111
101 010
111 010
110- 111
111 110
011 010
011 110.
001 010
110 111
110 III
110 111
101 010
111 000
111 100
001 110
1 11 000
011 110
111 -100
010 .010
010 010
101 0.10
111 011
IlJ 000
011 010
101 010
111 111

9
10
11
12
13
14
15
16

17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

345
000

678
000

91011
000

AND THEN

press ADDR LOAD and
press EXTD ADDRLOAD
011 I 1I
lift DEP key
000 110
lift DEP key
000 100 .. - lift DEP key
000 110 _ lift DEP key
000 011 " lift DEP key
000 100
lift DEP key
110 100
lift DEP key
000 010
lift DEP key
001 000
lift DEP key
001 001
lift DEP key
on 110
lift DEP key
000 101
lift DEP key
000 100
lift DEP key
000 110
lift DEP key
000 001
lift DEP key
001 110
lift DEP key
lift DEP key,
000 0.10
011 000
lift DEP key
011 .- 110
lift DEP key
010 010
lift DEP key
011 110
lift DEP key
'010 -000
lift D EP key .
all 110 lift DEP key
lift DEP key
011 101
0.0.1 101
lift DEP key
100 110,
lift DEP key
000 010
lift DEi> key
011· 101
lift DEP key
OQO 001
lift DEP key
011 HI
lift DI;:P key

1-11

Table 1-4
STEP OCTAL
# VALUES

3557
7730
4000

33
34

Cassette Bootstrap (Cont.)

SWITCH REGISTER
SETTING

011 101 101 III
1 1 1 1 1 1 0 I 1 000
100 000 000 000

AND THEN
lift DEP key
lift DEP key
press ADDR LOAD key and
press CLEAR and
press CaNT

Either bootstrapping procedure should cause the- system cassette to move and BUILD to print a $ at the left margin of the
console terminal. If there is no response, check that the system
cassette is properly mounted on transport unit 0 and repeat the
bootstrapping procedure, paying particular attention to the
swit.ch manipulations. Be careful not to bounce the DEP
switch.
3. When BUILD prints:
$
respond with the system device on which OS/8 is to be built.
(At this point, the usual command editing features of BUILD
are available; see Table 2-10 in the BUILD section of Chapter
2.) This response must be in the following form:
$SYS dev=n
where "dev" represents one of the legal replies taken from
Table 1-5. The "n" is optional and need only be used to indicate the number of physical disk platters which are present if
the system device is RF08 or DF32. The possible replies and
the maximum value of n which can be used for each one are
indicated below.
Table 1-5 Systell! Devices

Maximum n

Device
DF32
RF08
RK8
RK8E

(DF32 disk)
(RF08 disk)
(RK8 disk)
(RK8E disk)

4
4
1

1-12

n must be a digit in the range 1 to 4. If no value for n is specified 1 a value of 1 is assumed. If a response other than a digit
is entered, the message:
?SYNTAX

is printed and the SYS command must be typed again. If n is
specified as a digit but is too large for the device specified, the '
SYS command must be retyped. For example: l
l.SY S RF 08 = 5
?PLAT
!SYS RF08=4

4. When a correct SYS command has been entered, e.g.:
$SYS RK8E

BUILD prints another $. At t~is time, insert the desired devices for the initial system. The minimum system for cassettes
must hav~ inserted the terminal handler, the mass storage device, and the cassette handlers. (See the BUILD section of
Chapter 2 for detailed information.)
In response to the $ printed by BUILD (indicated here by an
underline), type the following; each command line should be
followed by typing the carriage return key.

.!! N
lo! N

TA8 A: CSA0- 1
KL8 E: TTY

(cassette unit 0, drives
(terminal keyboard)

and 1)

5. The user should also specify the device that is to be the default
mass storage· device by entering the· DSK command. For example:
..!DSK=SY S

Any device other than SYS (or carriage return) specified in the
DSK command must be the permanent name of a device which
appeared in one of the INSERT commands.
Characters printed by the system are underlined to eliminate confusion
with characters typed by the user.

1-13

6. When all desired devices have been entered with INSERT 'commands, type the following in responseJ:o the $:

1iBUILD

BUILD responds .by printing:
LOAD OS/8:

type CSAO, followed by carriage return, m response to this
message, I.e.,
LOAD OS/8:

CSA0

BUILD loads and writes the various parts of OS/8 onto the
system device. If a SYS ERR message occurs at any time during the load, ensure that the system device is write-enabled and
press the CONT switch to retry. 'If the retry is unsuccessful, return to step 2.
7. After writing OS/8, BUILD prints:
LOAD CD:

Respond with a carriage return. BUILD loads the Command
Decoder from cassette unit and writes it onto the system deVIce.
8. Wh~n BUILD responds with another $, type the following:

loB 001

to initiate the final system creation process. BUILD creates
05/8 on the system device, writes AB5LDR on the system
device, and prints:
SY S BUI L T

•

The dot indicates that the OS/8 Keyboard Monitor is activated.
BUILD is still in memory at this time and must be written onto
the system device. To save the copy of BUILD just used with
the current date, type:

1-14

..,:.DATE mm/dd/yy

(mm=month, dd=day, yy=year)

.!.SAVE SY!? BUILD

This copy of BUILD reflects the current configuration of the
system. It can be loaded and rerun with the command:
.:..RUN SY S BUI L D

9._ The OS/8 system programs must now be loaded from their respective cassettes. To load these programs, it is first necessary
to load MCPIP (Magnetic Tape/Cassette Peripheral Interchange -Program). Type the following commands to load
MCPIP .
.:.GET SY S BUI LD.
.:..START 17 400
• SAVE SY S M CPI P; 12000= 6400

Loading System Programs From Cassette
After creating an OS/8 system from cassettes, the user must
transfer the system programs from cassette to the system device.This transfer operation is performed with MCPIP which the user
has saved on the system, device.
NOTE
Users with OS/8 software supplied on DECtape (LINCtape) already have core images
of the system programs on the system device. This section concerns only users with
software supplied on c·assettes.
Each cassette supplied with OS/8 contains several OS/8 system
programs: To transfer the programs to the system device, the user
mounts the appropriate cassette on a cassette drive and types
MCPIP commands as shown below. Use the following procedures
to load the system programs.
1. Mount the system cassette DEC-S8-OSYSB-A-TC2 on cassette
drive O.
2. Mount the system cassette DEC-S8-OSYSB-A-TC3 on cassette
drive 1.
1-15

3. Type the following to call MCPIP from the system device:
~R

MCPI P

MCPIP responds with an asterisk, indicating that it is ready to
receive a command line of I/O specifications.
4. Respond as follows to the asterisks printed by MCPIP:
~SYS:CCL.SV
~SAVE

SYS FORT

SABR (DEC-S8-0SYSB-A-PB7)
Place the SABR Assembler binary tape in the reader, and type
the following responses to load and save SABR.
!oR ABSLDR
,£f'TR:(SP)$
..:..SAVE SYS SABR

1-21

LOADER (DEC-S8-0SYSB-A-PB8)
Place the Linking Loader binary tape in the reader, and type the
following responses to load and save LOADER .
.:.R ABSLDR
!.PTR: /9 $
.&.SAVE SY S LOADER

LIBSET (DEC-S8-0SYSB-A-PB9)
Place the Library Setup binary tape- in the reader. Type the·
following:
.!,.R A8SLDR
.!.PTR: 12600$
~SAVE SYS LIBSET

LIB8 (DEC-S8-0SYSB-A-PR)
Place the LIB8 relocatable binary tape in the reader and type the
following:
~R

LI BSET

~,/S$

The tape is read and a LIB8.RL file is created on the system'
device.
CREF (DEC-S8-0SYSB-A-PBIO)
Place the CREF binary tape in the reader, and type the following responses to load and save CREF .
.:.R ABSLDR
*PTR: /9 $
:- SAVE SY S CREF

EDIT (DEC-S8-0SYSB-A-PBIl)
Place the Editor binary tape in the reader, and type the following responses to load the tape and save EDIT on the system device .
..:.R ABSLDR
*PTR:/9$
.s.SAVE SY S EDI T

1-22

, PAL8 (DEC-S8-0S¥SB-A:'PB12) :c',
Place the P AL8 Assembler binary tape in the reader, and type
the following responses to load and save P AL8 .
.,:.R ABSLDR
.!PTR: 19 $
..t.,SAVE SY S PAL8

PIP (DEC-S8-0SYSB-A~PBI3)
Place the PIP binary tape in the reader, and type the fol1o~ing
responses to load and save PIP .
.:.R ABSLDR
13000(89P)$
.:.SAVE SY S PI P

~PTR;

MCPIP (DEC-S8-0SYSB:A-PB 14 )
Place the MCPIP binary tape in the reader, Clnd type the following responses to load and save MCPIP ..
• R ABSLDR
;PTR: 12000C89P)$
7SAVE SY S MCPI P ,

BITMAP (DEC-S8-0SYSB-A-PB 15)
Place the BITMAP binary tape in the reader, and type the follow.
ing responses to load and save BITMAP.
• R ABSLDR
iPTF: 12000/9$
• SAVE SY S BI TMAP

EPIC (DEC-S8-0SYSB-A-PBI6)
Place the EPIC 'binary tape in the reader, and type the following
responses to load and save EPIC.
~R ABSLDR
!.PTR:$
• SAVE SY S EPI C

1-23

SRCCOM (DEC-SS-OSYSB-A-PB17)
Place the Source Compare binary tape in the reader, and type
the following responses to load and save SRCCOM.
• R ABSLDR
iPTR:$
• SAVE SY S SRCCCM

CCL (DEC-SS-OSYSB-A-PB1S)
Place the Concise Command Language binary tape in the reader,
and type the i6110wing responses to load and save CCL.
..:..R ABSLDR
12001< 89) $
• SAVE SY S CCL

~PTR:

FOTP (DEC-SS-OSYSB-A-PB 19)
Place the File Oriented Transfer Program binary tape in the
reader, and type the following responses to load and save FOTP .
.!oR ABSLDR
!.PTR: 14600(-89P) 11
.SAVE SYS FOTP

RESORC (DEC-S8-0SYSB-A-PB20)
Place the Resources binary tape in the reader, and type the following responses to load and save RESORC.
,!,.R ABSLDR
*PTR: 12000(89) $
·7SAVE SYS RESORC

DIRECT (DEC-SS-OSYSB-A-PB21)
Place the DIRECT binary tape in the reader, and type the following responses to load and save DIRECT .
.:.R ABSLDR
*PTR: 111600(89P) $
7SAVE, SYS DIRECT

1-24

PIPlO (DEC-S8-0SYSB-A-PB22)
Place the PIP 10 binary tape in the reader, and type the following
responses to load and save PIP10.

• R ABSLDR

£ pTR:$
.:..SAVE SY S PI PIe

CAMP (DEC-S8-0SYSB-A-PB23)
Place the Cassette and Magnetic Tape Positioner program binary
tape in the reader, and type the following responses to load and
save CAMP.

• R ABSLDR

iPTR: $
.....SAVE SY SCAMP

BOOT (DEC-S8-0SYSB-A-PB24)
Place,the BOOT binary tape in the reader, and type the following
responses to load and save BOOT.
• R ABSLDR
*PTR:$
-7SAVE SY S BOOT

This completes the building of the 08/8 system. If the OS/8'
extension kit paper tapes are available, see the appropriate chapters
for loading instructions. Additional device handlers may be loaded
and made active using BUILD. See the BUILD section in Chapter
2 for this procedure.
Disk as the System Device
,
If disk is to be the OS/8 system device, an OS/8 system must
be built onto the disk from the distribution media, i.e., cassettes,
paper tape, or DECtape (LINCtape). The disks available as system devices are RF08, DF32, RK8, and RK8E. Refer to the appropriate part of this section for the cassette or paper tape building
procedure. For DECtape or LINCtape distribution, refer to the,
BUILD section of Chapter 2.

1-25

Once an OS/8 system has been built on a disk, it m:ayoccasionally be necessary to start (bootstrap) the system into operation
when nothing is in memory. For example, whenever an RK8E disk
. Gartridge is placed into its slot and is to be used, the system should
be bootstrapped. Also, if a program error is encountered such that
the contents of locations 7600-7777 in either field 0 or field 1 are
in doubt, the system should bepootstrapped. The following sections detail the specific bootstrap used for each type of disk.
"

RF08 AND DF32 DISKS
If the OS/8 system device is an RF08 or DF32 disk, use the
bootstrap shown in Table 1-7.
Table 1-7 RFOS/DF32 Disk Bootstrap
STEP OCTAL
# VALUES

1
2
3
4
5
6
7
8

0000
7750
7600
6603
6622
5352
5752
7750

SWITCH REGISTER
SETTING

012 345
000 000
111 111
111 110
110 110
110 110
101 011
101 III
111 111

678
000
101
000
000
010
101
101
101

AND THEN

91011
000
press EXTD ADDR LOAD
000
press ADDR LOAD
000
lift DEP key
011
lift DEP key
010 . lift DEP key
010
lift DEP key
010
lift DEP key
press ADDR LOAD and
000
press CLEAR and .
press CONT

When the bootstrap has been loaded, the OS/8 Keyboard Monitor should respond with a dot (.). If it does not, repeat the bootstrap procedure. If an error persists, consult the local Digital sales
office.
RK8E DISK
If only one RK8E disk unit is present on the OS/8 system, use
the bootstrap shown in Table 1-8.

NOTE
If a PDP-12 computer is being used, execute

an I/O PRESET in 8 mode before performing step 5 of the bootstrap in Table 1-8.
1-26

Table 1-8 SingleRK8E Disk Bootstrap
STEP OCTAL
# VALVES

1
2
3
4

SWITCH REGISTER
SETTING

012
000
000
IIqilr
101
000

0000
0030
6743
5031
0030

345 678
000 000
000 011
III 100
000 011
000 011

91011
000
000
011
001
000

AND THEN

press EXTD ADDR LOAD .
press ADDR LOAD
lift DEP key
lift DEP key
press ADDR LOAD and
press CLEAR and
press CONT

If more than one, RK8E disk unit is present on the system, the
user may choose which unit (0-3) he wishes to he the system device. To specify"the correct RK8E unit as the system device, load
the OS/8 disk cartridge in the desired unit and enter the bootstrap
shown in Table f ..9.
Table 1-9 Multiple RK8E Disk Bootstrap
STEP OCTAL
# VALVES

1
2
3
4
5
6
7
8

0000
0025
7604
6746
6743
7604
5031
0025

SWITCH REGISTER
SETTING

012 345 678 91011
000 000 000 000
,000 000 010 101
111 110 000 100
110 111 100 110
110 111 100 011
111 110 000 100
101 000 011 001
000 000 010 101

AND THEN

press EXTD ADDR LOAD
press ADDR LOAD
lift DEP key
lift DEP key.
lift DEP key
lift DEP key
lift DEP key
press ADDR LOAD

Enter the desired unit number (0-3) in switch register settings 9
and 10 as follows:
unit
unit
unit
unit

0
1
2
3

all switches down
switch 10 up; all others· down
switch 9 up; all others down
switches 9 and'IO up; all others down

Press CLEAR and CONT.
1-27

•

When either of the bootstraps has been loaded, the OS/8 Keyboard Monitor should respond with a dot (.). If it does not, repeat the bootstrap procedure. If an error persists, consult the local
Digital sales office.
RK8 DISK
If the pser has only one RK8 disk unit on his OS/8 'system, the
bootstrap in Table 1-10 is used to start OS/8. 'Il.
Table 1-10 Single RK8 Disk Bootstrap
STEP OCTAL
# V ALVES

SWITCH REGISTER
SETTING
/"\,""

Vl~

1
2

3
4

0000
0030
6733
5031
0030

345

£"70

V/O.

AND THEN

91 f\1 1

.lV.l.l

000 000 000 000
000 000 011 000
110 111 011 011
101 000 011 001
000 000 011 000

press EXTD ADDR LOAD
press ADDR LOAD
lift DEP key
lift DEP key
press ADDR LOAD and
press CLEAR and
press CONT

NOTE
If a PDP-12 computer is being used, execute

an I/O PRESET in 8 mode before performing step 5 of the above bootstrap.
If more than one RK8 disk unit is present on the system, the

user may choose which unit (0-3) he wishes to be the system device. To specify the correct RK8 unit as the system device, load the
OS/8 disk cartridge in the desired unit and enter the bootstrap
shown in Table 1-11.

1-28

Table 1-11 Multiple RK8 Disk Bootstrap
STEP OCTAL
# VALUES

1
2
3
4
5
6
7

0000
0026
7604
6732
6733
5031
0026

SWITCH REGISTER
SETTING

012
000
000
111
110
110
101
000

345
000
000
110
111
111
000
000

678
000
010

91011
000
110
000 100
011 010
011 011
011 001
010 110

AND THEN

press EXTD ADDR LOAD
press AD DR LOAD
lift DEP key
lift DEP key
lift DEP key
lift DEP key
press ADDR LOAD

Enter the desired unit number (0-3) in the switch register settings 9 and 10 as follows:
unit
unit
unit
unit

0
1
2
3

all switches down
switch 10 up; all others down
switch 9 up; all others down
switches 9 and 10 up; all others down

Press CLEAR and CONT.
When either of the above bootstraps has been loaded, the OS/8.
Keyboard Monitor shouid respond with a dot (.). If it does not,
repeat the bootstrap procedure. If an error persists, consult the
local Digital sales office.

Restarting OS /8
If the OS/8 system ever ceases apparent response to the user,
the computer can be restarted by loading a restart address of either
7600 or 7605. To load a restart address, set the console switches
to 7600 or 7605, press the HALT, ADDR LOAD, EXTD ADDR,
CLEAR, and CONT switches. A period should be printed on the
terminal. If there is no response, OS/8 is no longer in memory and
must be bootstrapped in.
Starting at location 7600 causes the contents of locations 0-1777
to be saved on the system device. These locations are then available
when the Keyboard Monitor resumes operatiori. Starting at 7605
does not save the core locations, but does save time on a DECtape
configuration.

1-29

KEYBOARD MONITOR
The Keyboard Monitor provides communication between the
user and the OS/8 executive routines by accepting commands
from the terminal Keyboard. The Keyboard Monitor allows the
user to create logical names for" devices, run system and user
programs, save programs and to call ODT.
System Conventions
The OS/8 system has various conventions which are quickly
mastered by even the novice programmer. Naming procedures
for devices and· file extensions have been designed as simple
mnemonics. OS/8 makes use of the terms: "word", "page",
"r"""nrrl"
rI "hl",,,lr" a" n ... ;t" of sto .........
'" T... rl: ... o,-o"",[" 1;S.. : .... ,.,.'"
.a. ....
".5\..1.
and elsewhere file lengths are referenced in terms of blocks (or
records). The terms are defined as follows:
"'V.l.""..

':l ...
,UJ..I.\..I.

U.I.'\...Ao.fJ.'tr...

1 block

UJ..l.1"'~

...

~1J.

= 1 record = 2 pages = 256

UJ..l ~""'''V)

1..1

"'J.1.J.b~

words

Each word is composed of 12 bits. The internal structure of the
PDP-8 words and pages is described in detail -in Chapter 2 of

Introduction to Programming
PERMANENT DEVICE NAMES
Each device in the OS/8 system is referenced by means of a
standard permanent device name. These names are used in all
I/O designations and are listed in Table 1-12.
These names are the device names assigned when the OS/8
". system is configured. They may be changed by reconfiguring the
system; however, caution should be observed when doing so.
Certain system programs operate on the premise that a specific
device name will be present in the system; for instance, PIP makes
use of the device name TTY: as the default device when doing
directory listings, CREF assumes LPT: as the default output
device, and the Command Decoder uses device DSK: as the
general default output device. Therefore, it is suggested that the
following device names remain present on the system:
SYS:
DSK:
TTY:
LPT:

1-30

Table 1-12

Permanent Device Names

Permanent Name

I/O Device

SYS

System device (disk if the system has a large disk
-RK8 or RF08; otherwise DTAO).

DTAn

DECtape n, where n is an integer in the range 0
to 7, inclusive.

LTAn

When using BUILD, LINCtapes may be called
LTA rather than DTA. n is an integer in the range
o to 7 inclusive.

DSK

The default storage device for all files. The assignment of DSK is specified at system generation
time. Usually DSK is the disk on a single disk system or DTAO on a DECtape system.

TTY

Terminal keyboard and printer.

PTP

Paper tape punch.

PTR

Paper tape reader (before accepting input, the system prints an up-arrow (i), to which the user replies by typing any key).

CDR

Card Reader

LPT

Line printer (performs a form feed before it begins printing output from a new program).

CSAn

Cassette drive n, where n is an integer in the range
o to 7, inclusive.

MTAn

Magnetic tape drive n, where n is an integer in the
range 0 to 7 inclusive.

DF32 disk ..

RF08 disk.

RKAn

RKO 1 or RK05 disk unit n, where n is an integer
in the range 0 to 3.

VR12 scope (PDP-12 only).

BAT

Pseudo device which reads from BATCH input
stream (see BATCH section in Chapter 2).

1-31

FILE NAMES AND EXTENSIONS
Files are referenced symbolically by a name of up to six alphanumeric characters followed, optionally, by a period and an extension of two alphanumeric characters. The extension to a file
name is generally used as an aid for remembering the format of
a file. Some commonly used extensions are given in Appendix G.
Some programs (e.g., FOTP) also accept the characters * and?
in file names. These characters have special meanings to the programs involved.
In most cases the user will want to conform to the standard
file name extensions established for OS/8. If an extension is not
specified for an output file, some system programs append assumed
extensions. Where an extension for an input file is not specified
by the user, the system does a search for that file name with the
default extension. Failing to find such a file, a search is then
done for the original file without an extension. For example, if
PROG were specified as an input file to P AL8, the Command
Decoder would first look for the file PROG.PA (since .PA is the
standard extension for PAL8 input files). If PROG.PA were
not found, the Command Decoder would try to find the file PROG
(with no extension). As not. all system programs utilize default
extensions, reference the following table and the individual system
programs for details:
\

Table 1-13

Assumed Extensions

Extension

Meaning

.SV

Core image file or SAVE file; appended to a file name
by the R, RUN, SAVE, and GET Keyboard Monitor
commands .

.FT

8K FORTRAN source file .

.SB

8K SABR source file .

.P A·

P AL8 source file .

.BN

Absolute binary file (default extension for ABSLDR,
BUILD, and BITMAP input files. Also used as the default extension ,for PAL8 binary output file).

1-32

Table

1~13

Assumed Extensions (Cont.)

Extension

Meaning

.RL

Relocatable binary file (default extension for a Linking
Loader input file. Also used as the default extension for
an 8K SABR output file) ~
.

~MP

File containing a loading map (used by the Linking
Loader). Also used as default extension for BITMAP
output files .

.LS

Assembly listing output file (default extension for PAL8
and SABR).

.TM

Temporary file generated by FORTRAN or SABR for
system use (default extension for CREF input files and
PAL8 output files).

For example, if the user types:
• RUN DSK PROG

..
the file PROG.SV (on device DSK)
types:

isr~n,

if found. If the user

• RUN DSK PRO G • A

then PROG.A (on device DSK) is run, if found.
Using the Keyboard Monitor
Each command to the Keyboard Monitor is typed at the
terminal keyboard. If corrections ·are necessary, they must be
made before entering the command line to the system. A command line is entered to the system by typing either the RETURN
key, which causes a carriage return/line feed operation but no
printed character, or· an ALTMODE (ESCAPE on some Teletype Keyboards), which prints a $, but causes no carriage return/
line feed. Correcting mistakes is accomplished by typing the RUBOUT key, which deletes the last character typed and causes a
backslash ("'-) character to be printed followed· by the character
1-33

which was deleted. Successive RUBOUTSeach cause one more
character to be printed and deleted. The first non-RUB OUT
character typed (after the last RUB OUT in a sequence) causes
a closing backslash (") to be printed, thus enclosing the deleted
characters with backslashes. For example:

User types:.;..RUN DSK (RUBOUT) (RUBOUT) (RUBOUT) DTAI :FILE
Teleprinter
Shows:
.:.RUN DSK\KSD\DTA1:FILE
Keyboard
!vfonitor SeeS:

.RUN DTAl :FILE

If at any time an input line becomes so corrected that it is no

longer intelligible to the user, he can verify the contents of the
line by typing the LINE FEED key. This causes the entire input
line to be echoed as the Keyboard Monitor would see it at that
point. The line is not considered to be entered to the system, and
the user can proceed to -edit, delete, or enter the lin~ at his
discretion.
For example:
User types:
,:.RUN DTA3,,3,,2:PRG "G"OG (LINE FEED key typed)
System echoes: RUN DTA2: PROG
A command line may be deleted completely before it is entered by typing a CTRLjU (produced by pressing the CTRL key
and U key simultaneously). This echoes as a tU, and returns control to the Keyboard Monitor without accepting the current input
line. Typing a CTRLjU causes a dot (.) to be printed at the left
margin and the Keyboard Monitor is ready to accept commands.

Control can be returned to the Keyboard Monitor while under
any of the system library programs by typing a CTRL/C (produced by pressing the CTRL and C keys simultaneously). This
echoes as 1'C and the Keyboard Monitor signals that it is ready
to accept input by printing a dot (.) at the left margin of the terminal screen or paper.

1-34

KEYBOARD MONITOR COMMANDS
The user has a choice of nine commands which he may type in
response to the dot (.) printed by the Keyboard Monitor. These
are: ASSIGN, DEASSIGN, GET, SAVE, ODT, RUN, R, START,
and DATE. Commands may be abbreviated by typing only the
first two characters. Execution occurs after typing the RETURN
or ALT MODE key.
Any errors the user may make while utilizing these commands
result in an error message being printed by the Keyboard Monitor.
After occurrence of an error, control returns to the Keyboard
Monitor and the command must be retyped. The error messages
and their explanations are listed in Table 1-14, following the descriptions of the commands.
In addition to the Keyboard Monitor commands discussed in
this section, certain extended commands and features are available
to the user through the Concise Command Language (CCL). eCL
simplifies the entry of certain commands and performs operations
which could not be performed otherwise. See the CCL section in.
this chapter for further information.
ASSIGN Command
The ASSIGN command is of the form:

.ASSIGN dev udev
or
.AS dev udev
This command causes a new, user-defined device name (udev)
to be considered equivalent to the permanent device name (dev).
Only one ,user name can be associated with a single device at a
time. For example: .

• AS DTAI

causes all future references to IN to refer to DECtape unit 1,
(references can still be made to the device DTAl also).
If a user-defined device name is not indicated, any existing
1-35

user-defined name is removed and only the permanent device name
is valid. For example:
.AS DTAl

.AS DTAl

The above sequence changes the name of DECtape 1 to IN and
then back to simply DTAI again ...
The user-defined name is composed of up to four alphanumeric
characters; the user-defined name takes precedence over the permanent name., Device-independent programs are easily possible
since a change in the user name of a device by means of the ASSIGN command can change the operation of a routine without
changing the code.
Althuugh user-defined names may be four characters long, the
name may not be unique in the OS/8 system. (This is due to the
fact that the device name is internally coded in only one word.)
A three or four character name may be tested for uniqueness by
typing an ASSIGN command as follows:
.AS name
If a 'name NOT AVAILABLE' message results, the name is
unique within the current system, is not in the system tables, and
therefore may be used.
All user-defined device names of one or two characters in
length are unique.

DEASSIGN Command
The DEASSIGN command is of the form:
.DEASSIGN
or
.DE
and causes all permanent device names to be restored, discarding all previous user-defined device names. For example:
.AS DTAl

• DE

causes DECtape 1 to be assigned the name IN. The DEASSIGN
command removes the name IN from the system tables; DTA 1
can no longer be referenced as IN.

1-36

OETCommand
The GET command is of the form:
.GET dev file.ex
or
.GE dev file.ex
The GET 'command loads core image files (.SV format, not
ASCII or binary) into core from a device. This device (dev) is
specified along with the file name (file) and an optional file name
extension (.ex). The file is loaded into core with its core control
block; the core control block is then moved to a special area on
the system device, where it is maintained on the system device
and contains information about the file such as its starting address and areas of core occupied by the file. Also contained is a
Job Status Word, which IS saved (with the SAVE command) and
. loaded in location 7746 of field 0 with the file to indicate what
part~ of core the file uses and how, as follows:

Job Status Word

Bit Condition

Meaning

Bit 0 = 1

File does not load into locations 0-1777
field 0, (0000-1777).

Bit 1 = 1

File does not load into locations 0-1777 in
field 1, (10000-11777).

Bit 2 = 1

Program must be reloaded before it can be
restarted because it modifies itself during execution.

Program being run will not destroy the BATCH
monitor.

Bit 3

Bits 4 -- 9

III

. Unused, and reserved for future expansion.

Locations 0-1777 in field 0 need not be saved
when calling the Command Decoder overlays.

Bit 11 = 1

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

Bit 10

1-37

A core control block is created for each core-image file when the
file is created by the Linking Loader, ABSLDR, or the SAVE
command.
If a fUe name extension is not specified to the GET command,
the extension .SV (for core-image file) is added automatically to
the file name. For example:
.GE DTA3 OH

attempts to fetch the-file OH.SV from device DTA3.
The GET command is typically used _before a debugging session with ODT. GET is used to load the object program into
core, then ODT is called~ and the program can be altered and/
or debugged (see the section on ODT for more details).

SAVE Command
The SAVE command is of the form:
.SAVE dev file.ex a-b,c, ... ;s=n
or

.SA dev file.ex a-b,c, ... ;s=n
where:
a-b,c,...

are the addresses of the areas and locations in core to
be saved. (In this case, locations a through b, location c, and any other specified locations.) a, b, and c
are five digit locations. (The first digit represents the
field.) When a single location is indicated (c) the
entire page on which c is located is saved.

is the starting address of the file.

n is a four digit octal number representing the contents of the Job Status Word (see the GET command).

The program currently in core is saved on the device (dev)
specified, with the file name indkated (file.ex). If an extension
is not specified, the extension .SV is automatically added by the
system. If the remaining arguments are not given, the required
information is taken from the current core control block (refer
to the GET command).

1-38

There are some restrictions. on the ' SAVE arguments which
should be noted:

1. Each set of limits (a,-b) must be in the same field and not
cross field boundaries. For example:

-.SAVE

SYS FOO'0200-20200

is illegal since the limits transcend a field boundary.
2. No two sets of limits can overlap; (i.e. a-b, c-d must not
overlap). In fact, once a location,on a specific page is in.:.
cluded in the limits, any other location on that _core page,
whether overlapping or not, will produce an error message.
For example:
.SAVE'SYS FOO 0-177~200-377islegal,but
• SAVE SYS FOO

0- 200~ 20 i - 377 is illegal.

3. In SAVEs involving' memory fields other than field 0, the
field must be specified before' each of the two core limits.
If the, field is unspeCified, field 0 IS assumed. Thus:
:.SAVE SYS FOO

20200-0377 is illegal, while

• SAVE SYS FOO

20200-20377 is legal.

4. SAVE files can include 7600 in any field. However, extreme
care must be taken when manipulating these areas, particularly in fields 0 and 1, as the system resident code could
be destroyed by GETting area 07600-07777. It is suggested that SAVEs involving 7600 be limited to fields above
'
field 2.

5. If the first location of a page is not a multiple of 400, that
page cannot be saved without the previous page. Thus the
following commands are equivalent:
.SAVE DSK PROG 2634
DSK PROG 2400-2777

~SAVE

1-39

If an error message is printed in response to a SAVE command,
the program currently in core has not yet been saved. The core
image, however, is still intact.

Examples of SAVE commands are:
~SAVE

DSK CPROG

55~10500-10577;

10502

This statement saves the program in core on the disk as a file
named CPROG.SV. The areas of core saved are locations 0 to
177 in field 0 and locations 400 to 577 of field 1 (when a single
. core location or part of a page is indicated, the entire page on
which the locations occur is saved). The starting address of the
progt;am is 502 in field 1. The core control block is updated to
contain this information and the old Job Status Word is taken
intact from the original core control block .
• SAVE DSK CPROG

The above statement causes the program in core to be saved on
device DSK under the name CPROG.SV where the areas of core
to be saved are taken from the core control block currently
available.

ODT Command
The ODT command is of the form:
.ODT
or
.OD
This command causes the system ODT to be loaded into core
and started-. ODT is a system overlay, and as such takes up none
of the user's program area unless the breakpoint feature is used,
in which case ODT uses locations 4, 5, and 6 of every field in
which a breakpoint had been placed. When using ODT to debug
programs, the user-defined oevice names cannot be used; each
I/O device must be called by its permanent device name ..
ODT is described in greater detail later in this chapter.
1-40

RUN Command
The RUN command is of the form:
.RUN dev file.ex
or
.RU dev file.ex
The RUN command, like the SAVE command, handles' only
core-image files. The file indicated (file.ex) on the device specified (dev) is loaded into core and its core control block is moved
to the system scratch area. The program is started at its starting
address. The RUN command is equivalent to a GET and a START
command.
If an extension to the file name is no.t specified, the extension
.SV is automatically added to the file name. For example:

• RU DIAl PROG

causes the filePROG.SV on DECtape 1 to be loaded and started.

R Command
The R 'Command is of the form:
.R file.ex.
and is similar to
.RUN SYS file.ex
This command handles only. core image files from the system
device. The file is loaded and started. If the file name extension
is not specified, the extension .SV is automatically added.
The R command differs from the RUN command in that a core
control block is not written to the system device. In order to save
a program which does not have its core control block in the usual
location on the system device, all the optional arguments of the
SAVE command must be explicitly stated. System programs are
most often called using the R command, since they need not be
resaved.
To call a program which is to be later updated and saved, use
. of the RUN or GET commands is suggested.
START Command
The ST ART command is of the form:
1-41

.START nnnnn
or
.ST nnnnn
The program currently in core is started at location nnnnn. If the
argument nnnnn is omitted, the program is started at the starting
address specified in the core control block.
For example:

.ST 10555

•

,starts the program in core at location 555 in field 1.

• ST,

starts the program at the starting address given in the c~re control
block.
The ST ART command clears certain areas of core-the device
handler in core table and the Command Decoder output area.

DATE Command
The DATE command is of the form:
.DATE mmjdd/yy
or
.DA mmjddjyy
The DATE command sets up the date in the system for purposes
of dating directory entries and listings, printing on program output,
etc. For example:
.DA 3/13/74

indicates that the date is March 13, 1974.
Keyboard Monitor ~rror Messages
Table 1-14 lists the generalized and command Keyboard Monitor
errors. All errors return control to the Keyboard Monitor and the
command must be retyped. xxxx indicates the core location where
the error was detected.
1-42

Table 1-14 Keyboard Monitor Error Messages

Meaning

-Message
BADARGS

The arguments to the SAVE command are not consistent and violate
restrictions listed in 1, 2, 3 under
SA VE command.

BAD CORE IMAGE

The file requested was not a coreimage file (it could have been an
ASCII or binary file).

BAD DATE

The date has not been entered correctly (using slashes), or incorrect
arguments were used, or the date
was out of range.

ILLEGALARG.

The SAVE command was not expressed correctly; illegal syntax used.

MONITOR ERROR 2 AT xxxx Attempt made to output to a
(DIRECTORY II 0 ERROR) WRITE-LOCKed device, usually
DECtape; or an error has occurred
reading/writing a directory.
MONITOR ERROR 5 AT xxxx An error occurred while doing I/O
(I/O ERROR ON SYS)
to the system device. This error is
normally the result of not WRITE..
ENABLing the system device.
MONITOR ERROR 6 AT xxxx This message results if a directory
(DIRECTORY OVERFLOW) overflow- has occurred (no room for
tentative file entry in directory).
name NOT AVAILABLE

The device with the name given is
not listed in any system table, or it
is not available for use at the moment
(check the device in question), or
the user tried to obtain input from
- an output-only device (such as the
high-speed paper tape punch).

name NOT FOUND

The file with the name given was not
found on the device indicated, or the
user tried to input from an outputonly device.

NO!!

The user attempted to start (with
.ST) a program which cannot be
started. The user must not restart
any user program or system library

1-43

Table 1-14

Keyboard Monitor Error Message (Cont.)

Message

Meaning
program which modified itself while
in core (bit 2 of the Job Status Word
is set; see the GET command for
details).

NO CCL!

The command was not a legal keyboard monitor command. It was, however, a valid CCL command, but the
file CCL.SV was not found or an
II 0 error occurred while trying to
read the file.

SAVE ERROR

An 1/ 0 error has occurred while
saying the program. The program remains intact in core.

SYSTEM ERR

An error occurred while doing I/O
to the system device. The system
should be restarted at 7600 or 7605.
Do not press CONTinue, as this is
sure to cause further errors.

TOO FEW ARGS

An important argument has been
omitted from a command. For example,
:.RUN DSK

would generate this message, as the
program to be run has not been
entered in the command.
USER ERROR 0 AT xxxx

An input error was detected while
loading the program. xxxx refers to
the Monitor location where the error
was generated.

abed?

Where abed is not a legal command;
for example, if the user typed:
.:.HELLO

the system would echo:
HELLO?

1-44

CONUtlAND DECODER
Once a system program has been called via the Keyboard Monitor, that system program may make use of the Command Decoder
by permitting the user to enter a list of 1/0 files and devices. The
, Command Decoder prints an asterisk (* )at the left margin to
indicate it is ready to accept a command string.
The Command Decoder uses the same keyboard characters as
the Keyboard Monitor for the purpose of correcting typing mistakes. The RUB OUT key deletes one character per rub out. The
CTRL/U (tU) combination deletes an entire line. CTRL/C returns the user to the Keyboard Monitor, and the LINE FEED key
causes the entire line (preceded by an asterisk) to be printed on
the terminal as it appears in the TTY input buffer.
The description of files, file names, extensions, devices, and device names is contained in the section concerning the Keyboard
Monitor; this description pertains to the Command Decoder as
well.

Command Decoder Input String
The expected string for 1/0 specification takes the form:
DEV:OUTPUT FILES!
EX!

'I:

* *

Search for and remove line feeds
Exit back to Monitor

To remove the line feeds from a series of files, the user specifies
the name of the above file (MACRO.TE) and the name of the file
from which the line feeds are to be removed. For example:
.MUNG MACRO .. FILEl.DA
.MUNG MACRO .. FILE2.DA
.MUNG MACRO .. FILE10.~A

PAL Command
This command runs P AL8 and assembles the source file specified
as the argument of the PAL command. The PAL command has the
form:
.P AL file.ex
If no extension is. given, a search is made for a file with a .P A
extension. If no argument is given, CCL remembers the argument

of the last COMPILE, EXECUTE, or LOAD command.
See Chapter 3 for· a detailed explanation of P AL8.

1-70

•

PRINT Command
The .PRINT command runs a program named LPTSPL; if the
user has such a program on his OS/8 system. This can be a user.
written program ora program obtained from DEeUS.
PUNCH Command
The PUNCH command runs PIP and punches the file specified
on paper tape. This command has theJorm:·

.PU dev:file.ex
IFNZRO NOHSPT <

{
PTP,

(2)

CLA
Cl
JMS
PTPLP, KSF
JMP
(
)
'KRT
AND
TAD
[

D\
l

E{#·-2S

SET LINK

CLL CMX\L
PSETUP

PTPCNT

IKEYBOARD FLAG OFF

PTP1??
PTPM3

KRT\S

#.L

KRS

{#P
#K

SZA CLA
JMP PTPCNT

Summary of Editor Commands
The commands discussed in Table 1- 23 can each be given whenever the Editor prints a # at the left margin. These commands are
of the general form:
1-92

#X
#nX
or
#m,nX
where m and n represent the line number designation, (m~n) and
X represents the command letter. The command is entered to the
Editor with the RETURN key. Numbers used in Editor commands
.
are decimal numbers.
Table 1·23 Symbolic Editor Commands
Command

Format

Meaning

Append the following text being typed
at the keyboard until a form feed·
(ASCII 214 or CTRL/FORM) is
found. The form feed returns control
to command mode. Text input following· the A command is appended to
whatever is present in the text buffer.

List the number of -available core locations in the text buffer. The Editor
returns the number of locations on the
next line. To estimate the number of
characters that can be accommollated
in this area, mUltiply the number of
free locations by 1.7.

#nC

Change the text of line n to the line (s )
typed after the command is entered
(typing a form feed terminates the
command).
".
Delete lines m through n and replace
with the text line (s) typed after the
command is entered. (Typing CTRLI
FORM indicates the end of the inserted lines.) The C command utilizes
.the text collector in altering text.

#m,nC

#nD

Delete line n from the buffer.

#m,nD

Delete· lines m through n from the
buffer. The space used by the line to
be deleted is reclaimed as part of the
DELETE function. (Refer to Text
Collection in the section entitled Editor Text Buffer.)

1-93

Table 1-23
Command

Symbolic Editor Commands (Cont.) .
Meaning

Format.

Output the current buffer and transfer
all input to the output file, closing the
output file.

Follows a string search. Look for next
occurrence of the string currently being sought. (See section under Search
Mode concerning Inter-Buffer Character String Search.)

Get and list the next line which- has a
label associated with it. A label in this
context is any line of text which does
not begin with one of the fo)]owing:
space
I
TAB
RETURN

(ASCIT
(ASCII
(ASCI[
(ASCII

240)
257)
211)
215)

At the termination of a G command,
control goes to command mode with
the c4rrent ]in~ counter equal to the
line just listed.
#nG

Get and list the first line which begins
with a label, starting the search at
line n.

Insert whatever text is typed before
line 1 of the text buffer. The form feed
(CTRL/FORM) terminates the entering process and sends control to the
command mode where Editor prints
a#.

#nI

Insert whatever text is typed (until a
form feed is typed) before line n of
the text buffer.

Inter-buffer search command for character strings (see section under Search
Mode concerning Inter-Buffer Character String Search) .

Kill the buffer. Reset the text buffer
pointers so that there is no text in the
buffer.

1-94

Table 1-23
Command

Symbolic Editor Commands (Cont.)

Format

Meaning

NOTE
The Editor ignores the commands
nK o( m,nK. This is to prevent
the buffer from accidentally being
destroyed if the user means to
type a List command (m,nL).
L

List entire contents of the· text buffer
on the terminal.

#nL

List line n of the text buffer on the
terminal.

#m, nL

List lines· m through n of. the text buf-·
fer on the terminal. Control then returns to command mode.

#m,n$xM

Move lines m through n directly before line x in the text buffer. The $
character represents typing the dollar
sign key (SHIFT /4). The old occurrenee of the moved text is removed;
no buffer space is lost.

Write the· current buffer to the indicated output file and read the next
logical page.

#nN

Write the current buffer to the output
file, zero the buffer, and read the next
logical page. This is done n times until
the nth logical page is in the text buffer. Control then returns to command
mode.
The N command cannot be used with
an empty text buffer. ? is printed if
this is attempted.

Write the entire text buffer to the output buffer.

#nP

Write line n of the text buffer to the
output buffer.

#m,nP

Writes lines m through n, inclusive, to
the output buffer. When this buffer is

1-95

Table 1·23

Command

Symbolic Editor Commands (Cont.)

Format

Meaning
full, the text is output to the indicated'
output file. The P command auto·
matically outputs a FORM character
(214) after the last line of output.

Immediate end-of-file. Q causes the text
buffer to be output. All text written
into the output buffer is then written
into the output file and the file closed,
with control returning to the Keyboard
Monitor.

Read from the specified input device
and append the new text to the current
contents of the buffer. If no input file
was indicated or if no input remains,
a ? is printed and control returns to
command mode.

Character search command (see the
section entitled Search Mode).

Punch trailer tape. Causes 32 frames
of blank tape to be written into the
output buffer (only to non-directory
devices).

If an LP08 line printer is available,.
the V command causes the entire text
buffer to be listed on the line printer.

#nV

List Jine n of buffer on the line printer.

#m,nV

List lines m through n inclusive on the
line printer.

#nY

Skip to a logical page in the input file,
without writing any output. For example:

reads through four logical pages of
input, deleting them without pfJ)ducing
output. The fifth page is read into the
text buffer and control automatically
returns to command mode.

1-96

Table 1-23

Symbolic Editor Commands (Cont.)

Command

Format

Meaning.

#$TEXT"
#$TEXT'

Perform a character string search for
the string TEXT. (See the section under Search Mode concerning IntraBuffer Character String Search). Following a string search, #" causes a
search for the next occurrence of the
string.

By typing these characters the user
can obtain the current line number
( .=) and. the last line number in the
The number is
text buffer (I
printed. by the Editor immediately
after the user types the equal sign.
(The colon character is equivalent to
the equal sign.)

.·=or .:
1= or I:

=).

Equivalent to .+lL; list the next line
in the text buffer on the teleprinter.

Equivalent to .-1 L; list the next line
in the text buffer on the teleprinteI<

LINE FEED
Key

Equivalent to ,+lL; list the next line
in the text buffer on the teleprinter.

Print the current Editor version number.

PERIPHERAL INTERCHANGE PROGRAM (PIP)
PIP is the OS/8 system program which is used to transfer files
between devices, merge and delete files, and list, zero, and compress directories.
Calling and Using PIP
To call PIP from the system device the user types:
R PIP

in response to the dot printed by the Keyboard Monitor. The Com-'
mand Decoder then prints an asterisk at the left margin of the teleprinter paper and waits to receive a line of I/O files and options.
PIP accepts up to nine input files and performs output to a single
output file; options generally are placed at the end of the command string.

1-97

Since PIP performs file transfers for all file types (ASCII, Image
or SAVE format, or Binary), there are no assumed extensions assigned by PIP to file names for either input or output files. All
extensions, where present, must be explicitly specified.
Following completion of a PIP operation, the Command I>e. coder again prints an asterisk at the left margin and waits, for
another PIP I/O specification line. The user can return to the Keyboard Monitor by typing CTRL/C or by terminating the specification line with ALTMODE ..
PIP OPTIONS
The various options allowed on a PIP 1/0 specification line
are detailed in the following table. Either / A, IB, or II is generally indicated for each transfer; if none of these are specified,
the .system proceeds as though IA had been typed.
.

Table 1-24 PIP Options

Option

Meaning

Transfer files in ASCII mode. The file is modified as it is
copied: embedded blank tape and rubouts are deleted and
leader / trailer code is reducd to a standard length. PIP may
also do some editing of the input file under control of the
/ C and / T options (see below) .
Transfer files in Binary mode (used for absolute and relocatable binary files). Leader/trailer code is reduced to a
standard length, but the checksum is not recalculated.
NOTE
If several absolute binary files are combined
into one, the / S option must be indicated to
the Absolute Loader in order for the files to
load properly. (The Linking Loader will not
load combined files.)
Eliminate trailing blanks. Valid in ASCII mode only.
Delete the old copy of the output file before doing any
data transfer. If / D is not used, the old copy is not deleted
until all input has been processed. For example:

/C
/D

*DTA1:0FILE typed and prepare to insert subsequent values beyond the
one(s) skipped.

RETURN key'

Close the previously opened location.

LINE FEED key

Close location; open the· next sequential location for modification, and print the contents of
that location.

Open the current location plus n for modification and print the contents of that location.

Open the current location minus n for modification and print its contents.

t or "
(up-arrow or
circumflex)

Close location, take contents of that location
as a memory reference and open the location
referenced, printing its .contents.
NOTE
No distinction is made between instruction
op-codes when using t. Thus, all op-codes
(0-7) are treated as memory reference
instructions. Also, great care should be
exercised when using t with indirectly referenced auto-index registers. If t is used
in this case, the contents of the auto-index
.. register is incremented by one. The user
must 'check to see that the register contains
the proper value before proceeding.

~or

(back-arrow
or underline)

Close location, take .contents of that location.
as a 12-bit address and open that address for
modification, printing its contents.

nnnnnG

Transfer control of program to location nnnnn,
~here the first digit represents the memory field.

nnnnnB

Establish a breakpoint at location nnnnn, where
the first digit represents the memory field. Only
one breakpoint is allowed at any given time.

1-123

Table 1-28

ODT Command Summary (Cont.)

Command

Meaning

Remove the breakpoint.

Open for modification the location in which
the contents of the accumulator were stored
when the breakpoint was encountered.

Open for modification the location in which
the contents of the link were stored when the
breakpoint was encountered.

C
nnnnC

Proceed from a.breakpoint.
Continue from a breakpoint and iterate past the
breakpoint nnnn times before interrupting the
user's program at the breakpoint location.
Open the search mask, initially set to 7777,
which can be changed by typing a new value.

LINE FEED

Open the lower search limit. Type in the location (4 octal digits) where the search will begin.

LINE FEED

Open the upper search limit. Type in the location (4 octal digits) where the search will
terminate.
Search the portion of core as defined by the
upper and lower limits for the octal value nnnn.
, Search can only be done on a single memory
field at a time. See the F command.

nnnnW

Open for modification the word containing the
data field which was in effect at the last breakpoint. Contents of D always appear as multiples of las-i.e., 10 means field 1, 20 field
2, etc.

CTRL/O

Stop any printing currently in progress.

Open for modification the word containing the
field used by ODT in the W (search) command, in the ~ and t (indirect addressing)
commands, or in the last breakpoint (depending upon which was used most recently. The
contents of F are always expressed as multiples
of las (as in the D command).

RUBOUTkey

Cancels previous number typed, up to the last
non-numeric character typed.

1-124

. batch
bitmap
boot
build
camp
creP
direct

•

epic
. r:otp
•
mcplp
•
plp10
resorc
srccom.
teco

2
utility programs
BATCH

Introduction
OS/8 BATCH provides PDP-8 users with a batch processing
monitor that is integrated into the OS/8 monitor structure. The.
system is organized in such a way that it may be used in either a
keyboard input configuration or as a batch stream processor.
BATCH may be run on any OS/8 system equipped with at least
12K of memory. A li1).e printer, although optional, is highly desirable. BATCH will support up to 32K of memory and any I/O
devices that are present in the system.
OS/8 BATCH processing is ideally suited to frequently run pro_duction jobs, large and long-running programs, and programs that
require little or no interaction with the user. BATCH permits the
user to prepare his job on punched cards, high-speed
paper tape or
,the OS/8 system device and leave it for the computer operator to
start and run. Output is returned to the user in the form of line
printer and/or teleprinter listings that include program output as
well as a comprehensive summary of all action taken by the user
program, the monitor system and the computer operator.
BATCH provides optional' spooling of output files. This feature
serves to increase throughput on any system, but it is particularly
valuable when a line printer is not available. BATCH also performs
extensive command analysis and error diagnosis, as well a.s detailed
interaction with the user/operator to facilitate initializing the system and establishing system parameters.
Almost any program that runs under interactive OS/8 may also
be run under BATCH. Since BATCH is called from the keyboard
_ in the same manner as any other system program, interactive users
may use BATCH to execute multiprogram utility routines, even
when continuous batch processing is not desired.
i -

2-1

With a few exceptions, BATCH uses the standard OS/8 command set. BATCH assumes that the reader is familiar with the
operation and use of OS/8.
BATCH Processing Under OS/8
OS/8 BATCH maintains an input file and an output file. The
BATCH input file may be a punched card; high-speed paper tape,
disk or DECtape file consisting of a series of BATCH commands.
If the input file is a disk or DECtape file, it must reside on the

OS/8 system device or on a device whose handler is co-resident
with the OS/8 system device (e.g., RKBO on RK05 systems).
Each command in the BATCH input file 'occupies one file record.
If the file is a ...Dunched card file.' each ...Dunched card constitutes one
record, which must contain one complete BATCH command. If
the file resides on paper tape, disk or DECtape, each record consists of one logical line, or all the characters between two line
terminators, including the second terminator.
The BATCH output file is a line printer listing on which BATCH
prints job headers, certain messages that result from conditions
within the input file, an imf(ge of each record in the input file and
certain types of user output. If a line printer is not present i~ the
system, the output file is printed on the terminal.
BATCH accepts user input files (i.e., program and data files)
from any device in the OS/8 system, with the exception that highspeed paper tape input files are not allowed when the BATCH
input file also resides on high-speed paper ~ape. User output files
may be directed to any output device in the system.
BATCH also permits optional spooling of output files. When
spooling is requested, every non-file;:-structured output file is assigned a file name from a lis't, of names maintained by BATCH
and directed to a file-structured spool device instead of the user
specified device. Spooling of output files increases BATCH throughput when system resources are scarce and permits slow output
operations to be postponed until a more favorable time. For example, a batch processing run that generates many output listings
may be initialized to re-route all listings from the terminal or line
printer to a specified DECtape unit. This DECtape may be dumped
onto the appropriate hard copy device after the run, when more
time is available. The spool device may be any file-structured device selected by the user.
2-2

OS/8 BATCH is called from the keyboard by typing:
R BATCH
(terminated by a carr!age return) in response to the dot generated .
by the OS/8 monitor. BATCH then calls the OS/8 Command
Decoder to obtain its parameters, input device and file name (if
file-structured). If CCL is enabled, BATCH may also be invoked
via the SUBMIT command, in which case the BATCH parameters,
input device and file name (if file-structured) are specified on the
same line as the SUBMIT command.
The format for a BATCH command string is:
*SPDV: ~DEV: INPUT/ option/ option

where SPDV: is the device on which to spool non-file-structured
output. If SPDV: is not specified, no spooling is performed. Note
that spooling applies only to non-file-structured output devices
specified to the Command Decoder. The output of programs such
as FOTP, which use a special mode of the Command Decoder, is
not spooled by BATCH. DEV : INPUT is the input device and file
if the input is from SYS: or a device whose handler is co-resident
with SYS:. The default extension for BATCH input files is .BI.
The Run-Time Options are used to specify input from the paper
tape reader or the card reader. The Run-Time Options and their
meanings are listed in Table 2-1.
Table 2-1 Run-Time Options
Option
IC

Meaning
The input file is to be read from the card reader (CRS! I or
eRS/E)

;' Q
IT

Treat OSI S Keyboard Monitor and OSI S Command Decoder
errors as non-fatal errors. If / E is not specified, OS/ S Keyboard Monitor and OSI S Command Decoder errors cause the
current job to be aborted.
The input file is to be read from the paper tape reader.
Do not output a BATCH log. $JOB and $MSG are the only
line output to the terminal.
Output the BATCH log to the terminal. This option need be
specified only if a line printer is available. If a line printer is
not available, the BATCH log is automatically output to the
terminal.

2-3

Table 2-1 Run-Time Options (Cont.)
Option

Meaning

B-ATCH will not pause for operator response to $MSG lines.
Any attempt to use TTY:, PTR:, or CDR: as input devices to
the Command Decoder in an unattended BATCH stream will
cause the current job to be aborted.

Print the version number of OS/ 8 BATCH on the terminal.

Accept card input in DEC 026 format. This option is used
only when the I C option is specified. The default card input
format is DEC 029.

B-ATCH Monitor Commands

A BATCH command is a character or string of characters that
begins with the first character of a record in the BATCH input
file. If the input file is a disk, DECtape or paper tape file, each
BATCH command must be followed by a carriage return/line feed
combination. If the input file is a punched card file, each command
must begin in the first column of a punched card. Disk and paper
tape files may contain form feed characters. Form feed characters
are ignored by BATCH on input.
OS/8 BATCH recognizes four monitor level commands. These
commands allow routine housekeeping operations in a multi-job,
batch processing environment and provide communication between
the BATCH programmer and the computer operator. Table 2-2
lists the BATCH monitor commands, which may be considered as
an extension of the OS/8 Keyboard Monitor command set. Note
that the first character of the $JOB, $MSG and $END commands,
is a dollar sign (shift/ 4). The BATCH monitor does not recognize
the ALT MODE character.
In the current version, any record that begins with a dollar sign
character but is not one of the BATCH monitor commands listed
above is copied onto the output file and ignored by BATCH.
A BATCH processing job consists of a $JOB command record
and all of the commands that follow it up to the next $JOB or
$END record. Normally, all the commands submitted by ~me user
are processed as a single job, and all output from these commands
appears under one .job header. '
2-4

Table 2-2 BATCH Monitor Commands
Command

Meaning

$JOB

Initialize for a new job and print a job header on the
output file. The remainder of the $JOB record is included
in the job header but ignored by BATCH. It should be
used for job identification, to provide correlation between
Teletype output, line printer output and spool device
output.

$MSG

Ring the terminal bell and print an image of the record
at the teleprinter. If the IV option was not specified, implying that an operator is present, BATCH will pause
until al1Y key is struck at. the keyboard. If the I V option
was specified, processing continues uninterrupted.

$END

Terminate batch processing and exit to the OS/8 Keyboard Monitor. A $END command record should be the
last record of every BATCH input file.

. Copy the record onto the output file, then ignore it.·
'\I, BATCH assumes that every record beginning with a slash
is a comment.

After BATCH encounters a $JOB command, it scans the input
file until the next Keyboard Monitor command is read. Any records
that follow the$JOB command and precede the first Keyboard
Monitor command are written onto the output file and ignored by
BATCH.
The first character of every Keyboard Monitor command record
is a dot (.). The rest of the record contains an OSj8 Keyboard
. Monitor command, which should appear in standard OSj8 f~rmat;
however, commands that would be terminated with an ALT
MODE under interactive OSj8 should be terminated with· a dollar
sign under BATCH. Every standard OSj8 Keyboard Monitor command is legal input to BATCH; however, the ODT command. will
go to. the terminal for input instead of the BATCH file. Typing
CTRLjC to ODT will terminate BATCH. Type: 7600G to ODT
to resume the BATCH run.
BATCH executes ~ Keyboard Monitor command by stripping
off the initial dot character and loading the remainder of the record
into the Keyboard Monitor buffer. BATCH then passes control to the Keyboard Monitor, which executes the command as though it
2-5

had been typed at the keyboard. Keyboard Monitor commands that
return control to the monitor level should be followed by a BATCH
monitor command or another Keyboard Monitor command. Keyboard Monitor commands that transfer control to the program level
should be followed by a Command Decoder file specification whenever the running program calls the Command Decoder. All OS/8
V3 CCL commands are legal under BATCH, including the SUBMIT command (which can be used to chain from one BATCH
stream to another) .
When a running program calls the Command Decoder, the Command Decoder determines whether batch processing is in progress
and, if so, instructs BATCH to read the next record of the BATCH
input file .. BATCH expects, this record to contain a Command
Decoder file specification.
The .first character of every Command Decoder file specification
record is an asterisk (*). The rest of the record contains an OS/8
Command Decoder file (and/or option) specification, which should
appear in standard OS/8 format. As with BATCH monitor commands and Keyboard Monitor commands, any Command Decoder
specification that would be terminated witb an ALT MODE under
interactive OS/8 should be terminated with a dollar sign under
BATCH.
BATCH executes a Command Decoder file specification by
stripping off the initial asterisk character and loading the remainder
of the record into the Command Decoder buffer. BATCH then
passes control to the Command Decoder, which decodes the file
specification as though it had been typed at the keyboard and returns control to the running program.
If BATCH reads a record from the input file, expecting to find a
Command Decoder file specification, and finds a Keyboard Monitor
command instead, BATCH returns control to the monitor level by·
recalling the Keyboard Monitor to execute the command. The running program is terminated and control remains at the monitor
level. If BATCH encounters a BATCH monitor command when it
expects to find a Command Decoder specificatioIl, it executes the
BATCH monitor command and continues processing the input file.
As long as a Command Decoder file specification is finally read
before the next Kevboard
Monitor command, . control will eventu.
ally return to the running program, and the file specification will be
executed.
2-6

A BATCH monitor command is legal at any level of command
execution, and the BATCH monitor returns ,control to the level
from which it was entered. Keyboard Monitor commands are also
legal at any level (under BATCH, but not under interactive OS/B); .
however, the Keyboard Monitor terminates any program that may
be running when it is called and returns control to the monitor'
level.
The computer operator may type CTRL/C at any time during a
batch processing run. Typing CTRL/C at the program level causes
an effective jump to location 07600, which recalls the BATCH
monitor. The BATCH monitor then recognizes the CTRL/C and
terminates the BATCH run.

The BATCH Input File
Figure 2-1 shows a listing of a BATCH input file. This listing
was produced by using PIP to transfer the BATCH input file from
disk to the console terminal, and the output has been reproduced
intact. Assume that OS/8 BATCH is loaded on a 12K system containing one TU56 dual DECtape transport, a line printer, a Teletype terminal, and a disk as the system device. If the disk file shown
in Figure 1 is specified as an input file, B4TCH will begin processing by printing a job header and executing the DATE command.
Control remains at the monitor level, so BATCH executes the
next command by calling and starting the Peripheral Interchange
Program. PIP, in turn, calls the.Command Decoder, which accepts
and decodes the file/option specification that occupies the next
executable record (following the comment) of the input file. The
Command Decoder passes control to the program level, and PIP
lists the short form of the system disk directory at the terminal.
If spooling is active, BATCH will intercept this output and store
it in a temporary file on the spool device. Assuming that DTAO is
the spool device and this listing is the first non-file-structured output file intercepted by BATCH, the output will be stored in a file
named BTCHAI. BATCH then prints the message:
#SPOOL TO FILE BTCHA1
on both the console terminal and the line printer. The next file that
is rerouted to the spool device will be assigned the file name
BTCHA2, and successive files will be named:
2-7

BTCHA3
BTCHA4

BTCHA9
BTCHBO
BTCHBI

BTCHZ9
SJOrl 051S BATCH P~OCESSING EXAMPLE $1
.LJATE 3/5/14
.~ PIP
ILIST SYSTEM DEvICE DIRECTORV ON TE~ETYPE
*TTYI
INO~ ~IST THE OIR~CTORY OF OECTAPE .3 ON THE
~MSG MOUNT TAPE .J ON UNIT 1
*I..PllcDTA11/L
INO~ TRANSF~R FORTRAN SOURCl PROGRAM
IFROM DIS~ TO OeCTAPE '3 (UNIT 1)
$MSG wRITE tNAB~E ~N!T 1

~PT

*UTA1IFO~TS1.FTCD5KIFORTS1.FT
ICOMPll..~fORTRAN SOURCE

.i<

FOWT·

.DTA1IFORTS1.RL,FORTS1.~ScFORTS1.FT

ITHAT CUNCLUDES JOB #1
SJOB 05/8 BATCH P~OCESSING EXAMPLE *2
SMSG MOuNT TAPE .~ ON UNIT 1, WRITE ENABLED
.R PAL.S
.PTPI,DTA1:PROG.L5':>U5'""

C"A

t-h",+ ;+ n"f"'lto ...... OIl,.." ~n +ha ~" ............,..

.:>V '-I1U'-

~'-

Ul'p,"",u.:>

l.U'-' 1.V~J.ll.

#SYSTEM ERROR
Any occurrence of a Keyboard Monitor or Command Decoder
error normally causes BATCH to abort the current job and scan
the input file for the next $JOB command. If the /E option was
specified, BATCH treats Keyboard Monitor and Command Decoder errors as non-fatal and continues the BATCH run.
Table 2-3 lists the BATCH error messages, their meanings, and
the probable cause for the error.
Table 2- 3 BATCH Error Messages
BATCH E,!or Message

Meaning

#MONITOR OVERLAYED

The Command Decoder attempted to
call the BATCH monitor to accept
and transmit a file specification, but
found that a user program had overlayed part or all of the BATCH
monitor. Control returns to th'b monitor level, and BATCH executes the
next Keyboard Monitor command.

#BAD LINE. JOB ABORTED

The BATCH monitor detected a record in the input file that did not
have one of the characters dot, slash,
dollar sign or asterisk as the first
character of the record. The record
is ignored, and BATCH scans the
input file for the next $JOB record.

2-10

Tabl~.

2-3 BATCH Error Messages. (Cont.)

BATCH Error Message
#SPOOL TO FILE BTCHAI

#MANUAL HELP NEEDED

Meaning
Where the "A" may be any character
of the alphabet and the "1" ·may be
any decimal digit. This message indicates that BATCH has intercepted
a non-file-structured output file and
rerouted it to the spool device. This
is not, generally, an error condition.
Spool device file names are assigned
sequentially, beginning with file
BTCHAl. Standard default extensions may be assigned by some system programs.
BATCH is attempting to operate an 1/0. device, such as PTR or TTY,

that will' require operator intervention. If the jnitial dialogue indicated
that an operator is not present, this
message is suppressed, the current
job is aborted, and BATCH scans the
input file for the next $lOB command record. If an operator is present, he should have been notified
what action to take by a $MSG command.
#ILLEGAL INPUT

A file specification designated TTY
or PTR as an input device when the
initial dialogue indicated that an operator is not available. The current
job is aborted, and BATCH scans
the input file for the next SlOB command record.

#INPUT FAILURE

Either a hardware problem prevented
BATCH from reading the next record of the input file, or BATCH
read the last record of the input file
without encountering a $END command record. If a hardware problem
exists, correct the problem and type
any character at the Teletype to resume processing.

2-11

Table 2-3 BATCH Error Messages (Cont.)
BATCH Error Message

Meaning

#SYSERROR

A hardware problem prevented
BATCH from performing an 110
operation. Program execution halts,
and the system must be restarted
manually. This message often indicates that the system device is not
write enabled.

INSUFFICIENT CORE FOR
BATCH RUN

OS/8 BATCH requires 12K of core
to run. Control returns to the OS/8
Monitor.

BATCH.SY NOT FOUND ON
SYS:

A copy of BATCH.SY must exist on
the system device. Control returns to
the OS/8 Monitor.

WRONG OS/8 MONITOR

OS/8 BATCH requires an OS/8
Monitor no older than version 3.
BATCH cannot accept input from
the specified input device because its
handler is not permanently resident
(SYS: or co-resident with SYS:).
Control returns to the Command
Decoder.

DEY NOT IMPLEMENTED

ILLEGAL SPOOL DEVICE

The device specified as a spooling
output device must be file-structured.
Control returns to .the Command
Decoder.

Running BATCH From Punched Cards
The carriage return and ALT MODE characters are not defined
in the punched card character set. BATCH permits terminating
carriage return characters to be omitted from punched card input
files. Thus, when BATCH reads a punched card input file, it
appends a carriage return to' the content of each card, immediately
following the last character on the card that is not a space character. As with disk,DECtape or paper tape input files, BATCH
considers the dollar sign character to be equivalent to an ALT
MODE when it appears on a punched card' in any column except
the first.
2-12

When BATCH is run with a punched card input file, it is possible
for user input files to be embedded in the BATCH input file. User
input files should be. inserted into the' BATCH input file in such a
way that BATCH will never attempt to read a record of the user
file. That is, user files should follow a command record that transfers control to the program level, and the running program must.
exhaust all records of the user file before returning to the monitor
level.
,
Figure 2-2 illustrates how the second sample job of Figure 2-1
may be modified to run from a punc.hed card input file with an
embedded user file. In this example, PAL8 reads the punched card
user file and assembles the source program, then returns c.ontrol
to the monitor level. BATCH reagsthe next card of the input file,
which should contain the .R CREF command. If P AL8 has not
. read every reco¢ of the user input file, however, BATCH will encounter a record from this file rather than the Keyboard Monitor
command record. This results in the message:
#BAD LINE. JOB ABORTED
and causes BATCH to scan the input file until the next $JOB
record is read.
Restrictions Under OSj8 BATCH
OS/8 BATCH is a "friendly" system; that is, one which is
largely unprotected from user errors. The BATCH monitor resides
in locations 5000 to 7577 in the highest memory field available.
BATCH also uses the following locations in field 0 and the memory
field in which it resides:
LOCATION
07777
N7774-N7777

USED AS:
Batch processing flag.
Internal pointers.

Both the Keyboard Monitor and the Command Decoder check the
batch processing flag whenever they are entered from the program
level. Any user program that modifies location 07777 may cause
batch processing to be terminated prematurely before the next
record of the BATCH input file is read.
2-13

($END
( / END OF EXAMPLE #2
EMBEDDED
USER FilE

~
(*

f* DTA 1: PROG. LS

( . RUN DSK CREF

I---

PTP:, DTA1: PROG. LS CDR:

f--

(.R PAL8

f--

($MSG MOUNT TAPE #2 ON UNIT 1

f--

$JOB 05/8 BATCH PROCESSING EXAMPLE # 2

f----

1
f-f--

Figure 2-2 Punched Card Input File

When the Keyboard Monitor is entered from the program level
(effective JMP to 07600 or 07605) it checks the batch processing
flag and reads a new copy of the BATCH monitor into core if
batch processing is in progress. The Command Decoder, however,
does NOT perform this operation. Thus, the Command Decoder
must not be called unless the BATCH monitor is already in core.
This means that large user programs may be loaded over the
BATGHmonitor as long as they do not modify the last four locations in the highest memory field; however, once a user core load
has overwritten the BATCH monitor, execution must remain at
the program level until the Keyboard Monitor has been re-entered
and a new copy of the BATCH monitor is read into core. The
Command Decoder must not be called after a user program has
been loaded over the BATCH monitor.
In general, this restriction applies only to loader programs and
only when the loader calls the Command Decoder more than once
while building a large core load. Multiple calls to the Command
Decoder may be avoided when loading large programs during batch
processing if the core load is first built in a stand-alone environment
and then saved for subsequent execution under BATCH.
In conjunction with this, note that it is impossible to save the
core image of any program that overlays the BATCH monitor
under BATCH. After the load operation but before the save is
executed, the BATCH monitor will be read back into core, destroying part of the user program. Thus, the Keyboard Monitor SAVE
operation will cause part of the BATCH monitor to be saved instead of that part of the user program which originqUy overlayed
the BATCH monitor.

2-15

BATCH Demonstration Program
The following listing was produced. by running BATCH on a
12K PDP-8/E system containing a disk, DECtape and a line
printer. Only the Teletype output is reproduced here, and page
breaks were inserted arbitrarily to divide the listing into convenient
segments. The same BATCH input file has been processed twice,
with two different system configurations.
Notice that the first BATCH processing run begins by listing the
BATCH input file, and that the three
s'(~

BAler{

Once the ALT MODE ($ ) has been entered, the system will
print an uparrow and pause. Load the binary paper tape into the
high-speed reader, turn the reader on, and type any character at the
keyboard to continue.
Loading and Saving Programs
For Use Under BAT~H
A program that never uses more than 8K of core can never de- '
stroy the BATCH monitor. When this sort of program is loaded
from a DECtape system, considerable time is saved through use of
the /P option.
The /P option is a new ABSLDR option designed for use under
OS/8 BATCH. It causes the 400 b~t of the job status word (location 077 4~) to be set and prevents the Keyboard Monitor from
reading a fresh version of the BATCH monitor into core every time
the monitor level is re-entered from the program level.
For example, OS/8 PIP never uses more than 8K of core. Thus,
the best method of loading PIP wouid be:
.R ADSLDH

*PTR: (89P)=13000$

The /P option is not really necessary on a disk system, because
very little time is required to refresh the BATCH monitor from
disk. The /P option should not be used with any program. that
occupies or modifies core above field 1.
Transferring the System Software From Cassette to the System
Device
The following BATCH file can be used to transfer the OS/8
System Software from cassette to the system device.

2-22

SJOB JOB TO LOAD SYSTEM CASSETTE
.R MCPIP
*SVS CCL.SV0 22222222 2i111111
01'11""

1000~01'10

(110000000 00000000 00000000 00000000 00000000

0021'10 22222222 22222222 22222222 22222222 22222222 22222222 22222222 22222222
0.03!il0 22222222 22222222 22111111 11111111 11111111 11111111 11111111 11122221
00400 22222222 22222222 i?2?f12222 22222222 22222222 22222222 22222222 2222222<'
00SIi'0 22222222 22222222 22222222 2222222<' 22222222 22222222 22222222 22222222
00&00 11111111 11111111 11111111 11111111 11111111 11111111 11111111 11111111
00700 1111til1 11111111 11111111 11111111 11111111 11111111 \1101111 11111111
1111000
01100
111120111
1111300
014Q'0
015~11I

01&00
017QH1'
020~0
021~1'I

2-29

BITMAP Error Messages·
After each error message control returns to the Command Decoder and the user can try the procedure again, or reset the program (using the /R option) and try again using different inputs.

Meaning

Message
I/O ERROR
FILE'#n
BAD INPUT,
FILE #n

An I/O error occurred in input file number

A physical end of file has been reached before a logical end of file, or extraneous characters have been found in binary file n.
BAD CHECKSUM, File number n of the input file list had a
checksum error.
FILE #n
No binary file was found on the designated
NO INPUT
device.
Error occurred while writing on output deERROR ON
vice, i.e., output error on DECtape write.
OUTPUT
DEVICE
Cannot produce a bitmap of an image file.
NO/I

Assembly Instructions
Use PAL8 to make BITMAP.BN from BITMAP.PA as follows

• R PAL8
*OEV: BITMAP'
000111
041117
0200
0003
0002
0001
1377
1177
&20.3
5200
0003

10177

0002

5
&
7

9
10
11
12
13
14

15
1&

18
19
i/0
21
22
i!3

24
25
2&
27
is

00200
00201
00202
0111203
1111112111/1
111111205
111020&
00207
00210
0037&
1110377
00400
1110401
011141112
00403
0111404
00405
0040&
00407
0057&
00577
00177

30
31
32
33
34
35
3&

PALe-Vge
EXAMPl.E PROGIUM
ILLUSTRATI~G OETAILS OF
USING PALS AND CREF

·03/05/74 . PAGE 1

LISTI~G

~ORMAT

020111
START,

CLl Cl.L
TAO A
.
TAO B
TAO 12
TAO (3
DCA LINK
JMP I ADDRP2
A,
0011
ADDRP2. P2
*400
P2.

lINK,

TAO l.I~K
TAD (3
TAO (2
TAO (3
DCA B
CDF CIF 10
JMP Fl.Dl
0
B-l.INK

FIElD 1
TAO
FlD1.
TAO
CIF
JMP

(3
12
CDI' 0
START

ICURRENT PAGE SYMBOl.
10FF-PAGE SYMBOL, LI~K GENERATED
IPAGE ZERO LITERAL
ICURRENT PAGE LITERAL
JOFF-PAGE SYMBOl., LINK GENERATED
IUSER CREATED LINK
IINDIRECT ADDRESS

IPAGE
INOT.E
INOTE
ISAME

2 START
THAT nns IS A NEW LITERAL
THAT THIS IS SAME OLD l.ITERAL
AS CURRENT PAGE LITERAl.
ICURRE~T PAGE SYMBOl.
ICHANGE FIEl.DS
101'1' PAGE SYMBOL. LI~K GENERATED

IFIEl.D 1, DEFAULT TO PAGE 1 0200
INEW LITERAL, BECAUSE IN PAGE 0 OF NEW FIEl.D
ICHANGE FIEl.DS AGAIN
INO lINK GENERATED, SAME PAGE, OTHER fIELD

2-73

EXA~PLE

PROGQAM

02Qt7

AOORP2 0210

B
FLO!
LINK
Pi!
STAIH

0407
00200
1;:1407
0400
0200

ERRORS OiTECTED: "
LINKS GENERATED I 3

,
'DORPi!
8

FLO!
LINK
P2
START

.. 0fun
.. 00311>
.. 00577
:UI177
';:111377

121

13,
21
30*

25.

i!1I"

7
i!3

10
~!

.'.
,,~

33
, 1q

18
3!

2il

Restrictions

CREF 'has the follow'ing restrictions:
1. CREF can handle a maximum of 896 (decimal) symbols in one
major pass. (In 8K, PAL8 is limited to 897 symbols while
SABR is limited to fewer than 800 symbols.) If more than 896
symbols are found, an error message is generated.
2. If any symbol in the input file has more than 2044 (decimal)
references, an error message is generated.
3. If more than 8192 (decimal) source lines are input, sequence
numbers return to 4096, not O.
4. If the ID option is used in PAL8 (to generate a DDT compatible symbol table) and the output listing is put through
CREF, no symbol table listing will appear.
5. Use of semicolons-This is a restriction which, when not observed, could cause errors in the CREF table. It is recommended that the user follow these suggestions when preparing
source files in order to insure a proper CREF listing. Semicolons should not be used' on lines with pseudo-ops. In particular, a combination such as the following must not be used:
2-74

*30e0
TE ST

~ERROR~;

TAO

[42

In this case, CREF do~s not process the page zero literal
properly. A literal is generated which is derived from the expanded TEXT message. No error message is generated, but
the literal table entry is meaningless. As a general rule, semicolons should not be used as line terminators insidecondiFor example:
tional assembly brackets

«».

EXOR=fll

IFNZRO EXOR
\THI5 IS T~E NEXT LI~E PAST IfNZRO

The conditional code is not assembled; however, CREF does
not realize this and tries to process the bracketed instructions.
As a result of these semicolons, extra symbols may be processed and some valid references missed. However if the code
had been assembled CREF -would operate properly. There
are two ways around this:
a. Write straight line code:
EXOR=0
IF~JZRO

CLA

EXOR <

TAD 8

!-ILT ERROR
>

b. Use XLIST around conditional code, in the above example:
IFIERO EXOR
IFNZRO EXOR

HLT\E~ROR>

XLIST turns off the listing if the code does ,not assemble and
turns it back on after the conditional c,ode.
6. Formats-There are several output formats that can be used
in generating a PAL8 listing file:
/T Form feeds converted to carriage return/line feeds.
/H No heading or form feeds generated.
/D DDT compatible symbol table is generated.
For best results with CREF, none of these switches should be
2-75

used. This generates a heading and form feed in the output.
CREF automatically converts form feeds to carriage returnl
line feeds
. if output is to the, terminal.
7. PAL8 generated links do not cause a reference to a link to be
noted by CREF. Only literals specifically generated with ( and
[ are processed by CREF.
CREF Error Messages
CREF errors are non-recoverable errors, and control returns to
the Keyboard Monitor through location 07605 (no core saved).
Table 2-15 lists the error messages printed by CREF.
Table 2-15
Error Message

CREF ElTor Messages
Meaning

SYM OVERFLOW

More than 896 (decimal) symbols and literals
were encountered during a major pass.

ENTER FAILED

Entering an output file was unsuccessfulpossibly output was specified to a read only
device.

OUTDEV FULL

The output device is full (directory devices
only).

CLOSE FAILED

CLOSE on output file failed.

INPUT ERROR

A read from the input device failed.

DEV LPT BAD

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

2045 REFS

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

HANDLER FAIL

This is a fatal error on output, and can occur if
either the system device or the sel~cted output
device is WRITE-LOCKed.

2-76

DIRECT
DIRECT is an 05/8 program that produces listings of OS/8
device directories. The directories produced can be of several
varieties, depending upon the options specified -in the DIRECT
_. command line. The standard directory listing consists of the following columns: file name, file name extension, length (decimal) in
blocks written, and creation date.
DIRECT supports the wild card construction, using * in plact:
of the file name or extension or ? in place of a -character. See the
FOTP section of this chapter for a description of wild card
construction.
Calling and Using DIRECT
To call DIRECT from the system device, type:
··R DIRECT

in response to the dot printed by the Keyboard Monitor. DIRECT
may also be called via the CCL command DIR (see the CCL section in Chapter 1). The Command Decoder prints an asterisk at
the left margin, indicating that it is ready to accept a line of I/O
files and options. One output specification and one to five input
specifications can be entered in a DIRECT command line. The
I/O command line may be terminated with -a carriage return
(DIRECT retains control) or with an an ALTMODE ·(control
returns to the Keyboard Monitor).
The output _specification consists of a device upon which the
directory is to be produced, a file name, and a file name extension.'
All parts of the output specification are optional, as is the output
specification itself. A -file name and extension should be specified
if it is desired to save the directory for listing at a later time. If no
output device is specified, TTY is assumed. If a file name is given
without an extension, the extension .DI is assumed. The wild card
? and * are not permitted in DIRECT output file names or
extensions.
A DIRECT input specification consists of a device, an optional
file name, and· an optional extension. The wild car~ * and ? are
permitted in input specifications. If an input device is specified
with no file name or extension, *. * is assumed. DIRECT determines which files have the form ·specified and prints a directory
listing of just those files.
2-77

DIRECT OPTIONS
The following table lists the options that may be used in a
DIRECT I/O specification line. Examples of the use of these
options are shown following Table 2-16.
Table 2-16, DIRECT Options

Option

Meaning

Include the starting block numbers (octal) for each file in
the directory.
List only files with the current date, i.e., the date entered
with the most recent DATE command.
Include empty file spaces in the directory listing.
List a short form of the directory, omitting file lengths and
dates.
List additional information words in octal, other than the
first which is listed as the date.
List the standard form of the directory, including file name,
extension, length in blocks, and creation date. The I L
option is assumed if none is specified.
List only the empty spaces in the directory.
Use n columns in the directory listing. This option allows
the user to specify the number of directory entries per line
of output. The "n" must be in the range 0 to 7. The =n
option is useful when a wide column printer, e.g., 132
columns, is being used.
List only files with other than the current date.
List the remainder of the files after the first one found.
This option causes DIRECT to find the first file that
matches the specifications given and then list a directory
that includes the first matching file and all files that follow
it on the device. The I C and /0 options are still considered
when listing these remaining files. If I Rand / V are used
in the same command, only the first file of the form specified is listed.
Treat each input specification separately. The IU option
creates a separate directory listing for each input specification.
List files not of the form specified.
Print the version number of DIRECT.

IC
IE
IF
II
IL

1M
=n

10
IR

IV
IW

2-78

DIRECT EXAMPLES
The following are legal command strings to DIRECT and the
resultant DIRECT output. To facilitate understanding of the
DIRECT options, the same device (DTAO) is used for each of the
examples, and the current date is 21-JAN-74.
When DIRECT h~s completed an operation, control returns to
the Command Decoder for additional input.
Example 1:
This example shows a directory of all the files on DTAO, listed in
two columns on the terminal (TTY) .
• R OI RECT
*DTA0:=2
21-JAN-74
MTPALA. PA
MTPALS. PA
\o!NTSTC. BA
WNPPPAIPA
\·JNPAL B. PA
\ ....""'u .~rst
1 . 1 , mnd t"h"t ,,11 til""'" "he5.1
...
E>
"1'
0
.PA extensions be listed next. The short form of the directory is to
be listed on the line printer (LPT) in three columns.
.::).1vJ..1

u ...... J.

i.J.u. ... Ul..£..1.

* L P 1: < D T A 0: ~}N ?? ? ? • 8 A"

"""'13

.1.

Wi\) ? ? ? ? • P AI F' I

.L.l.

,Y..l."

u,..i. .... ,.,... ...

""' ..............

u= 3

WNT~TA.BA

WNTSTb.BA

WNTSTC.8A

WNTSTO.liA

wtJU

WNXY

• BA

"'",.&..1.

.C~

718 FREE Bl.OCKS
21-JAN-74

WNPALA.PA

WNPALB.PA

718 Fqt:E BLOCKS

Example 5:
This example demonstrates the use of the IV option to print
files not of the form specified and the use of the 10 option to
exclude files with the current date. All files except those beginning
with WN are to be printed in a single column on TTY.

21-JAN-74
18-JAN-74
18-JAN-74

MTPALA.PA
MTPALB. PA
I

718

F'REE BLOCKS

2-80

Example 6:
_
This example demonstrates the use of the /R option to list part
of the directory. DIRECT is to find the first file that begins with
WN and has a .PA extension; that file and all files that follow are
to be listed. The directory is listed in two columns on TTY.
*DTA0:WN????PA~R=2

21-JAN-74
WNPALA. PA
\·;NTSTD. BA
MTPALC. PA
~jNXY
• BA

1
1
1
1

19-JAN-74
2 1- J AN - 7 L!
21-JAN-74
21-JAN-74

WNPPPA.PA
WNPALP. PA
WNXX
• SA

19-JAN-74
21-J AN- 74
1 21-JAN-74

7 18 FREE BL OCK S

Direct Error Messages
The, following error messages may appear when running the DIRECT program.
Table 2-17

DIRECT Error Messages

Message

Meaning

BAD INPUT DIRECTORY

This message occurs when
the input device has -a bad
directory, e.g., the device
is not an OS/8 device, or
a DECtape has not been
zeroed.

DEVICE DOES NOT HAVE A
DIRECTORY

The input device is a nondirectory device, e.g., PTR.
DIRECT can only read
directories from file-structured devices.

EQUALS OPTION BAD

The =n option is not m
the range 0-7.

ERROR GLOSINGFILE

System error.

ERROR READING INPUT
DIRECTORY

An error occ\lrred while
reading the directory.

- 2-81

Table 2-17

DIRECT Error Messages (Cont.)

Message

Meaning

ERROR WRITING FILE

An error occurred while
writing the output file.

An asterisk (*) was included in the output file
specification or an illegal
* was included in the input file mime.

ILLEGAL ?

A question mark (1) was
included in the output file

NO ROOM FOR OUTPUT FILE

Self-explanatory; the output device does not have
sufficient space for the directory to be written.

THERE IS NO HOPE-THERE IS NO
1TY HANDLER IN YOUR SYSTEM!

A command was issued to
print a directory on the
terminal when no TTY
handler is present on the
OS/8 system. Use BUILD
to insert a TrY handler in
the system.

ILLEGAL

2-82

EPIC
Introduction
EPIC, the Edit, Punch and Compare utility program for OS/8, is
designed primarily to assist users by performing the following
functions:
1. Read and punch paper tape files and patches
2. Edit arbitrary files
'. 3. Compare files in any fOmiat
When EPIC is loaded, the command line determines which function is desired. Each of these functions is discussed as a sep_arate
topic in these next few pages. This section assumes an elementary
knowledge of OS/8.

Loading EPIC
To load the EPIC program type R EPIC in response to the
OS/8 monitor's dot C.). Specify the EPIC function desired by including one of the following numeric options in the file command .
line:
o paper tape
• R EPI C
1 edit
2 compare
*TRAN s. AS< 10$
punch the file TRANS stored
on SYS.
• R EPI C

fetch FILEA from DTAI for
editing

*DTAl:FILEA.SVi/l$

.R EPIC
*DSK: ABC. SV

0004 0110
3124 13121

,,7777

0004 0132
3126 1 3127

0004 B 0132 3126 7777

W
?

R,2 .
0, 10 •
1367

11364>

3324 •
E

*
Compare Capability
A third feature of EPIC is file compare (/2). Because EPIC
uses an absolute compare technique, there are no limitations in
the data format or the length of the file. The files to be .compared
must reside on the system device.
COMMAND FORMAT
Option 2 of EPIC requires only one command, .specified as
follows:
2-91

SYS:filel l' printed by the Command Decoder.
1. If FOTP does not find the file SMILE.PA on DTA3, the
message:
NO FILES or THE FORM SMILE.PA

is printed and no transfer is performed.
2. FOTP examines DTA5 to determine whether it already contains a file FROWN.PA. If FROWN.PA is already on DTA5,
FOTP deletes it before beginning the transfer. This process is
known as predeletion.
3. The IN option is used to specify that no predeletion is desired.
Thus the command:
DTA5:FROWN.PA
I'ORMAT< '
COMPI L ER TEST' >
RJ=3
RK=7

X=.5
RI 1= RK IRJ* e 2- RK* RK 1 < 3.
R= 10. 6
5=3.5
RI 5
RJ=2
RN=7
Z=R+ S*fd IRJ*RN 13
WRI TEe 1 .. 2> RII .. Z
FORMAT
END

$PEF$$
*tC
• R 1'4

*ATEST I~
US 2
ML
0017
.R TECO
*ERATEST.I'T$EWBTEST.I'T$Y$$
*SF10.$0LDI2$0LT$$
2
FORMAT< 1'10. 2 .. 1'12. 5>
*PEI'$$
*t C

* RJ> )

User calls TECO, specifies output file, and creates FORTRAN source
program.

. He then closes the file
and exits to the mon-

itor.
User calls FORTRAN
and executes test program.
FORTRAN lists two errors, so user calls
TECO and edits corrections into new output
file.
User finally calls FORTRAN and successfully
executes the text program.

• R 1'4

*8TEST.FT
C()1PI LER TEST
-8.04
31.~1667

The remainder of this chapter is devoted to a detailed description of the full TECO command set. It is assumed that the reader
is familiar with the elementary TECO commands presented earlier.
2-141

TECO Character Set
TECO accepts the full ASCII character set, which is presented
in Appendix A. Most terminals will not transmit and receive all of
the ASCII codes; however, characters that are not available on the
user's terminal may be inserted into the TECO text buffer by means
of special commands which will be presented later in this section.
TECO command strings may be entered by using upper case
characters, as indicated throughout this chapter, or by using the
corresponding lower case characters. A file which contains upper
and lower case text may be edited in the same manner as a file
which contains only upper case text. If such file is edited from a terminal that does not accept lower case characters, all characters will
be printed at the terminal as their upper case equivalents.
TECO considers certain ASCII characters to be special characters. Most· of the special characters are immediate action commands. Typing these characters in a command string causes TECO
to perform a specified function immediately, without waiting for
the double ALT MODE which terminates the command string. Immediate action commands may be entered at any point in a command string--even in the middle of a command or text argument.
For this reason, the special ·characters should not be used in text
arguments, ex(.;;:pt where specifically indicated throughout this
chapter.
Table 2-28 lists the special characters, their functions and the restrictions associated with each character.
Table 2-28

Restrictions on Special Characters

Character

Restriction

ALT MODE

The ALT MODE character is a command terminator. It may not be used in the argument of any
command except where noted specifically throughout this chapter. TECO echoes a dollar sign when
an ALT MODE is received. ALT MODE "may be
labelled ESCAPE on some terminals.

RUB OUT

Typing a RUBOUT character causes the last character typed to be deleted. Typing consecutive RUBOUTs deletes one character for each RUBOUT
typed, beginning with the last character typed.
TECO echoes the deleted character whenever a
RUB OUT is typed.

2-142

Table 2-28

Restrictions on Special Characters (Cont.)

Character

Restriction

CTRL/V

CTRLI V causes the current line to be deleted, and
eches a tV and. a carriage return I line feed.

CTRL/C

CTRLI C causes an immediate exit from, TECO to
the OS/8 Keyboard Monitor. If an output file is.
open when the CTRLI C command is executed, the
contents of the file will be lost.

CTRL/P

CTRL/P causes an immediate branch to the starting address of TECO.

CTRL/G

Typing two .consecutive C:fRLI G characters causes
.all commands which. have been entered but not
executed to be erased. (If the terminal has a bell, it
will ring.) This command is used to erase an· entire
command string.

CTRL/S

If CONTROLI S is typed as the first character of a

new command string, the entire previous command
string, even if it was in error, is saved as a text
string in Q-Register Z. The previous contents, if
any, of Q-Register Z are destroyed.

The CTRLjZ character is used as an end-of-file terminator.
Inserting this character into a file may cause the file to be terminated pre~aturely th~ next time it is read as an input file.
TEeO also attaches special significance to the carriage return,
line feed, space and null characters. A,line feed is appended to
every carriage return entered into the text buffer. Thus, it is necessary to type a carriage return and then a RUB OUT in order to enter a carriage return character which is not followed by a line feed.
Carriage return, line feed and space characters are ignored between commands in a command string; they may be inserted for
clarity or convenience whenever necessary. The null character
(CTRL-shift-P) is ignored by all TECO input commands.
Control cllaracters which are not special characters (i.e. immediate action commands) maY,pe included in the text argument of any
TECO command. When used in this manner, the control character
must 'be produced by striking the CONTROL key and a character .
key simultaneously. TECO will eGho an uparrow followed by the
2-143

character which was typed whenever most control characters are
entered; however, some control characters do not echo, while
others, such as CTRLjL (form feed) or CTRL/G (bell) echo as
the function they perform.
Many control characters are also TECO commands. When a
control character is entered as a command, it may be produced by
striking the CONTROL key and the character key simultanteously
or else by typing an uparrow followed by the desired character.
This is advantageous because all control characters echo normally
when
typed in the uparrow/character format.
,

File Specification Commands
An input file must be specified whenever TECP is requested to
accept text from any source except the keyboard, An output file
must be specified whenever a permanent change is made to the input
file. Input and output files are selected by means of file specification commands, which always include the OS/8 designation of the
input or output device. If the device is a directory device, the file
specification command also includes a file name and extension. If a
file extension is not explicitly defined, the null extension is lssumed.
If a file name is specified but no device is explicitly defined, the OS/8
default device is assumed.
Almost every editing job begins with at least one file specification
command. Additional file specification commands may be executed
during an editing job whenever required; however, TECO will only
keep one input file and one output file active at a time, and the
same file may not be used for both input and output. When an output file is opened on a directory device, it is essential that the file
be closed by a TECO file closing command before any other output
file is opened. If this is not done, the content of the file will be lost.
Note that a bulk storage (directory device) input file must be a
file that presently exists on the system. A bulk storage f)utput file
may be a file which presently exists, in which case TECO will create a second file with same name and extension, then delete the
original file when the file is closed. It may also be a nonexistent file,
in which case TECO will create the specified file. Table 2-29 lists
the full file specification command set.

2-144

Table 2-29

File Specification Commands

Command

Function

ERdev:filnam.ex$

Opens a file for input where "dev:filnam.ex" is
the OS/8 file designation and "$" signifies an
ALTMODE.

EWdev: filnam.ex$

Opens a file for output where "dev: filnam.ex" is
the OS/8 file designation and "$" signifies an
ALTMODE.

EBdev:filnam.ex$

The EB command may be used for directory device files only. It opens file "dev:filnam.ex" for
input and file dev:filnam.BK for output then,
upon receiving any file closing command, switches
the file names before closing the files. Thus,
dev:filnam.ex is always the current, updated file
and "dev:filnam.BK" is the previous version of
the file, which may be retained as a backup file.

Closes the current output file.

Moves the remainder of the current input file to
the current output file, then closes the output file.

Performs the same function as the EC com. mand, but then transfers control to the OS/8
CCL Processor to re-execute the most recently
typed CCL-command of the group: PAL, COMPILE, EXECUTE, and LOAD. This allows the
user to go from TECO to a compiler and then
to execution of a program without returning to
the OS/8 Keyboard Monitor.

. EX

Performs the same function as the EC command,
but then returns control to the OS! 8 monitor.

CTRLI G

Typing CTRLI G causes an exit to the OS/8
monitor as soon as all previous commands have
been executed. It is equivalent to the uparrow
form- of CTRLI C.

Many editing jobs are most conveniently accomplished by using
the EB command to open the designated input file and backup file,
then terminating the job with either an EC command, which returns control to TECO, or an EX command, which returns control
to the OSj8 monitor. Note that once a directory device output file
has been opened with an EW or EB command, it must be closed
2-145

",ith an EF, Ee, EG or EX command or else the content of the
file will be lost.

Page Manipulation Commands
The following commands permit whole pages of text to be read
into the text buffer from an input file or written from the buffer
onto an output file.
Table 2-30

Page Manipulation Commands

Command

Function

Appends the next page of the input file to the current content of the text buffer, thus combining the two pages of
text on a single page with no intervening form feed character.

Clears the text buffer and then reads the next page of the
input file into the buffer.

Writes the content of the buffer onto the output file and
appends a form feed character. The buffer is not cleared
and the pointer position remains unchanged.

nPW

Executes the PW command n times, where n must be an
integer in the range O~n~4095.

m,nPW

Writes the content of the buffer from the m+lth character
through and including the nth character onto the output
file. M and n must be integers in the range O~n~4095 and
m should be less than n. A form feed is not appended to
this output, nor is the buffer cleared. The pointer position
remains unchanged.

HPW

Equivalent to the PW command except that a form feed is
not appended to the output.

Writes the content of the buffer onto the output file, appending a form feed, then clears the buffer and reads the
next page of the input file into the buffer.

Executes the P command n times, where n must be an
integer in the range O~n~4095.

m,nP

Equivalent to m,nPW.

Equivalent to HPW.

All of the input commands listed in Table 2-30 assume that the
input file is organized into pages of less than 3800 characters each.
If any page of the input file contains more than 3800 characters,
the input commands will continue reading characters into the buffer

2-146

until either the first line feed following the 3800th character is
read or the 4000th character is read, whichever comes first. Special
techniques for handling files with pages in excess of 4000 characters in length will be developed later in this section.

Buffer Pointer Manipulation Commands
Table 2-31 summarizes the complete buffer pointer manipulation
command set. These commands may be used to move the pointer
to a position between any two characters in the buffer, but they will
not move the pointer across either buffer boundary. If any R or C.
command attempts to move the pointed backward past the beginning of the buffer or forward past the end of the buffer, the command is ignored and an error message is printed. If any L command
attempts to exceed the buffer boundaries in this manner; the pointer
is positioned at the boundary which would have been exceeded. No
error message is printed.
Table 2-31

Command

Buffer Pointer Manipulation Commands
,.,/-

Function

Moves the pointer to a position immediately preceding the
first character in the buffer.

Moves the pointer to a position immediately following the
nth character in the buffer. N must be an integer in the
range O~n~4095.

Moves the pointer to a position immediately following the
last character in the buffer.

Advances the pointer forward across one character.

Executes the C command n times, where n must be an
integer in the range -2048~n~2047. If n is positive, the
pointer is moved forward across n characters. If n is negative, the pointer is moved backward across n characters.
If n is zero, t1!e pointer position is not changed.

-C

Equivalent to -IC.

Moves the pointer backward across one character .

.nR

Executes the R command n times, where n is an integ~ in
the range -2048~n~2047. If n is positive, the pointer is
moved backward across n characters. If n is negative, the
pointer is moved forward across n characters. If n is zero,
the pointer position is not changed.
2-147

Table 2-31

Buffer Pointer Manipulation Commands (Cont.)

Command
- R
L
nL

-L

Function
Equivalent to -IR.
Advances the pointer forward across the next line feed and
positions it at the. beginning of the next line.
Executes the L command n times, where n is an integer in
the range -2048~n~2047. A positive value of n advances
the pointer to the beginning of the· nth line following its
current position. A negative value of n moves the pointer
backwards to the beginning of the nth line preceding its
present position. If n is zero, the pointer is -moved to the
beginning of the line on which it is currently positioned.
Equivalent to -lL.

Text Type-Out Commands
Table 2-32 summarizes the commands which may be used to type
out part or all of the content of the buffer .for examination. These
commands do not move the buffer pointer.
Table 2-32

Command
T

-T
m,nT

.,.+nT
.-n,.T

Text Type-Out Commands

Function
~ypes

out the content of the buffer from the current positiqn of the buffer pointer through and including the next
line feed character.
Executes the T command n times, where n is an integer
in the range -2048~n~2047. If n is positive, the n lines
following the current position of the pointer are typed. If
n is negative, the n lines preceding the pointer are typed.
If n is zero, the content of the buffer from the beginning
of the line on which the pointer is located up to the pointer
is typed.
Equivalent to -IT,
Types out the content of the buffer from the m+lth character through and including the nth character in the buffer.
M and n must be integers in the range O~n~4095, and m
should be less than n .
Types out the n characters immediately following the buffer pointer. N should be greater than zero.
Types the n characters immediately preceding the buffer
pointer. N should be greater than zero (Le. -n·should be
less than zero).
Types out the entire content of the buffer.

2-148

•

Users may stop the execution of any T command by typing
CTRLjO at the keyboard. Typing CTRLjO terminates execution
of the current T command, causes all subsequent T commands to be
ignored while the rest of the current command string is executed.
When used in this manner, the CTRLjO must be entered while
TECO is actually in the process of typing out text at the terminal.
Deletion Commands
Table 2-33 summarizes the text deletion commands, which per-.
mit deletion of single characters, groups of adjacent characters,
single lines ·or groups of adjacent lines .

•

Table 2-33' Text Deletion Commands
Command

Function

Delete the first character following the current position of
the buffer pointer.

Execute the D command n times, where n is an integer in
the range -2048~n~2047. If n is positive, the n characters following the current pointer position are deleted. If'
n is negative, the n characters preceding the current pointer
position are deleted. If n is zero, the command is ignored.

-D

Equivalent to -ID.

Deletes the content of the buffer from the current position
of the buffer pointer through and including the next line
feed character.

Executes the K command n times, where n is an integer in
the range -2048~n~2047. If n is positive, the n lines
following the current pointer position are deleted. If n is
negative, the n lines preceding the current pointer positiolT
are deleted. If n is zero, the content of the buffer from the
beginning of the line on which the pointer is located up to
the pointer is deleted.

-K

Equivalent to -IK.

m,nK

Deletes the content of the buffer from the m+1th character
through and including the nth character. M and n must be
integers in the range O~n~4095, and m should be less
than n.
.

Deletes the entire contents of the buffer.

2-149

Insertion Commands
Table 2-34 lists the full text insertion command set. All text insertion commands cause the string of characters specified in the
command to be inserted into the text buffer at the current position
of the buffer pointer. Following execution of an insertion command,
the pointer will be positioned immediately after the last character
of the insertion.
The length of an insertion command is limited primarily by the
amount of core available for command string storage. During normal editing jobs, it is most convenient to limit insertions to about
10 or 15 lines each. If a very long insertion command begins to exceed the TECO command storage capacity, TECd will ring the
terminal bell once when ten characters of storage remain and once
after each additional character that is entered. "''hen this occurs,
the command string should be terminated immediately. Attempting
to enter more than 10 additional characters into the current command string causes a fatal error.
With the exception of the nl$ command, insertion command arguments may contain any ASCII characters that are not special
characters. The nl$ command will insert any character into the
buffer, including the special characters.
Table 2-34

Command

Text Insertion Commands

Function

Itext$

Where "text" is a string of ASCII characters terminated
by an ALT MODE, which echoes as a dollar sign. The
specified text string is entered into the buffer at the current
position of the pointer, with the pointer positioned immediately after the last character of the insertion.

hl$

Where n is any ASCII code. This form of the I command
inserts the single character whose ASCII code is n into the
buffer at the current position of the buffer pointer. It may
be used to insert characters that are not available on the
user's terminal or special characters such as RUBOUT
which may not be inserted with the standard I command.

text$ Where is a tabulation, produced by pressing the
CONTROL key and the I, key simultaneously. The TAB
character echoes as from one to eight spaces on most
terminals. This command is equivalent to the I command
except that the tabulation is also inserted into the buffer
immediately preceding the specified text string.

2-150

Table 2..34 Text Insertion Commai)(ls (Cont.)
Command

Function

@I1text!

Equivalent to the I command except that the text to be
inserted may contain ALT MODE characters as long as it
does not contain two consecutive ALT MODEs. A delimiting character (shown as a slash here) must precede and
follow the text to be inserted. This delimiter may be any
character which does not appear in the insertion except for
the special characters.

Search Commands
In many cases, the easiest way to position the buffer pointer is
by means of a character string search. The search commands cause
TEeO to scan through text until a specified string of characters,.
from 1 to 31 characters In length, is found and then position the
buffer pointer, at the end of the string. A character string search always begins at the current position of the pointer and proceeds in
the forward direction.
Table 2-35

Search Commands
Function

Command
Stext$

Where "text" is a string of 1 to 31 characters terminated by an ALT MODE. This command
searches the text buffer for the next occurrence of
the specified character string following the current
position of the buffer pointer. If it is not found, the
pointer is positioned immedately before the first
character in the buffer and an error message is
printed.

FStextl $text2$

The FS command is used to search for a character
string within the current editing buffer (function of
the S command) and replace it with another string.
If the string to be replaced is not found after the
current position of the buffer pointer and before the
end of the buffer, the search fails and no replacement is made. Textl is the string to be deleted and
text2 is the string to be inserted in its place. If
text2 is omitted, textl is deleted without any string
replacing it. However, even when text2 is omitted,
its terminating ALT MODE must be present.

2-151

Table 2-35

Search Commands (Cont.)

Command

Function

FNtextl$text2$

The FN command is used to search for a character
string in a page of the input file which may not yet
have been read into the buffer (function of the N
command) and replace it with another string. If
the search fails no replacement occurs. Textl is the
string to be deleted and text2 is the string to be inserted in its place. If text2 is omitted, textl is deleted without any string replacing it. However, even
when text2 is omitted, its terminating ALT MODE
must be present.

~text$

The backarrow command is identical to the N command except that the search is continued across
page boundaries by executing effective Y commands
instead of p or HPY commands, so that no output
is generated.·

tRtextl $text2$

The ltR command is identical to theFS command,
and is included only for compatibility with older
versions of OS/8 TECO.

If a search command is entered without a text a;gument, TECO
. will execute the search command as though it had been entered with
the same character string argument as the last" search command executed. For example, suppose the command "STHE END$" results
in an error message, indicating that character string "THE END"
was not found on the current page. Entering the command "N$"
causes TECO to execute an N search for the same character string.
Although the text argument may be om~tted, the command terminator (ALT MODE, in this case) must always be entered.
Any of the TECO search_ commands may be preceded by the
number n, in which case TECO will search for the nth occurrence
of the specified text string.
Any of the search commands listed above may be preceded by a
colon (:). The colon is a search command modifier which suppresses error message generation and causes the next sequential
command to be executed with an argument of zero, if the search
fails. If the search succeeds, the next sequential command is executed with an argument of -1. If the next sequential command belongs to the class of commands which require a positive argument
(0
where "command string" is the sequence of commands to be
iterated and n is the number of interations. N must be, a positive
integar. If n is not supplied, a value of 4096 is assumed.
If a search command whkh is not preceded by a colon modifier
is entered into a command loop and the search fails, the command
loop is exited immediately and the command following the right
angle brackets of the loop is the next command to be executed.
No error message is printed.
Q-Registers

TECO provides 36 data storage registers, called Q-registers,
which may be used to store single integers and/or ASCII character
strings. Each Q-register is divided into two storage areas. In the
number storage area, each Q-register can store one integer in the
range -2048::::;n::::;2047. In the text storage area, each Q-register
can store an ASCII character .string of up to 2000 characters which
may be either text or a TECO command string. Each Q-register
has a single character name which is one of the upper case letters A
to Z or one of the digits 0 to 9. In this manual, a Q-register name
is indicated by a lower case "q", which stands for anyone of the
36 Q-registers.
Table 2-37 lists the commands which permit characters to be
loaded into the Q-registers.
2-155

Table 2-37

Q-Register Loading Commands

Conunand
tUqstring$

@tU/stringi

nUq

n%q$

n% $

nXq

m,nXq

Function
Where tU is an uparrow-U character, "q" is the name
of a user-specified Q-register, "string" is a string
of ASCII characters, and "$" signifies an ALT
MODE. This comniand inserts character string
"string" into the text storage area of Q-register "q".
(Do not confuse uparrow-U with CTRL/U; CTRL/U
is an editing conunand. r
Equivalent to the tU command except that the character string to be inserted into Q-register q may contain ALT MODE characters as long as it does not
contain two consecutive ALT MODE characters.
The insertion must be delimited before ai"ld after by
any character (a slash is shown here) which does
not appear in the insertion.
Load n into the number storage area of Q-register q, where n must be an integer in the range
-2049::;;;n::;;;2048.
Add n to the contents of the number storage area of
Q-register q, where n should ,be an integer that will
not cause overflow. If n is not present, it is assumed
to be equal to 2.
Equivalent to n % q$ except that the resulting value
contained in Q-register q is used as a numeric argument for the next command. If the next command
does not require a numeric argument, this value is
discarded.
Copy the contents of the buffer from the current
position of the pointer through and including the
next line feed character into the text storage area
of Q-register q.
Execute the Xq command n times, where n is an
integer in the range -2048::;;;n::;;;2047. If n is positive,
the n lines following the current pointer position are
copied into the text storage area of Q-register q. If
is negative, the n lines preceding the pointer are
copied. If n is zero, the contents of the buffer from
the beginning of the line on which the pointer is
located up to the pointer is copied.
, Copy the contents of the buffer from the m+1th
character through and including the nth character
into the text storage area of Q-register q. M and n
must be positive, and m should be less than n.

2-156

Table 2..:38 lists the commands which permit characters to be
retrieved from the Q-registers.
Table 2-38, Q-RegisterExecution Commands
Command

Function

Copy the contents of the text storage area of Q-register
q into the buffer at the current position of the buffer
pointer, leaving the pointer positioned after- the last character copied.

-Use the integer stored in the number storage area of
_ Q-register q as the argument of the next command. The
characters "Qq" may be considered as equivalent to "the
value contained in the number storage area of Q-register
q", where "q" is any Q-register name.

Execute the contents of the text storage area of Q-register
q as a_ command string.

-nMq

Execute the contents of the text storage area of Q-register
q as a command string and use n as a numeric argument
for the first command in this string.
--

Branching Commands
TECO commands may be combined in sophisticated command
strings which are capable of solving even the most complex editing
problems. In fact, TECO might be considered a programming
langUage which accepts an input file as data and processes this
input to produce aD. output file. As with most programming languages, TECO provides an unconditional branch command and a
set of conditional execution commands.
To provide for branching within a command string, there must
be some means of naming locations inside -the string. TECO permits location tags which have the form:

! tag!
to be placed between any two commands in a command string. The
name "tag" will be associated with -this location when the command string is executed. Tags may contain any number of ASCII
characters and any character except for special characters and,
exclamation points. Since tags are ignored by TECO except when
a branch command references the tagged location, they may also
be used as comments within complicated command strings.
2-157

The unconditional branch command is the 0 command which
has the form:
Otag$
where "tag" is a named location elsewhere within the command
string and "$" signifies an ALT MODE. When an 0 command is
executed, the next command to be executed will be the command
following the tag referenced by the 0 command, and command execution continues normally from this point.
.
If an 0 command is stored in a Q-register as part of a command
string which is. to be executed by an M command, the tag referenced by the 0 command must also reside in the same Q-register.
An important restriction on the 0 command prevents any 0
command which is inside a command loop from branching to a
tagged location preceding the command loop. However, it is always
possible to branch out of a command loop to a location which
follows the command loop.

Conditional Execution Commands
All conditional execution commands are of the form:
n"Gcom~and

string'

where "n" is a numeric argument on which the decision is based,
"G" may be any of the conditional executional commands listed in
Table 2-39, and "command string" is the command string which
will be executed if the condition is satisfied. If the condition on n is
not satisfied, the command string will. not be executed. Note that
the numeric argument is separated from the conditional execution
command by a double quote (") and the command string is
terminated with an apostrophe (').
Conditional execution commands may be nested in the same
manner as iteration commands. That is, the command string which
is to be executed if the condition on n is met may contain conditional execution commands, which may, in turn, contain further
conditional execution commands.
Table 2-39 lists .the conditional execution commands. Each
conditional execution command must be followed by a command
string (not shown in Table 2-39) which will be executed only if
the condition is satisfied. This command string must be terminated
by an apostrophe. If the condition is not satisfied, the first command following the apostrophe will be the next command executed.
2-158

Table 2-39

Command

Conditional Execution Command

Function

n-m"A

Execute the following command string (terminated by an
apostrophe) if n is greater than or equal to m. Otherwise
skip the following command string. Nand m should be
integers in the range O~n~4095.

n-m"B

Execute the following command string (terminated by an
apostrophe)- if n is less than m. Otherwise skip the following command string. Nand m should be integers -in
the range O~n~4095.

n"G

Execute the following command string (terminated by an
apostrophe) if n is greater than zero. Otherwise skip the
following command string. N must be an integer in the
range -2048~n~2047.

n"L

Execute the following command string (terminated by an
apostrophe) if n is less than zero. Otherwise skip the following command string.

n"E

Execute the following command string (terminated by an
apostrophe) if n is equal to zero. Otherwise skip the following command string.

n"C

Execute the following command string (terminated by an
apostrophe) if n is the decimal ASCII code of any character which is one of the upper or lower case letters A to
Z or one of the digits 0 to 9. Otherwise skip the following
command string.

In general, integers "n" and "m" will be variables (e.g. the content of a Q-register) whose values are computed during execution
of the command string. -,
There is one further conditional execution command which is
not related to the commands listed in Table 2-39. The n; command,
where n is any integer, may be inserted between any two commands
in an iterated command loop. It has the general form:
mstring3
where "m" is the iteration count, "stri~gl", "string2", and "string3"
are command strings and "n;" is the conditional exit command.
When the n; command is executed, it will cause TECO to exit the
command loop so that "string3" will be executed next if n is in
the range O:
preceded by an argument such as,Qq (tHe value. of the numeric
part of Q-register q), or-the argument may be omitted if the semicolon command is preceded bya command. that. generates an
argument, such as any colon.;;.modified· search command',
Note that all unmodified search commands entered within command loops are executed as though they were preceded by-. a COIOIl
and followed by a semicolon. :If the search- command is preceded.
by a colon modifier, however, it will be executed as it stands.
The conditional execution commands will accept user-supplied'
numeric arguments (n and m Table 2-39) of the same form as ,.
most other TECO commands. This is generally a trivial case, however, because the user will know in advance whether the condition
is satisfied, and need not use the conditional execution command.
The following section introduces run'-time numeric quantities' com- .
puted by TECO which may also be used as numeric arguments.

Numeric Arguments
Almost all TECO commands may be preceded by a numeric
argument which generally indicates the number of iterations, or
how many times the command should be executed. Some numeric
arguments must be positive, while others may be negative· or zero.
In any case, every numeric argument is stored as a single, 12-:bit
word ..
This leads to an impurtant restric;tion on the maximum size of
any' numeric argument. Commands which require positive arguments must have an argument in the range 0 !

usn

! !J
FY! ~- 40"G !
! 60- QN- QS"G QS< S $1 SSt N $->!
! 0L QS%N $ QS%S$ OJ
FY $' !
!60-~"G. 60-QN"!
!L 0IS'$$!

usn

Figure 2-5

TECO Macro for Example 3

• R TEeo
*ERDTAl:MACRO.TES Y HXI HKS$
*ERDT,lI.I:TEXT.AS$ Y MISS

*
Figure 2-6

Loading and Executing a TECO Macro

Example 4: Managing a Macro Library
A TECO macro library is most conveniently stored with TECO
on the OS/8 system device. Macros are usually short enough to
require a small amount of storage space, however it is impractical
to store each macro in a separate named file, because a large macro
library stored in this manner would make the device directly unmanageably large and might even exhaust the available directory
entries.
Figure 2-7 illustrates a macro that packs the user's TECO macro
library (or any other set of short ASCII files) into a single file
requiring oIlly one directory entry. This macro could be stored on
the system device in a file named PACK.TE (the extension indicates
a TECO command string file). The user must also create a sepr ate file containing the name of each file to be packed. This file must
'
be formatted as follows:
2-175

filel!ex
file2.ex
file3~ex

filen.ex

after

where each file specification
the first is preceded and followed
by a carriage return/line feed combination. Assume that· such a,.,
file is created and stored as INDEX.AS on the ,system device. If.
macro PACK. TE is also on the system device, the following commands will pack all files listed in INDEX.AS into file MACLIB.PK

Y to HX0 HK 0Ut 0U2
02"E 08S' EF·
!B! HK 02\ I FILES PACKED
$ HT HK

Figure 2-7

File Packing Macro

.R TEeo
*ERSYS:PACK.TESY HXP HK$$
* ERSY S: INDEX. ASSEWSY S: MACLI b. PK $MP$$
N FILES PACKED

*
Figure 2-8

Loading and Running the File Packing Macro

0U2 Q2"E 08$' EF
!S! Q2\ I F"lLES UNPACKED
$ HT HK

Figure 2-9

Unpacking Macro

2-176

·' R TECO
*ERSYS: UNPACK.TE5:Y HXU HK$$
*ERINCEX.AS$MP$$
,~ FILES UNPACKED

*
Figure 2-10

Loading and Running the Unpacking Macro

The packing macro prints a message, as shown, where "n" is
the number of files that were packed. The files to be packed will be
taken from the system device. Files PACK. TE, INDEX.AS and
MACLIB.PK may reside on any file-structured device if the file
designations in the above command summary are changed accordingly.
Once the packing macro has packed all the files into
MACLIB.PK, the individual files may be deleted. Alternatively,
macros could be saved in individual files on, say, DTAI and the
packing macro could be used to pack the files into one system
device file simply by replacing the imbedded "ERDSK:" command
in the macro body with "ERDTAl:". If the library.index is also
saved on the system device; an unpacking macro may be used to
create an unpacked copy of the macro library whenever required,
and the original library tape may be saved as a backup.
Figure 2-9 illustrates a macro that unpacks the output file produced by the packing macro. This macro accepts a packed ASCII
file (such as MACLIB.PK), then unpacks the file and restores each
entry as a discrete file with the appropriate specification.
Assume that a user desires to access a macro or other ASCII
file that was packed into file MACLIB.PK, as shown in the previous example. If file UNPACK.TE contains the unpacking macro,
the following commands will unpack the entries and restore them
as individual, named files.
The unpacking macro prints a message, as shown, where "n" is
the number of files that were unpacked. Once the files are unpacked, they will be directed to the system disk. Alternately, the
unpacked files could be directed to, say, DECtape unit 5 by modifying the "EWDSK:" command in the macro body to read
"EWDTA5:".
Using TECO to Retrieve Lost Files
Inevitably, through user error, hardware error, or operating
. system error, valuable files maybe deleted or directories destroyed.

2-177

A two-word patch to TECO creates a program known as SUPER
TECO which may be a considerable aid in these situations. The
patch is:
• GET SY S TEGO
.ODT

203417 420 7610
211717450 7410

tG
• SAVE SY S STEGO

To use STECO, mount the device on which you want to retrieve
the file, then type:
.R STEGe

* ERDEV: $$
*text$
Insert tabulation, then text. is a TAB (control-I) character.
nI
Insert character whose ASCII code is n.
@I!text/
Insert text delimited by arbitrary character shown
as a slash.
n"
Insert the ASCII code for integer n.
OUTPUT AND EXIT
PW
Write current page and append form feed.
P
Write current page, append form feed, clear buffer, and read next page.
Write m+ 1til through n tb . characters without apm,nP
pending a form feed.
EF
Close the current output file.
Close the current output file and exit to the OS/8
tG
monitor.
Immediate exit to the OS/8 monitor.
tC
Exit to the monitor and do a START 200.
tP
EX
Write the rest of the input file on the output file
and exit to the monitor. ,
Write the remainder of the input file on the output
Ee
file and close the file.

2-180

Table 2-44' TECO Command Summary (Cont.)
, Function

Command

SEARCH COMMANDS
nStext$
Begin at the pointer and search for the nth occurrence of the text delimited by the Sand t1:le ALT
MODE on the current page.
nNtext$
Equivalent to nStext$ except that the search is
continued across page boundaries.
n ~text$
Equivalent to nNtext$ except that no output is
generated.
nFNtestl $text2$ .Do nNtext1$ and then replace textl with text2.
:nStext$
Equivalent to nStext$ except, that it returns a
value of-I. If the search succeeds, or 0, if the
search fails. The colon may be used with Nand
~ searches.
n@S/text/$
Equivalent to nStext$ e!,cept that the text is delimited by the arbitrary character following the S,
instead of ALT MODE.
tX
Accept any character in this position.
tS
Accept any separator in this position. Save last
typed command.
tN
Accept any character except the following character in this position.
tQ
Interpret the next character literally, rather than
as a command.
ITERATION AND FLOW CONTROL
n< >
Perform enclosed commands n times.
n;
If n is positive, jump out of the current iteration
field.
!tag!
Define position named "tag" at this location.
Jump to the position defined by "tag."
Otag$
n"E
If n=O, execute the following command string.
n"N
If n1=0' execute the following cOrrimand string.
n"L
If n is less than zero, execute the following command string.
n"G
If n is greater than zero, execute the following
command string.
If n is the ASCII code !Oi' an alphanumeric character, execute the following commands.
n-ni"A
If n is greater than or equal to m, execute the
following commands.
n-m"B
If n is less than m, execute the following commands.
Q-REGISTER COMMANDS
nUq
Store n in Q-register q..
Qq
Equivalent to the value stored in Q-register q.

2-181

Table 2-44

TECO Command Summary (Cont.)

Command
n%I
tUqtext$

nXq
m,nXq
Gq
Mq

Function
Add n to the content of Q-register q and return
this value.
Insert text into Q-register q.
Load the n following lines into Q-register q.
Load the m+l th character through the nth character into Q-register q.
Insert the content of Q-register q into the buffer.
Execute the content of Q-register q as a command
string.

NUMERIC VALUES
nA
ASCII value of nth character following pointer.
tE
Form feed flag.
tF
Console data switches.
tH
Always equals zero.
ttX
Equivalent to the ASCII code for character "X."
tZ
Command and Q-register storage words in use.
to
Set octal radix.
tD
Set decimal radix.
"
Equivalent to the value of the digit string following the pointer.
Equivalent to the ASCII code for the next chartT
acter typed.
Equivalent to the number of the version of TECO
tV
being run.
.
PROGRAMMING AIDS
After an error message, identifies erroneous char?
acter.
Except after an error message, toggles in and out
?
of trace mode.
..
Erases current command string.
tGtG

RuoniogTECO 00 The PDP·12
When TECO is run on a PDP-12, part of the content of the text
buffer is displayed on the console scope. Initially, TECO displays
the three lines immediately preceding and following the buffer
pointer. An uparrow character (t) is displayed below the current
position of the pointer.
The ntW command, where n is a small positive integer and tW
is a control-W or uparrow/W character, causes TECO to display
the n lines preceding and following the current position of the
pointer on the scope. If a value of n greater than 7 is specified, the
2-182

display will wrap around the. scope and produce flicker on it. N
is assigned an initial value of 3.
The tW command (CTRLjW with no numeric argument) causes
TECa to execute one scope display cycle. This command may be
entered into long command strings for the purpose of displaying
part of the buffer at a given point in the command string.
When a tF character is entered in a numeric expression on the
PDP-12, TECO considers the tF to be equivalent to the current
value of the right~hand switch register.
Assembly Instmctions

The source tape of TECO may be assembled with the PAL8
assembler, in the same manner as any other PAL8 source program.
For example, if a TECa source DECtape is mounted on unit 1,
typing:
• R PALS
*TECQ.8NM,
7ABC,
LA BEL,
D+TAG,
LABEL ,

(contains an illegal character)
(first character must be alphabetic)
(must not contain imbedded spaces)
(contains a legal but non-alphanumeric character)
(must be terminated by a comma with no intervening spaces)

Current Location Counter
As source statements are processed, PAL8 assigns consecutive
memory addresses to the instructions and data words of the object
program.
The current location counter contains the address in which the
next word of object code will be assembled and is automatically
incremented each time a memory location is assigned. A statement
which generates a single object program storage word increments
the location counter by one. Another statement might generate six
storage words, incrementing the location counter by six.
The user sets or resets the location counter by typing an asterisk
followed by the octal absolute address value in which the next program word is to be stored. If the origin is not set by the user, PAL8
begins assigning addresses at location 200.
*300
TAG,

B,
A,

/SET CURRENT LOCATION COUNTER
TO 300

CLA
JMP A
0
DCA B

The symbol TAG (in the preceding example) is assigned a value
of 0300, the symbol B a value of 0302, and the symbol A a value
of 0303. If a symbol is defined more than once in this manner, the
assembler will print the illegal definition diagnostic:
ID address
where address is the value of the location counter at the second
occurrence of the symbol definition. The symbol is not redefined.
3-10

(For an. explanation of diagnostic messages refer to the section
on PAL8 Error Conditions.) For example:
*300
START,
TAD A
DCA COUNTER
CONTIN,
JMS LEAVE
JMP START
A,
-74
COUNTER,· 0
CLA CLL
START,

The symbol START would have a value of 0300, the symbol
CONTIN would have a value of 0302, the symbol A would have a '
value of 0304, the symbol COUNTER (considered COUNTE by
the assembler) would have a value of 0305. When the assembler
processed the next line it would print (during pass I):
ID COUNTE+OOOI

Since the first pass of P AL8 is used to define all symbols, the assembler will print a diagnostic during pass 2 if reference is made
to an undefined symbol. For example:
A,

*7170
TAD C
CLA CMA
HLT
JMP Al
0

This would produce the undefined symbol diagnostic:
US A+0003

Symbol Table
Initially, the assembler's symbol table contains the mnemonic
op-codes of the machine instructions and the assembler pseudo-op
codes; this is its permanent symbol table. As the source program is
processed, user-defined symbols along with their binary values are
added to the symbol table. The symbol table is listed in alphabetic
order at the end of pass 3.
3-11

During pass 1, if PAL8 detects that the symbol table is full (in
other words, there is no more memory space in which to store symbols ,and their associated values), the symbol table exceeded diagnostic is printed:
SE address
and control returns to the OS/8 Monitor. If the system contains
more than 8Kof memory, the user may choose the /K option with
the Run command, or more address arithmetic may be used to reduce the number of symbols. It is also possible to segment a program and assemble the segments separately, taking care to generate
proper links between the segments (see LINK GENERATION
AND STORAGE). PAL8's symbol capacity is 992 symbols.
The permanent symbol table contains 24 pseudo-operations
and 71 symbols, leaving space for 897 possible user-defined symbols. Each additional 4K allows 992 new symbols.
Instructions concerning altering the permanent symbol table are
discussed later in this chapter should the user wish to add instructions more suitable to his programming needs.
Direct Assignment Statements
The programmer may insert new symbols with their assigned
values directly into the symbol table by using a direct assignment
statement in the form:
SYMBOL=VALUE VALUE may be a number or expression. No spaces or tabs may
appear between the symbol to the left of the equal sign and the
equal sign itself. The following are examples of direct assignment
statements:
A=6,
EXIT=JMP I 0
C=A+B
All symbols to the right of the equal sign must be already defined.
The symbol to· the left of the equal sign is subject to the same restrictions as a symbolic address, and its associated value is stored
in the user's symbol table. The use of the equal sign does not increment the location counter; it is, rather, an instruction to the assembler itself.
3-12

A direct assignIiIent statement may also equate a new symbol to
the value assigned to a previously defined symb()l. For example:
BETA=17
GAMMA=BETA
The new symbol, GAMMA, is entered into the user's symbol table
with the value 17. The value assigned to a symbol may be changed
as follows:
ALPHA=5
. ALPHA=7
The second line of code shown changes the value assigned to
ALPHA from 5 to 7.
Symbols defined by use of the equal sign may be used in any valid
expression. For example:
*200
/DOES NOT UPPATE
/DOES NOT UPDATE
/THE VALUE 500 IS
LOC.200
/THE VALUE 1200 IS
LOC.201

A=100
B=400
A+B
TAD A
.

CLC
CLC
ASSEMBLED AT
ASSEMBLED AT

If the symbol to the left of the equal sign is in the permanent
symbol table, the redefinition diagnostic:
.
.

RD address
will be printed as a warning, where address is the value of the location counter at the point of redefinition. The new value will be
stored in the symbol table; for example:
CLA=7600.
will cause the diagnostic:
RD +200
Whenever CLA is used after this point, it will have the value 7600.
Symbolic Instructions

Symbols used as instructions must be predefined by the assembler
or defined in the assembly by the programmer. If a statement has
no label, the instructions may appear first in the statement and must
3-13

be terminated by a space, tab, semicolon, slash, or carriage return.
The following are examples of legal instructions:
TAD
PAGE
ZIP

(a mnemonic machine instruction)
(an assembler pseudo-op)
(an instruction defined by the user)

Symbolic Operands
Symbols used as operands normally have a value defined by the
user. The assembler allows symbolic references to instructions or
data defined elsewhere in the program. Operands may be numbers
or expressions. For example:
TOTAL, TAD ACI

+ TAG

The values of the two symbols ACI and TAG (already defined by
the user) are combined by a two's complement add (see the section
on Operators). This value is then used as the address of the
operand.

Internal Symbol Representation for PAL8
Each permanent and user-defined symbol occupies four words
tn the symbol table storage area. A PDP-8 instruction has an operation code of three bits as well as an indirect bit, a page bit, and
seven address bits. The PAL8 assembler distinguishes between
pseudo-ops, memory reference instructions, other permanent symbols, and user-defined symbols in the symbol table.
EXPRESSIONS
Expressions are formed by the combination of symbols, numbers,
and certain characters called operators, which cause specific arithmetic operations to be performed. An expression is terminated by
either a comma, carriage return, or semicolon.
Operators
There are seven characters in P AL8 which act as operators:

+
t

%
&

Two's complement addition
Two's complement subtraction
Multiplication (unsigned, 12-bit)
Division (unsigned, 12-bit)
, Boolean .inclusive OR
Boolean AND
3-14

spaCe
(or TAB)

Treated as a Boolean inclusive OR. except
in a memory reference instruction

Two's complement addition and subtraction are· explained in _
detail in Chapter 1 of INTRODUCTION TO PROGRAMMING;
the user should refer. to that handbook if he wishes more information. No checks for overflow are made during assembly, and
any overflow bits are lost from the high order end. For example:_
7755+24 will give a result of 1
The operators -+ and - may be used freely as prefix operators.
Multiplication is accomplished by repeated addition. No checks for
sign or overflow are made. All 12 bits of each factor are considered
as magnitu?e. For example:
3000t2 will give a result of 6000
Division is-accomplished by repeated subtraction. The numberof
subtractions which are performed is the quotient. The remainder is
not saved and no checks are made for sign. Division by 0 will
arbitrarily yield a result of O. For example:
7000% 1000 will yield a result of 7
This could be written as:
-1000%1000
In this case the answer might be expected to be -1 (7777), but all
12 bits are considered as magnitude and the result is still 7~
Use of the multiplication and division operators requires an attention to sign on the part of the programmer beyond that which is
required for simple addition and subtraction. Table 3-2 con- tains examples of operators.
The ! operator causes a Boolean inclusive OR to be performed bit
by bit between the left-hand term flnd the right-hand term. (The
inclusive OR is explained in Chapter 1 of INTRODUCTION TO
PROGRAMMING.) There is an option which can be given to the
assembler to have "!" interpreted as a 6-bit left shift of the; left
term prior to the inclusive OR of the right. According to this interpretation:
if A=l and B=2
then A!B=0102
3-15

Table 3-2 Use of Operators

Expression

Also written as:

Result

7777+2
7776-3

-1+2
-2-3

+1
7773 or-5

Ot2
2tO

o
o

1000t7
0%17
12%0
7777% 1
7000% 1000
1%2

7000 or -1000

o
o
-1%1
-1000% 1000

7777 or -1
7

llnder normal conditions· A!B would be 0003. The & operator
causes a Boolean AND to be performed bit by bit between the left
and right values. The operation is the same as that indicated by the
memory reference instruction AND.
SPACE has special significance depending on the context in
which it is used. When the symbol preceding the space is not a
memory reference instruction as in the following example:
SMA CLA
it causes an inclusive OR to be performed between them. In this
case, SMA=7500 and CLA=7600. The expression SMA CLA is
assembled as 7700. When SPACE is used following pseudo-operators it merely delimits the symbol. When it is used after memory
reference operators it also signals the assembler that a memory
reference instruction must be assembled.
User-defined symbols are treated as operate instructions. For
example:
•

A=333
*200
CLA

Possible expressions and their values using the symbols just defined
are shown below. Notice that the assembler reduces each expression to one 4-digit (octal) word:
3-16

A
B
A+B
A-B
-A
1-B
B-1
A!B
-71

0333
0222
0555
0111
7445
7557
0221
0333
7707

(an inclusive OR is performed)

If the information generated is to be loaded, the current location
counter is incremented. For example:

B-7;A+4;A-B
produces three words of information; the current location counter
is incremented after each expression. The statement:
HLT=HLT CLA
, produces no information to be loaded (it produces an association in
the symbol table) and hence does not increment the current location
counter.
*4721
TEMP,
TEM2,

The location counter is not incremented after the line TEMP,; the
two symbols TEMP and TEM2 are assigned the same value t in this
case 4721.
Since a PDP-8 instruction has an operation code of three bits as
well as an indirect bit, a page bit, and seven address bits, the assembler must combine memory reference instructions in a manner
_ somewhat differently from the way in which it combines operate or
lOT instructions. The assembler differentiates between the symbols
in its permanent· symbol table and user-defined symbols. The following symbols are used as memory reference instructions:
AND
TAD
ISZ
DCA
JMS
JMP

0000
1000
2000
3000
4000
5000

Logical AND
Two's complement addition
Increment and skip if zero Deposit and dear accumulator
Jump to subroutine
Jump
3-17
•

When the assembler has processed 'one of these symbols, the space
following it acts as an address field delimiter.

*4100
JMP A
CLA

A has the value 4101, JMP has the value 5000, and the space acts
as a field delimiter. These symbols are represented as follows:

A
JMP

100 001 000 001
101 000 000 000

The seven address bits of A are taken, e.g.:
000 001 000 001
The remaining bits of the address are tested to see if they are zeros
(page zero reference); if they are not, the current page bit is set:
000 011 000 001
The operation code is then ORed into the JMP expression to form:
101 011 000 001
or, written more concisely

in octal:

5301
In addition to the above tests, the page bits of the address field
are compared with the page bits of the current location counter. If
the page bits of the address field are nonzero and do not equal the
page bits of the current location counter, an out-of-page reference
is being attempted and the assembler will take action as described
in the section on Link Generation and Storage.

Special Characters
In addition to the operators described in the previous section,
P AL8 recognizes several special characters which serve specific
functions in the assembly process. These characters are:

*
"

equal sign
comma
asterisk
dot
double quote
3-18

()
[1
/

<>
$

parentheses
square brackets
slash
semicolon"
angle brackets
dollar sign

The equal sign, comma, asterisk, slash, and semicolon have been
previously described. The remainder will be described next.
The special character dot C.) always has a value equal to the
value of the current location counter. It may be used as any integer"
or symbol (except to the left of an equal sign), and must be preceded by a space when used as an operand. For example:
*200
JMP .+2
is equivalent to JMP 0202. Also,
*300
.+4400
will produce in location 0300 the quantity 2700. Consider:
*2200
CALL=JMS I.
0027
The second line (CALL~JMS I.) does not increment the current
location counter, therefore, 0027 is placed in location 2200 and
CALL is placed in the user's symbol table with an associated value
.of 4600 (the octal equivalent of JMS I ).
If a single character is preceded by a double quote ("), the 8-bit
value of ASCII code for the character is used rather than interpreting the character as a symbol (ASCII codes are lis~ed in Appendix
A). For example:
CLA
TAD

("A

The constant 0301 is placed in the accumulator. The code:
"

3-19

will be assembled as 0256. The character must not be a carriage
return or one of the characters which is ignored on input (discussed
at the end of this section).
Left and right parentheses ( ) enclose a current page literal
(closing member is optional).
'*200

CLA
TAD INDEX
TAD (2) .
DCA INDEX

The left parenthesis is a signal to the assembler that the expression following is to be evaluated and assigned a word in the constants table of the current page. This is the same table in which the
indirect address linkages are stored. In the above example, the
quantity 2 is stored in a word in the linkage and literals list beginning at the top of the current memory page. The instruction in
which the literal appears is encoded with an address referring to the
address of the literal. A literal is assigned to storage the first time
it is encountered; subsequent reference to that literal from the current page is made to the same register. The use of literals frees
symbol storage space for variables and makes programs much more
readable.
If the programmer wishes to assign literals to page zero rather than
to the current page, he may use square brackets, [ and ], in place of
parentheses. This enables the programmer to reference a single
literal from any page of memory. For example:
*200
TAD [2]
•
•
•

*500
TAD [2]
•
•

3-20

The closing member is optional. Literals may take the following
forms: constant term, variable term, instruction, expressIOn, or
another literal.
NOTE
Literals can be nested, for example:

*200
TAD (TAD (30
This type of nesting may be continued in
some cases to as many as 6 levels, depending
on· the number of other literals .on the page
and the complexity of the expressions within
the nest. If the limits of the assembler are
reached, the error messages BE (too many
levels of nestjng) or PE (too many literals)
will result.
Angle brackets ar.e used as conditional delimiters. The code enclosed in the angle brackets is to be assembled or ignored contingent
upon the definition of the symbol or value of the expression within
the angle brackets. (The IFDEF, IFNDEF, IFZERO, and IFNZRO
pseudo-operators are used with angle brackets and are described
later in this chapter.)
NOTE
Programs which use conditionals should
avoid angle brackets in comments' as they
may be interpreted as beginning or terminating the conditional.

The dollar sign character ($) is optional at the end of a program
and is interpreted as an unconditional end-of-pass. It may however
occur in a text string, comment or " term, in which case it is interpreted in the same manner as any other character.
The following characters are handled by the assembler for the
pass 3 listing, but are otherwise ignored:
FORM FEED
LINE FEED
RUBOUT

Used to skip to a new page
Used to create a line spacing without causing
a carriage return
Used by the EDITOR to allow corrections in
the input file
3-21

Nonprinting characters include:
SPACE
TAB
RETURN

INSTRUCTIONS
There are two basic groups of instructions: memory referen~e and
microinstructions. Memory reference instructions require an operand, microinstructions do not.
Memory Refer~nce Instructions
In PDP-8 computers, some instructions require a reference to
memory. They are appropriately designated memory reference instructions, and take the following format:
o

OPERATION
CODE 7
I

INDIRECT ADDRESSlNGt
foJEMOR.Y PAGE
.

ADDRESS

Figure 3-1 Memory Reference Bit Instructions

Bits 0 through 2 contain the operation code of the instruction to be
performed. Bit 3 tells the computer if the instruction is indirect.
Bit 4 tells the computer if the instruction is ,referencing the current
page or page zero. This leaves bits 5 through 11 (7 bits) to specify
an address. In these 7 bits, 200 octal (128 decimal) locations can
be specified; the page bit increases accessible locations to 400 octal
or 256 decimal. A list of the memory reference instructions and
their codes is given at the end of the chapter.
In PAL8 a memory reference instruction must be followed by a
space(s) or tabes), an optional I or Z designation, and any valid
expression. It may be defined with the FIXMRI· instruction. (See
pg. 3-33; Altering the Permanent Symbol Table.) Permanent symbols may be defined using the FIXTAB instruction and may be
used in address fields as shown below:
A=1234
FIXTAB
TAD A
3-22

Indirect Addressing
When the character I appears in a statement between a memory
reference instruction and ·an operand, the operand is interpreted as
the address (or location) containing the address of the operand to
be used in the current statement. Consider:
TAD 40

which is a direct address statement, where' 40 is interpreted as the
location on page zero containing the quantity to be added to the
accumulator. References to locations on the current page and page
zero may be done directly. "For compatibility with older paper-tape
assemblers the symbol Z is also accepted as a way of indicating a
page zero reference, as follows:
TAD Z 40

This is an optional notation, not differing in effect from the previous example. Thus, if loca,tion 40 contains 0432, then 0432 is
added to the accumulator. Now consider:
TAD I 40
which is an indirect address statement, where 40 is interpreted as
the address of the location containing the quantity to be added to
the accumulator. Thus, if location 40 contains 0432, and location
432 contains 0456, then 456 is added to the accumulator.

NOTE
Because the letter I is used to indicate indirect addressing, it is never used as a variable. Likewise the letter Z, which is sometimes used to indicate a page z~ro. reference,
is never used as a variable.
Microinstructions
Microinstructions are divided into two groups: operate and
Input/Output Transfer (lOT) microinstructi9ns. Operate microinstructions are further .subdivided into Group 1, Group 2, and
Group 3 designations.

3-23

NOTE
If a programmer mistakenly specifices an
illegal combination of microinstructions, the
assembl~r will perform an inclusive OR between them; for example:
eLL SKP is interpreted as SPA
(7100) (7410)
(7510)

OPERATE MICROINSTRUCTIONS
Within the operate group, there are three groups of microinstructions which cannot be mixed. Group 1 microinstructions perform
clear, complement, rotate and increment operations, and are designated by the presence of a 0 in bit 3 of the machine instruction
word.
.
0

2
1

I 0 IClA ICll I(MAl CMl I

ROTATE AC AND l RIGHT
ROTATE AC AND L LEFT
ROTATE 1 POSITION IF A 0, 2 POSITIONS IF A 1
(BSW IF BITS 8, 9 ARE 0)
LOGICAL SEQUENCE:

I I
1r
BSW [lAC

l-ClA, CLL

2-CMA,CML

3-IAC

4 - RAR,RAl,RTR,RTL,BSW

Figure 3-2 Group 1 Operate Microinstruction Bit Assignments

Group 2 microinstructions check the contents of the accumulator
and link and, based on the check, continue to or skip the next instruction. Group 2 microinstructions are identified by the presence
of a 1 in bit 3 and a 0 in bit 11 of the machine instruction word.
o

2345678

REVERSE SKIP SENSING OF BITS '5,6,7 IF SET

LOGICAL SEQUENCE: 1 (BIT 8 IS 0) - SMA OR SZA OR SNL
(BIT 8 IS 1) - SPA AND SNA AND SZL
2- ClA
3- OSR, HlT

Figure 3-3 Group 2 Operate Microinstruction Bit Assignments

3-24

9roup 3 microinstructions, reference the MQ register. They are
differentiated· from Group 2 instructions by the presence of a 1 in
bits 3 and 11. The other bits are part of a hardware arithmetic
option.
o

~~~TI~N!

IClA IMQAI

I I , ,

MOl

.
~ ~l

CQll.lTAINS A1 TO ~
~t
SPECIFY GROUP3
KE8-E EXTENDED ARITHMETIC ELEMENT
CONTAINS A1 TO SPECIFY GROUP 3 --------~

Figure 3-4 Group 3

Operate Microinstruction Bit Assignments

Group 1 and Group 2 microinstructions cannot be combined since
bit 3 determines either one or the other. Within Group 2, there are
two groups of skip instructions. They can be referred to as the OR
group and the AND group.
OR Group
AND Group
SMA
SPA
SNA
SZA
SNL.
SZL

The OR group is designated by a 0 in bit 8, and the AND group
by a 1 in bit 8. OR and ·AND group instructions cannot be com- .
bined since bit 8 determines either one or the other.
If the programmer does combine legal skip instructions, it is
important to note the conditions under which a skip may occur.
1. OR Group-If these skips are combined. in a s~atement, the
inclusive OR of the conditions determines the skip. For
example:
SZA SNL
The next statement is skipped if the accumulator· contains
0000 or the link is a 1 or both.
2. And Group-If the-skips are combined in a statement, the
logical AND of the conditions determines the skip. For
example:
SNASZL
The next statement is skipped only if the accumulator differs
from 0000 and the link is O.
3-25

INPUT/OUTPUT TRANSFER MICROINSTRUCTIONS
These microinstructions initiate operation of peripheral equipment and effect an information transfer between the central processor and the Input/Output device(s); i.e., console terminal, and
line printer.

Autoindexing
Interpage references are often necessary for obtaining operands
when processing large amounts of data. The PDP-8 computers
have facilities to ease the addressing of this data. When one of the
absolute locations from 10 to 17 (octal) is indirectly addressed, the
contents of the location is incremented before it is used as an
address and the incremented number is left in the location. This
allows the program.rner to address consecutive memory locations
using a minimum of statements. It must be remembered that
initially these locations (10 to 17 on page 0) must be set ·to
one less than the first desired address. Because of their characteristics, these locatiens are called autoindex registers. No
incrementation takes place when locations 10 to 17 are addressed directly. For example, if the instruction to be executed
next is in location 300 and the data to be referenced is on
the page starting at location 5000, autoindex register 10 can be
used to address the data as follows:
0276
0277
0300

1377
3010
1410

TADC4777
DCA 10
TAD 110

0377

4777

C4777,4777

/=5000-1
jSET UP AUTO INDEX
/INCREMENT TO 5000
/BEFORE USE AN AN
ADDRESS

When the instruction in location 300 is executed, the contents
of location 10 will be incremented to 5000 and the contents of
location 5000 will be added to the contents of the accumulator.
When the instruction TAD I lOis executed again, the contents
of location 5001 will be added to the accumulator, and so on.
PSEUDO-OPERATORS

The programmer uses pseudo-operators to direct the assembler
to perform certain tasks· or to interpret subsequent coding in a
3-26

certain manner. Some' pseudo-ops generate storage words in the
object program, other pseudo-ops direct the assembler how to proceed with the assembly. Pseudo-ops are maintained in the 'permanent symbol table. The function of each P AL8 pseudo-op is
described below.
Indirect and Page Zero Addressing
The pseudo-operators I and Z are used to specify the type of
addressing to be performed. These were discussed earlier in the
chapter.
/

Radix Control
Numbers used in a source program are initially considered to be
octal numbers. However, ,the programmer may change or alternate
the radix interpretation by the use of the pseudo-operators
DECIMAL and OCTAL. The DECIMAL pseudo-op interprets all
following numbers as decimal until the occurrence of the pseudo-op,
OCTAL. The -OCTAL pseudo-op resets the radix to its original
octal base.
Extended Memory
The pseudo-op FIELD instructs the assembler to ,output a field
s~tting so that it may recognize more than one memorr field. This
field setting is output during pass 2 and is recognized by the Absolute Loader which in turn causes all subsequent information to be
loaded into the field specified by the expression .. The form is:
FIELD n

•
n is an integer, a previously defined symbol, or ~ expression within'the range Oto 7~
This field setting is output on the binary file during pass 2
followed, by an origin setting of 200. This word is read by the
ABSLDR when it is executed and begins loading information into
the new field.
The field setting is never remembered, in binary, by the assembler and no initial field setting is output. However, it appears as
the high-order digit of the Location Counter on the listing. A
binary file produced without field settings will be loaded into field
o when using the ABSLDR.
A symbol in one field may be used to reference the same location
in any other field. The field to which it refers is determined by the

3-27

use of the CDF and CIF instructions. (The programmer who is
unfamiliar with the lOTs but wishes to use them 'should refer tothe PDP/8E SMALL COMPUTER HANDBOOK and experiment with several short test programs to satisfy himself as to their
effect.) CDF and elF instructions must be used prior to any instruction referencing a location outside the current field, as shown
in the following example:

P301 ..

NEXT ..

P302 ..
PRINT ..

PCDI F' ..

*200
TAD P301
DCF' 00
CI F' 10
JMS PRINT
CI F' 10
JMP NEXT
301
F'I ELD 1
*200
TAD P302
CDF' 10
JMS PRINT
HLT
302
0
TLS
TSF
JMP • - 1
CLA
RDF'
TAD PCDI F'
DCA • + 1
000
JMP I PRINT
CDF' CI F 0

When FIELD is used, the assembler follows the new FIELD
setting with an origin at location 200. For this reason, if the programmer wants to assemble code at location 400 in field 1 he must
write:
FIELD 1 '
*400

/CORRECT EXAMPLE

The following ,is incorrect and will not generate the desired code:
*400
FIELD 1

/INCORRECT ,
3-28

Specifying the /0 option to P AL8 inhibits the origin to 200 after
a FIELD pseudo-oPe
End-Of-File
PAUSE signals the assembler to stop processing the file being
read. The current. pass is not terminated, and processing continues
with the next file. The PAUSE pseudo-op is present mainly for:
compatability with paper tape assemblers, and its use is optional.
Resetting The Location Counter
The PAGE n pseudo-op resets the location counter to the first
address of page n, where n is an integer, a previously defined symbol, or a symbolic expression, whose terms have been defined previously and whose value is from 0 to 37 inclusive. If n is not specified, the location counter is reset to the next logical page of memory. For example:
PAGE 2 sets the location counter to 00400
PAGE 6 sets the location counter to 01400
If the pseudo-op is used without an argument and the current loca-

tion counter is at the first location of a page, it will not be moved.
In the following example, the code TAD B is assembled into
location 00400:
*377
IMP .-3

PAGE
TADB
.If several consecutive PAGE pseudo-ops are given, the first will
cause the current location counter to be reset as specified. The rest
of the PAGE pseudo-ops will be ignored.

Entering Text Strings
The TEXT pseudo-op allows a string of text characters to be
entered as data and stored in 6-bit ASCII by using the pseudo-op
TEXT followed by-a space or spaces, a delimiting character (must
be a printing character), the string of text,and the same delimiting
character. Following the last character, a 6-bit zero is inserted as a
stop code. For example:
TAG,

TEXT/123*/
3-29

The-string would be stQred as:
6162
6352
0000
The IF option inhibits the generation ()f the extra 6-bit zero character.
Suppressing The Listing

Those portions of the source program enclosed by XLIST
,pseudo-ops will not appear in the listing file; the code will be
assembled, however.
Two XLIST pseudo-ops may be used to enclose the code to be
suppressed in which case the first XLIST with no argument will
suppress the listing, and the second :will allow it again. XLIST
may also be used with an expression as an argument; a listing will
be inhibited if the expression is equal to zero, or allowed if the expression is not equal to zero. XLIST pseudo-ops never appear in
the assembly listing.
Reserving Memory

ZBLOCK instructs the assembler to reserve n words of memory
containing zeroes, starting at the word indicated by the current··
location counter. It is of the form:
ZBLOCKn
For example:
ZBLOCK40
causes the assembler to reserve 40 (octal) words. The n may be an
expression. If n=O, no locations are reserved.
Conditional Assembly Pseudo-Operators

The IFDEF pseudo-op takes the form:
IFDEF symbol
If the symbol indicated is previously defined, the code contained

in the angle brackets is assembled; if the symbol is undefined, this
code is ignored. Any number of statements or lines of code may be
contained in the angle brackets. The format of the IFDEF statement requires a single space before and after the symbol.
3-30

The IFDEF pseudo-op is similar. in form to IFDEF and is expressed:
IFNDEF symbol
If the symbol indicated· has not been _previously defined, the
source code in angle brackets is assembled. If the symbol is defineq,
the code in the angle brackets is ignored. The IFZERO pseudo-op
is of the form:

IFZERO expression
If the evaluated (arithmetic or logical) expression is equal to
zero, the code within the angle brackets is assembled; if the expression is non-zero, the code is ignored. Any number of statements or
lines of code may be contained in the angle brackets. The expression may not contain any imbedded spaces and must have a single
space preceding and following it. IFNZRO is similar in form to
the IFZERO pseudo-op and is expressed:

IFNZRO expression
If the evaluated (arithmetic or logical) expression is not equal
to zero, the source code within the angle brackets is. assembled; if
the expression is equal to zero, this code is ignored. Pseudo-ops can
be nested, for example:

IFDEF SYM >
The evaluation and subs~quent inclusion or deletion of statements
is done by evaluating the outermost pseudo-op firsL
Controlling Binary Output
NOPUNCH causes the assembler to cease binary output but
continue assembling code. It is ignored except during pass 2.
ENPUNCH causes the assembler to resume binary output after
NOPUNCH, and is ignored except during pass 2. For example,
these two pseudo-ops might be used where several programs sharethe same data on page zero. When these programs are to be loaded
and executed together, only one page zero need be output.
Controlling Page Format
_The EJECT pseudo-op causes the listing to jump to the top of
the next page. A page eject is done automatically every 55 lines;

3-31

EJECT is useful if the user requires more frequent paging. If this
pseudo-op is followed by a string of characters, the first 50 (octal)
characters of that string will be used as a new header line.
Typesetting Pseudo· Operator
DTORG is used in typesetting to output a two frame DECtape
block number (4 digits) in the binary tape. The form of this pseudoop is as follows:

DTORG expression
The first frame on the binary tape includes channels 7 and 8
punched (in the same manner as a FIELD setting) as a signal to a
special typesetting loader that the following data is to be loaded
into DECtape block fl. The DTORG setting is added into the
checksum, unlike the FIELD setting, which is not included.
DTORG and FIELD should not be used in the same program.
Calling OS /8 User Service Routine
The pseudo-operators DEVICE and FILENAME may be used
by calls to the OS/8 User Service Routine, but have no other
meaning to the assembler. The form for these pseudo-ops is:

DEVICE name
FILENAME name. extension
When using DEVICE, the name can be from 1 to 4 alphanumeric
characters. These are trimmed to 6-bit ASCII and packed into 2
words, filled in with zeroes on the right if necessary. With
FILENAME (FILENA is also acceptable) the name (or name.extension) may be from 1 to 6 alphanumeric characters and
the optional extension may be 1 or 2 characters. The characters are
trimmed to 6-bit ASCII and packed 2 to a word. Three words are
allocated for the filename, filled with zeroes on the right if less than
6 characters are specified, followed by one word for the extension.
For example:
L,

FILENAME ABC.DA

is equivalent to the following coding:
L,

0102
0300
0000
0401
3-32

Relocation Pseudo-Op
It is' sometimes desirable to .assemble' code at a given /location
and then move it to another location for execution. This may result
in errors unless the relocated code is assembled in such a way that
the assembler assigns symbols their execution-time addresses rather
than their load-time addresses. The RELOC pseudo-op establishes
a virtual location counter without altering the actual location
counter. The line:
RELOC expr
sets the virtual location counter to expr. The line:
RELOC
sets the virtual location counter equal to the actual location counter
and terminates the relocation section.
Example:
0400
2000
02000* 1377
02001* 3005
02177* 2000
0600

CODE,

*400
RELOC 2000
TAD (CODE
DCA 5
PAGE
RELOC

The location marked CODE is loaded into location 400, but the
assembler treats it as if it were' loading into location 2000. The
asterisks after the location" values indicate that the virtual and the
actual location counters differ for that line of code. RELOC always
causes current page li~erals to be dumped.

Altering The ~ermanent Symbol Table
PAL8 contains a table of symbol definitions for the PDP-8 and
OS/8 peripheral d~vices. These are symbols such as TAD, DCA,
and CLA, which are used in most PDP-8 programs. This table is
considered to be the permanent symbol table for PAL8.
If the user purchases one or more optional devices whose instruct:on set is not defined among the permanent symbols (for example
EAE or an A/D converter), he would want to add the necessary
symbol definitions to the permanent symbol table in every program
he assembles.
3-33

Conversely, the user who needs more space for user-defined
symbols would probably want to delete all definitions except the
ones used in his program. For such purposes, PALS has three
pseudo-ops that can be used to alter the permanent symbol table.
These pseudo-ops are recognized by the assembler only during
pass 1. During either pass 2 or pass 3 they are ignored and have
no effect.
EXPUNGE deletes the entire permanent symbol table, except
pseudo-ops.
FIXTAB appends all presently defined symbols to the permanent symbol table. All symbols defined before the occurrence of
FIXTAB are made part of the permanent symbol table for the
current assembly.
To append the· following instructions to the symbol table, the
user generates an ASCII file called SYM.PAL containing:
MUY=7405
DVI=7407
CLSK=6131
FIXTAB

/MULTIPLY
/DIVIDE .
ISKIP ON CLOCK INTERRUPT
ISO THAT THESE WON'T BE
/PRINTED IN THE SYMBOL TABLE

The ASCII file is then entered in PALS's input designation. The
user may also place the definitions at the beginning of the source
file. This eliminates the need to load an extra file. Each time the
assembler is loaded, PALS's permanent symbol table is restored.
The third pseudo-op used to alter the permanent symbol table in
PALS is FIXMRI. FIXMRI is used to define a memory reference
instruction and is of the form:
FIXMRI name'=value
The letters FIXMRI must be followed by one space, the symbol
for t~e instruction to be defined, an equal sign, and the value of the
symbol. The symbol will be defined and stored in the symbol table
as a memory reference instruction. The pseudo-op must be repeated
for each memory reference instruction to be defined. For example:
EXPUNGE
FIXMRI T AD= 1000
FIXMRI DCA=3000
CLA=7200
FIXTAB
3-34

When the preceding program segment is read into the assembler
during pass 1, all symbol definitions are deleted and the three symbols listed are added to the permanent symbol table. Notice that _
CLA is not a memory r"eference instruction. This process can be
performed to alter the .assembler's symbol table so that it contains
only those symbols us~d at a given installation or by a given program. This may increase the assembler's capacity for user-defined
symbols in the, program.
.-

LINK GENERATION AND STORAGE
In addition to handling symbolic addressing on the current page
of memory, PAL8 automatically generates links for off-page references. If reference is made to an address not on the page where an
instruction is located, the assembler sets the indirect bit (bit 3) .and
an indirect adqress linkage will be generated on the current memory page. If the .off-page reference is already an indirect one, the
error diagnostic II (illegal indirect) will be generated. For example:

*2117
A,

CLA

*2600
JMPA
-.

In the example above, the assembler will recognize that the register
labelled A is not on the current page (in, this case 2600 to 2777)
and will generate a link to it as follows:
1. In location 2600 the assembler will place the word 5777
which is equivalent to JMP I 2777.
2. In address 2777 (the last available location on the current
page) the assembler will place the word 2117 (the actual
address of A).
During pass 3, the octal code for the instruction will be followed by
an apostrophe (') to indicate that a link was generated.
Although the assembler will recognize and generate an indirect
address linkage when, necessary, the programmer may indicate an
explicit indirect address by the pseudo-op I. The assembler cannot
3-35

generate a link for an instruction that is already specified as being
an indirect reference. In this case, the assembler will print the error
message II (illegal indirect). For example:
t

*2117
A,

CLA

*2600
JMPIA'
The above coding will not work because A is not defined on the
page where JMP I A is attempted, and the indirect bit is already
set.
Literals and links are stored on each page starting at page
address 177 (relative) and extending toward page address 0
(relative). Whenever the origin is then set to another page, the
literal buffer for the current page is output. This does not affect
later execution. There is room for 160 (octal) litera]s and links on
page zero and 100 (octal) literals on each other page of memory. '
Literals and links are stored only as far down a~ the highest "instruction on the page. Further attempts to define literals will result
in a PE (page exceeded) or ZE (page zero exceeded) error message.
CODING PRACTICES

A neat printout (or program listing, as it is usually called) makes
subsequent editing, debugging, and interpretation much easier than
if the coding were laid out in a haphazard fashion. The coding
practices listed below are in general use, and will result in a
readable, orderly listing.
1. A title comment begins with a slash at the left margin.
2. Pseudo-ops may begin at the left margin; often, however,
they are indented one tab stop to line up with the executable
instructions.
3. Address labels begin at the left margin~ They are separated
from succeeding fields by a tabulation.
4. Instructions, whether or not they are preceded by a label
field, are~ indented one tab stop.
3-36

5~..

A comment is separated from the preceding field by one or
two tabs (as required) and a slash; if the comment occupies
the whole line it usually begins with a slash at the left margm.

PROGRAM PREPARATION AND ASSEMBLER OUTPUT
The following program was generated using the OSj8 EDITOR
and was assembled with PAL8.
/SAMPLE PAL8 PROGRAM
/GETS INPUT FROM KBD,HAL TS WHEN "E" I S TYPED
*200

BEGIN,

lEND

KCC
KSF
JMP .-1
KRB
TAD (-"E
SNA CLA
HLT
JMP BEGIN+1
OF EXAMPLE

/WAIT FOR FLAG
/READ IN CHARACTER
II

SIT

The program consists of statements and pseudo-ops and is
terminated by the dollar sign ($). If the program is large, it can be
". segmented by placing it into several files; this often facilitates the
editing of the source program since each section will be physically
smaller."
The assembler initially sets the current location counter to 0200.
This counter is reset whenever the asterisk (*) is processed.
The· assembler reads the source file for pass 1 and defines all
symbols used. During pass 2, the assem~ler reads the source file
and generates the -binary code using the symbol table equivalences
defined during pass 1. The binary file that is output may be loaded
by the Load command. This binary file consists of an origin setting
and data words.
During pass 3, the -assembler reads the source file and generates
the code from the source statements. The assembly listing is output
in ASCII code. It consists of the current location counter, the
generated code in octal, and the source statement. Unless options
are chosen to suppress paging or to change the header, the first 50
(ectal) characters of the first line of the source program will be used
3-37

as a heading for each page followed by the assembler version-number, the date and the listing page" number. The 5-digit first column
is the field number and 4-digit octal address (current location
counter); the 4-digitsecond column is the assembled object code.
The symbol table is printed at the end of the pass. The pass 3 output is:

ISAMPLE PAL8 PROGRAM
IGETS INPUT FRO~ KBO,HALTS WHEN "E" IS TYPED
00200
210201
00202
00203
00204
00205
212120&
210207

0ii!00
&2132
&031
5201
&03&
137'7
7&50
7402
5201

2121317

7473

BEGIN,

*2210

KCC
KSF
JMP .-1
KRB
TAD (wilE
SNA CLA
HLT
JMP BEGIN+l
lEND of EXAMPLE

IWAITFOR FLAG
IREAD IN CHARACTER
115 IT E?

ISAMPLE PALS PROGRAM
BEGIN

0200

TERMINATING ASSEMBLY
P AL8 will terminate assembly and return to the Monitor under
any of the following conditions:
. 1. Normal exit: The end of the source prograin was reached
on pass 2 (or pass 3 if a listing is being generated).
2. Fatal error: One of the following error conditions was found
and flagged (see the next section):

3. CTRL/C: If typed by the user, control returns to the Monitor.
3-38

PAL8 ERROR CONDITIONS
.
PAL8 will detect and flag error conditions and generate error
messages on the console terminal. The format of the error message
IS:

CODE address
where code is a 2-letter code which specifies the type of error, and
address is either the absolute octal address where the error occurred
. or the address of the error relative to the last symbolic tag (if there
was one) on the current page. For example, the following code:
BEG,

TAD LBL
%TAD LBL

would produce the error message:
IC BEG+OOOI

since % i,s an illegal character.
On the pass 3 listing, error messages are output as 2-character
messages on the line just prior to the line in which the error occurred. The following table lists the PAL8 error codes. Those
labeled Fatal Error are followed immediately by an effective
CTRL/C.
Table 3-3 PALS Error Codes
Error Code

Meaning

Two P AL8 internal tables have overlapped. This situation can usually be corrected by decreasing the level of
literal nesting or the number of current page literals used
prior to this point on the page. Fatal error: assembly
cannot continue.
'

Chain to CREF error. CREF.SV was not found on
SYS: .

D E < Device error. An error was detected when trying to read
or write a device. Fatal error assembly cannot continlle.
DF

Device full. Fatal error: assembly cannot continue.

Illegal character. The character is ignored and the assembly is continued.

3-39

Table 3-3 PAL 8 Error Codes (Cont.)
Error Code

Meaning .

Illegal redefinition of a symbol. An attempt was made
to give a previous symbol a new value by means other
than the equal sign. The symbol is not redefined.

Illegal equals. An attempt was made to equate a variable
to an expression containing an undefined term. The variable remains undefined.

Illegal indirect. An off-page reference was made; a link
could not be generated because the indirect bit was already set.

Illegal pseudo-op. A pseudo-op was used in the wrong
context or with incorrect syntax.

Illegal page zero reference. The pseudo-op Z was found
in an instruction which did not refer to page zero. The Z
is ignored.
.

The / L or I G options have been specified and the Absolute Loader is not present on the system.

Link generated. This code is printed only if the / E option
was specified to PALS.

Current non-zero page exceeded. An attempt was made
tn'
~'V.

L Override a literal with an instruction.
2. Override an instruction with a literal.
"

3. Use more literals than the assembler allows on that
page.
This can be corrected by decreasing either the number of
literals on the page or the number of instructions on the
page.
PH

Phase error. A conditional assembly bracket is still in
effect at the end of the input stream. This is caused by
non-matching < and> characters in the source file.

Redefinition. A permanent symbol has !>een defined
with =. The new and old definitions do not match. The
redefinition is allowed.

Symbol table exceeded. Too many symbols have been
defined for the amount of memory available. Fatal error:
assembly cannot continue.

3-40

Table 3-3 PALS Error, Codes (Cont.),
Error Code

Meaning

Undefined origin. An undefiried symbol has occurred in
an origin statement.

, US

Undefined symbol. A symbol has been processed during
pass 2 that was not defined before the end of pass 1.

Page 0' exceeded., This is the same as PE except with
reference to page O.

PAL8 PERMANENT SYMBOL TABLE
The following are the most commonly used elements of the
PDP-8 instruction set and are found in the permanent symbol table
within the PAL8 Assembler. For additional information on 'these
instructions and for a description of the synibols used when programming other optional devices, see THE SMALL COMPUTER
HANDBOOK, available from the DIGITAL Software Distribution
Center. (All times are in microseconds and representative of the
PDP-8/E.)
Mnemonic

Time

Operation

Code

, Meinory Reference Instructions
AND
TAD
ISZ
DCA
JSM
JMP
lOT
OPR

0000
1000
2000
3000
4000
5000
6000
7000

Logical AND
Two's complement add
Increment and skip if zero
Deposit and clear AC
Jump to subroutine
Jump
InlOut transfer
Operate

Group 1 Operate Microinstru~tions (1 cycle
NOP
lAC
BSW
RAL
RTL

7000
7001
70Q2
7004
7006

1.2
. 1.2

= 1.2 microseconds)

No operation
Increment AC
Byte swap
Rotate AC and link left one
Rotate AC and link left two
3-41

2.6
2.6
2.6
2.6
2.6

3
3
4
4

Mnemonic

Code

RAR
RTR
CML
CMA
CLL
CLA

7010
7012
7020
7040
7100
7200

Operation

Sequence

Rotate AC and link right one
Rotate AC and link right two
Complement the link
Complement the AC
Clear link
Clear AC

4
4
2
2
1
1

Group 2 Operate Microinstructions (1 cycle)
HLT
OSR
SKP
SNL
SZL
SZA
SNA
SMA
SPA

7402
7404
7410
7420
7430
7440
7450
7500
7510

Halts the computer
Inclusive OR SR with AC '
Skip' unconditionally
Skip on non zero link
Skip on zero link
Skip on zero AC
Skip on non zero AC
Skip on minus AC
Skip on positive AC (zero is
positive)

3
3
1
1
1
1
1
1
1

Group 3 Operate Microinstructions
MQA
, MQL
SWP

7501
7421
7521

Multiplier Quotient OR into AC
Load Multiplier Quotient
Swap AC and Multiplier Quotient

Combined Operate Microinstructions
CIA
STL
GLK
STA
LAS

7041
7120
7204
7240
7604

Complement and increment AC
Set link to '1
Get link (put link in AC, bit 11)
Set AC to-l
Load AC with SR

3-42

2.3
1.2

1.4
2.0
2.3

Mnemonic

Operation

Code

Time

Internal lOT Microinstructions
SKON

6000

ION
IOF
GTF
RTF
SGT
CAP

6001
6002
6004
6005
6006
6007

Skip with interrupts on and turn
them off
.Turn interrupt. processor on
Tum interrupt processor off
Get flags
Restore flag, ION
Skip if "Greater Than" flag is set
Clear all flags

1.2
,1.2

Keyboard/Reader (l cycle)
KCF
KSF
KCC
KRS
KIE
KRB

6030
6031
6032
6034
6035
6036

'Clear keyboard flags
Skip on keyboard/reader flag
Clear keyboard/reader flag and
AC; set reader run
Read keyboard/reader buffer
(static)
Set/clear interrupt enable
'Clear AC, read keyboard buffer
(dynamic), clear keyboard flags

1.2
1.2
",

1.2
1.2

Teleprinter/Punch (1 cycle)
TFL
TSF
TCF
• TPC
TSK
TLS

6040
6041
6042
6044
6045
6046

Set teleprinter flag
Skip on teleprinter/punch flag
Clear teleprinter/punch flag
Load teleprinter/punch and
print
Skip on keyboard or teleprinter
flag
Lo~d teleprinter/punch, print,
and clear teleprinter/punch flag

3-43

1.2
1.2
1.2
1.2
1.2

Mnemonic

Code

Operation

Time

High Speed Perforated Tape Reader
RPE
RSF
RRB

nFrt
J.'\.. '-'

6010
6011
6012
6014

Set Reader/Punch interrupt enable
Skip if reader flag= 1
Read reader buffer and clear
flag
Clear flag and buffer and fetch
character

1.2
1.2
1.2
1.2

High Speed Perforated Tape Punch
PCE
PSF
PCF
PPC
PLS

"6020
6021
6022
6024
6026

Clear Reader/Punch interrupt
enable
Skip if punch flag= 1
Clear flag and buffer
Load buffer and punch character
Clear flag and buffer, load buffer
and punch character

3-44

1.2
1.2
1.2
1.2
1.2

"..r

4
sabr
INTRODUCTION

The OS/8 SABR assembler is a modified version of the 8K
SABR assembler which is designed to run under the OS/8 Operating System.
The OS/8 SABR assembler can be used as the automatic second pass of the FORTRAN compiler, called separately to do
assemblies of FORTRAN compiled files, or used as an independent
assembler with its own assembly language. In addition, SABR
statements may be used in an OS/8 FORTRAN program, expand.
ing the capabilities of the FORTRAN language.
Calling and Using OS /8 SABR

Unless otherwise specified, the SABR assembler is called automatically by the system to assemble the output of a FORTRAN
compilation. At other times the user can call SABR by typing:
R SABR

in response to the dot printed by the Keyboard Monitor. When
the Command Decoder prints an asterisk at ~e left margin, the
user types the appropriate device assignations, I/O files, and any
of the .acceptable options.
The line to the' Command Decoder consists of 0 to 3 output device and file designations, 1 to 9 input device and file designations,
and the desired option (s ). The form is:
*BINARY,LISTING,MAP

4-17

PAGE

REORG

CPAGE

The PAGE pseudo-op causes the current core
page to be assembled as is~ Assembly of succeeding instructions will begin on the next core page.
No argument is required.
The REORG pseudo-op is similar to the PAGE
.pseudo-op, except that a numerical argument
specifying the relative location within the sub- .
program where assembly of succeeding instructions is to begin must be given. A REORO below
200 may not be given. A REORG should always
be to the first address of a core page. If a REORG
address is not the first address of a page, it will
be converted to the first address of the page it
IS on.
0200

7200

0400

7040

1000

7041

START! .

CLA
PAGE
CMA
REORG 1000
CIA

The CP AGE pseudo-op followed by a numerical
argument N specifies that the following N words of
code 1 must be kept together in a single unit and
not be split up by page escapes and literal tables.
If the N words of code will not fit on the current
page of code, the current page is assembled as if a
PAGE pseudo-op had been encountered. The N
words of code will then be assembled as a unit on
the next core page. An example follows.

NOTE
N must be less than or equal to 200 (octal)
in nonautomatic paging mode or less than or
equal to 176 octal in automatic paging mode.

1 Normally

data. However, if these N words are instructions, for example
a CALL with arguments, it is the user's responsibility to count extra
machine instructions which must be inserted by SABR.

4-18

0200

7200

0400
0401

0000
0000

START,

CLA
LAP
IIN~IBIT PAGE ESCAPE
CPAGE 200 ICLOSES THE
NAME1
ICURRENT PAGE
NAME2
lAND ASSEMBLES
ITHE NEXT PAGE

The conditional pseu~o-op, IF,
following syntax:.
IF NAME...

used with the

The action of the pseudo-op in this case is to first
determine whether the symbol NAME has been
previously defined. If NAME is defined, the
pseudo-op has no effect. If N AtvIE is not defined,
the next seven symbolic instructions (not counting
null lines and comment lines) will be treated as
comments and not assembled.

IABSYM NAME 176
IF NAME, 2
/THE NEXT LINE
CLL RTL
/TO BE ASSEMBLED
RAL
/WILL·BE "DCA LOC"
/IF THE SLASH BEFORE "ABSYM NAME 176"
/IS REMOVED, THE "CLL RTL" .AND "RAL"
/WILL BE ASSEMBLED.
0200
0201

3201
0000

DCA LOC

LOC,

Normally the symbol referenced by an IF statement should be either an undefined symbol or a
symbol defined by an ABSYM statement. If this
is done, the situation mentioned below cannot
occur.

WARNING
In a situation such as the following, a special
restriction applies.
4-19

NAME,

IF NAME, 3

The restriction is that if the line NAME, 0 happens to occur on the same core page of instructions as the IF statement, then, even though it is
before the IF statement, NAME will not have been
previously defined when the IF statement is encountered, and on the first pass (though not in the
listing pass) the three lines after the IF statement
will not be assembled. The reason for this is that
location t~gs cannot be defined until the page on
which they occur is assembled as a unit.

Symbol Definition
ABSYM

OPDEF
SKPDF

An absolute core address may be named using the
ABSYM pseudo-op. This address must be in the
same core field as the subprogram in which it is
defined. The most common use of this pseudo-op
is to name page zero addresses not used by the
operating system. These addresses are listed under
Linkage Routine Locations.
Operation codes not already included in the symbol table may be defined by use of the OPDEF or
SKPDF pseudo-ops. Non-skip instructions must
be defined with the OPDEF pseudo-op and skiptype instructions must be defined with the SKPDF
pseudo-op.

Examples of ABSYM, OPDEF and SKPDF syntax:

0177
0010
6761
6771
7540

ABSYM
ABSYM
OPDEF
SKPDF
SKPDF

TEM
AX
DTRA
DTSF
SMZ

4-20

177
10
6761
6771
7540

IPAGE 0 ADDRESSES
INON-SKIP INSTR.
ISKIP-T'YPE INSTR.

NOTE
ABSYM, OPDEF and SKPDF definitions
must be made before th~y are used in the
program.

COMMN '

The COMMN pseudo-op is used to name loca;.
tions in field 1 as externals so that they may be
referenced by any program. If any COMMN statements are· used, they must occur at the beginning
of the source, before everything else including
the ENTRY statement. Common storage is always"
in field 1 and is allocated from location 0200
upwards. Since the top page of field 1 is reserved,
no more than 384010 words of common storage
may be defined.
A COMMN statement normally takes a symbolic
address label, ~ince storage is being allocated.
However, common storage may be allocated with-.
out an address label.
A COMMN statement always takes a numerical
argument which specifies how many words of
common storage are to be allocated; however, a
o argument is "allowed. A COMMN statement
with 0 argument allocates no common storage;
it merely defines the given location symbol at the
next free common location.
The syntax of the COMMN statement is shown
as folloW-s :

o 2/J i7
0220
0230
0530
0530

CCIVY):
COtv:MN
COMMN
CCrv:MN
COMMN
ENTRY

B,
c~
D~

211
10
300
0
10

SUERUT

In this example- 20 words of common storage are
allocated from 0200 to 0217, and A is defined
at location 0200. Then, 10 words are allocated
4-21

from 0220 to 0227, and B is defined at 0220.
Notice that if A is actually a 30 word array, this
example equates B ( 1) with A (21) .
The example continues by allocating common
storage from 0230 to 0527 with no name being
assigned to this block. Then 10 words are allocated from 0530 to 0537 with both C and D
being defined at 0530.

Data Generating
BLOCK
The BLOCK pseudo-op given with a numerical
argument N will reserve N words of core by
placing zeros in them. This pseudo-op creates
binary output, and thus may have a symbolic
address label.
Before the N locations are reserved, a check is
made to see if enough space is available for them
on the current core page. If not, this page is assembled and the N locations are reserved on the
next core page. The action here is similar to that
of the CPAGE pseudo-op. Similar restrictions on
the argument apply.
/EXAMPLE OF HOW LARGE BLOCK STORAGE
/MAY BE ACHIEVED WITHIN A SUBPROGRAM AREA
LAP
BLOC:.K 2QlQl
BLOCK 2QlQl
BLOCK lQlQl
EAP

/INHIBIT PAGE ESCAPES
/RESERVE 5QlQl
/(QlCTAL) LOCATIONS
IRESUME NORMAL CODING

As a special use, if the BLOCK pseudo-op is used
with a location tag (but with no argument or a
zero argument), no code zeros are assembled; instead the symbolic address label is made equivalent to the next relative core location assembled.
(This is equivalent to usi~g a symbolic address
label with no instruction on the same line.)

4-22

TEXT

The TEXT pseudo-op is used to obtain packed
six-bit ASCII text strings. Its function and use
are almost exactly the same as for the BLOCK
pseudo-op except that instead of a numerical argument, the argument is a text string. In particular, a check is made to be sure that the text
string will fit on the current page without being .
interrupted by literals, etc.
The text string argument must be contained on
the same line as the TEXT pseudo-op. Any printing character may be used to delineate the text
string. This character must appear at both the beginning and the end of the string. Carriage return,
line feed and form: feed are illegal characters
. within a text string (or as delineators). All characters in the string are stored in simple stripped
six-bit form. Thus, a tab character (ASCII 211)
will be stored as an 11, which is equivalent to the
coding for the letter I. In general, characters outside the ASCII range of 240-337 should not be
used.
0200
0201
0202
0203
0204
0205
0206
0207
0210
0211

2405
3024
4005
3001
1520
1405
4061
6263
5273
7700

TAG,

4-23

TEXT

/TEXT EXAMPLE 123*;?/

SUBROUTINES

A subroutine is a subprogram which performs a specific operation and is geperally designed so that it can be used more than
once or by more than one program. Direction of flow goes from the
main, or calling, program to the subroutine, where the action is
performed, followed by a return back to the address following the
subroutine call in the main program.
Internal subroutines are those subroutines which can only be
called from within a program. This type of subroutine is used
extensively in nearly all PDP-8 programs, and is handled through
the use of the JMS, JMS I, and JMP I instructions. An example of
an internal subroutine call follows:

o 200
020 1
0202

7300
1204
4206

0203

3205

0204
0205

0001
0000

0206
0207

0000
7104

0210
021 1
0212
0213

7 /130

7402
6201 05
5606

START,

N,
RESLT,

CLA CLL
TAD N
JMS TWO

/GET NUMBER IN AC
ITRANSFER TO SUB/ROUTINE
DCA RESLT ISTORE NUMBER
/(CONTROL RETURNS
IHERE)
1
0

/SUBROUTINE
TWO,
0

cu.

RAL

/ROTATE LEFT AND
/MULTIPLY BY 2
ICHECX FOR OVERFLOW
...c:" 7T
.......
HLT
ISTOP IF OVERFLOW
JMP I TWO /RETURN TO MAIN
/PROGRAM
END .

The main program picks up a number (N) and jumps to the
subroutine (TWO) where N is multiplied by two. A check is made,
and if there is no overflow, control returns to the main program
through the address stored at the location TWO.
External subroutines are distinguished from internal ·subroutines by the fact that they may be called by a program which has
been compiled, or assembled, without any knowledge of where the
subroutine will be located in core memory. Thus, external subroutines must be loaded with a relocatable linking loader. This
makes it possible for a programmer to build a library of frequently
4-24

used programs and subroutines which can be cpmbined in various
configurations, aI),d eliminates the need to reassemble, or recompile,
each individual program when a minor change is made in the
system.
A call to an external subroutine can be illustrated using the
following FORTRAN programs:

100

, IPARM=S
CALL TVJO CIPARM)
WRITE <1,100) IPARM
FORMAT CIS)
END
SUBROUTINE TWOCIARG)
H\RG = IARG + IARG
RETURN
END

(Calling Program)

(Subroutine)

NOTE
Care should be exercised when naming a
function or subroutine. It must not have the
same name as any of the assembler mnemonics or pseudo-ops or FORTRAN/SABR
library functions or 'subroutines, as errors are
likely to result. The symbol table f9r SABR
Assembler is listed in Appendix C, and the
library functions are described in the section
The Subprogram Library.
Any time a subroutine is called, it must have data to process.
This data is contained in parameters in the calling program which
are then passed to the subroutine. The data is picked up by the
subroutine where it is referred to as arguments. (The subroutine
actually picks up the arguments by a series of TAD 1's, and one
final TAD I for an integer argument, or by a call to the IFAD
subroutine if a floating point argument. This is illustrated in the
section entitled SABR Programming Notes.) SABR has special
pseudo-operators' which facilitate the passing/handling of arguments, and each will be explained in turn.

CALL andARG
The CALL pseudo-op is used by the main program to transfer
control to the subroutine and is of the form:
4-25

CALL_n,NAME
where n represents a one or two-digit number (62 10 maximum).
indicating the number of parameters' to be passed to the subroutine, and NAME (separated from n by a comma) represents the
symbolic name of the subroutine entry point. .
The Assembl~r must know the number of parameters which
follow the call so that enough room on the current page can be
allowed. The CALL pseudo-op and its corresponding parameters
must always be coded on the same memory page; that is, there
must be no intervening page escapes. (Page format and page escapes are discussed later in the chapter.)
The ARG pseudo-op is used only in conjunction with CALL
and consists of the symbol ARG followed by one of the parameters (referred to as arguments in the subroutine) to be passed.
One ARG statement must be coded for each parameter.
In the previous FORTRAN example, the main program. (or it
may have been a subroutine) called a subroutine named TWO, and
supplied one argument:

CALL 1,TWO
ARG IPARM

SABR actually assembles the above instructions as follows ( the
user may wish to consult the section concerning the Loader Relocation Codes) :
0200

0000

0206
0207
0210
0211

4033
0103 06
6201 05
0200 01

IPARM,

BLOCK 1

CALL 1,TWO
ARG IPARM

END

4-26

ENTRY and RETRN
In the subroutine, the ENTRY statement must occur before the
name of the entry point appears as a symbolic address label. The
actual entry location must be a two-word reserved space so that. __
both the return address and field can be saved when the routine
is called. Execution of the subroutine begins at the first location
following the two-word ENTRY block. For example, the TWO
subroutine mentioned in the previous example would begin as follows:

0200
0201

000.0
0000

0227
0230

4040
0001 06

HJO ..

ENTRY TwO
BLOCK 2

RETRN TwO
END

When a subroutine is referenced in a CALL statement, the
Run-Time Linkage Routine LINK executes the transfer to the subroutine. It assumes that the entry point to the routine is a twoword block. Into the first word of this block it places a CnF instruction which specifies the field of the calling program. In the
second word it places the address from which the CALL occurred.
(This is analogous to the operation of the JMS instruction.) In
the previous example, if the MAIN program had been in field 0,
a 6201 would have been deposited in the location at TWO; and a
0210 at TWO #.
The RETRN statement allows the user to return to the calling
program from the subroutine. The name of the subroutine peing
returned from must be specified in the RETRN statement so that
the Return Linkage Routine can determine the action required,
and also because a subroutine may have differently named ENTRY'
points. (This is analagous to the operation of a JMP I instruction.)
When a subroutine is entered, the second word of the entry name
block contains the address of the argument or next instruction
immediately following the subroutine call in the calling program,
and it is to this address that control returns.
4-27

Example
A user wishes to write ~ long main program, MAIN 2, which
uses two major subroutines, 51 and 52. 51 requires two arguments
and 52 one argument. The user writes MAIN, 51, .and 52 as three
separate programs in the following manner:
MAIN,

ENTRY MAIN
CLA

/START OF MAIN

CALL 2,S1
ARG X
ARG Y
CALL 1,S2
ARG Z
END
,-

ENTRY S1
BLOCK 2
RETRN S1
END

S2,

ENTRY S2
BLOCK 2

RETRN S2
END

S 1 could also contain calls to 52, or 52 calls to 51. Each of these
programs is independently assembled with 5ABR and loaded with
the Linking Loader. During the loading process, all of the proper
addresses will be saved in tables so that when the user begins
execution of MAIN, the Run-Time Linkage Routines .{see 5ABR
2

A useful procedure in SABR programming is to provide an ENTRY
point named MAIN in the main program at the address where execution
is to begin. This assures that the starting address of the program will
appear in the Linking Loader's symbol print-out where it may be easily
referenced. If using OS; 8, execution will begin at this address automatically, eliminating the need to specify a 5-digit starting address.

4-28

Operating Characteristics), -which were automatically loaded, will
be able to execute the proper reference. Thus, MAIN will be able
to fully use SI and S2 and be able to pass data to and receive it
from them.
Passing Subroutine Arguments

DUMMY
A DUMMY pseudo-op is used in SABR to define a two word
block which contains an argument address. Indirect instructions
are used to pass arguments to and from subroutines through these
DUMMY variables. If a DUMMY variable is referenced indirectly,
it causes a CALL to the DUMMY Variable Run-Time Linkage
Routine ( see Run-Time Linkage Routines) which assumes that
the DUMMY variable is a two-word reserved space where the
first word is a 62Nl (CDF N), with N representing the field of
the address to be referenced, and that the second word contains a
12-bit address.'
AS'" an example, consider the FORTRAN subroutine TWO
shown earlier. This could be written in SABR as follows (the user
may wish to refer to the section concerning the Subprogram
Library) :
CALL TYJO

ICALLED BY:

ENTRY 1\VO

0200
0201
0202
0203
0204
0205
0206
0207
0210
0211
0212
021,3
0214
0215
0216
0217
0220

0000
0000
0000
0000
4067
0202 01
1407
2203
3200
4067
0202 01
1407
2203
3201
4067
0200-01
1407

IARG ..

DUMMY IARG
BLOCK 2

TWO ..

BLOCK 2
' TAD

IDEFINE THE
IENTRY PT. USED
ITO PICK UP ARG.

lEN TRY POINT

TYJO

INC TYJO#
DCA IARG
TAD I TWO

INC TWO#
DCA IARG#
TAD I IARG

4-29

(IARG)

IGET ARG ADDRESS

IGET ARGUMENT

0221
0222
0223
0224
0225
0226

4067
0200 01
1407
4067
0200 01
3407

0227
0230

4040
0001 06

TAD I IARG

IINTO AC
IADD
IT AGAIN
,

DCA I IARG

IRETURN ARG. TO
ICALLING PROGRAM

RETRN TWO
END

A second example may be one in which a user has written a
FORTRAN program which contains a call to a SABR subroutine
ADD:

212'

A=2
N=3
CALL ADDCA,N,C)
WRITE Cl,2eJ)C
FORMAT C' THE SUM IS',F6.1)
STOP
END

The FORTRAt"'1 program is compiled and the resulting 5.A.BR
code translates the subroutine call as follows:
0223 412'33
12'224 0305
13225 62131
12'226 12'21312'
13227 6212'1
132312' 12'212'3
13231 6201
12'232 ·12'204

CALL 3,ADD
136
135
12'1
12'5
12'1
12'5
12'1

ARG A
ARG N
ARG C

The CALL statement defines 3 parameters-A, N, and C, and the .
subroutine name ADD. The subroutine itself would appear as
follows (the DUMMY variables X, K, and Z.facilitate the passing
of the arguments to and from the subroutine):
4-30

/CALLED BY:
ENTRY
DUMMY
DUMMY
'DUMMY
X...
BLOCK

0200
0201
0'202
0203
0204
0205
0206
0207
0'210
0211
0212
0213
0214
0215
0216
0217
0220
0221
0222
0223
0224
0225
0226
0227
0230
fJ231
0232
0233
0234

0000
0000
0000
0000
1300,0
0000
0200
0000
0000
0000
0000
1206
3207
1377
3210
4067
0211
1407
2212
6201
3607
2207
2210
5217
4067
0202
1407
4033
0002

0235
0236
0237
0240,
0241
0242
0243
0244
0245
0246
0377

4033
0103 06
6201 05
0200 01
4033
0104 06
6201 05
0204 01
4040
0001 '06
7772·

CALL ADD (X ... K... Z)
ADD
X
K
Z
2

K...

BLOCK 2

Z ...

BLOCK 2

XPNT ...
PNTR ...
CNTR ...
ADD ...

X
0
0
BLOCK 2

Al ...

TAD
DCA
TAD
DCA
TAD

/ENTRY POINT '

XPNT
PNTR
(-6
CNTR
I ADD

01
05

INC ADD'
DCA I PNTR
INC
ISZ
JMP
TAD

PNTR
CNTR
A1
I K

/GET 2ND ARG

01
CALL 0 ... FLOT

/CONVERT TO

CALL l ... IFAD

/FLOATING PT.
/ADD 1ST ARG

ARG X
CALL 1 ... 1STO
ARG Z,
RETRN ADD
END

4-31

/RETURN RESULT

The COMMN pseudo-op may be used to specify variables as
externals so that they may be referenced by any program. This
pseudo-op has been explained under Symbol Definition; an example of its usage is included here.
0200

0200
0201
0202
0203
0204
0205
0206
0207
0210
0211
0212
0213
0214
0215
0216
0217

0000
0000
4033
0102
6211
0200
4033
0103
6211
0200
4033
0104
6211
0200
4040
0001

C..

CSQR ..

COMMN 3
. ENTRY CSQR
BLOCK 2
CALL l .. FAD

/RESERVES COMMON
/STORAGE
/DEFINES ENTRY PT.
/ACTUAL ENTRY POINT
/GET THE ARGUMENT

06
ARG C
CALL l .. FMP

/MUL T IPLY IT

06
ARG C
CALL 1 .. STO

/REPLACE WITH RESULT

06
ARG C
RETRN CSQR

/RETURN TO CALLING

06
/PROGRAM
END

This subroutine computes the square of a variable C. C resides
in field 1 in common storage where it can be referenced by any
calling program through argument passing. The above is equivalent
to the FORTRAN subroutine:
SUBROUTINE CSQR
COMMON C

c=c*c
RETURN
END

SABR OPERATING CHARACTERISTICS
Page·by·Page Assembly
SABR assembles page-by-page rather than one instruction at a
time. To accomplish this it builds· various tables as instructions
are read. When a full page of instructions has been collected
(counting literals, off-page pointers and multiple word instructions) the page is assembled and punched. Several pseudo-operators are available to control page assembly.

4-32

PAGE FORMAT
A normal assembled page of code is formatted as below:

X 000
ASSEMBLED
INSTRUCTIONS

JUMP TO
PAGE ESCAPE
LITERALS
AND
OFF-PAGE
POINTERS

X377

PAGE
ESCAPE

Literals and off-page pointers are intermingled in the table at
the end of the page.
..
PAGE ESCAPES
SABR is normally in automatic paging mode: it connects each
assembled core page to the next by an appropriate jump. This is
called a page escape. For the last page of code, SABR leaves the
Automatic Paging Mode and issues no page escape. The LAP
(Leave Automatic Paging) pseudo-operator turns off the automatic paging mode, EAP (Enter Automatic Paging) turns it back
on if it has been turned off.
Two types of page escape may be generated depending on
whether or not the last instruction is a skip. If the last instruction
is not a skip, the page escape is as follows:
last instruction (non-skip)
5377 (JMP to x177)
literals
and
off-page
pointersxI77/NOP
4-33

If the last instruction on the page is a skip type, the page escape
takes four words, as follows:

last instruction (a skip)
5376 (JMP to xI76)
5377 (JMP to xI77)
literals
etc.
xl 76jSKP
xI77jSKP

Multiple Word Instructions
Certain instructions in the source program reqUIre SABR to
assemble more than one machine language instruction (e.g., offpage indirect references and indirect references where a data field
re-setting may be required). In the listing, the source instruction
wiIl appear beside the first of the assembled binary words.
A difficulty arises when a multiple word instruction follows a
skip instruction. The user need be aware that extra instructions
are automatically assembled to enable the skip to be effected correctly.

Run-Time Linkage Routines
These routines are loaded by the Linking Loader and perform
their tasks automatically when certain pseudo-ops or coding sequences are encountered in the user program. The user needs
knowledge of them only to better understand the program listing.
(The user may wish to refer to the section entitled Loader Relocation Codes.)
There are seven linkage routines:
1.
2.
3.
4.

Change data field to current and skip
Change data field to 1 (common) and skip
Off-page indirect reference linkage
Off-bank (common) indirect reference
linkage
5. Dummy variable indirect reference linkage
6. Subroutine call linkage
-7. Subroutine return linkage
4-34

CDFSKP
CDZSKP
OPISUB
OBISUB
DUMSUB
LINK

RTN

The individuallinkage.routines function as fol}k)ws:.;.
1.. CDFSKP is called- when a direct off-page- memory refer-

encefollows a skip-type instruction requiring the data field to be
,reset to the current field. _
Program

szA
DCA LOC

Assembled
Code

Meaning

7440
4045
7410
3776

call CDFSKP
SKP in case AC = 0 at .-2
execute the DCA via a
pointer near the end of the·
page.

2. CDZSKP is called when a direct memory reference is made to a location in common (which is. always in Field 1). Theaction of CDZSKP is the same as that of CDFSKP except that it
always executes a CDF 10 instead of a CDF current (see Loader
Relocation Codes).
Program
SZA
DCA CLOC

Assembled
Code

Meaning

7440
4051
7410
3776

call CDZSKP
SKP in case AC = 0 at .-2
exe~tite the DCA via a
pointer near the· end of. the
page.

3. OPISUB is called when there is an indirect reference to an
off-page location.
Program
DCAIPTR

Assembled
Code

Meaning

4062
0300 01
3407

call OPISUB
relative address of PTR
execute the DCA I via 0007

4. OBISUB is called when there is an indirect reference to a
loc ation in common storage. In such a case it is assumed that the
4-35

location in common which is being indirectly referenced points to
some location that is also in common.
Program
DCAICPTR

Assembled
Code

Meaning

4055
1000
3407

call OBISUB
address of CPTR in Field 1
execute the DCA I via 0007

5. DUMSUB is called when there is an indirect reference to
a DUMMY variable. In such a case, DUMSUB assumes that the
DUMMY variable is a two-word vector in which the first word is
a 62N 1, where N. th,e field of the address to be referenced, and
the second word is the actual address to be referenced.
Program
DCA I DMVR

Assembled
Code

Meaning

4067
0300 01
3407

call DUMSUB
relative address of DMVR .
execute DCA I via pointer
in location 0007

6. LINK is called to execute the linkage required by a CALL
statement in the user's program. When a CALL statement is used,
it is assumed that the entry point of the subprogram is named in
the CALL and that this ehtry point is a two-bit word, free block followed by the executable code of the subprogram. LINK leaves the .
return address for the· CALL in these two words in the same format
as a DUMMY variable.
Program
CALL 2, SUBR
ARGX
ARGC

Assembled
Code

Meaning
call LINK
code word
X resides in field M
relative address of X
C is in common
absolute address of C

4033
0205 06
62Ml
0300 01
6211
1007

7. R TN is called to execute the linkage by a RETRN statement in the user's program.
4-36

Assembled
Code

Program

RETRN SUBR

Meaning
call RTN
number of the subprogram
being returned from (SUBR)

4040
0005 06

Skip Instructions
In page escapes and multiple word instructions, skip-type instructions must be distinguished from non-skipping instructions.
For this reason both ISZ and INC are included in the permanent
symbol table. ISZ is considered to be a skip instruction and INC
is not. INC should be used to conserve space when the programmer desires to increment a memory word without the possibility
of a skip.
The first example below shows the code which is assembled for
an indirect reference to an off-page location following an INC instruction. The second example shows the same code following an
ISZ instruction.
Example 1:
INC POINTR
TAD I LOC2

0220 ' 2376
0221
4062
0222 0520 01
0223 1407

10FF PAGE IND IRECT EXECUTION

Example 2:
ISZ COUNTR
TAD I LOC2

0220
0221
0222
0223
0224
0225

2376
7410
5226
4062
0520 01
1407

ISKIP TO EXECUTION
I JUMP OVER EXECUTION
10FF PAGE INDIRECT EXECUTION

A special pseudo-operator, SKPDF, must be used to define skip
instructions used in sot}rce programs but not included in the permanent symbol table.·For example:
SKPDF DTSF 6771

4-37

Program Addresses
Since each assembly is relocatable, the addresses specified by
SABR always begin at 0200, and all other addresses are relative
to this address. At loading time, the Linking Loader will properly
adjust all addresses. For example, if 0200 and 1000 are the relative
addresses of A and B, respectively, and if A is loaded at 2000,
then B will be loaded at 2000 + (1000-0200) or 2600.
All programs to be assembled by SABR must be arranged to fit
into one field of memory, not counting page 0 of the field, or the
top page (7600 - 7777). If a program is too large to fit into one
field, it should be split into several subprograms.
Explicit COF or CIF instructions are not needed by SABR programs because of the availability of external subroutine calling and
common storage. Explicit COF or CIF instructions cannot be assembled properly.
The Symbol Table
Entries in the symbol table are variable in length. A one or twocharacter symbol requires three symbol table words. A three- or
four-character symbol requires four words, and a five- or sixcharacter symbol, five words. Thus, for long programs ii may be
to the user's advantage to use short symbols whenever possible.
The symbol table,not counting permanent symbols, contains
2644 10 words of storage. However, this space must be shared
when there are unresolved forward and external references temporarily storeq. as two-W9rd entries.
If we may assume that a program being assembled never has
more than 10010 of these unresolved references at anyone time,
this leaves 246410 words of storage for symbols. Using an average
of four words per symbol, this allows· room for 616 10 symbols.
The OS/8 version of SABR has a smaller space for symbol
tables, leaving 1364 10 words of storage, or 162010 if used as the
second pass of FORTRAN II ..
Symbol table overflow is a fatal condition which generates the
error message S.

SYMBOL TABLE FLAGS
Symbols are listed in alphabetic order at the end of the assembly
pass 1 with their relative addresses beside them. The following
flags are. added to denote special types of symbols:
4-38

ABS

The address referenced by this symbol is absolute.

COM

The address is in common.

The symbol is an operator..

EXT

The symbol is an external one and mayor may not
be defined within this program. If not defined, there
is no difficulty; it is defined in another program.

UNDF

The symbol is not an external symbol and has not
been defined in the program. This is a programmer
error. No earlier diagnostic can ];Je given because it
is-not known that the symbol is undefined until the
end of pass 1. A location is reserved for the unde_fined symbol, but nothing is placed in it.

THE SUBPROGRAM LmRARY
The Library is a set of subprograms which may be CALLed by
any FORTRAN/SABR program. These subprograms are automatically loaded with the OS/8 FORTRAN/SABR.system; in the
paper tape system they are provided' on two relocatable binary
paper tapes with part 1 containing those subprograms used by
almost every FORTRAN/SABR program. This allows the user
to load only those routines which his program makes use of, thus
conserving symbol space.
Many of the subprograms reference the Floating-Point Accumulator located at ACH, ACM, ACL (20,21,22 of field 1). The
OS/8 Subprogram Library is summarized in the FORTRAN II
. chapter. The organization of the library programs, as they are provided in the paper tape system, is described in the following pages.
Part 1. "IOH"
"FLOAT"

contains IOH, READ, WRITE·
contains FAD, FSB, FMP, FDV, STO,
FLOT, FLOAT, FIX, IFIX,
IFAD, ISTO, CHS, CLEAR
"INTEGER" contains lREM, ABS, lABS, DIV,
MPY,IRDSW
"UTILITY" contains TTYIN, TTYOUT, HSIN,
HSOUT, OPEN, CKIO
"ERROR"
contains SETERR, CLRERR, ERROR
4-39

Part 2. "Sl.JBSC"
"POWERS"
"SQRT"
"TRIG"
"ATAN"

contains SUBSC
contains IIPOW, IFPOW, FIPOW,
FFPOW, EXP, ALOG
contains SQRT
contains .SIN, COS, TAN
contains ATAN

Input/ Output
READ is called to initialize the I/O handler before reading data.
WRITE is called to initialize the I/O handler before writing data.
IOH is called for each item to be read or written. IOH must also
be called with a zero argument to terminate an input-output sequence.
All of the programs require that the Floating-Point Accumulator be set to zero before they are called.
CALL
ARG
ARG

2, READ

(n
fa

/n=DEVICE NUMBER
/fa=ADDR OF FORMAT

•••
CALL
ARG

1, IOH

data 1

CALL
ARG

1,IOH
data 2

/data l=ADDR OF HIGH
IORDER \VORD OF
/FLOATING POINT
/NUMBER

•••
•••
CALL
ARG

/TERMINATES READ

1, IOH
-0

•••
CALL
ARG·

2, WRITE

ARG

jINITIALIZES WRITE

4-40

The following device numbers are currently implemented:
1
2
3
4

(Teletype keyboard/printer)
(High-speed reader/punch)
(Card reader/line printer)
(Assignable device)

Floating Point Arithmetic

FAD is called to add the argument to the Floating-Point Accumulator.
CALL
ARG

1, FAD
add res

FSB is called to subtract the argument from the Floating-Point
Accumulator.
CALL·
ARG

1, FSB
addres

FMP is' called to multiply the Floating-Point Accumulator by
the argument.
CALL
ARG

1, FMP
addres
..

FDV is called to divide the Floating-Point Accumulator by the
argument.
•
CALL
ARG

1, FDV
addres

CHS is called to change the sign of the Floating-Point Accumulator.
CALL

0, CHS

All of the above programs leave the result in the Floating-Point
Accumulator. The address of the high-order word of-the fioatingpoint number is "addres".
STO is called to store the contents of the Floating-Point

4-41

Accumulator in the'argument'address . The floating-perint accumu-.
lator is cleared.
CALL
ARG

1, STO
storag

/storag=ADDRESS WHERE
/RESULT IS TO BE PUT

IFAD is called to execute an indirect floating-point add to the
Floating-Point Accumulator.
CALL
ARG

1, IFAD
ptr
/ptr=2 WORD POINTER
/TO HIGH ORDER
/ADDRESS OF FLOATING
/POINT ARGUMENT

ISTO is called to execute an indirect floating-point- store.
CALL
ARG

1, ISTO
ptr

CLEAR is called to clear the Floating-Point Accumulator. The
AC is unchanged.
CALL
"pr.L.. OAT auu.
" .... ,;1
~

0, CLEAR
"PT
nT al
n .. ". ".;"11"r/ 4-"
~ .L..'-J ~
\..- \..-a,l1\..-u. tV

c",-ue""
..l-.~
VlI" I l Ull;;

: .... 4-e~e- ~~- ~:-e...t
111t 2:; 1 ,",Vl1laUI U

in the AC (processor accumulator) to a floating-point number and
store it in the Floating-Point Accumulator.
CALL

0, FLOT

CALL 1, FLOAT
ARG addr

IFIX and FIX are called to convert the number in the FloatingPoint Accumulator to a 12-bit signed integer and leave the result
in the AC.
CALL

0, FIX

CALL 1, IFIX
ARG addr

ABS leaves the absolute value of the floating-point number at
"addr" in the Floating-Point Accumulator.
CALL
ARG

1, ABS
addr
4-42

Integer Arithmetic
MPYis called to multiply the integer contained in the AC by
the integer contained in "addr." The result is left
in the. AC.
.
CALL
ARG

1, MPY
addr

DIV is called to divide the integer contained in the AC by the
integer contained in "addr." The result is left in the AC.
CALL
ARG

1, DIV
addr

IREM leaves the remainder from the last executed integer divide
in the AC.
CALL
ARG

1, IREM,

(The argument is ignored.)
lABS leaves the absolute value of the integer contained
"addr" in the AC.
CALL
ARG

III

1, lABS
addr

IRDSW reads. the value set in the console ·switch register into
the AC.
CALL

0, IRDSW

Subscripting .
SUBSC is called to compute the address of a subscripted. variable, and can be used for doubly or singly subscripted arrays. On
entry, the AC should be negative for floating-point variables-any
negative 1}umber for singly subscripted variables, and I's comple- .
ment of the first dimension for doubly subscripted variables. For
doubly subscripted integer variables, the AC must be the first
dimension.
The general calling sequence for SUBSC is as follows:

4-43

*TAD (M

lIST DIMENSION (USED ONLY

IIF 2 DIMENSIONS)
IUSED ONLY IF ARRAY IS
IFLOATING POINT
2,SUBSC]/SINGLE SUBSCRIPT

*CMA
CALL [

3,SUBSC
*ARG J
ARG I
ARG BASE
LOCA

IDOUBLE SUBSCRIPT
12ND DIMENSION

lIST DIMENSION
IBASE ADDRESS OF ARRAY
IADDRESS OF TWO WORD DUMMY

IADDRESS, LOCATION

* Optional Statements.
F,?r example, to load the I,Jth element of a floating-point array
whose dimensions are 5 by 7:
TAD (5

CMA

IDIMENSIONS ARE 5 BY 7

CALL 3,SUBSC
ARG J
ARG I
ARG ARRAY
LOC
CALL 1,IFAD
ARG LOC

IADDRESS OF 2ND SUBSCRIPT
IADDRESS OF 1ST SUBSCRIPT
IBASE ADDRESS OF ARRAY
IMUST BE A DUMMY VARIABLE

Functions
SQRT leaves the square root of the floating-point number at
"addr" in the Floating-Point Accumulator.
CALL
ARG

1, SQRT
addr

SIN, COS, TAN leave the specified function of the floating-point
argument at "addr" in the Floating-Point Accumulator.
,CALL
ARG

1, SIN
addr

ATAN leaves the arctangent of the floating-point number at
•
"addr" in the Floating-Point Accumulator.
CALL
ARG

1, ATAN
addr
4-44

ALOG leaves the natural logarithm of the floating-point number at "addr" in the Floating-Point Accumulator.
CALL
ARG

1, ALOG
addr

EXP raises "e" to the power specified by the floating-point number at "addr" and leaves the result in the floating-point accumulator.
CALL
ARG

1, EXP
addr

All of these subprograms require that the floating-point accumulator be set to zero before they are called.
The POWER routines (IIPOW, IFPOW, FIPOW, FFPOW)
are called by FORTRAN to implement exponentiation. The first
operand is in the AC (floating-point or processor depending on
mode), and the address of the second is an argument. The address
of the result is in the appropriate AC upon return.

FUNCTION
NAME
II POW
IFPOW
FIPOW
FFPOW

CALL

ARG

MODE OF
OPERAND 1 •
(BASE)
"

INTEGE'R
INTEGER
FLOATING POINT
.FLOATING POI NT

2, FFPOW
addr 2

MODE OF
OPERAND 2
(EXPONENT)
INTEGER
FLOATING POINT
INTEGER
FLOATING POINT

MODE OF
RESULT
INTEGER
FLOATING POINT
FLOATING POINT
FLOATING POINT

. / ADDRESS OF OPERAND 2

Utility Routines
, OPEN is called atthe beginning of every FORTRAN program
to st,art the high-speed reader/puncli and teleprinter, and to initialize the I/O routines for device code 4 if using the OS/8 FOR-.
TRANjSABR system. The form is:

CALL 0, OPEN

4-45

When an error is. encountered in a program, the ERROR routine is called. The program passes to the ERROR routine the
address of the error message to be printed: The format of the
error message is 4 characters itr stripped ASCII and packed into
2 words:
2343
2344
2345
2346

0102
0304
0000
0000

XYZ,

ABC,
•

ENTRY ABC
0102;0304
BLOCK 2

CALL 1,ERROR
ARG XYZ

When control passes to the ERROR routine, the parameters
passed are picked up. In the case above, the parameters are as
follows:
62Nl
2343

ARG XYZ

where N is the field that'XYZ is in, and 2343 is the address of
XYZ. The ERROR routine then prints the message at location
2343 plus a 5-digit address which is 2 greater than 2343.
ABCD ERROR AT N2345

Since XYZ is 2 locations before ABC, the address printed will be
the address of ABC.
The error message is usually placed just before the entry point
of the routine in which the error was detected-"thus the address
printed by ERROR will be the, address of the entry point. This
provides a convenience to the programmer since the entry point
will appear in the Loader Map.
CKIO is a subroutine which waits for the TTY flag to be set. It
is called by the OS/8 EXIT subroutine to eliminate the possibility
of a garbled TTY output. It may be used in FORTRAN for possible expansion with interrupts, and is of the form:
4-46

CALL

(2),

C K 10

The following subroutines-IOPEN, OOPEN, OCLOSE,
CHAIN, EXIT, and GENIO-are used by the OS/8 FORTRAN/
SABR Operating System for device independent I/O and chaining.
DECtape I/O Routines
RTAPE 'and WTAPE (read and write tape) are the DECtape
read and write subprograms for the .8K FORTRAN and 8K SABR
systems. The subprograms are furnished on one relocatable binary,coded paper tape which must be loaded into field 0 by the 8K
Linking Loader, where they occupy one page of core.
RTAPE and WTAPE allow the 'user to read and write any
amount of core-image data onto DECtape in absolute, non-mestructured data blocks. Many such data blocks may be stored on a
,single tape, and a block may be from 1 to 4096 words in length.
RT APE and WTAPE are subprograms which may be called
with standard, explicit CALL statements in any 8K FORTRAN or
SABR program. Each subprogram requires four arguments separated by commas. The arguments' are the same for both subpro,./ granis and are formatted in the same manner. They specify the
following:
1. DECtape unit number (from 0 to 7)
2. Number of the DECtape block at which transfer is to
start. The user may direct the DECtape service routine to
begin searching for the specified block in the forward direction rather than the usual backward direction by making
this argument the two's complement of the block number.
3. Number of words to be transferred (1~N~4096)
4. Core address at which the transfer is to start..

.DECtape I/O Routines for the FORTRAN II system are explained in Chapter 7. In 8K SABR,' the CALL statements to
RTAPE and WTAPE are written in the following format (arguments·may be. either octal or decimal numbers):
4-47

CALL 4,WTAPE
ARG (6
ARG (200
ARG (604
ARG LOCB

/WOULD BE SAME FOR RTAPE
/DATA UNIT NUMBER
/STARTING BLOCK NUMBER
/IN OCTAL
/WORDS TO BE TRANSFERRED
/IN OCTAL
/CORE ADDRESS, START OF
/TRANSFER

In these examples, LOCA and LOCB mayor may not be in common.
As a typical example of the use of R TAPE and WTAPE, assume that the user wants to store the four arrays A, B, C, and D
on a tape with word lengths of 2000,400, 400, and 20 respectively.
Since PDP-8 DECtape is formatted with 1474 blocks (numbered
0-2701 octal) of 129 words each (fora total of 190,146 words),
A, B, C, and D will require 16, 4, 4, and 1 blocks respectively.
(The block numbers used by RTAPE and WTAPE should not be
confused with the record numbers used by OS/8. A OS/8 record
is 256 words-roughly twice the size of a DECtape block.)
Each array must be stored beginning at the start of some DECtape block. The user may write these arrays on tape as follows:
CALL
CALL
CALL
CALL

WTAPE
WTAPE
WTAPE
WTAPE

(0,1,2000,A)
(0,17,400,B)
(0,21,400,C)
(0,25,20,D)

The user may also read or write a large array in sections by
specifying only one DECtape block (129 words) at a time. For
example, B could be read back into core as follows:
CALL RTAPE (0,17,258,B(1»
CALL RTAPE (0,19,129,B(259»
CALL RTAPE (0,20,13,B(388»

As shown above, it is possible to read or write less than 129
words by starting at the beginning of a DECtape block. It is impossible, however, to read or write starting in the middle· of a
block. For example, the last 10 words of a DECtape block may
not be read without reading the first 119 words as well.
A DECtape read or write is normally initiated with a backward
4-48

search for the desired block number.. To save searching time, the
user may request RT APE or WTAPE to start the block number
search. in the forward direction. This is done by spe.cifying the
negative of the block number. This should be used only if the
number of the next block to be referenced is at least ten block
numbers. greater than the last block number used. For example,
if the user has just read array A and now wants array D, he may
write:
CALL RTAPE (0,1,2000,A)
CALL RTAPE C0,-27,20,D)

THE BINARY OUTPUT TAPE
SABR outputs each machine instruction on binary output tape
as a 16-bit word contained in two 8-bit frames of paper tape. The
first fSlur bits contain the relocation code used by the Linking
Loader to determine how to load the data word. The last 12 bits
contain the data word itself.

. .

...

•

RELOCATION
CODE
-

HIGH ORDER OF
DATA WORD

. .

LOW ORDER OF DATA WORD.

FIRST FRAME
SECOND FRAME

The assembled binary tape is preceded and followed by leader/
trailer code (code 200). The checksum is contained in the last two
frames of tape before the trailer code. It appears as a normal 16-bit
wore., as shown. below.

.
1

HIGH ORDER OF
CHECKSUM

LOW ORDER OF DATA WORD

FIRST FRAME
SECOND FRAME

All assembled programs have a relative origin of 0200.
Loader Relocation Codes
The four-bit relocation codes issued by SABR for use by the
Linking Loader' are explained below. The codes are given in octal.
00 'Absolute
Load the data word at the current
loading address. No change is required.
4-49

0205

5277

~~P

LaC

I~HERE

LaC IS

IAT 0(7;77 (OF
ICURREl\lT PAGE)

0376

Simple
Relocation

0520 01

Add the relocation constant to the
word before loading it. (The relocation constant is 200 less than the
actual address where the first word
of the program is loaded.) Items
with this code are always pr9gram
addresses.

LOC2

In the above example, LOC2 ,is at
relative address 0520. If the first
word of the program (relative ad-dress 0200) is loaded at 1000,
then the actual address of A is
1176 and location 1176 will be
loaded with the value 1320, which
will be the actual address of LOC2
when loaded.
03

External
Symbol
Definition *

The data word is the relative address of an entry point. Before entering this definition in the Linkage
Tables so that the symbol may be
referenced by other programs at
run-time, the Linking Loader must
add the relocation constant to it.
The six frames of paper tape following the two-frame definition are
the stripped ASCII code for the
symbol.

Does not appear in assembly listings.

4-50

IADDRESS.

ADDRESS lOW ORDER
L

0
C

2
SPACE
SPACE

Re-origin*

Change the current loading address
to the value specified by the data
word plus the relocation constant.

CDF
Current

The data word is always a 6201
(CDF) instruction which has been
generated automatically by SABR.
The code 05 indicates to the Linking Loader that the number of the
field currently being loaded into
must be inserted in bits 6-8 before
loading.

0300
0301

6201 05
1776

,0376

0520 01

TAD LOC2
/WHERE LOC2 IS
/OFF PAGE SO
/THAT THE TAD
/INSTR. MUST BE
/INDIRECT

If the program containing this code

is being loaded into field 4, relative
location 0300 will be loaded with
6241.
Such an instruction is referred to
in this document as CDF Current.
It is generated automatically by

Does not appear in assembly listings.

4-51

SABR when a direct reference instruction must be assembled as· an
indirect, and there. is the possibility
that the current data field setting is
different from the field where the
indirect reference occurs.
06

Subroutine
Linkage
Code

The data word is a special constant enabling the Linking Loader
to perform the necessary linking
for an external subroutine call.
(c.f., CALL Pseudo-op). The
structure of the data word is shown
below.
BITS 6-11

BITS 0-5

LOCAL PROGRAM
NUMBER ASSIGNED
TO THE EXTERNAL
SUBROUTINE
BEING CALLED

NUMBER OF
ARGUMENTS
FOLLOWING
THE CALL

Before the 12-bit, two-part code
word is loaded into memory, a
global external number will be substituted for the local external symbol number in the right half of the
data word.
0200
0201

4033
0307 06

CALL

3~SUB

ARG X
ARG Y
ARG Z

Here, SUB has been assigned the
local number 06 during assembly.
At loading time this number will
be changed to the global number
(for example, 23) which is assigned to SUB. In this example,
0323 would actually be loaded at
relative address 0201.
4-52

Leader/Trailer*
and
Checksum

This code represents normalleader/trailer. The checksum is
contained in the last two frames
of paper tape preceding the trailer
code.

High Common*

The data word is the highest location in Field 1 assigned to common storage by the program. This
item will occur exactly once in
every binary tape and it must be
the first word after the leader. If
no common storage has been allocated in the program, the data
word will be 0177.

Transfer*
Vector

Signifies that reference to an external symbol 'occurs in the assembled program. The 12-bit data
word is meaningless. The next s~x
- frames contain the ASCII code for
the symbol.
The Linking Loader uses this definition to create a transfer table,
whereby local external symbol
numbers assigned during assembly
of this particular _program can be
changed to the global- external
symbol number when several programs are being loaded.

SAMPLE ASSEMBLY LISTINGS
The following examples are offered to illustrate many of the
features and formats of the SABR Assembler.

When a multiple word instruction occurs, th~ actual instruction
line is typed beside the first instruction.

Does not appear in assembly listings.

4-53

0650
0651
0652
0653
0654

62131 05
5774
71136
70136
7006

LOC2,

JMP NAME

/OFF PAGE

CLL RTL,;RTL,;RTL

When there is an erroneous instruction, the error flag appears
in the address field. The instruction is not assembled.
0700

CLA
CLL SKP
HLT

7200
I

0701

7402

The page escape and literal and off-page pointer table are typed
with nothing except the correct address, value and loader code.
0770
0771
0773
0774
0775
0776

7006
75130
5376
5377
0200 01
0020
7410

0777

7410

07'"Z2

N3,

RTL
SMA

/SKP TO 1ST LO~.
/NEXT PAGE (AC IS
/NOT MINUS)
/SKP TO 2ND LOC.INEXT PAGE (Ae IS
It-lINUS)
I

Locations 0772, 0773, 0776 and 0777 make up the page escape
since the last instruction is a skip instmction (SMA). Refer to the
section concerning Page Escapes.
The following program has been assembled and listed. It cannot
be run without first debugging and editing it.
During "the first pass, SABR outputs the binary tape and prints
error messages as they occur. In this case, none of the errors are
fatal, and assembly continues. The symbol table is printed, and
undefined symbols, external symbols, or any other special types of
symbols which cannot be determined until the end of the pass
. are flagged in the symbol table.
The optional second pass of the Assembler produces a listing.
The 4-digit first column contains the octal address, while the
4-54

second column contains the octal code for each line of instructions.
Errors are also printed during the listing pass at the line in which
they occur. Meanings of error codes are described· later in the
chapter.
The reader is also referred to Demonstration Program Using
Library Routines.

C AT

PUNCH +12101213

COUNT
DECIMA
LT
MAIN
MESG
ORG
PTAPE
PUNCH
REF
RPT
START
TYPE

12131212
0000UNDF
0264
0000EXT
121243
031213
0201EXT
0274
0177ABS
0267
0205
0000EXT
/PROGRAM TO PUNCH RIM FORMAT PAPER TAPES
612126
612121
121177

1212121121

121121121121

12121211
0202

121121121121
00121121

0203
021214

1377
331212

• '?i21215
12121216
121207
12121121

131213
7132
712112
712112

OPDEF PLS 6026
SKPDF PSF 6021
ABSYM REF 177
ENTRY MAIN
DECIMAL

/DEFINE HI SPEED
/IOTS

LAP
PTAPE~

START~

BLOCK 2

/PUNCH LEADER

/TAPE (21210 CODE)
TAD (-32
/32 LOCATIONS
DCA COUNT
OCTAL
TAD ORG
CLL CML RTR;RTR;RTR

4-55

0211"
0212
0213
0214
0215
0216
0217
0220
0221
0222
0223
0224
0225
02260227

0376
4274
1303
0376
4274
1703
7112
7012
7012
0375
4274
1703
0375
4274
2303

AND
JMS
TAD
AND
JMS
TAD
CLL

(177
PUNCH
ORG
<177
PUNCH
I ORG
RTR;RTR;RTR

AND
JMS
TAD
AND
JMS
INC

PUNCH
I ORG
(77
PUNCH
ORG

0230
0231
0232
0233
0234
0235
0236
0237
0240

2302
5205
4033
0102 06
6201 05
0243 01
4264
7404
3303

ISZ COUNT
JMP START
CALL 1,TYFE
ARG MESG

0241
0242

7402
5774

HLT
JMP MAIN

0243
0244
0245
0246

2401
2005
4020
2516

0247

0310

0250

0504

02!,) 1

!')6L!0

0252
0253
0254
0255
0256
0257
0260
0261
0262
0263

0516
2405
2240
1722
1107
1116
4046
4003
1716
2456

0264

0000

0265
0266
0267
0270
0271
0272
0273

1373
3302
1372
4274
2302
5267
5664

IPUNCH LEADING
IDIGITS OF ADDRESS
IPUNCH SECOND
IDIGITS OF ADD~ESS
INOW PUNCH CONTENTS
10F THAT LOCATION

(77

JMS LT
OSR
DCA ORG

IGET SECOND DIGITS
10F THAT LOCATION

IPOINT TO NEXT
/CORE LOCATION
IDONE YET?
INO
IYES, TYFE MESSAGE

/ENDING 200 CODE
IGET NEW ADDRESS
IFROM SWITCH REGISTER
IPUT I T IN ORG
IPAUSE
/PUNCH NEW TAPE

MESG,

TEXT "TAPE PUNCHED. ENTER ORIGIN & CONT."

LT,

RPT,

OCTAL
TAD (-40
DCA COUNT
TAD (200
JMS PUNCH
ISZ COUNT
JMP RPT

JMP I LT

4-56

132 FRAMES OF

ILEADER/TRAILER
IPUNCH IT
IDONE?
INO
IRETURN

0274
0275
0276

0000
6026
602'1

PUNCH~

0277
0300
0301

4045
7410
5674

0302
0303
0304
0305
0372
0373
0375
0376
0377

0000
7300
4040
0003 06
0200
7740
0077
0177
7746

COUNT ~
ORG~

0
PLS
PSF
JMP • -1
JMP I PUNCH

/PUNCH /WAIT FOR FLAG
/EXIT

0
7300
RETRN PTAPE

END

SABR PROGRAMMING NOTES
Optimizing SABR Code
There are generally two types .of programmers who will use the
SABR Assembler-those who like the convenience of a pageboundary-independent code and need not be concerned with program size, 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 circumvent the cost of non-paged code is to make
use of the LAP (Leave Automatic Paging) pseudo-op and the
PAGE pseudo-op to force paging where needed. This saves 2 to
4 instructions per page by elimination of the page escape. In addition, the fact that the. program must be properly segmented may
save a considerable amount.
Extra core-may be reduced by eliminating the CDP instructions
which SABR inserts. into a program. This is done by using "fake
indirects". Define the following op codes:
4-57

OPDEF
OPDEF
OPDEF
OPDEF

AND I
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
illustrated by an example:
If X is off-page, the sequence:
LABEL,

SZA
DCA X

is assembled by SABR into:
LABEL,

SZA
JMS 45
SKP

DCA I

ex)

or four instructions and one literal.
The sequence:

px..

LABEL,

SZA
DCAl PX

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

0200
0201
0202
0203
0204
0205
0206
0207
0210
0211
0212
0213
0214
0215
0216
0217
0220
0221
0222

0000
0000
0000
0000
0000
4067
0203 o 1
1407
3201
2204
4067
0203 01
1407
3202
2204
4067
0201 01
1407
3200

IARG,
X,

DUMMY X
0
BLOCK 2

SUBR,

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

This is the method the FORTRAN compiler uses, and although
it is standard, it is also the slowest. This code requires 19 words
of core and takes several hundred microseconds to execute.
The fastest way to pick up arguments within a SABR coded
external subroutine is as follows (this takes approximately one
fifth of the time of the previous method and four less locations):
0200
0201
0202
0203
0204
0205

0000
0000
0000
1201
3205
7402

0206
0207
0210
0211
0212
021.3
0214

1602
3214
2202
1602
3200
2202
7402

0215
0216

1600
3200

IARG,
S.UBR,

0
BLOCK 2

Xl,

TAD SUBR
DCA Xl
HLT

X2,

TADI SUBR#
DCA X2
INC SUBR#
TADI. SUBR#
DCA IARG
INC SUBR#
HLT
3ADI IARG
DCA IARG

4-59

/REPLACED
/BY CDF

To pick up multiple arguments, the locations from Xl to X2+ 1
inclusive can be made into a subroutine.

Calling the OS /8 USR and Device Handlers

One important point to remember is that any code which calls
the USR must not reside in locations 10000 to 11777. Tberefore,
any SABR routine which calls the ~SR must be loaded into a field
other than field 1 or above location 2000 in field 1. To call the
USR from SABR use the sequence:

CPAGE N
6212
JMS 7700
REQUEST
ARGUKENTS
ERROR RETURN

IN=7+C# OF ARGUMENTS)
ICIF 10
lOR 200 IF USR IN CORE

IOPTIONAL DEPENDING ON REQUEST
IOPTIONAL DEPENDING ON REQUEST

To call a device handler from SABR use the sequence:

HAND,

CPAGE 12
6202
JMS I HAND
FUNCT
ADDR
BLOCK
ERROR RETURN
SKP
0

110

IF "HAND" IN PAGE 0

ICIF 0
IDO NOT USE JMS I

I"HAND" MUST BE ON SAME PAGE
lAS CALL,

OR IN PAGE 0

SABR ERRORS
In case of error, SABR prints the following codes in the address
field of the instruction line:

4-60

Table 4-3

SABR Error Codes

Error Code

Meaning

Too many or too few ARG statements follow
a call statement.

An illegal character appears on the line.

A device· handler has returned a fatal condition.

/ L or / G option was indicated, but the
LOADER.SV file does not exist on the system
device.

A symbol is multiply defined. Listing of programs with multiple definitions have unmarked
errors.

An illegal syntax has been used, (as one of the
following) :

1.
2.
3.
4.
5.
E

a pseudo-op with improper arguments,
a quote mark with no argument,
a non-terminated text string,
an improper address,
an illegal combination of micro-instructions.

There is no END statement.

Either the symbol table has overflQwed; common storage has been exhausted, more than 64
different user-defined symbols occurred in a
core page, or more than 64 external symbols
have been declared. Could also indicate a system error such as overflowed output file.

No symbol table is being produced, but there
is at least one undefined symbol in the program.

UNDF

Undefined symbol, printed in the symbol table
. listing.

4-61

LIl\TJ(ING LOADER
The Linking Loader is the system program used to load and
link a user's program arid subprograms in any field(s) of memory.
It can be called automatically to load or load and start a FORTRAN or SABR program, or ip.dependentIy to load or load and
start a relocatable binary file stored on a device. It is capable of
loading programs over itself, and has options which allow the user
to obtain storage map listings of core availability.
The Linking Loader has the capability of searching program
libraries for subroutines which are referenced by the program in
core and to load those subroutines needed. (A library is a collection of relocatable-subroutines-FORTRAN or SABR outputwith a directory at the beginning to facilitate searching.) Any
library can be searched by using the /L option to the Loader, but
the system library, LIBS.RL, is searched automatically just before
the Loader completes the building of a core image of the user's
program. If LIBS.RL is not on the system device, there is no.~uto
matic library search. (The system p~ogram LIBSET is available
to allow the user to build his own subroutine library.)
The Linking Loader is capable of loading any number of user
and library programs into any field of memory. Several programs
are usually loaded into each field. Because of the space reserved
for the Linkage Routines, the available space in field 0 is three
pages smaller than in all other fields.
Any common storage reserved by the programs being loaded is
allocated in field 1 from location 200 upwards. The space reserved
for common storage is subtracted from the available loading area
in field 1. The program reserving the largest amount of common
storage must be loaded first.
The Run-Time Linkage Routines necessary to execute SABR
programs are automatically loaded into the required areas of every
field by the Linking Loader- as part of its initialization. The user
needs to know nothing more about these routines than the particular areas of core they occupy.

Calling and Using the Linking Loader
The user can automatically call the Linking Loader following
assembly of either a SABR program or a SABR-assembled FORTRAN program by use of the /L or /0 options. For details on
4-62

" Loader; see the FORTRAN secautomatic calling of the Linking
tion of this chapter.
'
When the user wishes to call the Linking Loader specifically to
load or load and start a relocatable binary file, he issues the
command:
R LOADER

in response to the dot printed by the Keyboard Monitor. The Com-.
mand Decoder replies by printing an asterisk at the left margin;
the user then indicates input and output files and any desired options. 0 to 1 output files and 1 to 9 input files are possible. Only
one binary program per file is permitted. The assumed extension
for input files is .RL. The output file, "if indicated, is used to hold
a map of the loaded program.
The user has the ability to either specify all options and operations to be performed on one line or to have various operations
performed individually. Where all options are being specified at
one time the line to the Command Decoder contains the complete
instructions for the Linking Loader. If operations are to be done
individually, the user can type a command, enter it with the RETURN key, and that command will be executed, with another
command expected when the first is completed. To indicate the
last command~ the user types an ALT MODE character, or ends
the last command with a /G option tostart the program.
LINKING LOADER OPTIONS
The options to the Linking Loader are as shown in Table 4-4.

Table 4-4

Linking Loader Options

Option

Meaning

A program doing device-independent input is to be loaded.
(This feature costs the user 3 pages of core.)

A program doing device-independent output is to be loaded.
(This feature costs the user 3 pages of core.)

4-63

Table 4·4

Linking Loader Options (Cont.)

Option

Meaning
If both I I and 10 are indicated, 6 pages of core are used

to handle device-independent I/O.
I I and 10, if used, must be given before or on the first

input line specifying files to be loaded. For example:

!.INPUT .. FILES/O$

is acceptable, but

!INPUT
.;tIO FILES

•

is not legal and will generate an error message.

A program doing device-independent I/O requires twopage device handlers at run-time. (This feature costs the
user one additional page if he is doing just input or output,
and two additional pages if he is doing input and output.
If II, 10, and IH are indicated, 8 pages of core are used

to handle device-independent I/O. IH, if used, must be indicated on or before the first line containing II or 10, and
is meaningless without / I or 10 also being specified.
IG

Start the program after processing'the rest of the command
string. Execution starts at the symbol MAIN unless otherwise indicated.

Specifies the starting address of the program if other than
the entry point MAIN; n is an octal number up to 5 digits
long.

Output a map of the loaded programs onto the output file
specified, followed by a count of the free pages in each
field. If no output is specified, the map is put onto the tele..;
printer. The assumed extension for map output file is .MP.
The map is printe4 after the rest of the command line is
processed.

4-64

Table 4-4

Linking Loader Options (Cont.)

Option

Meaning

Similar to I M, but only outputs undefined symbols.

Similar to I M, but only outputs counts of free pages in
each field:

Search through the available fields starting at field n for
space large enough to hold each input file; n is an integer
in the range 0 to 7, inclusive. Only one binary program
can be in each input file. If n is not specified, the Loader
starts looking at field o.

Restart loading process (forget all previously loaded programs). This command is equivalent to restarting the Linking Loader, but is much faster for DECtape systems since
no tape motion is involved.

Load the first input file as a library file (Loader expects a
Library Directory as the first block of the file). All other
input files on the line are ignored.

The Core AvailabiIity option (/P) causes the number of free
pages of memory in every field of memory to be printed in a list
on the teleprinter. For example, if the user has a 16K configuration, a list like the following might be printed:
0002
0010
0030
0036

(number
(number
(number
(number

of
of
of
of

free
free
free
free

pages
pages
pages
pages

in
in
in
in

field
field
field
field

0)
1)
2)
3)

The number of pages initially available in field 0 is 0033 and in
all other fields is 0036.
The Storage Map option (1M), when selected, causes a list of
all program entry points to be printed along with the actual address at which they have been loaded. Entry points of programs
which have been called but which have not been loaded are also
4-65

listed along with U flag for "undefined". Such flagged programs
must. be loaded before execution of the user's programs are possible. The core availability list is automatically appended to the
storage map. A sample is shown below for an .8K machine:

MAIN
READ
WRITE
IOH
ERROR
GENIO
FDV
CLEAR
IFAD
FMP
ISTO
STO
FLOT
FAD
DIV
I REM
FSB
FLOAT
FIX
IFIX
CHS
1Zl1Zl1 1

11Zl21Zl1Zl
IZlIlZl51Zl
1Zl11Zl66
1Zl31Zl31
1Zl1Zl1Zl1Zl1Zl
1Zl1Zl1Zl1Zl1Zl
1Zl4722
1Zl5247
1Zl5131
1Zl4632
1Zl51Zl74
1Zl4447
1Zl5211Zl
1Zl41Zl11Zl
1Zl1Zl1Zl1Zl1Zl
1Zl1Zl1Zl1Zl1Zl
041Zl1Zl1Zl
1Zl5046
1Zl4513
04561
1Zl5231

U
U

0033

EXAMPLES OF I/O COMMAND STRINGS
The following are examples of possible input command strings:

-*PROG .. DTA2:SUBl .. SUB2/G
This string loads DSK: PROG .RL, DT.A2: SUB l.RL,
DTA2:SUB2. RL, loads any necessary library routines requested,
and starts the program at the entry point MAIN. The same process
could have been done as follows:
4-66

Load DSK: PROG.RL ; Get a list of undefined symbols on the teleprinter;

-*PROG
.:!;/U

(Symbols go here)

~DTA2:SUBR1~SUBR2

Load DTA2: SUBRl.RL,SUB2.RL ;

-*LPT:/M<$
.

Put loading map on the line printer, load the binary of any
library routines requested by the program, and exit ($ is
printed by the ALT MODE key);
• SAVE DTA2 FORTPG

Save the, core image on DTA2 as FORTPG.SV;
Start the core image at its starting address (entry point MAIN
in this case) .

-• START
Linking Loader Error Messages
The Linking Loader outputs error messages in the form
ERROR nnnn
where nnnn represents a 4-digit error code. Table 4-5 lists the
meanings of these error codes.
4-67

Table 4-5

Linking Loader Error Messages

Error Code

Meaning

0000

/ I or /0 specified too late.

0001

Symbol table overflow; more than 64 subprogram
names.

0002

Program will not fit into core.

0003

Program with largest common storage area was not
loaded first.

0004

Checksum error in input tape.

0005

Illegal relocation code.

0006

An output error has occurred.

0007

An input error has occurred· (either a physical device
error, or an attempt was made to read from a writeonly device such as LPT: ).

0010

No starting address has been specified and there is
no entry poInt named MAIN.

00 11

An error occurred while the Loader attempted to load
a device handler.

0012

I/O error on system device.

LiBRARY SETUP (LIBSET)
LIBSET, the FORTRAN Library Setup program, creates a
library of subroutines from the relocatable binary output of SABR.
These library files can be quickly and effectively scanned by the
Linking Loader, thus saving a great deal of the time involved in
loading frequently used subroutines. (Refer to the section concerning the Linking Loader for information pertaining to relocatable library files, automatic loading of the LIB8.RL file, and
the /L option. )

Calling and Using LmSET
To call LIB SET from the system device, the user types
R LIBSET

4-68

in response ·to the dot printed by the Keyboard Monitor. The Command Decoder then print~ a.n asterisk at the left margin of the
teleprinter paper and waits to receive a line of input. The general
form of input required to build a library file is:
*DEV:OUTPUT FILE 0
Jump if impossible to fix the
floating point number contained in the F AC; i.e., if the
exponent is greater than(23ho.

SPECIAL FORMAT 2 - Pointer moves
- Op Code

Extension

Mnemonic

Function

SFTX

SETB

JSR

Set XO to the address contained in bits 9-23 of the instruction.
Set the base register to the
address contained m bits
9-23.
Jump and save return. Jump
to the location specified in
bits 9-23 and the return is
saved in bits 21-35 of the
first entry of the base page.

JSA

An unconditional jump is deposited in the address and
address + 1, where address is
specified by bits 9-23. The
FPC is set to address+2.
5-10

2
OP CODE

I IoI

EXTENSION

-I

Y
SPECIAL FORMAT 2

SPECIAL FORMAT 3 -NORMAL SIZE
Function
Op Code Extension Mnemonic

ALN

ATX

5-11

The mantissa of the F AC is
shifted until the F AC exponent equals -the contents of
the index register specified by
bits 9-11. -If bits 9-11 are
zero, the F AC is aligned so
_that the exponent '= (23)10.
Setting the exponent = (23)10
integerizes or fixes the floating-point number. The JAL
instruction tests to see if fixing is possible. In doubleprecision mode, an arithmetic
shift is performed on the F AC
fraction. The number of shifts
is equal to the absolute value
of the contents of the speci- fied index register. The direction of shift depends on the
sign of the index register contents. A positive sIgn indicates a shift toward the least
significant bit, while a negative sign indicates a shift toward the most significant bit.
The F Ac exponent is not altered by theALN instruction
in double-precision mode.
The contents of the FAC are
fixed and the least significant
12 bits .of the mantissa are

Op Code Extension

Mnemonic

XTA

NOP

o
o
1

5-7 1
12-1 7 ~
14-17 J

reserved

Function
loaded into the index register
specified by bits 9-11. In
double-precision mode the
least significant 12 bits of the
F AC are loaded into the spec- .
ified index register. The FAC
itself is not altered by the
FATX instruction.
The contents of the index
register specified by bits 9-11
are loaded right-justified into
the F AC mantissa. The f AC
exponent is loaded with (23)w
and then the F AC is normalized. This operation is typically termed floating a 12-bit
number. In double-precision
mode, the F AC is not normalized.
The single-word instruction
performs no operation.
These codes are reserved for
instruction set expansion and
should not be used.

SPECIAL FORMAT 3 - OPERATE
Op Code Extension 9-11 Bits Mnemonic

Function

FEXIT

Dump active registers
into the APT, reset
the FPP RUN flip-flop
to the 0 state, and interrupt the PDP-8 processor.

FPAUSE

Wait for synchronizing signal. lOT FFST
(6555) will restart the
instruction following
FPAUSE.

5-12

Function

Op Code· Extension Mnemonic
0

FCLA

Zero the FAC man-:tissa and exponent..

FNEG

Complement FAC.
mantissa. This instruc-.
tion produces the true
negative, not the.bitby-bit complement.

FNORM: Normalize the FAC.
In double-precision
mode FNORM is a
NOP.

STARTF

STARTD Start double-precision
mode.

JAC

OP CODE

01 0 I

Start
mode.

Jump to the location'
specified by the least
significant 15 bits of
the FAC mantissa.
8

EXTENSION

flo"ating-point

9
F

SPECIAL FORMAT 3 .

FPP MODE ADDRESSING
The FLAP /RALF assembler is able to interact with and effectively use the rather complex addressing-scheme of the FPP. This.
addressing scheme allows the FPP to access a full 32k words of
core through 15~bit addresses. It also allows the FPP to access a
movable base page through 7-bit addresses. The FPP can also use
2 or 3 bits to specify an index register from a movable set that can·'
modify the address. The FORTRAN compiler makes extensive use
of, this addressing freedom, particularly in the subroutine calls.
The base page is a block of 128 floating point variables, or 384
12-bit words. The Special Format 2 instruction SETB gives the
FPP the origin of the base page. The pseudo-op BASE is used to

5-13

pass the base page ongm to the FLAP/RALF assembler. The
origin of the base page may be changed as often as necessary. The
first 8 locations of the base page serve as a pointer to memory .
. The index registers are a block of seven 12-bit words in memory.
The Special Format 2 instruction SETX gives the FPP the origin
of the index registers. The locations used for the index registers
may be changed as often as necessary.
The three forms of Data Refer~nce Instructions compute the
address of the data referenced in three different ways. The line of
print below the diagram of each instru.ction shows symbolically how
each address is computed. The address computation for the first form
begins with the IS-bit address in bits 9-23 of the instruction. If X
(bits 6-8) is zero, this is the address used. If X is nonzero, the contents of the specified memory location, X +XO (where XO is the
beginning of the index registers, set by SETX), is used as an index.
If bit 5 of the instruction is equal to one, the index value is incremented by one. The index value remains incremented after the instruction is completed. The resulting index value is multiplied by
either two or three, depending upon whether the FPP is in Double
Precision Fixed Point Mode (STARTD) or Floating Point Mode
(STARTF). This index is then added to the' original address (bits
9-23 to form the address used.
The second data reference form· is used to address the locations
on the hase nage.
The contents of hits 5-11 of the instruction are
u
multiplied by three and added to the origin of the base page, set·
by the SETB instruction.
Note that the offset on the base page always assumes FloC;lting
Point (3-word) variables. It is wise to prevent use of the base page
for storage of double precision fixed point variables or instructions.
The third form of data reference instruction provides an indirect
or indexed indirect mode of address. The offset, bits 9-11 of the
instruction. are multiplied by three and added to the origin of the
base page, to give the address of a 3-word variable. The last 15
bits of this word are used for the address of the data. This address
may be modified by the index register exactly the same as in the
first form.
The FLAP/RALF Assembler will choose the form of the data
reference instruction that is generated. The second form (one word
direct) is usel instead of the first form (two word direct) whenever
~

5-14

· the data lies on the base page; no indexing is involved. The indirect
form is used whenever indirect addressing is called for by a % in
the assembler source statement.
.
LITERALS
Only FLAP allows literals in PDP-8 code. By starting an expression in a PDP-8 memory reference instruction with a left parenthesis or square bracket (as explained below), the value after it
is ta~en "literally" by FLAP. There is then no need to specify an
address or tag that contains the value. Internally the value of the
literal expression is the address of the word generated by FLAP
that contains the eval~ated expression.
If the expressi~n starts with a left parenthesis, (, then the literal
"is placed at the end of the current page. If it starts with a left
bracket, [, the literal is placed at the end of page O. Literal tables
are built backwards from the end of the page so that the most recently defined literal has the lowest core address.
If the origill is changed to a new page, the previous page's literals
are output and the literal table is reset. If the origin is reset to a
previous page which contained literals, those literals may be overlayed by any new literals. The previously-defined literals will not
be available for reference. For this reason, it is best to complete all
coding on any non-zero page before moving to another:
If the field is changed, the literals on page 0 of the previous field·
are output and the page 0 literal table is reset. For this reason, it
is best to complete all coding in anyone field before moving to
another.
Because locations 0-17 are generally used for interrupts and
autoindex registers, there may be only 11210 (1608) literals on
page O.
The following examples illustrate the use of literal expressions with
memory reference instructions:

TAD (POINTER

generates a literal with the lower 12 bits of
the address of PO INTER at the end of the
current page.

TAD [10

generates a literal containing 0010 at the end
of page O.
I

The left bracket, [, is typed as a SHIFT /K on an ASR-33.
5-15

Literals may not be nested. For example, the expression:
TAD (TAD [10
LINKS
Links are only generated by the FLAP assembler. If a PDP-8
memory reference is made to an address that is not on the same
page as the instruction, FLAP creates an indirect address linkage
on the current page. The address can, therefore, be accessed during
the second pass of the Assembler. For example, the coding:
ORG 200
00200 1177'
210377

TAO A

040~

PAGE
@0400 11025

.A,

1025

is equivalent to
OI'tG 200

00200 1777
00377

040~

TAO I x

ORG 311
X,
A

PAGE
0400 1025

11325

All instructions genera~ing links are flagged in the listing ~ith an
apostrophe (') following the generated code. The total number of
links is printed at the completion of assembly.
DATA SPECIFICATION
A logical line of code may consist of only an expression. Such
expressions can function as flags, pointers, constants, or symbols.
If the expression is larger than 12 bits, it will be truncated to 12
bits.
PSEUDO-OPERATORS
A pseudo-operator is a defined mnemonic code that is included
in the source program as a logical line to control some fUnctions of
the assembler. Binary code mayor may not be generated by a
5-16

pseudo-op, depending on its function. The FLAP /RALF pseudoops and their functions are listed below.
EQUATE ('=)
The symbol to the left of the = is -assigned the value of the expression to the right of it.
OCTAL
All integers which follow are assumed to be in octal radix. The
digits 8 and 9 are flagged if they occur in octal radix . The radix is
initially set to octal by FLAP.
DECIMAL
All integers which follow are assumed to be in decimal radix .
. PAGE
The current location counter is set to the beginning of the next
core page. This pseudo-op is not in the RALF assembler. '
BASEn
The location of the base page, n, is placed in FLAP /RALF base
register to be used in calculating single-word addresses. The argument, n, is an expression denoting a IS-bit address. The expression
may not contain any symbols that are defined after the BASE
pseudo-op occurs. A correct sequence is illustrated below.
ORG 400
A,

F 2,0

F 3.0

BASE A
SET" A

ISET ASSEMBLER- 8ASE REGISTER
ISET FPP 's ASf REG 1STER

FI.OA A

If no BASE pseudo-op is included, all FPP memory reference instructions will be 2 words. Refer to the sections on FPP addressing, and on referencing memory.

TEXT
A string of text may be entered by using the pseudo-op TEXT
followed by a space or tab, a delimiting character, a string of text,
and the same delimiting character, issued in that order. The first
5-17

printing character after TEXT is the delimiter and the text string
is all the characters that follow it until the next occurrence of the
delimiter or a carriage return. The characters space, tab, , , and /
cannot be delimiters. For example:
TEXT %DATA%
causes the word DATA to be printed with the code at assembly
time as:

TEXT

00200 0401
00201 2401

%OATA~

END
Input is tenninated. (This pseudo-op is optional, and is never
printed on the listing.)
INDEXn
Set the location of the first FPP index register to n.
ORG expr
the value of the lower
The current location counter is assigned
...
15 bits of the address expression expr. The expression should contain only symbols which have previously been defined. For example, to set the origin at location 400 of field 1. the Dseudo-oD used

...

. . I . . L

is ORG 10400.

If the ORG pseudo-op is omitted, an origin of 200 in field 0 is
assumed, but the origin setting is not included in the binary output
file. For useful results, the user program must begin with an ORG
pseudo-op.

ZBLOCKn
Assemble a block of n words containing O.
LISTOF
Continue assembly but inhibit further listing. There is no effect
on the first two passes or if the listing is currently inhibited. This
pseudo-op never appears in the listing.
LISTON
Cease to inhibit the listing. There is no effect on the first two
passes if the listing is not currently inhibited.
5-18

IFnnn (conditional assembly)
FLAP /RALF has ten conditional pseudo-ops. Four of them
require an argument expression:
pseudo-op

function

IFZEROn <
IFNZROn <
IFPOS n <
IFNEG n <

assemble if n is zero
assemble if n is not zero
.assemble if n is positive
assemble if n is negative

where n is an integer expression. For each of the above' conditional
pseudo-ops, the expression n is evaluated and, if it fulfills the conditions of the pseudo-op (e.g., n equals zero for IFZERO), the
subsequent coding is assembled. If the condition is not met, the
subsequent coding is ignored until a matching > is encountered.
Assembly is continued after the>.
'
. The fifth and sixth pseudo-ops are used in the format:
IFREF symbol

IFNDEF symbol <

assemble if symbol was previously defined or referenced.
where symbol may be defined or undefined. When an IFREF statement
is encountered, subsequent coding is
assembled if the symbol after the
pseudo-op has been defined or referenc;ed in a previous statement. Note
that use of a symbol with an IFREF
pseudo-op or in a statement that was
skipped during assembly because the
condition required by a preceding conditional pseudo-op was not met does
not constitute a reference to the symbol. If the symbol has not been previously defined or referenced assembly is continued after the matching
> is found.

The seventh through tenth pseudo.:.ops are:
IFSW n

assemble the enclosed code if the switch n
was set in the input/output file specification
to the command decoder, i.e. In or (n).
5-19

IFNSWn

assemble the enclosed code if the switch n
was not set.

IFFLAP<

assemble the enclosed code if the assembler
is FLAP. Thi~ pseudo-op is intended for use
in programs which may be assembled either
by RALF or by FLAP.

IFRALF<

do not assemble the enclosed code if the assembler is FLAP.

Conditionals may be nested. A possible nested conditional is
IFFLAP < IFREF A < A=263> >
-,

Use of some of the conditional assembly pseudo-ops is illustrated
in the next example. •
IFPOS _I c
A,

F ".0
~

00200 ""0k1
00201 0000
00202 0i00k3

IFNEG -I c
F. 0.0
~

IFREF A c
TAO A
~

TAD

Pl0C!01 lt0k:!

IFREF C c
TAD C
~

IFNDfF D c
0-5
~

NO ERHORS
2 SyMBOLS, NO LINKS
B

00200

00005

REPEATn
Assemble the following line n times.
Sn
Generate a I-word constant with value n. RALF does not support this pseudo-op.
5-20

Fn
Generate a 3-word floating point constant with value n. The
argument n may be written as a decimal floating point number, for
example 2.0, or in standard exponential format, for example 2ElO.
In standard expon~ntial form~t, 2ElO is equal to 2 x 1010.
En
Generate' a 6-word extended precision floating point constant
with value n. The argument· n may be written as a decimal floating
point number or'in standard exponential format.
ADDR
'Generates a two-word address corresponding to the value of the
argument.
COMMON·
Causes the assembler to enter the COMMON section whose
name follows the pseudo-op. Subsequent output is placed in the
named COMMON section until another section defining pseudo-op
is encountered.
COMMZ
Define Field 1 8-mode page 0 section. Used to give PDP-8 page
osection for the Loader.
DPCHK
Indicates that the current module requires double precision hardware in order to execute.
ENTRY
Defines program entry point. The symbol whose name follows
. the ENTRY pseudo-op can be used as an external symbol by other
programs. Multiple entry points with the same name are accepted
. by the assembler but cause an error from the loader.
EXTERN
The symbol following this pseudo-op is defined to be external
to this assembly.
FIELD 1
Define FIELDI 8-mode section. Used to give field 1 name of
section for the Loader.
5-21

SECT
Define program section, used at the. beginning of subprograms
to give the name of section for the Loader. For example:

BO,

SECT
JA
BASE
F
etc,

SUBROU
START

SECT8
Define 8-mode program section. Used at the beginning of 8-mode
subprograms.
.
-

REFERENCING MEMORY
A PDP-8 computer with an FPP is basically a 32Kmachine. All
of this memory may be referenced through the 15 bit address field
provided by the 2-word memory reference instructions. When it is
necessary to conserve memory, the base page and the short form
(1 word) of the memory reference instructions can be used. Those
instructions that have a floating point operand can use this short
form:

FADD

FDIV

FADDM

FLDA

FJvIUL
FSTA
FMULM FSUB

The base page is a movable page
assigned by the user. To
determine the location referred to ~y the operand of the single
word instruction the displacement field (address expression) is
multiplied by' 3 and added to the contents of the base register.
Thus, using the single word fomi of the instruction, any location
within 128*3 locations of the base register can be referenced. (Only
128 *3 locations can be. accessed because the displacement field has
only 7 bits.) The location of the base page (via BASE) and the
operands (via ORG,=,etc.) must be defined in the coding before
the FPP instruction. Then the short form of the instruction will be
executed unless the suffix # is added, forcing the long (2 word)
. form.
5-22

Consider the following example of the BASE pseudo-op:
OHG 200
002100
00201
013202
0"203
0020(&
00205
011120&
01il207
0111210
00211
00212
00213

12111102

F 3,0

F 5,0

0.,

F 0.0

2,0

21il0'"
0~01il

0~0c

3~0"

00"'1il

0"'03
2"-00
0000
01d0l~

•

0fd0~

00010

BASE i!00
SETB 21110
00214 111 "
00215 02010
0021& 0200
00217 1201
010220 4202
0ir!l221 e203

FI,.OA A

I"AOO 6
FMUI,.

10·(A.B)*C

FSTA 0

This same program can be written with a subroutine:
0212\10
01c:l2\11
00202
00203
021204
021205
1i1020&
00207
1il1il210
00211
00212
00213

0\102
21C01/l

QRG 21il0
F 2.0
A,

'0000

0iC0&!

3.0

5,0

0,O

3\10~

0000
01d03

~40icl

000\1

00010
01rj0kl

01101il
SE.TB 200

00214 1110
014215 02011
00216 112101
00217 0/,j00
0"'220

13,

HLT
BASE

H0&!

1/1

QRG 400

<'121400 0000
010401

~00k1

001.102
Lli01.1"1:,3
1/I"'1.I1:J4
001.105
1/1040b
001107

020\1
12t'll
420&!
&21/1;S
HJ31:J
131113\1

$UElR,

ILEAVE 2 WORDS FOR JSA

010
FI-OA 1/1

FADD 3

Ff'lUL i:I
FSTA 11

, 10

JA SUBR

I··RETURN ...

5-23

This rout~ne performs the same operation as the first one. The
values 0, 3, 6, and 11 are used with BASE 0 so that the assembler
generates the correct 1 word instructions.

RALF FEATURES
RALF symbols may be absolute, relocatable, or external. When··
a relocatable symbol appears in an assembled value, an indicator
is pi aced in the binary output file so that the relocating loader
(LOAD) will add the base loading address of the assembled value
to arrive at the value to be loaded. If an external symbol appears,
the loader will look up the name of the symbol in its symbol table
and substitute the value found there for the symboJ. The loader
symbol table contains all symbols defined by the SECT, SECT8,
FIELD 1, COMMON, COMMZ and ENTRY pseudo-ops of
RALF. Expressions using both absolute and relocatable terms are
evaluated as follows (where "op" is one of the set [+ - * / & !]
and ~'op 1" is one of the set [* / & !]):
Expression

Evaluated

numeric constant
label

absolute
relocatable

relocatable J:. absolute
relocatable - relocatable

relocatabie
absolute
relocatable
ERROR
ERRQR
ERROR

absolute - relocatable
expression qp 1 relocatable
relocatable op 1 expression

RALFcode is divided into sections. each section is .a separately
load able entry within the assembly. These sections are defined via
one of the five pseudo-ops: SECT, SECT8, FIELDl, COMMON
and COMMZ. Section names are placed in the External Symbol
Dictionary (ESD) which is used by the relocating loader to build
its symboL table. The pseudo-ops ENTRY and EXTERN allow
RALF programs to insert other symbols into the ESD and to refer
to these symbols in other RALF programs at load time. Table 5-3
lists the RALF pseudo-ops and their meanings.
5-24

Core Allocation

The user who wishes to link RALF modules containing PDP-8
mode code must be aware of the core allocation algorithm of the
loader. Five RALF pseudo-ops may be used to specify a section: .
SECT, COMMON, SECT8, FIELDl, and COMMZ. These sections are loaded independently by the loader, including those in
the same RALF module. SECT is used to begin a section of RALF
code that can be loaded into any level and overlay and anywhere in
field 1 and above. COMMON is used to begin a section.with a given
name ·available to COMMON statements in FORTRAN or other
RALF modules. SECT8 is used to begin a section of RALF code
that is loaded into level MA~N and is required to begin and end
on a page boundary. FIELD 1 is used to begin a section subject to
all the restrictions of SECT8 and in addition must be loaded into
field 1. COMMZ is used to begin a se.ction subject to all the restrictions of FIELDI and must be loaded into page O.
The first COMMZ section encountered is forced to begin at location 10000, thus enabling a page a in field 1. COMMZ sections of
the same name are handled like COMMON sections of the same
name (i.e., they are combined into one common section). This
feature allows 8-mode code in different modules to share page 0,
provided that the modules do not destroy each other's page a
allocations. Suppose two modules were to share page 0, with the
first using location 0-17 and the second using locations 20-37:
"'/Module A
COMMZ SHARE
PI,
P2,
KSUBAl,
KSUBA2,

1
2

SUBAI
SUBA2

LASTA;

-1

FIELD 1

/Should not go over
/20 locations

TADZ PI
JMSZ% KSUBAI

5-25

/Module B
COMMZ SHARE
ORG .+20
P3,
P4,
KSUBB,

SUBB

LASTB

-2

FIELD!

B
TADZ P3

/ORG past module A's
/Page 0

3
4

The two COMMZ sections will be put on top of one another, however, because of the ORO .+20 in module B, they will effectively
reside back to back. When the image is loaded, the COMMZ sec. tions will look as follows:
"'r1

LVL-

CONTENtS

1 0000
0001
2
3

1 0017
1 0020
21

2
SUBAI
SUBA2

-1

3
4
SUBB

-2

/LASTA

/LASTB
5-26

If module A is to reference module B's page 0, the procedure is:

P3=20
TADZ P3
Alternately, a duplicate of the. source code for COMMZ SHARE
may be included in module B. Modules that are using the same
COMMZ section must be aware of how it is divided up. Although
COMMZ SHARE takes only 40 locations, the loader allocates a
full 200 locations to it. All 8-mode section core allocations are
always rounded up so that they terminate on a page boundary. If
COMMZ sections of different names exist, they are accepted by
the loader and inserted into field 1, but. only one COMMZ is the
real page O. In general, it is unwise to have more than 1 COMMZ
section name.
If there is more than one COMMZ pseudo-op in a module, they
are stacked one behind the other, but there is no way of specifying
which one starts at absolute location 0 of field 1. CQMMZ sections
are allocated by the loader before FIELD 1 sections.
For users who intend to write 8-mode code that will execute in
conjunction with certain 8-mode library routines, the layout of
PDP-8 FIELDl #PAGE 0 is:
LOCATION

USE

0-1
2-13
14-157
160-177

Temps for any non-interrupt time routine.
User locations.
System locations.
User locations.

1. Do not define any COMMZ sections other than the system
COMMZ which is #PAGEO.
2. If the system page 0 is desired, it will be pulled in from the
library if EXTERN # D ISP .' appears in the code.
3. Do not use any part of page 0 reserved for the system.
FIELD 1 sections
are identical to COMMZ sections in most
,
respects. Memory allocation for' FIELD 1 sections is assigned after
COMMZ sections. however, and FIELDl· sections are combined
with FORTRAN COMMON sections of the same name as well as
other FIELDI sections of the same name. The first difference ensures that COMMZ will be allocated page 0 storage even in the
presence of FIELDI sections. The second allows PDP-8 code to
be loaded into COMMON, making it possible to load initialization
5-27

code into data buffers. Two FIELDI sections with the same name
may be combined in the same manner as' two COMMZ sections.
The primary purpose of COMMZ is to provide a PDP-8 page 0;
the primary purpose of FIELD 1 is to ensure that 8-mode code will
be loaded into field 1 and that generating CIF CDF instructions
in-line is not necessary. SECT8 sections may not be combined in
the manner of a COMMON and are not ensured of being placed·
into field 1.
A section begins when a pseudo-op with its name first appears.
A SECT8 section is not combined with another of the same name
in another RALF module. However, the second use of the same
name in the same module continues a section. For example:
SECT8 PARTA

SECT8 PARTB

SECT8 PARTA
The second mention of PARTA in the same module continues the
source where the first mention of PART A ended. (There is a location counter for each section.)
An 8-mode section does not have to be less than a page in length;
however, the programmer should be aware that a SECT8 section
which exceeds one page may be loaded· across a field boundary and
could thereby produce disastrous results at execution time. For
this reason, it is generally unwise to cross. pages in SECT8 code.
This situation will never occur on an 8K configuration. If the total
amount of COMMZ and FIELDI code exceeds 4K, the loader
generates an OVER CORE message. The loader generates an MS
error for any of the following:
1. A COMMZ section name is identical to some entry point or
some non-COMMZ section name.
2. A FIELD 1 section name is identical to some entry point or a
SECT, SECT8 or COMMZ section name.
3. A SECT8 section name is identical to an entry point or some
other section name.
5-28

COMMZ sections, like FORTRAN COMMONS, are never entered in the library catalog.

RALF Programming Notes
The best means, of creating RALF modules that can be called
from FORTRAN programs is to write a skeleton FORTRAN subroutine. The subroutine should'be written so that it can be called
with the same "call" statement to be used for the RALF subroutine.
This FORTRAN subroutine is then compiled with the" RALFout-.
put sent to a mass storage file. This file may be modified usingEDIT or TECO to create the desired module.
The address pseudo-op(ADDR) which generates a two word
relocatable I? bit address (i.e., JA TAG without use of JA) might
prove ·useful in 8-mode routines: The following example demonstrates a way in which an 8-mode routine in one RAL~ module
calls an 8-moderoutine in another module:
EXTERN SUB .

.
RIF
TAD
DCA
0
TAD
RTL
RAL
"TAD
DCA
0

ISet DF to current"
IIF for return"

ACDF
.+1

ICDFX
IMake a CIF from
IField bits

KSUB
CLL

ACIF
.+1

I CIF to field
IContaining .SUB

JMS%

KSUB+l

~SUB,

ADDR

SUB

ADCF,
ACIF,

CDF
CIF

IPseudo-op to
IGenerate 15 bit
I ADDR of subroutine
ISUB

In general the address pseudo-op can be used to supply an 8-mode
section with an argument or pointer external to the section. .
5-29

FPP and 8-mode code may be combined in any RALF section.
PDP-8 mode routines must be called in FPP mode by either:
TRAP3SUB
TRAP 4 SUB

A TRAP3 SUB causes FRTS to generate a JMP SUB with interrupts on and the FPP hardware (if any) halted. TRAP4 generates"a
JMS SUB under the same conditions. The return from TRAP4 is:
CDFCIFO
JMP% SUB
The return from TRAP3 is:
CDFCIF0
JMP% RETURN+l
RETURN,

EXTERN #RETRN
ADDR #RETRN

It is not possible to call PDP-8 mode subroutines from FOR-

TRAN. A RALF subroutine called from FORTRAN will be entered in FPP-mode, it may branch into PDP-8 mode code using a
TRAP3 or TRAP4.
the FPP level because of greater ftexibiiity in both addressing and
relocation in FPP mode. The following routine demonstrates how
to pass an argument to, and retrieve an argument from, an 8-mode
routine:
EXTERN SUB
EXTERN SUBIN
EXTERN SUB OUT

FLDA
FSTA
TRAP4
FLDA
FSTA

X
SUBIN
SUB
SUB OUT

/ Arg for SUB
/ Call SUB
/Get result

5-30

If the 8-mode
.
.routine SUB were in the same module as the
FPP routine, the EXTERN s would not be 'necessary. In practice it is
common for FPP and 8-mode routines that communicate with one
another to be in the same section. A number of techniques can be
used to pass arguments. For example,' an FPP routine could move
the index registers to an 8-mode section and pass single precision
arguments via A TX.
Because 8-mode routines are commonly used in conjunction with
FPP code (generated by the compiler), the 8'-mode programmer
should be familiar with OS/8 FORTRAN IV subrolJtine calling
conventions. The general code for a subroutine 'call is a JSR, fol-lowed by a J A around a list of arguments, followed by a list of
.pointers to the arguments. The FPP code for the statement:
CALL SUB (X,Y,Z)
would be
EXTERN
JSR
JA
JA
JA
JA

SUB
SUB
BYARG

X
Y
Z

BYARG,

The general format of every subroutine obeys the following scheme:
SECT SUB
JA
#ST
TEXT +SUB+
RTN,
BSUB,

SETX XSUB
SETB BSUB
FNOP
JA

/Jump to start of
/Routine
/Needed for
/Trace back
/Reset $UB's index
/ And base page
/Start of base page

5-31

ORG BSUB+30
FNOP:JA RTN GOBAK, FNOP:JA.

IRestart for SUB

IReturn to
ICalling program

Location 0000 of the calling routine's base page points to the list
of arguments, if any, and may be used by the called subroutine
provided that it is not modified .. Location 0003 of the calling
routine's base page is free for use by the called subroutine. Location 0030 of the calling routine's base page contains the address
where execution is to continue upon exit from the subroutine, so
that a subroutine should not return from a JSR call via location 0
of the calling routine:
CORRECT
FLDA 30
JAC

INCORRECT
FLDAO
lAC

This return allows the calling routine to reset its own index registers and base page before continuing in-line execution. General
initialization code for a subroutine would be:-

#ST,

SECT
JA

SLTB
#ST

BASE
STARTD

FLDA
FSTA
FLDA
SETX
SETB
BASE
INDEX
FSTA

30
GOBAK
0
XSUB
BSUB
BSUB
XSUB
BSUBX

ISo only 2 words
IWill be picked up
I Get return J A
ISave it
I Get pointer to list
ISet SUB's XR
ISet SUB's Base
IStore pointer
ISomewhere on Base
5-32

STARTF
JA

GOBAK

/Set F mode before
/Retum

The above code can be optimized for routines that do not require
full geberality. The JA #ST around the base page code is a convenience which may be omitted. The three words of text are necessary only for ~ror traceback and may also be omitted. If the
subroutine is not going to call any general subroutines, the SETX
and SETB instructions at location RTN and the JA RTN at-location 0030 are not necessary. If the subroutine does not require a
base page, the SETB instruction is not necessary in subroutine
initialization;, similar remarks apply to index registers. If neither
base page nor index regIsters are modified by the subroutine, the
return sequence:
/

FLDAO
JAC
is also legal. In a subroutine call, the JA around the list of arguments is unnecessary when there are no arguments. A RALF listing of a FORTRAN source will provide a good refe'rence of general FPP coding conventions.
The AMOD routine is listed in Figure 5-1 to illustrate an ~applica
tion of the formal 'calling sequence. It also includes an error condition check and picks up two arguments. When called from
FORTRAN, the code is AMOD(X,Y).

If a PDP-8 mode subroutine is longer than one page and values

are to be passed across page boundaries, the address pseudo-op,
ADDR, is required. The format is:
AVARl, ADDR VARI

5-33

I
I
I
I
I
I

A :') 0 D

ISUBROUTINE
SECT
ENTRY
JA
TEXT
Ai"lODXR, SErX
SET8

BPAI'IOD. F 0.0
XRAMOD, F 0.0
A(1fODX, F' 0.0
ORG
F'NOP
JA

AMDRTN, JA
EXTERN
AMODER, TRAP4
F'CLA
JA

BAsE

ILONG ENOUGH TO
MOD,
IAMOD, STARTD
F'LDA
F'STA
F'LDA
SETX
SETS
BASE
LDX
F'STA
F'LDAi.
F'STA
FLDA i.
F'STA
,.. ... ,.n .... _

AMOD(X,Y)
AMOD
MOD
IIAMOD
+AMOD +
XRAMOD
BPAMOD

ISECTION NAME(REAL NUMBERS)
IENTRY POINT NAME(INTEGERS)
IJUMP TO START OF ROUTINE
IFOR ERROR TRACE BACK
ISET INDEX REGISTERS
IASSIGN BASE PAGE
IBASE PAGE
II NDEX REGS.
ITEMP STORAGE
IRE TURN SEQUENCE

AMODXR

.#ARGEH
lARGER
AMDRTN

IEXIT
IPRINT AN ERROR MESSAGE
IEXIT wITH FAG =!2l

ISTAY ON CALLER'S BASE PG
GET RETURN ADDRESS
ISTART OF' INTEGER ROUTINE SAME AS
ISTART OF REAL NU~. ROUTINE
IGET RETURN JUMP
Ifll*3
ISAVE IN THIS PROGRAM
AMDRTN
()
IGET POINTER TO PASSED ARG
XRAMOJ
•
IASSIGN MOD'S INDEX REGS
BPAMOD
IANJ ITS BASE PAGE
BPAMO~

1, 1

BPAMO:J
BPAMOD,l
AMODX
BPA!"lO:J, 1+
B?AMOD

IADDR OF X
IA !)DR Of Y

;) Htl1 1 r

F"LDAi.
JEQ
JGT
F'NEG
F'S TA
F'LDA7.
JGT
F'NEG
LDX
F'STA
F'DIV
JAL
AL~

AM,

F'NORM
F'i'lUL
F'NEG
F'AD::>
JXN
F'NEG
JA

BPAMOD
AMODER

IGET Y
IY =0 IS ERROR

.+3

IAtlS VALUE
BPAMOD
Af"lODX

IGET X

.+5

VAI:.UE
INOTE SIGN
ISAV IN A TEMPORARY
IDIVIDE BY Y
!TOO BIG.
IFIX IT UP NO;,.!.
lABS

",1

AMODX
BPAMOD
AMO~ER

AMODX,
AM, 1

IMULI TPL Y IT.
INEGATE IT.
lAND ADD IN X.
ICHECK SIGN

AMDRTN

IDONE

BPAMOD

Figure 5·1

AMOn Routine

5-34

This generates a two-word (15 BIT) reference to the proper location on another page, here VARl. For example, to pass a value to
VAR1, possible code is:
00124
00125

1244
3757

TAD
DCA%

VAR2
AVAR1+1

00156
.00157

0000 AV AR1,ADDR VAR1
0322

/Value on this page
/Pass through 12-bit
/Iocation
/Field and
/location of V AR 1

Any reference to an absolute address can be effected by the ADDR
pseudo-op.
If it is doubtful that the effective address is in the current data field,
it is necessary to create a CDF instruction to the proper field. In
the above example, suitable code to add to specify the data field is:
TAD
RTL
RAL
TAD
DCA

AVAR1

/Oet field bits
/Rotate to bits 6-8

(6201
.+1

/AddaCDF
/Deposit in line
/Execute CDFn

If the subroutine includes an off-page reference to another RALF
module (e.g., in FORLIB), it can be addressed by using an
EXTERN with an ADDR pseudo-op. For example, in the display
program, a reference to the non-interrupt task subroutine ONQB
is coded as

EXTERN
ONQBX, ADDR

ONQB
ONQB

and is called by

JMS%

ONQBX+1

No field change instruction is necessary here, because both library
modules are defined by' field 1 pseudo-op's, and so are both in the
same field.
RALF does not recognize LINC instruction or PDP-8 labora-·
tory device instructions. Such instructions can be included in the
subroutine by defining them by equate statements in the program.
5:·-35

For example, adding the statements:
PDP=2
LINC = 6141
DIS = 140
takes care of all instructions for coding the PDP-12 display subroutine.
When writing a routine that is going to be longer than a page,
it can be useful to h,ave a non-fixed origin in order not to waste
core and to facilitate modification of the code. A statement such as
IFPOS .-SECNAM&177-K
will start a new page only if the value [current location less section
name] is greater than some K (start of section has a relative value
,of 0) where K~177 and is the relative location on the current page
before which a new page should be started. The ORG statement
includes an AND mask of 7600 to preserve the current page. When
added to 200 for the next page and the section name, the new
origin is set.
When calculating directly in a module, the following rules apply
to relative and absolute values.

relative - relative = absolute
ahso1ute + relative = relative
OR 0), AND (&) ru"ld ADD (+) of relative symbols
generate the RALF error message RE.
~.

When passing arguments (single precision) from FPP code to PDP
code, using the index registers is very efficient. For example,

FLDA % ARG 1
/Get argument in FPP mode
SETX
MODE 8 /Change index registers so XRO is
/AtMODE8
ATX
MODE8 /Save argument

. TRAP4

SUB8

/Go to PDP-8 routine
5-36

SUB8,

TAD

MOD~8,

/PDP-8 routine

MODE8

/Get argument

/ Index registers set here

The source. of FORTRAN Library is the best collection available
of usefnl coding techniques in RALF. Working examples include
subroutine linkage, 8-mode trap sequences, background task
inclusion, interrupt handling, laboratory peripheral interfacing,and
mathematical calculation.
Using The Assembler
FLAP/RALF is run as a standard OS/8 program by typing:
.R FLAP (or RALF)
*binary ,1isting~input 1,input2, .....
where binary is the binary output file, default extension .RL; listing
_is the listing output file, default extension .!:-S; inputl, input2, etc .
. are up to 9 source input files, default extensions .RA . The source
files must contain only one FLAP /RALF source module (i.e., one
END statement) .

. All error messages are printed on the terminal during pass 2,
without affecting the binary output file, along with the line which
caused the error. This output maybe inhibited by typing CTRLjO.
The error. messages are also printed above the error line on the
listing. FLAP /RALF error codes are listed in the next section.
5-37

Assembly may be aborted by typing CTRL/C. Each page: of a
FLAP/RALF listing has a one line header in the form:
.
FLAP (or RALF) V

da,

yr. PAGE r

where nn is the assembler version number, mo da, yr is the date,
and r is the page number.
The /S option, in FLAP, may be used to suppress the listing
file and generate o'nly the symbol map on pass 3. If no listing file
is .specified, this option is ignored. The /T option performs the
same function in RALF.
Error Messages
During pass 2, error messages are printed at the terminal .as they
occur, followed by the statement in which the error occurred.
During pass 3, error codes are printed in the listing immediately
preceding the line in which the error occurred, except the EG message, .which is printed after the line. If the line of code includes
statements t~rminated by a semicolon, then the error message for
a statement precedes the printing of its octal value on the next line.
A fatal error causes an immediate return to the OS/8 monitor
after the message is printed. The following table lists the error
codes and their meanings.

Table 5-2

FLAP/RALF Error Codes

Error Code

Meaning

Illegal equate. The symbol had been defined previously.

Illegal index register specification.

Bad expression. Something in the expression is incorrect or the expression is not valid in this context.

Ail attempt was made in an expression evaluation to
divide by zero ..

The preceding line contains extra code which could
. not be used by the assembler.
5-38

Table 5-2

FLAPJRALF Error Codes (Cont.)

Error Code

Meaning

External symbol error. (RALF only)

An error has occurred in the FPP or software floating conversion routines. This could be due to an attempt to convert an excessively large or small number, or an internal error in the assembler occurred.

A syntax error WqS encountered in a floating point
or. extended precision constant.

The symbol or expression in a conditional is improperly used, or left angle bracket is missing. The
conditional pseudo-op is ignored.

An entry point has not been defined, or is absolute,
or is also defined as a common, section, or external.
(RALF only)

A literal was used in an instruction which cannot
accept one. (FLAP only)

Input/output error (fatal error).

Invalid reference in a PDP-8 instruction.

An index register was specified for an instruction
. which cannot accept one.

The line is longer than 127 characters. The first
127 characters are assembled and listed.

The tag on the line has been previously encountered
at another location or has been used in a context
requiring an absolute expression.

N umber error. A number out of range was specified
or an 8 or 9 occurred in octal radix.

Page overflow. Literals and instructions have been
overlapped. (FLAP only)

Relocatability error. A relocatable expression has
been used in context requiring an absolute expression. (RALF only)
5-39

Table 5-2

FLAP/ RALF Error Codes (Cont.)

Error Code

Meaning

User symbol table overflow (fatal error).

Undefined symbol in an expression.

External symbol table overflow. Control returns to
the OS/8 Keyboard Monitor. (RALF only)

FLAP/ RALF Pseudo-Operators
The following table lists the FLAP /RALF pseudo-ops and gives
a brief description of each pseudo-op.
Table 5-3

FLAPIRALF Pseudo-Operators

Pseudo-op

Meaning

ADDR

Place the I5-bit address of the symbol into two
words of core at the current position of the
location counter.

BASE expr

Assign base register for I-word instructions.

COMMON name

Causes the assembler to enter the common section whose name follows the pseudo-op.

CO~YfMZ

Define name as a special common section restricted to load into page 0 of field 1.

name

DECIMAL

Set radix for integer conversion to decimal.

Exxx

Generate 6-word extended precision floating
point constant.

END

End of input.

ENPUNC

Re-enable binary output (FLAP only).

ENTRY name

Insert name into the ESD as an entry point.
The symbol name must be defined as a relocatable symbol in the current assembiy.

EXTERN name

Insert name into the ESD as an external reference. The symbol name must not be defined in
the current assembly.

Fxxx

Generate 3-word floating point constant.

FIELDI name

Similar to SECT8, but this section is restricted
to load into field I only.

5-40

Table 5-3

FLAP/RALF Pseudo-Operators (Cont.)
Meaning

Pseudo-op ,
IFFLAP

Assemble if the assembler is FLAP.

IFNDEFn

Assemble if n is not defined.

IFNEG n

Assemble if n is negative.

IFNSWn

Assemble if switch n was not set in Command
Decoder input.

IFNZROn

Assemble if n is not zero.

IFPOS n

Assemble if n is positive.

IFRALF

Assemble if the assembler is RALF.

IFREF symbol

Assemble if symbol has already been defined or
referenced.

IFSWn

Assemble if symbol was set in Command Decoder input.

IFZERO n

Assemble if n is zero.

INDEXn

Assign index register location.

LISTOF

Inhibit program listing.

OCTAL

Set radix for integer conversion to octal.

ORG expr

Set current location counter to lower 15 bits of
expr.

PAGE

Set current location counter to the beginning of
next core page (FLAP only).

REPEATn

Repeat next line n times.

Sxxx

Generate I-word constant (FLAP only).

SECT name

Define name as a section and begin that section.
Subsequent SECT name commands will resume
the section wherever it left off.

SECTS·

Similar to SECT, but this section is restricfed
to load in level MAIN, on a 200 8 word boufldary. SECTS is used to define sections that contain PDP-S mode code.

TEXT

Assemble the text between delimiters as packed
6-bit ASCII characters.

ZBLOCKn

Assemble n words containing O.
Equate symbol on left of
sion on right.

5-41

= to value of expres-

5-42

basic
~ortrali II
~ortranlv

basic.
INTRODUCTION TO OS/8 BASIC
BASIC! is an interactive programming language with a variety
of applications. It is used in scientific and business. environments
to solve both simple and complex mathematical problems with a
minimum of programming effort. It is, used by educators and students as a problem-solving tool and as an aid to learning through
programmed instruction and simulation.
In many respects the BASIC language is similar to other pro'gramming languages (such as FOCAL and FORTRAN), but
BASIC is aimed at facilitating communication between the user ,
and the computer. The BASIC user types in the computational
procedure as a series of numbered statements, making use of common English words and familiar mathematicaL notations. Because
of the small number of commands necessary and its easy application in solving problems, BASIC is one of the simplest computer
languages to learn. With experience, the user can add the advanced
techniques available in the language to perform more intricate manipUlations or express a problem more efficiently and concisely.
OS/8 BASIC has a greater capability than 8K BASIC andcontains such added features as chaining, string manipulation, and
file-oriented input/output.
Running BASIC

Once the Keyboard Monitor has responded with a period to indicate that it is ready to receive a monitor command, the user
types the following command:
.R BASIC
BASIC responds with the following:
!

BASIC is a registered trademark of the trustees of Dartmouth College.

6-1

NEW OR OLDThe user types in:
NEW FILE.EX
if the user is going to create a new program, where FILE.EX is the
name and extension of the new program. If the user wants to work
with a previously created program. that he saved on a storage
device, he types in the following:
OLD DEV:FILE.EX
where DEV: is the name of the OS/8 device on which his old file
is stored.
For example:
OLD DTA6:SAMPLE.BA
This response to NEW or OLD-retrieves the file named SAMPLE from DECtape 6 and replaces the current contents of user
core with the file SAMPLE. If the user specifies a device that does
not exist or that is not available for use, BASIC returns an error
message.
ENTERING THE NEW PROGRAM
After the user types in his filename, OS/8 BASIC responds with
the following:
READY
The user can begin to type in his new program or make changes
to his old program. When the new program is being typed, the
user must make sure that each line begins with a line number containing no more than five digits and containing no spaces or nondigit ~haracters. The RETURN key must be pressed at the completion of each line. If, in the process of typing a statement, the
user makes a typing error and notices it before he terminates the
line, he can correct it by pressing the RUB~UT key or SHIFT /0
keys once for each character' to be erased, going backward until
the character in error is reached. Then he may continue typing,
beginning with the character in error. Using the RUB OUT key or
SHIFT / 0 keys echoes a backarrow (~) for each character de,leted. The following is an example of this correcting process (note
that a ~ is typed for spaces as well as characters):

6-2

20 DEN

F~~~F

FNA(X,Y)=t2+3*Y

The corrected version of the above example would appear on a
subsequent listing of the program as:
20 DEF FNA(X,Y)=Xt2+3*Y
Program listings can' be generated using the LIST or LISTNH
commands.
EXECUTING THE PROGRA1\1
After typing the complete program (~o not forget to end with an
END statement), type RUN· or RUNNH, followed by the RETURN key. OSj8 BASIC prints the name of the program,
,the version of OSj8 BASIC, the current date (unless RUNNH is
specified), and then it analyzes the program. If the program can be
run, OSj8 BASIC executes it and, via PRINT statements, prints out
any results that were requested. The print~)Ut of results does not
guarantee that the program is correct (the results could be wrong),
but it does indicate that no syntactical errors exist (e.g., missing
line numbers, misspelled words, or illegal syntax). If errors of
this type do exist,-OSj8 BASIC prints-a message (or several messages) to the user. A list of these diagnostic messages, with their
meanings, is given at the end of the chapter.

NOTE
RUN and RUNNH are control commands,.
and like all other OSj8 BASIC edit and control commands, they do not require a line
number preceding the command.
CORRECTING THE PROGRAM
·If the user receives an error message printout informing him,
for example, that line 60 is in error, the line can be corrected by
typing in a.new line 60 to replace the erroneous one. If the statement on line 110 is to be eliminated from the program, it is
accomplished by typing the following:
110 (followed by a carriage return)
If he wishes to insert a statement between lines 60 and 70, the

user types a line number between 60 and 70 (e.g., 65), followed
by the statement.
6-3

INTERRUPTING EXECUTION OF THE PROGRAM
If the results being pril}ted seem to be incorrect and the user
wants to stop execution of his program, the user types CTRL/C
which is echoed by t C. The OS/8 BASIC editor responds with the
READY message whereupon the user can modify or add statements and rerun his program.
LEAVING THE COMPUTER
When the user's program is finished and he no longer requires
the use of OS/8 BASIC, he types the BYE command (or CTRL/C)
to return control to the Keyboard Monitor.
EXAMPLE OF OS/8 BASIC RUN
The following is a simple example of the use of OS/8 BASIC.
READY
SCRATCH
READY

Instruct""monitor to bring
BASIC into core and start
its execution

• R BASI C
NEW OR OLD--NE\tJ

S.AMPLE.B.A

READY
1 0 FOR N = 1 T 0 7
20 PRINT N~SQR(N)
30 NEXT N

BASIC asks \vhether new
or old program is to be run

40 PRINT "DONE"
50 END

RUN
SAMPLE

BASIC is now ready to
receive statements

3.0

2
3

1.41421

2.23607

2. 44949
2. 64575

Type in statements

1.73205

Run program
Program heading and results of program are printed

DCNE

READY

6-4

os/8

BASIC Overview

GENERA~

SYSTEM DESCRIPTION
The OS/8 BASIC system is divided into five discrete parts:
1.
-2.
3.
4.

Editor
Compiler
Loader
Runtime System
5. Runtime System Overlays

The ·OS/8 BASIC Editor is used to create and edit the source
program. On receipt of a RUN command, the Editor stores the
program in a temporary file and chains to the Compiler. The Com- _
piler compiles the program into pseudo-instructions which are then
loaded into core with the Run-time System by the Loader. The Runtime System interprets each pseudo-instruction, calling each of the
Overlays into core as needed. On completion of the program, the
Run-time System chains back to the Editor.
OS/8 BASIC STATEMENTS AND COMMANDS
OS/8 BASIC consists of program statements and system control commands which are needed to write programs. A number of
the elementary OS/8 BASIC statements and commands are: OS/8 BASIC Statements
LET
PRINT
READ
DATA
GOTO
IF GOTO}
IF THEN
FOR TO }
STEP
NEXT
GOSUB
RETURN
INPUT
REM
RESTORE

Assign a value to a variable.
Print out the indicated information.
Initialize variables to values from the data list.
Provide initial data for a program.
Change order of program execution.
Conditionally change order of program execution.
Set up a program loop.
End a program loop.
Go to a subroutine.
Return from a subroutine.
Get initial values from the terminal.
Insert a program comment.
Restore the data list.
~

6-5

DEF
STOP
END
DIM
UDEF

Define a function.
Stop program execution.
End a program.
Define subscripted variables.
Define user-coded function.

.oS/8 BASIC Edit and Control Commands
LIST

RUN
.SCRATCH
SAVE
OLD
NEW
NAME
BYE

List all stored program statements.
Run the currently stored program.
Delete the currently stored program .
Save the currently stored program.
Retrieve the old program.
Prepare for a new program.
Rename the currently stored program.
Exit from BASIC.

These statements and commands are explained in detail with actual
computer output in this manual. For the convenience of the user,
a detailed OS/8 BASIC Statement, Command and Function Summary is included at the end of the chapter.
The experienced BASIC programmer may elect to skip the first
six sections of this chapter since they are rather fundamental.
However, he should familiarize himself with the remaining sections
as they provide information specifically related to OS/8 BASIC.

OS/8 BASIC ARITHMETIC
Numbers
An OS/8 BASIC number may be any number in the range of
lo-61~

equai to
< less than
or <= less than or equal to

greater than
=> or >= greater than or
equal to
> < or < > not equal to

Depending upon the result of the comparison, control of program
execution may be directed to another part of the program. Relational operators are used in conjunction with the IF-THEN statement which is discussed in the next section.
The meaning of the (=) sign should be clarified. In algebraic
notation, the formula X=X+ 1 is "meaningless. However, in
OS/8 BASIC (and most computer languages), the equal sign
designates replacement rather than equality. Thus, this formula is
actually translated "add one to the current value of X and store
the new result back in the same variable X." Whatever value has
previously been assigned to X will be combined with the value 1.
An expression such as A=B+C instructs the computer to add the
6-10

values -of Band C and store the result in a third variable A. The
variable A is not being evaluated in terms of any previously assigned value,but only in terms of Band C. Therefore, if A has
been assigned any. value prior to its use in this statement, the old
value is lost; it is instead replaced by the value of B+C.
RULES FOR EXPONENTIATION
The following rules apply in evaluating the expression A t B.'
Rule

Example

--\

1. If B=O, then A t B-:-l
3tO=1
Ot2-.-:0
2. If A=O and B>O, then A t B=O
3. If A=O and B9, then
A tB=Al*A2*A3 ... *A n, where n=B
5. If B is an integer <0 then
3 t -5=1/243
A tB=1/CAl*A2*A3' .. *An),
where n=B
6. If B is a de.cimal (non-integer)
2 t 3.6=eB1nA =
e3.61n2
and A>O, then A tB=
EXP(B*LOG(A))
-3 t 2.6 is illegal.
7. If B is a positive or negative
Fatal error message
decimal (non-integer) and A
INPUT G
LET V=V+G
NEXT K
LET V=V/B
PRI N T "AVERAGE GRADE - "J V
PRINT
LET Q=Q+V
NEXT J
PRJ NT
PRJNT
PRINT "Q..ASS AVERAGE ="; Q/A
STOP
END

READY
RUNNH
H ()l MANY STUDENTS .. H OW MANY GRADES PER STUDENT
STUDENT NlIMBER =
0
ENTER GRADES
?78
?86

?5 .. 4

?S8
?74
AVERAGE GRADE STUDENT NlJ:1BER
ENTER GRADES

?59
?86
?79
?87
AVERAGE GRADE STUDENT NUMBER
ENTER GRADES

81.5

75.5

?58
?64
175
?89
AVERAGE GRADE STUDENT NUMBER
ENTER GRADES

?S8
?92
?85
?79
.AVERAGE GRADE -

69.25

6-12

STUDENT NUMBER
ENTER GRADES
160

178

185
180
AVERAGE GRADE - 75.75

CLASS AVERAGE

= 77.6

READY

Statement Numbers

A program is made up of statements. Each line of the program
begins with a line number of 1 to 5 digits that serves to identify
the line as a statement. The largest allowable line number is 99999.
Line numbers serve to specify the order in which these statements
are to be performed. Before the program is run, OS/8 BASIC sorts
out and edit~ the program, putting the statements into the order
specified by their line numbers; thus, the program statements can
be typed in any order, as long as each statement is prefixed with a
line number indicating its proper sequence in the order of execution. Each statement starts after its line number with an English
word (except the LET statement where LET is optional) which
denotes the type of statement. Unlike program statements, system
commands are not preceded by line numbers and: are executed
immediately after they are typed in. Spaces have no significance
in BASIC programs or commands, except in messages or literal
strings which are printed out, and in line numbers. Thus, spaces
may, but need not be,. used to modify a program and make it more
readable.
'
A common programming practice is to number lines by fives or
tens, so that additional lines may be inserted in a program without
the necessity of renumbering lines already present. Renumbering
a program can be accomplished by using the RESEQ program
described in the section entitled EDITING AND CONTROL
COMMANDS.
Multiple statements may be placed on a single line by separating
each statement from the preceding statement with a backslash
(SHIFT /L on'some terminals). For example:
10 A=5",-B=.2",-C=3'",-PRINT "ENTER DATA"
6-13

All of the statements in line 10 will be executed before BASIC
continues to the next line. Only one statement number at the beginning of the entite line is necessary. However, it should be remembered that program control cannot be transferred to a statement within a line, only to the first statement of the line in which
.
it is contained.
REMARK-The Commenting Statement
The REl\.1 or REl\.1ARK statement allows the programmer to
insert comments or remarks into a program without these comments affecting execution. The OS/8 BASIC compiler ignores
everything between REM and" the end of the line. The form is:
(line number) REM (message)
In the Example Program, lines 10 and 15 are REMARK statements describing what the program does. It is often useful to put
the name of the program and information relating to its use at the
beginning where it is available for future reference. Remarks
throughout the body of a long program will help subsequent debugging by explaining the purpose of each statement within the
program.
Statements For Terminating A Program
END
The END statement (line 140 in the Example Program) should
be the last statement of the entire program. The form is:
(line number) END
STOP
The STOP statement is used synonymously with the END statement to terminate execution; but while END occurs only once at
the e.nd of a program, STOP may occur any number of times. The
format of the STOP statement is:
(line number) STOP
This statement signals that execution is to be terminated at that
point in the program where it is encountered.
6-14

LET-The Assignment Statement

The Assignment (LET) statement is probably the most commonly used OS/8 BASIC statement and is used whenever a value
is to be assigned to a variable. It is of the form:
(linenumber) LET x '= expression
where x represents a variable,' and the expression is either a number, another variable, or an arithmetic expression. The word "LET"
is optional; thus the following statements are treated the same:
100 LET A=A t=R GO TO 100
150 PRINT B*I,R-B*I
160 PRINT "LAST PAYMENT "; 8*I+B
200 END

=";

BALANCE"

READY

RUNNH
INTEREST IN PERCENT?9
AMOUNT OF LOAN ?250.0
N UMBER OF YEARS?2
NUMBER OF PAYMENJS P-ER YEAR?4
AMOUNT PER PAYMENT = 344.965
TOTAL INTEREST
= 259.724
INTEREST
56.25
49.7539

43.1116
36.3199
29.3754
22.2746
15.0141

7. :)9015
LAST PAYMENT

APP TO PRIN
288.715
295.212.
30!.854

308.645
315. 59

BALANCE
2211.28
1916dn

1614;22
130.5. ':17

989.982

322. 69 I
329.9':11
331. 31 ':J
344.93

667.291
337.34

READY

As can be noticed in this example, the question mark is grammatically useful in a program in which several values are to be input
by allowing the programmer to formulate a verbal question which
the input value will answer.
6-20

THE TAB(X) FUNCTION
The TAB function, which may only be used in a PRINT statement, allows the user to position-the printing of characters anywhere
on the terminal line (or other printing device line when used with
PRINT #). Print positions can be thought of as being numbered
from 1 to 72 across t1,J.e Teletype from left to right. The form of this
function is:
TAB(X)
where the argument X represents the position (from 1 to 72 columns available on the terminal) in which the next character will be
typed.
Each time the TAB function is used in a PRINT statement; positions- are counted from the beginning of the line, not from the current position of the printing head. For example, the TAB function
in the following program causes the character "/" to be printed at
24 equally spaced positions along the line.
10 FOR K=3 TO 72 STEP 3
20 PRINT TAB(K); "/";
30 NEXTK
40 END
If the argument X in the TAB function is less than the current posi-

tion of the printing head, printing is started at the current position.
If the argument X is greater than 72 (the number of columns available· in an output line), a carriage return-line feed is executed and
printing resumes at position 1.
THE PNT(X) FUNCTION
OS/8 BASIC provides an additional function, PNT(X), to increase input/output flexibility. The function is primarily used for
outputting non-printing characters such as the "bell", but can be
used for more sophisticated applications. The PNT(X) function,
like the TAB (X) function, may only be used in either a PRINT or
PRINT# statement. The form of the function is:
PNT(X)
where the -argument X. represents the decimal value of the 7-bit
ASCII character to be output. For example, the statement:
6-21

10 PRINT "X=";3.14159;PNT(13) ;TAB(14) ;"/"
will print the slash (/) on top of the equal sign after executing a
carriage return (CR=13 1O ) and a TAB to column 2 as shown
below:
XFLJ3.14159 w
Notice that a TAB (14 ) is required since OS/8 BASIC remembers
the print head to be at column 12 after the carriage return (11 columns for X=u3.14159u and 1 column for the PNT function). A
tab to column 2 after the carriage return provides a total of 14
columns. The PNT ( 13) carriage return does not zero the column
count but, in fact, adds to the column count. (This example may
not work on some- terminals.)
The READ and DATA Statements
READ and DATA statements are used to provide data to a
program. One statement is never used without the other. The form
of the READ statement is: .
(line number) READ xl ,x2 , ... ,xn
where x 1 through xn represent variable names. For example:
10 READ A,B,C
A, B, and C are variables to which values will be assigned. Variables in a READ statement must be separated by commas. READ
statements are generally placed at the beginning of a program, but
must at least logically occur before that point in the program where
the value is required for some computation.
Values which will be assigned to the variables in a READ statement are supplied in a DATA statement of the form:
(line number) DATA xl,x2 ... ,xn
where x 1 through xn represent values. The valqes must be separated by commas and occur in -the same order as the variables
which are listed in the corresponding READ statement. A DATA
statement appropriate for the preceding REAP statement is:
70 DATA 1,2,3
Thus, at execution time A=I, B=2, and C=3.
'-.

6-22

The- D ATA statement is usually placed at the end of a program
(before the END statement) where it is easily accessible to the
programmer should he wish to change the values.
A READ statement may have more or fewer variables than
there are values in anyone DATA statement. The READ statement causes OS/8 BASIC to search all available DATA statements in the order of their line numbers until values are found for
each variable in the READ. A second READ statement will begin
reading values where the first stopped. If at some point in the
program an attempt is made to read data which is not present,
OS/8 BASIC will stop and print the following message at the
console:
, DA AT LINE YYYYY
where YYYYY indicates the line which caused the error.
RESTORE
If it is desired to use the same data more than once in a pro-

gram, the RESTORE statement will make it possible to recycle
through the DATA list beginning with the first DATA statement.
The RESTORE statement is of the form:
(line number) RESTORE
An example of its use follows: 15 READ B,C,D

55 RESTORE
60 READ E,F,G

80 DATA 6,3,4,7,9,2

100-END
6-23

The READ statements in lines 15 and 60 will both read the first
three data values provided in line 80. (If the RESTORE statement
had not been inserted before line 60, then the second READ would
pick up data in line 80 starting with the fourth value.)
The programmer may use the same variable names the second
time through the data or not, as he chooses, since the values are
being read as though for the first time. In order to skip unwanted
values, the- programmer may insert replacement, or dummy variables. Consider:

1 REM -

PROGRAM TO ILLuSTRATE USE OF REST ORE

20 READ N
25 PRINT "VALUES OF X ARE: I t
30 F OR I 1 TON
40 READ X
50 PRINT X,
60 NEXT I
70 RESTORE
80 READ M
185 PRINT
"190 PRINT "SECCND LIST OF X VALUES"
200 PRINT "FG..LOWING RESTORE STATEMENT:
2 1 0 F OR I 1 TON
220 READ X
230 PRINT X,
240 NEXT I
250 DATA 4~!.!' 2
251 DATA 3",4
300 Eo"'lD

READY
RLNNH
VALUES OF X ARE:
1 2 3
SEC(ND LI5T OF X VALuES
FCLLOWING RESTORE STATEMENT:

)

READY

6-24

The second time the data values are read, the first X picks up the
value originally assigned to N in line 20, and as a result. OS/8
BASIC prints:
2

To circumvent this, the programmer could insert a dummy variable
which would pick up and store the first value,·. but would not be
>represented in ·~the PRINT 'statement, -in which case the output
would be the same each time through the list.

Control Statements
Certain control statements cause the execution of a program to
jump to a different line either unconditionally or depending upon
some condition within the program. The following statements give
the programmer capabilities in this area.
GOTO
The GOTO (or GO TO) statement is an unconditional statement
used to ~ direct program oontrol either forward or backward in a
. program. The form of the GOTO statement is:
(line number). GOTO n
~

where n represents a statement number.· When the logic of the
program reaches the GOTQ statement, the statement(s)- immediately following will not be executed; instead execution is. transferred to the statement beginning with the line number indicated.
, The following program never ends; it does a· READ, prints
something, and jumps back to the READ via a GOTO statement.
It attempts to do th.is over and over until it runs out of data, which
:' -is sbmetimes an acceptable, though not adv!sable, way to end a
program.
10 REM - PROGRA."1 ENOl NG WI TH ERR OR
11 REM - MESSAGE WHEN· OUT OF DATA
20 READ X

25 'PRINT "X=";X"

"Xt 2=";Xt 2

30 GO TO 20
35 D.oTA 1,,5,,10..t5,2e. .. 25
40 END

6-25

READY
RlJNNH
X= 1
X= 5
X= 10
X= 15
X= 20
X= 25

Xt
Xt
Xt
Xt
Xt
Xt

2= 1
2= 25
2= }0e,
2= 225
2= 400
2= ,625

READY

IF-THEN and IF-GOTO
If a program requires that two values be compared at some
point, control of program execution may be directed to different
procedures depending upon the result of the comparison. In computing, values are logically tested to see whether they' are equal,
greater than, less than another value, or possibly a combination of
the three. This is accomplished by use of the relational operators.
IF-THEN and IF-GOTO statements allow the programmer to
test the relationship between two variables, numbers, or- expressions. Providing the relationship described in the IF statement is
true at the point it is tested, control will transfer to the line numbers specified. If the relationship described in the IF statement is
not true at the puint it is tested, control will transfer to the line
following the IF statement. The statements are of the form:

G~~O}

(line number) IF vI v2 .{
.
THEN

where vI and v2 represent variable names, numbers, or expressions, and x represents a line number. The use of either THEN or
GOTO is acceptable.
In the following example, the value of the variable A is changed
or remains the same depending on A's relation to B.
100 IF A>B THEN 120
110 A=A l' B-1
120 C=A/D

6-26

·. When using non-integer arithmetic in the IF-THEN statement,
the test for zero may not always be appropriate due to the nature of
the ~oating-point arithmetic used by the cemputer. To aveid this
preblem, the pregrammer sheuld either aveid using nen-integer
arithmetic in the IF-THEN statement, or test fer fractienal values
. less than the telerance desired and set the value te zero.
IF-THEN statements that test the running variable in FORNEXT loops (see the next section) are particulariy sensitive te this
preblem. Fer example:
10 FOR A=-5 TO 5 STEP.1
20 IF A=O THEN 50
30 NEXT A
40 STOP
50 PRINT "EQUAL TO ZERO"
60 END
The abeve pregram will never ge to line 50.

LOOPS
Frequently programmers are interested in writing a program in
which one ,or mere pertions are executed a number of times,
usually with slight variations each time. Te write the simp~est program in which the portion of the pregram te be repeated is written
just ,once, a loep is used. A leep is a bleck ,of instructions that the
computer executes repeatedly until a specified terminal conditien
is met. BASIC prevides two statements te specify a leop: FOR and
NEXT.
FOR and NEXT Statements
The FOR statement is of the ferm:
(line number) FOR v=xl TO x2 STEP x3
where v represents a variable name, and x I , x2, and x3 all represent "
'expressiens (a numerical value, variable name" ,or mathematical expression). v is termed the index, xl the initial value, x2 the terminal
value, and x3 the incremental value. Fer example:
15 FOR K=2 TO 20 STEP 2
This means that the loep will be repeated as leng as K is less than
,or equal to 20. Each time threugh the loop, K is incremented by 2,
so the loop will be repeated a total of 10 times.
6-27

-""

A variable used as an index in a FOR statement must not be
subscripted, although a common use of loops is to deal with subscripted variables, using the value of the index as the subscript of
a previously'defined variable (this is illustrated in the section concerning Subscripted Variables).
The NEXT statement is of the form:
(line number) NEXT v
and signals the end of the loop. When execution of the loop reaches
the NEXT statement, the computer adds the STEP value to the
index and checks to see if the index is less than or equal to the
terminal value. If so, the loop is executed again. If the value of. the
index exceeds the terminal value, control falls through the loop ~o
the statement following the NEXT statement, with the value of the
index equaling the value it was assigned the final time through the
loop.
If the STEP value is omitted, a value of + 1 is assumed. Since
+ 1 is the usual STEP value, that portion of the statement is
frequently omitted. The STEP value may also be a negative number.
The following example illustrates the use of loops. This loop is
executed 10 times: the value of I is 10 when control leaves the
loop. + 1 is the assumed STEP value.
READY
1 0 I' OR 1

TO 1 0

20 NEXT I
30 PEINT I
40 END
RUNNH

10
READY

If line 10 had been:
10 FOR 1=10 TO 1 STEP -1

the value printed by the computer would be 1.
6-28

As indicated earlier, the numbers used in the FOR statement
are expressions; these expressions are evaluated upon first encountering the loop. While the index, initial, terminal, and STEP values
may be changed within the loop, the value assigned to the initial
expression remains as originally defined until the terminal condition is reached. To illustrate this point, consider the last example
program. The value of I (in line 10) can be successfully changed as
follows:
10 FOR 1=1 TO 10
15 LET 1=10
20 NEXT 1
The loop will only be executed once since the value 10 has been .
reached by the variable I and the terminal condition is satisfied.
If the value of the counter variable is" originally set equal to the
terminal value, the loop wjll execute once, regardless of the STEP
value. If the starting value is beyond the terminal value, the loop
will never execute because an initial check is made of the starting
and terminal values before the loop is executed. The following
statement is executed but the loop it describes would never" be
executed:
10 FOR 1=10 TO 20 STEP-2
It is possible to exit from aFaR-NEXT loop without the index
reaching the terminal value via an IF statement. Control may only
transfer into a loop which has been left earlier without being completed, ensuring that the terminal and STEP values are assigned.
Nesting Loops
It is often useful to have one or more loops within a loop. This
technique is called nesting, .and is allowed as long as the field of
one loop (the numbered lines from the FOR statement to the corresponding NEXT statement, inclusive) does not cross the field of
another loop. A diagram" is the best way to illustrate acceptable
nesting procedures:
ACCEPTABLE NESTING
TECHNIQUES

UNACCEPTABLE NESTING
TECHNIQUES

Two Level Nesting
FOR
FOR

FOR
FOR

[ ~~~;
[

[NEXT
FOR
[ [
NEXT

6-29

UNACCEPTABLE NESTING
TECHNIQUES

ACCEPTABLE NESTING
TECHNIQUES

Three Level Nesting

rrC

FOR

IIC~~~T
[

'L
I

FOR
FOR
FOR

I.I LfFOR
NEXT

FOR

NEXT
NEXT
NEXT

,-NEXT

LISTS AND TABLES
Subscripted Variables
In addition to single variable names, OS/8 BASIC accepts
another class of variables called subscripted variables. Subscripted
variables provide the programmer with additional computing
capabilities for handling lists, tables, matrices, or any set of related
variables. Variables are allowed one or two subscripts. A single
letter or a letter followed by a digit forms the name of the variable;
this is followed by one or two integers in parentheses and separated
by commas, indicating the place of that variable in the list. Up to
31 arrays are possible in any program, subject only to the amount
of core space available for data storage. For example, a list might
be described as A(I) where I goes from 1 to 5~ as follows:

A(l ),A(2),A(3),A(4),A(5)
This allows the programmer to reference each of the five elementsin the list A. A two dimensional matrix A(I,J) can be defined in a
similar manner, but the subscripted variable A can only be used
once (i.e., A(I) and A(I,J) cannot be used in the same program). It
is possible, however, to use the same variable name as both a subscripted and an unsubscripted variable. Both A and A(I) are valid
variable names and can be used in the same program.
Subscripted variables allow data to be input quickly and easily,
as illustrated in the following program (the index of the FOR
statement in lines 20, 42, and 44 is used as the SUbscript):
6-30

42 fOR 1=1 TO 2
LI ST
BA

BAS16
10
11
15
16
20
25
30
35
38
39
L!0

41
42
43
44
48
50
55
56
60
61
65

18-MAR-7 L!

REM - PROGRAM DEMCNSTRATING .READING
REM - Of SUB~CRIPT£D VARIABLES
DIM A(5).rB(2 1 3).
PRINT "An) WHERE A= 1 TO 51"
f OR I = 1 TO 5
READ A( I)
PRI NT A( I ) 1
NEXT I
PRINT
PRINT
PRINT "B( I IJ) WHERE 1=1 TO 2:"
PRINT"
AND J= 1 TO 3:"
f OR I = 1 TO 2
PRINT
fOR J= 1 TO 3
READ B(IIJ)
PRINT B

6
8

7
7

~~HERE

1= 1 TO 2:
AN D J= 1 TO 3:

8
6

READY

The DIM Statement

From the preceding example, it can· be seen that the·use of
subscripts requires a dimension (DIM) statement to define the
maximum number of elements in the array. The DIM statement is
of the form:
(line number) DIM vI(n l ), v2 (n 2 ,m 2 )
where v indicates an array variable name and nand m are integer
. numbers indicating the largest subscript value required during the
program. For example:
15 DIM A(6,10)
6-31

The first element of every array is automatically assumed to have
a subscript of zero. Dimensioning A( 6, 10) sets up room for an
array with 7 rows and 11 c~lumns. This matrix can be thought of
as existing in the following form:

Ao,o Ao,l ... Ao,lO
Al,o Abl ... A blO
A 2 ,o A 2,l ••• A 2,lO

A 6 ,o A6 ,l ... A6 ,10
and is illustrated in the following program:
10
15
20
22
25
28

REM
Dl M
FOR
LET
FOR
LET

- MATRIX CHECK PROGRAM
A< 6, 10}
1=0 TO 6
A.;

To obtain random numbers which are integers from 5 to 24~
inclusive, the user can change line 20 to the following:
20 PRI N T I NTC 20* RND

(X)

+ 5>.;

If random numbers are to be chosen from the A integers of which

B is the smallest, the use.r can call for INT(A*RND(X)+B).
The RANDOMIZE Statement
As noted in the example program, the same numbers in the same
order resulted both times the program was run. However, a different set will be produced with the RANDOMIZE statement, as in
the following program:
5 RAN D0'-1 I Z E
10 FOR L= 1 TO 20
20 PRINT INT( 10*RNDeX»;
30 NEXT L
40 END
READY

6-35

RUNNH
0 7
READY
RUNN.H
1

READY

RANDOMIZE resets the numbers based on elapsed time spent
waiting for terminal I/O. For example, if RANDOMIZE appears
after a' PRINT or INPUT instruction but before a statement with
the RND (X) function, then repeated RUNs of the program produce different results. If the instruction is absent, then the official
list of rando~ numbers is obtained in the usual order. It is suggested that a simuJated model should be debugged without this
instruction so that one always obtains the same random numbers
in test runs. After the program is debugged, and before starting
production runs, the user inserts the following:

(line number)

RANDOMIZE

at the appropriate place in the program.
THE SIGN FUNCTION - SGN (X)
The SGN function is one which assigns the value 1 if the argument is any positive number, if zero, and -1 if any negative number. Thus, SGN (7.23) = 1, SGN (0) = 0, and SGN (-.2387) =1.
For example, the following statement:

25 LET X=SQR (A l' 2+2*B*C) *SGN (A)
assigns the sign of X to the sign of A.
6-36

TI:IE INTEGER FUNCTION - INT (X)
The integer function returns the value of the nearest integer not
greater than X. For example, INT (34.67) = 34. By specifying
INT (X +.5) the INT function can be used to round numbers to
the nearest integer; thus, INT (34.67+.5) '= 35. INT can also be
used to round numbers to any given decimal place by specifying:

, INT (X*10tD+.5)/10tD
where D is the number of decimal places desired. The following
program illustrates this function; execution has been stopped by
typing a CTRL/C:
10
20
30
40
50
60
70
80
9 0-

REM - I N T fUN CTI ON EX AM PL E
PRI NT "NUMBER TO BE ROUNDED"';
INPUT A
PRINT ''NO. OF DECIMAL PLACES:".;
INPUT 0
LET B=INTCA* 10fD+. 5)/10tD
PRINT "A ROUNDED =".;B
GO TO 20
END

READY
RUNNH
NUMBER TO BE ROLNDED?55.65342
NO. Of DECIMAL PLACES:?2
A ROUNDED
55. 65
NUMBER l' 0 BE ROUN DED?7 8.375
NO. Of DEC! MAL PLACES:?- 2
A ROUNDED = 100
N.UMBER TO BE ROUNDED?67.89
NO. OF DECI MAL PLACES:?- 1
A ROUNDED = 70
NUMBER TO BE ROUNDED?tC
READY

If the argument is a negative number, the value returned is the

largest negative integer (rounded to the higher' value) contained
in the number. For example, INT (-23) =-23 but INT (-14,39)
=-15.
THE ABSOLUTE VALUE FUNCTION - ABS (X)
The absolute value function is used to obtain the absolute
(positive) value of an expression. For example:

6-37

5 PRI NT ABS( - 66)
10 END
READY
RUNNH

66
READY

THE SQUARE ROOT FUNCTION - SQR (X)
The square root function is used to compute the square root of
an expression. For example:
5 LET B=4'A=2.5,C=.5
10 PRINT SQR
20 END

RUNNH
3.31662
READY

If the argument of the SQR (X) function is <0, the absolute value
of the argument is used.
Transcendental Functions

THE SINE FUNCTION - SIN (X)
The sine. function is used to calculate the sine of an angle specified in radians. For example:
5

REM -

CALCULATE SINE 30 DEGREES

10 LET P= 3. 14159
20 PRINT SINC30*P/180)
25 END
RUNNH
0.5
READY

THE COSINE FUNCTION-.COS(X)
The cosine function is used to calculate the cosine of an angle
specified in radians. For example:
5
REM - CALCULATE THE CbSINE OF 45 DEGREES
10 PRINT COS<45*3.14159/1:30)
20 END
RUNNH
0.707108
READY

6-38

THE ARCTAN FUNCTION-ATN(X)
This function calculates the angle (in radians) whose tangent is
given as the argument of the function. For example:
5 REM ~ CAL CULATE ATNe. 57735>.
10 PRINT ATN(.57735>
20 END
RUNNH
0. 523598
READY

THE EXPONENTIAL FUNCTION-EXP(X)
The EXP(X) function calculates the value of e raised to the X
power, where e is equal to 2.71828. For example:
5 REM - CALCULATE EXPONE."lTIAL VALLJE OF 1.5
10 PRINT EXP( 1.5)
20 END
RUNNH
4.48169
READY

THE NATURAL LOGARITHM FUNCTION-LOG(X)
The LOG (X) function calculates ,the natural logarithm of X.For
example:
5 REM - CALCULATE THE LOG OF 959
10 PRINT LOO(959)
20 END
RUNNH
6.86589
READY

User Defined Functions
THE FNA(X) FUNCTION AND THE DEF STATEMENT
In addition to the standard functions OSj8 BASIC provides, the
user may define up to 26 functions of his own with the DEF statement. The name of the defined function must be. three letters, the
first two of which are FN, e.g., FNA, FNB, ... , FNZ. Each DEF
statement introduces a single. function and is of the form:
6-39

(line number) DEF FNA(X)=expression (X)
where A may be any letter and X is a dummy variable, but must be
the same on each side of the equal sign. The DEF statement may
appear anywhere in the program so long as it appears before the
first use of the function it defines. The function itself can be defined
in terms of numbers, several variables, other functions, or mathematical expressions. For example, if the user repeatedly uses the
function e-x2 +5, he can introduce the function by the following:
30 DEF FNE(X)=EXP( - X t 2)+5
and call for various values of the function by FNE(.l), FNE(3.45),
FNE(A+2), etc. This statement saves a great deal of time when the
user needs· values of the function for a number of different values
.
..
of the varIable.
The statement:
DEF FNA(S}=S t 2
will cause the later statement:
20 LET R=FNA(4) + 1
to be evaluated as R= 17 .
The user-defined function can be a function of-lliore th3J."1 one vari-

able, as shown below:
25 DEF FNL(X, Y,Z,)~QR(X t 2+Y t2+Z t 2)
A later statement in a program containing the above function might
. appear as follows:
55 LET B=FNL(D,L,R)
where D, L; and R have been defined in the program.
THE UDEF FUNCTION'CALL AND THE USE STATEMENT
OS/8 BASIC has the capability for adding one or more usercoded assembly language functions. These user functions may use
. four numeric and two string arguments 'and once properly interfaced to OS/8 BASIC, 'they can be used as any other OS/8 BASIC
,function. Complete instructions for writing and interfacing such
~

6-40

functions are provided later in this chapter. A user-coded function,
if present, is specified in an OS/8 BASIC program as:
(line number) UDEF function name argument)
For example:
10 LET R=4
15 LET B=6
20 LET 0=10
25 UDEF PLT(X,Y,Z)
30 LET D=PLT(R, B,O)
35 PRINT 4*D
40 END
-Line 25 introduces the function PLT to OS/8 BASIC and indicates
the number and. type of arguments associated with· the function .. In
line 30 the function is used as any other standard. function might be
used in an OS/8 BASIC program. If the function requires the use
of an array, a USE statement identifying the array must precede the
statement that calls the function.
10 DIM S(15,5)

20 LET 0=10
_ 22 USE S
..
25 UDEF PLT(X,Y,Z)

NOTE
A UDEF function name may consist of alphabetic characters only and must have at
least one argument (a dummy argument if
necessary).

6-41

The Debugging Function~TRC(X)

The TRC(X) function is used by the programmer to follow the
progress of a program and is, therefore, a useful debugging aid. The
form of this function is:
(line number) vl=TRC(X)
where vI is a dummy variable, X=l turns the function on and x=o
turns the function off. When TRC(!) is encountered in a program,
OSj8 BASIC prints the line number of each line in the program as
it is executed. The line numbers are printed between a pair of percent signs so as to be distinguishable from other material that is
printed by the program. Program execution time is slowed down
considerably to accommodate the function and the extra printing
which it causes. When TRe(O) is encountered by the program the
function is turned off and normal program operation resumes.
The following example shows the effect of using the TRC(X)
function in a program to check the operation of a loop. The same
program with the TRC(X) function removed from the program, is
also shown.
With TRC(X) Function
5 REM BASI C
6 REM FACTORIAL PROGRAM
10 FOR J= 1 TO-5
20 GOSUB 60
30 NEXT J
40 STOP
60 LET S= 1
62 T=TRCe 1)
6 5 F OR K = 1 TO J
70 LET S= S*K
75 NEXT K
77 T= TRCe 0)
80 PRINT JI S
85 RETURN
90 END
READY
RUNNH

% 65 %
% 70 %
% 77 %
1

% 65 %

Without TRC(X) Function
5 REM BASI C
6 REM FACTORI AL PROGRAM
t 0 FOR J = 1 T 0 5
20 GOSUB 60
30 NEXT J
40 STOP
60 LET S= t
65 FOR K = 1 T 0 J
70 LET S=S*K
75 NEXT K
80 PRINT JI S'
85 RETURN
90 END·
READ.Y
RLNNH
1
2
3
4
5
READY

% 70 %
% 10 %
% 17 %

6-42

2
6
24
120

With TRC(X) Function
2
% 65
% 70
% 7 @
% 70
% 77
3
% 65
% 70
% 70
% 70
% 7'"
% 77
4
% 65
% 7JZJ
%
% 7 '"
% 70

2
%
%
%"
%
%

6
%
%
%
%
%
%

%
%
%
%
%
%
% 7 '"
% 77 %

7'"

120

READY

Subroutines
• A subroutine is a part of the protfam performing some operation
that is required at more than one point in the program. Subroutines
are gene~ally placed physically at the end of a program, usually
before DATA statements, if any, and always before the ~ND statement.
GOSUB AND RETURN
Two statements are used exclusively in OS/8 BASIC to handle
subroutines; these are the GOSUB and RETURN statements.
When a program encounters a GOSUB statement of the form:
, (line number) GOSUB x
where x represents the first line number of the subroutine, control
then transfers to that line. For example:

50 GOSUB 200
When program execution reaches line 50, control transfers to line
200; the subroutine is processed until execution encounters a
6-43

RE TURN statement of the form:

(line number) RETURN
,-

which causes control to return to the statement following the
GOSUB statement. Before transferring to the subroutine, OS/8
BASIC internally records the next statement to be processed after
the GOSUB statement; thus the RETURN statement is a signal to
transfer control to this statement. In this way, no matter how many
different subroutines are called, or how many times they are used,
OS/8 BASIC always knows where to go next.
The following program demonstrates a simple subroutine:
1 REM - THIS PROGRAM ILLuSTRATES GOSUB AND RETURN
10 DtF FNA(X)=A8S
50 LET B=FNA( B)
60 LET C=FNA( C)
70 PRINT
80 GOSUB 100
90 STOP
100 REM - THI S SUBROUTINE PRINTS OUT THE Sa.. UTI O\JS
110 REM - OF THE EQUATICN: A(Xt2>+8(X)+C=0
120 PRI NT "TH E EQUATI CN
S"J AJ ','*X t 2 + "; B; "*X + "; C
130 LET D=B*B-4*A*C
140IF 0<>0 THEN 110
150 pRiNT H()\jL't (N£ SCLLJllCN ••• )(=;;;-fj/(2*A)
160 RETURN
170 IF D<0 THEN 200
180 P~I NT "TWO SOLUTI eN S ••• x
to;
185 PRINT C-B+SQRCO»/(2*A>J"AND X=";(-B-SQR(D»/(2*A)
190 RETURN
200 PRINT "IMAGINARY SOLUTI eNS ••• x = C to;
205 PRINT -B/C2*A>;"I";5QRC-D)/(2*AH") AND (to}
207 PRINT -B/(2*A>J"l to ;-SQR(-D)/(2*A>;")"
210 RETURN
900 END

READY
RUNNH
? 11.51 -. 5
THE EGUATIO\! IS 1 *Xt2 +
0.5 *X + -0.5
TWO sa..UTI CNS ••• x = 0.5 AND X=-l
THE EQUATION IS 1 *Xt2·+
0 *X +
IMAGINARY $OLUTI 0\15 ••• X = ( 0 I
READY

6-44

1 )

AND (

0 1-1 )

Line 100 begins the subroutine. There are several places in which
control may return to the main program, depending upon a certain
condition being satisfied. The subroutine is executed from line 30
and again from line 80. When control returns to line 90, the program encounters the STOP statement and execution is terminated.
It is important to remember that subroutines' should generallY be
kept distInct from the main program. The last statement in the main
program should be a STOP or GOTO statement, and subroutines
are normally placed following this statement.
More than one subroutine may be used in a single program in
which case these can be placed one after another at the end of the
program (in line number sequence). A useful practice is to assign ,
distinctive line numbers to subroutines. For example, if the main
program is numbered with line numbers up to 199, 200 and 300 '
could be used as the first numbers of two subroutines.
NESTING SUBROUTINES
Nesting of subroutines occurs when one subroutine calls another
subroutine. If a RETURN statement is encountered during execution of a subroutine, control returns to the statement following the
GOSUB which called it. From this point, it is possible to transfer
to the beginning or a~y part of a subroutine, even back to the calling subroutine. Multiple entry points and RETURN statements
make subroutine"s more versatile.
The maximum level of GOSUB nesting is ten levels; which'
should prove more than adequate for all normal uses. Exceeding
this limit results in the message:
GS AT LINE YYYYY
where YYYYY represents the line number where the error occurred. An example of GOSUB nesting follows (execution has been
stopped by typing a CTRLjC, as the program would otherwise
continue in an infinite loop).
10 REM FACTORIAL PROGRAM USING GOSU8 TO
15 REM COMPUTE RECURSIVELY THE FACTORS
40 INPUT N
50 IF N>'20 THEN 120
60 X= 1
70 K= 1
80 GOSUB 200
90 PRINT "FACTORIAL";N;"=",;X
110 GOTO 40

6-45

120
130
200
210
. 220
225
227
230

PRI N T "MU ST BE 20 OR LESS"
GOTO LIe;
I F N 1 TH EN 230
N=N- 1
G OSUB 200
N=N+ 1
X=X*N
RETURN
2L1" END

READY
RUNNH

?2
FACTOR! AL 2 = 2
?LI

FACTOR! AL LI = 2L1

?5
FACTORi AL

120

?f C

READY

ALPHANUMERIC INFORMATION (STRINGS)
In previous sections .we have dealt only with numerical information. However, OS/8 BASIC also processes, or manipulates, alphanumeric infonnation called strings. A string is a sequence of
characters, each of which is a "letter, a digit, a space, or some
character other than a statement terminator (backslash or carriage
return).
String Conventions
CONSTANTS AND VARIABLES
Strings may appear as constants or variables just as numerics
may. We have already used string constants in PRINT statements.
For example:
100 PRINT "THIS IS A STRING CONSTANT"
where the alphanumerics enclosed in quotes are the string constant.
Naming a string variable is similar to naming a numeric variable.
It consists of a letter followed by a dollar sign ($) or a letter and a
single digit followed by $. A$ and Al $ are both legitimate string
variable names; 2A$ and ~A$ are not legitimate string variable
names.
DIMENSIONING STRINGS
OS/8 BASIC assumes that a string l~ngth is 8 characters or less
unless a string has been dimensioned in the form:
10 DIM A$(I)
6-46

where "I" is the length of string variable A$. "I" cannot exceed 72.
String lists (equivalent to single subscripted numeric variables)
are permitted in OSj8 BASIC and must be dimensioned in the
form:
20 DIM A$(K,L)

where K is the number of strings in the list and L is the length of
each string.
When referencing a subscripted string variable in a LET or IFTHEN statement, for example:
25 LET B$(I)

= "YES"

the expression I represents the place of that string variable in the
list B$.
Double subscripted string variables (string tables) are not permitted
in OSj8 BASIC.
INPUTTING STRING DATA
String data may be included in a DATA list but must always be
enclosed by quotation marks. In fact any stnng written into a program must be enclosed by quotation marks to be recognized by the
OSj8 BASIC Compiler.
10 READ A$,B$,C$
20 PRINT C$;B$;A$
25 DATA "NG","RI","ST"
30 END

The program above prints STRING.
Quotation marks may be included in strings by indicating 2 quotation marks in succession. For example the string A"B would
appear in a program as:
10 LET A$= "A" "B"

Both string data and numeric data may be intermixed in a DATA
list but the burden falls on the programmer to assemble the list in
the correct sequence, since all READ statements for both string and
numeric data remove data serially from the DATA list. If he does
not: the results of the READ statement are unpredictable.
The INPUT statement may also be used for inputting string data
to a program. Quotation marks are not necessary when inputting
6-47

string data in response to the question mark (?) generated by the
INPUT statement unless the quotation marks are deliberately
meant to be part of the string.

330 PRINT "DO YOU-WISH TO CONTINUE?"
340 INPUT A$
350 IF A$="YES" THEN 410
360 PRINT "ARE YOU SURE?"
370 INPUT B$
.
380 IF B$="NO" THEN 410
390 PRINT "PROGRAM STOPPED"
400 STOP
410 PRINT "LET'S CONTINUE"

490 END
Each string literal requested by an INPUT statement must be terminated by a carriage return which acts as the data delimiter. This
is necessary since all characters, except for the carriage return, are
recognized as part of the data string.

10 INPUT A$.,BS.,C$

RLNNH
?ABCD

?EFGH
?IJ

In the above example A$'="ABCD", B$="EFGH" and C$="IJ".
6-48

STRINGS IN LET AND IF-THEN STATEMENTS
Strings may be . used in both LET and IF-THEN· statements as
already indicated by some of the previous examples. Any of the
relational operators may be used in an IF-THEN statement to compare strings. Strings are compared on the basis of the ASCII numeric value of each character in the s~ing.
When comparing strings in an IF-THEN statement, the relational
operators have the following significance:
Operator

Meaning

earlier in ASCII numeric order than
>
later in ASCII numeric order than
=< or <= same ASCII numeric order as or earlier,
in ASCII numeric .order than
same ASCII numeric order
>< or <> different ASCII numeric order than
=> or >= same ASCII numeric order as or later in
ASCII numeric order than

For example:
10 IF "ABCD"<"ABC@" THEN 50
20 STOP

50 LET A$="ABCD"
Each character in string ABCD is compared, left-to-right, with
the respective character in string ABC @. A, B, and C match but D
and @ do not. The character @ has a lower numeric value than
the character D. Therefore the string ABCD is not earlier in ASCII
numeric sequence than ABC@ and the program stops at line 20.
If the strings in an IF-THEN comparison are of unequal length,
then OS/8 BASIC lengthens the shorter string to make it equal in
length to the longer string by appending an appropriate number of
ASCII space characters. In the following example:
6-49

10 IF "ABCD"<"AB" THEN 50
20 STOP

50 LET A$="ABCD"
string "AB" is treated as "ABuu". Since the character C is earlier
in, ASCII numeric order than the character "space," the IF-THEN
statement is true and control is transferred to line 50.
STRING CONCATENATION
Strings can be concatenated by means of the operator ampersand
(&). The ampersand can be used to concatenate string expressions
wherever a string expression is legal, with the exception that information cannot be stored by means of a LET statement in concatenated string variables. That is, concatenated string variables cannot
appear to the left of the equal sign in a LET statement. For example, LET A$=B$&C$ is legal, but LET A$&B$=C$ is not. An
example of string concatenation is:
10 READ A$,B$,C$
20 PRINT C$&B$&A$
25 DATA "NG," "RI," "ST"
30 END
Running this program causes STRING to be printed.
String Handling Functions

A number of functions have been implemented that perform
manipulations on strings. These functions are LEN, ASC, CHR$,
VAL, STR$, POS, SEG$, and DAT$. Functi"ons that return strings
have names that end in a dollar sign ($J; those functions that return
numbers have names that do not end in a dollar sign.
THE LEN FUNCTION
The LEN function returns the number of characters in a string.
It has the form:
LEN(X$)
6-50

•

Example:
SCRATCH
EEADY
5DIMBH10)
10 READ A$,8$
20 PRINT LEN( Ai.&ESl&"AROU\lD")
30 DATA "UP, .. , "DOWN, A\)D "
4el END
RU\j:\jH

216
FEADY

•

TRE ASC AND CRR$ FUNCTIONS
The ASC and CRR$ functions perform conversion from and to
ASCII, respectively. The ASC function converts a one character
string to its ASCII decimal equivalent, and the CRR$ function converts a decimal number to its equivalent ASCII character.
The ASC function has the form:
ASC (argument)
The argument is a one character string. ASC returns tne equivalent
ASCII decimal number for the character.
The CRR$ function has the form:
CRR$ (numeric expression)
The value of the numeric expression is truncated to an, integer
that is in the range 0 tQ 63. Integers greater than 6,3 'are treated
modulo 64. That is, they are divided by 64 and the remainder becomes the new integer. This integer is then interpreted as an ASCII
decimal number that is converted to its equivalent character (refer
to Appendix A for the ASCII decimal numbers and the equivalent
characters) .
An example of the ASC and CRR$ functions follows:
5 FOR T=ASC( "A") TO ASC< "A") + 3
10 PPINT "THIS IS TEST "&CHRSCT>
15 NEXT T
20 END

6-51

This is the beginning of a FOR loop that successively prints:

R EtlDY

RUNNH

THIS I~
THIS IS
TH I SIS
TH I SIS

TEST
TEST
T EST
T EST

A
B
C
0

READY

THE VAL AND STR$ FUNCTIONS
The VAL and STR$ functions perform conversions from strings
to numbers and numbers to strings. The form of the VAL function
IS:

VAL (string expression)
The string expression must look like any number which may be
legally typed in response to an INPUT statement. VAL returns the
actual number that the string represents. The VAL function does
not return the ASCII value of the number that the string represents,
it returns the number. For example, VAL ("25") returns the number 25. The 25 that is the argument to VAL is a string, the 25
that VAL returns is a number.
Example:
10 INPUT A$
20 PRINT VAL(tI~)*2

25 END
READY

RUNNH
?2. Ll61 t t
4.92222
READY

6-52

The STR$ function retur:ns the string representation (as a number) of its argument. The form of STR$ is:
STR$ (numeric expression)
The string that is returned is in the form in which numbers are output in BASIC. For example, PRINT STR$(l.76111124) prints the
string 1:7611l.
THE POS FUNCTION
The 'POS function is of the form:
POS(X$,Y$,Z)
The function returns the location in string X$ of the first occurrence of string Y$ starting with Zth character in string X$. For
example:
20 LET X$="MONDAY"
25 LET X=POS(X$,"DAY,"1)
After line 25, X will be equal to 4. The arguments of the POS function may be constants, variables, or expressions.
The following rules apply in evaluating the POS(X$,Y$,Z) function~
1. If Y$ is a null string (no characters) then
POS(X$, Y$ ,Z)= 1
2. If X$ is a null string (no characters) then
POS(X$, Y$ ,Z)=O
3. If Z is less than zero or greater than the actual string length, a
fatal ef!or (PA) is detected and program execution stops
4. If Y$ is not found, then
POS(X$,Y$,Z)=O
THE SEG$ FUNCTION
This function is of the form:
SEG$(X$,Y,Z)
The function returns the substring of X$ which is between positions Y and Z inclusively. For example:
20 LET X$="MONDAY"
25 LET B=6
30 LET A$=SEG$(X$,2*B/3,B)
After line 30, A$ is equal to "DAY". The arguments of the SEG$
function mOay be variables, constants, or expressions.
6-53

The following rules apply in evaluating the SEG$(X$,Y,Z) function.

1. If Y~O, Y is set equal to 1
2. If Y> length X$, then SEG$(X$,Y,Z)
null string (no
characters)
3. If Z~O, then SEG$(X$,Y,Z) = null string
4. If Z > length X$, then Z is set equal to length of X$
5. If Z

1
2000
0000
2
2000
0000

CO UNT STRING_

FIELD N

DLSTRT

POINTER TO DATA lIST-1
POINTER TO LAST
WORD IN DATA LIST
FIELD

7773
24

} "THREE"

3
2000

0000

THE STRING ACCUMULATOR (SAC)
All BRTS string operations use the String Accumulator (SAC)
as one of the operations, and the result is always left in the SAC.
The string accumulator is to strings as the hardware AC is to
PDP-8 instructions. The SAC starts at location SAC for 36 words
(72 characters), and the length of the string currently in the SAC is
stored as a negative number in STRLEN. A page 0 pointer to the
start of the SAC less 1 is maintained at SACPTR.
BRTSSYlIlbol Table Structure
The BRTS symbol tables all reside in the highest core field. A
CDP to the symbol table field can be found in location CDPIO of
field O.

6-76

THE SCALAR TABLE
The Sca!ar Table is the highest symbol table in core, and it con-sists of successive three-word entries, each entry containing a 3 word floating-point number. One entry exists for each variable used
in thep'rogram, and a few extra entries are used as temporaries.
A pointer to the start of the Scalar Table can be found at location
SCSTRT of field O. The scheme for scalar variables is as follows:
FIELD 0
POINTER TO
SCALAR TABLE

SCSTRT

CDFIO

CDF X

~
I

FIELD X

SCALAR
TABLE

~--_~+~E=XP~--~
~ HI MANT

LOWMANT

THE ARRAY SYMBOL TABLE
The Array Symbol Table consists of successive 4- word entries,
each entry specifying the location and size of an array used in the
program. Each entry is as follows:

POINTER TO A(O,O)
CDF TO FIELD OF A (0,0)
DIMENSION 1
DIMENSION 2

The first word of each entry is a 12-bit pointer to the location of
the exponent word of the first element in the array. The second
word is a CDF N where N is the field for the pointer in the first
word. The third word is the first dimension of the array (obtained
by adding 1 to the M in a DIM A(M,N) statement because the
6-77

.first subscript is always 0), and the last word is the second dimension of the array (obtained by adding 1 to the N in the aforementioned DIM statement for the same reason). If the array is unidimensional, the second dimension is zero. To locate the ntll
element in the array, BRTS performs the following calculation:
Addr of A(M,N)=3*[M+(DIMI + 1)*N]+Addr of A(O,O)
A pointer to the start of the Array Symbol Table less 1 (for use
in an index register) can be found in field at location ARSTRT.
The scheme for arrays is:

I POINTER
COFIO I COF X

ARSTRT
FIELD 0

TO ARRAY T A-1
S:JLE

START OF ARRAY ...... - - - - - - - - ----,
I
SYMS OL TABL~ II

}NMI
POINTER TO A/O,O)

---I~.1

I ~ ENTRY 2

COF Y
ARRAY SYMBOl i-----=-=-----11
M+!
iABLE ii'iELD X)

+_1_----11 J

A(O,O)

MU ,,"

r-'\\I",I',

'---_ _
N

THE STRING SYMBOL TABLE
The String Symbol Table has successive three-word entries as
follows:
POINTER TO STRING
COF FOR STRING
-MAXIMUM #OF CHARS IN STRING

6-78

The first word is a 12-bit pointer to the count word of the string.
The second word of each entry is a cnp for that count word, and
the third word of the entry is the maximum length of the string (in
number of characters) stored as a two's complement negative number. A pointer to the start of the String Symbol Table (less 1) can be
found in field 0 location STSTRT. Note that the maximum number
of characters in the string represents the amount of space allocated
for the string; the amount of space actually used is represented by
the count word which is stored with the string.
, The scheme for simple strings is:

STSTRT
FIELD 0
CDFIO

I POINTER TO STRING SYMBOL

I CDF

:r-----

------.....,:__- - - - - J

ENTRY 1 {
STRING
SYMBOL TABLE
(FIELD X).

POINTER TO A$
CDF Y
-MAX LENGTH

COUNT FOR A$

,--

J
ENT,RY 2

STRING A$
(FIELD Y)

INT (MAX,LE NGTH+l )+1
2
WORDS LoNG

THE STRING ARRAY TABLE
The String Array Table consists of consecutive 4-word entries,
with each entry as follows:
POINTER TO A$(O)
CDF FOR A$ (0)
- MAX # OF CHARS IN A$ (0)
DIMENSION OF A$ (0)

The first word contains a pointer to the count word of string
A$(O), and the second word contains a cnp for this count. The
third word has the maximum length (in characters) of each element
6-79

in the array stored as a two's complement negative number. The
last word contains the dimension of the string array, obtained by
adding 1 to the M in a DIM statement of the form DIM A$ (M,N)
because the first element is always A$(O). A pointer to the start of
the String Array Table less 1 can be found in field 0 at location
SASTRT.
The scheme for string arrays is:

it~~~R~

I POINTER TO START OF STR~ING
ARRAY TABlE-l

COflO

~:~~

___

um~

I
I

h
COUNT

ENTRY 1

A$(O)
}

STRING ARRAY
TABLE(FIELD X)

POINTER TO A$ (0)
COf Y
-N
M+l

STRING ARRAY
A$(CM,N)
IFIELD Y)

COUNT
ENTRY 2

A$(l)

}
L

To locate the nth dement of the string array, BRTS performs
the following calculation:

.
(ABS(Z)+ 1)
addr of A$ (N)=addr of A$ (O)+(INT

+ l)*N

where Z '= individual element length.

Floating-Point Operations
The BRTS floating-point package is permanently resident, and
as such it is readily available for use by assembly language routines
for floating-point calculations.
FLOATING-POINT ACCUMULATOR
One of the operands of every floating-point operation is the
Floating Accumulator (FAC), and the result of all floating-point
operations (except FPUT) is always left in the FAc. The FAC is
6-80

found at EXP ~ HORDand LORD on page 0 with standard PDP-8 .
23-bit floating-point format:

EXP
HORD
LORD

HI MANTISSA'
LON MANTISSA
SIGN OF
MANTISSA.

The floating~point accumulator is to floating-point instructions
what the hardware accumulator is to, PDP-8 machine language
instructions.
FLOATING-POINT ROUTINES
The following floating-point routines are available for user subroutine use:
Function

Starting Address Operation

ADD
SUBTRACT
MULTIPLY
DIVIDE
INVERSE SUBTRACT
INVERSE DIVIDE
LOADFAC
STOREFAC

FFADD
FFSUB
FFMPY
FFDIV
FFSUBI
FFDIVI

FAC~FAC+OPERAND

FFG~T

FAC~PERAND

FFPUT

OPERAND~FAC

FAC~FAC-OPERAND
FAC~FAC*OPERAND

FAC~FAC/OPERAND
FAC~PERAND-FAC
FAC~PERAND/FAC

The symbol "~" means "is replaced by" .
Note that the store function (FFPUT) is the only operation in
which the result is not left in the F AC. Note also that FFPUT is a
nondestructive store, i.e., the FAC is the same after the store
operation as before.
There are two calling sequences for the floating-point routines,
each with a different method for passing the address, of the operand.
Mode 1 is the most efficient, and can 'be used whenever the operand
is in field O. Mode 2 is the field independent call, but is more core
expensive than mode 1.
6-81

The mode being used is determined as follows:
1. If the contents of the AC is non-zero on entry, the mode used
is mode 2.
2. If the contents of the AC is zero on entry, the location FF is
examined. If FF is also zero, mode 1 is the calling mode. If
FF is non-zero, mode 2 is used.
The calling modes are as fonows:
:Mode I-address of operand follows call to floating-point routine,

CLA
DCA Ff
JMS I POINTR
(OPEFUND AQUR)
•

ISWITCH FF.~ FOR MODE 1
./JUMP TO FLOATING-POINT ROUTINE
/12 BIT ADORESS OF OPERAND
IRE TURNS HERE

•

POINTR,

•(STARTING

AODR)

IfLOATING-POINT ROUTINE
ISTARTING ADDRESS.

Mode 2-address of operand
routine.

CI.A lAC
CCA H

CD' N
TAD OPAODR
JMS I POtNTR
(UNUSED)

I~f

AC on call to floating-point

SWITC~

NOT EQUAL TO 0 FOR MOO!

10' TO FI!LO 0' OPERAND

IADDRESS 0' OPERAND
IJUMP TO 'I.OATING-POINT ROUTINE
I~HIS LOCATION UNUSED
IRnURNSHERE •
•
POINTR, (STARTING AOOR) IADDRESS 0' 'LOATING-POINT ROUTINE
IADDRESS OF OPERAND
OPADDR, (OPERAND)

Both modes return with a clear 'AC and the data field set to O.
Note that the switch FF is not altered by the routines themselves,
hence it is only necessary to set it when desired to change modes,
not before every call.
6-82

The mode 2 call always returns to the second instruction following the JMS call, skipping the word following the JMS. Since this
word is completely unused, it is a good location for constant
storage.
The FF switch is necessitated by the special case when it is
desired to reference an operand located at location 0- in a field
other than field O. If the FF switch were not present, the floatingpoint package would examine the AC, find it empty, and use the
address in the w9rd. following the call, since there is no way of
distinguishing an empty AC from an operand address of loaded
.into the AC. The FF switch, then, is used to tell the floating-point
package whether the zeroAC means "mode 1 call" or "operand at

0."

· BRTS maintains links for FGET and FPUT on page of field·
0, providing convenient access to these frequently used routines.
Page 0
Link Name

Routine Linked

FGETL
FPUTL

FFGET
FFPUT

Examples:
Some examples of BR:rS floating-point code:
1. Routine to calculate X 2 +2X+ 1

•

CLA
DCA Ff
JMS I fGETL
X
JMS I FMPYLK
X
JMS I· FPUTL

IOPERAND AODRESS wILL
IFOLLOw CALLS (MODE 1)
ILINK IS ON P~GE 0

IX * X
ISAVE X-2

JMS I FGETL
X

ILOAD X AGAIN

6-83

•

JMS I FMPYL"
TWO
JMS I FADOLK
ONE
JMS I FADOLI<

/2'1.
12'1.+1
1'1."'2+2'1.+1

IRESULT NOW IN fAC

•

FFAOO
FMPYLK, FFMPV
TWO,
0002
FADDLI~,

ONE,

2000
0000
0001

ILINK TO ADO ROUTINE
I~INK TO F~OATING MULTIFLY
IFlOATING POINT CONSTANT
12.ft,

IFLOATING POINT CONSTANT
11.0

2~00

\ 0000
X,

/VARIABLE

• ••

• ••
• ••
0

IFLOATING POINT TEMPORARY

2. Routine to add 5 successive floating-point numbers starting
at location 0 of field 2.

START,

elA
DCA OPADDR

JMS
lAC
DCA
•
AlOOP,
CDF
TAO
" JMS
MINUS5, ... 5
TAD

IFI~ST

OPERAND AT LOCATION"

I FCLR

IZEF(O FAC

ICALlS ARE MODE 2

OPADDR
I FADOLI<
OPAonl<

IOPERAND AOOR IN At
ICALL ADD ROUTINE
ILOCATION UNUSED, SO WE USE
lIT AS A COUNTER

6-84

TAO 1<3
DCA OPAODR
lSZ MINUS5
JMP ALOOP
HLT
FAOOLK, FFAOD
OPAI)OR, o
1(3,

IUPDATE OPERAND ADDRESS

IDONE?"
INO
IYES-ANSWER IN FAC.
IPOINTER TO ADO RQUTINE
IPOINTER TO OPERAND
lEACH OPERANO IS 3 WORDS LONG.

FLOATING-POINT OPERATIONS
There are also four simple floating-point operations that operate
on the F AC and are avallable to user subroutines.
Function

Starting Address

Operation

NEGATE
NORMALIZE
SQUARE
CLEAR

FFNEG
FFNOR
FFSQ
FACCLR

FAC+--FAC
NORMALIZE +-FAC
FAC+-FAC*FAC
FAC+-O

These functions are all called by simple JMS, and return with
the hardware AC=O. Page 0 links are maintained for negate,
normalize, and clear.
Page 0 Link

Routine

FNEGL
FNORL
FCLR

FFNEG
FFNOR
FACCLR

BRTS Subroutines
There are several subroutines in BRTS which can be useful to
assembly language functions. A discussion of each of these routines .
follows. They are identified in the discussion by the tag for their
starting address, and all tags referred to can be found in the symbol table.
'
SUBROUTINE ARGPRE
Subroutine ARGPRE is used to locate scalar variables in the
Scalar Table. When called, it uses the rightmost 8 bits (0-255
decimal) of location INSAV as the entry number to be found, and
6-85

on return, the data field is set to the field of the variable and the
AC points to the exponent word of the variable. ARGPRE is
called via a JMS, and is used most often in passing arguments to
and from the user subroutine.
Example: Load the F AC with the third variable in the Scalar
Table.
ClA
TAO C2
DCA INSAVE
lAC
DCA FF
JMS t ARGPRL
JMS I FGETL.
(UNUSED)
HlT
C2,

IWE ~ANO ENiRV #J,BUT
ISINCE THE FIRST ONE IS 0,
ILOADINSAVE WITH 2
15ET FF SWITCH
ICALL ARGPRE
ITHE AC AND DATA FIELD
IARE SET, 50 THIS 11 A
IMODE 2 CAL.l.

ARGPRL, ARGPRE

SUBROUTINE XPUTCH
Subroutine XPUTCH is used to pHt ASCII characters into the
termimil ring buffer. When called, the R-bit ASCII character is in
the light-most 8 bits of the AC. On return, the AC is cleared. Note
that un1ess the ring buffer is full, XPUTCH does not cause any
characters to be printed; it merely places the character in the
term"nal ring buffer. A page 0 link to XPUTCH is maintained at
location XPUT.
Example: Put a carriage return/line feed combination in the
teminal buffer.
elA
TAD
JM5
TAD
JMS
HLT
1(215,

1(212,

215
212

K215
I XPUT
1(212
I XPUT

IL.OAD CR It.,jTO AC
ICALl XPUTCH VIA PAGE 0 lINK
ILOAD LINE. FEED INTO AC
IPUT IN BUFFER
ASC II CODE FOk CR
IASCII CODE FOR LF

6-86

SUBROUTINE XPRINT
Subroutine XPRINT is used to print the next character in the
terminal ring buffer. If there are characters waiting to be printed in
the- ring buffer, XPRINT returns to the instruction following the
calling JMS.-If the ring buffer is empty, XPRINT skips the instruction following the JMS on returning~ XPRINT will actually print
a character only if the terminal is not -busy; i.e., a call to XPRINT
means "print a character if possible" rather than "print a terminal
character." For a more detailed description of how the terminal
ring buffer I/O operates, see terminal I/O. BRTS maintains a-page
o link to XPRINT called PRINT. .
Example: In the middle of a compute bound loop a call placed to
XPRINT keeps the terminal busy. At the end of the compute loop
a call is placed to XPRINT that empties the terminal ring .buffer
before proceeding.

LOOP,

•

•
•
J~S I PRINT
Nap

ICOMPUTING INSTRUCTIONS
ICALL XPRINT VIA PAGE 0 LINK
ITHIS INSTRUCTION WILL BE
ISKIPPED IF RI~G BUFFER IF EMPTY

•
•

lSZ LOOPCN
JMP LOOP
JMS I PRINT
JMP ,-1

ILOOP CONTROLLING INSTRUCTION
I

ILOOP IS DONE - EMPTY RING
IBUFFER BEFORE CONTINUING

SUBROUTINE PSWAP
Under normal conditions, BRTS runs with the OS/8 page
17600 portion of the resident monitor moved to the highest page of
core (second highest page TD8/E system). PSWAP is used to
swap this page back and forth prior to doing any operations with
OS/8. Prior to calling OS/8, PSWAP should be used to restore the
6-87

. page 17600 resident to 17600, and when OS/8 operations are
complete, PSWAP should be called again to swap the 17600
resident back up to high core. A page 0 link to PSWAP is maintained at location P1SWAP.
Example: The following code uses the USR in OS/8 to perform a
LOOKUP on the file BASIC.DA on the system device.

•

•
•
CL.A

JMS
CL.A
ClF
JMS

I P1SWAP
lAC
10
I 1<7700

FNAME

ML.T
JMS t P1SWAP
•

S~OUL.O BE 0 ON CAL.L.
IRESTORE OS/8 PAGE 17&00 RESIOENT
IDEVICE • FOR SYSI IS 1

lAC

ICALL. USR
IL.OOKUP
IPOINTER TO FIL.E NAME
ICONTAINS L.ENGTH ON RETURN
IERROR RETURN
ISWAP 05/8 -RESIDENT BACK
ITO HIGH CORE

•
•

NOTE
If PSWAP is used, it must be executed an
even number of times. When the assembly
language function is called, the page 17600
resident is at high core; when the function
returns to BRTS, the 17600 resident must
be back in high core.
SUBROUTINE UNSFIX
Subroutine UNSFIX is used to :fix a positive, 12-bit, magnitude
only integer from the F AC and return with the result in the hardware AC. The range of the fixed integer is 0-4095; an attempt to
fix a number larger than 4095 or a negative number will cause..,an
"FO" or "FM" error, respectively. UNSFIX is called via simple
6-88

JMS, and a page 0 link to. UNSFIX is maintained, called INTL.
UNSFIX destroys th~ contents of the F AC.
Example: The following code uses the F AC as a count of the .
number of times to ring the bell on the terminal.

BELLOP,

•
•
CLA
JMS I INTL
CIA
aCA COUNTR
TAO 1<207

-JMS I xPUT
ISZ COUNTR
J.MP 8ELLOP

IFIX THE FAC TO 12 BIT INTEGER
INEGATE THE INTEGER •
lAND STORE AS COUNT
IASCII ~OR BELL
IPUT IN RING BUffER
IR I GHT ,NUMBER YE T?
,/~O-RING ANOTHER BELL

•

•
1<201,

•

207

. SUBROUTINE STFIND
.Subroutine STFIND is used to 'locate a string variable or the
first element of a string array. When called, if the link is non-zero,
STFIND looks for an entry in the String Array Table. If the link
is zero, STFIND uses the String Symbol Table. For standard string
variables, the rightmost 8 bits of location INSAV are used as the
.number of the entry to be obtained; for string array variables the
last 5 bits are used. On_returns' from STFIND, the AC contains a
. CDF to the field of the string spe.cified, location STRPTR points
to the first word (count word) of the string, location STRMAX
holds the_maximum length of the string (as a negative number),
. and location STRCNT contains the actual number' of characters in
the string. (as a negative number). STFIND is used most often in
passing arguments to and from user functions.
6-89

Examples:
1. To find string" number 7
TAO 1(6
DCA INSAV
Cl.,L
Jfo1S I STGINL

ITHE NUMBERING STARTS WITH 0
ISET UP STFIND POINTER
/WE WANT SIMPLE STRING
ICALL STFIND

•
Kb,

•

STFINL, STFINO

2. To find the first element of string array number 2.
TAO 1<1
DCA INSAV
CLl CML
JMS I STFINL

ITHE SECOND ENTRV
IWE WANT STRING ARRAY
ICALl STfI!\;O

·
•

1,
1 .
STFINL, STFIND

SUBROUTINE BSW
Subroutine BS\V is used to swap thc two halves of the hardware
AC. BSW is called by a simple JMS, and a page 0 link called
BSWLis maintained. Obviously, PDP-8/E users would perform
a hardware BSW instruction rather than use this subroutine.
SUBROUTINE MPY
Subroutine MPY is a 12 by 12 bit binary multiply routine. The
AC is multiplied by the contents of location TEMP3 (both numbers are treated as 12-bit, unsigned integers), and on return, the
high-order bits of the result are in TEMP6, and the low-order bits of
the result are in the AC. The page 0 link to MPY is MPYLNK.
SUBROUTINE DLREAD
Subroutine DLREAD is used to read the next word of the incore
DATA list into the AC. If there is no more data in the DATA list,
. a DA error message results.
6-90

Example: Read the next number fro~ the DATA list into the FAC.

CLA
JMS
DCA
JMS
DCA
JMS
DCA

I OLREAL.
EXP
I DLREAL
HORD
I DLREAL.
LORQ

IREADEXPONENT WO~O INTO AC
/STORE IN FAC
/READ HIGH MANTISSA FROM LIST
ISTOPE HIGH MANTISSA WORD
IREAD LOW M_NTISSA ~ROM LIST
ISTORE LOW MANTISSA WORD

•

•
DLREAi.., DLREAO

SUBROUTINE ABSVAL
Subroutine ABSVAL is used to take the absolute value of the
FAC. If the FAC is positive, ABSV AL is essentially a NOP; if the
F AC is negative, it is negated before return.
"

Passing Arguments To The User Function
BRTS calls the user assembly language function with a JMS
instruction. Prior to executing that JMS, it places the first numeric
argument in the- FAC, the second in Scalar Table entry 0, the third
in Scalar Table entry 1, etc., until the argunient list is satisfied. If
any string arguments are used, the first is found in the SAC and
the second is pointed to by String Table entry 0. The user function
obta ns these arguments as needed by calling the routines
'
ARGPRE and STFIND appropriately.
Example: The following function takes the first two numeric arguments and performs the operation on them specified in A$:
UDEF EXM (X,A$, Y)
LET Z=EXM (2,"PLUS",1)
Legal values for A$ are strings begimiing with "PL" for "PLUS"
and "MI" for "MINUS".
6-91

EXM,

(()

TAD I SAC?
TAD PL
SZA CL.A
JMP EMINUS
DCA INSAV
JMS 1 ARGPRL.
JMS I FADDL
ARGPRL, ARGPRE
JMP ! El(M
EMINUS, TAO ! SACP
TAO "'1

CL.A
, JMP I IAL
DCA INSAV
JMS I ,ARGPRL.
_..
SZA

Ji-i$

,,().

! ".,UDL.

IENTRY POIN,,(
IINDEX REGISTER 5 POINTS TO SAC
IGET FIRST 2 CHARS OF A$ FROM SAC
ICQMPAR T~EM TO "PL"
INOT "PL.US"-CHECK FOR "MINUS"
IOPERATION IS PL.US-INIT ARGRE TO GET
ISCALAR 0
IfIND Y. X IS AL.READV IN FAC
IX+Y
IT~IS LOC SKIPPED BY FADO
IDONE-RETURN WIT~ RESULT IN FAt
IFIRST TWO CHARS OF SAC AGAIN
ICOMPAR TO I'll
lIS IT "MINuS"?
INO-ERROR
IYES-SET UP ARGPR~ FOR ENTRY 0
IFINO Y. X IS AL.REAOY IN fAC
iX-V

SACP,

SAC

11HIS LOC SKIPPEO BV

PL.,
MI,
FADOL.,
fSU6L,
tAL. ,

JMP I EXr;
-2014
·1511
FFAOO
FFSUB
IA

/RETURN

6-92

~ITH

Fsue

VALUE IN,FAt

If the function is to return any value, that value should

left
in the F AC on f'eturn. The user fmiction must always return by a
JMP I through the entry point.
To generate a fatal IA (illegal argument) error message, perform
a JMP to location IA in BRTS.
USING THE USE STATEMENT
If the assembly language function needs to know the location of
an array (for buffer space, mUltiple argument passing, array argument), the USE statement is necessary. The USE statement places
the octal number for the array specified into location USECON.
By using this value as an index into the Array Symbol Table, the
array specified can be located and used by the assembly language
function, as necessary.
For examp~e: The hypothetical assembly language function PLT
requires a 100 word buffer. To assure allocation of this buffer, the
BASIC user of PLT is- instructed to dimension a 34 element array
and use it in a USE statement before calling the PLT function.
In BASIC:

10 REM DEFINE THE USER FUNCTION
20 UOEF PLT ex,V)
30 REM ALLOCATE A 34 ELEMENT (102 WORDS) ARRAY FOR A BUFFER

40 DIM 8(34)

•

The function PLT finds B as follows:

•

100 USE 8
110 VII PLT(3,2.8)

6-93

PLT,

TAO USECON
CLL TRL
TAD ARSTRT
DCA lIRS
TAD cono
OCA 1+1

•
TAO I )(1(5

DCA
TAO
DCA
TAO

BPTR
I lIRS
DIMl
I XRS

IGET ENTRV NUMBER OF B
IMUL TIP\. V BY 4 (E.ACH ARRAY TABLE ENTRY
lIS 4 wORDS LONG)
IMAKE POINTER INTO ARRAY TABLE
lAND SAVE IT
IGET CDF TO SYMBOL TABLE FIELO
IPUT INTO LINE
ICHANGE OF TO SYMBOL TABLE FIELD
IGET POINTER TO B(~)
ISAVE FOR LATER
IGET ARRAY DIMENSION 1
IGET ARRAY DIMENSION 2

Note that the USE statement merely passes an array entry number
to the assembly language function; all actual parameters must be
obtained from the Array Symbol Table using that entry number as
an index. Note also that the physical location of arrays passed in
such a fashion can be almost anywhere in core, and a field
boundary may fall within the array.
BRTS I/O
TERMINAL I/O
BRTS drives the terminal asynchronously by maintaining a 40
character terminal output buffer and regularly callLng subroutine
XPRINT. The procedure is as follows:

1. Characters are inserted into the terminal ring buffer by calling
subroutine XPUT. If the ring buffer is full, XPUT waits
until a character is printed and a slot is free.
2. BRTS regularly (at least once every pseudo-instruction) calls
subroutine XPRINT. XPRINT acts as follows:
a. If the terminal flag is not set, XPRINT returns.
b. If the terminal flag is set, the buffer is checked for any
more characters. If it is not empty, the next characJer is
printed (via TLS) and XPRINT returns.

6-94

XPRINT returns to the instruction following the calling JMS if
there are cparacters waiting in the ring. buffer. If, the ring buffer is
empty; XPRINT skips the next instruction before returning. This
scheme allows BRTS to do other things for most of the 100
milliseconds necessary to print a character, without turning the
interrupt on. It requires periodic calls to XPRINT, but the overhead is still considerably less than the time wasted waiting for the
termin~l flag.
Assembly language functions are free to use the ring buffer (it is
emptied before the function is called), or th~y may choose to perform simple terminal I/O (TLS, TSF, JMP.-l). If terminal I/O is
performed other than ring buffered I/O, the terminal flag must be
set when the user function returns toBRTS. Note thatthe assembly
language function need not call XPRINT; it may choose to place
characters in the ring buffer, and let . BRTS empty it after the.
assembly language function has returned.
BRTS··FILE FORMATS
BASIC files are formatted as follows:
1. Numeric files-Numeric files are formatted as consecutive
3 word floating-point numbers, 85 to each 256 word OS/8
block. The last word in each block is unused. There is no
end-of-file marker.
2. ASCII Files-ASCII files are stored in OS/8 ASCII format,
that is, 3 8~bit characters packed to every two words as
follows:
o

HI ORDER CHAR 3

CHAR 1

LO ORDER CHAR 3

CHAR 2

The end of the file is marke~ with a CTRL/Z character.
BRTS BUFFER SPACE
Locations 10000-12000 in BRTS are devoted to file buffer
space. Buffers are allocated as they are needed, the lowest free
buffer always being allocated first. A map .of currently· allocated
6-95

buffers is maintained Dn page 0, called BMAP. Bits in the map are
Dn if the buffer is allo.cated, off if the buffer is free. Bit 11 represents the buffer frDm 10000-10377, Bit 10 fDr 10400-10777; Bit
9 fDr 11000-11377; and Bit 8 fDr 11377-11777. If any Df the
buffers are not available because the pseudD-code or variable space
extends belDW 12000, the corresponding BMAP. bits are set when
BRTS is started.
BRTS DEVICE DRIVER SPACE
LDcations 7000-7577 are devoted to. space for OS/8 device
drivers. Both one and two page handlers may be loaded; a map Df
these three pages is maintained at DMAP. Page 7000-7177 is
represented in Bit 11; Page 7200-7377 in Bit 10, and 7400-7577 .
in Bit 9.
. Note that assembly language functiDns that are used in prDgrams
which do not require mDre than Dne or two files Dpen at once may
wish to. use some Df this driver and buffer space fO~A their Dwn
purposes. This space can be allocated by setting appropriate bits in
BMAP. and DMAP. After the bits are set, BRTS will nDtuse this
space in subsequent FILE commands.
THE BRTS I/O TABLE
BRTS keeps track Df the status Df each Df the up to. four files
which may be open simultaneously by means of the I/O table.
Starting at FILEI, it has four I3-word entries, labeled Fll~EI,
FILE2, FILE3 and FILE4. Each name corresponds to the number
specified in the file statement which opened that file, and the format
of each entry is as fDllows:
HEADER WORD
STARTING ADDRESS OF BUFFER (IN FIELD 1)
CURRENT BLOCK IN BUFFER
READ/WRITE POINTER INTO BUFFER
HANDLER ENTRY POINT
STARTING BLOCK NUMBER FOR FILE
ACTUAL FILE LENGTH
MAXIMUM FILE LENGTfI
POSITION OF PRINT HEAD (FOR COLUMN FORMAT~
TING)
6-96

FILENAME
FILENAME
FILENAME.
FILENAME
The header word bits have significance as follows:
Bit Positions
0-3
4-5
6
7
8
9
10
11
,/

Meaning
OS/8 number for device
Current character number for unpacking ASCII
files
0 if the current buffer load has not been changed
1 if ,current buffer load .has been altered
0 if device is file structured
1 if device is read/write. only
0 if the handler is 1 page long
1 if it is a 2 page handler
0 if file is fixed length
1 if variable length
0 if more data in file
1 if BOF has been seen
O. if file numeric
1 if file ASCII

Interfaci~ Th~

Assembly L~nguage Function To BRTS
All assembly language functions are subrQutines', called by a
JMS through the User Function Table. This table, which begins at
location 1560 in BRTS, contains absolute pointers to the starting,
addresses of each of the user asse~bly language functions. User
functions must be origined' to run between 3400 and 4577, and
must return to BRTS via a JMP I through the user function starting address. To interface a set of user functions to BRTS, perform
the following operations:
.
,.
1. Assemble all the user assembly language functions (up to
1610) together. They must fit between 3400 and 4577, but
may be anywhere within that space .
.RPAL8
*USER.BN ~USER.PA
6-97

2. Load the user functions into core with the Absolute Loader,
and save locations 3400-4577 as the file BASIC.UF, which
is the user overlay .
.RABSLDR
*USER.BN$
.SAVE SYS:BASIC.UF 3400-4577
3. Using OS/8 ODT, modify the User Function Table in
BRTS which starts at 1560, entering pointers to the user
assem~ly language functions. Unmodified tabie entries are
240 8 ; replace these entries with the starting addresses
(pointers) to the, user assembly language function. Starting
at location 1560, enter the pointers in the table in the exact
corresponding order in which the functions appear in the
UDEF statement which defines tbem .
.GET SYS:BRTS
.ODT
1560/240 3400 (LF)
1561/240 3410
tC
.SAVE SYS:BRTS
On the procedure above two functions are interfaced which
start at locations 3400 and 3410 respectively. LF indicates
nressinl! the LINE FEED kev.

J......

Example: There are three assembly language functions in our
package, called PLT, HI, and LO. The BASIC user is instructed
that when he uses this function package, PLT, HI and La must be
defined in that order. The function files, then, look like:
Function Source (USER.PA)

HLT,

*34012l
0

'•.

IENTRY POI~T FOR HI
IORDER OF ENTRV POINTS IS
INOT CRITIC~L.

•
•

JMP I HI

6-98

PLT,

•
•
JMP
LO,

,
I

PLT

IENTRY POINT FOR PLT

IENTRY POINT FOR LO

•

•
JMP

I LO

To enter these three functions into the User Function Table in
BRTS, the procedure is:
.GET SYS:BRTS
.ODT
(LF)
1560/240 PPPP
(LF)
1561/240 HHHH
1562/240 LLLL
tC
.SAVE SYS:BRTS
where PPPP, HHHH, and LLLL represent octal starting addresses
for PLT, HI, and LO respectively. LF indicates pressing the LINE
FEED key.

NOTE
BRts establishes calls to the user function
by setting up a one-to-one correspondence
between---the pointers at 1560 and the function names present in a UDEF statement.
Therefore, the order of the pointers must
exactly correspond to the order of the function definitions' in UDEF. If the BASIC
user wants to use only the nth function ina
given user package, he must still define n
functions in the UDEF statement, though
the first n-l may be dummies.
For example: A package of eight assembly
language functions that use arguments as
follows:
6-99

ONE (X)
TWO (X,Y)
THR (X,Y,Z)
FOU (X,Y,Z,A)
FIV (X,Y,Z,A,A$)
SIX (X,Y,Z,A,A$,B$)
SEV (X)
"HTn
4.....J..L.~

(V)
,Jl...1

If a

BASIC user wishes to use only
function ONE, the UDEF would look like:
10 UDEF ONE (X)
If the BASIC user wants to use functions

ONE and EIG, the UDEF would look like:
10 UDEF ONE(X),DUA(D),DUB(D),
DUC(D),DUD(D),DUE(D),DUF(D),
EIG(Y)
For this user, DUA through DUF are dummy user function names which are never
called; Ehey merely set up the right correspondence between names and pointers.
The easiest way to assure that the pointers
are established correcily is to provide the
user of an assembly language function package with a set of complete UDEF statements
that define all functions correctly, and instruct him to use the complete set of
UDEF's each time.

General Considerations And Hints

ROUTINES UNUSABLE BY ASSEMBLY LANGUAGE
FUNCTIONS
,Because the assembly language functions reside in the overlay
buffer when executing, they cannot use any routines that reside in
any of the three other overlays. Following is a list of the BRTS
functions and routines that are not callable from the assembly
language function overlay.
6-100

Routine N arne
FFATN
FFCOS
FFEXP
EXPON
INT
FFLOG
SGN
FFSIN
RND
FROOT
ASC
CHR
DATE
LEN

pas

SEG
STR
VAL
TRC

Function
Arctangent Function
Cosine Function
Exponential Function (eX)
Power Function (AB)
Signed integer Function
N aperian log Function
Sign Function
Trigonometric Sine Function
Random Number generator
Square root Function
String Function ASC
CHR$ Function
DAT$ Function
String length Function
String search Function
String segmenting Function
STR$ Function
VAL Function
Trace Function

Routine Name

Function

CHAIN
CLOSE
OPENAF
File manipulation Routines
OPENAV
OPENNF
OPENNV
USING OS/8
So long as the assembly language function is carefully designed
to protect all core areas being used by BRTS, there are no restrictions on the function's use of OS/8. Once the page 17600 resident
monitor has been restored, the OS/8 User Service Routine (USR)
may be called at will, and files may be located, used, and closed
again. If the user's BASIC program does not need full file capabilities, the assembly language function is free to use the driver space
from 7000-7577 and the buffer space from 10000-17777. The
assembly language function should be careful, however, to check
the bit maps and status words on-page 0 to make certain a given
6-101

area is free before using it. Note that the sy~tem device driver may
be used without restoring the page 17600 resident: restoration is
only required when it is desired to use the USR.
OS/8 runs with the interrupt off, and as an OS/8 based program, BASIC does not use the interrupt facility. Locations 0-2,
" however, in BRTS have been left free for any assembly language
functions which wish to use the interrupt facility. Prior to turning
on the interrupt system, an assembly language function must clear
0;,11 thp
Ro;,m~ left aT'Ol1nr! hu t].,p 0<;,; /Q ].,o:>nd1pT''' o:>nr! hpfoT'P 1"eh11"n_
..&."'" ...."'....ou .L.......
..."' ....... ""'" '-'J "'.............
u-/
ing the function must turn off the interrupt system and set the
TTY flag.
u.............

.l.J.U.LJ.

.1.""'&'~,

".1...1."""-

l,"JV.LV.&.V

. . . . . . u..... .1. ...

PAGE o USAGE
Following is a map of the BRTS page 0 usage. Locations
marked with an * may be used by the assembly language function
without saving the contents.
Locations
0-2 *
3-7
10-15 *
16-17
20-30
30-36
37-62
63-67
73-107
110-161
162-177

Interrupt vector
System parameters and temps
Index registers
System pointers
Compiler-BRTS communication
System registers
Floating-point package area
System registers
Constants
Links to BRTS subroutines
I/O Table pointers

Assembly language functions are free, of course, to use any of the
pointers or constants, but they must be intact when control is returned to BRTS.
Assembly Language Function Examples
To illustrate the material in the previous sections, two examples
of a complete assembly language function follow. The first example, which we call PLY, evaluates a second degree polynomial of
the form ax2 ±bx±c. It requires six arguments: X,A,R1$:.B,R2$,C.
X is the variable; A,B and C are the coefficients, and R 1$ and R2$
are the signs of the first order and constant term, respectively.

6-102

Legal values for R1 $ and R2$ are "+" and "-"; any other string
causes an error message to be printed. Note that this example is
tutorial in nature; .it is meant to illustrate argument passing and
floating-point operations rather than a typical use for assembly
language functions.
The second example, ADC, is an example of an actual assembly
language function which samples an AD8-EA analog to digital converter. It was written as part of a user function package intended
for lab<:>ratory use.
Example 1: PLY
In BASIC:
10 UDEF PLY (X,A,R1$:B:R2$,C)

1000 PRINT PLY (Z,1,"+",2,"+",l)
The pointer for PLY·is 3460 and the function is coded as follows:
ILOCATIONS IN BRTS
IVALUES ~ERE OBTAINED FROM SYMBOL
XR1-U
XPUT-122
FFADD-&000·
FFSU8a&117
FFMPV·S&00
STRLEN a 32
SAC_3il
INSAV-&II
STFIND a l&&&
STRCNTal1
STRPTRa72
FPUTL·13S
FGETL-134
ARGPRE:a307
FFSQa&347
*15&0
PLY
,*31100

ILINk TO FUNCTION FOR BRTS
IASSEMBLY LANGUAGE FUNCTION OVERLAY STARTS
IAT 31100

ISUBROUTINES USED 8Y THE.FUNCTION PLY
ISUBROUTINE SEVAI.-USED TO DETERMINE IF LEFT HAI.F OF AC CONTAINS
IA ft+" OR P_". IF "+P , LOADS THE OCTAL EQUIVALENT OF "JMS I FADOL"
IINTO THE AC AND RETURNS. IF U_P , LOADS THE EQUIVALENT OF
IJMS I "FSUSL INTO THE AC AND RETURNS. IF THE CHARACTER IS EQUAL
ITO NEITHER, IT TypES AN ERROR MESSAGE ON THE TERMINAL AND EXITS
IFROM THE FUNCTION
SEVAL,

\11

DCA SCNTV
UD SCNTV
AND K77011l

ISAYE AC IN TEMPORARY
ISTRIP TO LEFT CHARACTER

6-103

MC,

UD
SZA
JllIP
TAO
JMP
TAO
AND

"PLUS
ClA
MC
JMSlOD
I SEVAl
SCNTV

52A
JMP
TAD
JMP
TAD

ClA
SERR
JflSSUB
I SEVAL
EMESSA

ICoMPARE TO U._
lIS IT A -."?
INO-CI'IECIC FOR A ".It
IYES-LOAD AC WITH AJMS I HDD1."
IRE TURN
IGET ORIGINAL AC VALUE AGAIN
ISTRIP TO LEFTMOST CHAR
ICoMPAR TO ".n

1(7700
TAO "'MINUS

SERR,
ElOOP,

",..
......
Ho

lIS IT

11.-,

INOdJ>j ILLEGAL STRING ARGUMENT HAS BEEN PASSEO
IYES-LoAD AC WITH "J"S I FSUBl"
lAND RETURN
IAOORESS OF ERROR MESSAGE .1
I!NOf~ REG!STER ! POINTS TO ERROR MESS,lGE
IGET CHAR Of ERROR MESSAGE
lIS IT 07 (0 TERMINATES MESSAGE)
/YES-FUNCTIoN COMPLETE-RETURN TO BRTS
INO-PUT CHARACTER IN RING BUfFER

.. It"

An.

I XIU

SNA
JMP t PLY
JMS I XPUT
JMS ELOOP-

JMSADD, JioIS I FADOl
JMSSUB, JI'IS I FSUSL
"'PLUS, "53011
"'MINUS, ·5500
[MESSA, E",ESS-l
EMESS, 311

1
I
1
I
I
I
I
I
I
I
I
I

314

314
305
307
301
314
240
323
311
301
31(i
215
212

L
L
E
G
A
L

5
I
G
TIl

ICR,lF
ITERMINATES MESSAGE

SC~iV·HiKES CE~TAI~ THE AC IS ; -1. IF NOT, THE STRING
IWHOSE COUNT IS IN THE AC IS LONGER THAN 1 CHARACTER, MAKING IT
IAN ILLEGAL SIGN SPECIFICATION, AND THE ABOVE ERROR MESSAGE IS
IPRINTED. IF SO, IT CLEARS THE AC AND RETURNS,
iSU8~OUTI~E

SCNTV,

111

IBUMP AC BY 1
ISHOUL.D NOW BE 0
lIT IS NOT, SO PRINT
IRETURN

UC:

SZA CL.A
JMP SERR
JMP t SCNTV
ITHE

~oOY

PLY,

MESSAGE

OF THE FUNCTION ITSELF

TAO
JMS
TAD
JM5
DCA
DCA
CLl
JMS
DCA
nCDF,

E~ROR

STRlEN
SCNTV
I SAcP
UVAL
OP1
INUVE

I STFINL.
nCDF
TAO STRCNT
JM5 SCNTV

•

ISZ STRPTR
JMP NOSKIP

IENTRY POINT
IGET LENGTH OF THE STRING IN THE SAC (R1S)
IMAKE SURE IT IS ONL.Y 1 CHARACTER lONG
IGET THAT 1 CHARACTER FROM THE SAC
IGET THE CORRESPONDING ROUTINE CAL.l INTO THE AC
I AND PLACE IT IN LINE
.
ISET UP STFINO TO GET STR1NG TABLE ENTRY 0(R2S)
IWE WANT REGULAR STRINGS, NO STRING ARRAYS
IFINO STRING ARGU~ENT 2 (R2S)
IPUT THE COF IN L.INE WHERE ITS NEEDED
IGET COUNT FOR STRING A2S
IMAKE SUR! IT'S -1
ICHANGE OF TO FIEL.O OF STRING R2S
IBUMP STRING POINTER PAST COUNT ~ORO
IIF ISZ DOeSN'T SKP,THE STR1NG IS WITHIN 1 FIELD
IIF lSI DOES SKP, THERE IS A FIELD BOUNDARY

6-104

ROF
TAO COF10
DC A • + 1

NOSKIP, TAO I STRPTH
COF'
JMS SEIIAl
~CA OP2
J14S I FPUTl

IWITHIN THE STRING AND wE ~UST BUMP ~HE DATA
IFIELD BY 1
IREAD CURRENT DATA FIELD
IHAKE A COF INSTRUCTION, INCREASING OF BY 1
ISTORE THE NEW COF IN LINE
lCHANGE BY 1
IGET CHARACTER IN STRING
lAND GET TH! OPERATION IT REPRESENTS
IPlACE THAT OPERATION'IN LINE
ISAVE X,WHICH ~AS I~ THE FAC ON CALL

JMS
DCA
JMS
JMS

IFFSQl
INSAV
t A'RGPRL
I FMPYl

ARGP'Rl, ARGPQE
JMS I FPUTl
AXSQD
UC
DCA INSAV

COFU,

JMS
JMS
COF
JI'IS

I ARGPQL
I F'GETl

121

I FMPYl

IX·2

IARG A CAN BE FOUND AT SCALAR TABLE ENTRY 21
IFINO THE ADDRESS OF A
'/USE IT AS T"EADDRESS TO PASS TO THE MULTIPLY
I~OUTI.NE

ITHIS WORD IS SKIPPED 8Y MULTIPLY ON RETURN
ISAVEhX-2
I

ITHE THIRD NUMERIC ARGUMENT (8) IS FOUND AT
ISCALAR TABLE ENTHY t
IFIND THE ADDRESS OF 8
lAND USE IT IN A MODE CALL TO FGET
ITHIS LOCATION IS SKIPPED BY FGET ON RETURN
IBU

OP1,

JMS I FPUTL
BX
JMS I FGETI..
AXSQO

ISAvE 8*X

•

ITHIS LOCATION IS LOADED ~ITH A CALL TO THE ADO
lOR SUBTRACT ROUTINE, DEPENDING ON THE VALUE
.
10F .RU. IN EITHER CASE, THE OPERAND IS BS

BiI:

UC
·ClL. RAl
DCA H.UV

JHS I ARGPRL
OP2,

K772121,

TT2I2I

Jt4P I PlV

ILOAD FAC _ITH A*X-c

12 IN THEAC

ITHE FOURT~ NUMERIC ARGUMtNT eel IS FOUND
lIN SCALAR TABLE ENTRY 2
IFIND THE ADDRESS OF C
ITHIS LOCATION IS LOADED WITH A CALL TO ADO
lOR SUBTRACT, OEP~NDING UPON THE VALUE OF R2S
lIN EITHER CASE, IT .15 A MODE TwO CALL wITH
ITHE OPERAND BEING C
ITHIS !NSTQ~CTION IS SKIPPED ON THE RETURN
IRETURN FROM THE FUNCTION-ANSWER IS IN THE FAe

FADDl,
FSUBl,
FMPYL,

FFAOO
FFSUe
FFMPY
SACP,
SAC
STFINl, STFINO
FFSQL, HSQ
IFlOATING POINT STORAGE
lI,

21
21
21

ex,

21
21
21

AXSGlO,

21
21
21
21
S

6-105

Example 2: ADC
Assembly language function ADC comes from a laboratory package
of 11 routines, of which ADC is the eighth. ADC accepts one argument, the number of the channel to be sampled, and returns the
channel reading.
In BASIC:

10
20
30
40
30
40
50

uOEF OUACD),!)l,)8(O),OUCCO),DUOCO),QUE(I1),DUF(O),DUGCD),AOCCN'
REM SINCE ADe IS EIGHTH FUNCTION IN PACKAGE,
REM IT MUST BE EIGHTH FUNCTIO~ IN UDEF
REM 'IRST SEVEN ARE DUMMIES
y.,ADC(0}
PRINT Y
ENO

Modify the User Function Table in BRTS as follows:

.GET Sy S BRTS

.ODT

1560/0240
01561 10240
01562 10240
01563 /0240
01564 10240
01565 10240
01566 10240
01567 /0240 4416
fC
• SAVE SY S: BRTS

•

6-106

ADC is coded as follows:
*4£lle
INTL = 114
Exp :: 44
HORO • t.l5
LORD I: 46
FNORL ::I 136
AOC,

JMS I INTL
ADLM
AOST
AOSK
JMP ."1
AORB
DCA EXP
JMS FFLOT
JMP I ADC
IA08-EA rOTS
ADLM ;: 6531
ADST = e532
AORB = ~533
ADSK = ~5:S£l

IBRTS LOCATIONS
ITAKEN FROM
ISYMBOLTABLE
IENTRY POINT
IFIX ARG TO I~TEGER
ILOAD MULTIPLEXER
ISTA~T

CO~VERSI0N

IWAIT FOR COMPLETION FLAG
IRE AD VALUE
ICONVERT TO FLOATING POINT
IRETURN WIT~ READING IN FAC
ILOAD MULTIPLEXER FROM AC
1ST ART CONVERSION

IREAD AID BUFFER
ISKIP ON AID DONE

IROUTINE TO CONvERT 12~8IT INTEGER IN EXP INTO
IFLOATING POINT NUM~ER IN fAC
FFLOT,

1<13,

TAD
DCA
DCA
TIIO
OCA
JMS
JMP
13

eXP
HORO
LORD
1(13
EXP
I FNORL
I FFLOT

. IPUT NUMBER IN HI MANTISSA
IZERO LOW MANTISSA
IINITIALIZE EXPONENT TO 11(10)
INORMALIZE
IRE TURN

6-107

Table 6-1 OS/8 BASIC Language Summary
ELEMENTARY OS/8 BASIC STATEMENTS
Statement

Example Form

Meaning

CHAIN

CHAIN DEV:
Filename.ex

Stops execution of the current program, retrieves the
program named III the
CHp-.. IN statement from the
specified device and file,
compiles the chained program and begins execution
of the program.

DATA

DATA xl,x2, ... ,xn

Values xl through xn are to
be associated with corresponding variables in a
READ statement. The values may be either numerics
or strings. Strings must be
enclosed
by
quotation
marks.

DEF

DEF FNB(x) f(x)
The user may define his own
DEF FNB(x,y) f(x,y) function to be called within
•
his program by putting a
DEF statement at the beginning of a program. The
function name begins with
FN and must have three letters. The argument list in
the function may contain as
many as 4 numeric and 2
string arguments.

DIM

Enables the user to create a
For numerics:
DIM vl(n!)., v2(n2,m2) table or array with the specified number of elements
where v is the variable name and nand m are the maximum SUbscript values. Any
number of arrays can be dimensioned in a single DIM
statement.

=
=

6-108

Table 6-1 OS/8. BASIC Language Summary (Cont.)

Statement

Example Form

Meaning

For strings:
DIM v1 $(I),v2$(K,L)

I is the length of string variable v1 $, K is the number
of strings and L is the length
of strings of string variable
v2$. Strings longer than 8
characters must be dimensioned. String tables are illegal.

END

FOR-TOSTEP

FOR v=x1 TO x2 .
STEP x3

GOSUB

GOSUBx·

Allows the user to enter a
subroutine at several points
in the program. Control
transfers to line x.

GO TO or
GOTO

GO TO n or
GOTO n

Transfers control to line n
and continues execution
from there.

IF-GOTO

IF f1 r f2 GOTO n

Same as IF-THEN.

IF-THEN

IF f1 r f2 THEN n

If the relationship r between
the expressions f1 and f2 is
true, transfers control to line
n; if not, continues in regular sequence. If f1 and f2
are strings they are compared on the basis of the
ASCII numeric value of
each character in the string.

6-109

Last statement in the program. Signals completion of
the program.
Used to implement loops;
the variable v is set equal to
the expression xl. From this
point the loop cycle is completed following which v is
incremented after each cycle
by x3 until its value is
greater than x2. If STEP x3
is omitted, x3 is assumed to be
+1. x3 may also be negative. Ifx3 is positive and
xl >x2, the loop is riever
executed.

Table 6-1 OS/8 BASIC Language Summary (Cont.)
Statement

Example Form

Meaning

INPUT

INPUT vl,v2, ... ,vn

Causes typeout of a ? to the
user and waits for the user
to supply the values of the
variables vi through VD.

LET

LET v=f

Assigns the value of the expression f to the variable v.
The word LET is optional.

NExt v

Used to tell the cQmputer to
return to the FOR statement
and execute the loop ag'ain
until v is greater than or
equal to terminal value in
FOR statement (or v is ~
terminal value if increment
<0).

PRINT al,a2, ... ,an

Prints the values of the specified arguments, which may
be variables, text, or format
control characters (, or ;).

RANDOMIZE

Generates new sets of- random-numbers.

READ

READ vI,v2, ... ,vn

Variables vI through vn are
assigned the value of the
corresponding numbers or
strings in the DATA list.

REM

When typed as the first three
letters of a line everything
between REM and end of
line is ignored to allow typing of remarks within the
program.

RESTORE

Sets pointer back to the beginning of the list of DATA
values.

6-110

Table 6-10S/8 BASIC Language Summary (Cont.)

Statement

Example FOrm

Meaning

RETURN

Transfers control to the
statement following the last
GOSUB.

STOP

Terminates execution at that
point at which the statement
is reached in the program.

UDEF

UDEF function name
(arguments)

The UDEF statement is used
to define the syntax of a call
to a u~er-coded machine
language function (function
name) with its associated
arguments.

USE

USE vl,v2, ... ,vn

The USE statement identifies lists· and arrays referenced by a user-coded machine language function.

OS/8 BASIC FILE STATEMENTS
CLOSE #

CLOSE #N:

Closes a file N previously
opened by a FILE# N statement where N is the numerical expression for the file
number.

FILE #
FILEV #
FILEN #
FILEVN #

FILE #n:s _
FILEV #n:s
FILEN #n:s
FILEVN #n:s

These statements, respectively, open a fixed length
ASCII,
variable
length
ASCII, fixed length numeric, and variable length
numeric file, wnere n has a
value of from 0 to 4 and s
is a strin"g expression with a
value of DEV:FILE.EX.

INPUT #

INPUT #N: vl,v2, ... ,vnReads vI through vn from
file number N.

IF END #

IF END' # N THEN n If an attempt has been made
to read or write beyond the
last datum in file number N,
control passes to line num~
ber n.

6-111

Table 6-108/8 BASIC Language Summary (Cont.),
Statement

Example Form

Meaning

PRINT #

PRINT #N: al,a2, ... ,an Writes the values of the
arguments into file number
N.

RESTORE #

RESTORE #N

Sets pointer back to beginning of file number N.

OS/8 BASIC CONTROL COMMANDS

BYE

Exits from BASIC and returns control to Keyboard
Monitor.

CTRLIC

Stops execution of program
and returns control to OS/8
BASIC editor. In editor
mode returns control to
OS/8 Keyboard Monitor.

CTRLIO

CTRL/O

Stops the listing of text and
returns control to BASIC
editor.

LIST
LI

Lists program with heading.

LISTn

IT
....
..&...J..I.. J.t

IT
...
..L..J..I. 1.1

Lists program starting from
line n, \vith heading.

LISTNH
LISTNH n

LISTNH
LISTNHn

Same as LIST and LIST n,
but heading suppressed.

NAME
NA

NAME FILE.EX
NA FILE.EX

This statement renames the
current program in user
cQre.

NEW
NE

NEW FILE.EX
NE FILE.EX

Used to name a program to
be created. Performs an inherent SCRATCH.

OLD
OL

OLD DEV: FILE.EX Performs inherent
SCRATCH and retrieves a
OL DEV: FILE.EX
previously created file from
the device specified.

RUN
RU

Compiles and executes the
program currently in core,
with heading.

6-112

Table 6-1 OS/8 BASIC Language SwmmaryiCont.)

Statement

Example Form

Meaning

RUNNH

Compiles and executes the
program currently in core,
with heading. suppressed ..

SAVE
SA

SAVE DEV:FILE.EX
SA DEV:FILE.EX

Saves the current· program
on the device specified.

SCRATCH
SC

Deletes all program statements from user core.

OS/8 BASIC FUNCTIONS

Function

Meaning

ABS(X)

This function returns the absolute value of the argu- .
mentX.

ASC(X)

This function returns the decimal ASCII number (see
Appendix A) corresponding to the character X.

.ATN(X)

This function calculates the angle (in radians) whose
tangent is given by the argument X.

CHR$(X) .

X is a numeric expression (modulo 64) which.is truncated to an integer. The decimal integer is converted
to its equivalent ASCII character (see Appendix A).

COS(X)

The cosine fUnction is used to calculate the cosine of .
an angle specified in radians.

~AT$(X)

This function returns the data in the form MM/DDI
YY. The argument X is a dummy argument.

EXP(X)

This function calculates the value of e (2.71828)
raised to the X power;

FNA(X)

Used with a DEF statement to. define a user function.
Thereafter used as any other function.

INT(X)

This function returns the greatest integer less than
the value of the argument X.

LEN(X$)

This function returns the number of characters in
string X$.

LOG (X)

The LOG(X) function calculates the natural logarithm ofX.
,

6-113

Table 6-1 OS/8 BASIC Language Summary (Cont.)
Function

Meaning

PNT(X)

This function, which can only be used in a PRINT
statement, outputs the character whose decimal ASCII
value is X. This function is useful for outputting nonprinting characters.

POS(X$,Y$,Z)

This function returns the location in stririg X$ of the
first occurrence of string Y$ starting with the Zth
character in string X$.

RND(X)

This function returns a random number. between 0
and 1.

SEG$(X$,Y,Z)

This function returns the substring of X$ which is be.tween positions Y and Z inclusively.

SGN(X)

The sign function returns the value 1 if X is any positive number, 0 if zero, and -1 if any negative number.

SIN (X)

This function is used to calcu1ate the sine of an ang1e
specified in radians.

SQR(X)

The square root function computes the square root of
the absolute value of an expression.

STR$(X)

This function converts the numeric value of X to a
string which is its decimal representation.

T AB(X)

This function which can only be used in a PRINT
statement, moves the print head to position X.

TRC(X)

This function turns on the trace feature if x i and
O. When the trace
turns off the trace feature if x
feature is on, line numbers are printed between percent signs as the lines are encountered in the program.
The feature is useful when debugging programs.

V AL(X$)

This function returns the number represented by the
string X$ which is the decimal representation of a
number.

6-114

Compile-Time Diagl1~stics
Compile-time diagnostic messages typed out by OS/8 BASIC are
in the form:
XXyy

where XX is the diagnostic code and YY is the line number at
which the error occurred.

Table 6-2 Compile-Time Diagnostics

Diagnostic Code

Explanation

Error in CHAIN statement.

Error in DEF statement.

Error in DIM statement syntax or string dimension
greater than 72, or array dimensioned twice.

Error in file number or filename designation.

Incorrect FOR loop parameters or FOR loop syntax..

Error in function arguments or function not defined.

THEN or GOTO missing from IF statement, or bad
relational operator.

I/O error.

Missing equal sign in LET statement.

Statement too long (greater than 80 characters).

Line number defined more than once. YY equals
line number before line in error.

Missing END statement.

Operand expected, not found.

Missing parenthesis or error in expression within
parentheses.

OPtirand of mixed type or operator does not match
operands (e.g., A$ 1 and A&2 are both incorrect).

NEXT statement without corresponding FOR statement.

Line number missing after GOTO, GOSUB, or
THEN.

6-115

Table 6·2 Compile.Time Diagnostics (Cont.)
Diagnostic Code

Explanation

Output file error.

Pushdown stack overflow. Result of either too complex a statement (or statements) or too many nested
FOR-NEXT loops.

String literal too long or does not end in quote.

Subscript or function argument error.

S)'

Symbol table overflow due to too many variables,
line numbers, or literals. Combine lines using backslash ("'-) to condense program.

System incomplete. System files such as BASIC.SV,
BCOMP.SV, and BRTS.SV missing.

Program too big. Condense or CHAIN.

Too much data in program.

Too many total characters in the string literals.

Error in UDEF statement.

FOR loop without corresponding NEXT statement.

Undefined statement number. (i.e., statement number mentioned in statement is not in progfam.)

Incorrect or missing array designator in USE statement.

Extra characters after the logical end of line. (E.g.,
LET A=B.D-the dot after the B suggests that B
is the end of the line and the characters .D appear
extraneous. )

Run-time Diagnostics

Run-time diagnostic messages typed out by OS/8 BASIC are in the
form:
XX AT LINE YYYYY
where XX is the diagnostic code and YYYYY is the line number
at which the error occurred. Most runtime errors stop execution of
the program. Those errors which do not stop the program are
termed non-fatal (NF) and are indicated below.
6-116

Table 6-3 Run-time Diagnostics

Diagnostic Code

Explanation

No more file buffers available.

Inquire failure in CHAIN. Device not found.

Lookup'failure in CHAIN. Filename not found.

Attempt to read past end ,of data list.

Device driver error. Caused by hardware 110 failure.

No more room for drivers. Too many different devices used in file commands.

Attempt to divide by 0. Results is set to zero. (NF)

Logical end of file. Usually caused when I/O device
runs out of medium.

Attempt to exponentiate a negative number to a
power.

Enter error in opening file. Device is read only or
.there is already one variable file open on that device
or file not found.

FILE busy. Attempt to use a file already in use.

OS/8 error while closing variable file. Device is read
only on file closed already.

Fetch error in opening file. Device not found, or device handler too big for available space. ,

FI .

Attempt to close or use unopened file.

Attempt to fix minus number. Usually caused by
negative subscripts or file numbers
.
.,

Illegal file number. Only 0,1,2,3,4 are legal.

Attempt to fix number greater than 4095. Usually
caused by negative SUbscripts of 'file numbers.

RETURN without a GOSUB.

Too many nested GOSUBs. The limit is 10.

Illegal argument in UDEF function call.

Illegal DEV: filename specification.

IN,

Inquire failure in opening file. Device not found.

6-117

Table 6-3 Run-time Diagnostics (Cont.)
Diagnostic Code

Explanation

TTY input buffer overflow. Cause input buffer to be
cleared and outputs another? (NF).

Attempt to take log of negative number or O.

Driver error '~Jhile c'lerlaying. Caused by SYS device hardware error.

Numeric or input overflow.

Illegal argument in POS function.

Atempt to read past end of file. (NF)

String too long (greater than 72 characters) after
concatenating.

String too long or undefined.

Attempt to read string from numeric file.

String truncation on input. Stores maximum length
allowed. (NF)

SUbscript out of DIM statement range.

Attempt to write string into numeric file.

Attempt to read variable length file.

'VE

Attempt to write past end of file (NF).

OS/8 BASIC System Build Instructions
OS/8 BASIC is distributed on DECtape and paper tape. The
DECtape version of OS/8 BASIC contains SAVE images (readyto-run)" for each of the OS/8 BASIC system components as well
as binaries for each system component. The paper tape distribution
includes binaries for each of the system components. OS/8 BASIC,
then, is distributed as the following files:
File

Component

Distributed on:

BASIC.BN
BASIC.SV
BCOMP.BN
BCOMP.SV

Binary for editor
Editor save image
Compiler binary
Compiler save image

DECtape and paper tape
DECtape only
D ECtape and paper tape
DECtape only

6-118

BLOAD.BN
BLOAD.SV
BRTS.BN

Loader binary
DECtape and paper tape
Loader save image·
DECtape only
Run-time system binary DECtape and paper tape
(any PDP-8 orPDP-12)

EAEOVR.BN Overlay for KE8/E EAE
(8/E with KE-SE-EAE)
Run-time system save
BRTS.SV
image (from BRTS.BN)
Arithmetic function
BASIC.AF
overlay
BASIC.SF
String function overlay
-BASIC;FF
File manipulation overlay

DECtape and paper tape
DECtape only
DECtape only
DECtape only
DECtape only

. Making SAVE Images from Binary-Files:
.
To create SAVE images of each of the OS/S BASIC binaries, perform the following OS/8 commands.
1. For the editor:
.R ABSLDR
*DEV:BASIC.BN$
.SAVE SYS:BASIC;3011
2. For the compiler:
.R ABSLDR
*DEV:BCOMP.BN$
.sAV~ SYS:BCOMP;7000
3. For the loader:
.R ABSLDR
*DEV:BLOAD.BN$
.SAVE SYS:BLOAD;7605
4. For the run-time system:
.R ABSLDR
*DEV:BRTS.BN$
(without KE8/E EAE option)
or
*DEV:BRTS.BN,DEV:EAEOVR.BN$
(PDP-S/E, PDP-8M or
PDP-SF with KE-8E EAE)
6-119

.SAVE
.SAVE
.SAVB
.SAVE

SYS:BRTS 0-6777
SYS:BASIC.AF 3400-4577
SYS:BASIC.SF 12000-13177
SYS:BASIC.FF 13400-14577

NOTE
All BASIC system files must reside on the
systems device (SYS:).

5. At this point, BASIC is ready to run.
Assembling the BASIC sources
In~tructions for assembling each of the OS/8 BASIC sources
follow. PAL-8 (under OS/8) is used, and the descriptions represent
OS/8 commands. To assemble OS/8 BASIC, a 12K machine is
required.,The OS/8 BASIC sources are named as follows: .
NAME.MM
where MM represents the version number. For the first release, the
files are named:
Name

Component

BASIC.03
BCOMP.03
BLOAD.03
BRTS.03

Editor Source
Compiler Source
Loader Source
Runtime System Source

1. To assemble the editor:
.R PAL8
*DEV :BASIC.BNJ

.n~-

General Description

This program contains a set of 12 functions which enable a user
of OS/8 BASIC to utilize the following peripherals ort a LAB8/E:
AID converter, VC8-E display control, DK8-ES real-time clock,
6-124

and DRS-EA 12-channel.buffered digital I/O. All functions, contained in an overlay called BASIC.UF, reside in the overlay area of
. BASIC (3400-4577) with the understanding that the entire set of
functions is in core whenever a given function is in use. Each function is called by a suitable three-character name, followed by any
necessary arguments.
General regulations on arguments passed by the user functions in
this package:
1. All arguments must be within the following range:
04095) will cause
the fatal error, Fa .. Fatal errors terminate program execution
and return the user to command mode.
2.. Furthermore, certain functions in this package require that the
arguments be further restricted. These restrictions will be stated
along with the discussion of each function later on. Argument
errors due to these added restrictions will cause the fatal error,
IA (illegal argument).
Preparing Basic for LABS / E Functions
The Basic Run-Time System (BRTS) provides for one overlay
area and ·divides a set of infrequently used functions into three separate overlays; namely, BASIC.AF, BASIC. SF and BASIC~FF.
Since a logical need for user-written assembly language subroutines
exists, a last overlay, BASIC.UF was reserved. It is this last overlay
that contains the 12 functions for LABS/E support. Since the subroutines of this last overlay are determined apart from BRTS, it is
necessary that BRTS be given a list of core addresses for each of
the user subroutines. It is critical that the order of specifying these
. links or addresses be in the same order that the UDEF statements
will appear in the program that calls the functions.
Before writing any program using these functions, it is absolutely
necessary to modify BRTS. The following exampJe illustrates how
this is done. Notice that in the test programs at the end, the order
in the UDEF statements is the same as the ordering of the addresses
here. A list of the names of the functions associated with each address is specified to the right for the sake of clarity only.
6-125

~GET

SYS

~RT5.5V

..!. 00
1/~

used for interrupts

541t12

0000c I~ 4450
15~0/**** 3400

015bl
015~2

015b3

INI
PLY
DLY
DIS
SAM
CLK
. CLW
ADC

I~ 3454
I~ 3413
I~ 3b00
I~ 400~

015b4
0iSb5 I!!!! 4100
015bb I~ 3~41
1'lI15~7

01570
01571

I~
I~
I~

01572

1****

01573
1'C:

.&AvE SYS

3521
4400
4432
4211
4313

GET
PUT
DRI
DRO

e~TS.SV

Since many of BASIC's functions also reside in overlays, the user
is cautioned about using a function. that will cause the current set
of functions to be overlayed and thereby destroy any useful information. For example, the user cannot calculate a set of cosine
values and pass them to the PLY function to be stored, because
COS resides in BASIC.AF overlay and PLY resides in BASIC.UF.
Once BRTS has been modified to recognize the user function
from the BASIC.UF overlay, BASIC programs making use of these
functions may be written. If a program requires the use of the Nth
function in the ordered list of links, the first (N-I) functions of
the list must be defined by UDEF statements or a set of (N-l)
dummy-named functions must precede the defining of the Nth function. For example:
In reference to the ordered list of functions in the previous section, if the ADC function is the only one to be used in a particular
BASIC program, the UDEF statements must be:

10
11

UDEF INI(N),PLY(Y),DLY(N),DIS(S,E,N,X)
UDEF SAM(C,N,P,T),CLK(R,O,S),CLW(N),ADC(N)

6-126

10
11

UDEF DUA(N),DUB(N),DVC(N),DUD(N)
UDEF DUE(N) ,DUF(N) ,DUG(N),ADH(N)

However, it is recommended that the user always- use the complete
set of UDEF's each time one requires one or more functions in a .
program. This is recommended solely to keep careless omissions to
ammlmum.
INI(N)
The -initialize function has a twofold purpose. Its main purpose
is to locate the address of the array specified by BASIC's USE
statement and retain that address until BASIC.UF is overlayed by
one of the other three overlays.
A secondary purpose is to set a pointer to the first location of
the array. Consequently, an array may be used to store one set of
data .followed immedi(~.tely by a second" set of data, provided the
INI function was called only once. This means that displayable.
data (10 bits), and fixed point data (12 bits) may share the user
array at the user's' discretion. If, however, the INI function was
again specified at the end of the first data run, the first set of data
is overwritten by the second set of data. Hence, INI effectively zeros
the array in this case. Whenever an array is to be used in conjunction with one or more of the functions in the BASIC.UF overlay,
user first dimensions the array and eventually employs the USE
statement before the INI function can have meaning. For.example:
DIMA(3)

USE A

- 6-127

X=INI(O)

The argument N, for INI, is a dummy argument, and may be any
integer; 0, 1, 2, . : .
\Vhenever the functions PLY, DIS, SAM, GET, and PUT are
used, make sure that the INI fu~ction has been previously called at
least once. When an array is given the dimension N, BASIC allocates (N+ 1) floating point words of memory which is actually
3 (N+ 1) single memory locations. Thus, in the example above,
BASIC allocates 4 floating point words or 12 single memory locations for the array. Each data value deposited into the user's array
by the user functions is a single precision value (uses one memory
word).
PLY(Y)
The purpose of the plot function is to enable a BASIC program
to create y-data values and enter them into the user array sequentially, beginning with the first unused location of the array. Each
floating point value is fixed to a ten (10) bit single precision value
before it is put into the array. The range of the y-data values must
be:
O~y~l.O

This is easily accomplished by inserting a scaling factor. (Refer to
line numbers 26 and 64 of the example program TESTOA.PG at
the end of this chapter.)
The data in the user array can be displayed as it is being passed
to the array (see DLY function) and/or be refreshed continuously
once all values have been entered into the array (see DIS function).
DLY(N)
The delay function is used only in conjunction with the PLY
function. It causes the scope to be refreshed with the contents of
the User array after each point is processed, so that the graphical
p·rogress of data can be observed:
6-128

N is.an integer such that 1~N~1024. It specifies the maximum
number of points to be eventually displayed. Implied here is the.
-fact that the display will contain only the.first N points even if the
arrays contain more than N points.
DIS (S,E,N,X)
-. The display function is used to. set up parameters for the displaying of y-data stored in the user array. The_ display will begin
with the desired starting point, S of the array and display every Nth
point while not exceeding the desired endpoint, E (where N= 1,
2,3, ... ).
Depending on the value of X, the DIS function has two separate
operations. Operation when _x equals zero (X==O): Indication is
given to the user-overlay-functions that a SAM function will· be the
next BASIC instruction. Consequently the parameters mentioned
above are set up so that exactly one of the sampled channels can be
disphiyed 'on the fiy'. To understand the use of the arguments
S,E,N,X; it is necessary to know how the A/D data is stored in the
user array. For example assume 100 samples/channel in each case:

ARRAY

CASE 1
SAMCH#O

CASE 2
SAM CH #3,4,5

WD1
WD2
WD3
WD4
WD5
WD6

CH#O
CH#O
CH#O
CH#O
CH#O
CH#O

CH#3
CH#4
CH#5
CH#3
CH#4
CH#5

WD100

CH#O

CH#3

To display CASE1, once sampling begins:
DISC 1,100,1,0)
To display CH#4 of CASE2, once sampling begins:
DIS(2,100,3,0)
6-129

Operation when X is greater than zero (X>O): A user array of
y-data is to be displayed immediately. The display is continually
refreshed (no return to BASIC) until the operator types CTRL/N
on the keyboard.
Displayable y-data values are assumed to be 10-bit single precision
data words.
The x-coordinate for each y-data value is determined by a DELTAX value found as follows;
DELTAX = 1023//[E-S)/N]
Due to the outcome of DELTAX, the display may not always use
the full width of the scope. However, the display is always centered.
S~l; E~S; (E-S)/N~1023. At least one point must be displayed and no more than 1024 points may be displayed.
SAM(C,N,P,T)
The sample function is used solely to set up parameters for subsequent sampling of the ADC's or for subsequent sampling of
digital input registers (0,1,2) depending on the value of T.
TASK 1 (T=O): Sample the ADC's
C = First channel # to be sampled; 0~C~178.
N = Number of consecutive channels to sample; 1~N ~ (20s-C) .
P == Number of sample

points/channel~

P=O.

TASK 2 (T=O): Sample digital input registers.
C = First register # to be sampled; 0~C~2.
N = Number of consecutive input registers to sample;

1~N~(3-C).

P = Number of samples/register; P=O.
Anytime a SAM instruction is used to sample the ADC's, exactly
one channel must be displayed on the fly. However, the sampling
rate is not slowed down by this requirement. Hence a DIS function
call must precede a SAM function call whenever TASK 1 is chosen.
It is possible to display digital input data so long as only the least
significant 10 bits will be displayed. However, this data can not be
_, displayed 'on the fly' and can only be displayed via the DIS function once all data is in the array.
6-130

CLK(R,O,S)
The clock function sets up the clock to be used for AID sampling, f-or digital input sampling, or as a simple timing device ..
R(rate) = desired frequency at which to run the clock
Frequency

Value of R

External input
100HZ
1KHZ
10KHZ
lOOK HZ - 1MHZ

1
2
3
4
5
6

°(overflow CNT) = number of clock ticks per interrupt with

the clock running at the desired frequency, R. O~O~4095
S (Schmitt trigger) (St=O) = Activate all Schmitt triggers and
start the clock when anyone of the three Schmitt triggers fires.
(S=O) Do not activate any Schmitt triggers and start up the clock
immedia tely.
As mentioned above, this single clock fmiction is used to set the
clock for one of three separate tasks.
TASK 1: Sample the ADC's.
The interrupts are turned anI and the program waits in the display loop for a clock overflow; at which time the AID channel(s)
is (are) sampled. The display loop will display the data for the
channel specified by the user in the DIS function. When an channels have been sampled the requested number of times, the CLK
function returns to BASIC.
TAS~2:

Sample digital input registers.
At each clock overflow, the digital input register (s) is ( are)
sampled. When all registers have been sampled the requested num.ber of times, the CLK function re,turns to BASIC.
1 When interrupts are turned on; the only possible valid interrupts can be
caused by the keyboard or the clock. Hence, any other interrupt is an uncontrollable, spurious interrupt (faulty hardware) which will cause a HLT
at location 4466. If this happens, do the following:
1. Set SWITCH REGISTER to 4476 and press ADDR LOAD.
2. Next, press the CLEAR and CaNT switches to return to BASIC.
3. Type CTRL/C to return to the OS/8 Monjtor.

6-131

NOTE
The sampled data from the ADC's or· the
digital input registers is stored sequentially
in the, user's array.
~

T ASK3: A simple timing device.
The clock is set up and started (unless it is to be started when a
Schmitt trigger fires) and then returns to BASIC.
The following illustrates what sequence of instructions are
needed for each task.
TASK1

TASK2

TASK3

DIM A(n)
USE A

Z=CLK(R,O,S)

W=INI(O)
X=DIS(C,N,P,T)
Y =SAlvl (C,N,P ,0)
Z=CLK(R,O,S)

W=INI(O)
Y=SAM(C,N,P,l )
Z=CLK(R,O,S)

CLW(N)
With the clock having been set up by CLK as a simple timer,
this clock wait function, when called, simply returns to BASIC
whenever a clock overflow occurs; and/or whenever a Schmitt trigger fires,provided S was a non-zero argument in CLK.
Upon return to BASIC, a number is returned to the caller indicating whether the return was due to a clock overflow, a Schmitt
trigger, or a clock overflow and the firing of a Schmitt trigger simultaneously. The number also indicates whether one of the above
conditions occurred before or after the CLW function was called.
N is a dummy argument (N=O,1,2, ... ) .
6-132

The following table illustrates the various numbers returned.
Case 1: Clock overflowed or a Schmitt trigger fired after CLW is
called.
Overflow only

Schmitt Trigger Only
1 (Trigger 1 fired)
2 (Trigger 2 fired)
3 (Trigger 1 & 2 fired)
4 (Trigger 4 fired)
5 (Trigger 1 & 4 fired)
6 (Trigger 2 & 4 fired)
7 (Trigger 1,2 &4 fired)

Simultaneously
- 1
- 2
-3
-4.
-5
-6
-7

Case 2: Clock overflowed or a Schmitt trigger fired before CLW is
called.
Overflow only

Schmitt Trigger only

-8

9
10
11
12
13
14
15

Simultane~usly

-9
-10
-11
-12
-13
-14
-15

The TEST4A;PG and TEST5A. PG examples make use of the
CLW function.
The CLW function has many useful applications. Subroutine
timing may be accomplished by starting the clock with a specific
rate and overflow count. The subroutine is called, and at the end of
the subroutine the CLW function is called to see if an immediate
return is obtained. This timing is empirical in that the user "would
keep changing the rate and/or overflow count until Case 2 occurred .. Secondly, Schmitt trigger firing may be used to branch to
a pa"rticular subroutine or to notify the program to proceed with
specific tasks such as" reading digitaJ data or sampling an analog
input. Thirdly, time interval histograms and post stimulus histograms are also possible (see TST20A.PG).
6-133

ADC(N)
This function is issued any time one wishes to sampJe AID chaimel
N. The 10 bit data value is floated and returned to the ca11er for
immediate examination. O~N ~ 17 8 •
The BASIC statement W=ADC(3) asks that AID channel #3
be sampled and the floating point value be assigned to W.
The TEST5A.PG example illustrates one use of the ADC function.
GET(M,L)
This function is used to get one 12 bit word from the user array,
mask out certain bits and return the result as a floating point number to .the caller.
Lis Lth location of the user array. Hence, if an array has N single
precision words, L can take on meaningful values of 1,2,3, ... ,N.
NOTE
Although BASIC allows 0 to be a meaningful value in a dimension statement such as
DIM A(O), it must be understood that L
always begins with 1, where 1 stands for the
first ,single-word location of the array. Thus
DIM A(O) specifies an array of one floating
point word (three one-word locations) .

r-..1 is a masking number such that

O~rvf~4095.

This fluating
point number is converted to a 12 bit binary number between 0
and 7777. Those bits that are zero will mask out or eliminate those
bits in the array value. If M=O, then no masking is done and the
12 bit array value is returned intact. M=O and M==4095 have the
same meamng.
The BASIC statement Y =GET ( 15,2) gets the second word of
the user array, masks out all bits except bits 8,9,10,11 and assigns
the floating point result to Y. Consequently, if an array is as
follows:
_

single prec WD 1 . ~ 5678
single prec WD2 ~ 1234
single prec WD3 ~ 4455

6-134

FI. pt. word 0

WD2 ~ 12348 = 0010100111002
MASK = 15 10 = 178-0000000011112
The 12 bit value after masking is:
000000001100 2 = 1210
Hence, Y=12

NOTE
For user assistance in understanding decimal
to octal to binary conversions, refer to-Introduction to Programming.
PUT(M,L)
~ This function enables a floating point number to be fixed to a
,
single 12,bit word and put into the user's array.
L is Lth location of the user's array. For an array of N single
preCision words, L can take on meaningful values of 1,2,3, ... ,N.
- M is the floating point number to be fixed and stored in the
array. 0:::;;M:::;;4095.

NOTE
Both GET and PUT functions imply that a
user's array must not exceed 4096 memory
locations, because of the general restriction
on any argumept for these' user functions.
The BASIC statement Y=PUT(128,4) means fix 128 to 12
bits (000 010 000 000 2) and- put the value' into the 4th word
of the user array. TST15A.PG, TST16A.PG, TST17A.PG and
TST18A.PG illustrate the use of functions GET and PUT.
DRI(N)
This function is issued any time one wishes to sample a digital .
input register, N (0:::;;N:::;;2). The 12 bit digital value is" returned
to the user as afloating point number. Basic statement: X=DRI(O)
means that input register #O,is sampled and the floating point result
is assigned to X.
DRO(M,N)
This function is issued any time one wishes to set the bits of a
digital output register, N (0:::;;N:::;;2). The output register bits are set
via the value of M (l:::;;M :::;;409 5). If M=O, the output register is
6-135

cleared, otherwise the bits of the register remain set. Hence, additional bits of the register can be set while maintaining those set
earlier.
Basic statement: Z-DRO(9,1) means set bits 8 and 11 of output register # 1 if not already set.
910 -

000000001001 2

DRO functions.
LAB8/E Examples
The following set of BASIC programs illustrates a number of
ways the user functions may be implemented. Each program has
been kept as simple as possible.
.
Note that for TSTI2A.PG, TSTI3A.PG and TSTI5A.PG a battery powered 'black·box' was. used to interact with the digital I/O
registers. The box contained a set of 12 switches which could set
any combination of bits for the digital input register, and it also
contains a row of 12 lights that were lighted by the contents of the
12 bit digital output register. When running TST18A.PG, use the
data from TST17A.PG.

1 REM -

PROGRAM NAME:

TEST0A.PG

2 REM 3 UDEF I:-J I (N) " PL Y (Y ) ~ DL,« N) " D1 S( 5" E" :"oJ" X)
4 UDEF' SAM(C"N"P"T>"CLK(R"O"S)"CLw
49 REM 50 REM - CALC 30 PTS & 01 SPUW ONLY
51 REM - WHEN DCNE.
60 Z=IN1(0)
62 FOR N= 1 TO 30

6-136

64
66
68
70
80

Y=<2+N+l)/61.1
Z=PLY
END

1 REM PROORAM NAME:
TESTIA.PG
2 REM 3 UDEF INI CN), PLYCY.), DLY(N), DI SC S, E,N,X)
4 UDEF SAM(C,N,P,T>,CLKCR,O,S),CLW(N),ADC(N)
5 UDEF GET(M,L),PUTCM,L),DRICN),DRO(M,N)
6 DIM A( 342)
10 REM 11 R~M - SAMPLE CHAN 0 (1024 TI MES) J DI SPLAY
12 REM - ALL PTS eN THE FLY.
13 REM - 10INTERRUPTS/SEC
14 REM .20 USE A
21 W=INI(0)
22 W=OI S( 11 Hl241 1,0>
24 X=SAM( 0, I, 1024,0)
26 Y=CLK( 3, HHh 0)
28 Z=DI S( I, 10241 11 1)
40 REM .41 REM - SAMPLE CHANNELS 0,1 C 100 TIMES EACH).
42 REM - 10 INTERRUPT S/SECJ DI SPLAY CHAN 0 WHI LE
43 REM - SAMPLING,WHEN DONE SHOW THREE :DIFF
44 REM - DI SPLAY.S: DI SPLAY CHAN 0--HI T tN 01 SPLAY
45 REM - CHAN I--HI T tN DI SPLAY CHANS 0&1.
50 USE A
51 W=INI(0)
52 W=DI S( 1,200,2,0)
54 X= SAM ( 0, 2, 1(0 1 0)
56 Y=CLK C3, 100'10)
, 58 Z=DI S( 1,200,2, 1>
60 U=DISC2,200,2,t)
62 V=DI S( h 200, I, t)
70 END

1 REM PROGRAM NAME:
TEST2A. PG
2 REM 3 UDEF INI(N)"PLY(Y),DLYCN),DIS(S,EIN,X)
4 UDEF SAMe CIN I PI T)' CLK( RIO, S)' CLW( N), AuCC N)
5 UDEF GET(M,L)IPUTCMIL),ORICN)IDROCM,N)
6 DIM A( 342)
10 REM 11 REM - CALC A PARAbCLA CF 601 PTS AND DI ~PLAY
12 REM - CN THE FLY. WH EN D CN E 01 SPLAY EVE.hY 10TH
13 REM - PT OF PARABCLA.

14
20
22
24
26
28
30
32
34
50
51

52
53
60
62
64
66
68

70
72
80

REM USE A
Z=INI(0)
FOR N=-300 TO 300
Y=(N*N)/100000
X=PLY(Y)
~;=DLY(

601>

NEXT N
V=DI S( 1.. 601 .. 10" 1>
REM.
REM - CALC A CU8I C OF 6e.. PTS g 01 SPLAY
REM - WHEN DCNE 01 SPLAY EVERY 10TH PT.
REM Z=INI(0)
FOR N=-300 TO 300
Y=(~*N*N+27000000) 154000010
X=PLY< Y)
W=DL Y ( 60 1>
NEXT N
V=DI S( 1.. 601 .. 10" 1>
END

1 REM -

PROGRAM NAME:

Q\j

FLY

1 EST3A. PG

2 REM -

3 UDEF INICN)"PLYCY)"DLY(N)"DISCS"E"N"X)
4 UDEF SAM(C .. N"P"T)"CLKCR .. O"S) .. CLW(N)"ADCCN)
5 UDEF GET(M"L}"PUT(M"L)"DRI(N)"DRO(M"N)
6 DIM A( 342)
10 REM 11 REM - ILLUSTRATE ABILITY TO ACCESS USEK bUFFEK.
12 REM -

13
14
20
22
24
26
28
30
32
34
36
38
40
50

PUT NUMbERS

1-10 !NTO EUF !N THAT ORDEF·

REM - & READ THEM OUT IN THE REVERSE ORDER.
REM Z=INI(0)
FOR N=1 TO 10
PRINT N
T=N
R=PUT< T"N)
NEXT N
FOR N=1 TO 10
N= II-N
P=GET< 0 .. M)
PRINT P
NEXT N
END

6-138

1 REM PROGRAM NAME:
TEST4A.PG
2 REM 3 UD,EI' INICN),PLYCY),DLY(N),DIS(S,E,N,X)
4 UDEI' SAM( C,N, P, T>, CLK( R, 0, S~, CLW( N), ADC( N)
5 UDEI' GET(M,L),PUTCM,L),DRICN),DRO(M,N)
6 REM - SAMPLE CHAN 0 I I' CL OCt< 0.1'.
'
7 REM - SAMPLE CHAN 1 I I' SCHMI TT ONLY
8 REM - SAMPLE CHAN I I' BOTH n RE
9 REM - II' EARLY, TELL USER
10 REM - ROUTINE ALSO OUTPUTS Z
11 X= CLK ( 3, 41!HHh 1)
1 2 I' OR N = 1 TO 1 0
14 Z= CLW C(0)
15 PRI N T
= "'; Z
16 II' z=e GOTO 310
18 I I' Z < 10 GOT 0 24
19 I I' Z<8 GOTO 34
210 I I' Z=8 GOTO 410
21 GOTO 410
24 I I' Z<-8 GOTO 40
26 W=ADC( 2)
28 GOTO 36
310 ~J=ADC( 0)
31 G OTO 36
34 W=ADC( 1)
36 PRINT W
37 GOTO 42
410 PRI NT "E.o,RL Y"
42 NEXT N
50 END

1 hEM -

2
3
4
5

PROGf'AM ,\JAME:
TEST5.o,. PG
UDEF INI(N),PLY(Y),DLYCN),DISCS,E,N,X)
ODEI' SAM( C,N, P, T>, CLK( R, 0, S)., CL!,oJ( N), ADCC N)
UDEI' GET(M,L),PUTCM,L),DRI(N),DROCM,N)
DIM AC 342)
•

10 REM -

11
12
13
14
210
22
24
26
28
310
40
, 41
42

REM - USE CLK AS A 51 MPL E TI MER.
REM - SAMPLE CHAN 0 EvERY 4TH SEC AND PUT VAL TO TTY
REM - DO THIS 10 TIMES
REM X=CLKC 3, 401010, 0)
I' OR 1= 1 TO 10
Y=CU1( 0)
Z=ADC( (il)
PRINT Z
NEXT I
REM REM - USE CL K A S A S I MPL E TI MER
REM - SAMPLE CHAN 1 TEN TU·1I~~5 & SYNC OFF ANY

6-139

43
44
50
52

54
56
58

60
70

1
2
3
4
5

REM - SCHMI TT TRI GG ER
REM X=CLK ( 4" 4000" 1)
FOR 1=1 TO 10
Y=CLW(0)
Z=ADC( 0)
PRINT Z
NEXT I
END

REM PROGRAM NAME: TEST7A.PG
REM UDEF INICN)"PLY(Y)IDLY(N)ID1S(SIEINIX)
UDEF SAMCC"NIPIT)ICLK(RIOIS)ICLW(N)IADC(N}
UDEF GET(MIL)IPUT(MIL)IDRI(N)IDRG(M"N)
DHl A(342)
USE A
REt'l - D1 S.PLAY A TRIANGLE

6
7
8
10 Z.=INI(0~
12 FOR ~= 1 TO 30
14 Y=N/3001
16 W=PLY{Y)
18 Z=1/30ol

20
22
24
26
27
28
30
32

U=PLY(Z)
P=DLY( 118)
NEXT N
FOR N=l TO 29
t-1=30 -N
Y=N/30.1

W=PLY(Y)
Z=1/30.1

34 U=PLY(Z)

36
38
40
42

P=DLY(118)
NEXT N
V=D1S(1111811 1 1)
END

REM PROGRAM NAME:
TEST8A.PG
REM UDEF INICN)IPLY(Y)"DLYCN)IDISCS"E1N"X)
UDEF SAMCC"N"P"T)"CLKCR"O"S)"CLWCN)"ADCCN)
6 DIM AC 342)
10 REM II REM - SAMPLE CHAN 0 100 TIMESIDISPLAYI
12 REM - HOWEVER SYNC OFF SCHMITT TRIGS.
1
2
3
4

6-140

14
32
34
36
38
40
42
511'

REM USE A
W=INI(0)
W=DISCI ..
X=SAM(0 ..
Y=CLKC3 ..
Z=DIS(I ..
END

1 REM -

100 .. 1.. 0)
I .. 1011' .. 11')
1011' .. 1)
100 .. 1.. 1>

PROGRAM NAME:

TEST9A.PG

2 REM 3 UDEF IN1(N) .. PLY(Y) .. DLY(N) .. DIS(S .. E.. N.. X)
4 UDEF SAM(C .. N.. P .. T) .. CLK(R .. O.. S) .. CLWCN) .. ADCCN)
5 UDEF GET(M .. L) .. PUTCM .. L) .. DR1CN) .. DROCM .. N)
6 DIM A( 342)
10 REM 11 REM - CALC A PARABOLA OF 401 PTS AND D1 SPLAY ON FLY
13 REM 20 USE A
22 Z=INI(0)
24 FOR N=-200 TO 211'0
26 Y=CN*N)/40001
28 X=PLYCY)
30 W=DLYC 401)
32 NEXT N
511' REM 51 REM - CALC A CUBIC OF 401 PTS & DISPLAY ON FLY
52 REM - SHOW PARABOLA. WHEN DONE DI SPLAY EVERY PT-53 REM - & THEN EVERY 10TH PT
54 REM 62 FOR N=-2eJ0 TO 200
64 Y=CN*N*N+8000000)/16000010
66 X=PLY(Y)
68 W=DLY(802)
70 NEXT N
72 V= DI SU .. 802 .. l..t)
74 V=DI SC 1.. 802 .. 111' .. 1)
80 END

1
2
3
4
5
6

REM PROGRAM NAME:
TST10A.PG
REM UDEF INI .. CLKC R.. 0 .. S) .. CLWCN) .. ADCCN)
UDEF GETCM .. L) .. PUTCM .. L) .. DRICN) .. DROCM .. N)
DIM A(342)

6-141

7 REM - THIS ROUTN RETURNS 4 DIGITS-3BITS/DIGIT
10 USE A
11 Z=INI(0)
12 PRINT "VALUE"
14 INPUT Y
16 Z= PUT CY1 1 )
H~ P=GETC 71 1>
19 PRINT P
20 P=GETC 561 1 )
21 PRINT P
22 P=GETC4481 1)
23 PRlf'.JT P

24
25
26
30

P=GETC 35841 1>
PRINT P
GOTO 12
END

1 RDt -

PROGRANJ NAME:

TSTI2A.PG

2 REM -

3 REi'-! - THIS ROUTN SAHPLES DIGITAL BOARD
4 RDt - III TEN TIMES 1 ONCE EVERY 4 SECS &. PUTS
5 RE!1 - THE VALUES INTO USER BUF THEN I T PRINTS
6 REM - OUT THE 10 VALUES
10 UDEF INICN)IPLYCY)IDLYCN)IDIS(SIEIN1X)
11 UDEF SAMCCIN1P1T)ICLKCR10IS)ICLHCN)IADCCN)
12 UDEF GET(MIL)IPUTCMIL)IDRICN)IDROCMIN)
20 DIM A(342)
22 USE A
23 W=INI(0)
24 X=SAl'1Cl I 111011)
26 Y=CLK(31400010)
2 8 FO R N= 1 TO 1 0
30 1;,'=GETC 01 N)
32 PRINT \\1
34 NEXT N
40 END

1 RE-I 2 REM 3 REM 4 REM 5 RE!1 10 UDEF
11 UDEF
12 UDEF

PRO GR.At1 NAtvlE:

TST 13A. PG

TEST THE OUTPUT REG-SEE THE LIGHTS LITE
UP.
OCTAL INPUT LIGHTS THE LIGHTS AND
THE LAMP? AN INPUT OF 0 CLEARS THE OUTPUT REG
INICN)IPLY(Y)IDLYCN)IDISCSIEIN1X)
SAMCCINIP1TbCLK(R101S)ICUJ(N)IADC(N)
GETCMIL)IPUTCMIL)IDRICN)IDROCM1N)

6-142

14
16
18
19
20
22
30

\II= ORO ( 0" 1 )
PRINT "NUMBER"
INPUT Y
IF Y=0 GOTO 14
vl= ORO Cy" 1 )
GOTO 16
END

REr1 -;
PRO GRAM NAME:
TST 15A. PG
REM UOEF INICN)"PLY(Y)"OLYCN)"OIS(S"E"N"X)
UOEF SAM CC"N" p" T)" CLK (R" 0" S)" CLvJ(N)" AOC (N)
UOEF GET CM" L)·" PUT (M" L)" ORI eN)" DRO CM"N)
6 DIM A(342)
7 REM - THIS ROUTN RETURNS 3 DIGITS-4 BITS/DIGIT
8 REM - (MASKING) IT FIRST OUTPUTS THE DECIMAL
9 REM - EQUI V OF THE NUMBER
Ie USE A
11 Z=INICe)
1 2 v]= DR I ( 1 )
13 PRINT \.T
1 6 X= PUT OJ" 1 )
1 8 P= G ET ( 1 5" 1 )
19 PRINT P
2121 P=GET (240" 1 )
21 PRINT P
22 P=GET(3840" 1)
23 PRINT P
24 PRINT "',TASTE TIME"
25 INPUT R 26 GOTO I?
3121 END
2
3
4
5

RE~1 PROGRAM NAME:
TSTI6A.PG
REM UDEF INI(N)"PLY(Y)"DLYCN)"DISCS"E"N"X)
UDEF SAMCC"N"P"T)"CLKCR"O"S)"CLv,TCN)"ADCCN)
UDEF GETCM"L)"PUT(M"L)"DRI(N)"DRO(M"N)
6 DIM A(3)
7 REM - THI S RO UTN SHOVS THAT ANY N; e<=N<=4e9 5
8 REr-l - PUT I~JTO A USER BUF IS RETURNED AS THE
9 REM - SA!1 E VALU~.
Ie USE A
11 Z=INI (e)'·

2
3
4
5

6-143

12
14
16
18
20
26
313

PRINT "NUMBER"
INPUT Y
X=PUTCY,I)
Z=GETCe,l)
PRINT Z
GOTO 12
END

1 REM PROGRAM NAME:
TST17A.PG
2 REH - FILL AIIJ ARRAY 0 F 313 'lORDS WI TH THE
3 REM - FIRST 313 INTEGERS. WRITE THE ARRAY
4 REM - OUT TO DECTAPE.
5 UDEF INICN)"PLYCY)"DLYCN),DISCS"E,N,X)
6 UDEF SAMCC,N .. P .. T)"CLKCR,O,$)"CL"JCN)"ADCCN)
7 UDEF GET(M,L)"PUT(M"L) .... DRICN) .. DROCH"N)
8 DIM A(9)
9 USE A
Ie X= IN ICe)
11 FOR N= 1 TO 30
12 PRINT N
13 X=PUTCN .. N)
14 NEXT N
16 FILEVN'l:"DTAl:DATA.PG"
2 2 FO R I = 13 TO 9
24 PR IN T 11: A C1 )
26 NEXT I
28 CLOSE it
30 El..JD

REM PROGRAH NA~E:
TSTI8A.FG
REM - READ INTO AN ARRAY 1 e FL PT vms
REM - (313 INTEGERS FROt1 t1S) WRITE OUT THE
REM - 313 INTEGERS ON TTY
5 UDEF IN1(N) .. PLYCY) .. DLY(N)"D1SCS .. E,N,X)
6 UDEF S~1CC .. N,P,T) .. CLKCR .. 0 .. S) .. CLW(N) .. ADCCN)
7 UDEF GETCM .. L) .. PUTCM,L) .. DRICN)"DROCM"N)
8 DIM A(9)
9 USE A
20 FILEN 1I1:"DTAl:DATA.PG"
22 FOR 1=13 TO 9
24 INPUT 'l:ACI)
26 NEXT I
28 CLOSE 11
29 X= IN 1 Ce)
1
2
3
4

6-144

313
32
34
36
413

FOR N= 1 TO 313
X=GET(13"N)
PRINT X
NEXT N
END

1 REM PROGRA.1I1 NA"1E:
T$T19A. PG
2 REM 3 UDEF INI
28 Z=DIS(I,,513,,1,,1)
29 FILE\lN 11: "DTAl: SA.."1. DAft
3 13 FO R I = 0 TO 1 6
32 PR I N T 6 1 : A -8 GOTO 200
37 REM - INCR UNDERFLO BIN 0
38 1=0
39 GOTO 300
99 REM - CLK O.F. ONLY;BMP HIST BIN
11210 1=1+1
102 IF 1<> 100 GOTO 110
103 REM - END 0 F TIHE" BMP HI ST BIN
104 X(100)=X(100)+1
11215 1=0
109 REM - BHP LATENCY CTR
lIe K=K+l
112 IF K<>T2 GOTO 25
113 REM - AN EPOCH IS DONE
114 K=0
116 J=J+l
118 IFJ=Jl GOTO 50121
119 REM - MORE EPOCHS TO GO?
12121 GOTO 25
lQQ REM - CLK O~F~ fLt>.JD SCHM!TT TR!G
200 X(I)=X(I)+l
2~H2 yeJ)=yeJ)+1
204 GOTO 10121
299 REN - SCHMITT TRIG ONLY
300 X( l)=X( l ) + 1
302 YeJ)=Y(J)+l
304 GOTO 25
498 REM - GET LARGEST BIN VALUE TO BE USED AS A
499 REM - SCALE FACTOR FOR DISPLAY
500 USE A
503 Q=12I
504 FOR 1=0 TO 100
51216 Z=X.( I)
508 IF Q>=Z GOTO 516
510 Q=Z
516 NEXT 1
'549 REM - SCALE ALL BIN VALUES FOR MAX DI SPLAY
550 vJ= IN Ion
551 FOR 1=0 TO 100

6-146

552
554
555
556
598
599
600
602
604
606
608
610
699
700
702
704
706
708
710
711
712
720
725
726
800

Z=X(I)
Y=Z/(Q+l)
'YJ=PLY(Y)
NEXT I
REM - GET LARGEST LATENCY VAL TO BE
REM - USED AS A SCALE FACTOR FOR DISPLAY
Q=0
FOR 1=0 TO 100
.Z=Y( I)
IF Q>=Z GOTO 610
Q=Z
NEXT I
REM - SCALE ALL LATENCY VALS FOR MAX DISPLAY
FOR 1=0 TO 100·
Z=Y( 1)
Y=Z/(Q+!)
l.t,T=PLY(Y)
NEXT I
REM - DISPLAY 'TIH'
V=DIS(1.,101.,l.,l)
REM - D! SPLAY LATENCY
V=DIS(102~2021111)

REN -

DISPLAY BOTH

'TIH'

& LATENCY SIDE BY SIDE

V=DIS(1~20211~1)

END

Getting on the Air with BASIC
A. DECtape users:
Transfer the user overlays, BASIC.UF, from the DECtape
provided with the software kit to the OS/8 system device.
.RPIP
*SYS:BASIC.UF

(space)

FORTRAN Constants
Constants are self-defining numeric values appearing in source
statements and are of three types: integer, real, and Hollerith.
INTEGER CONSTANTS
An integer (fixed point) constant is represented by a digit string
of from one to four decimal digits, written with an optional sign,
1 Appendix A lists the octal and decimal representations of the FORTRAN
character sel.
.

2 Of these, the characters " ! $ '% & # : ? < > t [ ] " +- may only appear
inside FORMAT statements or Hollerith constants.

and without a decimal point. An integer constant must fall within
the range -2047 to +2047. For example:
_47
+47

(+ sign is optional)

-2
0434

(leading zeros are ignored)
(zero)

REAL CONSTANTS
A real constant is represented by a' digit string, an explicit
decimal point, an optional sign, and possibly an integer exponent to denote a power of ten (7.2 X 103 is written 7.2E+03).
A real constant may consist of any number of digits but only the
leftmost eight digits appear in the compiled program. Real con- stants Inust fall within the range of ± 1.7 xl (}'38.

HOLLERITH CONSTANTS
A Hollerith constant is a string of up to 6 characters (including
blanks) enclosed in single quotes. A Hollerith constant is treated
like a real constant, except that it cannot be used in arithmetic
expressions other than for simple equivalence (A=B). Any character except the, quote character itself can be used in a Hollerith
constant. For example:
'!"101\ij ,
'A+8=C'

10'

FORTRAN Variables
A variable is a named quantity whose value may change during
execution of a program. Variables are specified by name and type.
The name of a variable _consists of one or more alphanumeric
characters the first of which -must be alphabetic. Although any
number of characters may be used to make up the variable name,
only the first five characters are interpreted as defining the name;

7-9

the rest are ignored. For example, DELTAX, DELTAY, and
DELT A all represent the same variable name.
The type of variable (integer or real) is determined by the
first letter of the variable name. A first letter of I, J, K, L, M, or
N indicates an integer varia~le, and any other first letter indicates
a real variable. Variables of either type may be either scalar or
array variables. A variable is an array variable if it first appears/in
a DIMENSION statement.
INlEGER VARIABLES
The name of an integer variable must begin with an I, J, K,
L, M, or N. An integer variable undergoes arithmetic calculations with automatic truncation of any fractional part. For example,
if the current value of K is 5 and the current value of J is 9, J/K
would yield 1 as a result.
Integer variables may be converted to real variables by the
function FLOAT (see Function Calls) or by an arithmetic statement (see Arithmetic Statements). Integer variables must fall within
the range -2047 to +2047.
Integer arithmetic operations do not check for overflow. For
example, the sum 2047+2047 will yield a result of -2. For more
information refer to Chapter 1 of Introduction to Programming or
any text on binary arithmetic.
RhAL VARIABLES
A real variable name begins with any alphabetic character other
than I, J, K, L, M, or N. Real variables may be converted to integer
variables by the function IFIX '(see Function Calls) or by an
arithmetic statement. Real variables undergo no truncation in
arithmetic calculations.
SCALAR VARIABLES
A scalar variable may be either integer or real' and represents a
single quantity. For example:
U·1
A

G2
TOTAL
J

7-10

ARMY VARIABLES
An array (subscripted) variable represents a single element of a
one- or two-dimensional array of quantities. 'The array element is.
denoted by the array name followed by a subscript list enclosed in
parentheses .. The subscript list may be any integer expression or .
two integer expressions separated by a comma. The expressions
may be arithmetic combinations of integer variables and integer
constants. Each expression represents -a subscript, and the values
of the expressions determine the referenced array element. For
example, the row vector Ai would be represented by the subscripted
variable A (I), and the element in the second column of the first row
of the matrix A, would be represented byA (1, 2).
Examples of one-dimensional arrays are:.
YC 1 )

PORTCK)

while a two-dimensional array appears as follows:
A C3* K+2, 1 )

Any array must appear in-a DIMENSION statement prior to its
first appearance in an executable statement. The' DIMENSION
statement specifies the number of elements in the array.
Arrays are stored in increasing storage locations with the first
. subscript varying most rapidly (see Storage Allocation). The twodimensional array B (J, K) is stored in the following order:
B(1, 1), B(2, 1), ... , B(J, 1), B(1, 2), B(2, 2), ... , B(J, 2),
... , B(~, K)

For representatiolI of arrays of more than two dimensions, refer
to the section entitled Representation of N-Dimensional Arrays
toward the end of this chapter.
SUBSCRIPTING
Since excessive subscripting tends to use core memory inefficiently, it is suggested that subscripted variables be used judiciously. For example, the statement:
7-11

could be rewritten \\jth a considerable saving of core memory as
follows:
T=B(I)
A=«T+C2)*T+Cl)*T

Expressi9DS
An expression is a sequence of constants, variables, and function
references separated by arithmetic operators and parentheses in
accordance with mathematical convention and the rules given
below ..
Without parentheses, algebraic operations are performed in the
following descending order:
**
* and /
+ and -

exponentiation
unary negation
multiplication and division
addition and subtraction
equals or replacement sign

Parentheses are used to change the order of precedence. An
operation enclosed in parentheses is performed before its result is
used in other operations. In the case of operations of equal priority , the calculations are performed from left to right.
Integers and real numbers may be raised to either integer or real
powers. An expression of the form:
A**B
means AB and is real unless both A and B are integers. Exponential
(ex) and natural logarithmic (logp(x)) functions are supplied as
subprograms and are explained later.
Excluding ** (exponentiation), no two arithmetic operators may
appear in sequence unless the second is a unary plus or minus.
The mode (or type) of an expression may be either integer or
real and is determined by its constituents. Variable modes may not
be mixed in an expression with the following exceptions:
1. A real variable may be raised to an integer power:
7-12

2. Mode may be altered by using the functions IFIX and
FLOAT (see Function Calls):
A*FLOA T< I)

The I in example 2 above, indicates an integer variable; it is
changed to real (in floating point format) by the FLOAT function.
Zero raised to a power of zero yields a result of 1. Zero raised
to any other power yields a zero result. Numbers are raised to
integer powers by repetitive multiplication. Numbers are raised t~
floating point powers by calling the EXP and ALOG functions.
A negative number raised to a floating point power does not cause
.an error message but uses the absolute value. Thus, the expression
(-3.0)**3.0 yields a result of +27.
Any arithmetic expression may be enclosed in parentheses .and be
considered a basic element.
IFIX(X+Y)/2
(ZETA)
(COS(SIN(PI*EM)+X))

An arithmetic expression may consist of a single element (constant, variable, or function call). For example:
2.71828
Z C N)
TANC TeiETA)

Compound arithmetic expressions may be formed using arith-metic operators to combine basic elements. For example:
'-

;( +3 •

TOTAL/A
TANCPI*EillJ)

•

Expressions preceded by a
expressions. For example:

or a - sign are also arithmetic

- (ALPHA* BE TA)
-SQRT< -GAIV1IV1A)

7-13'

As an example of a typical arithmetic expression using arithmetic
operators and a function: call, the expression for the largest root of
the ge.p.eral quadratic equation:

is coded as:

FORTRAN STATEMENTS
A FORTRAN source program consists of a series of statements,
each of which must start on a separate line. Any FORTRAN
statement may appear in the statement field (columns 7 through 72)
and may be preceded by a positive number, called a statement
number, of from 1 to 4 digits which serves as an address label and
is used when referencing the statement. When used, statement numbers are coded in columns 1 through 5 of the 72 column line. Statement numbers need not appear in sequential order, but no two statements should have the same number. Statement numbers are limited
to a value of 2047 or less.
\Vhen using the Symbofic Editor to create the source program,
hrninrr <.:> rTOT IT A"R (O'""",o"a+orl hV h"lrl:_~ rl~ ... _ "h~ """""RT l-e~'
~Jt'Aub .... "-' ......... L.J/ ... I'i..uo \b'"'u,",J.
",",U u J UVIU111t; UVIIVU uu;; \...-1.
L ..... Y
and depressing TAB) causes a jump over the statement number
columns and into the statement field. Except for data within a
Hollerith field (see Input/Output Statements), spaces are ignored
by the compiler. The programmer may use spaces freely, however,
to make the program listing more readable and to organize data
into columns.
Line Continuation Designator
Statements too long for the statement field of a single terminal
line may be continued on the next line. The continued portion must
not be given a line number, but must have an alphanumeric character other than 0 in column 6. If the Symbolic Editor is used, the programmer may type a CTRL/TAB followed by a digit from 1 to 9
before continuing the line. The continuation character is not treated
as part of the statement.

7-14

For example, using spaces, a continued statement would look as
follows:
WR ITE (3 .. 30 )
30

FORMAT (lX .. 'THE FOLLC~ING DATA IS GROUPED INTO THREE
1 PARTS UKDER THE HEADINGS X, Y, AND Z.')

Using tabs, the same statement would be typed:
\VR ITE <3 .. 30 )
30

ETA,PI

.WRITE Statement
The WRITE statement specifies transfer of information from
the computer to a specified output device. The WRITE statement
assumes one of the following forms:
WRITE (d, f) list
WRITE (d, f)
where d is a device designation (integer constant or integer variable), f is a FORMAT statement line number, and list is a list of
variables to be output.
The WRITE statement followed by a list causes the values of the
variables in the list to be read from memory and written on
the designated device in ASCII form. The data is converted to external form as specified by the designated FORMAT statement.
The WRITE statement without a list causes information (generally Hollerith type) to be read directly from the specified format
and written on the designated device in ASCII form.
The I/O device designations used in the READ and WRITE
statements are described in Table 7-2.
Table 7-2

Device Code
1
2
3
44

Device Designations

Input Designation

Output Designation

. Teletype keyboard or Teleprinter
low-speed reader
High-speed reader
High-speed punch
Card reader (CRg/I) Line printer (LP08)
Assignable device
Assignable device
(see Device Independent I/O and Chaining)

Device code 3 is assigned to the card reader (for all READ
statements), and the line printer (for all WRITE statements~. The
card reader uses a two-page device handler, wh~ch is too large to
4 If using device code 4, the / I or /0 options to the Linking Loader
must be given. If the assignable device is a two-page handler, the IH option must be given also.

7-20

be used with the device independent I/O feature (device code 4) ..
Therefore, the card reader has its own device code.
'
The line printer is a separate output device because it can require
special formatting, such as inserting a Form Feed to skip to the
top of a page. The contents of the first column of any line is a· control character. These control characters are never prillted. They
are as follows:
Character in Column 1

Resulting Spacing
single space
double space
skip to top of
next page (Form
Feed)
single space

space

o
1

all others

FORMAT STATEMENT
The nonexecutable FORMAT statement specifies the form and
arrangement of data on the selected external device. FORMAT
statements are of the form:

where m is a statement number and each S is a data field specification. Both numeric and alphanumeric field specificati6ns may appear in a FORMAT statement. The FORMAT statement also
provides for handling multiple record formats, skipping characters,
space insertion, and repetition. .
FORMAT statements may be placed anywhere in the source
program. Unless the FORMAT statement contains only alphanu~eric data for direct I/O transmission, it will be used in conjunction with the list of a data transmission statement.
During transmission of data, the object program scans the desig.:
nated FORMAT statement; if a specification for a numeric field
is present, and the data transmission statement contains items remaining to be transmitted, transmission takes place according to the
specification. This process ceases and execution of the data transmission statement is terminat~d as· soon as all specified items have
been transmitted. Th~ FORMAT statement may contain specifications for more items than are indicated by the data transmission
7-21

statement. The FORMAT statement may also contain specifications for fewer items than are indicated by the data transmission
statement, in which case, format control reverts to the rightmost
left parenthesis in the FORMAT statement. If an input list requires more characters than the input device supplies for a given
record, blanks are inserted.

Numeric Fields

Numeric field specification codes and the corresponding internal and external forms of the numbers are listed in Table 7-3.
Table 7-3

Conversion
Code
E

F
I

Numeric Field Codes

Internal Form

External Form

Binary floating point Decimal floating point 5
with E exponents:
0.324E+10Binary floating point Decimal floating point
with no exponent: 283.75
Decimal integer: 79
Binary integer

Conversions are specified by the form:
rEw.d
rFw.d
rIw
where r is a repetition count, E, F, and I designate the conversion
code, w is an integer specifying the field width, and d is an integer
specifying the number of decimal places to the right of the decimal
point. For E and F input, the position of the decimal point in the
external field takes precedence over the value of d. For example:

5 When using E format, or with numbers less than 1.0 when using F format
in a WRITE statement, a zero will be typed to the left of the decimal point.

7-22

could be used to output the line
32

-17.60

0.59624575E+03

on the output listing.
The field width should always be large enough to include the
decimal point, sign, and exponent (plus a leading zero in OS/8
FORTRAN). In all numeric field conversions, if the field width
is not large enough to accommodate the converted number,asterisks willbe printed; the number is always right-justified in the field.
Numeric Input Conversion

In general, numeric input conversion is compatible with most
other ~ORTRAN processors. A few exceptions are listed below:
1. Blanks are ignored except to determine in which field digits
fall. Thus, numbers are treated as if they are right-justified
within a field. In ~n F52 format, the following:
bbb12
12bbb
00012
are read as the number 0.12 (where 'b' represents a blank
space).
2. A null -line delimited by two carriage return/line feed
(CR/LF) combinations is treated as a line of blanks, and
blanks are appended to the right of a line (if necessary) to
fill out a FORMAT statement. Thus:
12 (CR/LF)
12bbb
bbb12
are identical under an F5.2 format. If an entire line is blank,
numeric data from that line is read as zeros.
7-23

3. No distinction
Thus:

made between E and F format on input.
100.
100E2
1.E2
10000

are all read identically under either an F5.2 or E5.2 format.
Alphanumeric Fields
Alphanumeric data can be transmitted in a manner similar to
numeric data by use of the form

rAw
where r is a repetition count, A is the control character, and w is
the number of characters in the field. Alphanumeric characters are
transmitted as the value of a variable in an I/O list; the variable
may be either integer or real.
Although w may have any value, the number of characters transmitted is limited by the maximum number of characters which can
be stored in the space allotted for the variable. This maximum
depends upon the variable type; for a real variable the maximum

--i", ';:lY
----

rh::lr::lrtpr..:

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

for ::In lntpopr v::Irl::1hlp. thp. m::lximnm j.;: two·
----- -----0-- .------- ---- -------------- -- -.. -

characters. The characters are stored in stripped ASCII format. If
not enough data is supplied as input to the variables, the data is
padded with blanks on the right. For example:

READ (1,20) MI,M2.M3.M4.M5.M6,M7,Mg
FORMAT (8AI)

if the user types at this point:
123ABC

followed by a carriage return, the following are the values of the
variables:
7-24

Variable

Decimal

M1
M2
M3
M4

-928
-864

M6
M7

Octal

- 6140
6240
6340
0140
0240
0340
4040
4040.

~800

96
160
224
-2016
-2016

If the above had been re.ad in 4A2
follows:
Variable

M1
M2
M3
M4

. ASCII

Decimal

format~

1
2
3
A
B
C
blank
. blank

the values would be as

Octal

ASCII

-910
-831
131
-2016

6162
6301
0203
4040

1 2
3 A
BC
blanks

-2016

·.4040

....................
M8

As a second example: .
20

READ (1,20)
FORMAT (A6)

ALP~A

the user types:123AB

and a carriage return, and the octal value of ALPHA is:
6162

6301

0240

NOTE
The numeric value of alphanumeric
characters stored in floating point
variables is generally not meaningful.
7-25

blanks

Hollerith Conversion

Alphanumeric data may be transmitted directly from the FORMAT statement by using Hollerith (H) conversion. H-conversion
format is normally referenced by WRITE statements only.
In H -conversion, the alphanumeric string is specified by the form

where H is the control character and n is the number of characters
in the string, including blanks.· For example, the statement below
can be used to print PROGRAM COMPLETE on the output list-~·
mg.
FORMAT(17H PROGRAM COMPLETE)

A Hollerith string may consist of any characters capable of
representation in the processor. The space character is a valid and
significant character in a Hollerith string;
An attempt to use H format specifications with a READ statement will cause characters from the format field to be either printed
or punched. This can be a useful feature since it provides a simple
way of identifying data that is to be read from the Teletype keyboard. For example, the following instructions:

READ (1,30)A,B
FORMAT (4HA = ,F7.8/4HB

,F7.8)

cause A = and B = to be printed out before the data is read.
By merely enclosing the alphanumeric data in single quotes, the
same result is achieved as in H-conversion; on input, the characters
between the single quotes are typed as output characters, and on
output, the characters between the single quotes (including blanks)
are written as part of the output data. For example, when referred
to from a WRITE statement:
50

FORMAT (' PROGRAM COMPLETE')

7-26

causes PROGRAM COMPLETE to be printed. This· method
eliminates the need to count characters.
Blank or Skip Fields

Blanks can be introduced into· an output record or characters .
skipped on an input record by use of the nX specification. The. '.
number n indicates the number of blanks or characters skipped and
, must be greater than zero. For example:
FORMATC5H STEPI5,10X2HY=F7.3)

can be used to output the line:
STEP

Y=3.872

Mixed Fields

A Holle:r:ith format field may be placed among other fields -of
the format. The·statement:
FORMATCI5,7H FORCE=F10.5)

can be used to output the line:
22 FORCE=

17.68901

The separating comma may be omitted after a Hollerith format
field, as shown above.
Repetition oj Fields

Repetition of a field specification may be specified by preceding
the control character E, F, or I by an unsigned integer giving the
number of repetitions desired~
FORMATC2E12.4,315)

is equivalent to:

7-27

Repetition 0/ Groups
A group of field specifications may be repeated by enclosing the
group in parentheses and preceding the whole with the repetition
number." For example:

is equivalent to: .

Multiple Record Formats
To handle a group of output records where different records
have different field specifications, a slash is used to indicate a new
record. For example, the statement:
FORMAT(318/15,2F8.4)

is equivalent to:
FORMAT(318)

for the first record and
FORMAT(I5,2F8.4)

for the second record.
The separating comma may be omitted when a slash is used.
When n slashes appear at the end or beginning of a format, n blank
records may be written on output (producing a CR/LF for each
record) or ignored on input. When n slashes appear in the middle
of a format, n-l blank records are written or n-l records skipped.
Both the slash and the closing parenthesis at the end of the format
indicate the termination of a record. If the list of an I/O statement dictates that transmission of data is to continue after the
closing parenthesis of the format is reached, the format is repeated
7-28

from the last open parenthesis of level one or zero. Thus, the
statement:

causes the format:

to be used on the first record, and the format:

to be used on succeeding records.
As a further example, consider the statement:
FORVATCF7.2/C2CElS.S.,ElS.L!).,17»

The first record has the format:
F7.2

and successive records have the format:

Control Statements
The control statements GO TO, IF, DO, .PAUSE, STOP, and
END alter the sequence of statement execution, temporarily or
permanently halt program execution; and stop compilation.
GO TO STATEMENT
. The GO TO statement has two forms: unconditional and computed.
Unconditional GO TO
Unconditional GO TO statements are of the form:
GOTOn
7-29

where n is the number of an executable statement. Control is transferred to the statement numbered n.

Computed GO TO
Computed GO TO statements have the form:
GO TO (nl, n2, . . . , nk), J
where nb n2,' ., nk are statement numbers and J is a nonsubscripted integer variable. This statement transfers control to the
statement numbered nb n2 ... , nk if J has the value 1, 2, ... , k,
respectively. The index (J in the above example) of a computed
GO TO statement fil:ust never be zero or greater than the number
of statement numbers in the list (in the example above, not greater
than k). For example, in the statement:

the variable K acts as a switch, causing a transfer to statement 20
if K = 1, to statement 10 if K = 2, or to statement 5 if K = 3.
IF STATEMENT
Numerical IF statements are of the form:
IF (expression) nb n2, n3
where nl, n2, n3 are statement numbers. This statement transfers
,.nntrnl
tn
thp
ct'3tpm"'nt "U .l.J..i.V'\..I
...... h"'f"',-l...
...
....
,,-,.a.
'"'.....,
................. u ... IL4\. ....
,""U .1..1.1,
.1.i~,
11:~
_

....... .&. .........

.I..l,\o,.IJ..

...

,l..j..

~~ 4-1...0
.. , ... l
""
tIl,""
vaJ. U "'"

ro.~ 4-1...0
1.~1\..1

V.1

numeric expression is less than, equal to, or greater than zero,
respectively. The expression may be a simple variable or any
arithmetic expression.
IF CETtU4 . . 7 ..12
IFCKAPPA-L(10))20 . . 14 ... 14

DO STATEMENT
The DO statement simplifies the coding of iterative procedures.
DO statements are of the form:

where n is a statement number, i is a scalar integer variable, and
mb ml, m3 are integer constants or :t:lonsubscripted integer variables. If m3 is not specified, it is understood to be 1.
.

7-30

The DO statement causes the statements which follow, up to
and including the statement numbered n, to be executed repeatedly.
This group of statements is called the range of the DO statement.
In the example above, the integer variable i is called the index, the
values of ml, m2, ms are, respectively, the initial, terminal, and increment values of the index.
For .example:
DO 10 J=l .. N
DO 20 I=J .. K .. 5
DO 30 L=I .. J .. K

The index is incremented and tested before the range of the DO is
executed. After the last execution of the range, control passes to
the statem~nt immediately following the terminal statement in what
is called a normal exit. An exit may also occur by a transfer out
of the range taking place before the loop has been executed the
total number of times specified in the DO statement.
DO loops may be nested, or contained within one another, provided the range of each contained loop is entirely within the range
of the containing DO statement. Nested DO loops may contain the
same terminal statement, however. A transfer into a DO loop from
outside the range is not allowed.
Within the range of a DO statement, ,the index is available for
use as an ordinary variable. After a transfer from within the range,
the index retains its current value and is available for use as a
variable. 6 The values of the initial, terminal, and increment vari- .
abIes for the index and the index of the DO loop may not be
altered within the range of the DO' statement.
After a normal exit from a DO loop, the index of the DO statement has
the value of the index the final time through the loop plus whatever increment was assigned. For example:
6

DO 10 I=1,5

after a normal exit the 'value of the index is 6. However, it is good programming practice to avoid using the index as a variable following a normal exit
until it has been redefined, as according to ANSI FORTRAN Standards the
value is undefined.

7-31

The last statement of a DO loop must be executable, and must
not be an IF, GO TO or DO statement.
CONTINUE STATEMENT
This is a dummy statement, used primarily as a target for transfers, particularly as the last .statement in the range of a DO statement. For example, in the sequence:
DO 7

K=INIT~LIMIT

CONTINUE

a positive value of X(K) begins another execution of the range.
The CONTINUE provides a target address for the IF statement
and ends the range of the DO statement.
PAUSE, STOP, AND END STATEMENTS
The PAUSE and STOP statements affect FORTRAN object pro-··
gram operation; the END statement affects assembler operation
only.
Pause Statement
The PAUSE statement enables the program to incorporate operator activity into the sequence of automatic events. The PAUSE
statement assumes one of two forms:
or

PAUSE
PAUSE n

where n is an unsigned decimal number.
Execution of the PAUSE statement causes the octal equivalent
of the decimal number n to be displayed in the accumulator on the
user's console. Program execution may be resumed (at the next
executable statement) by depressing the CONTinue key on the
console.
In some cases the PAUSE statement may be used to give the
operator a chance to change data tapes or to remove a tape from
the punch. When this is done it is necessary to follow the PAUSE
7-32

statement with a call to the OPEN subroutine. This subroutine
initializes the I/O devices and sets hardware flags tha,t may have
been cleared by pressing the tape feed button. For example:
PAUSE,
CALL OPEN

NOTE
The CALL OPEN statement in OS/8 FORTRAN also resets all I/O on unit 4, the assignable channel. Any further READs or
WRITEs on unit 4 without an intervening
IOPEN or OOPEN will print an errormes- .
sage and abort.
Stop Statement

The STOP statement has the form:
STOP
It terminates program execution. STOP may occur several times

within a single program to indicate alternate points at which execution may cease. Program control is either directed. to a STOP
statement or transferred around it.
End Statement

The END statement is of the form:
END

and signals the compiler to terminate .compilation. The END statement must be the last statement of every program .. (In OS/8
FORTRAN, the END statement generates a STOP statement as
well.)

Specification Statements .
Specification statements allocate storage and furnish information
about variables and constants to the compiler. The specification
statements are COMMON, DIMENSION, and EQUIVALENCE
and, when used, must appear in the program prior to any executable statement.
7-33

C01vIMON STATE1vIE~l
The COMMON statement causes specified variables or arrays to
be stored in an area available to other programs. By means of
COMMON statements, the data of a main program and/or the
data of its subprograms may share a common storage area. Vari.. bles in COMMON. statements are assigned to locations in ascending order in field 1 beginning at location 20n storage alIocation .
. The COMMON statement has the genera! form:
rrYl\AMON
'(,.I, ".
"-" '-' YO.l."
Y:!, • • • , "
,.
~

J..

where v is a variable name. See the section entitled Common Storage Allocation for greater detail.
DIMENSION STATEMENT
The DIMENSION statement is used to declare array identifiers
and to specify the number and bounds of the array subscripts. The
information supplied in a DIMENSION statement is required for
the allocation of memory for arrays. Any number of arrays may be
declared in a single DIMENSION statement. The DIMENSION
statement has the form:
, DIMENSION Sl, S2,

••• , Sn

where s is an array specification. For example:
DIMENSION A( 100)
DIMENSION Y(10)~PORT(25)~B(10~10),J(32)

D l1T1 pn '11'on st!1te1Tlpnt~ !11"P used for the .t'nU!rnn~e
r-a.r of re<:ervm'00
sufficient storage space for anticipated data; it is the user's responsibility to see that his subscripting does not conflict with the
DHv,fENSION statement declarations. For example:
~- ....... y

"'"'

DIME~SIO~

.... "'"

,A...L.L ............. ...,

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

..L

.a.

........

.a.

....

.-.

I(10),Je10',K(10)

1(2,4)=2
JCl2 )=3

The above statements would assemble without error; at run time
I ( 8) would be set equal to 2 and K (2) would be set equal to 3.
NOTE
When variables in common storage are
dimensioned, the COMMON statement must
appear before the DIMENSION statement.
7-34

EQUIVALENCE STATEMENT
The EQUIVALENCE statement causes more-than one variable
within a given program to share the same storage location. This is
useful when the programmer desires to conserve storage space. The
form of the statement is:
EQUIVALENCE

(Vh V2 .•. ) , ...

where v represents a variable name. The inclusion of two or more
variables within the parenthetical list indicates that these variables
are to share the same memory location .and· thus have the same.
value. For example:
.EQUIVALENCECRED,BLUE)

The variables RED and BLUE are' now of equal value. The subscripts of array variables" must be integer constants. ror example:
EQUIVALENCE(X,A(3),YC~,1»,CBETA(2,2),AL~HA)

Because of core memory restrictions within the c<;>mpiler, variables cannot appear in EQUIVALENCE statements ~ore than
once.
EQUIVALENCECA,B,C)

is valid,but the statement:
EQUIVALENCE(A,B),(B,C)

would not compile correctly.
Variables may not appear in both EQUIVALENCE and COMMON statements.
'Subprogram Statements
External. subprograms are defined separately from the programs
that call them, and ar~ complete programs which conform to all
the rules of FORTRAN programs. They are compiled as closed
subroutines; that is, they appear only once in core memory regardless of the number or times they are used. Extern'll subprograms
'. ~re defined by means of the statements FUNCTION and SUBROUTINE. Functions and subroutines must be compiled indepen~
dently'ofthe main program and then lo.aded together with the main
program by the Li~king Loader.
7-35

NOTE
Care should be exercised when naming a
subprogram or subroutine. It must not have
the same name as any of the FORTRAN
library functions or subroutines, or assembler
mnemonics or pseudo-ops, as errors are likely
to result. The Library Functions are listed in
this chapter, and the symbol table for the
~ABR
ASS""
..... hl"".. ~s
11"ste'
rI~J.J.J.
... A "'pe...
r1~'V r\J
J.
\"J.J..lUJ.\"J.
J.
J.
U
HULA
,-,.
~p

Subprogram definition statements may optionally contain dummy
arguments representing the arguments of the subprogram. They
are used as ordinary identifiers within the subprogram and are
replaced by the actual arguments when the subprogram is executed.
FUNCTION SUBPROGRAMS
A function subprogram is a subprogram which is called from
an arithmetic expression within the main program and returns a
single numeric value. A function subprogram begins with a FUNCTION statement and ends with an END statement. It returns control to the calling program by means of one or m9re RETURN
statements. The FUNCTION statement has the form:

where FUNCTION (or FUNC) declares that the program which
follows is a function subprogram, and identifier is the name of the
function being defined. The identifier must appear as a scalar variable and be assigned a value during execution of the subprogram.
This value is the function's value.
Arguments appearing in the list enclosed in parentheses are
dummy arguments representing the function arguments. A function
must have at least one dummy argument. The arguments must
agree in number, order and type with the actual arguments used in
the calling program. Function subprograms may be called with expressions and array names as arguments. The corresponding dummy
arguments in the FUNCTION statement would then be scalar and
array identifiers, respectively. Those representing array names must
appear within the subprogram in a DIMENSION statement. Dimensions' must be indicated as constants and should be smaller
7-36

than or equal to the dimensions of the corresponding arrays in the
calling program. Dummy arguments to FUNCTION cannot appear
in COMMON or EQUNALENCE statements within the function subprogram.
A function should not modify any arguments which appear jn .
the FORTRAN arithmetic expression calling the function. The
only FORTRAN statements not allowed in a function subprog(am
are SUBROUTINE and other FUNCTION statements.
The type of function is determined by the first letter of the identifier used to name the function, in the same way as variable names.
The following short example calculates the gross salary of an
individual on the basis of the number of hours he has worked
(TIME) and his hourly wage (RATE). The function calculates
time and a half for overtime beyond 40 hours. The function name
is SUM.

10
20

FUNCTION SUM(TIME~RATE)
IF (TIME-40.)·10~10~20
SUM = TIME * RATE
RETURN
SUM = C40.*RATE) + (TIME-40-~H1.5*RAtE
RETURN
END

Depending upon which path the program takes, control will return to the main program at one ot" the two RETURN statements
with the answer. Assume that the main program is set up with a
statement to read the employee's weekly record from a list of
imormation prepared. on the high-speed reader:
READ(2~5)

NAME~

NUM~

NDEP~

TIME~

RATE

This statement reads the person's name, number, department number, time worked, and hourly wage. The main program then calculates his gross pay with a statement such as the following;
GROSS =

SUM(TIME~RATE)

and goes on to calculate withholdings, etc.
SUBROUTINE· SUBPROGRAMS
A subroutine subprogram is a subprogram which is called by
the main program via a CALL statement, and may return several
7-37

or no values. The subprogram begins with a SUBROUTINE statement and returns control to the calling program by means of one
or more RETURN statements. The SUBROUTINE statement has
the form:
SUBROUTINE identifier (a1, a2 ...

a,J

where SUBROUTINE declares the program which follows to be a
subroutine subprogram and the identifier is the subroutine name.
The arguments in the list enclosed in parentheses are dummy arguments representing the arguments of the subprogram. The dummy
arguments must agree in number, order, and type with the actual
arguments, if any, used by the calling program.
Subroutine subprograms may have expressions and array names
as arguments. The dummy arguments may appear as scalar or array
identifiers. Dummy identifiers which represent array names must
be dimensioned within the subprogram by a DIMENSION statement. The dummy arguments must not "appear in an EQUIVALENCE or COMMON statement in the subroutine subprogram.
A subroutIne subprogram may use one or more of its dummy
identifiers to represent results. The subprogram name is not used
for the return of results. A subroutine ..subprogram need not have
any arguments, or may use the arguments to return numbers to the
calling program. Subroutines are generally used when the result of
a subprogram is not a single value.
Exampl~ SUBROUTINE statements'are as follows:

SUBROUTINE FACTO (COEFF,N,ROOTS)
SUBROUTINE RESID (NUi"1,N,I)EN,'V!,R~S)
SUBROUTINE SERlE

The only FORTRAN statements not allowed in a subroutine subprogram are FUNCTION and other SUBROUTINE statements.
The following short subroutine takes two integer numbers from
the main program and exchanges their values. If this is to be done
at several points in the main program, it is a procedure best performed by a subroutine.
7-38

SUBROUTINE ICHGE (I,J)
ITEM=I
I=J
J=ITEM
RETURN
END

The calling statement for this subroutine might look as follows:
CALL ICHGE (M,N)

where the values for the variables M and N are to be exchanged.

CALL Statement
The CALL statement assumes one of two forms:

CALL identifier
CALL identifier (a1 , a2 ... , an)

The CALL statement is· used to transfer control to a subroutine
subprogram. The identifier is the subroutine name.
The arguments (indicated by a1, through an) may be expressions or array identifiers. Arguments may be of any type, but must
agree in number, order, type, and array size with the corresponding
arguments in the SUBROUTINE statement of the called subroutine. Unlike a function, a subroutine may produce more than one
value and cannot be referred to as a basic element in an expression.
A subroutine may use one or more of its arguments to return
results to the calling-program. If no arguments at all are required,
the first form is used. For example:
CALL EXIT
CALL TEST 2047; 2047 is returned.

7-56

point

In addition, the error message:
USER ERROR 1 AT XXXX
"

means that the user tried to reference an entry point of a program
which was not loaded, or possibly that he failed to define a subscripted variable in a DIMENSION statement. XXXX has no
meaning.
To pinpoint the location of a library program execution error:
1. Determine, from the storage map, the next lowest numbered
location (external symbol) which is the entry point of the·
program or subprogram containing the error.
2. Subtract, in octal, the entry point location of the program
, or subprogram containing the error from the location of the
error indicated in the error message.
3. From the assembly symbol table, determine the relative
address of the external symbol found in step 1 and add that
relative address to the result of step 2.
4. The sum of step 3 is the relative address of the error, which
can then be compared with the relative addresses of the
numbered statements in the program.
Undefined statem~nt numbers are not detected until the assembly
phase, at which time a U error message is given. (Refer to the list
of SABR error messages.) ,-

7-57

7-58

8~ortranlV
FORTRAN IV SYSTEM OVERVIEW
OS/8 FORTRAN IV provides full standard ANSI FORTRAN
IV under the OS/8 operating system. The FORTRAN IV package _
requires a minimum hardware environment consisting of a 'PDP-8.
family processor :with at least 8K of mainframe memory , a console
terminal, and at least 96K -of -mass storage: The- system is automatically self-expanding to employ a KE8-E Extended _Arithmetic
Element, FPP-12 Floating Point Processor, up to 32K of mainframe memory, and any bulk storage or peripheral I/O devices
that may be present in the system.
Although such factors as maximum program size and minimum
execution time depend heavily on the hardware configuration on
which any program is run, OS/8 FORTRAN IV affords the full
capability of the FORTRAN IV language, even on a minimum
configuration, subject orily to the restriction -that double precision
and complex number operations require an FPP-12 with extended
precision option. The system is highly optimized with respect to
memory requirements, and an overlay feature is induded that can
permit prograrris requiring up to 300K of virtual storage to run on a
PDP-8 or PDP-12. The library functions permit the user to access
a number of laboratory ,peripherals, t~ evaluate a number of
transcendental functions, to'manipulate alphanumeric strings, and
to output to a standard incremental plotter.A FORTRAN IV program written by the user is called a source
program, to distinguish it from the various object programs
generated by the OS/8 FORTRAN IV system. Source programs·
may be prepared off line on punched cards or low-speed paper
tape; however, it is usually most convenient to prepare source
programs on line by means of an editing program such as TEeO or
EDIT. (See Figure' 8-1.) The source file produced in this manner
is an image of the corresponding punched-card file, with carriage

8-1

return and Hne feed characters separating adjacent statements (that
would otherwise appear on adjacent punched cards) and ASCII
spaces or tabs entered in place of blank columns. Because of the
close analogy between punched card source files and other types
of source files, the terms "character" and "column" are used
interchangeably in this manual.

EDITOR

INPUT AT TTY

EDiTOR

Figure 8-1

Preparing a FORTRAN IV Source File

Once a source program has been prepared, it is supplied as input
to the FORTRAN IV compiler, which translates each FORTRAN
statement into one or more RALF (Relocatable Assembly
Language, Floating-point) statements and produces an output file
containing an assembly language version of the source program,
plus an optional annotated listing of the source. (See Figure 8-2.)
8-2

This is accomplished in three passes. System program F4.SV
begins compilation by building a symbol table and generating
intermediate code. F4 chains to PASS2.SV automatically, and
PASS2 calls PASS20.SV to complete the translation into assembly
language during compilation pass 2. If a source listing was requested, PASS20 chains to P ASS3 .SV automatically, and PASS3
generates the listing during pass 3. Like PASS2, PASS20 and
PASS3 are never accessed directly by the user.

PREPARATION
OF PROGRAM

COMPILATION

Figure 8·2

Compiling a Source File

The RALF assembly language output produced by the compiler
must be assembled by system program RALF.SV, the RALF
assembler. (See Chapter 5 for a description of the RALF assembler.) During assembly, ~ach RALF assembly language statement
is translated into one or more instructions for either the PDP-8
processor or the FPP and an output file is created containing a
8-3

relocatable binary version of the assembly language input. This is
accomplished in two passes; a third pass is executed to generate an
annotated listing of the assembly language input file, if requested.
The relocatable binary file produced by the RALF assembler is
a machine language version of a single program or subroutine. This
file, called a RALF module, must be linked with its main program
(if it is a subroutine) and with any other subroutines, inc:uding
subroutines from the system library (e.g., FORLIB.RL) that it
requires in order to execute. System program LOAD.SY, the OS/8
FORTRAN IV loader, accepts a list of RALF module specifications from the console terminal and builds a loader image file
containing a relocated main program linked to relocated versions
of all subroutines and library components' that the mainline requires in order to execute. (See Figure 8-3.)
The loader image file is an executable core load, .complete
except for run-time I/O specifications. It may be stored on any
mass storage (directory) device and executed whenever desired.
The loader also proquces an optional symbol map that indicates
the core storage requirements of the linked and relocated program.
The overlay feature of the loader permits certain segments of a
program to be stored in the loader image file during execution and
read into core memory only as needed, which effectively provides
a tenfold increase in maximum program size.
Thp
ImH1pr
.. ~

~~~--~

lTn!:l(]P

.... ~.::>-

flIp nronn{,pn hv thp
lo::lnf'.r
j" rf'::In ::Inn
. . ------'-------'
~---

r~~-----

~.l

executed by system program FRTS.SV, the OS/8 FORTRAN IV
run-time system, which also configures an 110 supervisor to handle
any FORTRAN input or output in accordance with run-time I/O
specifications. This makes the full I/O device independence of the
OS/8 operating system available to every FORTRAN IV program,
and permits FORTRAN programs to be written without concern
for, or even knowledge of, the hardware configuration on which
they will be executed. The run-time system assigns I/Q device
handlers to the I/O unit numbers referenced by the FORTRAN
program, allocates I/O buffer space, and also diagnoses certain
types of errors that occur when the loader image file is read into
core. If no errors of this sort ar.e encountered, the run-time system
starts the FORTRAN program and monitors execution to check
for run-time errors involving data I/O, numeric overflow, hardware malfunctions, and the like. Run-time errors are identified at
the console terminal, and, when a run-time error occurs, the
8-4

system also provides complete error traceback to identify the full
sequence of FORTRAN statements that terminated in the error
condition.

RALF
ASSEMBLY

ASSEMBLY

DYMBOl

Figure 8-3

Assembling, Loading,

an~

MAP

Executing a RALF File

The compiler, assembler, loader, and run-time system each
accept standard OSj8 Command Decoder option specifications,
as do most OSj8 programs. The option specifications are alphanumeric characters which may be thought of as switches that, by
their presence or absence, enable or disable certain program
8-5

features and conventions. For example, specifying the N option
to the compiler suppresses compilation of internal sequence numbers, thereby reducing program memory requirements (at the cost
of preventing full error traceback during execution). Thus, N is
one of the compiler run-time option specifications which may be
requested to modify the usual compilation procedure. In this context, run-time refers to the time at which the compiler, or other
system program is executed, rather than the time at which the
FORTRAN program is executed.
A FORTRAN source program may be executed by calling the
compiler to convert the source into RALF assembly language, then
calling the assembler to produce a relocatable binary file, calling
the loader to link and relocate the bil1:ary file, and finally calling the
run-time system to load the program and supervise execution.
OS/8 FORTRAN IV provides a program chaining feature that
can simplify or eliminate this sequence of program calls in most
cases. When chaining is requested, the first system program to be
executed automatically calls the next program in the compiler /
assembler/loader/run-time system sequence. When the compiler
chains to the assembler, for example, the five programs (the compiler consists of four programs) function as a single unit that
accepts FORTRAN source language input and generates relocatable binary output, suitable for use as input to the loader. In this
manner, simple FORTRAN programs may be compiled, assembled, relocated, loaded, and executed, all as the result of a single
Keyboard Monitor or CCL command. More complicated programs
involving subroutines and, perhaps, overlays, do not admit to a
high degree of chaining because a great deal of user input in the
form of run-time option specifications may be required at some
point in the chain. In general, however, it is usually most Convenient to chain from the compiler to the assembler (combining
compilation and assembly into a singl~ operation) and from, the
loader to the run-time system (combining relocation, loading, and
execution).
Errors encountered by the various system programs do not
result in termination of program chaining unless the error is such
that it is impossible for execution to continue. This permits the
system to locate and identify as many errors as possible before
returning control to the Keyboard Monitor. When chaining is
8-6

requested, intermediate output files produced by one system program are deleted automatically after they have been read as input
by the next program in the chain sequence. This serves to. optimize
storage requirements and minimize· access time, particularly on
DECtape and LINCtape based systems.
The OS/8 FORTRAN IV system also includes FORLIB.RL, a
library of FORTRAN functions and subroutines, plus LIB~A,
the system librarian program. Almost every FORTRAN program
executes calls to library functions and subroutines which perform
such tasks as mathematical function evaluation, data I/O and
numeric conversion. When the loader recognizes that a program
or subroutine has called a library component, it copies a relocated
version of the referenced library routine into the loader image file
.and links it to the calling routine. LIBRA is used to maintain the
library by inserting or deleting library functions or subroutines,
which are simply assembled FORTRAN files or specially coded
RALF modules. LIBRA may also be used to create alternate
libraries for use in place of the standard system library.
Because it affords full I/O device independence, highly optimized memory and bulk storage, program chaining, and a variety
of run-time options, OS/8 FORTRAN IV is necessarily somewhat complicated. In order to use the system most efficiently, it
is important to identify the four processes that must be performed,
in the proper sequence, to execute a FORTRANsource program:
Process

Performed by

COMPILATION

FORTRAN IV compiler (F4, PASS2,
PASS20 and PASS3).
RALF assembler (RALF).
FORTRAN loader (LOAD) usmg system library. '
FORTRAN run-time system (FRTS).

ASSEMBLY
RELOCATION
EXECUTION

It is also important to identify the types of input that must be

supplied to each process listed above and the types of output that
will be produced. The OS/8 FORTRAN IV system accepts usergenerated FORTRAN source programs (supplied as input to the
compiler) and user-written RALF assembly language files (supplied
to the assembler) as input. It generates four types of output files: _
8-7

a. RALF assembly language files generated by the compiler
and read as input by the assembler. Compiler output is
functionally equivalent to user-written RALF language
input.
b .. Relocatable binary files generated by the assembler and
read as input by the loader.
c. Loader image files generated by the loader and read as
input by the run-time system. Once a program has been
written and debugged, it may be stored as a· loader image
file and executed whenever required without the necessity
for further compilation, assembly, or relocation.
d. Optional listing files including the FORTRAN source
listing produced by the compiler, the RALF language listing
produced by the assembler, and a symbol map produced by
the loader;
In addition, the FORTRAN program itself usually reads and
writes data files under the supervision of the run-time system;
FORTRAN I/O files are treated separately in the section on the
FORTRAN IV Run-Time System.
Every FORTRAN source program thus generates up to three
. object files,aside from any I/O files that may be read or written
during execution, and up to three listing files. System-generated
files are most conveniently identified by assigning them the same
file name as the source. from which they were produced and a file
extension that identifies them by type. Table 8-1 lists the standard
file extensions used to identify various types of source and systemgenerated files. The standard extensions are called default extensions because, when any output file name is specified with a null
extension, the appropriate standard extension is appended by
4efault. Thus, specifying file "PROG" or "PROG." to the RALF
assembler, for example, causes the relocatable binary output from
the assembly to be written on file "SYS:PROG.RL" where "SYS:"
is the. default device when a file . name is explicitly defined ang
".RL" is the default extension for relocatable binary files. Specifying a null file causes this output to be routed to' file "DSK:
FORTRN.RL" where ."DSK:" is the OS/8 default device and
"FORTRN" is the default output file name. For clarity, all
examples in this chapter will use either null or default extensions,
although the user may explicitly specify any extension desired.
8-8

Table 8·1 .Standard FORTRAN IV File Extensions
Extension
.FT
.RA
.RL
.LD
.LS
.TM

- File Type
FORTRAN languag~ source file .
RALF assembly language file.
Relocatable binary (assembler output) .
Loader image.
Listing or symbol map .
System temporary file. Created by certain mUltipass programs and normally deleted automatically after use.

This chapter assumes that the reader is familiar with the OS/8
operating system; -however,· all material has been presented in a
manner that requires minimal experience with OS/8. Every reader
. should understand. the use of the OS /8 Keyboard Monitor
_ (although only the monitor R command is referenced here) and
the OS/8 Command Decoder. In particular, notice that all Command Decoder ,file/option specifications presented here are
illustrated in a standard -format which may not be the most convenient format for an experienced user's particular application. In
.- addition, the Command Decoder provides file .stqrage optimization
features which may be invaluable in many applications, but are
not covered in this chapter. DECtape and LINCtape users will
benefit from an understanding of the OS /8 file structure, so that
they may assign I/O files in a -manner that minimizes access time
on tape-based systems.
The FORTRAN N system of programs may be entered through
the CCL commands COMPILE, EXECUTE, and LOAD. These
-commands are described-In the CCL section of Chapter 1.
THE' FORTRAN IV COMPILER
The OS/8 FORTRAN N, compiler accepts one FORTRAN
source language program or .subroutine as input, examines· each
FORTRAN statement for validity, and produces a list of error
diagnostics plus a RALF assembly language version of the source
program, along with an optional annotated source listing, as output. A job containing one or more subroutines is run by compiling
and assembling the main program and each subroutine separately,
then combining them with the loader. F4 terminates a compilation
by chaining to the RALF assembler automatically unless it was
8-9

requested to return to the Keyboard Monitor. The compiler
called by typing:

R F4--

(terminated by a carriage return) in response to the dot generated
by the Keyboard Monitor. F4 may also be called via the CCL
command COMPILE (see the CCL section in Chapter 1). It replies
by loading the OS/8 Command Decoder, which accepts and decodes
a standard command line that designates 0 to 3 output files, 1 to 9
input files, and any run-time option specifications. The file/option
specification command line is entered by typing:
DEV:RALF.RA,DEV:LIST.LS,DEV:MAP.LS 0.0, ACOS(X)=ATAN[SQRT(1-X2)]
x
If x < 0.0, ACOS(x),= 1I"+ATAN
[SQRT(1-X2)]
x

If x = 0.0, ACOS(x) = 11"/2.0

ADB* (RETURN NEXT SAMPLE FROM REAL-TIME SAMPLING BUFFER)
ADB gets and returns the next sample in the range [-512, 511]
from the real-time sampling buffer. The following program illustrates how ADB may be used to sample 500 points from channel 3
and plot them on the scope:

100
10

DIMENSION PLTBUF(4ee)IDATBUF(5e)
CALL CLRPLTe4e0 I PLTBUF)
CALL- REAL 1M (DATBUFI 501 31 11 50e)
CALL CLOCK (81 10)
DO 100 1=11500
CALL PLOTelII/384.IADB(X)/1024.+.5)
READe 1.. 10) Q
FORMATeI2)
GO TO 1
STOP
END

After finishing the plotting, the program waits for the user to
type the RETURN key,. and then repeats the sampling-display
process. Note that REALTM sets up the sampling procedure, while
CLOCK actually initiates the sampling.
ADC* (ASYNCHRONOUS SAMPLING)
The ADC function accepts an integer argument in the range [0,
15], assumed to be a channel number. It returns the current value
of the referenced channel as a real number in the range [-1, 1].
Sampling employs the fast SAM instruction for one or multiple
channels. ADC may not be used in a program that also uses
REALTM. ~he following program illustrates the use of the ADC
function.
8-47

C
C
C

E~AMPL.

E. OF' ADC !"UNCn 01'1
l1EQUlhES PDP12 OR LABBE riAhDwAhE
SAMfLES Ai'JD l'fPES AL'JALOG I.~PUT

C
10 COL\) TL'J UE
\Vm1E(4~

100)
TYPE lL'-I CHA\lL~EL Nl.MBEh •
1
• A~ D L~ LM BE R 0 Jo' SAM R.. E S • )
READ( ~ 1 0 1> N C~ L'I S
101 FOFMAT< 21 3>
DO 20 l=lll'JS·
X=ADC(NC)
wRI TE( 4, 102) X
102 liOfMAT< F 15.5)
20 CONTINUE
GOTO 10
CiLL EXI T
END
100 FOFMAT<

AIMAGt (COMPLEX TO IMAGINARY CONVERSION)
AIMAG returns the imaginary part of its complex argument as a
real variable.
AINT (SINGLE-PRECISION FLOATING-POINT to/ INTEGER)
AINT is a floating-point truncation function. Given a real argument, it truncates the fractional part of the argument and returns
the integral part as an integer. This is accomplished by taking the
absolute value of the argument, aligning and normalizing this result,
then restoring the original sign. AINT, IFIX, and INT perfonn
identical functions.
ALOG (SINGLE-PRECISION NATURAL LOGARITHM)
ALOG calculates and returns the natural (Naperian) logarithm
of a real argument greater than zero. Any negative or zero argument returns an error message and a value of 0.0. The algorithm'
used is an 8-term Taylor series approximation.
ALOGIO (SINGLE-PRECISION COMMON LOGARITHM)
ALOGIO calculates and returns the common (base 10) logarithm
of a real argument greater than zero. Any negative or zero argument returns an error message and a value of 0.0. The calculation
is accomplished by calling ALOG to compute the natural logarithm
and executing a change of base.
8-48

AMAXO (SINGLE-PRECISION MAXIMUM VALUE)
AMAXO accepts an arbitrary number of integer arguments and
returns a real value equal to the largest of the arguments.
AMAXI (SINGLE-PRECISION MAXIMUM VALUE)
AMAXI accepts an arbitrary number of real arguments and
returns a real value equal to the largest of the arguments:
AMINO (SINGLE-PRECISION MINIMUM VALUE)
AMINO accepts an arbitrary number of integer arguments and
returns a real value" equal to the smallest of the arguments.
AMINI (SINGLE-PRECISION MINIMUM VALUE)
AMINI accepts an arbitrary number of real arguments and returns a real value equal to the smallest of the arguments.
AMOD (SINGLE-PRECISION A MODULO B)
AMOD accepts two real argume 3ts and returns a real value
equal to the remainder when the first argument is divided by the
second·argument. If the second argument is not sufficiently large to.
prevent overflow, an error message and a value of 0.0 are returned.
ASIN (SINGLE-PRECISION ARC-SINE)
ASIN calculates and returns the arc-sine (in radians) of a real
argument in the range [-1, 1] according to the relation:
ASIN(X) = ATAN(X/SQRT(I-X**2»
If the argument falls outside the range [-1, 1], an err.or message

results.
r

ATAN (SINGLE-PRECISION ARC-TANGENT)
ATAN calculates and returns the primary arc-tangent (in radi" ans) of. a real argument. The argument is first reduced according to
the r~lations:
(1) If x<2-14 ,
(2) If x>2- 14,
(3) If x> 1.0,
(4) If x PI T1\.Tf""1T1\.T ...... n" ....... "" ...... Tf ..1-.0 ..... ~ 110_ ,l~,,~ .... ~ .. ~ .... "";f,, ·~n "' .... ,,--~ 1
"p'-""'uy
\:,ALI:-Il1a.l
rate (e.g., FUNCTN less than 16), then RATE is interpreted as· a
number in Hertz and specifies the rate of clock interrupts.
When the clock is run at a programmable rate, the rate must fall
in the range [0.0244, 4096.0], or one tick every 250 microseconds
to every 40 seconds. Specifying a rate outside this range causes the
clock to be disabled (which may be desirable in some cases). The
calling program should not specify an unnecessarily high clock rate,
as this slows down program execution. Because the allowable set of
programmable clock rates is discrete, the clock may not run at
exactly the specified rate but will always be less than or equal to
the specified rate and within one percent of it. The actual rate can
be computed from the specified rate by:
.... ~

....

...., ... , ' - ' ......

UJ.6U..1UI.dH••

~J.

Ul,-

... au,-.1

RA = RBI [RB/RR]
RA = actual rate
RR= requested rate

[ ] = greatest integer
8-52

\.LV"",,,

av\.

(11

RB = base rate- maximum number in the set (100000,
10000, 1000, 100) that satisfies the condition.
RB/RR~4096

If an externally driven clock is specified, RATE is interpreted
as the number of external ticks between clock interrupts; and must
be in the range (1, 4096]. If the argument is outside this range,
the interrupt rate will be arbitrary. The RATE argument is actually
an overflow count, and the actual rate of the clock can be determined from:

RA=RE/RATE
where'RE is the rate of the external input and RA is the actual
clock rate. The advantage of an externally driven clock is that it
may run at an arbitrarily high rate; however, specifying too high a
rate may hang up the FORTRAN system. The calling sequence to
define an external clock for the KW12A differs from that of a call
for the DW8ES in that the'KW12A calling program must enable
Schmitt trigger 1. Optional clock execution is obtained on a
KW12A external clock when RATE=l. Note that the arguments
fora KW12A external clock are sufficient to enable a DK8ES
external clock, but not vice versa.
CLOGt (COMPLEX NATURAL LOGARITHM FUNCTION)
CLOG calculates and returns the natural logarithm of its complex argument, as defined by the relation: '
LOG(X+iY)= LOG(X**2+Y**2)+i*ATAN(Y IX)
CLRPT* (CLEAR PLOT SUBROUTINE)
The calling sequence:
CALL CLRPLT (N,BUFFER)
clears the current plot, if any, and assigns an N element buffer
(designated BUFFER) which will hold 3N/2 points for display.
The display is actually created by the PLOT subroutine. The variable BUFFER must be an array with at least N elements.
CMPLXt (REAL-TO-COMPLEX CONVERSION FUNCTION)
- CMPLX accepts two real arguments and returns a complex
value with real part equal to the first argument and imaginary part
equal to the second argument.
8-53

CONJGt (COMPLEX CONJUGATE FUNCTION)
CONJG calculates and returns the complex conjugate of its
complex argument. This is accomplished by leaviJ)g the real part of
the argument unchanged, and negating the imaginary part.
COS (SINGLE-PRECISION COSINE FUNCTION)
COS calculates and returns the cosine of a real argument (in
radians) by applying the identity:
COS(X) '= SIN(X+7T/2)
COSD (SINGLE-PRECISION COSINE IN DEGREES)
C9SD calculates and returns the cosine of a real argument (in
degrees). This is accomplished by adding 90 to the argument,
converting the result to radians, and extracting the sine.
COSH (SINGLE-PRECISION HYPERBOLIC COSINB FUNCTION)
COSH calculates and returns the hyperbolic cosine of a real
argument according to the relation:
If Ixl ~88.029
(
1.0 )
COSH(x) 1/2 EXP(x) "I EXP(x)

Tf
Iyl '>
.... i ..... j
'"

~~
()?~ :-Inn Iyl
-- ............ _ ................... 1....... 1

COSH(x)

= EXP(lxj -

100'
?~~R
()?~
........ 'oe...................
_-

loge2)

Jf Ixl ,- loge2>88.028
COSH(x) 377737777777 8

and an error message is returned.
CPUT (CHARACTER PUT SUBROUTINE)
The calling sequence:
CALL CPUT (STRING,N,CHAR)
causes CPUT to insert CHAR as the Nth character in STRING,
where STRING is a character string stored in A6 format, and
CHAR is a number in the range [0, 63] which is interpreted as a
character. The following program illustrates the use of CGET and
CPUT.
8-54

DATA STR/'clEf! 'I
100) STR
FOhMATC'
. clEf! IN A~CII
'1 A6)
WRI lEe 41 101>
FORMAT<'
tiE'f! IN DECIMAL'}
DO 10 1= 114
CALL CGETC SlIu III CrlAFO
WhITE,(41102) ICnAR
CONTINUE
FORo1ATC 16)
DO 20 1= 1.. 6
J=2*I
CiLL CPlITC SI& II J)
~RITEt41

100
101

10
102

COl~TINUE

WRITE(41103) SIR
103 FOhMATC'
NEW STRING
CALL EXI T
E.'l'D

'IA6)

.R F4
*TCHRC/G$
nEf! I N ASCI I
nEf f
KEf! IN DECIMAL
8
5

25
33
NEW SlliIl'l'G

BDFHJL

CSINt (COMPLEX SINE FUNCTION)
CSIN calculates and returns the. sine of a complex argument
according to the relation:
SIN(X+iY)= SIN(X)*COSH(y)+i*COS(X)*SINH(y)
CSQRTt (COMPLEX SQUARE ROOT FUNCTION)
CSQRT calculates and returns the square root of a complex
argument. .
DABSt (DOUBLE-PRECISION ABSOLUTE VALUE FUNCTION)
DABS returns the absolute value of its double-precision argument by negating the ~gument if it is negative, or returning it
intact if it is positive.
DATANt (DOUBLE-PRECISION ARC-TANGENT FUNCTION)
DATAN calculates and returns the primary arc-tangent of its
double-precision argument. The argument is first reduced to the
interval [0, 1;2] with the identities:

8-55

ATAN(-X)

= -ATAN(X)

if X> 1.0, ATAN(X)

= 1T/2-ATAN(1/X)

if O.5 1, then arg 1 of
CLOCK CALL should not specify clock-initiated
sampling. Fetching of the first sample will be
initiated in the clock interrupt routines, or 50-100
fLS after the clock tick. The other samples are
taken as soon as possible, about 100-200 ILS later
fro .. .0-:.,-.1-. c

LV.&.

'"" ...................

-:.TY't1"\ 1.0

UU.l.L.Ly..l.~.

NPTS= total number of samples to take.
Algorithm and Comments
The following program samples 500 points from channel 3 at 10 .
Hz. and plots them on-the scope:

100
C
10

DIMENSION PLTBUF(400),DATBUFC50)
CALL CLRPLT(400,PLTBUF)
CALL REALTM eDATBUF, 50, 3, 1,500)
CALL CLOCK (8, 10)
DO 100 I = I, 500
CALL PLOTCl,I/384.,ADBeX)/1024.+.S)
NOW PAUSE SO THAT POINTS WILL BE DISPLAYED
READC 1, 10) Q
FORMATCI2)
GO TO 1
STOP
END

8-62

ROPEN* (OPEN A PDP-12 RELAY)
ROPEN accepts one integer, real or logical argument, assumed
to be a PDP-12 relay number in the range [0, 5], and opens the
referenced relay. If the argument falls outside the specified range,'
. the result is unpredictable. ROPEN has no effect when called on a
PDP-8.
RSW (READ SWITCH REGISTER)
RSW accepts two real, integer or logical arguments. The first
argument is assumed to be a switch register switch number in the
range [0, 11]. The second argumentis set to the logical value of
the referenced switch (right switch register on the PDP-12). If tne
first argument falls outside the range [0, 11], the result that will be
returned in the second argument is unpredictable.
SCALE * (DEFINE SCALE OF SCOPE)
SCALE defines the scope screen scaling for calls to PLOT. The
calling sequence is:
.
•
CALL SCALE (XLO, YLO, XHI, YHI)
where:
XLO is the value at the left edge of the screen.
YLO is the value at the bottom of the screen.
XHI is the value at the right edge of the screen.
YHI is the value at the top of the screen:
If SCALE is never called, the assumed values are equivalent to:

CALL SCALE (0,0,1.3,1.0)
SIGN (SINGLE-PRECISION TRANSFER OF SIGN)
SIGN accepts two real arguments, calculates the absolute value
of the first argument, and returns this value if the second argument
is positive (or zero), or the negative of th!s value if the second
argument is negative.
SIN (SINGLE-PRECISION SINE FUNCTION)
SIN calculates and returns the sine _of a real argument (in
radians). The argument is reduced to the first quadrant, and the.
sine is then computed from a Taylor series expansion.
8-63

SIND (SINGLE-PRECISION SINE (DEGREES) FUNCTION)
SIND calculates and returns the sine -of a real argument (in
degrees). This is accomplished by converting the argument to
radians and passing this value to the SIN function.
SNGL t (DOUBLE- TO SINGLE-PRECISION CONVERSION)
SNGL accepts a double-precision argument, truncates the loworder bits, and returns the resulting real value.
SiNH (SiNGLE-PRECISION HYPERBOLIC SIGN)
SINH calculates and returns the hyperbolic sine of a real argument according to the relations:
If

o.1088.028. SINH(x)

= 1/ 2 [EXP(x) -

X+X!1/fl

~XP(X)-\

+ x5/12o

[EXP(lxl - log('2)] • [-signum(x)]

SQRT (SINGLE-PRECISION SQUARE ROOT FUNCTION)
SQRT calculates and returns the (positive) square r~ot of a
positive real argument. Any negative argument results in an error
message.
ssw* (READ PDP-12 SENSE SWITCH)
SSW accepts two real, integer or logical arguments. The first
argument is assum~u to be a PDP-12 sense s'vvitch nu.tnber in the
range [0, 5]. The second argument is set to the logical value of the
referenced sense switch. If SSW is called on a PDP-g, a value of
zero is always returned. If the first argument falls outside the range
[0, 5], the result that will be returned in the second argument is
generally unpredictable. The exception is the calling sequence:
CALL SSW (l4,RUA12)
-,

which returns RUA12=0 on a PDP-8 and RUA12=1 on a
PDP-12.
SYNC* (READ A SCHMITT TRIGGER)
SYNC determines whether a Schmitt trigger has been fired, and
must not be called unless CLOCK has been called at least once.
SYNC accepts two real, integer or logical arguments. The first
argument is assumed to be a Schmitt trigger number in the range
[1, 3]. The second argument is set to one if the referenced Schmitt
8-64

trigger has fired since the last time it was read, or to zero other",:.
wise. The referenced Schmitt trigger is also_reset to the not-fired, or
zero, state. A call to CLOCK sets all triggers to the zero state, and
any tngger that was not enabled by a call to CLOCK is always in
the zero state. If the first argument falls outside the range [1, 3], an
unpredictable result (either zero or one) is generally returned. If .
the first argument- is zero, however, a value of zero is· always
returned.

TAN (SINGLE-PRECISION TANGENT FUNCTION)
TAN calculates and returils the tangent .of a real argument (in .
radians). This is accomplished by computing the quotient of the,
sine of the argument divided by the cosine of the argument; thus,
if the cosine of the argument is zero, an error message is returned.
TAND (SINGLE-PRECISION TANGENT, DEGREES)
T AND calculates and returns the tangent of a real argument (in
• degrees). This is accomplished by converting the argument to
radians and passing the resulting value to the TAN routine.
.
TANH (SINGLE-PRECISION HYPERBOLIC TANGENT)
TANH calculates and returns the hyperbolic tangent of a real
argument by computing the quotient of the hyperbolic sine of the
argument divided by the hyperbolic cosine of the argument.
TIME* (READ TIME OF DAY)
TIME may be called as a _subroutine with one real or integer
argument, or as a function with a dummy argument. It returns the
elapsed time since the clock was started. This result will be in
seconds' unless the clock is running under external input, in which
case it will be in external tick~, with the interval between ticks
specified by the clock rate (see CLOCK). FORTRAN IV SOURCE LANGUAGE
The FORTRAN language is composed of mathematical-form ,
statements constructed in accordance with precisely formulated
rules. FORTRAN (source) language programs consist of meaningful sequences of FORTRAN statements that direct the computer
to perform specified operations and computations. OS/8
FORTRAN IV is compatible with ANSI Standard FORTRAN;
that is, programs written in compliance with the ANSI Standard
FORTRAN (3.9-1966) are acceptable to OS/8 FORTRAN IV.

8-65

Certain features of OS/8 FORTRAN IV are not defined by the
standard, so users intending to write OS/8 FORTRAN IV programs to be used on other machines should ensure either thatthey
do not use the non-standard features, or that the other machines
on which the programs are to be run also include these features.
FORTRAN source programs are generally written on a coding
sheet such as the one shown in Figure 8-4. Each line of a program
contains three fields: statement number field, line continuation
field, and statement field. A fourth field, the identification field
consisting of columns 73 to 80, is ignored by the compiler. It may·
be used to number statements sequentially or for any other purpose.
A statement number consists of one to five digits entered in
columns 1-5. Leading zeros or blanks (leading and trailing) are
retained on the listing, but otherwise ignored in this field. Statement numbers may be assigned in any order, but they must be
unique. Any statement referenced by another statement must have
a statement number. Statement numbers'on specification statements
are ignored.
Do"

FORTRAN
=~-

i~:~~;::~il:

..--- -.----.----

FORTRAN STATEMENT

'OfN'"

"'''ON

12 ) .. ~!6 " 9 Ion '21Jl.15161'1'1'20'ln2)"'2HQo2nn9lO)IJ1J)l'~16l1l13''''04l1''UJ''.')'4.7.'49SO~I.5HJS.5H6)7U~606Io2636.6S"6I6l6fl0nn J'17.a 1$1671 nn

c:t.1LtiL2+-!'!+9.g~r'~l~,UL,AlIE,S, t.R:J.ME, ,N4MB•E,R,S,

,F,RPM

~+-+--t-+-tB-Q."lI0,

t I I I I

,1,=,1,1"

,5,°1 '1,2,« I I

I I

I 1 I II

11~
j

..Tlq

,51~'

I I

J I

1 I

I I I

I I

11 I I I I I r I I I I I I I I L 111 I

I I

,'I I

I j! II It:

"1_ ,

~~-~'II

III

11111

Iltll!

i'::':it:£:=-==:::::::::::'::::::~~:'::::::::::::::::::::I:::::::i
~~~ ~:~~~ -+~~.--~

f------+

.........,...............-;

I:':' :::~'\~"5:ci~';'~T:
:(:1:\:):): :99: T8:4::::::::
105.1
ITVPE

JRNT,I NU,E , , , "

105

"FORMAT 114 'I S PR IME: ' l

""
~ ~+-+-t-"""""'+-+-+-+-+-+-+-+-I

I I

I-+-++++t->-++++++-+-!-+t-+ I

I I

1111!

I::::::: i

:::::::::::::::::::::::
.;.

H-++-+++-++_: : : : : : : : : : : : : : : : : : : : : : I : : : : : : : : : : : : : : : : : : : : : :
I 1 I

, I

....-+-+-

I I I 1 t • -+ ........ +-, I

Figure 8-4

" t I , 1 I I I r I • I , I I I-J.++-,I-I-H++++++-I-I-H+H-;-I-l-H+-i--rl

FORTRAN IV Coding Form

8-66

If a FORTRAN statement is so large that it cannot conveniently
fit into one statement field, the statement fields of up to 5 additional"
lines may be used to specify the complete statement. The first line
of a statement must have a blank in column 6. Continuation lines
must have some character other than a blank in column 6.
FORTRAN statements ~efine arithmetic operations, call for
input or output, and alter the sequence of program execution. Any
FORTRAN statement may appear in the statement field (columns
7 -72). Except when -they occur as alphanumeric data within a
FORMAT statement, DATA statement, or literal constant, blanks
(spaces) are ignored and may be used freely for appearance purposes. A TAB at the beginning of a line or after the statement
number causes spacing to column 7. The first TAB after column 7
is treated as a blank by the compiler. Any input line that does
not contain a TAD' or at least 6 other characters in columns 1-72
is ignored by the compiler.
Comments explaining tIre program may be written in any format. A line which contains the letter C in column 1 is interpreted as a
line of comments. Comment lines are printed on ali listings, but are
otherwise ignored by the compiler. A comment line must not immediately precede a continuation line.

Constants, Variables, and Expressions
CONSTANTS
The constants, variables, and expressions _described below are
basic to expressing data values in the FORTRAN language. Seven
types of constants are used in OS/8 FORTRAN IV programs:
integer, real, _double precision, octal, complex, logical, and Hol_lerith.
Integer Constants
An integer constant consists of from one to seven decimal digits
written without a decimal point. Negative- constants must be preceded by a minus (-) sign; however, the plus (+) sign preceding a
positive constant is optional. Embedded commas and blanks are
not allowed in integer constants.
Examples:

o
+051
-440
6073
8-67

Integer constants must fall within the range -2t23 to 2t23-1
(-8,388,608 to 8,388,607 decimal). When used as subscripts, integer constants are taken modulo 2t12 (4096 decimal). The follow- .
ing are illegal as integer constants:

10.3
5,000 '

9000000

(decimal point)
(comma)
(outside acceptable range)

Real Constants
A real constant is an integer constant followed by a decimal point,
a second string of digits and an optional exponent. Only the leftmost
six digits, aside from leading zeros, are used by the compiler. A
negative constant must be preceded by a minus (-) sign. The plus
(+) sign'preceding a positive real constant is optional.
Real constants may be entered in exponential notation, as illustrated below, by specifying a positive or negative decimal value
followed by the letter E and a 1-3 digit integer which may be positive, negative or zero. The value of the real constant is taken as
the value of the decimal number preceding the letter E multiplied
by that power of 10 indicated' by the integer following the letter E.
This notation eliminates leading and trailing zeroes from very large
or very small real constants. The absolute value of any real constant
must fall within the approximate range 1Ot-615 to 1Ot615 (or zero).
Examples:
0.0
.579
-10.794
5.0E03
5.0E+3
5.0E-3
5.0EO
5EO

(i.e., 5000.)
(i.e., 5000.)
(i.e., 0.005)
(i.e., 5.0)

The following are not valid real constants.

6,517.6
131

IDE
20E1.5

(comma)
(no decimal point or exponent)
(no exponent)
(exponent must be integer)

8-68

Double Precision Constants
A double precision constant is a real constant that contains extra
significant digits. Aside from leading zeroes, only the leftmost 17
significant digits of a double precision constant are used by the
compiler.. The decimal point may be omitted from a double precision constant that does not have a fractional component. In other
,respects, double precision constants conform to the same format as
real constants, except that the letter D is used in place of the letter
E, preceding the exponent, when exponential notation is employed.
Double precision arithmetic requires the presence of an FPP with
extended precision· option.
Examples:

24.671325982134DO
3.6D2(i.e., 360.)
3.6D-2
(i.e., .036)
3.0DO
3DO
Octal Constants
An octal constant is a string of octal digits (0-7 only) preceded
by the letter O. Only the 12 low-order digits are used by the compiler. Octal constants are valid only in DATA statements where
they are generally used to sefbits for masking purposes.
Examples:

DATA JOB/01032/
DATA BASE/07777/
Complex Constants
FORTRAN IV provides for direct operations on complex numbers. A complex constant is written as an ordered pair of real constants separated by a comma and enclosed in parentheses.
Examples:

(.70712,-.70712)
(8.763E3, 2.297)
The first constant of the pair represents the real part of the complex number, and the second constant represents the imaginary
part. The real and imaginary parts may each be signed. The enclosing parentheses are part of the constant and always appear,
regardless of context. The two parts are represented internally by
8-69

single precision floating-point numbers occupying adjacent positions in memory. Complex arithmetic can only be done on the FPP
using the extended precision option.

Logical Constants
The two logical constants (.TRUE. and .FALSE.) have the internal values 1. and 0., respectively. Logical constants may be
entered in DATA or input statements as .TRUE. or .FALSE.
(or abbreviations .T. or .F.).The enclosing periods are part of the
constant and always appear. Logical quantities are operated upon
by logical operators only.
Hollerith Constants
A hollerith cOl!,stant (or literal constant) is a string of ASCII
characters. There are two forms by which a Hollerith constant may
be represented.
Form I: nH character string
where n is the number of characters following the H.
Examples:
5HWORDS

3H123
Examples:
'WORDS'

'123'
The single quote character which delimits a Hollerith constant in
form 2 may be included in the character string if immediately preceded by a second single quote character. Thus, 'DON' 'T' will be
stored as DON'T.
A Hollerith value may be entered ina DATA statement or FORMAT statement as a string of one to six ASCII characters per in. teger or real variable, and one to twelve per complex or double
precision variable .
. VARIABLES
A variable is a quantity which is represented by a symbolic
name. Arithmetic statements and ASSIGN statements are·used to

8-70

change the value. of a variable, by computation or assignment, during program execution. I/O statements and subroutine calls can
also change the value ofa variable. A variable name is a string of
one to six alphanumeric characters, the first of which must be
alphabetic:
Valid Names
J
ALPHA
MAX

A,34

Invalid Names

1ACT
STANDARD
FILE 1
#MAIN.

(first character number)
(too long)
·(space within name)
(# not alphanumeric)

There are five types of variables: integer, real, double precision,
complex, or logical. Definitions for these types correspond to
definitions of constants of the same type, i.e., integer variables take
on a value of from zero to any positive or negative integer in the
range -8,388,607(decimal) to 8,388,607(decimal); real variables
contain a decimal point; etc.
Type classification is assigned to a variable explicitly via a type
declaration statement or by virtue of the initial letter of its name. A
first letter of I, J, K, L, M, or N indicates an integer variable .. Any
other first letter indicates areal variable. The type declaration statement overrides the type assigned by an initial letter .
Arrays
Variables can be either scalar (representing a single quantity)
or array (representing many quantities with one name). An entire
array is identified by its name, while a single element of the array
is identified by a subscript, in parentheses, following the array name.

Refers To

Variable
. ARRAY(l)

B(l,3)

The first element of a onedimensional array named
ARRAY.
The element located in the
first row and the third column of a two-dimensional
array named B.
8-71

Subscripts
The subscripts of an array variable can be integer constants or
expressions. For example, A(l), A(ONE), and A(I+ 1,2*K+3*J)
illustrate valid subscripts. The elements of an array must be of the
same type, i.e., all real or all logical.
The extent of an array is determined by the dimensions it is
assigned. This may be done by means of a DIME~SION or COM. MON statement, or as part of a type declaration statement.

EXPRESSIONS
An expression is a combination of elements (constants, subscripted or non subscripted variables, and function references), each
of which is related to another by operators and parentheses. An
expression represents one single value that is the result of calculations specified by the elements and operators that make up the
expression. An expression may, itself, function as an element in
another expression if it is enclosed in parentheses. The FORTRAN
language provides two kinds of expressions: arithmetic and logical.

A rithmetic Expressions
. An arithmetic expression is a combination of constants, variables,
and function references separated by arithmetic operators and
parentheses. In the absence of parentheses, algebraic oper~ations
within arithmetic expressions are performed in the following
descending order:

**
* and /
+and-

exponentiation
unarymmus
multiplication and division
addition and subtraction
equals or replacement sign

Parentheses are used to change this order of precedence. An
operation enclosed in parentheses is performed before its result is
used in other operations. In the case of operations of equal precedence, the calculations are performed from left to right. Additional
computations (such as sine, cosine, or square root extraction) may
be specified via a function reference.
An arithmetic expression may consist of a single constant, variable, or function call, referred to as a basic element. For example:
8-72

2.71828

ZeN)
. TAN (THETA)
Any fun<;tion reference acts as a basic element in an expression,
since all functions return a unique value for any given argument.
The reference SQRT(4.), for example', always represents the value
2. in an expression.
Any arithmetic expression may be enclosed in parentheses and
considered as a basic element. For example:
IFIX(X + Y)/2
(ZETA)
(COS(SIN(PI*EM)+ X))

...

Compound arithmetic expressions may be formed using numeric
. operators to combine basic elements. For example:
X+3
TOTAL/A
PI*EM,
A basic element preceded by a
expression. For example:

+ or- sign is also an arithmetic

+X
-(ALPHA *BETA)
-(SQRT(-GAMMA))
With the exception of unary minus,no . two arithmetic operators
may appear in sequence. For instance, X* /Y is illegal.
Parentheses do not imply multiplication, thus (A+B)(C+D) is
improper. This expression must be written:
(A+B) *(C+D)

A typical numeric expression using numeric operators and a
function reference, the expression for· one of the roots of the general
quadratic equation
,-b+ (bt2 -4ac
2a
might be coded as:
,(-B+SQRT(B**2-4. *A *C))/(2. *A)
8-73

The following examples illustrate conversion of other mathematical expressions into FORTRAN expressions.
a+5
a.b
at(b+2)
(b:d) 2.5

A+5.0
A*B
A**(B+2)
((B+D)/ A)**2.5

In general, only real and integ~r quantities may be mixed in
arithmetic expressions. No other type mixing is legal. Logical variables and constants may only be operated upon by logical operators
(.AND., .OR., .NOT., .XOR., .EOV.). Hollerith literals in expressions have type integer, with only the first six characters being used.
Logical Expressions
A logical expression combines logical constants, logical variables,
logical function references, and logical expressions, using the logical
or relational operators given below.
Logical operators can combine only basic elements whose type is
logical. Rela~ional operators compare units of type integer, real, or
double-precision. The value of such an expression will be of logical
type (that is, .TRUE. or .FALSE.). The relational operators .EO.
and .NE. may also be used with complex expressions. Complex
quantities are equal if the corresponding parts are. equal.
~1eaning

Logical Operator
.NOT. expr

H"as the value .TRUE. only if the expression
is .FALSE., and has the value .FALSE. only
if the expression is .TRUE.

exprl.AND.expr2

Has the value .TRUE. only if exprl and
expr2 are both .TRUE., and has the value
.FALSE. if either exprl or expr2 or both are
.FALSE.

exprl.OR.expr2

(Inclusive OR) Has the value .TRUE. if
either exprl or expr2 or ,both are .TRUE.,
and has the value .FALSE. only if both
exprl and expr2 are .FALSE.

exprl.XOR.expr2

(Exclusive .OR.) Has the value .TRUE. if
either exprl or expr2, but not both, are
8-74

Logical Operator

Meaning
.TRUE., and has the value .FALSE. otherWIse.

exprl.EQV.expr2

(Equivalence) Has the value .TRUE. if exprl
and expr2 are both. TRUE. or both .FALSE.,
and has the value .FALSE. otherwise.

Relational operator

Relation

.GT.
.GE.
.LT.
.LE.
.EQ.
.NE.

greater than
greater than or equal to
less than
less than or equal to
equal to
not equal to

The enclosing periods are part of the logical and relational operators, and must be present
. A logical expression, like an arithmetic expression, may consist
of basic elements or a combination of elements, as in
.TRUE.
X.GE.3.14159
or
TVAL.AND.INDEX
BOOL(M).OR.K.EQ.IMIT
where BOOL is a logical function with 1 argument, or a singlydimensioned logical array. A logical expression may also be enclosed in parentheses and function as a basic element. Thus, the
expressIOns:
A.AND.(B.OR.C)
and
(A.AND.B).OR.C
are evaluated differently.
8-75

No two logical operators may appear in sequence, except in the
case where .NOT. appears as the second of two logical operators.
Any logical expression may be preceded by the unary operator
.NOT. as in:
.NOT.T
.NOT.X+7.GT.Y+Z
BOOL(K).AND .. NOT.(TV AL.OR.R)
Logical and relational operations (unless overridden by parentheses) are carried out in the following order:
.GT.,.GE.,.LT ... LE.,.EQ.,.NE .
.NOT .
.AND .
.OR .
.EQV.,.XOR.
For example, the logical expression
.NOT.ZETA**2+Y*MASS.GT.K-2.0R.PARITY.AND.X.EQ.Y
is interpreted as
(.NOT.«(ZETA * *2)+(Y*MASS».GT.(K -2))).OR.(PARITY. AND.(X.EQ.Y»

There are 16 logical operators theoretically possible between the
logical expressions. Two of them are constants (true and false) and
four are unary operators (that is, the. value of one of the two expressions is irrelevant to the value of the operation). These six are
marked by asterisks in Table 8-12. The remaining ten operators
can be most conveniently represented as shown at the right of the
table, with A and B representing the two logical expressions involved.

Assignment Statements
A variable may be assigned a value at any point in the source
program. During program execution, the most recent assignment
determines the variable's value in subsequent statements. The
statements which may be used to assign a value to a variable are
the arithmetic and logical statements which assign a numeric or
logical value and the ASSIGN statement which assigns a statement
number.

8-76

ARITHMETIC STATEMENTS
Arithmetic statements indicate computations to be performed by
OS/8 FORTRAN IV.
Form

v=e

where

is- a variable name

IS an expreSSIOn

is the replacement operator
Effect

Table 8-12

The variable v is assigned
the value of expression e.

Truth Table for Logical Expressions

Expressions Involved:
F
F

F
T

T
F

T
T

FORTRAN IV
Expressions _

FALSE

.FALSE.

AND

A.AND.B

A .AND .. NOT. B

F
'F

.NOT. A .AND. B

XOR

A .XOR. B

A .OR. B

NOR

.NOT. (A .OR. B)

EQV

A .EQV. B

NOT B

.NOT. B

A .OR. .NOT. B

.NOT. A

.NOT. A .OR. B

NAND

.NOT. (A .AND. B)

TRUE

.TRUE.

A
B
-Function

*
*
*

NOT A

8-77

•

The arithmetic statement associates a variable name with a value.
This name may then be used in subsequent expressions to represent
the value. Thus, if the arithmetic statement A=2 is executed first,
the statement B=A+ 1 is equivalent to the statement B=2+ 1, or
B=3.
Since the equal sign in the arithmetic statement does not indicate
equality but, rather, a replacement; statements of the form:

1=1+1
are perfectly legal. The arithmetic statement is, in fact, the only
means in FORTRAN by which the results of computations represented by expressions may be stored.
Tn the following examples, the expression to the right of 'the
equal sign is evaluated and converted when necessary to conform
to the type of the variable to the left of the equal sign. The converted value is stored in the storage location associated with the
variable name to the left of the equal sign. That is, if a real expression is assigned to an integer variable, the value of the exp~es
sion is converted to an integer before assignment.
Examples: .
ANS=Y*(X**2+Z)
I=l*N
,.T/Y"o

~T'\

-n~T'\

~~J)=f\~J)--I>~J)

P=.TRUE.
S=D.LT.5
The expression to be assigned must be capable of yielding a value
which conforms to the type attribute of the variable to which it is
. being assigned. The compiler performs conversions in accordance
with Table 8-13.
THE GO TO ASSIGNMENT STATEMENT
The ASSIGN statement is used in conjunction with an assigned
GO TO statement to permit symbolic referencing of statements.
Form

ASSIGN n to var

Where n is a statement number
var is an integer or real variable
Effect

The variable represents the assigned statement number
and may be used in an assigned GO TO statement.
8-78

Table 8·13

Conversion Rules for Assignment Statements

TO:

00
I
-....l
\0

DOUBLE
PRECISION

LOGICAL
CQNSTANT

LITERAL
CONSTANT

R,D

H,D

D,6

R,C

H,C

D,6

D,R,I

H,D,R,I

D,R,I

D,6

Double
Precision

D,H,L

D;H,L

R,D,H,L

D,H,L

D,6

Logical

R,N

H,N

N,6

FROM:

REAL

INTEGER COMPLEX

Real

Integer

Complex

N-Convert non-zero to 1.0 (logical truth)
D-Direct replacement
C-Conversion between integer and floating point
R-Real only (imaginary part set to 0)
1-,Set imaginary part to 0
H-High order portion of ,expression assigned
L-Set low-order part to o·
.
6-Use the first character in the literal and five characters following

The statement number assigned must be that of an executable
statement. If more than one ASSIGN statement refers to the same
integer variable name, the value assigned by the last executed statement is the current value.
An integer variable which has obtained its value via an ASSIGN
statement must be redefined via an arithmetic statement before it
can be used in any context other than the GO TO statement. For
example, the statement: .
ASSIGN 10 TO COUNT
associates the variable name COUNT with statement number 10
and the statement:
COUNT=COUNT+l
is then invalid. The statement becomes valid, however, if preceded
by an arithmetic assignment statement such as:
COUNT=10
which assigns COUNT the integer value of 10. The use of an
arithmetic aSsignment, however, invalidates any future use of the
variable COUNT in an assigned GO TO.
An assigned GO TO must not be used to transfer program control outside of the program or subprogram in which it appears.

Control Statements
Statements are normally executed in the sequence in which t..~ey
appear in the source program. This sequence may be altered by the
use of the FORTRAN control statement: GO TO, IF, DO, CONTINUE, PAUSE, STOP, CALL and RETURN. The CALL and
RETURN statements, which transfer control to and from subroutines, are described later in this section.
GO TO STATEMENTS
The GO TO statement transfers control directly to a specified
statement. There are three forms of the GO TO statement: unconditional, computed, and assigned. A GO TO statement may
appear anywhere in the executable portion of the source program
except as the terminal statement in a DO loop.
Unconditional GO TO Statement
Form

GOTOn
8-80

Where n = the statement number of an executable statement
Effect

Control is transferred to statement n

When control.is transferred by a statement of the form GO TO
n, the usual sequential processing continues at the statement whose
number is n.
Examples:
GO TO 50
GO TO 1020

Computed GO TO Statement
Form

GO TO (n1,n2, ... ,nK)e
An optional comma may- follow the right parenthesis.

Where n1,n2, ... ,nk are statement numbers ..
e is a positive (non-zero) integer expression whose
value is less than or equal to the number of statement
numbers within the parentheses.
Effect. Control is transferred to the statement whose number
is eth in the list of statement numbers.
The integer expression in a computed GO TO statement acts as
a switch, as. in the example given below:
GO TO (20,1 O,6),K .'
If

K=l, control will be transferred to statement 20; if K=2, to

statement 10; or if K=3, to statement 6. If K has a value less than
1 or greater than the number of statements' within the parentheses,
unpredictable results occur.
.

Assigned GO TO Statement
Form

GOTOv
or
GO TO v,(n1,n2, ... ,nk)

Where v is an integer variable
n1,n2, ... ,nk are statement numbers whose values may
have been assigned to v
8-81

Effect

Control is transferred to the statement whose number
is currently associated with the variable v via an ASSIGN statement.

An ASSIGN statement defines an integer or real variable as a
statement number. Thus, when the statement:
ASSIGN 10 TO LOOP
has been executed, control is transferred to statement 10 by the
assigned GO TO statements:
GO TO LOOP
or
GO TO LOOP, (10,20,100)
either of which may be used to transfer control to whichever statement number is currently associated with LOOP.
An assigned GO TO statement must never be used to transfer
program control outside of the program or subprogram in which it
appears.
IF STATEMENTS
An IF statement causes control to be transferred on the basis of
the value of a specified expression. There are two forms of the IF
statement: arithmetic and logical.
Arithmetic IF Statement

Form

IF (arithmetic expression) n1,n2,n3

Where n1,n2,n3 are statement numbers
Effect

Control is transferred to:
n1 if expression <0
n2 if expression =
n3 if expression >0

An IF statement transfers control to one of three statements, as
shown in the model, according to the value of the expression given.
For example, the statements:
ALPHA=3
IF {ALPHA) 10,20,30
8-82

transfer control to statement number 30. Complex expressions may
be used in an arithmetic IF statement; however, only the real part
is used in the comparison. If less than three statement numbers are
present, ,control passes to the next sequential statement for each of
the missing conditi,ons. T~us: '
IF (ALPHA) 10
STOP
transfers control to 10 if ALPHA is negative, otherwise it executes
the STOP statement.
Logical IF Statement

Form-

IF (logical expression) statement

Where statement may be any executable statement except
another logical IF or a DO statement
Effect

the statemen(given is executed if the expression has
the value .TRUE., otherwise, the next statement in
sequence is executed.

Examples:
LOGICAL T,F
IF (T.OR.F)X=Y+l
IF (Z.OT.X) CALL SWITCH (S,Y)
IF (K.EQ.INDEX) GO TO 15
. DO STATEMENT
DO statements provide for the repeated execution of a statement
or series of statements.
Form

DO n i=ml,m2,m3

Where n isa statement number
i is a nonsubscripted integer or real variable
ml,m2,in3 are integer or real constants or expressions
Effect

i is set to m 1 and statements following the DO statement up to and including statement n are executed
repeatedly increasing i by m3 at the end of each
iteration, until i is greater than m2. .

8-83

The statements which are executed as a result of a DO statement
are called the range. The variable i is called the index. The values
m1, m2, and m3 are, respectively, the initial, limit, and increment
values of the index. Note that the range of a DO need not be merely
a section of straight line code following the DO statement. A control statement which cauSes instructions elsewhere in the program
to be executed is permissible, as long as control eventually comes
back to the terminal statement. When the range contains such control statements, it is called an extended range.
If m3 is omitted, an increment of 1 is assumed. A zero or nega-·
tive increment is not permitted. The range of a DO is always
executed at least once, regardless of the values of the limit and
increment. After each execution of the range, the increment value
is added to the value of the index and the result is compared with
the limit value. If the value of the index is not greater than the
limit value, the range is executed again using the new value of the
index.
Examples:
DO 5 1=1,100
(1= 100 during last iteration of DO loop)
DO 20 1=5,100,2
(1=99 during last iteration of DO loop)
DO 100 1=0,100,2
(I=100 during last iteration of DO loop)
After the last execution of the range, control passes to the statement immediately following it. This exit from the range is called the
normal exit. Exit may also be accomplished by the execution of a
control statement within the range.
The values of the initial, limit and increment variables or expressions of the DO loop may be altered within the range of the
DO statement. Such alteration will not affect the operation of the
loop, since the values of ml, m2, and m3 are remembered by the
program. Altering the index will affect the number of iterations of
the loop, however. This value is available for program use as a
variable.
8-84

For example:
00 40 1-1,10

TEMP-I-!
ANUMBFhiEMP*0.1
ROOT-SQRT(ANUMBR)

In this example, the value of the index I is used as the minuend
in determining the value of TEMP. Also, when a statemerrt transfers control' outside the range of a DO loop, e.g., by a GO TO -or
IF, the index retains its current value and is available for use as a
variable. A transfer into a DO loop from outside its range may
cause improper partial execution of the loop unless the transfer
into the range is a return from the extended range.
The terminal statement of a DO range must not be a GO TO,
DO, RETURN, STOP, PAUSE, or an arithmetic IF statement. A
logical IF statement is allowed as the last statement of the range,
provided -that it does not contain any of the statements mentioned
above. As an example:
005. K-l,'i

IF (X(K).GT.L) YCK)-XCK)

•••
In this case, the range is considered ended when, and if, control
would normally pass to the statement following the entire logical
IF statement. Statement 5 is executed four times whether or not the
statement Y(K)=X(K) is executed. Statement 6 is not executed
until statement 5 has been executed -four times. Note that if statement 5 were:
5

IF (X(K).GT.Y(L»

GO TO 10

it would be an error.
Any statement which serves as the range limit of a DO loop must
not be used as the transfer point for IF or GO TO statements which
are outside the DO loop. The range of a :pO statement may also
include other DO statements. This is referred to as nesting. The
range of any nested DO statement must fall entirely within the
range of the next outermost DO statement; that is, every statement
8-85

in the range of an inner loop must be within the range of its enclosing outer loop. It is possible for a terminal statement to be the terminal statement for more than one DO loop, however. Figure 8-5
illustrates the order in which nested DO's are executed.

Figure 8-5. Nested DO Loops.

Do loops may be nested to a depth of (at least) ten levels. In
calculating this depth, one implied DO in an I/O statement counts
as one level, whose range is the single statement and n implied
DO;s within one I/O statement count as n levels the ranges of
which are all within the single statement.
CONTINUE STATEMENT
The CONTINUE statement consists of the text:
CONTINUE
and causes continuation of the normal sequence of program execution. CONTINUE is principally used as the range limit of DO
loops in which the last statement would otherwise be a GO TO,
IF, PAUSE, STOP or RETURN statement. The CONTINUE
statement is also used as a transfer point for IF and GO TO
statements within the DO loop that are intended to begin another
repetition of the loop. For example:
8-86

DO 25 1=1.,20

1
10
25
30

0=0+5.0
IF (A-B)10.,30.,25
A=A+ 1.0
B=B-2.0
GO TO 7
CONT)NUE
C=A+B

•
•
•

A CONTINUE statement used as the range limit of any number
of DO loops is compiled as an executable instruction,- as in .this
example:
DO 55 1=3., 5

•
•

DO 55 C= I., 11

•
•

DO S5 V=2., 6., 3

•

•
CONTINUE

•

A CONTINUE statement which serves as the range limit, of a
DO loop must not be used as the transfer point for IF or GO TO
statements which are outside the DO loop. If it serves as the range
limit of several DO loops, as above, it must not be used as the
transfer point for IF or GO TO statements which are. outside the
innermost loop. For example:

10
20
100

DO 20 1= I., 50
IF (K.EQ.4) GO TO 10
DO 10 1= I., 50
IF CK.EQ.4) GO TO 20
WRITE (51100)I.,J.,K
. CONTINUE
CONTINUE
FORMAt C31 6)
END

8-87

(incorrect)
(correct)

PAUSE STATEMENT
Form

PAUSE
PAUSE number

Where number iS,an integer variable or expression
Effect

The number, if any, is typed on the console terminal.
Execution is suspended until the user presses CONTinue on the comnuter console .
.L

The PAUSE statement interrupts program execution.
STOP STATEMENT
The STOP statement is placed at the logical end of a program.
Form

STOP

Effect

terminates the program and returns control to the
OS/8 monitor.

The STOP statement terminates program execution. No continuation is possible. If no STOP statement is present in a program, a
STOP occurs when control passes to the' END statement in the
MAIN program.
A CALL EXIT statement is equivalent to a STOP and closes
tentative files at the last block written on the file. Control returns to
the OS/8 Monitor.
END STATEMENT
The END statel11ent consists of the text:
END
and is placed at the physical end of a program or subprogram. In
the main program, the END statement is equivalent to STOP; in a
subroutine, END is equivalent to RETURN. The compiler assumes
the presence of an END statement if it fails to find one before the
end of the source input file. A program can not reference an END
statement.

Data Transmission Statements
Data transmission statements control the transfer of data between
computer memory and I/O devices. These include three distinct
types. of statement: data description (FORMAT) statement, input;
8-88

output (READ and· WRITE) statements, and device control
(BACKSPACE, REWIND, and END FILE) statements.
FORMAT STATEMENT
The FORMAT statement describes the form and arrangement
. of data on a record.
"~

Form

FORMAT (specl,spec2, .. ./ ... )

Where spec 1,spec2 define consecutive series of characters
within a record.
/ is the end of the record description.
) is the ~nd of a statement.
Effect

Specifies either the type of conversion to be performed. between the internal and external representation of data or the format of fixed data.

A FORMAT statement' must have a statement number which is
used in other statements for reference.
The field specification (spec) is one of the following:
"nAw
nBw.d
nDw.d
nEw.d
nFw.d"
nGw.d
nR
nlw
nLw
-sP

Tw
nX
'string'
"string"
where:
n '= an unsigned non-zero integer stating the number of times
the field specification is to be repeated.
s = scale .factor·
8-89

A,B,D,E,F,G,H,I,L,P,T,X = type of conversion
w= non-zero, unsigned integer constant specifying width of
field. Field width must be large enough to provide for all
characters (including decimal point, sign, and exponent)
necessary to constitute the data value plus any blank
characters needed to separate it from other data values.
The data value within a field is right justified; if the value
is too large for the field, the field is filled with asterisks .
. .d

unsigned integer constant (may be zero) specifying number of digits to the right of the decimal point or, for G
conversion, the number of significant digits.

Field specifications must be written in the same sequence as the
data record being described, except when the T specification is
used.
A FORMAT statement may describe one or more records, each
of which can consist of one or more field specifications. The character "/" (slash) indicates that a new 'record is being described.
For example, the statement:
FORMAT

(Gle.2/15~2F8.4)

is equivalent to

for the first record, and:

for the second record. Field specifications are separated by commas as shown above. The separating comma may be omitted when
a slash is used. When n slashes appear at the end or beginning of a
format, n blank 'records may be written on output or n records
skipped on input. When n slashes appear in the middle of a format,
n-1 blank records are written or n-1 records skipped.
For example,

8-90

· where / / / indicates that two records are to be skipped
A group of field specifications may be repeated by enclosing the
group in parentheses and preceding. the enclosed group ~ith a
repetition number. For example,
FORMAT (3(.15" 010.3»

Both the slash and the closing parenthesis at the end of the format
indicate the termination of a record. If the list of an input/output
statement dictates that transmission of data is to continue after the
closing parentheses of the format is reached, the format is repeated
starting with that group repeat specification terminated by the last
preceding right parenthesis, or, if none exists, then to the first left
parenthesis of the format specification. Thus, the statement:
FORMAT (F7.2,3(I2,2(I3,E9.3)17))
t

group repeat
specification

r:erminator
Last preceding
right parenthesis

causes
(F7.2,3(I2,2(I3,E9.3)I7)
to be used on the first record, and the format
3(I2,2(I3,E9.3)I7)
~

to be used on succeeding records.
As a further example, consider the statement:
FO RMAT (F7. 2 ( 2 ( E 1 5. 5" E 1 5. 4)" I7) )

The first record has the format
(F7.2)
and successive recor~s have the format
(2(E15.5,E15.4),I7)
FORMAT statements may be placed anywhere within ·the
executable portion of the source program. Unless the FORMAT
statement contains only Hollerith data for direct input! output
transmission, it will be used in conjunction with the list of a data
8-91

transmission statement. Because FORMAT statements are refer- .
enced by READ or WRITE statements, each FORMAT statement
must have a statement number.
The ASCII character string comprising a format specification
may be stored as an array. Input/output statements may then refer
to the format by giving the array name, rather than the statement
number of a FORMAT statement. The stored format has the
same form as a FORMAT statement excluding the word "FORNIAT". The enclosing parentheses are required.
Field specifications in a FORMAT statement should be of the.
same type as the corresponding items in the I/O list; that is,
integer quantities require integer (I) conversion, etc. There are
three types of field specifications: numeric, logical, and alphanumeric (including Hollerith). In addition, a blank field, description
may be given to skip portions of an input record or to embed
blanks within an output record.
Numeric Fields
. Numeric fields are specified by one-letter codes (B, D, E, F, G
or I) which designate the type of conversion to be performed. Two
parameters may appear in a numeric field description, depending
on the field type. These are: an integer (w) specifying the field
width (which may be greater than required to provide for blank
rnl11mn<;: hptmppn
nnmhpT<;:)
..
_~~~~~~~~v

~-~

--~~

~~_£~~~_£v,

~nn
•• - ~n lntpoPT
~

-.~

.'~'-e>-~

fn)
nnm'-I <;:nf'rlfvlno
vr----,l---e> thp
.--- ------

ber of decimal places to the right of the decimal point or, for G
conversion, the number of significant digits. Decimal points are
not permitted in I conversion. (For B, D, E, F and G input, the
position of the decimal point, if present in the external field, takes
precedence over the value of d in the format.) Conversion codes
and the corresponding internal and external forms of the numbers
are listed in Table 8-14. Numeric fields are right justified with the
addition of leading spaces and, if necessary, trailing zeroes.
Single precision I/O specifications will transfer a maximum of
six decimal digits of accurate data. Double pretcision I/O specifications will transfer a maximum of 15 decimal digits of accurate data.

8-92

Table 8-14

Numeric Field Codes

Conversion
Code

Internal
Form

External
Input Form

External
Output Form

Double·
precision

Decimal number
with or without a
decimal point or
exponent field.

Decimal number
with a.D exponent
field and a decimal
point.

Double
precision

Same as D.

Same as F.

Real

Decimal number
with or without a
decimal point or
exponent field.

Decimal number
and an E exponent
with a decimal point
field.

Real

Decimal number
with or without a
decimal point or
exponent field.

Decimal number
with a decimal point.

Real

Decimal number
with or without a
decimal point or
exponent field.

Decimal number
with a decimal point
and with or without
an E exponent field.

Integer

Decimal number
without a decimal
point or exponent.

The allowable numeric field specification forms are:

1.
2 ..
3.
4.
5.
6.

Bw.a

Dw.d
Ew.d
Fw.d

Iw
Gw.d
For example:

could be used to output the line
bb32bbbb-17.60bbO.5962547681E+03
8-93.

on the output listing. (The letter b represents a blank or space.)
Since there is no carriage control character in the statement, the
first character is interpreted as a carriage control character a~d is
not printed.
Complex quantities are transmitted as two independent real
quantities. The format specification consists of two successive real
specifications or one repeated real specification. For instance, the
statement

could be used in the transmission of three complex quantities.
The G format is the general format code that is used to transmit
data having a specific number of significant figures, no matter what
the magnitude of the number. This format is intended to allow use
of the simplest output format which can express the desired value
in the space allowed. The rules for input are the same as for E
format.
The form of the output conversion (E or F) is a function of the
magnitude of the data being converted. Table 8-15 shows the
magnitude of the internal data, M, and the resulting method of
con verSIOn.
Table 8-15 "Conversion Under G Format
Magniiude of Daia

Resulting Conversion

O.l<=Mm2.
Cease program compilation; equivalent
to STOP In main
program or RETURN in subprogram.

. END FILEu

Writes END-OFFILE character in
file u.

EQUIVALENCE

EQUIVALENCE (vl,v2, ... ,),

Identifies same storage location for variables within parentheses.

EXTERNAL

EXTERNAL subprog,...

Declares a. subprogram for use by
other subprograms.

FORMAT

FORMAT (spec1 ,spec2, .. ./ ... )

Specifies conversions
between internal and
external representation .of data.

FUNCTION

FUNCTION name (al ... )

Indicates an external
function definition.
Transfers control to:

GO TO
(1) GO TO n

(1) statement n

(2) GO TO (nl, ... ,nk),e

(2) to statement n1

8-122

if e = 1,
to statement nk
if e==k.

Table 8-17

FORmAN IV Statement Suinmary (Cont.)

Effect

Form

Statement

(3) GO TO v
GO TO v(nl, ... ,nk)
GO TO v,(n 1,... ,nk)

(3) Transfers control
to statement
number assigned
to v optionally
checking that v
is assigned one
of the labels nl
.... nk.

IF (arith expr)nl ,n2,n3

Transfers control to
nl if expr <0, n2 if
expr 0, n3 if expr

>0.

IF (logicalexpr) statement

Executes statement if
expression has value
.TRUE., otherwise
executes next statement in sequence.

Logical

V=E

Value of expression
E is assigned to variable V.

PAUSE

PAUSE
PAUSE number

Program execution
interrupted and
number printed, if
given.

READ

READ (u,f) list
READ (u,f)
READ (u) list
READ (u)
READ (a'r) list

Reads a' record from
a peripheral device'
according to specifications given in the
arguments of the
statement.

RETURN

Returns control from
a subprogram to the
calling program.

REWIND

REWINDu

Repositions designated unit to the beginning of the file.

STOP

Terminate
execution.

'8-123

program

Table 8-17
Statement

FORTRAN IV Statement Summary (Cont.)
. Form

Effect

SUBROUTINE SUBROUTINE name(al, ... )

Declares name to be
a subroutine subprogram and aI, ... , if
supplied, as dummy
arguments.

type

type vl,v2,v3, ...

Where the variables
vn are assigned the
indicated type, i.e.,
Real, Integer, etc.

WRITE

WRITE (u,f) list
WRITE (u,f)
WRITE (u) list
WRITE (u)
WRITE (a'r) list

Writes a record to a
peripheral device according to specifications given in the arguments of the statement.

PAPER TAPE LOADING INSTRUCTIONS
The FORTRAN IV system may be loaded from paper. tape
using OS/8 EPIC. Of the nine files that make up the system, the
following eight:
F4.SV
PASS2.SV
PASS20.SV
PASS3.SV
RALF.SV
LOAD.SV
FRTS.SV
LIBRA.SV
are on separate paper tapes, as indicated, and may be read in any
order. After these tapes have been read, the six tapes that comprise
the library (FORLIB.RL) must be read in ascending numerical
order. A typical procedure might be:
Load OS/8 EPIC .

• R EPIC

Designate the device on which
the new FORTRAN IV system will be built and mount
the F4.SV tape in the reader.

8-124

*/Y

Mount the P ASS2.SV tape in
the reader.
Mount the P ASS20.SV tape
in the reader.
Mount the PASS3.SV tape in
the reader. .
Mount the RALF.SV tape in
the reader.
Mount the LOAD.SV tape in
the reader.
,Mount the FRTS.SV tape in
the reader.
Mount the LIBRA.SV tape in
the reader.
Mount the first FORLIB.RL
tape in the reader.
Continue to read the six
FORLIB.RL paper tapes in
increasing numerical order.

*/Y
*/Y
*/Y
*/Y'
*/Y
*/Y
*/Y

END OF' TAPE ENTER NEXT
END OF' TAPE ENTER NEXT
END OF' TAPE ENTER NEXT
END OF' TAPE ENTER NEXT
END OF' TAPE ENTER NEXT
* tC
PDP-12 users who create OSj8 FORTRAN IV systems from
paper tape and ,require the real-time capabilities of this system
mu'st assemble the RALF modules containing REALTM, ADB,
ADC, PLOT, CLRPLT, and SCALE; then add these modules to
the system library. The routines' to be assembled 'and inserted are
contained on three paper tapes. A typical procedure might be as
follows .
• 4SSIGN SYS DEV
.R PI?
*DEV:rILEl.R4c

':l

'-'

Ll,.

r=-

'--

G
H
I
J
K
L
M
N
0
P

8
9
10
/1

--'- J.

12
1

43
44
45

'"1

c:
5
'-.J

45
47
Ll.8-

53
,- 4

r--1

~.,j

55
55

1-4

:If

8
9

R
S
T

"IT
I

Multiple Characters
Any of the above characters, except pi, in' Table· 8-20 can be
combined in any order to print titles, legends, labels or the like
using a multiple character call:

CALL SYMBOL (X,Y,H,T,A,N)
8-133

where:

x, Y

is the coordinate in inches of the lower left corner of the
first character to be printed.

is the height in inches of each character. Because characters are considered to be on a 7x7 grid, a' multiple of
7 times the increment size is recommended (i.e., a mini/mum of .07 for .01 increment plotters and .035 for .905
increment plotters). The actual plotting grid occupied by
any character, is 6x4, the remaining 1x3 being used for
spacing between characters.

is the text in A or Hollerith format.

is the angle at which the text is to be printed and is
specified in degrees from the X axis.

is the number (positive integer) of characters to be
plotted and must be greater than 0 and equal to or less
than the number of characters in T.

For example:
DIMENSION TEXT(~)
OAT. TEXT/'TEXT EXAMP~E'I
CALL PLOTSC.01,l)
CALL X.PLOT~0,0,.j)
CALL SYMROL(1,1,.il,TEXT,0,12)
CALL PLEXIT
END

will, on a non-PDP8/e machine with a .01 increment plotter,
initialize the origin point at the current pen location, move from
there to 1,1 and print the 12 characters in TEXT, namely TEXT
EXAMPLE, in letters .21 inches high at 0 degrees from the X axis,
i.e., parallel to the side of the plotter.
The program above is equivalent to:
CALL
CALI.
CALL
CALL

PLOTSC.01,l)
XYPLOT(0,0,.3)
SYM80LC1,1,.cl,12 HTEXT fXAMPLf,0,li)
PLfXIT

END

8-134

Note that the character pi can only be plotted by a single character
command because it has no Hollerith representation.
Single Characters

Two types of single characters can be plotted:
1. Characters from the available character set listed in Table 8-20.
2. Special symbols used to denote a data point. The available
special symbols are listed in Table 8-19. Their use differs-from
other characters in that their starting and terminating point is
the center of the character, "not the lower left corner. These
_ symbols occupy a 4x4 grid.
The call is:
CALL SYMBOL (X,Y,H,I,A,N)
where:

x, Y

is the X, Y coordinate of the lower left corner of a regular
character, including pi, or the center for a special symbol..

is the height in inches of the symbol and sh~mld be 7 times
the increment size for a regular character and 4 times the
increment size for a special symbol (i.e., .02 or .04
minimum depending on the plotter) .

is in the range 1-63 for regular characters (Table 8-20)
and 100-117 for special symbols (Table 8-19). If a nonacceptable value is used, SYMBOL prints a space in its
place.

is the angle in degrees from the X axis at which the
character is printed.

is-l if the pen is to be up during the move to X,Y or-2
if the pen is to be down during the move to X, Y.

For example:
C4L~

PLOTSC.01,1)

CALL

XY~LOTC0,0,~l)

CAL~

SYMBOL(.b,~,.35,1,180,~1)

CALL PLEXIT
END

8-135

This will plot the letter A .35" tall at 180 degrees to the X axis
on a PDP-8/B. The pen will be up during the move from 0,0 to
-6,2, the lower left comer of the A.
CALL PLOTSC.01,1'

CALL SVMBOL(1,4,.20,100,270,.l)
CALL. PLtXIT
END

,This will plot the first special character .2 inches tall centered at
point 1,4 at an angle of 270 degrees to the X axis on a non-PDP-8/E.
The move of the pen from its current location to the start of the
character (1,4) will be visible.
NUMBER
To facilitate handling internal format data (floating point) the
NUMBER routine is included. It plots floating point numbers in a
format similar to FORTRAN IV F format. One number at a time
is plotted using the call:
CALL NUMBER (X,Y,H,Z,A,N)
where:
X,Y

is the coordinate of the lower left corner of the first character of the number.

is the height of each character, preferably 7 times increment size (each number is considered to occupy a 7x7
grid) .

is the number to be plotted. It may be a real or integer
number.

is the angle to the X axis at which to plot the number.

is an integer that controls the format of the number Z as
follows:
Value of N

Result

Z is truncated and plotted as an integer

followed by a decimal point
-1

Z is truncated and plotted as an integer

8-136

· Value of N

.r..-

Result

=>1

N digits to the right of the decimal point
are plotted. The number is rounded based
on the value of the (N +1 ) th digit.

<-1

N -1 digits are truncated from the integer
portion of the number.

Note that the accuracy of the number printed cannot exceed 6
digits, however at the user's discretion he may plot up to 19 digits
with an expected loss of accuracy. If a bad digit is found in Z, that
digit defaults to O. For Z less than one a leading zero is included.
For example:
CALL
C-0

PLOTS(.0~5,lJ

AII':198,678
~

CALL XY~LUT(0,0,w3)
CALL NUM8E;:R(1,t,.07,A,C,0)
C~LL

CALL

NUMB~R(1,2,.07,A,C,·1)
NUM8ER(1,3,.1~,A,C_·2'

~ALL

NUMB~R(1,4,.1~,A,C,2)

CAU.

PLfXIT

E'ND

Statis~ically

the above program will be plotted as follows:

,Starting
Location

Height
(Inches)

Number
Plotted

Angle

1,1
1,2
1,3
1,4

.07 * 6/7
.07 * 6/7
.14 * 6/7
.14 * 6/7

198.
198
19
198.68

0
0
0
0

If the number (Z) is out of range of the acceptable number of

characters including minus sign and decimal point, the message:
NUMeE~

OF DIGITS

~OT

1~19

is printed on the console device (unit 0) .

8-137

PSCALE
For many applications, the data to be plotted is scattered irregularly across the total range and in a manner not neatly related to
unit (inch) increments. To permit plotting data in a finite (user
specified) length graph with labelled axis, the PSCALE routine is
invoked to establish two critical plotting parameters-starting value
and scaling increment. The starting value can be positive or negative and a maximum or minimum. It is the value printed at the
starting axis annotation. The scaling increment is the delta value
between succeeding axis annotations and is the number of data units
per inch of plot, adjusted to 1,2,4,5 or 8 * 10iN. These two values
are used by the AXIS and LINE routines to produce a properly
annotated axis and a graph whose data includes all points in a user
specified length. PSCALE does no plotting; its use is in conjunction
with AXIS and/or LINE. It is generally called twice-once for X
(abscissa) values and once for Y (ordinate) values.
The call is:
CALL PSCALE(A,L,N,I)
where:
A

is the array containing the data to be plotted. This array
must have extra locations at the end in which PSCALE can
.., .. __ ..... 4-1..._

,.,4-",_4-! _ _

.:IlVL~

M-dLllUt;

U11;,

... "' ..... 1 ...........

~_...l

v dIU\; dl1U

,._ ...... 1= __ ! __ ........ ____ L

_ _ _ "' ..

~~dHl1t; HI~l

i:t~

C:111C:l1l,

_1 .... ! __ ..l

C:.AJJli:tlllC:U

below.
L

is the length (integer) of the axis that the data is to cover.
L must be greater than 'or equal to 1.

is the number of data values in A to be considered. N must
be greater than or equal to 1.

is the increment between data values to be considered. The
first value examined is always A(1), the next is A(1+ I).
If I is positive, the calculated starting value will be a
minimum value.
If I is negative, the calculated starting value will be a
maximum and the scaling increment will be negative.

The calculated starting value is stored at A(N*J+l), the scaling
increment is stored at A(N*J+J+l) where J is the absolute value
8-138

of 1. Be sure to dimension A to a length sufficient to include ,these
locations. Consider the data array ARRAY:
Element

Contents
.S

1
2
3
4
S
6
7

1
.9
.9
3.4
3.2
3.9
4.S
S.2
S.9

9
10
The statement:
CALL PSCALE (ARRAY,S,S,2)

PSCALE will use ARRAY(l), ARRAY(3), ARRAYCS),
ARRAY (7), and ARRAY (9) in determining the starting value
and scaling increment. For the example above, the scaling increment is 2.0 and the starting value is O.
If an axis length of less than one is supplied, the message:
AXIS LENGTH <1

is printed on device O. If all
the message:

~lements

of the data array are the same,

MAX PT • MIN PT

is printed.
AXIS
For most graphs, the· presence of labelled axes adds significantly
to interpreting the data. The AXIS routine draws an axis with
labelled tic marks at one inch intervals and a title or other annotation parallel and centered to the axis. AXIS must be called
separately for an X and a Y axis. The starting value and scaling
8-139

increment discussed in PSCALE must have been determined previously to calling AXIS.
The call is:
CALL AXIS (X,Y,T,N,L,A,F,D)
where:
X, Yare the coordinates of the start of the axis, in inches,
relative to the current origin .. Often when two axes are
required, X and Yare 0 for both calls. It is suggested that
the physical origin of the axis be at least 1Iz~' in from any
edge of the plotter, as annotation will require that space.
This position becomes the new origin for subsequent
plotting.
T

is the title in Hollerith format. It is printed .14 inches tall
(dependent on existing user specified plotting factors)
and centered along the axis. If the scaling increment is
greater than 99 or less than .01, the notation *10 is added
at the end of the title.

is the number of characters in the title (T) to be printed-.
Its sign is used to specify on which side of the axis the
tic marks and their labels are to be: positive means the
positive (counter clockwise) side of the axis, negative is
the negative or clockwise side, Positive'labeling is generally used for Y axes and negative for X axes.

is the length of the axis in inches. Note that this value
should not exceed the width of the plotter for an axis in
that direction. The absolute value of L is used.

is the angle in degrees at which the axis is to be drawn. X
axes are generally at 0 and Y axes at 90.

is the starting value and will be used as the annotation for
the first tic mark. The annotations include two significant places after the decimal point. This value may be
determined by PSCALE or supplied by the. user. If
calculated by PSCALE, F must be the appropriate array
element. If the user chooses to calculate his own starting
value and scaling increment, be aware that a tiny F and
large D or large F and tiny D do not produce a meaningful graph ..
8-140

is the scaling increment between tic mark annotations. It
may be determined by PSCALE or by the user. If calculated by PSCALE, D must be the appropriate array
element.

For best results axes should be drawn at multiples of 45 degrees
(including 0). AXIS uses the routine NUMBER.
LINE
Pairs of data points in two arrays can be combined by LINE and
. plotted according to user specified parameters. Points to be plotted
can be indicated by a special symbol and can also be connected by
a continuous line. LINE requires a starting value and scaling increment for each array such as those produced by PSCALE.
The call to LINE is:
CALL LINE (A,B,N,I,L,J)
where:
A

is the name of the array whose values are to be the abscissa
values.

is the name of the array whose values are to be the ordinate
values.
For A and B, the (N*I+ 1 )th element must contain its
starting value and the (N*I+I+1)th element must contain
its scaling increment, as supplied by the user or PSCALE.

is the number of points in each array to be plotted. The
same number of points is' taken from each array.

is the increment at which the data in A and B' is collected,
i.e., every ph point is plotted. I must be greater than O.

determines the manner in which the line is plotted, as
follows:
If L is positive, each point is connected by a line and a
special symbol is plotted at each point.
If L is 0, each point is connected by a line, and no symbols
are drawn.
If L is negative, no connecting lines are plotted. Each point
is indicated by a special symbol.
8-141

is a value between 100 and 117 according to Table 8-19
indicating the special symbol to be used in the plot.

The pen should be located at the logical 0,0 position of the
graph when a call to LINE is issued. If the preceding plot operation was drawing an axis in the usual manner, the pen should be properly positioned. If I or N is less than or equal to 0, the LINE
routine returns without plotting.
PLEXIT
In order to permit the plotting routines to finish co~pletely, the
routine PLEXIT must be called once when all' plotting commands.
have been issued. PLEXIT does a final pen up operation.
Implementing the Plotter Routines
GETT.ING STARTED
In order for the plotter to interface properly to OS/8 FORTRAN IV, the following patch must be made to the file FRTS.SV.
It adds a clear plotter flag lOT to the run-time device initialization
chain. The sequence is:

.GE'T SYSIFRTS,S'v

.OOT
/ User tvoes 4020 I Response
/ at terminal is 7000.
IUser types 6502

4020/7000 &502

IType-CTRL/C to exit ODT

.SA SYS.FRTS.SV

/ Assumes FRTS.SV on SYS
I Device

ADDING THE PLOTTING ROUTINES
The FORTRAN plotting routines are supplied as relocatable
RALF (.RL) modules that can either be added to the FORTRAN
library (FORLIB.RL) or specifi~d explicitly to the loader. To add
the files to FORLIB.RL, the procedure is:
.R L.ISlh
*PL.OTL.Bt3lc~ORLIA.RL/Z.~0

*PLOTLBcXYPLOT.RL,AXIS,RL,PSCALE.RL,LINE.RL,NU M8£R,RL
*fC

8-142

PLOTLB may then be used by specifying it as a library to the
loader or it may be copied using PIP so that no additional loader
specifications are required. If you choose not to add the plotting
modules to the librarY,and prefer to specify them to the loader, it
is suggest.ed that only the modules required by the FORTRAN
program be specified in order not to waste space. 111: general tht:
user employing elaborate overlay schemes will not want these in
his library, while the user with shorter programs will.
The core requirements to the nearest hundredth location of the
files are:
XYPLOT

SYMBOL
symbol table
NUMBER
PSCALE
AXIS·
LINE

1000 locations in field
1 and 700 elsewhere
(includes F ACTOR,PLOTS,
WHERE, and PLEXIT).
500
700 (regular and special
characters)
1300
1000
1500 (requires NUMBER)
600

Note that the routines PLOTS, XYPLOT, FACTOR, WHERE,
PLEXIT, SYMBOL and the symbol table, including the code in
field one, are all loaded if anyone of those routines is called.
Loading the Plotter Routines from Papertape
If the relocatable plotter routines are supplied on paper tape, .
they must be loaded into mass storage using the program EP~C.
Place each tape in the reader before typing the response to the
asterisk. The sequence is:

EPIC
I M.ount XYPLOT.RL

*/0$
./y

IMount
/ Mount
/ Mount
I Mount

./V
./Y
·/Y

*1'C

The above puts the files on device SYS.
8-143

NUMBER.RL
AXIS.RL
PSCALE.RL
LINE.RL

Examples
An example combining several of the commands is shown below.
This program requests user input of text and then plots it as a
spiral.

100
2~0

150

250

DIMENSION NAMEC]')
!TTh"
W~ITE(ITTY,100)· .
FORM'TC!X,~TYP! IN T!XTt]1 CHA~ACTfR MAX)',
REAOCITTV,200)NAME
FORHATC10Al)
WRITE(ITTY,150)
~ORM.T(lX,·HOW "AN' CHARACTERS DID YOU T"! IN")
ef.AO CITT\', 250) NN
FORMATCI2)
CAL~ PLOTSC,01,1)
CALL XYPLOT(0,-30,-3)
CALL XYPLOT(10,10,-3)
IUD-3
SIZE- .1225*fUO
SPIR-,QQ5
CONV-U0.I3,1415

ANG·0
BUll'al.5'701
00 300 J-l,NN

300
380

CALL SYM80~((J-l-~N)*SIZE,RAD,SI%E,NAM!CJ),ANG,1)
DO 400 J.l,NN
T.Z*ATANCSIZE/(2.*RAO»
ANG.ANr;-T*CONV

h1UO*C08 (BANG)
Y.IUD*sIN (BANG)
BANG.IUNG-T
UO.RAD*SPIR
S IlE •• 1225 *R-A 0

400

CAL~

500

IF(SIZE-.07lS00,500,380
CAL~ PLEXIT
ElliO

S'MBOLeX,Y,SIZE,NAHECJl,AHG,l)
.

The actual plotter output is shown in Figure 8-6.

8-144

>
H
Z
IT:
~

"'o"

(f)

Figure 8-6· Spiral Plotter Example·

8-145

The next example plots a histogram.

DIMENSION X(50),Y(50),SALtS(ll',TXT(T~
DATA SALES/20,30,3i,40,50,~0,95,q0,40,30,le,151
DATA TXT/~AIR CQNDITIONER SALES !ACM MONTH O~ 19T2 ' I
CALL PLOTS(.01,0)
CALL XYPLOT(0,-30,-3)
CALL XYPLOTC1,l,-3)
00

J.l,12

I).0
YCJ+l)·SALESCJ)
VCI+2),SAL.ES(J)
Y(

V(t+3)'~.
V('i~'·0.

y(~q'·tro.

DO 10 1'1,48,14
)((I)'I/4+.75
X(%+1).)((I)
X0+2) -1/4+.25
)((I+3).X(I+2)
X(49)-0.
X(511)'1,
CALL. AXIS(0,0,'MONTH',.S,13,0,0,1)
CALL. AXIS(0,0,'AIR CONDITIONERS CX100)·,Z3,10,.0,0,10)
CALL LINE(X,Y,48,l,0,0)
CALL. SVM~OL(1,10.5,.25,TXT,0,40)
CALL XyPLOTC12,0,3)
CALL. PL!::)! IT

ENO

The actual plotter output is shown in Figure 8-7.

8-146

.,..,

!
I
LL

I-

I
U

cr:

W
..
...

(j)

W
-.J

cr:

(j)

(k:

W
Z

I-

U
(k:

cr:
1

00°00];

,00°06

00°08

00°,0L.

Figure 8-7

00°0~

00°09

00°0S

l00J;Xl

S~3NOIIIONOJ

00°0E

00°02

~I~,

Histogram Plotter Example

8-147

00°0];

0
:>::

8-148

a
character codes
ASCII 1 Character Set

Character
A
B
C
D
E
F
G
H
I
J

K
L
M
N
0
P

Q
R
S
T
U
V
W
X
Y
Z
0
1
~

3
4
5
6
7
8
9

8-Bit
Octal
301'
302
303
304
305
306
307
310
311
312
313
314
315
316
317
320
321
322
323
324
325
326
327
330
331
332
260
261
262
263
264
265
266
267
270
271

6-Bit
Octal
01
02
03
04
05
06
07
10
11
12
13
14
1~

16
17
20
21
22
23
24
25
26
27
30
31
32
60
61
62
63
64
65
66
-67
70
71

Decimal
Equivalent
(AI Format)

Character

96
160
.#
224
288
$
352
%
416
&
480
·544
(
608
)
672
*
736
+
,
800
864
928
992
/
1056
ll20
;
1184
<
1248
1312
>
1376 •
?
1440
@
1504
[
1568
1632
]
1696
t( /\)2
«_)2
.....:..992
...,...928
Leader/Trailer
LINE FEED
-864
-800 Carriage RETURN
SPACE
-736
RUBOUT
-672
Blank
-608
BELL
-544
TAB
·-480
FORM
-416
-==

8-Bit
Octal
241
242
243
244
245
246
247
250
251
252
253
254
255
256
257
272
273
274
275
276
277
300
333
334
335
336
337
200
212
215
240
377
000
207
211
214

Decimal
6-Bit
Equivalent
Octal (AI Format)
41
42
43
44
45
46
47
50
51
52
53
54
55
56
57
.72
73
74
75
76
77

.A-l

~224

33
34
35
36
37

-160
-96
-32
32
1760
1824
1888
1952
2016

-2016

An abbreviation for American Standard Code for Information Interchange.

2 The character in parentheses is printed on some Teletypes .

-1952
-1888
-1824
-1760
-1696
-1632
-1568
-1504
-1440
-1376
-1312
-1248
-1184
-1120
-1056
-352
-288

A-2

b·
.loading· procedures

Initializing the System
Before using the computer system, it is good practice to initialize
all units. To initialize the system, ensure that all switches and controls are as. specified below.
t

1. Mai!l power cord is properly plugged in.
2. Terminal is turned OFF.
3. Low-speed punch is OFF.
4. Low-speed reader is set to FREE.
S. Computer POWER key is ON.
6. PANEL LOCK is unlocked.
7. Console switches are set to O.
8. SING STEP is not set.
9. High-speed punch is OFF.
10. DECtape REMOTE lamps OFF.
The system is now initialized and ready for your use.

Loaders
READ-IN MODE (RIM) LOADER
. When a computer in the PDP-8 series is first received, it is nothing more than a piece of hardware; its core memory is completely
demagnetized. The computer "knows" absolutely !l0thing, not even
how to receive input. However, the programmer can manually
load data directly into core using the console switches.
The RIM Loader is the very first program loaded into the computer, and it is loaded by the programmer using the console

B-1

switches. The RIM Loader instructs the computer to receive and
store, in core, data punched on paper tape in RIM coded format
(RIM Loader is used to load the BIN Loader described below.)
There are two RIM loader programs: one is used when the input
is to be from the low-speed paper tape reader, and the other is used
when input is to -be from the high-speed paper tape reader. The
locations and corresponding instructions for the low-speed reader
are listed in Table B-1. The high-speed reader RIM loader is listed
in Table B-2.
For each step in the table, place each of the PDP-8/E console
SWITCH REGISTER switches numbered 0 to 11 either in the up
position if the corresponding table entry is 1, or in the down position if the corresponding table entry is O. When a1112 switches have
been set to correspond to a line in the table, follow the instructions
- in the right hand column and proceed to the next line. The tables
also include octal values of the binary switch settings for the benefit
of users familiar with octal numbers.
Table B·l RIM Loader for Low.Speed Reader

1 0000
2 7756
3 6032
4 6031
5 5357
6 6036
7 7106
8 7006
9 7510
10 5357
11 7006
12 6031
13 5367
14 603415 7420
16 3776
17 3376
18 5356

And Then

Switch Register
Setting

Step Octal
# Values

012 345 678 91011
000 000 000 000
111

111

101

110

110
110
101
110
111
111
111
101
111
110
101
110
111
011
011
101

000
000
011
000
001
000
101
011
000
000
011

011
011
101
011

010
001
111
110
110
110
000
111
110
001
111
100
000
110
110
110

000

000
001
101
000
011
110
000 011
100 010
111 111
011 111
011 101

B-2

press EXTD ADDR LOAD
press i\DDR LOAD
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
liftDEP key
lift DEP key
lift DEP key
lift DEP key
liftDEP key

Table B-2 RIM Loader for High-Speed Reader
Switch Register
Setting

Step· Octal
# Values

1
2
3
4
5
6
7
8
9
10
11
12
13

14
15
16
17
18

0000
7756
6014
6011
5357
6016
7106
7006
7510
5374
7006
6011
5367
6016
7420
3776
3376
5357

012
000
111
110
110
101
110
111
111
111
101
111
110
101
110
111
011
011
101

345
000
111
000
000
011
000
001
--

DOD
101
011
000
000
011
000
100
111
011
011

678
000
101
001
001
101
001
000
000
001
111
000
001
110
001
010
111
111
101

And Then

91011
000
110
100
001

ill

110
110
110
000
100
110

OOt
111
110
000
110
110
111

press EXTD ADDR LOAD
press ADDR LOAD
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key
lift DEP key

After RIM has b~en loaded, it is good programming practice to
- verify that all instructions were stored properly. This can be done
by performing the steps illustrated in Figure B-2, which also
shows how to correct an incorrectly stored instruction.
- When loaded, the RIM Loader occupies absolute locations 7756
through 7776.

B-3

INITIALIZE

SET SWITCHES 6-8

TO DESIRED
IIJSTRUCTION FIELD*

*DECTAPE USERS SHOULD
LOAD RIM INTO fiELD 0

Figure B-1

Loading the RIM Loader

B-4

SET SWITCHES
6-8 TO FIELD IN
WHICH RIM HAS
BEEN LOADED

Figure B·2

Checking the RIM Loader

BINARY (BIN) LOADERThe BIN Loader is a short utility program which, when in core,
instructs the computer to read binary-coded data punched on paper
tape and store it in core memory. BIN is used primarily to load the
programs furnished in the software package (excluding the loaders
and certain subroutines.) and the programmer's binary tapes.
BIN is furnished to the programmer on pU,nched paper tape in
RIM-coded format. Therefore, RIM must be in core before BIN
can be loaded. Figure B-3 illustrates the steps necessary to properly 10ad,BIN. And when loading, the input device (low- or highspeed reader) must be that which was selected when loading RIM.
B-5

o----.c

LOAD RIM

}- -

~ -1 See FI_, C2-1,C2-21

SET SWtTCIES
6-8 TO FIELD

WHICH CONTAINS

RIM

SET SWITCHES

9-11 TO FIELD IN
WHICH BIN IS

SET SWITCHES
6-8 TO FIELD
BIN WAS LOADED
INTO

Figure B-3

Loading the BIN Loader

B-6

When stored in core, BIN resides on the last page' of core, occupying absolute locations 7625 through 7752 and 7777.
BIN was purposely placed on the last page of core so that it
would always be available for use-the programs in DEC's software p-ackage do not use the last page of core (excluding the Disk
Monitor) . The programmer must be aware that if he writes a
program which uses the last page of core, BIN will be wiped out when that program· runs on the computer. When this
happens, the programmer must load RIM. and then BIN before .
he can load another binary tape.
Binary tapes to be lo~ded should be started on the leader-trailer
code (Code 200), otherwise zeros may be loaded into core, destroy_
ing previous instructions.
Figure B-4 illustrates the procedure for loading binary tapes
into core.

B-7

Figure B-4 Loading a Binary Tape Using BIN

B-8

ooo~

permanent symbol
table"
The following are the elements of the PDP-8' instruction, set
found in the SABR permanent s~bol table~ These instructions
are already defined within the computer. For additional informa:-'
tion on these instructions and for a .description of the symbols
, used when programming other, optional, I/O devices, see the Small
Computer Handbook, available from .the DEC SOftware Distribution Center.
INSTRUCTION CODES
Mnemonic Code

Operation

Time Cu.sec.)1

Memory Reference Instructions
AND
0000
Logical AND
TAD
1000
Two's complement add
ISZ
2000
Increment and skip if zero
INC
2000
Nonskip ISZ
DCA
3000
Depositaild clear AC
JMS
4000
Jump to subroutine
JMP
5000
Jump'

2.6
2.6
2.6
2.6
2.6
2.6
1.2
Sequence

cycle2 )

Group 1 Operate Microinstructions (1
NOP
7000
No operation
IAC
Increment AC
7001
RAL
7004
Rotate AC and link
RTL
7006
Rotate AC and link
RAR
Rotate AC and link
7010
RTR
Rotate AC and link
7012
CML
Complemented link
7020
CMA
Complement AC
7040
CLL
Clear link
7100
Clear AC
CLA
7200
Times are representative of the PDP-8/E.
2 1 cycle is equal to 1.2 microseconds.,
1

C-l

,
left one
left two
right one
right two

-3
4
4
4
4
2
2
1
1

Mnemonic Code

Operation

Sequence

Group 2 Operate Microinstructions (1 cycle)
Halts the computer
7402
HLT
Inclusive OR SR with AC
7404
OSR
SKP
Skip unconditionally
7410
Skip on nonzero link
7420
SNL
Skip on zero link
7430
SZL
Skip on zero AC
7440
SZA
Skip on nonzero AC
7450
SNA
SMA
Skip on minus AC
7500
Skip on positive AC (zero is positive
SPA
7510
Combined Operate Microinstructions
CIA
7041
Complement and increment AC
STL
7120
Sent link to 1
STA
7240
Set AC to - 1
Internal lOT Microinstructions
ION
6001
Turn interrupt processor on
IOF
6002
Disable interrupt processor
Keyboard/Reader (1 cycle)
KSF
6031
Skip on keyboard/ reader flag
6036
Clear AC, read keyboard buffer
KRB
( dynamic), clear keyboard flags
Telenrin
PlIne
(1 eve le )
- - - - r - --"fer
- -. I -- -" h....
J

TSF
TLS

6041
6046

Skip on teleprinter/pu~ch flag
Load teleprinter/punch, print, and clear
teleprinter/punch flag

High Speed Reader-Type PR8/E (1 cycle)
RSF
6011
Skip on reader flag
RRB
6012
Read reader buffer and clear reader flag
RFC
6014
Clear flag and buffer and fetch
character
High Speed Punch-Type PPS/E (1 cycle)
PSF
6021
Skip on punch flag
PLS
6026
Clear flag and buffer, load buffer and
punch character

C-2

3
3
1
1
1

1
1

1
1
2,3
1,2
2

PSEUDO· OPERATORS
The following is a list of the SABR assembler pseudo-operators.
ABSYM

ACH
ACM
ACL
ARG

BLOCK
CALL
COMMN

CPAGE
DECIM
DUMMY
EAP
END
ENTRY

FORTR
I

LAP
OCTAL
OPDEF
PAGE
PAUSE
REORG
RETRN
SKPDF
TEXT

C-3

C-4

d
osja
demonstration run

The following pages present a demonstration of the use of th~
OS/8 system. The terminal output is set off by letters (to its left)
which correspond to the t~xtual explanations on the fa~ing page.
This demonstration illustrates the procedures involved and use of
many of the OS/8 system programs and commands.

D-l

A The eel., comma..'ld is used to zero the DECtape on Unit 1,
specifying one additional information word in the directory.
B

The user then types the DATE command to set the system date
to April 10, 1974.

C The ASSIGN command is used to give DTA1 the additional
name IN. All subsequent references to IN refer to DTAl.
D DIRECT is called to list the directory of DECtape Unit 1. A
directory listing of DTAl is produced,
E The Keyboard Monitor GET and SAVE commands are used
to copy EDIT from the system device to DTAl.
F The FORTRAN compiler is run via the"CCL command COMPILE. to compile and execute the program TEST1 on the
device DSK: An output relocatable binary file named TEST1
is saved by SABR on DECtape Unit 1. the program has an
error in it. Control is returned to the Keyboard Monitor ~fter
execution and the error message·printe.d on the termina1.
G The program EDIT, located on DTA1, is used to correct the
error in TEST 1. The old program, TEST 1, is input to the
Editor, and the new (corrected) program, TEST2, is written
by the Editor onto DTA 1. The first page is yanked into core.
H The user has noticed a misspelled word in FORMAT line 35
and used the string search feature of the Editor to correct it.
An END statement is appended to the program.

D-2

.ZERO DTAt:= I

.DA 4/10/74

C.AS DTAI IN
.01 R IN:
10-APR-74

D
73e FREE BL OCK S

E {.GET

SYS EDIT

• SAVE IN .EDI-T 0- 5000; 200= 2001

OCOMPILE IN:TEST2 2047; 2047 is returned.

E-15

Message

Program

FLAP
RALF

An error has occurred in the
FPP or software floating conversion routines.

FLPW

FORT
Library

Negative number raised to
floating point power; absolute
value taken.

BRTS

Attempt to fix minus number.
UsuaUy caused by negative
subscripts or file numbers.

FMTI

FORT
Library

Invalid format statement.

FMT2

FORT
Library

Illegal character in I format.

FMT3

FORT
Library

Illegal character in F or E
format.

BCOMP

Error in file number of file
name designation.

BRTS

Illegal file number. Only 0, 1,
2, 3, 4 are legal.

BRTS

Attempt to fix number greater
than 4095. Usually caused by
negative subscripts of file

Explanation

numbers.

FOR!v!AT ERROR

FRTS·

mega! syntax in FORMA T
statement.

BCOMP

Incorrect FOR loop parameters or FOR loop syntax.

FLAP
RALF

A syntax error was encountered in a floating point or
extended pre,~ision constant.

FPP ERROR

FRTS

Hardware error on FPP startup.

BCOMB

Error in function arguments
or function not defined.

FULL

Editor

The specified output device
has become full. The file is
closed; the user must specify
a new output file.

BRTS

RETURN without a GOSUB.

*'
GR

E-16

Message

Program

BRTS

Too many nested GOSUBS.
The limit is 10.

Syntax error in GO TO statement.

Assigned or computed .GO
TO variable must be integer
or real.

- HANDLER FAIL

Explanation

CREF

This is a fatal error on output
- and can occur if either the
system device or the selected
output device is WRITELOCKed.

?HANDLERS

BUILD

More than 15 handlers, including SYS and DSK were
active when a BOOT command was issued.

Hollerith field error.

SABR

An illegal syntax has been
used.

BRTS

Illegal argument in UDEF
function call.

FLAP
RALF

The symbol or expression in.
a conditional is iinproperly
used, or left angle bracket is
mlssmg.
The
conditional
pseudo-op is ignored ..

PAL8

Illegal character. The character is ignored and the assembly continued.

PAL8

Illegal redefinition of a symbol.

Error reading input file. Control returns to the Keyboard
Monitor.

PAL8

Illegal equals-an attempt was
made to equate a variable to
an expression containing an
undefined term. The variable
remains undefined.

E-17

Message

Program

Explanation

RALF

An entry point has not been
defined, or is absolute, or also
is defined as a common section, or external.

BCOMP

THEN or GOTO. missing
from IF statement, or bad relational operator.

BRTS

lllega! DEV:fiiename specification.

Logical IF statement cannot
be used with DO, DATA,
INTEGER, etc.

PALS

Illegal indirect-an off-page
reference was made; a link
could not be generated because the indirect bit was already set.

FLAP

A literal was used in an instruction which cannot accept one.

ILLEGAL *

DIRECT
FOTP

An asterisk ("') was included
in the output file specification
or an illegal * was included
in the input file name.

CCL

An ,;. or ? was used in a CCL
command that does not accept the wild card construction.

ILLEGAL ,;. OR

~1CP!P

ILLEGAL?

DIRECT
FOTP

A question mark (?) was included in the output file specification.

ILLEGAL ARG.

Keyboard
Monitor

The SAVE command was not
expressed correctly; illegal
syntax used.

ILLEGAL ARITHMETIC
EXPRESSION

FORT

Self-explanatory.

ILLEGAL BINARY
INPUT, FILE # n

PIP

Self-explanatory; n is the
number of the file in the input
list.

ILLEGAL CONSTANT

FORT

Self-explanatory.

ILLEGAL
TION

FORT

Self-explanatory.

CONTINUA-

Message

Program

ILLEGAL EQUIVALENCING

FORT

# ILLEGAL INPUT

BATCH

Explanation
Self-explanatory.
A file specification designated
. TTY or PTR as an input de-

vice when the initial dialogue
indicated that an operator is
not available. The current job
IS
aborted, and BATCH
scans the input file for the
next $JOB command record.
ILLEGAL OR EXCESSIVE DO NESTING

FORT

Self-explanatory.

ILLEGAL ORIGIN

Loader

A RALF routine tried to
store data outside the bounds
of its overlay.

ILLEGAL SPOOL DEVICE

BATCH

The device specified as a
spooling output· device must
be file-structured. Control returns to the Command Decoder:

ILLEGAL STATEMENT

FORT

Self-explanatory.

ILLEGAL STATEMENT
NUMBER

FORT

Self-explanatory.

ILLEGAL SYNTAX

CCL
Command
Decoder
MCPIP

The command line was formatted incorrectly.

ILLEGAL VARIABLE

FORT

Self-explanatory.

BRTS

Inquire failure in opening
file. Device not found.

INCOMPATIBLE!

ABSLDR

The versions of ABSLDR
and the Keyboard Monitor
being used are incompatible.

?INPUT ERROR

RESORC

An input error occurred during a RESORC operation.

INPUT ERROR

CREF
MCPIP

An input error occurred
while reading the file.

FRTS

Illegal character received as
input.

LIB SET

Parity error on input.

E-19

Message

Program

Explanation

PIP

An input error occurred while
reading file number n in the
input file list..

INPUT ERROR READING
INDIRECT FILE

CCL

eCL cannot read the file specified with the @ construction.

#INPUT FAILURE

BATCH

Either a hardware problem
prevented BATCH from reading the next record of the input file, or BATCH read the
last record of the input file
without encountering a $END
command record.

INSUFFICIENT CORE
FOR BATCH RUN

BATCH

OS/8 BATCH requires 12K
of core to run. Control returns to the OS/8 Monitor.

BCOMP

I/O error.

BRTS

TTY input buffer overflow.

INPUT ERROR, FILE

Causes input buffer to be
cleared and output another ?
(NF).
FLAP
RALF

Input/output error (fatal error).

FORT

A device handler has signalled an I/O FORT error.

IOER

FORT
Library

One of the following has
occurred:
1. Device independent input
or output attempted without /1 or /0 options, or
user attempted to specify
a device requiring a twopage handler for deviceindependent 1/ 0 without
using the / H option.
2. Bad arguments to IOPEN
or OOPEN, or
3. Transmission error while
doing 1/0.

I/O ERR

BUILD

An error occurred while
reading from an input device
during a LOAD command.

E-20

Message

Program

I/O ERROR

FRTS

Error reading or writing a
file, tried to read from an out- ...
put device, or tried to write
on an output device.

PIPIO

I/O device error; e.g., parity, .
write lock, out of paper.

EPIC

If EPIC encounters an error
while reading or writing a
mass storage device, or a
paper tape read fails three
consecutive times, it outputs
this error message, deletes
the output file if one exists,
and· returns to the Command Decoder.

I/O ERROR, FILE #n

ABSLDR
BITMAP

An 1/ 0 error has occurred in
input file number n.

10 ERROR IN (file name)

PIP

An error has occurred during
a /S transfer.

I/O ERROR ON SYS:

CCL

An error occurred while
doing I/ 0 to the system device. The system must be
restarted at 7600 or 7605
(see Restarting OS/8 in the
Getting On Line with OS/8
section of Chapter 1). Do not
press CONT, as that will
surely cause further errors.

I/O ERROR TRYING TO
RECALL

CCL

An I/O error occurred while
CCL was trying to remember an argument.

-CONTINUING

Explanation

.
PAL8

FLAP

Invalid reference in a PDP-8
instruction.

FLAP
RALF

An index register was specified for an instruction which
cannot accept one.

E-21

Illegal pseudo-op-a pseudoop was used in the wrong
context or with incorrect syntax.

Message

Program

PAL8

Illegal page zero referenceThe pseudo-op was found in
an instruction which did not
refer to page zero. The Z is
ignored.

SABR

IL or /G option was indicated, but the LOADER.SV
file does not exist on the system device.

PAL8

The IL or I G options have
been specified and ABSLDR
is not present on the system.

PALS

Link Generated-only printed
if the IE switch was specified to PAL8.

LI··

Argument of logical IF is not
type Logical.

LIBSET

Too many subroutines were
specified.

LINE TOO LONG IN
FILE #n

PIP

In ASCII mode, a line has
been found greater than 140
characters.

BRTS

Attempt to take log of negative number or o.

LOADER I/O ERROR

Loader

Fatal error message indicaiing that an error was detected by OS/8 while trying
to perform a USR function.

BCOMP

Missing equal sign
statement.

BCOMP

Statement too long (greater
than 80 characters).

Input line too long,
many continuations.

FLAP
RALF

The line is longer than 128
characters. The first 127 characters are assembled and
listed.

EPIC

EPIC was expecting leaderl
trailer and found non-leader
trailer while attempting to

. LIBRARY DIRECTORY
OVERFLOW

L/r ERROR

E-22

Explanation

LET

too

Message

Program

Explanation
read a block. The. program
prints this error message and
halts with AC=7777 to allow
the user to reposition the tape
then press the CONT key.

SABR

A symbol is· multiply-defined.
Listings of programs with
multiple definitions have unmarked errors.

# MANUAL HELP

BATCH

BATCH is attempting to operate an I/O device, such as
PTR or TTY, that will require 9perator intervention.

BCOMP

Line number defined more
than once. YY equals the
line number before line in
error.

FLAP
RALF

The tag on the line has been
previously encountered at another location or has been
used in a context requiring an
.absolute expression.

BCOMP

Missing END statement.

MIXED INPUT

Loader

The L option was specified on
a line that contained some
file other than a library file.
The library file (if any) is
accepted. Any other input file
specification is ignored.

MIXED MODE
EXPRESSION

FORT

Self-explanatory.

Misspelled keyword.

Multiply-defined line number.

Mismatched parenthesis.

BCOMP

Operand expected, not found.

NEEDED

F4
MONITOR ERROR 2 AT
xxxx (DIRECTORY I/O
ERROR)

Keyboard
Monitor

E-23

At1empt made to output to a
WRITE-LOCKed device usually DECtape; or an error
has occurred reading/writing
a directory.

Message

Program

Explanation

MONITOR ERROR 5 AT
xxxx (I/O ERROR ON
SYS=)

Keyboard
Monitor

An error occurred while doing I/O to the system device.
This error IS normally the
result of not WRITE-ENABLEing the system device.

MONITOR ERROR 6 AT
xxxx (DIRECTORY
OVERFLOW)

Keyboard
Monitor

A directorY overflow has occurred (no' room for tentative
"'n~"T1 ;" ;t;r<>ctory)
fi le "".I.
.1 J.

LJ.]

.1.~

'-".1..1._

...

•

# MONITOR OVERLAYED BATCH

The Command Decoder attempted to call the BATCH
monitor to accept and transmit a file· specification,. but
found that a user program
had overlayed part or all of
the BATCH monitor. Control
returns to the monitor level,
and BATCH executes the
next Keyboard Monitor command.

MORE CORE REQUIRED

The space required for the
program, the II 0 device
handlers (I/O buffers) and
the resident Monitor exceeds
the available core.

FRTS

1.Jf";('oco;nrr
..I.. .......

"""..,.1.i.16

",,-,-rQntl. u::a.c;(;'I

1'"..1. ""' • .I.L..I. .... ""' •.U

. ..,

Ar
V.L

DI...-r"r

""'.L ... v.&.

expression within parentheses.
In

BCOMP

Operand of mixed type or
operator does not match
operands.

MULT SECT

Loader

Any combination of entry
point, COMMON section
(with the exception of multiple COMMONs) or program section of the same
name causes this error, except as shown in the Table
8-6.

?NAEM

BUILD

A device or filename was not
designated in a command
that requires one to be present.

£-24

Message

Program

FLAP
RALF

Number error. A number .out
of range was specified or an
8 or 9 occurred in octal
radix.

NEED:nlFOUND:n2

EPIC

EPIC read block n2 of the
file when it was expecting
block n 1 of the file. EPIC
halts with AC+7777 to allow the user to reposition
the paper tape.

NEED: name I FOUND
name2

EPIC

EPIC read a block of tape
for the file NAME2 when it
was expecting a block of the
file NAMEl.-·

BCOMP

NEXT statement without corresponding FOR statement.

BCOMP

Line number missing after
GOTO, GOSUB, or THEN.

NO!!

Keyboard
Monitor

The user attempted to start
(with .sT) a program which
cannot be started.

NO CCL!

Keyboard
Monitor

CCL.SV is not present on the
system device or an II 0 error
occurred on the file. Refer to
the Getting occurred while
trying to read On Line section
of Chapter 1 for instructions
on loading programs onto the
system device.

NO DEFINE FILE

FRTS

Direct access II 0 attempted
without a DEFINE FILE
statement.

NO END STATEMENT

FORT

The input to the compiler has
been exhausted.

NO FILES OF THE FORM
xxxx

FOTP

No files of the form (xxxx)
specified were found on the
current input device group:

NO /1

BITMAP

Cannot produce a bitmap of
an image file.

NO /I!

ABSLDR

Us~ of /1 is prohibited at this
point.

E-25

Explanation

Message

Program

Explanation

NO INPUT

ABSLDR
BITMAP

No input or binar=y file was
found on the designated device.

MCP!P

No input me was specified
when one was required.

LOADER

No RALF module contained
section # MAIN.

FRTS

The referenced FORTRAN
I/O unit was not specified to
the run-time system.

NO OUTPUT FILE

MCPIP

No output file was specified
when one was required.

?NO ROOM

BUILD

Too many device handlers
were present on the system
when a LOAD or BUILD
command was typed. The
UNLOAD command must be
used to remove a handler before another can be loaded.

NO ROOM FOR OUTPUT

FORT

The file FORTRN.TM cannot fit on the system device.

NO ROOM FOR OUTPUT
FILE

DIRECT
PIP

Either room on device or
room in directory is lacking.

NO ROOM IN (file name)
-CONTINUING

PIP

Occurs during use of the !S
option. The output device
cannot cdntain all of the files
on the input device~

NO ROOM, SKIPPING
(filename)

FOTP

No space is available on the
output device to perform the
transfer. Pre deletion may already have occurred.

NO SUCH DEVICE

PlPIO

Device name used is not legal
in this OS! 8 system.

% NON SYSTEM DEVICE

RESORC

The input device specified in
a RESORC command line is
not an OS/8 system device.

NOT A LOADER IMAGE

FRTS

The first input file specified
to the run-time system was
not a loader image file ..

% NOT A SYSTEM HEAD

RESORC

The filename specified is not
a system-head file.

" T'"

l .... V

Y'"
TnT T"'"r
~l'lr U.L

1:'TT -C

.L u .... .LJ

NO MAIN
··NO NUMERIC SWITCH

E-26

Message

Program

Explanation

name NOT A V AILABLE

Keyboard
Monitor

The device with the name
given is not -listed in any system table, or it is not available for use at the moment,
or the user tried to obtain input from an output-only device.

NOT ENOUGH CORE

CCL

The number specified" in a
CORE command is larger
than the number of 4K core
banks on the system.

name NOT FOUND

BUILD
CCL
Command
Decoder .~
Keyboard
Monitor

The device or file name designated in the command was
not found.

file NOT FOUND

MCPIP

The file specified cannot be
found.

NOT OS8 FILE

PIPIO

The output device specified
with a IL or IF option was
not an OS/8 device or file.

NOT PDP-IO FILE

PDPIO

The output - device speciUed
with a I Z option was not a
DECsystem-lO tape, or the
input device specified with a
IL or IF option was not a
DECsystem-lO tape.

?NUMBER TOO BIG

CAMP

The "nnnn" specified in a
BACKSPACE or SKIP command is greater than 4095.

BRTS

Driver error while overlaying. Caused by SYS device
hardware error.

BCOMP

Output file error.

Error writing output, file.
Control retllrns to the Keyboard Monitor.

Illegal operator.

OS/8 ENTER ERROR

Loader

Fatal error message indicating that. an error was detected by OS/8 while trying
to perform a USR function.

E-27

Message

Program

Type/ operator use megal
(e.g., A.AND.B where A
and/ or B not typed Logical).

OUTDEVFULL

CREF

The output device is full (directory devices only).

OUT-IN

MCPIP

Both the input and the output devices were specified as
the same cassette or magnetic tape drive.

?OUTPUT DEVICE FULL

RESORC

The output device specified
does not have enough room
to copy the RESORC file.

OUTPUT DEVICE FULL

MCPIP

Either room on device or
room in the directory is lacking.

?OUTPUT DEVICE IS
READ ONLY

RESORC

The output device specified is
a read-only device; e.g., PTR.

"?OUTPUT ERROR

RESORC

An error occurred while at"tempting to output during a
RESORC operation.

OUTPUT ERROR

MCPIP

Output error-possibly a
WRITE-LOCKed device, parity error, or attempt to output to a read-only device.

OUTPUT FILE OPEN
ERROR

PIPIO

The output file could not be
opened. Check output directory to ensure that enough
space exists on the device.

BRTS

Numeric or input overflow.

OVER CORE

Loader

The loader image requires
more than 32K of core memory.

OVER IMAG

Loader

Output file overflows in the
loader image file.

OVERSYMB

Loader

Symbol table overflow. More
than 253 (decimal) symbols
in one FORTRAN job.

OVERFLOW

FRTS

Result of a computation exceeds upper bound for that
class of variable. The result

E-28

Explanation

Message

Program

Explanation
is set eqqal to zero and execution continlles. This· error
is detected only if an FPP is
present.

OVERLAY ERROR

FRTS

Error while reading overlay.

OVFL

FORT
Library

Floating point overflow; very
large number is returned.

BRTS

Illegal argument in POS function.

. FRTS

Parens nested too deeply in
FORMAT statement.

PARITY ERROR

EPIC

EPIC failed to read a block
correctly; e.g., the reader
dropped some .bits. EPIC
halts with AC=7777 to allow the user to reposition
the tape so that it can try the
read again.
.

BCOMP

Pushdown stack overflow.
Result of either too complex a statement (or statements) or too many nested
FOR-NEXT loops.

Compiler stack overflow;
statement too big and! or too
many nested loops.

PAL8~

Current non-zero page exceeded-an attempt was made
to:'

Bad program header line.

PARENS TOO DEEP

PALS

Phase errOf-a conditional
assembly bracket is still in·
. effect iit the end of the input stream-this is caused by
nonmatching < and > characters. in the source.

PIPIO CANNOT BE
CHAINED

PIPIO

Self-explanatory.

?PLAT

BUILD

The =n in a SYS command
is too .large for the device
specified; e.g., RF08=5.

E-29

Message

Program

FLAP

Page overflow. Literals and
instructions have been overlapped.

PREMATURE END OF
FILE, FILE#n

PIP

Message occurs in Binary
Mode UB) only. A physical
end-of-file has been found before the final leader/trailer.

PTR:name IS TOO BIG
FOR dev:

EPIC

The paper tape file name will
not fit on the specified output
device DEV:. EPIC aborts
the command and returns to
the Command Decoder. EPIC
makes the check for size before writing on the output device.

Nesting error m EQUIVALENCE statement.

BCOMP

String literal too long or does
not end in quote.

Syntax error in EQUIVALENCE statement.

Attempt to redefine the dimensions of a variable.

PALS

Redefinition - a permanent
symbol has been defined with
=. The new and old definitions do not match. The redefinition is allowed.

BRTS

Attempt to read past end of
file (NF).

RALF

Relocatability error. A reloeatable expression has been
used in context requiring an
absolute expression.

RECORD SIZE TOO BIG

MCPIP

The output record size specified is greater than 1000 or
an output record size is O.

Attempt to redefine the type
of variable.

RW.

Syntax error on
WRITE statement.

E-30

Explanation

READ/

Explanation

Message

Program

SABR

Either the symbol table has
overflowed, cOIp.mon storage
has been exhausted, more
than 64 different user-defined
symbols occurred in a core
page, or more than 64 external symbols have been declared. Could also indicate a
system error such as overflowed output file.

SABR.SV NOT FOUND

FORT

The SABR assembler is not
present on the system device.

SAVE ERROR

Keypoard
Monitor

An II 0 error has occurred
while saving the program.
The program remains intact
in core.

BRTS

String too long (greater than
72 characters) after concatenating.

PAL8

Symbol table extended-too
many. symbols have been defined for the amount of memory available. Fatal errorassembly cannot continue.

Bad
arithmetic
function.

BRTS

String too long or undefined.

Illegal subroutine name in
CALL.

SORRY-NO
INTERRUPTIONS

PIP

1. tC

#SPOOL TO FILE
BTCHA1

BATCH

E-31

statement

(CTRLj C) is typed
while compressing a file
onto it~elf;. the transfer
continues.
2. A IY transfer is done with
system device as the output, or if the transfer has
both input and output on
the same device.

Where the "A" may be any
character of the alphabet and
the "1" may be any decimal
digit. This message indicates
. that BATCH has intercepted

Message

Program

Explanation
a non-file structured output
file and rerouted it to the
spool device. This is not, generally, an error condition.

SQRT

FORT
Library

Attempt to take square root
of negative number; absolute
value used.

BRTS

Attempt to read string from
numeric file.

BCOMP

Subscript or function argument error.

Error in subscript expression; I.e., wrong number,
syntax.

SCaMP

Symbol table overflow due to
too many variables, line
number, or Iiter~als. Combine
lines using backslash (/) to
condense program.

BRTS

String truncation on input.
Stores maxImum length allowed (NF).

Compiler symbol table full,
program too big. Causes an
immediate return to the Keyboard Monitor.

FLAP

User symhol table overflow
(fatal error).

RALF
SU

BRTS

Subscript out of DIM statement range.

SUSR. OR FUNCT. STMT.
NOT FIRST

FORT

Self-explanatory.

% SUPERSEDED

CCL

The file specified in a MAKE
command already exists. This
is a warning message indicating that the file is being
replaced.

BRTS

Attempt to write string into
numeric file.

SWITCH NOT ALLOWED
HERE

CCL

Either a CCL option was
specified on the left side of

E-32

Message

Program

Explanation
the < or was used when riot
allowed.
.

BCOMP

System incomplete. System
files such· as BASIC.SV,
BCOMP.SV, and BRTS.SV
missing .
. System error; i.e., PASS20.
SV or P ASS2.sV missing, or
no room for output file.
Causes an immediate return
to the Keyboard Monitor.

SYM OVERFLOW

CREF

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

SYMBOL TABLE
EXCEEDED

FORT

Self-explanatory.

?SYNTAX

BUILD

illegal character was
typed in a BUILD command
line. The line must be retyped.

?SYNTAX ERROR

CAMP

An illegal character was typed
in a CAMP command or a
command was formatted incorrectly. The command must
be retyped.
'

SYNTAX ERROR

FORT
PIP 10

Invalid command line.

?SYS

BUILD

This message appears when
one of the following conditions exists:
a. A permanent name in a
SYS command was not a
system handler or coresident with one.
b. A BOOT command was
issued when two system
handlers were active.
c. A BOOT command was
issued with a active handler which must be coresident with a SYS handler did not have the
• system handler active.

£-33

Message

Program

Explanation
A hardware probiem prevented BATCH from performing an II 0 operation.

SYS ERROR

BUILD
a system handler. The computer halts. Press CONT to
retry or restart the BUILD
procedure from the beginning. Do not assume that a
valid OS/8 system 'remains in
core.

SYS NOT FOUND

BUILD

No active handler with the
name SYS was present when
a BOOTSTRAP command
was issued.

SYSTEM DEVICE ERROR

FRTS

I/O failure on the system
device.

SYSTEM ERR

Keyboard
Monitor

An error occurred while doing 1/ 0 to the system device.
The system should be restarted at 7600 or 7605. Do
not press CONTinue as this
IS
sure to cause further
errors.

SYSTEM ERROR

Loader

Fatal error message indicatmg that an error was detected by OS/8 while trying
TSR fnnl'tirtn
-- r--------- _.~ T--------------

trt nf"rfrtrm

SYSTEM ERRORCLOSING FILE

FOTP

Self-explanatory.

BCOMP

Program too big. Condense
or CHAIN.

BCOMP

Too much data in program.

Bad syntax in type declaration statement.

DIRECT

A command was issued to
print a directory on the terminal when no TTY handler
is present on the OS/8 system. Use BUILD to insert a
TTY handler in the system.

THERE IS NO HOPETHERE IS NO TTY
HANDLER IN YOUR
SYSTEM!

E-34

Message

Program

Explanation

TOO FEW ARGS

Keyboard
Monitor

An important argument has
been omitted from a command.

TOO MANY FILES

CCL

Too many files were included
in a CCL command.

TOO MANY FILES

Command
Decoder

More than three output files
or nine input files were specified. Some programs may
restrict the user to fewer files. -

TOO MANY FILES

MCPIP

More than 1 output device
was specified or more than 1
input device was specified.

TOO MANY HANDLERS

FRTS

Too many I/O device handlers are resident in memory,
or files have been defined on
too many devices.

TOO MANY LEVELS

Loader

The 0 option was specified
more than 7 times.

TOO MANY OVERLAYS

Loader

More than 16 overlays were
defined in the current level.

TOO MANY RALF FILES

Loader

More than 128 input files
were specified.

BCOMP

Too many total characters in "the string literals.
-

?TTY DOES NOT EXIST

RESORC

An output device was not
specified in the RESORC
command line and the TTY
handler does not exist on the
OS/8 system. See the BUILD
section of Chapter 2 for instructions on inserting TTY
handlers.

SABR

No symbol table is being produced, but there is at least
one undefined symbol in the
program.

-UD

BCOMP

Error in UDEF statement.

BCOMP

FOR loop without corresponding NEXT statement.

UNDF

SABR

Undefined symbol; printed
the symbol table listing.

E-35

Message

Program

UNIT ERROR

TT,...

Explanation
I/O unit net assigned, or Lllcapable of. executing the re-'
quested operation.

PALS

Undefined origin-an undefined symbol has occurred in
an origin statement.

BCOMP

Undefined statement number.

F4
FLAP
RALF
PALS

Undefined symbol in an expression.

USE PIP FOR NON-FILE
STRUCTURED DEVICE

FOTP

An input device specified is
not a file-structured device;
e.g., PTR.

USER ERROR

FRTS

Illegal subroutine call, or
call to undefined subroutine.
Execution continues only if
the E option was requested.

USER ERROR 0 AT XXXx

Keyboard
Monitor

An input error was detected
while loading the program.
xxxx refers to the Monitor
location where the error was
generated.

USER ERROR 1 AT xxxx

FORT
Library

The user tried to reference
an entry point of a program
which was not loaded, or he
failed to define a subscripted
variable in a DIMENSION
statement. xxxx has no mean·
ing.

USR n dev:name

EPIC

The USR encountered an
error while attempting to
perform a fetch, lookup, enter or close on the file
name on device dev. n= 1
is a fetch, n=2 is lookup,
n=3 is enter, n=4 is close.
EPIC aborts the command
and returns to the Command
Decoder.

BCOMP

Incorrect or missing array
designator in USE statement.

E-36

Message

Program

Version error. One of the
compiler programs is absent
from SYS: or is present in
the wrong version.

BRTS

Attempt to
length file.

BRTS

Explanation

read

variable

Attempt to write past end of
file (NF).

WRONG OS/8 MONITOR

BATCH

OS/8 BATCH requires an
OS! 8 Monitor no older than
version 3.

BCOMP

Extra characters after
logical end of line.

RALF

External symbol table overflow. Control returns to the
OS/8 Keyboard Monitor.

PAL8

Page 0 exceeded-same as
PE except with reference to
page O.

ZERO SYS?

PIP

If any attempt is made to
zero the· system device directory, this message occurs. Responding with Y causes the
directory to be zeroed; any
other character aborts the
operation.

E-37

the

E-38

osja
Ale name extensions
This appendix lists the file name extensions used in OS/8.
Extension

Meaning

.BA

' BASIC source file (default extension for a BASIC input
file).
°

.BI

° Batch input file .

.BK

Backup ASCII file (default extension for a TEeD output
file) .

.BN

Absolute binary file (default extension for °ABSLDR,
BUILD, and BITMAP input files; also used as default ex°
tension for P AL8 binary output file) .

.DA

Data file .

.DC

Documentation file .

.DI

Directory listing .

.FT

FORTRAN language source file (default extension for
FORT input files) .

.HL

HeI p file (default extension for HELP input files) .

.LD

F4 load mode (default assumed by run-time system, F4
loader) .

.LS

Assembly listing output file (default extension for P AL8
and SABR) .

.MA

Macro'source file .

.MP

File containing a loading map (used by the Linking
Loader) .

.PA

P AL8 source file .

.RA

RALF assembly language file.

F-l

Extension

Meaning

.RB

Relocatable binary source file .

.RL

Relocatable binary file (default extension for a Linking
Loader input file; also used as the default extension for an
8K SABR output file) .
.

.SB

8K SABR source file .

.SV

Core image file or SAVE file; appended to a file name by
the R, RUN, SAVE, and GET Keyboard Monitor commands .

.SY

System head .

.TE

TECO macro file (default extension for a MUNG input
file) .

.TM

Temporary file generated by FORTRAN or SABR for
system use (default extension for CREF input files and
P AL8 output files) .

.TX

Text files.

F-2

9
osja device handlers
The device handlers supplied with the- OS/8 system have cer,tain, operating characteristics which the user should understand.
Most of these are extremely simple and require no action by the
,user. Some device handlers perform additional operations for the
user when I/O is being performed on a given device. This appendix gives a brief description of the OS/8 device handlers. See the,
OS/8 Software Support Manual (DEC-S8-0SSMB-A-D) for more'
detailed information concerning device handlers.
HIGH-SPEED READER/PUNCH
The device handler for the high-speed paper tape reader, before
reading a tape, prints an uparrow (t) and waits for the user to
type any single character at the keyboard. This gives the user time
to check the reader to ensure that the tape is loaded _correctly, and
it facilitates readjng multiple tapes,e.g., a PAL8 source tape must
be loaded three times for the three passes of the assembler. Char, acters are read from the paper tape and packed into an input
buffer. The end of the paper tape or full input buffer causes the
buffer to be made available to the user-program. Typing CTRL/C
while the tape is moving causes a return to the Keyboard Monitor.
The handler for the high-speed paper tape punch unpacks characters from the output buffer and punches them on paper tape.
Typing CTRL/C causes a return to the Keyboard Monitor. The
punch must be manually turned on before an attempt is made to
output to that device.

-' LOW-SPEED READER/PUNCH
In addition to the handler for the high-speed reader/punch, a
similar handler is available for the ASR-33 Teletype low-speed
reader/puJ.1ch. This handler allows users not having high-speed
I/O to read and punch binary format tapes. (The standard TTY
handler cannot be used for binary format tapes, as the binary

G-l

format can appear as control characters to the handler.) The operation of this handler is exactly the same as that for the high-speed
reader/punch except that the uparrow is not printed.

TrY HANDLERS
There are two TTY (console terminal) handlers avail ahIe: a
I-page handler and a 2-page handler. Both handlers perform I/O
transfers between the terminal keyboard and an input buffer, or
between. an output buffer and the terminal.
The I-page handler echoes all terminal input and performs a
line feed operation after any typed carriage return. A CTRL/O
typed while output is being printed terminates printing of the current output buffer.' A CTRL/C typed at any time during input or
output causes a return to the Keyboard Monitor. Typing CTRL/Z
.as input terminates input and gives an end-of-file indication to the
. calling program. The TTY handler should not be used to read
binary tapes from the low-speed reader.
The 2-page TTY handler may be used only to read or write.
ASCII files; results are unpredictable with non-ASCII files. In
addition to the features included in the· I-page handler, this handler includes the use of the RUB OUT key to delete the previous
character and echo it either as a backslash (',,) or as the character
rubbed out, the use of CTRL/U to delete the current line, and the
use of the TAB key to output the correct number of spaces to bring
the text to the start of the next tab stop.
The 2-page TTY handler also includes approximately 30 free locations so that the user may comlitionalize certain nonstandard
features. See the OS/8 Software Support Manual for a complete
list of these features.
LINE PRINTERS
The OS/8 line printer handler is a I-page handler for the LP08,
LS8E, and L V8 line printers. This handler performs a form feed
operation before beginning an output task. The characters are unpacked from the output buffer and printed. A form feed is also
produced following the compl~tion of an output task. Typing
CTRL/C while the line printer is in operation causes a return to
the Keyboard Monitor. A CTRL/Z found in the output buffer
ca1,lses printing to terminate and a form feed to be produced. Tabs
and line overflow are handled; nulls are ignored.
G-2

Relative location 0 of this handler specifies the width of the line
printer. This location may be patched using the ALTER command
in BUILD. The location is set to the one's complement of the width
desired. Initially, this location is set to 7573 (octal) which corresponds to a 132-column printer. For example, to indicate an 80column printer, location 0 should be set to 7657 (octal).
VR12 SCOPE
The VR12 scope handler for OS/8 (running on a PDP-12) displays characters on the VR12 scope on both channels. When the
scope is full, the handler stops reading characters from the buffer
and displays what is known as a scope page. The screen is considered full whenever the end of the buffer is reached, a CTRL/Z
is encountered in text, or when the number of lines displayed become equal to the maximum number specified by the user. The
user can advance to the next scope page by typing any character,
other than CTRL/C.
When CTRL/C is typed, contr91 returns t~ the Keyboard Monitor. Control does not return to the calling program until a character is typed at a point when the handler is displaying the last
scope page of a particular buffer load.
To use the VR12 handler, the user sets the number of lines desired in a single scope page via the switch register (right switches).
The switch register is set to the negative of the number of lines to
be displayed in a 'scope page. When text reaches the right margin
of the scope face, it is continued on the next physical line of the
_
scope.
A line feed or form feed character causes succeeding text to continue on the next physical line. Carriage return characters have no
effect on the display.
CARD READER
The device handler for the card reader reads cards in alphanumeric format from either a punched card reader or an optical
mark -card reader. Card format can have up -to 80 characters per
card; trailing blanks' are deleted from each card. Blank cards cause
a carriage return/line feed to be entered into the data stream.
Typing CTRL/C while cards are being read terminates reading
and returns control to the Keyboard Monitor. Typing CTRIJZ
terminates further reading and performs as though an end-of-file
card was read. (An end-of-file card contains a ~ character in

0-3

column 1 (0-8-5 punch) with the remaining columns blank. Either
CTRL/Z or the -end~of-file card is necessary to terminate reading.)
Tt
1~ not
RTJN or
....................
_ . . nm:~ihlp.
r-- . . -- ... --- to
-- ------ OFT
- - - ::I
- nropr::lm
r--o----- from
---,--- the
---- card
- .. --- reader
-----.

as these commands assume a directory device.
DECTAPES
Any DbCtape other than the system device tIt me system is a
DECtape system) can be interrupted with a CTRL/C, returning
control to the Keyboard Monitor. DECtape unit 0 on a DECtape
system must never be WRITE LOCKed while operating OS/8.
MAGNETIC TAPE
The handler for magnetic tape reads and writes either 7- or 9channel magnetic tape with odd parity at 800 bpi. This handler is
non-file structured but may be altered by the user to read and write
files. CTRL/C returns control to the Keyboard Monitor but its use
is not recommended since it leaves the tape without an end-of-file
indicator.
CASSETTES
The cassette handler performs character I/O transfer between
the cassettes and the buffer. It treats cassettes as non-file structured
devices. Data appears on cassette in 192-byte records. Typing
CTRL/C returns control to the Keyboard Monitor.
BATCH HANDLER
The OS/8 batch handler is used from a BATCH job to read
from the BATCH stream. This is a I-page handler for read-only,
none-file structured devices. If this handler is used when BATCH
is not funning, it generates a fatal error. The BATCH handler
reads characters from the BATCH stream, ignoring line feeds, and
creating a line feed after a carriage return. When the handler
encounters a line beginning with a dollar sign, it pads the buffer
with CTRL/Z and nulls, and takes the end-of-file return.
DSK AND SYS
TheDSK and SYS device handlers work automatically without
any user intervention.

0-4

h
obtaining osja

program
~"'--,

version numbers
When the user receives new OS/8 software or when he wishes
to report problems with the software, he must know the version
number of the OS/8 program in question. Most OS/8 system programs have version num~ers that can be obtained by typing a
command to the OS/8 Command Decoder * or to the called program. Some sy~tem programs print the version number at the
. beginning of the output listing. The following table shows how to
obtain version numbers for most OS/8 system programs.
Program
ABSLDR
BASIC
BATCH
BITMAP
BOOT
BUILD
CAMP
CCL
Command Decoder
CREF
DIRECT
EDIT
EPIC
F4 Compiler
F4 Loader (LOAD)
FLAP
POTP
FRTS

How to Obtain Version Number
Internal only.
Printed in program heading.
Type IV in BATCH command string.
Printed at top of output listing.
Type VE to the I printed by BOOT.
Type VE to the $ printed by BUILD.
Type VE to the # printed by CAMP.
Type VER to the Keyboard Monitor.
Internal only.
Printed at end of CREF output listing.
Type IW to the * printed by DIRECT.
Type # to the # printed by EDIT.
Internal only.
Printed in heading of output listing.
Printed in heading of loading map.
Printed in heading of output listing.
Type /W to the * printed by FOTP.
Type IV to the * printed by FRTS (to be
implemented later).

H-l

Program

Keyboard Monitor
MCPIP
ODT
PALS
PIP
PIPIO
RALF
RESORC
SRCCOM
TECO

How to Obtain Version Number

Type VER to the Keyboard :Monitor.
Type I V to the * printed by MCPIP.
Internal only.
Printed in heading of output listing.
Type IV to the * printed by PIP.
Printed in heading of directory listing.
Printed at heading of output listing.
Type IV to the * printed by RESORC.
Printed in heading of output listing.
Type CTRLI V t~ the * printed by TECO.

H-2

ABS function,
FORTRAN II, 7-41
FORTRAN IV, 8-46
SABR,4-42
Absolute Binary Loader (ABSLDR);
1-21, 1-108
COrrect use, 1-112
error messages, 1-113
Options, 1-11 0, 1-111
Absolute relocation address, SABR,
4-49
Absolute value function, BASIC,
6-37
ABSYM pseudo-op, SABR, 4-20
A conversion (FORTRAN IV), 8-96
AID converter, 6-124
Addition,
BASIC, 6-8
PAL8,3-15
Addresses of operands, SABR;4-7
Addresses, PAL8, 3-9, 3-23
Addressing, FLAP/RALF
in FPP mode, 5-13
in PDP-8 mode, 5-6
Algebraic operations, FORTRAN
II, 7-12
ALOG function,
FORTRAN II, 7-41
FORTRAN IV, 8-48
, SABR, 4-45
.
Alphabetic characters, SABR, 4-4
Alphabetizing with TECO, 2-172
,Alphanumeric,
field specifications, FORTRAN II,
7-22, 7-24
information, BASIC, 6-46
Altmode character, TECO, 2-134
AL TMODE command, BASIC, 6-55
ALTMODE echo, 1-21
AND, Boolean (PAL8), 3-16
AND group skip instructions, PAL8,
3-25
.AND. (logical operator), FORTRAN IV, 8-74
Angle bracket «), usage,
command decoder, 1-45
PAL8, 3-21, 3-30
Arctangent function,
BASIC, 6-39

FORTRAN IV, 8-49, 8-50, 8-55,
8-56
ARG pseudo-op, SABR, 4-25
Arguments,
dummy, FORTRAN II, 7-36
SABR, 4-25, 4-29
Arithmetic expressions,
FORTRAN II, 7-13
FORTRAN IV, 8-72
Arithmetic functions, BASIC, 6-34
Arithmetic operations,
BASIC, 6-6, 6-8
FLAP/RALF, 5-3
FORTRAN II, 7-42
PAL8, 3-14; 3-15
SABR, 4-41, 4-43
Arithmetic operators, TECO, 2-163
Arithmetic statements,
FORTRAN II, 7-16
FORTRAN IV, 8-77
Arrays,
BASIC, 6-31
BASIC string, 6-74
FORTRAN II,
FORTRAN IV, 8-71
SABR, 4-43, 4-48
Array specifications, FORTRAN IV,
~lm

Array symbol table, BASIC, 6-77
ASCII
character set, A-I
constants, SABR, 4-7 .
conversion, BASIC, 6-51
file format, BASIC, 6-95
source files, 1-78
stripped format, FORTRAN II,
7-24
text strings, SABR, 4-23
Assembler, FLAP lRALF-see
FLAP IRALF'
,
Assembling RALF file (FORTRAN
IV), 8-5
Assembly error, RALF, 8-17
Assembly instructions,
BITMAP, 2-30
EPIC, 2-96
SRCCOM,2-128
TECO, 2-183
Assembly language function, BASIC,
6-69, 6-97, 6-101, 6-102
Assembly, SABR

Index-l

control, 4-16
first pass, 4-54
page-by-page, 4-32
C'lor- ........

."...t ...... f')C:OC'

.;:n...."'vuu.

.Pu.~I,)I,

A_,A

"""T -J"""T

Assembly termination PAL8, 3-38
ASSIGN command, keyboard monitor, 1-35
Assignment statements,
BASIC, 6-15
FORTRAN IV, 8-76, 8-79
ASSIGN statement, FORTRAN IV,
8-78
Asterisk (*) usage,
ABSLDR response, 1-21
command decoder, 1-45, 2-6
TECO, 2-134
wild card in DIRECT, 2-77
wild card in FOTP, 2-97
@ construction, CCL, 1-56
A TAN function
FORTRAN II, 7-41
FORTRAN IV, 8-49
SABR.4-44
ATAN, "library subroutine, FORTRAN IT, 7-47
Autoindexing, PAL8, 3-26
Automatic paging mode, SABR,
4-33
B

Back-arrow (~) character,
BASIC, 6-2, 6-55
Command decoder, 1-45
Background-foreground I/O FORTRAN IV, 8-33
Backslash, keyboard monitor, 1-33,
1-34
BACKSPACE command, CCL, 1-57
BACKSPACE statement, FORTRAN IV, 8-106
Base page, FPP (FLAPjRALF),
5-13 5-22
BASIC, '
arithmetic, 6-6
arithmetic functions, 6-33
BRTS-See BASIC Run-Time
System
commands, 6-54
compile-:-time diagnostics, 6-115
debugging function, 6-42
exit, 6-4
files, 6-60
function summary, 6-113, 6-114
getting on the air, 6-148
LAB8/~see LAB8/E
optimizing system performance,
6-121
overview, 6-5
running, 6-1
run-time diagnostics, 6-117

statements, 6-11
statement summary, 6-109
strings, 6-46
subroutines, 6-44
system build instructions, 6-118
BASIC Run Time System (BRTS),
6-69
assembly language function, 6-69,
6-102
buffer storage, 6-95
core layout, 6-71
data formats, 6-73
floating-point operations, 6-80
general considerations, 6-100
interfacing assembly language
function to BRTS, 6-97
1/0,6-94
overlays, 6-72
passing arguments to the user
function, 6-91
subrouti1les, 6-85
symbol table structure, 6-76
system components, 6-70
BATCH,2-1
demonstration program, 2-15
error messages, 2-9, 2-10, 2-11
input file, 2-1, 2-8
loading and saving, 2-21
monitor commands, 2-4
output file, 2-2
restrictions, 2-13
running from punched cards, 2-12
run-time options, 2-3
transferring software from cassette, 2-21
Binary output control, PAL8, 3-31
Binary output tape, SABR, 4-49
BITMAP (binary tape) load, 1-23
BITMAP utility program, 2-26
assembly instructions, 2-30
error messages, 2-30
hardware/software requirements,
2-26
loading, 2-26
options, 2-27
output, 2-29
BLOCK DATA statement,
FORTRAN II, 7-44
FORTRAN IV, 8-119
Block number, FORTRAN IT, 7-45
BLOCK pseudo-op, SABR, 4-22
Boolean AND, PAL8, 3-16
Boolean inclusive OR, PAL8, 3-15
BOOT (binary tape) load, 1-25
BOOT command, CCL, 1-58
BOOT (bootstrap" utility program),
2-32
mnemonics, 2-33
Bootstraps,
DF32 disk, 1-26

Index-2

for cassette, 1-10 through 1-15
LINCtape· for PDP-12 systems,.
1-9
MI8-E, 1~2, 1-10
RF08, disk, 1-26
RK8 disk, 1-28
RK8E disk, 1-26, 1-27
TCOl/TC08, 1-3
TD8E,I-4
Bracket ([) used in PDP-8 expression (FLAP), 5-15
Branching commands, TECO, 2-157
Breakpoints, 1-115
BRTS-See BASIC Run-Time System
Buffer pointer, TECO, 2-133
manipulation commands, 2-147
Buffer space, BASIC, 6-95
BUILD, (system generation program, 1-10 through 1-19, 2-34
cassette device handlers, 2-36
commands, 2-40
DECtape device handlers, 2-35
device handler format, 2-56
device handlers, 2-34
editing characters, 2-39
error messages, 2-55, 2-56
OS/8 device handlers, 2-38.
paper tape device handlers, 2-37
Building BASIC system, 6-119
Building OS/8
from cassette, 1-10
from paper tape, 1-17
BYE command, BASIC, 6-60
C
Calling,
ABSLDR,I-108
BASIC, 6-1
BATCH,2-2
BUILD,2-38
CREF,2-69
Editor, 1-78
FOTP, 2-97
MCPIP, 2-110
ODT,1-114
OS/8and device handlers, 4-60
. PAL8, 3-1
PIP, 1-97
PIPI0, 2-116
RESORC, 2-121
TECO, 2-133
Calling relationships, FORLIB, 8-44
Calling sequence, FORTRAN IV
loader routines, 8-21
CALL (pseudo-op), SABR, 4-25·
CALL statement,
FORTRAN II, 7-39
FORTRAN IV, 8-118

CALL subroutine, FORTRAN IV,
8-22
CALL OPEN statement, FORTRAN II, 7-33
CAMP (Cassette and Magnetic Tape
Positioner program),
commands, 2-62
error messages, 2-67
load, 1-25
Carriage control (FORTRAN IV),
8-97, 8-98, 8-99
Cassette and Magnetic Tape Positioner-see CAMP
Cassette
file names, 2-110, 2-113
software, 1-10,2-21
system BUILD, 2-36
system load, 1-15
transfer program, 2-110
CCY (Concise Command Language), 1-52
commands, 1-52, 1-58
error messages, 1-75
file names, nonstandard, 1-57
indirect commands, 1-56
load, 1-24
options, 1-54
source file, 1-16
wildcard construction, 1-55
CDF current;'SABR, 4-51
CDFSKP Linkage routine, SABR,
4-35
CDZSKP Linkage routine, SABR,
4-35
Chaining
FORTRAN II, 7~42, 7-51
FORTRAN IV, 8-6
CHAIN STATEMENT, BASIC,
6-68
CHAIN subroutine, SABR, 4-47
Changing the numeric conversion
mode, SABR, 4-17
Character deletion,
BASIC, 6-2, 6-55
keyboard monitor, 1-33, 1-34
Characters,
ASCII, A-I
BASIC format control, 6-18
FORTRAN II, 7-8
ODT special, 1-115
PAL8,3-5
P AL8 special, 3-18
SABR,4-4
Symbolic Editor special, 1-81,
1-82
TECO, 2-133, 2-142
Character search, Symbolic Editor,
1-83
.
Character string search, Symbolic
Editor, 1-84

Index-3

Checksum, SABR, 4-49, 4-53
CHR$ function, BASIC, 6-51
CHS subprogram, SABR, 4-41
-CKIO subroutine, S.£-\BR, 4~46
CLEAR, subprogram, SABR, 4-42
Clock function, LAB8/E, 6-131
CLOCK subroutine FUNCTN arguments, FORTRAN IV, 8-52
Clock wait function, LAB8/E, i-32
CLOSE# statement, BASIC, 6-64
Closed subroutines, FORTRAN II,
7-35
Codes,
ASCII character, A-1
leader/trailer, SABR,4-49
Loader relocation, SABR, 4-49
numeric field, FORTRAN II,
7-22
Coding form, FORTRAN IV, 8-66
Coding practices, PALS, 3-36
Comma used as. separator in command decoder, 1-45
Command Decoder. 1-45
called from BATCH, 2-:1'
error messages, 1-51
examples, 1-48
file specifications, 1-46
input string, 1-45
I/O specification options, 1-49
Command format, editing (EPIC),
2-88
Command loops, TECO, 2-155
Command mode, Editor, 1-80
Commands,
BASIC editing and control, 6-54
BUILD,2-40
CAMP, 2-62
CCL, 1-52
EPIC, 2-88, 2-89, 2-90
1............:1....: .... _....1 _
A~yuvalu

..... _:f....,..,..

l11V1.U.... V.1,

'2,

~..:..~..,

ODT, 1-115
,
Plotter, 8-129 through 8-142
special keyboard commands to
Editor, 1-80, 1-81
TECO; 2-132, 2-136 through
2-151, 2-157, 2-158, 2-179
through 2-182
Command string examples, Command Decoder, 1-48
Command string format, BATCH,
2-3
Command summary, ODT, 1-122,
1-123
Symbolic Editor, 1-92 through
1-97
Comments,
FLAP/TALF,5-3
FORTRAN II, 7-15
FORTRAN IV, 8-67
PAL8,3-7

SABR.4-10
TECd.2-165
COMMON statement,
FORTP~Jt.N 111 7-34
FORTRAN IV, 8-108, 8-111
Common 'Storage, SABR, 4-21
COMMON pseudo-op, SABR, 4-21
COMPARE command,
CCL,1-58
EPIC, 2-92
Compatability, DECsystem 10 files,
2-116
Compilation of FORTRAN IV
source file, 8-3
COMPILE command, CCL, 1-59
Compile time diagnostics, BASIC,
6-115, 6-116
Compiler, FORTRAN II
error messages, 7-54
loading and operating, 7-1
suppressing output, 7-5
Compiler, FORTRAN IV, 8-9
run time options, 8-12
error messages, 8-14, 8-15
Complex constants, FORTRAN IV,
8-69
Computed' GOTO,
FORTRAN II, 7-30
FORTRAN IV, 8-81
Conditional assembly pseudo-operators, PAL8, 3-30
Conditional delimiters, P AL8, 3-21
Conditional execution commands,
TECO, 2-158, 2-159
Conditional pseudo-op, SABR, 4-19
Conserving storage space, FORTRAN II, 7-35
Console terminal as I/O device,
FORTRAN IV, 8-37

rnn
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : No
XMP Toolkit : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-21:37:19
Create Date : 2003:04:20 18:12:29-07:00
Modify Date : 2016:11:05 10:16:34-07:00
Metadata Date : 2016:11:05 10:16:34-07:00
Producer : Adobe Acrobat 9.0 Paper Capture Plug-in
Format : application/pdf
Document ID : uuid:84bb3643-3ea1-264e-bd2c-a2378127b81a
Instance ID : uuid:45810e8d-bf4e-ea44-91b8-fda0cec299ca
Page Layout : SinglePage
Page Mode : UseOutlines
Page Count : 954

EXIF Metadata provided by EXIF.tools

OS8_Handbook_Apr1974 OS8 Handbook Apr1974

OS8_Handbook_Apr1974 OS8_Handbook_Apr1974

Navigation menu

Versions of this User Manual:

Views

Navigation