Digital PDFs

DEC-S8-OSHBA-A-D.

April 1974

954 pages

Original

33MB

Document:	OS8 Handbook Apr1974
Order Number:	DEC-S8-OSHBA-A-D.
Revision:
Pages:	954
Original Filename:	http://bitsavers.org/pdf/dec/pdp8/os8/OS8_Handbook_Apr1974.pdf

OCR Text

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

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

DECtape Systems ........ ..................................................... 1-1
TC01/TC08 DECtape Users ...................................... 1-2
TD8E DECtape Users ................................................ 1-4
LINCtape (PDP-12) Users .......................................... 1-9
Building OS/8 From Cassette ........ .............. ........ ........ .... 1-10
Loading System Programs From Cassette ........................ 1-15
Building OS/8 From Paper Tape .................................... 1-17
Loading System Programs From Paper Tape .................. 1-20
Disk as the System Device ................................ :............... 1-25
RF08 and DF32 Disks ................................................ 1-26
RK8E Disk .................................................................. 1-26
RK8 Disk .................................................................... 1-28
Restarting OS/8 .............................. :................. ~ ............. 1-29
Keyboard Monitor ....................................................... ........ 1-30

System Conventions .................................... :................... 1-30
Permanent Device Names ......... ,...-: .............................. 1-30
File Names and Extensions ........................................... 1-32
Using the Keyboard Monitor ........................................... 1-33
Keyboard Monitor Commands .................................... 1-35
Keyboard Monitor Error Messages ..................... ............. 1-42
Coinmand Decoder .............................................................. 1-45

Command Decoder Input String ...................................... 1-45
Examples of Command Strings .....: .............................. 1-48
Input/Output Specification Options ............................ 1-49
Command Decoder Error Messages ................. :.............. 1-51
xi

CCL (Concise Command 'Language) .................................. 1-52
CCL Commands .............................................................. 1-53
CCL Command Format .............................................. 1-53
CCL Command Options .............................................. 1-54
Wild Card Construction ........... ~ .................................. 1-55
Indirect Commands (@ Construction) ........................ 1-56
Nonstandard File Names (# Construction) ...... ............ 1-57
CCL Error Messages ........................................................ 1-75
Symbolic Editor .............. .................................................... 1-78
Calling and Using the Editor ............................... "............ 1-78
Editor Options ............................................................ 1-79
Special Key Commands to the Editor .............................. 1-80
. Editor Text Buffer ................................................ .......... 1-82
Text Collection ............................................................ 1-82
Search Mode .................................................................... 1-83
Single Character Search .............................................. 1-83
Character String Search .............................................. 1-84
Editor Error Messages .................................................... 1-89
Example Using the Editor ................................................ 1-91
Summary of Editor Commands ........................................ 1-92
Peripheral Interchange Program (PIP) ................................ 1-97
Calling and Using PIP ...................................................... 1-97
PIP Options ................................................................ 1-98
Examples of PIP Specification Commands .................. 1-102
Additional Information Words in File Directories .......... 1-105
PIP Error Messages .. ............ ...... ........................... ......... 1-106
Absolute Binary Loader (ABSLDR) .................................... 1-108
Calling and Using ABSLDR ............................................ 1-108
ABSLDR Options ................................................. :...... 1-110
Examples of Input Lines ......................................... ..... 1-111
Notes on Using ABSLDR Correctly ................................ 1-112
ABSLDR Error Messages ................................................ 1-113
Octal Debugging Technique (ODT) .................................... 1-113
Features .......................................................................... 1-113
Calling and Using ODT .................................................. 1-114
xu

Commands ..... _~ ........._...................... _... ~ ..~.................... 1-115.
Special Characters ,....................................................... 1-115
Illegal Characters ....................................................... : 1;.117
Control Commands ...................................................... 1-117
Additional Techniques .................................................... 1-121
Current Location ............ ;........ ~ .................................. 1-121
Indirect References ........................................................ 1-121
Errors ..................................................................... ,......... 1-122
Programming Notes Summary.:........................................ 1-122
Summary of ODT Commands .......................................... 1-122

CHAPTER 2

UTILITY PROGRAMS

BATCH .... .... ........ . .. ........................................................ , ........................................................................ . 2-1 .
Introduction .................................................................... 2-1
Batch Processing Under OS/8 .......... :.............................. 2-2
BATCH Monitor Commands .......................................... 2-4
The BATCH Input File .................................................. 2-7
BATCH Error Messages .................................................. 2-10
Running BATCH From Punched Cards .......................... 2-12 .
Restrictions Under OS/8 BATCH .................................. 2-13
BATCH Demonstration Program .................................... 2-16
Loading and Saving BATCH ..................... ...................... 2-22
Loading and Saving Programs 'for Use Under BATCH .. 2-22
Transferring the System Software from
Cassette to the System Device ..................................... . 2-22
~

BITMAP .............. ................................................ ....... ....... 2-26
Hardware and Software Requirements ......... ,.................. 2-26
Loading BITMAP ...................................................... ~ ..... 2-26
BITMAP Output .............................. ......... ........... .......... 2-28
BITMAP Error Messages .............................................. 2-30
Assembly Instructions ...................................................... 2-30
BOOT ................................................................................... 2-32
Xlll

BUILD ........................................................ :........................ 2-34
OS/8 Device Handlers .............. ..... ....... ......... ....... .......... 2-34
DECtape (LINCtape) Systems .................................... 2-35
, Cassette Systems .......................................................... 2-36
Paper Tape Systems .... ....... .............. ...... .............. ....... 2-36
Calling and Using BUILD .............................................. 2-38
BUILD Commands .................................. _.................... ;. 2-40
The Hyphen Construction .......................................... 2-41
PRINT ......................................................................... 2-41
QLIST ......................................................................... 2-42
LOAD .......................................................................... 2-42
INSERT ..................................................... ~................ 2-44
DELETE ..................................................................... 2-45
REPLACE ............ ,..................................................... 2-46
UNLOAD .................................................................... 2-47
NAME ........... :.......................... :................................. 2-48
ALTER ...................................................................... 2-49
EXAMINE .................................................................. 2-49
DSK ................... ;..................... :.................................. 2-49
CORE .................................................. :....................... 2-50
DCB· ............................................................................. 2-51
CTL ............................................................................ 2-51
VERSION .................................................................. 2-52
SYSTEM .................................................................... 2-52
BUILD ......................................................................... 2-53
BOOTSTRAP ............................................................ 2-54
BUILD Error Messages .................................................. 2-55
BUILD Device Hand.Ier Format ...................................... 2-56
Header Block .............................................................. 2-57
Descriptor Block .......................................................... 2-57
Breakdown of DCB Word ............................................ 2-59
Entry Point Offset ......... :.............................................. 2-60
CAMP .................................................................................. 2-62
CAMP Commands .................. :....................................... 2-62
BACKSPACE .............................................................. 2-62
EOF ............................................................................ 2-63
HELP .......................................................................... 2-64
REWIND' ................... :................................................ 2-64
SKIP ............................................................................ 2-64

xiv

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

Cross-Reference Program (CREF) .....: ................................ 2-69
Calling and Using CREF ...................................... ;......... 2-69
CREF Options ............................................................ 2-69
Examples of CREF Usage .......................................... 2-70
Pseudo-Op Handling ........................................................ 2-71
Interpreting CREF Output ................ :-............................. 2-72
Restrictions .................................'.. ................................... 2-73
CREF Error Messages .................................................... 2-76
·DIRECT .............................................................................. 2-77
Calling and Using DIRECT .. .................... ...................... 2-77
DIRECT Options ........................................................ 2-78
DIRECT Examples ...... :...........
2-79
DIRECT Error Messages .........................................
2-81
! .................................
! ......

EPIC .................................................................................... 2-83
Introduction .................................................................... 2-83
Loading EPIC ............................................................... ~.. 2-83
Restart Procedure ............................................................. 2-84
Paper Tape Facility .......................................................... ·2-84
Command Format .......... :................................................. 2-84
Default Options .............................................................. 2-85
Error Conditions ............................................................ 2-86
Low-Speed I/O .............. ..... ... ...... ...... .... .... ...... .... .......... 2-86
Device Codes .................................................................. 2-87
Editing Capability ........................................................... ~ 2-88
Initial Command Format ...................... :..................... ·2..:88
Editing Commands ...................................................... 2-88
Compare Capability ......................................... :............. ,. 2-91
Command Format ...................................................... 2-91
Error Messages ................................................................ 2-92
Paper Tape Format ................................................ :. ...... 2-95
Loading EPIC From Paper Tape .................................. ' 2-95
EPIC Assembly Instructions ...................................... :... 2-96
xv

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

Calling FOTP .......... ...................................................... 2-97
Input Specifications .................................................... 2-97
Output Specifications .................................................. 2-99
Using FOTP .................................................................... 2-99
Advantages of Predeletion .......................................... 2-103
Advantages of Postdeletion .......................................... 2-103
Control Characters ...................................................... 2-103
FOTP Options ................................................................. 2-104
Examples of FOTP Specification Commands ............ 2-106
Error Messages ................................................................. 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 .. ............ ......... ............. ............ 2-116
PIPI0 Options ................................................................ 2-117
PIP 10 Examples .............................................................. 2-118
Error Messages ................................................................ 2-119
RESORC ............................................................................. 2-121

Calling and Using RESORC ............................................ 2-121
RESORC Options ............................................................ 2-122
Fast Mode (IF Option) ................................................ 2-122
Limited Mode (lL Option) ........................................ 2-122
Extended Mode (IE Option) ........................................ 2-124
RESORC Error Messages................. ................. .............. 2-127
Source Compare (SRCCOM) -.............................................. 2-128

SRCCOM Assembly Instructions .................................... 2-128
Loading SRCCOM ..............'............................................ 2-128
SRCCOM Output ............................................................ 2-129
Error Messages ................................................................ 2-131
XVl

TECO .................................................................................. 2-132
Introduction ........................................................... ;.-....... 2-132
Introductory Commands .................................................. 2-132
TECO Character Set ...................................................... 2-142
File Specification Commands .................................. ~....... 2-144
Page Manipulation Commands ........................................ 2-146Buffer Pointer Manipulation Commands ........................ 2-147
Text Type-Out Commands .............................................. ·2-148
Deletion Commands ........................................................ 2-149
Insertion Commands ........................................................ 2-150
Search Commands ................................................... ;... ... 2-151
Match Control Characters .......................... ,..................... 2-154
Command Loops .......................................... ............. ...... 2-155
Q-Registers .................................. ..................................... 2-155
Branchi~g Commands ..................... :................................ 2-157
Conditional Execution Commands .................................. 2-158
Numeric Arguments ........................................................ 2-160
Programming Aids .......................................................... 2-164
Error Messages ....................................................... ,........ 2-166
Manipulating Large Pages ........................................ :..... -2-167
Techniques and Examples ....................... :...................... 2-168
Running TECO on the PDP-12 ...................................... 2-172
Using TECO to Retrieve Lost Files ................................ 2-177
Incompatibilities Between OS/8 TECO and
DECsystem-10 TECO ................................................ 2-178
Assembly Instructions ...................................................... 2-183
Error Messages ................................................................ 2-184

CHAPTER 3 PAL8

Introduction ........................................................................ 3-1
Calling and Using PAL8 ...................................................... 3~1
. Character Set ...................................................................... 3-5
XVll

Statements .......................................................................... 3-6
Labels .............................................................................. 3-6
Instructions ...................................................................... 3-6
Operands ........................................................................ 3-6 ,"
Comments ........................................................................ 3-7
Format Effectors .................................................................. 3-7
Form Feed ...................................................................... 3-7
Tabulations ..... ......... .................... ..................... ....... ........ 3-7
Statement Terminators ..................................................... 3-7
Numbers .............................................................................. 3-9
Symbols .............................................................. ~ .......... ~...... 3-9
Permanent Symbols .......................................................... 3-9
User-Defined Symbols ................................................ -,: ..... 3-9
Current Location Counter ................................................ 3-10
Symbol Table .................................................................. 3-11
Direct Assignment Statements ................... ~ .................... 3-12
Symbolic Instru~tions .............................................'.. :...... 3-13
Symbolic Operands ..................................................... ~.... 3-14
Internal Symbol Representation for PAL8 ...................... 3-14
Expressions .......................................................................... 3-14
Operators ............................................. :.......................... 3-14
Special Characters .......................................................... 3-18
PAL8 Instructions .................'.............................................. . 3-22
Memory Reference Instructions ..................................... . 3-22
Indirect Addressing ......................................................... . 3-23
. t ruet'Ions .......................................................... .. 3-23
M ·IcrOlns
Operate Microinstructions ......................................... . 3-24
Input/Output Microinstructions ................................. . 3-26
Autoindexing ................................................................... . 3-26
Pseudo-Operators .......................... :.................................... . 3-26
Indirect and Page Zero Addressing .............................. .. 3-27
Radix Control .............................................................. .. 3-27
Extended Memory ......................................................... . 3..:rJ
End-of-File ..................................................................... . 3-29
XVlll

Resetting the Location Counter ......... ... ........ ...... .............. 3-29
Entering Text Strings ...................................................... 3-29
Suppressing the Listing .................................................... 3'::30
Reserving Memory .. ..... ........ ........... .............. ...... ... ......... 3-30
Conditional Assembly Pseudo-Operators .................. ~ ... 3-30
.Controlling Binary Output .......................................... .... 3-31
Controlling Page Format.... ....... ....... ..... .......... .... ............. 3-31
Typesetting Pseudo-Operator .......................................... 3-32
. Calling OS/8 User Service Routine ......... ~ ...........: ............ 3-32
Relocation Pseudo-Op .................................................... 3-33
. Altering the Permanent Symbol Table ....... :.................... 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

Operators: ........................................................ ~ .......~ ....... 4-6
Operands .............. N........................................................ 4-7
. Constants .................................................................... 4-7
Literals ................................... :.................................... 4-8
Parameters .................................................................. 4-9
Symbols ........................................................................ 4-9
Comments ........................................................................ -4-10
IncreDtenting Operands ............. ~.......................................... 4-11
4-12
Pseudo-Operators ......................................................
Assembly Control ............. ~ .............. :............................... 4-16
Symbol Definition .................................................... ......... 4-20
Data Generating .............................................................. 4-22
H

........

Subroutines ............................................... ,.......................... 4-24
CALL and ARG .. .............. ........................ ...................... 4-25
ENTRY and RETRN ...................................................... 4-27
Example .......................................................................... 4-28
Passing Subroutine Arguments ............................................ 4-29
DUMMY ....................................................................... ; 4-29
SABR Operating Characteristics .......................................... 4-32
Page-by-Page Assembly ............................................. , .... 4-32
Page Format ............................................ :................... 4-33
Page Escapes ................................................................ 4-33
Multiple Word Instructions .............................................. 4-34
Run-Time Linkage Routines .. ........................ .................. 4-34
Skip Instructions ............................................................... 4-37
Program Addresses ........................................................... 4-38
The Symbol Table ............................................................ 4-38
Symbol Table Flags ..................... .......................... ..... 4-38
The Subroutine Library ...................................................... 4-39
Input/Output .................................................................. 4-40
Floating-Point Arithmetic .......................................... ,.... : 4-41
Integer Arithmetic .................................................... ,..... 4-43
Subscripting ...................................................................... 4-43
Functions ........................................................................ 4-44
xx

Utility Routines ...........................~ ...................................... 4-45
DECtape I/O Routines ............... :.................................... 4-47
The Binary Output Tape ....................................................... 4-49
Loader Relocation Codes .............................'................... 4-49
Sample Assembly Listings,.................................................... 4-53
SABR Programming Notes ........................................ .......... 4-57
Optimizing SABR Code .................................................. 4-57
Calling the OS/8 USR and Device Han9lers .................. 4-60
The Linking Loader .............................~ .............: ........... ~ .... 4-62
Calling and Using the Linking Loader ............................ 4-62
Linking Loader Options .............................................. 4-63
Examples of I/O Command Strings ............................ 4-66
Linking Loader Error Messages ...... ~............................... 4-67
Library Setup (LIBSET) ...................................................... 4-68
Calling and Using LIBSET ................................... :.......... 4-68
LIB SET Options .......................................................... 4-69
Examples of LIB SET Usage ................... :.................... 4-69
Subroutine Names .................................................. ~ ......... 4-70
Sequence for Loading Instructions ........ ........... ..... .......... 4-70
LIBSET Error Messages .................................................. 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"

Instructions ...................................................................... 5-2
Expressions ...................................................................... 5-2
Comments .................... ........... .......... .......... ... ..... ......... .... 5-3
Arithmetic and Logical Operators ...................................... 5-3
PDP-8 Operation Codes ................. " ................................... 5-4
PDP-8 Mode Addressing ...................................................... 5-6
FPP Symbols ................ ,.. ~ .................................................. 5-7
Data Reference Instructions ......................................... '" 5-7
Special Format 1 '" .~... .................................. ................ 5-9
a
~peclal rormaL .t. ....................................................... '"
..--./
Special Format 2-Conditional Jumps ......................... 5-10
Special Format 2-Pointer Moves '" ....... ,. ....... ........... 5-10
Special Format 3 ...............................: .......................... 5-11
Special.Format 3-0perate ........................................ 5-12
,.,

."1

T""1

1"\

FPP Mode Addressing ........................................................ 5-13
Literals ............ ,.. " ......... ,.. '" .................. " .......... '" . .. .. . . ... .. . . . 5-1 5
Links .................................................................................... 5-16
Data Specification ................................................................ 5-16
Pseudo-Operators ....... ......................................................... 5 -16
== (equate) ...................................................................... 5-17
OCTAL .......................................................................... 5-17
DECIMAL ....................................... ............ .... ................ 5-17
PAGE .............................................................................. 5. . 17
BASE .............................................................................. 5-17
TEXT ............................................................................... 5-17
END ................................................................................ 5-18
INDEX .............................. ,............................................. 5-18
ORG ................................................................................ 5-18
ZBLOCK ........................................................................ 5-18
LISTOF .......................................................................... 5-18
LISTON· .......................................................................... 5-18
'XXll

IF .................................................................................... 5-19
REPEAT ........................................................................ 5-20
S ....................................................................................... 5-20
F ...................................................................................... 5-21
E ...................................................................................... 5-21
ADDR ........................................................... ;-................ 5-21
COMMON ................................................... ;.................. 5-21
COMMZ .................
5-21
DPCHK .......................................................................... 5-21
ENTRY, ............................................ .1............................. 521
EXTERN ......................................................... :.............. 5-21
FIELD 1 ............................ ~............................................. 5-21
SECT ............................................................................... 5-22
SECT8 ......":....... ................................. ....... ...................... 5-22
u

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

Referencing Memory ................................................... -....... 5-22
RALF Features ................................. ............ ..................... 5-24
Core Allocation ................................................................ 5-25
RALF Programming Notes ........................................... :.. 5-29
Using the Assembler ........................ :................................... 5-37
Error Messages ............................................................ ~ ....... 5-38

CHAPTER 6 BASIC
Introduction to OSj8 BASIC ................................... ~., ........ 6-1
Running BASIC ......... .......... ........... ... .... ............... .......... 6-1
Entering the New Program .......................................... 6-2
Executing the Program ....._..... ........ .............................. 6-3
Correcting the Program .............................................. 6-3
Interrupting Execution of the Program ........................ 6-4
Leaving the Computer .................................................. 6-4
Example of an OS/8 BASIC Run ... ............................. 6-4
OS/8 BASIC Overview............ ......... .... ................. ... ..... 6-5
General System Description ............................. u.~ ••••••• 6-5
OS/8 BASIC Statements and Commands ................... , 6-5

xxm

os /8 BASIC Arithmetic...................................................... 6-6
Numbers ........................................ .................................. 6-6
Variables .................................................................. :....... 6-8
Arithmetic Operations ...................................................... 6-8
Priority of Arithmetic Operations ................................ 6-9
Parentheses .................................................................. 6-9
Relational Operators .................................................... 6-10
Rules for Exponentiation ............................................ 6-11
OS/8 BASIC Statements ....................................................... 6-11
Statement Numbers .......................................................... 6-13
REMARK-The Commenting Statement ...................... 6-14
Statements for Terminating a Program ............................ 6-14
END ............................................................. ;................ 0-14
STOP .......................................................................... 6-14
LET-The Assignment Statement .................................. 6-15
Input/ Output Statements and Functions .......................... 6-15
The INPUT Statement ............ :................................... 6-15
The PRINT Statement ................................................ 6-16
The T AB(X) ·Function ....... ................. ......... ............... 6-21
The PNT(X) Function ..... ,.......................................... 6-21
The READ and DATA Statements ................................ 6-22
RESTORE ....... ;............................................... 'l'. . . . . . . . . . . . . . 6-23
Control Statements .......................................................... 6-25
GOTO .......................................................................... 6-25
IF-THEN and IF-GOTO ............................................ 6-26
Loops .................................................................................. 6-27
FOR and NEXT Statements ............................................ 6-27
Nesting Loops ........... :....................................................... 6-29
Lists and Tables ................................................ ;................. 6-30
Subscripted Variables ...................................................... 6-30
The DIM Statement ........................... ............................. 6-31
OS/8 BASIC Functions and Subroutines ........................... . 6-33
General Information on OS/8 BASIC Functions ........... . 6-33
'h metic
. F unctIons
.
.
.....................................................
. 6-34
A rit
The Random Number Function-RND(X) .............. .. 6-34
XXIV

The Sign Function-SGN(X) ...................................... 6-36
The Integer Function-INT(X) .......................... ~ ....... 6-37
The Absolute Value Function-ABS(X) .................... 6-37
The Square Root Function-SQR(X) .......................... 6-38
Transcendental Functions ................................................ 6-3'8
The Sine Function-SIN(X) ........................................ 6-38
The COSINE Function-COS(X) .............................. 6-38
The Arctan Function-ATN(X) .............................~.. 6-39
The Exponential Function-EXP(X) ......................~... 6-39
The Natural Logarithm Function-LOG(X) .............. 6-39
User Defined Functions ....................... ;............................ 6-39
The FNA(X) Function and the DEF Statement .......... 6-39
The UDEF Function Call and the USE Statement ...... 6-40
, The Debugging Function-TRC(X) ................................ 6-42
Subroutines ...................................................................... 6-43
GOSUB and RETURN. ........ ........ ...... ... .......... ..... ....... 6-43
Nesting Subroutines .................................................... 6-45
Alphanumeric Information (Strings) .................................... 6-46

String Conventions ....... ~:................................................. 6-46
Constants and Variables .............................................. 6-46
Dimensioning Strings .................................................. 6-46
InpnttingString Data .................................................. 6-47
Strings in LET and IF-THEN Statements .................... 6-49
String Concatenation ........... ,' ............................ ,........... 6-50
String Handling Functions .............................................. 6-50
The LEN Function ..................................... ;................ 6-50
The ASC and CHR$ Functions ...... ! .......... ; ................ 6-51
The VAL and STR$ Functions.. .......................... ........ 6-52
, The POS Function ...................................................... 6-53
The SEG$ Function .................. ~ ................................., 6-53
The DAT$ Function ....... :................................ ;........... 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 OLD Command ....................................................... . 6-58
The NAME Command .................................................. .. 6-59
The SAVE Command ..................................................... . 6-59
The RUN and RUNNH Commands ............................... . 6-60
The BYE Command, ....................................................... . 6-60
Files, File Statements, and Chaining ................................... . 6-60
General Information on- OS/8 BASIC Files ................... . 6-60
System Devices ........................................................... . 6-60
File Statements .............................................................. .. 6-61
Creating Assembly Language Functions ............................. . 6-69
Introduction .................................................................... . 6-69
The OS/8 BASIC System ............................................... . 6-70
The OS/8 BASIC Run-Time System ............................. . 6-71
BRTS Core Layout ............... :..................................... . 6-71
BRTS Overlays ......................................................... . 6-72
BRTS Symbol Tables ................................................. . 6-73
Data Formats ................................................................. . 6-73
Variables ..................................................................... . 6-73
Strings ...............................................-.... :..................... . 6-74
Incore DATA L1st .................................................... .. 6-75
The String Accumulator (SAC) .................................. .. 6-76
BRTS Symbol Table Structure ...................................... .. 6-76
The Scalar Table ......................................................... . 6-77
The Array Symbol Table .......................................... .. 6-77
The String Symbol Table ..... :.................................... .. 6-78
The String Array Table ............................................. . 6-79
Floating-Point Operations ............................................... . 6-80
Floating-Point Accumulator ....................................... . 6-80
Floating-Point Routines ............................................. . 6-81
Floating-Point Operations ........................................... . 6-85
BRTS Subroutines ......................................................... . 6-85
Subroutine ARGPRE ................................................. . 6-85
Subroutine XPUTCH ................................................. . 6-86
Subroutine XPRINT ................................ _.................. .. 6-87
Subroutine PSWAP .......................................... :.......... . 6-87
Subroutine UNSFIX ................................................... . 6-88
Subroutine STFIND .................................................. .. 6-88
Subroutine BSW ..................................................... :.. .. 6-90
XXVI

Subroutine MPY .......................................................... 6-90
Subroutine DLREAD .................................................. 6-90
Subroutine ABSVAL .................................................. 6-91
Passing Arguments to the User Function ........................ '6-91
Using the USE Statement ....................... :.................... 6-93
BRTS I/O ...................................................................... 6-94
Terminal I/O .............................................................. 6-94
BRTS File Formats .................................................... 6-95
BRTS Buffer Space ................................ :..................... 6-95
BRTS Device Driver Space ........................................ 6-96
The BRTS I/O Table .................................................. 6-96
Interfacing the Assembly Language Function to BRTS .. 6-97
General- Considerations and Hints.................................... 6-100
Routines Unusable by Assembly Language
Functions ........... ...................................................... 6-100
Using OS/8 .................................................................. 6-101
Page 0 Usage ......................--: ....................................... 6-102
Assembly Language Function Examples .............. :........... 6-102
Compile-Time Diagnostics .................................................. 6-115
Run-Time Diagnostics ........................................ ................. 6-116

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

Introduction .................................................................... 6-124
General Description ........................................................ 6-124
Preparing BASIC for LAB8/E Functions ...................... 6-125
Definition of LAB8/E Support Functions ..... ~................ 6-126
LAB8/E Examples .......................................................... 6-136
Getting on the Air with BASIC ...... ~ ............................... 6-147
LAB8/E Function Summary .......................................... 6-148
CHAPTER 7 FORTRAN II
Introduction ................... ,................................. , .... .... .. .. .... .. 7-1

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

FORTRAN Options .................................................... 7-1
Example Program ............................................ :........... 7-3
Examples of FORTRAN I/O
Specification Commands .............................................. 7-4
Using FORTRAN or SABR with the Interrupt On ........ 7-6
Using PAL8 with SABR or FORTRAN ........................ ".. 7-7
FORTRAN II Source Language.......................................... 7-8

Character Set ................................................................... 7-8
FORTRAN Constants ........................... :......................... 7-8
Integer Constants ........................................................ 7-8
Real Constants ............................................................ 7 -9
Hollerith Constants ...................................................... 7-9
FORTRAN Variables ................. """ .. ,, ......................... 7-9
Integer Variables ......................................................... 7-10
Real Variables ........................................................... 7-10
Scalar Variables .......................................................... 7-10
Array Variables .......................................................... 7-11
Subscripting .. ................. ................................. ............ 7 -11
Expressions' ................................................ :..................... 7-12
FORTRAN Statements ........................................................ 7-14

Line Continuation Designator ........................................ 7-14
Comments ........................................................................ 7-15
Arithmetic Statements ...................................................... 7-16
Input/Output Statements ..... ......... ....... .............. ............. 7-16
Data Transmission Statements .................................... 7-17
FORMAT Statement .................................................. 7-21
Control Statements ................................................... :~ ..... 7-29
GO TO Statement .:...................................................... 7-29
IF Statement ............................ :................................... 7-30
DO Statement .............................................................. 7-30
CONTINUE Statement ................................................ 7-32
PAUSE, STOP, and END Statements ........................ 7-32
Specification Statements .................................................. 7-33
COMMON Statemenf ................... ................... ..... ....... 7-34
DIMENSION Statement...................................... ........ 7-34
EQUIVALENCE Statement .............................. .......... 7-35
Subprogram Statements............... ............ .................. ....... 7-35
Function Subprograms ................................................ 7-36
XXVlll

Subroutine Subprograms .............................................. 7-37
Function Calls .................................................... :.......... 7-40
Function Library ...........................................'...... ................. 7-40
Floating-Point Arithmeti~ .................................................... 7-42
Device Independent I/O and Chaining. ................................ 7-42
The IOPEN Subroutine .................................................. 7-42
The OOPEN Subroutine .................................................. 7-43
The OCLOSE Subroutine ... :....... :.................................. 7-44
The CHAIN Subroutine .................................................. 7-44
The EXIT Subroutine .................................................... 7-44
DECtape I/O RQutines ............................ ............................ 7-44
-..

OS /8 FORTRAN Library Subroutines .............................. 7-47
Mixing SABR and -FORTRAN Statements ........................ 7-50
Size of a FORTRAN Program ............................................ 7-50
FORTRAN Statement Summary ........................................ 7-51
FORTRAN Error Messages ,.............................. :................ 7-54
Compiler Error Messages ..................'............................ ~. 7-54
Library Error Messages .................................................. 7-55
CHAPTER 8

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

8-65
8-67
S-67
8-70
Pv ....... roClC';nnc
8-72
Assignment Statements ............................................... . 8-76
Arithmetic Statements ............................................... . 8-77
The GO TO Assignment Statement ........................... . 8-78
Control Statements ....................................................... . 8:. 80
GO TO Statements ................................................... . 8-80
IF Statements ..... .' ..................................................... . 8-82
DO Statement .......................................................... .. 8-83
CONTINUE Statement ............................................ .. 8-86
PAUSE Statement ................................................... . 8-88
STOP Statement ....................................................... . 8-88
END Statement ....................................................... . 8-88
DATA Transmission Statements' ................................ .. 8-88
FORMAT Statement .............................................. .. 8-89
DEFINE FILE Statement .................. :................... .. 8-100
Input/Output .Statements ........................................... 8-101
Device Control Statements ...................................... .. 8-106
Specification Statements ............................................... . 8-107
Storage Specification Statements .............................. .. 8-107
The DATA Statement ............................................ .. 8-112
Type Declaration Statements ................................... . 8-114
Subprogram Statements ............................................... . 8-114
Functions ................................... :............................. . ·8-115
Subroutine Subprograms ............. :............................. . 8-117
RETURN Statement ............................................... . 8-119
BLOCK DATA Statement ............... :...................... .. 8-119.
EXTERNAL Statement ........................................... . 8-120

'FORTRAN IV Source Language ................................... .
Constants, Variables, and Expressions ....................... .
Constants ................................................................. ..
Variables ................................................................... .
L...J.l1.J:-'.l.\o.Ia.:J~.1V.1.1..03

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 ••

xxx

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

8-124

FORTRAN IV Plotter Routines .......,.... :........................... .
Plotter Operation ......................................................... .
Plotter Commands ........................................................ .
PLOTS ..................................................................... .
XPLOT ................................................................... .
FACTOR ................................................................. .
WHERE ................. :................................................. .
SYMBOL ................................................................. .
NUMBER .................................................,.............. .
PSCALE ................................................................. ..
AXIS ....................................................................... .
LINE ....................................................................... .
PLEXIT ................................................................... .
Implementing the Plotter Routines ............................... .
Getting Started ........................................................ ..
Adding the Plotting Routines .................................. ..
Examples ................................................................. :... ,.

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 A Character Codes
Appendix B Loading Procedures ..................................... .
Appendix C Permanent Symbol Table .......................... ..
,Appendix D OS/8 Demonstration Run ........................... .
Appendix E OS / 8 Error Message Summary .................. ..
Appendix F OS/8 File Name Extensions ......................... .
Appendix G OS /8 Device Handlers ............................... .
Appendix 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
Cassette Bootstrap ..................................... . 1-11
Table 1-5
System Devices ........................................... . 1-12
Table 1-6
System Devices ........................................... ~ _ 1-18
Table 1-7
RF08/DF32 Disk Bootstrap ......... ~: ............ . 1-26
Table 1-8
Single RK8E Disk Bootstrap ...................... .. 1-27
Table 1-9
Multiple RK8E Disk Bootstrap .................. .. 1-27
Table 1-10 Single RK8 Disk Bootstrap ....................... . 1-28
Table 1-11 Multiple RK8 Disk Bootstrap .................. .. 1-29
Table 1-12 Permanent Device Names .......................... .. 1-31
Table 1-13 Assumed Ex.'tensions ................................... . 1-32
Table 1-14 Keyboard Monitor Error Messages ............. . 1-43
Table 1-15 Command Decoder Error Messages ........... . 1-51
Table 1-16 CCL Options ............................................. . 1-55
Tabie 1-17 Compiler / Assembiertxtensions ............... . 1-59
Table 1-18 CCL Error Messages ................................. . 1-75
Table 1-19 Editor Options ........................................... . 1-79
Table 1-20 Editor Key Commands ............................... . 1-80
Table 1-21 Special Characters .................................... .. 1-81
Table 1-22 Editor Error Codes .................................. .. 1-89
Table 1-23- Symbol Editor Commands ........................ .. 1-93
Table 1-24 PIP Options .............................................. .. 1-98
Table 1-25 PIP Error Messages ................................... . 1-106
Table 1-26 ABSLDR Options .................................... .. 1-110
Table 1-27 ABSLDR Error Messages :......................... .. 1-113
Table 1-28 ODT Command Summary ......................... . 1-122
Table· 2-1
Run-Time Options .................................... .. 2-3
BATCH Monitor Commands .................. .. 2-5
Table 2-2
BATCH Error Messages ........................... . 2-10
Table 2-3
BITMAP Options ..................................... . 2-27
Table 2-4
BOOT Mnemonics ..................................... . 2-33
Table 2-5
Standard DECtape System Device Handlers 2-35
Table 2-6
Table 2-7
Standard Cassette System Device Handlers 2-36
Table 2-8
Standard Paper Tape System Device
Handlers ..................................................... . 2-37
OS/8 Device Handlers ............................... . 2-38
Table 2-9
Table 2-10 BUILD Editing Characters ....................... . 2-39
Table 2-11 BUILD Error Messages ............................. . 2-55
Table 2-12 DeB Word ................................................. . 2-59
Table 2-13 CAMP Error Messages ............................ .. 2-67
Table 2-14 CREF Options .............................. \........... .. 2-69
XXXll

Table 2-15 CREF Error Messages ...................... :......... 2-76
Table 2-16 DIRECT Options ......................~.................. - 2-78
Table 2-17 DIRECT Error Messages ............................. 2-81
Table 2-18 EPIC Commands ........... :............................ 2-89
Table 2-19 EPIC Error Messages ................................ 2-93
Table 2-20 FOTP Options ............................................ 2-104
Table 2-21 FOTPError Messages ................................ 2-108
Table 2-22 MCPIP Options ......................................... ~ 2-111
Table 2-23 MCPIP Error Messages ........... .......... ......... 2-114
. Table 2-24 RESORC Device Types .............................. 2-123
Table 2-25 .;Kinds of Handlers ...................................... 2-125
Table 2-26 "' RESORC Error Messages .......................... 2-127
Table 2-27 Run-Time Options ............. ~........................ 2-129
Table 2-28 Restrictions .on Special Characters .............. 2-142
Table 2-29 File Specification Commands ...................... 2-145
Table 2-30 Page Manipulation Commands........... ......... 2-146
Table 2-31 Buffer Pointer Manipulation Commands .... 2-147'
Table 2-32 Text Type-Out Commands ........................ 2-148
Table 2-33 Text Deletion Commands .......................... 2-149
Table 2-34 Text Insertion Commands ......... ....... ....... ... 2-150
Table 2-35 Search Commands ...................................... 2-151
Table 2-36 Match Control Characters .......................... 2-154
Table 2-37 Q-Register Loading Commands ... ~.............. 2-156
Table 2-38 .Q-Register Execution Commands ......... :...... 2-157
Table 2-39 Conditional Execution Commands .............. 2-159
Table 2~40 Characters Associated with Numeric
__QuantItIes ................................................... . 2-161
Table 2·,,41 Arithmetic Operators ................................. . 2-163
Table 2-42 Radix Control Commands ......................... . 2-164
Table 2-43 Form Feed Processing Output Commands .. 2-168
Table 2-44 TECO Command Summary ....................... . 2-179
Table 2-45 TECO Error Messages ............................... . 2-184
. Table 3-1
PAL8 Run-Time Options .......................... .. 3-3
Table 3-2
Use of Operators ....................................... . 3-16
Table 3-3
PAL8 Error Codes; .................................... . 3-39
Table 4-1
SABR Options .......................................... .. 4-2
Table 4-2
SABR Pseudo-Operators ........................... . 4-13
Table 4-3
SABR Error Codes ..................................... . 4-61
Table 4-4
Linking Loader Options .......................... ;.. . 4-63
Table 4-5
Linking Loader E.rror Messages ................. . 4-68
I

xxxiii

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

LIBSET Error Messages ........................... .
Library Error Messages ............................. .
PDP-8 Operation Codes ............................. .
FLAP /RALF Error Codes ......................... .
FLAP /RALF Pseudo-Operators ........ "....... .
OS/8 BASIC Language Summary ............. .
Compile-Time Diagnostics ......................... .
Run-Time Diagnostics ............................... .
LAB 8/E Function Summary .................... ..
FORTRAN II Options ............................... .
Device Designations ................................... .
Numeric Field Codes ................................ ..
FORTRAN Function Library ................... .
FORTRAN II Library Subroutines ........... .
FORTRAN II Language Summary .......... ..
FORTRAN Library Error Messages ........ ..
Standard FORTRAN IV File Extensions ... .
FORTRAN IV Compiler Run-Time Options
FOR TRAN IV Compiler Error Messages ... .
RALF'Assembler Run-Time Options ....... .
Loader Run·Time Options ......................... .
Loader Error Messages ............................. .
Run-Time System Option Specifications .. ..
Run-Time System Error Messages ............. .
FORLIB Calling Relationships .................. ..
FORLIB MUltiple Entry Points by Section
CLOCK Subroutine FUNCTN Ar,guments
Truth Table for Logical Expressions ........ ..
Conversion Rules for Assignment Statements
Numeric Field Codes ................................. .
Magnitude of Internal Data ....................... .
Device Control Statements ...................... ~ .. .
FORTRAN IV Statement Summary .......... ..
FORTRAN IV Plotter Routines .............. ..
Special Symbols ......................................... .
Regular Characters .................... ~ ................ .

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

Sample BATCH Input File ..................... . 2-8
Punched Card Input File ......................... . 2-14
_TECO Command String for Example 2 '_~',' 2-173
TECO Flowchart for Example 2 ............... . 2-174
TECO Macro for Example 3 .................... .. 2-175
-Loading and Executing a TECO Macro ... . 2-175
File Packing Macro ................................. . 2-176
Loading and Running the File Packing
Macro ....................................................... . 2-176
Figure 2-9
'Unpacking Macro ..................................... . 2-176
Figure 2-10 Loading and Running the Unpacking Macro 2~177
Figure 3-1
Memory Reference Bit Instructions ........... . 3-22
Figure 3-2
Group 1 Operate Microinstruction
Bit Assignments ...................................... .. 3-24
Figure 3-3
Group 2 Operate Microinstruction
Bit Assignments ........................................ .. 3-24
Figure 3-4
Group 3 Operate Mkroinstruction
Bit Assignments ....................................... . 3-25
Figure 5-1
AMOn Function .... ,.................................. , 5-34
Preparing a FORTRAN IV Source File ... . 8-2
Fi!:!Ure 8-1
Figure 8-2
Compiling a Source File .. ~ .......................... . 8-3
Figure 8-3
Assembling, loading, and Executing a
RALF File ............................................... . 8-4
Figure 8-4
FORTRAN IV Coding Form ................... . 8-66
Figure 8-5
Nested no Loops ...................................... - 8-86
Figure 8-6
Spiral Plotter Example ............................. . 8-145
Figure 8-7
Histogram Plotter Example ..................... . 8-147

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

xxxv

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

345 678
000 000
110 001
111 1I 1
010 '. 010
I I I 110
III I I I
010 001
010 010
010 001
110 000
010 010
111 101
III 101 I t I
111 101 1I I
I 1I 110 001

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

91011
000
all

100
010
110
001
110
all

101
000
000
100
III

I I1
all

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 TO COpy FILES FRO'-1 UNI'I 0 TO UNI T 1
TYPE 2 TO ZERO THE DIRECTORY -OF UNIT 1
TYPE 3 TO LEAVE THE DI-RECTORY OF UNI T 1 ALONE
STRIKE 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

4000-

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

9
10
11
12
13
14
15
16

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

SWITCH REGISTER
SETTiNG

012
100

345
000

678
000

91011
000

AND THEN

press ADDR LOAD and
press EXTD ADDRLOAD
001 010 011 I 1I
lift DEP key
001 010 000 110
lift DEP key
110 I 1I 000 100 .. - lift DEP key
110 11 I 000 110 _ lift DEP key
110 111 000 011 " lift DEP key
101 010 000 100
lift DEP key
111 010 110 100
lift DEP key
110- 111 000 010
lift DEP key
111 110 001 000
lift DEP key
011 010 001 001
lift DEP key
011 110. on 110
lift DEP key
001 010 000 101
lift DEP key
110 111 000 100
lift DEP key
110 III 000 110
lift DEP key
001
111
000
lift
DEP key
110
lift DEP key
101 010 001 110
lift DEP key,
111 000 000 0.10
111 100 011 000
lift DEP key
001 110 011 .- 110
lift DEP key
1 11 000 010 010
lift DEP key
011 110 011 110
lift DEP key
111 -100 '010 -000
lift D EP key .
lift DEP key
010 .010 all 110
lift DEP key
010 010 011 101
lift DEP key
101 0.10 0.0.1 101
111 011 100 110,
lift DEP key
IlJ 000 000 010
lift DEi> key
011 010 011· 101
lift DEP key
101 010 OQO 001
lift DEP key
111 111 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

Device

Maximum n

DF32 (DF32 disk)
RF08 (RF08 disk)
RK8 (RK8 disk)
RK8E (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 TA8 A: CSA0- 1
lo! N 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.
1 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<CSA0:CCL.SV

'" SY s: DI RECT. SV< CSA0: 01 RECT. SV
ioSYS: FOTP. SV<CSA0: r OfP. SV
*SYS:PIP.SV<CSA0:PIP.SV
SY s: LI Ba. SV< CSA0: LI B8. SV
*SYS:EDIT.SV<CSA0:EDIT.SV

*SYS~PAL8.sv<csAe:PAL8.sV

iSYS:CREF.SV<CSA0:CREF.SV
~SYS:BITMAP.SV<CSA0:BITMAP.SV

i.SYS: BOOT. S\i<CSA0: BOOT. SV
*SYS:CAMP.SV<CSA0:CAMP.SV
*SYS:RK8FMT.S\i<CSA0:RK8rMT.SV
*SY S: RK EFMT. SV< CSA0: RK ErMT. SV
*SYS:FORT.SV<CSAl:FORT.SV
~SYS:SABR.SV<CSAl:SABR.SV

* SY S: LOADER. SV< CSA 1: LOADER. SV
*SYS: SRCCOM. SV<CSAl: SRCCOII\. SV
*SY S: EPI C. SV<CSA 1: EPIC. SV
iSYS:PIP10.SV<CSAl:PIP10.SV
.SYS:RESORC.SV<CSAl:RESORC.SV
*SYS:DTCOPY.SV<CSAl:DTCOPY.SV
*SYS:TDCOPY.SV<CSAl:TDCOPY.SV
*SYS:TDFRMT.SV<CSAlsTDFRMT.SV
iSYS:DTFRMP.SV<CSAl:DTFRMT.SV

5. The source file of CCL should be written onto the system device if the user desires to add his own CCL commands. To
write this file on the system device, mount the system cassette
DEC-S8-0SYSB-A-TC6 on cassette drive O. Respond as follows to the asterisk printed by MCPIP,

This completes the building of the OS/8 system. If the OS/8 extension cassette is available, see the appropriate chapters for loading instructions. Additional device handlers may be loaded and
made active using BUILD. See the BUILD section of Chapter 2
for this procedure.
1-16

Building OS/8 FromPaper.Tapes
An OS/8 system can be initially const.ructed on a mass storage
device from the paper tapes supplied with each OS/8 kit. The
paper tapes can be loaded from a low-speed reader on a Teletype
or from a high-speed reader. This initial construction i~ only necessary when the software is not supplied on DECtape or cassettes.
The system library program BUILD is used to construct an
OS/8 system from paper tapes in the following manner.
1. Load the RIM and Binary loaders into field 0 (refer to Appendix B for instructions on loading programs manually and on
paper tape).
2. Using the Binary Loader, load the BUILD binary tape (DECS8-0SYSB-A-PBl) into memory..
.
3. After the entire BUILD binary tape has been loaded with no
checksum errors (i.e., AC=O), set the switch register to 200
(octal), i.e., set switch 4 in' the up' position, set all other
switches in the down position. Press the ADDR LOAD and
CONT switches. BUILD prints:
$

(At this point, all the usual editing features of BUILD are
available; see Table 2-10 in the BUILD section of Chapter 2.)
Respond with the system (mass storage) device on which
OS/8 is to be built. This response must be in the following
form: 2
$SYS dev=n
where "dev" represents one of the legal replies taken from
Table 1-6. The "=n" is ()ptional and need only be used to
indicate the number of physical disk platters which are, present
if the system device is an RF08 or DF32 disk.
The "n" must be a digit in the range 1 to 4. If no value for n
is specified, a value of 1 is assumed. If a response other than
a digit is entered, the message:'
?SYNTAX

2 Characters

printed by the system are underlined to eliminate confusion
with characters typed by the user.

1-17

is printed and the SYS command line, 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:
!.SY S RF08= 5
?PLAT
l.SYS RF08=ij

Table 1-6 System Devices
K

Device

Maximum

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

4
4
I
I

4. When a correct SYS command line has been entered, e.g.,
!.SYS RK8E

BUILD prints another $. At this time, insert the desired
devices for the initial system. The. devices listed below must
be inserted for a minimum system with paper tape. Type the
following commands, followed by carriage returns, to insert a
low-speed paper tape configuration.
$IN KS33 :PTP,PTR
$IN KL8E:TTY

(low-speed paper tape punch/reader)
(terminal keyboard)

Type the following commands, followed by carriage returns,
to insert a high-speed paper tape configuration.
$IN PT8E: PTP ,PTR
$IN KL8E:TTY

(high-speed paper tape punch/reader)
(terminal keyboard)

5. At this. time, the user must specify the device that is to be the
default mass storage device by entering the DSK command.
For example:
~DSK= SY S

1-18

Any device other than SYS (or carriage return) specified in
the DSK command must be the permanent name of a mass
storage device which appeared in one of the- INSERT commands.
6. When all desired devices have been entered with IN commands,
type the following in response to BUILD's $.
jJ3UI LD

BUILD responds by printing:
LOAD OSI8:

At this point, load the OS/8 Keyboard Monitor tape (DECS8-0SYSB-A-PB4) in the proper reader and respond PTR
followed by a carriage return, i.e.,
LOAD OSI8:

PTR

BUILD loads and writes the various parts of the OS/8 Keyboard Monitor 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 on the
PDP-8/E console to retry. If the retry is unsuccessful, return
to step 2.

NOTE
When building -from the low-speed reader
(KS33), remember to tHrn off the reader
when it reaches the leader/trailer at the end
of the paper tape.
7. When the Keyboard Monitor has been successfully written onto
the system device, BUILD prints:
LOAD CD:

Place the Command Decoder binary tape (DEC-S8-0SYSB-APBS) in the proper paper tape reader and respond PTR followed by a carriage return, i.e.,
1-19

LOAD CD: PTR

BUILD loads and writes the Command Decoder.
8. When BUILD responds with another $, type the following:
.!,BOOT

to initiate the final system creation process. BUILD creates
OS/8 on the system device, writes ABSLDR on the system
device, and prints:
.
SY S BUILT

•

The dot indicates that the OS/8 Keyboard Monitor is activated.
9. At this time, BUILD is still in memory and it is necessary to
copy it onto the system device. To save the copy of BUILD
with the current date, type:
.DATE mm/dd/yy
.SAVE SYS BUILD

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

This copy of BUILD reflects the current configuration of the
system. It can be loaded and rerun with the command:
.:.RUN SYS BUILD

See the BUILD section of Chapter 2 for details of using BUILD
effectively.
ABSLDR (which resides on the system device) must now be
used to load the various system programs. Refer to the following
section for instructions.

Loading System Programs From Paper Tape
After an OS/8 system has been created from paper tapes using
BUILD, the system programs must be loaded using ABSLDR.
When loaded, the system programs are written onto the system
device with the SAVE command.

NOTE
Users with OSj8 software supplied on DECtape (LINCtape) or cassettes need not be
concerned with thIs section. The information
in this section is only for users with software
supplied on paper tape.
Use the following procedures to load the various system programs. The binary tape identification number is in~icated in parentheses after the program name. When the Command Decoder prints
an uparrow ( t ),. high-speed reader only, type any character on the
keyboard to cause the tape to be read into memory.
In response to the dot (.) printed by the Keyboard Monitor,
type:
R ABSLDR

(followed by the RETURN key)

ABSLDR prints an asterisk when it is ready to receive a command
line. Enter the command as specified for each program, ending the
command with an ALTMODE. AL TMODE echoes a $. When the
Keyboard Monitor responds with a dot, enter the SAVE command.
When the Keyboard Monitor responds with another dot, the system
prognim has been written OIito the system device and ABSLDR
may be called again.
FORTRAN II (DEC-S8-0SYSB-A-PB6)
Place the FORTRAN II Compiler binary tape in the reader, and
type the following r~sponses to the . and * printed by the Keyboard
Monitor and ABSLDR, respectively .
.:..R ABSL DR

HTR: (SP> $
~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
~PTR; 13000(89P)$

.:.SAVE SY S PI P

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 345 678
000 000 000
000 000 011
IIqilr III 100
101 000 011
000 000 011

0000
0030
6743
5031
0030

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 0
unit 1
unit 2
unit 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 0
unit 1
unit 2
unit 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.

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

1..1

"'J.1.J.b~

= 1 record = 2 pages = 256 words
10

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) isr~n, if found. If the user
types:
• 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 III
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.

Bit 3 = 1

Program being run will not destroy the BATCH
monitor.

Bits 4 -- 9

. 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<DEV:INPUT FILES
, (W~ile the left angle bracket «) is the accepted divider character
between output and input files, the back arrow (~) may also be
used.) There may be 0-3 output files and 0-9 input files, depending
,on the reql:lirements of the individual system program. The particular 1/0 string used with each system library program is described in its respective section.
For example:
,

The PAL8 assembler would use the first output fil~ (DTAl :XYI )
for the binary output of the assembly and the second output device
(LPT:) for the listing. DSK: PR OG or PROG.PA is the input
source file.
Multiple file specifications are separated by commas. If no output files are indicated, the left angle bracket can be omitted. For
example:
1-45

*DSK: PROG

would cause the file PROG on device DSK to be accepted as an
input file.
The forms in which I/O files may be specified in a command
string are illustrated below:

File Specifications

Form
DEVICE:FILE
NAME

Example

Meaning

!DTA3: FILE 1

The 110 file is to be found
under the specified name
(FILE1) on the device indicated (DT A3: )

DEVICE:

!LPT:

When a device IS indicated
without an associated file name,
the device is usually a nondirectory device. (If a direc- .
tory device is used, the device
can be read, but not written;
for example, referencing DT AO
"'causes the entire DECtape
Unit 0 to be used as the input
file. DSK: is always the default
output device.)

FILENAME-

!,NAME<DTA2: PROG

A file name used without an
associated device indicates
that the
will be found on
an assumed device. For all
output files and the first input
file, the device is assumed to
be DSK:. The example indicates DSK:NAME as an output file. For input file~ after

file

1-46

File Specifications
Form

Example

Meaning
the first, the device is assumed
to be the device of the previous entry. For example:

*DSK:PROGl<DTAl:FILEl~FILE2~FILE3

causes the three input files to
be taken from DTAI.
. NULL FILE
!~ LPT<DTAI : QUEST ~ DTA2: STAR

The absence of an explicit
file specification has different
meanings in context, and is indicated by a comma which is
not preceded by a file designation. For output files, a null
file indicates that there is no
output file for this position. If
the example given were an input line to PAL8, the first output file (binary) would not
be generated, but the listing
would be output to the line
printer. 'For input files, a null
file indicates that the device
of the most recent entry is to
be used as a non-directory
device:

!; DSK: A < P TR : ~ ~

This input string allows three
paper tapes to be read from
the high-speed reader.
1-47

EXAMPLES OF COMMAND STRINGS
Some examples of command strings specifying 119 are shown
below with appropriate explanations.
Example 1:
~DSK:BINARY~LPT:<SOURCE

The file named SOURCE is the input file on device DSK: The
two output files are BINARY on DSK, and a second file on the
line printer (LPT). The P AL8 assembler uses this format; however, the assembler also adds the extension .BN onto the file
labeled BINARY. Thus, the output file on device DSK: will be
named BINARY.BN.
Example 2:
!INPUTl,INPUT2,INPUT3,PTR:,

This is a string of input files with no output file. Notice that the
left angle bracket is not necessary if there are only input files specified. This type of input might be given to one of the loaders
(which do not require output files). Three files are taken from
device DSK and then two are taken from the paper tape reader
(PTR:,).
.
Example 3:

The input files C and D are taken from device XYZ (which could
be any device with the user-defined name XYZ). The' output
files are a file named A on DTA2 and a file named B on DSK.
Example 4:

The input file is named SRC and is on DSK. The two output files
specified are one null file (no output file in that position) and a
file to be sent to the line printer (LPT).
Example 5:
!PTR:, ~ DTAl : X

1-48

As in Example 2, this is another input only file string. The first
input file comes from the paper tape reader, as does the second
(PTR:,,). The third input file is named X and is on DTAl.
Example 6:
*A<TTY:~

Both input files in this example come from the Teletype (generally the low-speed reader). The single output file is named A and
is stored on DSK.
INPUT/OUTPUT SPECIFICATION OPTIONS
In addition to output and input files which are indicated on the
file specification line to the Command Decoder, there are various
options which can also be indicated on this line. These options
are interpreted by the. individual system programs and are covered
in detail in the sections describing the various programs. Options
are either numbers or alphanumeric option characters.
Numbers used as options are generally contained in the
command line with the equal. sign (=) or square brackets ([ ])
construction. The alphanumeric option characters are set off from
the I/O specifications by the slash (/) character for single character options, and parentheses for a string of single characters.
The usage of the slash, parentheses, equal sign, and square
brackets is explained below; These explanations will serve as
references and format specifications once the user has learned from
reading about each individual program. which options he will be
needing.
The format for input to the Co~mand Decoder looks generally
like the following:
DEV~ OUPUT

FILES <DEV : INPUT FILES/OPTIONS

The Slash Construction
A single alphanumeric option character is preceded by a slash
and can occur anywhere in the input line, even in the middle of a
name, although the usual position i~ after the file specification. For
example:

-*TTY: /L<:DsK:AB
1-49

is equivalent to:
!TTY:<DSK:AB/L

The option specified is L, which PIP interprets as a command to
list the DSK directory beginning at file AB.
The Parentheses Construction
Any number of option characters can be grouped together inside parentheses. This construction is also valid anywhere in the
input line. For example:
!OUT:X<IN:YCAQZ)

is equivalent to:

-*OUT:X<IN:Y/A/Q/Z
The Equal Sign Construction
An octal number up to seven digits long and preceded by an
equal sign (=) may optionally be used as an indicator. This
construction is often used to set a starting address, but may be
assigned other functions as well. It may only occur once in a line
and must be followed by a separator character (comma, left
angle bracket, back arrow, ALT MODE key or RETURN key)
or by other options and a separator character. The following
example uses the equal sign construction and indicates three separate options:
!FILE1=1002CAQX),FILE2

Interpretation of options and = sign numbers varies dep~ding
upon the program which called the Command Decoder. See the
individual system programs for details.
The Square Bracket Construction
The square bracket construction can only occur immediately
after an output file name and consists of an open bracket, a decimal
number between 1 and 255, and a close bracket. The square

1-50

bracket construction is generally only used by the more sophisticated user to optimize file'storage.
The open bracket ([) is produced .by holding down the SHIFT
key while typing a K (i.e., SHIFT /K); the close. bracket (D is
produced by typing a SHIFT1M. This construction is used to
provide an upper limit on the number of blocks (256 words per
. block) to be contained in the output file in order to allow the
system to optimize file storage. For example:
!BLNARY[ 19], L 1ST LNG [2QlQl] < SOURCE/ 8

The output files are a file named BINARY on device DSK: having
a maximum length of 19 blocks, and a file name LISTIN (only
six characters are significant) on the device DSK with a maximum
length of 200 blocks. The input file is SOURCE on device DSK;.
the option specified is 8, which is interpreted by the pro~ram
being fl,lll.

Command Decoder Error. Messages
The following is a complete list of the error messages which the
Command Decoder generates if a command string is improperly
input.
Table 1-15

Command Decoder Error Messages

Message

Meaning

ILLEGAL SYNTAX

The command line was formatted in-.
correctly or contains illegal characters.

name DOES NOT EXIST

The device with the name specified
could not be found in the system tables.

name NOT FOUND

The file with the name specified does
not exist on the device indicated.

TOO MANY FILES

More than three output files or nine
input files were specified. Some programs may restrict the user to fewer
files.

1-51

CCL (CONCISE COMMAND LANGUAGE)
CCL (Concise Command Language) provides the OS/8 user with
an extended set of Keyboard Monitor commands. Some CCL
commands allow the user to call a system program indirectly, per~
form an operation, and return to the Keyboard Monitor. These
commands are more concise than the usual calling sequence of a
program. For example, instead of typing the following to call
PAL8:
• R PAL8
*F'ILE" LPT: < FI LE

CCL can be used by typing the following command:
.PAL FILE-L

Other CCL commands perform functions not performed by
other OS/8 programs.
The user may write his own CCL commands and add them to
CCL. See the OS/8 Software Support Manual for instructions on
adding CCL commands.

CCL Commands
CCL commands are entered at the terminal in the same manner
as Keyboard Monitor commands, in response to the dot printed.
Normally, CCL commands are terminated with a carriage return.
Depending upon the command being used, control may return to
the Monitor when the operation is completed or may remain within
another OS/8 program. If the user wishes to remain within control
of another program when control would normally return to the
Monitor, he can terminate the CCL command with an ALTMODE.
This termination procedure is the reverse of the way in which most
OS/8 programs operate.
CCL COMMAND FORMAT
The full eeL command keyword need not be typed; each command has letters that are required. The eCL commands are listed
below in alphabetic order. Letters that are not required are printed
in italics, e.g., the CREATE command is shown as follows: .
1-52

CREATE
to indicate that only the letters CREA are required.
BACKSPACE
BOOT
CCL
COMPARE
COMPILE
COpy
CORE
CREATE
CREF
DATE
DEASSIGN
DELETE
DIRECT
EDIT

EOF
EXECUTE
HELP
LIST
LOAD
MAKE
MAP

MUNG
PAL
PRINT
PUNCH
RENAME
RES
REWIND
SKIP
SQUISH
SUBMIT

TEeO
TYPE
UA
UB

UC
UNLOAD

VERSION
ZERO
1-53

In some cases, there are two commands to run a program. For
example, the MAKE and TECO commands both run the TECO
program, as does the R TECO command.
Most CCL commands are entered by typing the command followed by an argument of the form:
dev: output files <dev :input files/options
This is the I/O specification format \lsed by the Command
Decoder. The slash construction and the parentheses construction
can be used to include options in the program being run by CCL.
If no input device is specified, DSK is assumed. If a filename is
specified with no extension but is followed by a dot, no default
extensions are tried. The actual format for each command is shown
in the command discussion.
CCL remembers arguments used by some CCL commands, e.g.,
COMPILE, and can use these arguments in other commands.
(This procedure is explained for each CCL command to which it
applies.) If, however, the DATE commat:ld is used to change the
current date, the remembered arguments are erased. Commands
which require remembered arguments produce a BAD RECOLLECTION message if no previous argument existed.
CCL COMMAND OPTIONS
Some CCL commands assume the inclusion of options that
would -have to be specified if the OS/8 program were called
directly. The DELETE command, for example, runs the FOTP
program, including the /L and /D options. Other options may be
included in the command line with the slash or parentheses construction.
CCL also has options that may be included in a CCL command
line. These options are of the form:
-ex
where "ex" is one of the options specified in Table 1-16.
1-54

Table 1-16

CCL Options

Option

Meaning

-L
-LS

Send output to LPT.
Generate a listing file (used with the COMPILE, EXECUTE, and PAL commands). The listing file is written
onto SYS if no output device is specified and is given a
.LS extension.
Generate a core map (used with the COMPILE, EXECUTE, and PAL commands).
Do not create a binary file (used with the COMPILE, EXECUTE, and PAL commands).
Send output to PTP.
Send output to TV.
Send output to TTY.

-MP
-NB
-P
-S
-T

WILD CARD CONSTRUCTION
Certain CCL commands that run the FOTP or DIRECT programs may use a wild Gard construction. These commands are
eOPY, DELETE, DIRECT, LIST, RENAME, and TYPE.
The wild card construction means that the file name or_ the extension in a CCL command may be replaced totally with an
asterisk or partially with a question mark to designate certain file
names or, extensions. The asterisk is used as a wild field to
designate the entire file name or extension. For example:

•

TESTl.*
*.BN

All files with t~e name TESTI and any extension.
All files with a BN extension and any file name.
All files.

The question mark is used as a wild character to designate part
of the file name or extension. A question mark is used for each
character that is to be matched; e.g., PR?? match~s all files beginning with PR that are two to four characters long. For example:
TEST2;B?
TES??P A

????

All files with the name TEST2 and any extension
beginning with B.
All files with a P A extension and any file name
from three to five characters long beginning with
TES.
.All files with file names of two characters or less.
1-55

The asterisk and the question mark can be specified together in
the same command line:
??? *

All files with file names of three characters or less.

A specification may not contain embedded *'s, e.g., A *B. * IS
an illegal specification and will produce the following message:
ILLEGAL SYNTAX

If an * or ? is included in a command other than COPY,
DELETE, DIRECT, LIST, RENAME, or TYPE, the following
message appears:
ILLEGAL

* OR ?

See the FOTP section of Chapter 2 for more detail about using
the wild card construction.
INDIRECT COMMANDS (@ CONSTRUCTION)
When many file names and options are to be included in a
single CeL command, they can be put into a file and thus need
not be typed each time they are required. This is accomplished by
the use of the @ file construction, which may appear anywhere
within the argument portion of a eCL command. The @ construction is of the form:
@dev:file.ex
If dev: is omitted, DSK: is assumed. The word file must be a file
name. If the extension (ex) is omitted, .eM is assumed.
The information in the specified file is then put into the command string to replace the characters @ file.ex. For example, if the
file FLIST.CM contains the string:

FILEB,FILEC/L,FILED
then the CCL command
• COMPI L E FI LEA .. n L E8 .. n L EC/L .. FI LED .. n L EZ

could be replaced by the CCL command
• COMPI L E FI LA .. @FLI ST .. FI L EZ

1-56

Carriage returns and line feeds within the file are ignored, but nulls
are not; the nulls signify end-of-line. Command files may not exceed one block in length. If a command line is more than 512
characters in length, the following message is printeq:
COMMAND LI N E OVERFLOW

NONSTANDARD FILE"NAMES (.# CONSTRUCTION)
In rare instances, a user may create a file that has a file name
unacceptable to OS/8. For example, a file mime could contain
embedded spaces: ABC D.EF. CCL provides an alternate means
of specifying an 8-character file name (6 characters of name and 2
of extension, separated by a dot). The alternate specification is a
16-digit sequence of octal numbers which represent the internal
packed 6-bit representation for the file name. These octal digits are
preceded by a # to identify them as an alternate file name.
For example, the file name:
ABC D.EF
could be replaced by:
#0102036404000506
The 64 is the octal representation for a space. Note that all 16
digits must be given to use the alternate specification even though
the file name does not contain 16 digits. This is done by specifying
00 for any nonexistent characters. If all 16 digits are not present,
.CCL prints the message:
BAD NUMBER

See Appendix A for a table listing the 6-bit octal code to be
used in the alternate file name construction.

BACKSPACE Command
The BACKSPACE command runs the OS/8 CAMP program
and spaces a magnetic tape or cassette backward a specified number of files or records. This eCL command works in exactly the
same way as the CAMP BACKSPACE command. When CAMP
has completed a backspace operation, control returns to the Keyboard Monitor. See the CAMP section of Chapter 2 for a detailed
.explanation of the BACKSPACE command.
1-57

BOOT Command
The, BOOT command chains to the OS/8 BOOT program,
allowing the user to bootstrap onto another device or onto another
PDP-8 system. The BOOT command is of the form:
.BOOT/dv
where dv is a mnemonic listed in Table 2-5 in the BOOT section of
Chapter 2. For example, the command:
• BOOT /RF

bootstraps onto the RF08 disk.
If the user wishes to halt before performing the actual bootstrap,
he can type the BOOT command followed by a period, e.g.
• BOOT ~CA.

The computer will halt, allowing the user to mount a new device.
Pressing the CONT switch completes the bootstrapping operation.
This form of the BOOT command is particularly useful when only
a single disk or DECtape drive exists on the system.
CCL Command
The CCL command disables the CCL program on the OS/8
Keyboard Monitor residing on the system device. This command
has no arguments and is of the form:
• CCL

When the CCL command is used, the CCL feature of OSj8 is
deactivated; OS/8 will not accept CCL commands. If CCL is
desired at a later time, it must be reactivated with the R command,
I.e.,
.R CCL

COMPARE Command
The COMPARE command runs SRCCOM and compares two
source files line by line and prints all their differences. This command has the form:
1-58

·COMP dev:file.ex<dev:file.ex,dev:file.ex
See the SRCCOM section of Chapter 2 for a complete description of SRCCOM.

COMPILE Command
The COMPILE command produces binary files and/or compilation listings for the specified program files. The assembler or compiler used is determined by the source file extension.
The COMPILE command is of.the form:
.COM file.ex<file.ex
Table 1-17 lists the extensions and the compiler or assembler to
which the COMPILE command will chain.
Table 1-17

Compiler/Assembler Extensions

Extension

Program ..

.BA
.FT

BASIC
FORT if pr~sent on SYS when CCL was enabled; otherwise F4 .
PALS
RALF
SABR

.PA
.RA
.SB

If no extension is explicitly given, each possible extension is
tried in order until one is found and the appropriate compiler is
invoked. If no output file name is specified, the name of the first input file is assumed.
If a nonstandard OS/8 file extension is used, i.e., other than
those listed in Table 1-17, a processor switch of the form:

-ex
can be included in the command line to indicate the compiler/
~ssembler to which COMPILE· must chain. This processor switch
must be a legal 2-character OS/8 extension. For example, to
assemble· a file named HANDLR.03 with the P AL8 assembler, the
user would type:
• C~PI LE HANDLR.03-PA

1-59

Each time the' COMPILE, LOAD, PAL, or EXECUTE command is executed, the command with its arguments is remembered
in a temporary file. Therefore, the file name used last can be
recalled for the next command without specifying the arguments
again. If, for example, the EXECUTE command:
• EX ECUTE TEST 1. PA

was entered previously, then the COMPILE command to specify
TEST1.PA could be:
• CG1PILE

COpy Command

The COpy command transfers files from one OS/8 I/O device
to another. The command string can contain one output specification and from one to five input specifications. This command runs
FOTP and includes the /L option among any other options
specified by the user.
The COpy command is of the form:
.COPY dev:file.. ex<dev:file.ex
When the user enters a COpy command, the message:
F"I L ES COPI ED:

is printed and each file copied is listed on the terminal.
Examples:
The following command copies all files with .FT extensions from
DTAO to DSK.
• COPY DTA0:*.FT
FILES COPIED:
PROGI. fT
DTA3.F'T
TEST.F'T

The following command transfers all files from four to six characters long beginning with FILE and having any extension.
1-60

.COpy DTA2: <DTA0: FILE??*
FILES COPI ED:
FILEt. PA
FILE2.PA
FILEX. DA
FILEZ.BN

To understand the COpy operation, see the FOTP section of
Chapter 2.

CORE Command
The CORE command can be used in two different ways. One
way is the same as the CORE command in BUILD to specify the
highest core field available to the OS/8 system. This form of the
CORE command is:
.CORE n
where n is an octal number in the range 0 to 7, specifying the number of 4K core banks available to OS/8. The following table indicates the value of n for the available core sizes.
n

core

all available core
8K
12K
16K
20K
24K
28K
32K

1
2
3
4

5
6
7

For example, a system which is to use only 20K of a 32K system
would have the following CORE command:
• CORE 4

The other form of the CORE command is the command typed.
without an argument. When this form is used, the amount of core
actually in use by OS/8 is printed on the terminal. For example, if
a 32K system has been restricted to 20K by the. CCL or BUILD
CORE command, the following would appear:
• CORE
20K 132K CORE!

1-61

If all available cote is in use on a32K system, the following would
be printed. .
• CORE
32K CORE!

CREATE Command
The CREATE command runs EDIT (the OSj8 Symbolic
Editor) and opens a new file for creation. The file specification
must consist of a single output file only. For example:
• CREA TEST 1. FT.

is the same as
• RED! T
*TEST1.1'1<

If no argument is given, the argument used in the last CREATE or
EDIT command is assumed. See the Symbolic Editor section in
this chapter for a detailed explanation of EDIT.

CREF Command
The CREF command runs the P AL8 assembler, including the
IC option which causes PAL8 to chain to the CREF program.
CREF produces a cross-reference listing file. If no listing file is
specified, the listing is sent to the line printer. For example, the
following command produces a CREF listing of the file DSK:
PROG.PA on the line printer .
• CREF PROG

DATE Command
If an argument is given with the DATE command, it is treated
as the standard Keyboard Monitor DATE command. If no argument is given, this command prints the current day and date on
the terminal or prints NONE if no date was specified. For example:
• DA
THURSDAY JAt"IJUARY

31 ..

1974

If the user has created a file named DATE.SV, the DATE command runs that program, allowing the user to implement messages
of the day.
1-62

PEASSIGN Command
The DEASSIGN command is exactly the same as the Keyboard
Monitor DEASSIGN command. If CCL is enabled, CCL performs
, this function instead of the Monitor.
DELETE Command
The DELETE command deletes one or more files from disk or
DECtape. The command string can contain one output specification and from one to five input specifications. This command runs
FOTP and inclu~es the /D and /L options among any other
options specified by the user.
The DELETE command has the form:
.DEL dev:file.ex<dev: file.ex/options
When the user enters a DELETE command, the .message:
FI L ES DEL ETED:

is printed and each file deleted is listed on the terminal.
Examples:.
The following example deletes any DSK file with a .BN extension if a file with the same name and a .PA extension exists on
DSK .
• DEL *.Bi\J<*.PA
FI L ES DEL ETED:
TESTl.BN
TEST2.BN

The following example deletes from DT AO any file of five or
less characters that begins with D AT A and' has. any extension .
• DEL DTA0:DATA?*
FI L ES DEL ETED:
DATAl.PA
DATAr.LS
DATA3.BN
DATA6.PA

To understand the DELETE operation, refer to the FOTP
section of Chapter 2.
1-63

DIRECT Command
The DIRECT command 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 in blocks written,
and creation date. The DIRECT command runs the DIRECT
program. See the DIRECT section of Chapter 2 for a complete
description ,of DIRECT and the available options.
In addition to the DIRECT options specified, the CCL options
-L, -P, -T, and -S ,can be used in the DIRECT command line. For
example, the command:
.DrR DTAl:/C-L

is the same as
• R DI RECT
*LPT:<DTAl: /c

Both these commands will list on the Ilne printer all files with
the current date that exist on the DECtape on DTAI.

EDIT Commands
The EDIT command runs EDIT (the OS/8 Symbolic Editor)
and opens an -already existing file for editing. For example, the
CCL command:
.EDIT DATAl

is the same as:
• K EDI T
*DATAl<DATAl

For a detailed explanation of EDIT, refer to the Symbolic Editor
section in this chapter.
If no argument is given, CCL assumes the argument used in the
last CREATE or EDIT command. If the EDIT command is used
with the < option, e.g.,
.EDIT TEST3<T£5T2

1-64

CCL remembers the argument up to but not including the <. Thus
the next EDIT command with no argument will edit the file TEST3.
EOFCommand

The EOF command runs the CAMP program and writes a single
mark (file gap) on the specified magnetic tape 'or cassette. The
EOF command has the form:
.EOF dev:
where "dev" may be either MTAn or CSAn, signifying the device
on which the file mark is to be written. For example:
• EOF MTA3:

writes an end-of-file mark on the magnetic tape mounted on MTA3.
The CCL EOF command operates in the same way as the
CAMP EOP command. See the CAMP sectioll: of Chapter 2 for a
detailed explanation of the CAMP commands.
EXECUTE Command

The EXECUTE command produces binary files and/or compilation listings for the specified program files, loads the binary
file, and executes the program. The EXECUTE command has the
form:
.EXE file.ex,file.ex
The assembler or compiler used is determined by the source file
extension. In addition to the extensions listed in Table 1-17, the
EXECUTE command includes the following:
Extension

Program

.BN

ABSLDR
LOADER or LOAD

.RL

If no file is specified, a search is made for a file with one of the

above extensions. The first such file found is executed.
The EXECUTE command, like the COMPILE command, will
~ccept processor switches in the -ex form to control the compiler or
assembler used.
Each time the EXECUTE, LOAD, PAL, or COMPILE command is executed, the command with its arguments is remembered
. 1-65

in a temporary file. If no argument is specified in. a EXECUTE
command, CCL rememb~rs the argument of the last COMPILE,
PAL, or LOAD command. For example, if the COMPILE command:
.COMPILE FILEt.PA

was previously executed, th~n the EXECUTE command to' specify
FILE 1.PA could be:
• EXECUTE

HELP Command
The HELP command prints useful information on specified
OS/8 programs. Each OS/8 program has a HELP file (.HL extension). It is these HELP files that are printed when a HELP
command is issued.
If OS/8 software was supplied on DECtape (or LINCtape), the
HELP files are present on System Tape #2 and can be run by
mounting that tape and specifying the unit in the HELP command.
For example, to print the HELP file for FOTP from the DECtape
mounted on DTA1, type:
.HELP OTA 1: rOTP

If the OS/8 software is supplied on paper tape, the HELP files

are on DEC-S8-0SYSB-A-P A. The HELP file tape is composed
of separate segments with a short length of leader/trailer code between them. The files are listed below in the order that they appear
on the tape.· These file segments must be separated and labeled before they can be used.
DIRECT.HL
BATCH.HL
SABR.HL
PIP.HL
FOTP.HL
ABSLDR.HL
PIP10.HL
BOOT.HL
LOADER.HL
1-66

BITMAP.HL
EDIT.HL
CREF.HL
BUILD.HL
PAL8.HL
ODT.HL
SRCCOM.HL
CCL.HL
TECO.HL
FORT.HL
LOAD.HL
LIBRA.HL
EPIC.HL.
The HELP files must be transferred onto the system device.·
This is done by using PIP to load the paper tape and save the file
on the system device. For example, to load and save CCL.HL, the
user puts the appropriate tape in the reader and types the following:
• R PI P

*CCL.HL<PTR:$

$=ALTMODE

If the OS/8 software is supplied on cassettes, the HELP files
must be transferred onto DSK with MCPIP. OS/8 HELP files are
supplied on the system cassette DEC-S8-0SYSB-A-TC4. To load
and save a HELP file, mount this cassette on cassette unit 0, drive
0. For example to load CAMP.HL from the cassette mounted on
CSAO, type:
'
.R MCPIP
*OSK:CAMP.HL<CSA0:CAMP.HL

Once the desired HELP file is present on DSK, the HELP command can be issued by specifying the desired file name. If no extension is specified, the .HL extension is assumed. If no file name is
specified, CCL.HL is assumed. The HELP file is printed on the
terminal if no output device is specified.
LIST Command
The LIST command lists the contents of the specified file on the
specified device. This command runs FOTP and includes the /U
option. The LIST command has the form:
1-67

.LI dev:file.ex<dev:file.ex
If no output device is specified, LPT is assumed.

LOAD Command
The LOAD command runs one of the OS/8 loaders, depending
on the extension of the first specified input file. The LOAD command is of the form:
.LO file.ex
A .BN extension ruris ABSLDR. A .RL extension runs
LOADER (or LOAD). If no e'xtension is given, a search is made
for a file with one of these extensions, The .IG ootion mav- be
specified to start execution of the program after it is loaded. If no
argument is given, CCL remembers the argument of the last COMPILE, PAL, or EXECUTE command.
~

MAKE Command
The MAKE command runs TECO and opens the specified file
for output. The MAKE command has the form:
.MA dev:file.ex
If no device is specified, DSK is assumed. If no file extension is
specified, .PA is assumed. If the file' specified already exists, CGL
prints the message:
'"'SUPERCEDING

Example:
The CCL command:
.MA DTAl:TEXT.TX

is the same as the following:
• R TECO
*E~'IDTA1: TEXT. TX $$

1-68

To use the MAKE command, the user. must be familiar with
TECO as explained in Chapter 2.
MAP Command
The MAP command runs BITMAP and produces a core map of
the specified file. The MAP command is of the form:
.MAP dev:file.ex
If no output device is specified, TTY is assumed. If no extension
is specified, .BN is assumed.
Example:
The CCL command:
.MAP TEXT .. DATA

is the same as
• R 81 TMAP
*TTY:<TEXT.BN .. DATA.BN

See the BITMAP section of Chapter 2 for a complete explanation of the BITMAP program.
MUNG Command
The MUNG command allows the user to operate on source files
and text using a predefined TECO macro. This command has the
form:
.MUNG dev:file.ex,text
The MUNG command runs TECO which reads the first page of
the specified file into Q-register Y. The contents of this file are
assumed to be a TECO macro. If no extension is specified, .TE is
. assumed. If a dot is typed after the file name, no extension is
assigned.
After the page is· read in, all text between the comma and the
end of the line is entered into the TECO text buffer. This text is
presumed to be an argument to the macro. If no text is desired, no
comma is necessary. With the text pointer at the end of the buffer,
the macro in Q-register Y is executed. In the following example, the
text will specify source files to be edited by the TECO macro.
If the text argument is too long, CCL prints the error message:
COMMAND TOO LCNG

1-69

Example:
This example assumes that the user wishes to remove the line
feeds from several files that contain carriage return and line feed'
characters at the end of each line. This operation is desirable for
certain data files.
To perform this operation, the user has created a file called
MACRO.TE. This file contains the following.
HX!
HKGY!
J2SFILE$-4DG 1 !
J2SS1:ART!$0 ... K!
J I

III{XY$ !

HX 1M 1 !
!! START!
EBFILE$!

Argument to Q.,register 1
Move macro into text buff
Enter argument into macro
Remove preamble
Insert command to kill Y
Move text buff into Q-register 1
and execute as macro
.open file

* * * Any user TECO code may be substituted here 'I: * *
<N

$-D>!
EX!

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<dev:file:ex
If no output is specified, PTP is assumed.

RENAME Command
The RENAME command renames one or more. files on disk or
. DECtape. The command can contain one output specification and'
one input specification. RENAME changes the name of the file
from the input file name to the output file name. This command
runs FOTP and includes the /Roption. The form of the RENAME
command is:
.

.REN dev:file.ex<dev:file.ex
When the user enters a RENAME command, the message:
FI L ES RENAM ED:

is printed and each file renamed is listed on the terminal.
Examples:
.REN DTA0:FILE0.TX<DTA0:FILEI.TX
FILES RENAMED:
FI LEI. TX
.REN NEWOOE. BN<OLDCNE. B;'IJ
FILES RENA,\'jED:
QLDCNE. BN

RES Command
The RES command runs the RESORC program and lists the
device handlers present on an OS/8 system. This command has the
form:
.RES dev: file. ex <dev: file .ex/ options
1-71

Any option allowed on a RESORC command line is allowed
with the RES command. See the RESORC section of Chapter 2 for
a detailed explanation.
REWIND Command
The REWIND command runs the CAMP program and issues a
rewiQd command to a specified OSj8 device controller. This command operates in the same way as the CAMP REWIND command.
See the CAMP section of Chapter 2 for a complete description of
the REWIND command.

SKIP Command
The SKIP command runs the CAMP program and advances
over the number of files or records specified on a magnetic tape.
, See the CAMP section of Chapter 2 for a complete description of
the SKIP command.
SQUISH Command
The SQUISH command runs PIP, including the PIP IS option.
This command has the form:

.SQ dev: <dev:
If no output device is specified, the output device is assumed to

be the same as the input device. The following example:
• SOUl SH SY S:

is the same as the PIP command:
*SYS:<SYS:I$$

SUBMIT Command
The SUBMIT command runs the BATCH program. This command is of the form:

.SUBMIT dev: file.ex <dev: file.ex
where the output dev and file.ex are the optional spooling output
file and the input dev and file.ex are the BATCH input file. If no
device is specified, DSK is assumed. If no input extension is specified, .BI is assumed. See the BATCH section of Chapter 2 for a,
complete description of the BATCH program.
1-72

TECO Command
The TECO command runs the TECO program which then opens
the specified input file for reading and creates an output file.' The
TECO command may have one output file and at least one input
file as arguments. If no argument is specified, the argument used in
the last TECO or MAKE command is assumed. If no output file
is specified, TECO does an edit backup' on the specified file. If no
file extension is specified, .PA is assumed.
Examples:
The CCL command:
• TECO FILE. SA

is equivalent to
• R TECO

* ESF! L E. BA$Y $$ ,
and the CCL command:
.TECO WIN2.PA<LTA2:WIN.PA

is equivalent to
• R TECO
\oJI N 2. PA$ERL TA2: .WI N. PA$Y $$

The first page of the input file is read into the text buffer' before
control is returned to the user.
If the TECO command is used with the < option, e.g.,
.TECO FILEl<FILE2

CCL remembers the argument up to but not including the <. Thus
the next TECO command with no argument will edit th~ ,file
FILEI.

TYPE Command
The TYPE command runs the FOTP program, including the IV
option, and prints the specified file. The form of this command is:
1-73

.TY dev:file.ex<dev:file.ex
If no output device is specified, TTY is assumed. Thus the CCL
command:
.TY DTA0:TESTl.DA

is the same as
• R FOT?
*TTY:<DTA0:TESTl.DA/L/U

UA, UB, UC Commands
The D~A.., DB, and DC commands are used to remember and
recall arguments. When one of these commands is typed with an
argument, CCL remembers the argument in a temporary file. This
argument must be a legal CCL command. For example:
• UA COpy DSK: < DTA0: *. FT

If the UA command is then typed without an argument, the last

UA argument is recalled and executed as a CCL command.

UNLOAD Command
The UNLOAD command runs the CAMP program and jssues a
rewind and turn off line command to the specified magnetic tape
controller. This command may also be used to' rewind a DECtape
or to write-lock an RK8E disk. See the CAMP section of Chapter
2 for a complete description of the- UNLOAD command.
VERSION Command
The VERSION command prints the version numbers of both the
OS/8KeyboardMonitor and CCL. This command has no arguments and is of the form:
• VER

ZERO Command
The ZERO command runs PIP, including the /Z option, and
zeroes the device specified. Only file structured devices can be
1-74

specified in a ZERO command. The eeL command:
.ZERO DTA7:

is equivalent to
.R PIP
*DTA7:/Z<$

CCL Error Messages
The following error messages may appear in response to a eeL
command.
Table 1·18

CCL Error Messages

Message
BAD DEVICE
BAD EXTENSION

BAD MONITOR

BAD NUMBER

BAD RECOLLECTION

BAD SWITCH OPTION

Meaning
The device specified in a CCL
command is not of the correct
form, (e.g., DTAO.PA:).
Either an extension was specified
without a file name (e.g.,
DTAl :.PA) or two extensions
. were specified (e.g., DTA 1:
FILE.PA.BN).
The version of the Keyboard.
Monitor being used is not compatible with CCL. A newer version of the monitor must be
obtained from Digital before
CCL can be used.
A CCL command which uses
~he # construction does not
have the full 16-digit specification th~t is required.
An attempt was made to use a
previously remembered argument when no argument was
saved. This error occurs when
no argum~nt was previously
saved or when the DATE command has been used since the
argument was saved.
The character used with a slash
(I) to indicate an option is not a
legal option.

1-75

Table 1-18

CCL Error Messages (Coot.)
Meaning

Message
CANNOT CHANGE CORE
CAP ACITY WHILE RUNNING
BATCH
% CAN'T REMEMBER

CCL 3X OVERLAY &
MONITOR INCOMPATIBLE
COMMAND LINE
OVERFLOW
COMMAND TOO LONG
CONTRADICTORY
SWITCHES

name DOES NOT EXIST
ERROR IN COMMAND

ILLEGAL * OR?

ILLEGAL SYNTAX
INPUT ERROR READING
INDIRECT FILE

A CORE command was issued
while the BATCH program was
running.
The argument specified in a
CCL command line is t60 long
to be remembered or an II 0
error occurred.
The version of CCL being used
is not compatible with the Keyboard Monitor present on the
system. Type R CCL to retry.
'T'L_
- ___
l:
...:1Ip
,",,,,,,,:fi<3.-1
.lIle
\.,..UJlIl11aUU
111ne
...... ""
with the @ construction is more
than 512 characters in length.
The length of a text argument
in a MUNG command is too
long.
Either two CeL processor
switches were specified in the
same command line (e.g., FILEPA-FT) or the file extension and
the processor switch do not
agree (e.g., FILE.FT-BA).
The device with the name given
,is not present on the OS/8
system.
A command not entered directly
from the console terminal is not
a legal CCL command. This
error occurs when the argument
of a VA, VB, or VC command
was not a legal command.
An *or? was used in a CCLcommand that does not accept the
wild card construction. Only
CCL commands that run FOTP
or DIRECT allow the wild card
construction.
The CCL command line was
formatted incorrectly.
CCL cannot read the file specified with the @ construction.
~_..:I

1..&."""""""",

1-76

Table 1-18

CCL Error Messages (Cont.).

Message

Meaning

II 0 ERROR ON SYS:

An error occurred while doing
II 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 this chapter). Do not press CONT, as
that will surely cause further
errors.
An II 0 error occurred while
CCL was trying to remember an.
argument.
CCL.SV is not present on thesystem device. Refer to the Getting On Line section of this
chapter for instructions on
loading programs onto the system device.
The number. specified in a
CORE command is larger than
the number of 4K core banks
onthe system.
The file with the name given is
not present on the specified
device, or the user tried to
input from an output-only
device.
The file specified in a MAKE
command already exists. This is
a warning message indicating
that the file is being replaced.
Either a CCL option was specified on the left side of the < or
was used when not allowed.
COMPARE
For
example:
FILE-NB.
Too many files were included in
a CCL command.

I/O ERROR TRYING TO
RECALL
NO CCL!

NOT ENOUGH CORE

name NOT FOUND

%SUPERCEDED

SWITCH NOT ALLOWED
HERE

TOO MANY FILES

1-77

SYMBOLIC EDITOR'
The Symbolic Editor is used to create and modify ASCII source
files so that these files may be used as input to other system programs (such as FORTRAN, SABR, and PAL8).
The Editor considers a file to be divided into logical units called
pages. A page of text is generally 50-60 lines long, and corresponds
approximately to a physical page of a program listing. (Note that
this is not the same as a core memory page.) The Editor reads
one page of text at a time from the input file into its internal buffer where the page becomes available for editing. The Editor contains commands for creating, modifying, or deleting characters,
lines, or complete logical pages of text.
Calling and Using the Editor
To call the Editor from the system device, type:
R EDIT

in response to the dot C.) printed by the Keyboard Monitor. The
system prints an asterisk (*) at the left margin, and in answer to
the asterisk, the user types the device designation and the output
file name, a left angle bracket, and the input device and file designation(s). For example:
~DSK:ABC<PTR:,DSK:AAI

causes input from the paper tape reader and from a file named
AAI on DSK. The output file is named ABC and is stored on
DSK.
Once I/O file designations are entered, the Symbolic Editor is
ready to accept commands from the keyboard and signifies its
readiness by printing a number sign (#) at the left margin. This
symbol occurs whenever the Editor is waiting for a command.
Any device which operates in ASCII mode and has a device
handler in the system is available for use by the Editor. For example, the high and low-speed reader /punch, DECtape, disk,
card reader and line printer are each legal devices. The Editor
only operates properly on ASCII files, however. No error message
is given if non-ASCII files are input to the Editor, but the results
of operations are garbled.
1-78

As many as· nine and as few as zero input files are permitted.
If the number of input files is zero, (that is, a new file is to be .
created using the terminal keyboard) the Editor allows input from
the keyboard via the Append command. ~ The Editor uses a key"':
board input routine which is independent of the OS/8 termi}~al
handler, thus it is not necessary to specify TTY: as an input device
if text is to be created. (It is, in fact, recommended that TTY: not
be used as an input device, as input buffering may cause a loss of
characters on input.) Commands which attempt to read from any
other device (when no file name is specified) are disabled, and a
question mark (?) appears when a Read command is attempted.
The Editor allows only one output file. If no output file is specified, the only output operations which may be performed are' L
(list buffer on TTY:) or V (list buffer on LP08.line printer) .
•

EDITOR OPTIONS
The following three options are the valid IIO specification options for the Editor. (The format for I/O specification options has
been previously described in the section detailing the Command
Decoder. After reading these options, the reader is advised to turn
to that section to review the various formats.)

Table 1·19 .Editor Optjons

..
Option

Meaning

Return control to the Editor after the file is closed (calls
Command Decoder for hew files). If I A is not used, control returns to the Keyboard Monitor.

Convert two or more spaces to a TAB when reading from
input device.

Delete the old copy of the output file (if one exists) before
opening the new output file on the device. If / D is not·
used, the old copy of the output file is not deleted until all
data has been transferred to the new file by an E or Q
. command.

3 See Example Using the Editor for an illustration of using the Editor to
create a program.

1-79

For example, the I/O specification line:

*DTA2:FILE<DTAl:ARG/D

deletes FILE on DT A2 (if such a file exists) before creating a new
FILE on DT A2.

Special Key Commands to the Editor

The Editor can be consider~d as operating in two different
modes, During command mode, the Editor prints a # at the left
margin indicating that it is waiting for a command from the keyboard. Text mode is the condition of the Editor when it is processing various editing" and I/O commands (such as Insert and Append).
The following commands allow the user to transfer between
modes. (These commands are produced by pressing the CTRL
key and the appropriate character key simultaneously.)

Table 1-20
Command
CTRL/C

Editor Key Commands
•
Mode in Which
Used
Meaning

T ext and command Returns control to the Keymode
board Monitor. The text buffer
is retained and the Editor remains accessible to the user
with the START command. In
text mode, text between the last
carriage return and the tC is
lost.
The START command can be
used to restart the Editor as
follows:
T C

• START.

START recalls the Command
Decoder to accept new II 0

1-80

Table 1-20

Command

Editor Key Commands (Cont.)

Mode in Which
Used

Meaning
file designations. When the
START command is given, and
the previous output file is not
closed, that output file' and the
contents of the output. buffer
are deleted.

CTRL/O

Text Mode

Stops the listing of text. Returns control to Command
Mode.

CTRL/FORM

Text Mode

Returns the Editor to Command Mode.

CTRL/ U

Text Mode

Typing CTRL/U while entering text from the keyboard
causes text in the current line
to be ignored. A carriage return/line feed is generated and
the line may be retyped. (The
command is equivalent to typing rubouts back to the beginning of the line.)

Other special Editor characters used to represent numbers or
-.
perform erasures are listed in Table 1-21.
Table 1-21 Special Characters

Character

• + 1C

• -7L
•L

/-7L
/~5L

Meaning

Example

The dot (.) character is used as the
current line counter character. The
dot can be used alone, with + or an integer, or any place where a
number can be used.
Tl}e slash character is similar in use
to the dot and represents the highest numbered line in the text buffer.
Typing the # in response to Editor's prompting # prints the current version number of the Editor.

1-81

Table 1-21 Special Characters (Cont.)

Character
RUBOUTKey

Example

Meaning
Typing the RUB OUT key in text
mode deletes one character from
the text buffer and causes a backslash to be printed. The erasure is
done right to left up to the - last
CR/LF. Typing the RUBOUT~key
in command mode causes the entire
command line to be deleted.

Editor. Text Buffer
In text mode, the Editor performs I/O operations on text stored
within the text buffer. Text is input to the Editor buffer until a
form feed is encountered on input. A line of text is terminated by
a carriage return. If no carriage return is present, the text entered
on that current line is ignored. The buffer has room for approximately 5600 (decimal) characters. When text has been input- to
the extent that there are only 256 decimal locations available in
the buffer, the TTY rings a warning bell. From this point on,
whenever a carriage return is detected during text input, control
returns to the Editor command mode and the TTY bell is rung.
This line-at-a-time input may continue until the absolute end of
buffer is encountered. At this point, no more text will be accommodated in the buffet; a '1' is printed and control returns to command mod~.

TEXT COLLECTION
The 05/8 version of the Editor contains an automatic text collector which reclaims buffer space following the use of a D (delete),
S (Search), or C (Change) command. Formerly, deleted text was
not physically removed from the buffer; now this text is removed
by the text collector, and the necessary pointers updated. If a full
buffer condition is reached, the user may output lines of text
(using the Punch command, for example), and then delete these
lines from the buffer-text collection is automatic and always occurs on the three commands mentioned above.
1-82

NOTE
If extremely large amounts of text "are deleted, the text collection process could take
several seconds. For small amounts of text,
no appreciable time is lost.
Search Mode"

There are two types of searches available in the Editor. The
first is the standard character search, and the second is the character string search whiCh allows the user to search for a combination of characters. Each is explained in turn.
SINGLE CHARACTER SEARCH
The single character search is of the form:

#S
inS
#m,nS

or
or

where m and n represent line numbers (m~n), and S initiates the
search command. 4 This search command searches the entire text
buffer or the line (s) indicated for the search character. The search
character is typed by the user after he types the RETURN key
which enters the command, and does not echo on the t~rminal
The Editor prinls the contents of the entire buffer or the indicated
line(s) until the search character is found. When the search character is found, printing stops and the user may type one of the
following:
Result
Option
text

Enter text at that" point at
which the search character was
found and printing stopped.

CTRL/G (TTY bell rings)

Change the search character
to the next character typed;
search continues. If the character is not contained in the
line, the remainder of the line
will be printed and control will
be returned to command mode.

4A command summary is included in Table .1-23 at the end of this section.

1-83

Option

Resutt

CTRLjFORM

Continue searching for the next
occurrence of the character.

RETURN key

End line here, deleting all subsequent text on that line.

LINE FEED key

Make two lines out of the current line by inserting a carriage return at this point.

RUB OUT key

Delete characters from this
line. Each rubout echoes a
backslash ("') for each character deleted. When all characters have been deleted,
echoing of ''''' stops.

CHARACTER STRING SEARCH
The character string search can identify a given line in the buffer by the contents of that line or any unique combination of characters. This search returns the line number as a parameter that can
be used to further e~it the text. There are two types of string search
available: intra-buffer search and inter-buffer search.
Intra-Buffer Character String Search
The intra-buffer search scans all text in the current buffer for
a specified character string. If the string is not found, a ? is printed
and control returns to command mode. If the string is found, the
number of the line which contains the string is put into the current
line counter and control waits for the user to issue a command.

Thus, searching for a character string in this manner furnishes a
line number which can then be used in conjunction with other
Editor commands. This provides a useful framework for editing,
as it eliminates the need to count lines or search for line numbers
by listing lines.
An intra-buffer search is signalled by typing the ALT MODE
key (which echoes as $) in response to the Editor's #. The user
then types the string to be found (up to 20 characters long-any
additional characters typed are echged but not included in the
search). The search string cannot be broken across line boundaries.
1-84

Typing a single quote (') terminates the character string and
causes the search· to be performed. beginning at line 1 of the text
buffer.· Use of the double quote (") causes the search to begin
at the current line + 1. (Use of ' and" as command elements prohibits their use in the search string.)
For example, assume the text buffer contains the following text:
ABC DEF' GJO
lA2B3C4D5E6
• STRINGABCD

The user wants to list the line that contains ABC; he types:

!$ABC'L

The search begins with line 1 and continues until the string is
found. The current line cou1)ter is set equal to the line in which
the string ABC occurred, and the L ·command causes the line to be
printed as follows:
ABC DEF' GJO

Control returns to command mode, awaiting further commands. If
the user wanted' to find the next reference to ABC, he could type:
!"L

In this case, " is a command which causes the last string searched
for to be used again; with the search beginning at the current line
+ 1. It is not necessary to enter the search string again. The command may be used several times in succession. For example, if the
user wanted to find the fourth occurrence of a string containing the
characters FEWMET he could type:
#$F'EWMET'''''''L

1-85

This command will list the line which contains the fourth occurrence of that string. The L (List) command (or any other command code) can be given following either ' or ". The L command
causes the lineto be listed when and if it is found.
To clear the text string buffer, the user can type:
#$'

The system responds with a question mark and the text string
buffer is cleared.
allow for easy and
The properties of the commands and
useful editing, as the following example illustrates. In order to
change the CIF 20 to CIF ] 0, the. user can give the foHowing
commands:
I

!$DUM,'$CIF 20"C
elF 10
INEW FIELD

(CTRL/FORM)

The above set of instructions first causes the Editor to start at line
1 and search for the line beginning with DUM,. A search is then
made for CIF 20, starting from the line after the line containing
DUM,. When this string is found, the line number of the line containing the string CIF 20 becomes the current line number. The C
(Change) command is given, and the user then changes the line
to the correct instruction.
Since this search feature produces a line number as a result,
any operations which can be done by explicitly specifying a line
number can be done by specifying a string instead. For example:
#$STRING 1 +4L

will list the fourth line after the first occurrence of the text STRING
in the text buffer.

-$LABEL 1 .. ' .. $LABEL 2, "L
#

will list all lines between the· two labels, inclusive.
!$PFLUG'S
1~86

will do a character search on the line which contains PFLUG. (The
user types the search character after typing the RETURN key that
enters the line.)
. In cases where both strings and explicit numbers are used,
strings should be used first. For example, the following commands:

#l+$BAD! 'L

will not list the next line after the string BAD! occurs. The correct
syntax is:
#$BAD!'+lL

Inter-Buffer Character String Search
The inter-buffer search scans the current text buffer for a character string. If the string is not found;' the current buffer is written'
to the output file, the buffer is cleared, and the next buffer is read
from the input device. The search then resumes at line 1 of the new
buffer. This process continues until either the string is found or no
more input is left. If input is exhausted, control returns to conimand mode with all the text having been written to the output file.
If the string is found, control returns to command mode with the
current line equal to the number of the line containing the first
occurrence of the string. For example, a command to find the
character string GONZO may appear as follows:
#J
$GONZO'
!.=~

The J command. initiates an inter-buffer search; .the $ is printed
automatically by the Editor, and the -user types in the character
string to be sought.. The search proceeds, and when the string is
found, control returns to command mode. The. user types the .=
construction to discover the number of .the line in the current buffer
on which the 'string is contained. To find further occurrences of the
string GONZO, the user can use the F command. The F command
uses the last character string entered to search the buffer starting
from the current line count + 1.
1-87

The above example causes a search for the string G.ONZO starting
at the current line + 1. If no output file is specified to the J or F
commands, the Editor reads the next input buffer without attempting to produce any output. This provides an easy way of paging
through text for a particular string.
After the J or F commands have processed the entire input file,
it is necessary to· execute either an E or Q command to close the
output file. If this is not done, the file will· be deleted by the
Monitor.
The following two commands may be used to abort the string
search command, once given:
Command

Explanation

CTRLjU

A CTRLjU will return control to the Editor command mode if executed while entering text in a
string search command; the string search command is ignored, as in the following example:
IIJ
~WORDfU

The inter-buffer search for the characters WORD
was aborted by the user typing tU before terminating the string with' or
fl.

RUBOUT

Executing the RUBOUT key while entering text
for a string search causes the text so far entered
to be ignored and allows a new string to be inserted. Editor answers the command by printing
$, as in the following example:

!$CHAR
$

An example of the use of the character string .search is contained
in the OSj8 Demonstration Run in Appendix D.
1-88

Editor Error Messages
Errors made by the u,ser while running the Editor may be of two
types. Minor errors (such as an Editor command string error, an
attempt to execute a read or write command without assigning a
device, or a search for a nonexistent string) will cause a question
mark to be printed at the left margin. The command may be retyped.Major errors cause control to return to the Keyboard Monitor and may be due to one of the causes listed in Table 1-22. These
errors cause a message to be printed in the form:

?ntC
where n is an error code and tC indicates that control has passed
to the Keyboard Monitor.

Table 1-22

Editor Error Codes

Error .Code

Meaning

Editor failed in reading a device. Error occurred in
device handler; most likely a hardware malfunction.

Editor failed in writing onto a device; generally a
hardware malfunction.

File close error occurred. For some reason the -output file could not be closed; the file does not exist
on that device.

File open error occurred. This error occurs if the
output device is a read-only device or if no output
file name is specified on a file-oriented output device.

Device handler error occurred. The Editor could not
load the device handler for the specified device. This
error should never occur.

During the editing of a file, the output device specified in the
command string may become full before the editing process is complete. If this is the case and a write is attempted on that device,
an error occurs. The output file is closed, the message:
FULL

*
1-89

is printed; control returns to the Command Decoder for a new
set of I/O specifications. The user must indicate a new output file
which will contain the text that would not fit on the output device,
and any further editing the user wishes to do. Since the contents
of the text buffer are retained through this procedure, no text
will be lost if this error occurs.

NOTE
If no output file is specified when control
returns to the Command Decoder, the Editor returns to the Command Decoder again;
this continues until an output device is specified. However, specifying an improper
outout device (such as PTR:) wi11 cansI': a
fatal error and the output buffer will be
destroyed.
.A.

" .

Assuming the output device is valid, the Editor will continue
the operation which filled the old file, putting all output into the
new output ~le. After editing is completed, the output files should
be combined with PIP. The entire process may appear as follows:

!R EDIT
!OU'F-<JN
#y

#J
! STRING'

E!:lk.k

!DTA3:0UT2<

D&1.
#.L

TAD STRING

Device DSK: is full; DTA3: is specified
as the new output device, and editing
continues.

!.D
#E

,tDTA4:0UT3<

Device DTA3: has become full; DTA4:
is now specified as the output device, and
editin~ continues.

At this point the output "file" is the series of files-DSK:OUT,
DTA3:0UT2, and DTA4:0UT3. When output is split like this,
the split may have occurred in the middle of aline. Therefore, the
output files should never be edited separately as the split lines will
then be lost. In a case such as this, the files should be combined
with PIP as follows:
. 1-90

• R PIP
~DTA2:0UT<DSK:OUT~DTA3:0UT2~DTA4:0UT3

The new file, OUT, may then be edited.

Example Using the Editor
The following example illustrates both the use of the Editor to
create a new fiie, and a few of the commands available for editing.
Sections of the printout are coded by letter--corresponding explanations follow:
A The user calls EDIT; the output file will be called FILE and
will be stored on the default device. There is no input file
since one will be created from the terminal keyboard. The
Append command is used to insert text into the empty buffer.
B

Text is inserted.

The user makes a. mistake and uses the RUBOUT 'key to correctit.

More textis added.

The user notices a typing mistake he _has made several lines
back in the text. He types a CTRL/FORM to finish the Append command, searches for the illegal character, corrects it,
and then lists the line.

The P command writes the current buffer into the output file
placing a form feed after the last line. The K command deletes
all text in the current buffer, in preparation for a new page
of text.
G The user inserts new text using the Append command. Whe.n
he is finished, he types a CTRL/FORM to end the command.

The E command closes out the file. Control is returned to the
Keyboard Monitor.

1-91

• R EDIT
*FILE<

A
{

/PTP' PTR HANDLER FOR THOSE
IWITHOUT HIGH SPEED 1/0

IFZERO NOHSPT+LIST <XLIST>
IFNZRO NOHSPT <

{
PTP,

(2)

CLA CLL CMX\L
Cl
JMS PSETUP
PTPLP, KSF
JMP PTPCNT
(
)
'KRT
AND PTP1??
TAD PTPM3
[

I SET

LINK

IKEYBOARD FLAG OFF

D\
l

E{#·-2S

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

#m,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.

#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 240)
(ASCII 257)
(ASCI[ 211)
(ASCII 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<DTA2:NFILE/D

will first delete file OFILE on DTAI, and then transfer the
data from NFILE to a new OFILE. /D is useful when insufficient room exists on the output device for both the old
file and the new file.

1-98

-Table 1-24
Option

PIP Options (Cont.)
Meaning

/ D may be used to delete up to three files at a time by
specifying the files to be deleted as output files and not
specifying any input files. For example:
*OLDABC,DTA3:FILES/D<

This command string deletes OLDABC from DSK, and
FILES from DTA3.
/E

List directories in extended form (the lengths of the empty
files are also listed) .

List directories in short form (file names only).

Ignore any errors which occur during a file -transfer and
continue copying.

Transfer files in image mode. Used to transfer core image
(SAVE format) files, and any other files which do not fall
into either ASCII or Binary categories.
This option always opens the output file even if no input
files were specified. Thus, the II combined with the -n
option allows the user to substitute a named file for an
empty one. For example, a 23-block file named IMPORT.
P A was accidentally deleted. It can be recovered with the
following command:

Note that 23 10 = 278.

List the directories of the input devices onto the output
file starting at the file specified. Notice that in this case the
input file itself is not transferred, only the directory. The
directory listing is in extended form, but .empty files are
excluded. If no output file is specified, TrY: is assumed if
it- exists.

Save n extra words per file entry in the directory to contain descriptive information about the file (only the 2 low
order octal digits on nnnn are significant). For use with
the IZ and IS options only. Typing = 1 allows the date of

1-99

Table 1-24
Option

• AP Options (Cont.)
Meaning

the file creation to be automatically stored in the directory.
(= 1 is assumed after /Z or /S options unless otherwise
specified. Specifying =0 will still reserve one extra word
per entry.) Specifying = 100 will reserve no extra words
per entry.
II

If an
option is included with an image mode (jI) transfer, the low order 12-bits of the
option specify the desired length with which to close the output file. The output file is given this length except in the following two
cases:

1. If the data written is greater than the specified length,
the output file is given its correct size.
2. If the length specified is greater than the empty space
available, the data is transferred but the file is not
closed. The error message:
MONITOR ERROR 6 AT xxxx
(DIRECTOR Y OVERFLOW)
is printed and control returns to the Keyboard Monitor.
Data in the file following the EMPTY is not destroyed.

Okay to compress files or to zero the directory. When used
with the /S or /Z option, /0 prevents the messages ARE
YOU SURE? and ZERO SYS? from printing. The sy~tem
assumes that the u~er really wants the /S or /Z option.
Move all files from the input device (0 the output device,
eliminating any embedded empty files. All device names
should be explicitly stated, as no default devices are assumed. The directory of the output device will contain only
those files that appeared on the input device. Whenever a
/ S is initiated, PIP asks:
ARE YOU SURE?

The user responds with a "Y" if he wishes the compression;
typing any other character aborts the command.

1-100

Tab~e' 1-24

PIP Options (Cont.)

Meaning

Option

NOTE
When the IS option is used, the output device directory is read to determine whether
it is a system directory. If a system exists on
the output device, that system will be preserved on the IS tran~fer. To eliminate the
system directory, a IZ must be performed
before the IS.
In addition to compressing directories, I S provides a means
of copying one device to another. DEOtapes, for example,
can be copied by compressing one DECtape onto another
tape.
IT

Perform the following conversions of special characters: '
Chara,cter

Is Converted"To:

TAB

enough spaces to reach the next
TAB stop (every eighth position)

Vertical
TAB

FORM FEED

5 LINE FEEDs
9 LINE FEEDs

IT option is valid in ASCII mode only.

Print the current version number of PIP. This option
should be included in the first command line entered after
PIP is called. The version number is printed on the console terminal.

Copy the OS/8 System Area (records 0, 7-67) between
the output and first input file. Both dtrvices must be file
structured devices. If no file name is specified after a device
name, the System .Area of that device is assumed. If the
I Z option is used with I Y, a zeroed system directory is
placed on the output device before the system transfer
takes place. A system directory indicates that file storage
starts at record 70 rather than -record 7.

Zero directory of output device before file transfer. Before
using a DECtape for the first time, the I Z option should
always be used to create an empty file directory. No input
files are specified. For example:

1-101

Table 1·24

PIP Options (Cont.)

Meaning

Option
.!.DTA2:/Z<=1

One extra word per entry is used if no "=" is specified.
Thus, the DATE word is always left available in a new
directory.
If an attempt is made to zero the directory of the system
device, the message:
ZERO SYS?

is printed. A response of 'Y' will zero the directory; any
other response will abort the command and return control
to the Command Decoder.

No data transfer occurs if no input files are specified. Thus, as
mentioned previously, IZ can be used to zero a directory, and ID
can be used to delete a permanent file without creating a file. For
the three directory listing options (IE, IF, IL), if no output device is specified, the device TTY: is assumed. If no input device is
specified, device DSK: is assumed.
EXAMPLES OF PIP SPECIFICATION COMMANDS
The following are legal command strings to PIP. When PIP
has completed an operation, control returns to the Command Decoder for additional input.
Example 1 (ASCII Transfer) :
.:R PIP
*SYS: BLACK<PTR:

This command string transfers a tape from the paper' tape reader
to a file on the system device under the name BLACK. PIP assumes that the input tape is in ASCII format. (Control returns
to the Command Decoder, therefore, the .R PIP command need
only be given once.)
1-102

Example 2

(ASCII !File Merge) :

!DTA3:MERGE<DTAl':FILEl~FILE2

This command string instructs PIP to merge the ASCII files FILEI
and FILE2 on DTAI into one ASCII file, MERGE, on DTA3 .
. Example 3 (Binary Transfer):
.tEIN. BN<PTR: /B

The above com~and reads.a binary paper tape from' the paper
tape reader and creates a binary file BIN.BN on the device DSK.
Example' 4 (Image Transfer) :

PIP transfers the core image file P AL8.SV from the device DSK
to GAG.SV on the system device.

NOTE
A problem occurs when files longer than
255 blocks are transferred in Image Mode
from a directory device. If this is attemped,
the transfer will not end with the real endof-file, but will continue until the output·
limit is reached; an error message will occur.
For example, trying to transfer FORT.PA
or SABR.P A from the directory device using Image Mode will cause this error.
ASCII mode must be used for all PIP transfers of this type, or the FOTP program may
be used.
Example 5

(Directory Listing):

1TTY: </E

This command string produces an extended listing of the device
DSK on the Teletype. An extended listing contains all files with
1-103

their associated lengths, and all empty spaces in the directory. For
example, an extended listing might appear as follows .. (The current date is printed before the file listing provided the DATE command has been given; see the section concerning the Keyboard
Monitor for a description of the DATE command.):
2/17/72

EDIT • SV 12 1/10/72
TEST2
-4 1/10/72
ABCD • DA
1 2/17/72
<EMPTY>
7
-4 1/10/72
TEST2 • RL
<EMPTY>
702
709 FREE BLOCKS

The file lengths and number of free blocks are designated as
decimal values. The date 6f file creation is printed if at least one
additional information word is present in the directory (refer to
the section Additional Information Words in File Directories).
Example 6 (Directory Listing):
~/F

This command produces a directory listing of file names only. Thus,
the· preceding directory would appear on the teleprinter as follows:
2/17/72

EDIT • SV
TEST2
ABCD .DA
TEST2 • RL
709 FREE BLOCKS

Example 7

(Directory Listing):

~LPT:<DTA2:FETCH/L

A command such as the above produces a listing of the DT A2
directory on the line printer; however, the files that occur before
FETCH are not listed. The /L option gives the regular listing
which includes the file name and extension length, and date (if a
date is contained in the directory). Empty files are not indicated
in the listing.

1-104

Example 8

(System Area Transfer) :

!DTAl:HEAD</Y

Records 0 and 7-67 are transferred from SYS: to a file named
HEAD on DTA1.
Example 9 (System Area Transfer) :

*SYS:<DTAl:HEAD/Y
.

The contents of the file HEAD on DT Al are transferred to the
'. System Area (records 0 and 7-67) of the system device. The input
file is checked for validity before the transfer occurs.
Example 10 (System Transfer with Directory Zero) :
,!DTA 1 : <DTA0: (YZ )

This first crea'tes a zero system directory on DTAI, and then
transfers the system area from DT AO to to the System Area on
DTAI. A system directory indicates that file storage begins at
record 70 rather than record 7.
Example 11 (System Area Transfer) :
*DTAl:TR~~<DTA2:TR~~/Y

. This command string instructs PIP to transfer TRAN from DT A2
to DTAI. Since the /Y option is used, TRAN must be a copy
of the OS/8 System Area. However, since transfers of this type
involve files on both the I/O devices, and not the System Area, the
transfer is treated as an image transfer and either the IY or II
options can be used.
Additional Information Words in File Directories
If a device has any additional information words specified in its
directory, OS/8 automatically enters the last date specified in a
DATE command into the first of the additional information words
when a file is created on that device. Dates put into these additional
words appear in directory listings. Words after the first are not
currently used by the OS/8 system.
Whenever a IZ or IS is given, additional words can be specified
by a IZ==n or IS==n construction. The number' of additional
words can be changed by compressing a device onto itself. The
.

1-105

first additional information word is used by the system for the
file's creation date.

NOTE
The system is initially created with one
additional word in the file directory.
PIP Error Messages
The following messages are printed by PIP in response to user
errors or improper command strings:
Table 1-25 PIP Error Messages
Meaning

Message
ARE YOU SURE?

Occurs when using the I S option. A response of 'Y' will compress the files.

BAD DIRECTORY ON
DEVICE # n

Error message occurs when:
1. PIP is trying to read the directory,
but it is not a OS/8 directory.
2. The output device does not have
a system directory, i.e., file storage
begins at record 7 (occurs during
a I Y transfer).
n is the number of the file in the input
file list.

BAD SYSTEM HEAD

If the I Y option is used and the area
being transferred does not contain OS/8,
this error message results.

CAN'T OPEN OUTPUT
FILE

Message has occurred due to one of the
following:
1. Output file is on a read-only device.
2. No name has been specified for
th~tput file .
. 3. A I'\"transfer has been attempted
to a non-directory device.
4. Output file has zero free blocks.

DEVICE # n NOT A
DIRECTORY DEVICE

Message occurs when:
1. Trying to list the directory of a
non-directory device.
2. The input designated in a IY
transfer is not on a directory de-·
vice.
n gives the number of the device in the
input list.

1-106

:Table 1-25

PIP Error Messages (Cont.)

Message

Meaning

DIRECTORY ERROR

An error has occurred while reading or
writing the directory during a ; S option. The option is aborted; output is
likely to be garbled.

ERROR DELETING
FILE

An attempt was made to delete a file
that does not exist. Check that the device. name was explicitly given for all
files.

ILLEGAL BINARY
INPUT, FILE # n

Self explanatory; n is the number of the
file in the input file list.

INPUT ERROR,
FILE # n

An'input error occurred while reading
file number n in the input file list.

10 ERROR IN (file name)
, -'CONTINUING

An error has occurred during a / S
transfer. The name of the file being
transferred is. Indicated.

LINE TOO LONG IN
FILE # n

In ASCII mode a line has been found
greater than 140 characters. Make certain the file is an ASCII file. n is the
number of this file in the input list.

NO ROOM FOR
OUTPUT FILE

Self-explanatory; either room on device "or room in directory i.s lacking.

NO ROOM IN (file name)
-CONTINUING

Occurs during use of the / S option. The
output device cannot .contain all of the
files on the input device. The message is
printed for each file which "will not fit
into the output device. The file name is
indicated.

OUTPUT ERROR

Output error-possibly a WRITE
LOCKed device, parity error, or attempt to output to a read-only device.

PREMATURE END OF
FILE, FILE # n

Message occurs in Binary Mode (I B)
only. A physical end-of-file has been
found before the final leader/trailer.

SORRY-NO
INTERRUPTIONS

Error message occurs if:
1. tC (CTRL/ C) is typed while compressing a file onto itself; the
transfer continues.

1-107

Table 1·25

PIP Err,or Messages (Cont.)

Message

Meaning
2. A IY tran~fer is done with system
device as the output deyice, or if
the transfer has both input and
output on the same device.

ZERO SYS?

If any attempt is made to zero the system device directory, this message occurs. Responding with 'V' causes the
directory to be zeroed. Any other character aborts the operation.

ABSOLUTE BINARY LOADER
The Absolute Binary Loader is used to load the binary output
created by the PAL8 assembler. Input files are loaded according
to the options discussed in this section, and a core control block
is constructed (see the section concerning the GET command).
The standard input devices are the paper tape reader, DECtape,
LINCtape, the default storage device (DSK:), and SYS:, which
represents thp system device. Any other device which can contain
absolute binary files can be used as an input device if ~ device
handler exists. The terminal (TTY:) should not be used, as the
binary code may appear as control characters to the TTY handler.
Calling and Using ABSLDR
ABSLDR normally accepts absolute binary files (relocatable
files must be loaded with the Linking Loader); however, save
(.SV) format files can be loaded with ABSLDR providing the
/1 option is used. If no extension to the input file name is typed,
ABSLDR assumes the .BN extension. Up to nine input files are
allowed, but if more than one program is present in a file, only the
first program is loaded unless the /S option is used. (This feature
allows ABSLDR to ignore any 'noise characters' which might be
caused by reading over the end of a paper tape.)

The user calls the Absolute Binary Loader from the system
device by typing:
R ABSL.DR

1-108

in response to the dot printed by the Keyboard Monitor. The system responds by printing an asterisk at the left margin. The user.
then types an input line to ABSLDR, indicating input files and any
options desired. ABSLDR does not recognize any output files,
since the purpose of the loader is to load and optionally start
binary output files. The forma.t of the input line is:
*DEV: INPUT .EX/ (Options)·
By typing the RETURN key at the end of an input specification
line, the loader is signalled that more iilput is to be given on the
next line. If the ALT MODE key is used as a line terminator, no
more input is expected, the Command Decoder is not recalled,
and control returns to the Keyboard Monitor. For example:
:.R ABSLDR
~DTAI :FILE1 .. FILE2,FILE3,FILE4

~PTR: $

(Carriage RETURN)
(ALT MODE)

The preceding lines cause FILE 1, FILE2, FILE3; and FILE4
to be loaded at their absolute locations in core from, DECtape 1.
A file is then to be read from the paper tape reader. The $ character is printed by the ALT MODE key which indicates a return
to the Keyboard Monitor.

NOTE
If· the /G option (load and begin execution) is specified, control always passes to
the program just loaded, regardless of which
line terminator was typed.

When ABSLDR has completed loading and control has returned
to the Keyboard Monitor, the program loaded may not be physically in core at that moment. ABSLDR utilizes system scratch
blocks to store those locations which would overlay various parts
of the Monitor. To examine core locations after using ABSLDR,
use ODT (see the section concerning ODT for instructions detailing its use).
1-109

ABSLDR OPTIONS
The various options accepted. by ABSLDR are described in
Table 1-26.
Table 1-26 ABSLDR Options
Option

Meaning

Used when locations 0-1777 of field 0 are not being used
by the program. Eliminates extra DECtape motions to save
these locations, hence saves time. See the OS/8 Software
Support Manual for details of Job Status Word.

Similar to the /8 option; used when locations 0-1777 of
field 1 are not to be saved.

Treat the input fi1e(s) as a core-image-file to be overlaid
with the input of succeeding lines. (If this option is not
used in the first command line, it cannot be used unless
ABSLDR is recalled from the Keyboard Monitor level.)
The / I option can be used to make patches to an already
saved program without reassembling the entire program.

Reset internal core map of ABSLDR to appear as though
nothing has been loaded into core.

Load all binary programs in the specified input file (s)
(inst\..ad of loading only the first program in each file,
which is normally done). / Sand / I operate on a line-at-atime basis. Each successive command line must have the
option respecified if it is required. For example:
;l;PTR:...., /5
;l;DTAl :A, B .. C

These command strings instruct ABSLDR to take three files
from PTR (loading all binary programs in each file) and
three files from DTA 1 (loading only the first binary program in each file). / S is not implemented on the second
line.

Sets bit 3 of the Job Status Word (location 07746) and
prevents the Keyboard Monitor from reading a fresh version of the BATCH monitor into core every time the monitor level is reentered from the program level. This option
can be used with system programs that never use more
than 8K of core (PIP, FORTRAN II, SABR). The IP
option should not be used with any program that occupies
or modifies core above field 1. (See the BATCH section.
for further information.)

1-110

Table 1-26

ABSLDR Options (Cont.)

Option

Meaning

Start program execution upon finishing the loading procedure. Normally, control returns either to the Monitor or
Command Decoder (depending on the terminator key). If
/ G is specified, control is given to the program just loaded.
The starting address is assumed to be 200 unless specified
in the input string. Control stays with the user's program
until it is released to the Monitor from within the program.
No automatic return to Monitor or the Command Decoder
occurs.

Force loading of all files specified on this input line into
field n (where n is an octal integer).

Set the starting address of the program in core to n, where
n is a 5 digit octal integer. ABSLDR inserts a starting address of 0200 in field 0 if no other. address is indicated.
Specifying 0 as a starting address is equivalent to not specifying a starting address, thus ABSLDR would insert a
starting address of 0200.

EXAMPLES OF INPUT LINES
Example 1:
•

!R ABSLDR
!SYS: PR'JG. SVI I
~DTAl:PATCH$

!SAVE SYS: PROG

The above commands load the core-image file PROG.SV and then
overlay part of that program file with a binary patch from DT AI.
Control then returns to Monitor, at which time the user saves the
patched program on the system device.
When" using the /1 option, the starting address and Job Status
Word of the core image being loaded are ignored by the Loader.
The user must specify the starting address and contents of the Job
Status Word (unless the starting address is 200 in field 0, i~n which
case it need not be specified).
Example 2:
!oR ABSLDR
!PIP.SV/I
:!;PTR:=130021(89)$
.:.S,r,WE SYS PIP

1-111

In this example, the user overlays.PIP with a binary patch which
will not change its starting parameters. This could also be accom- .
plished using an explicit SAVE:
!,R ABSLDR
~PIP.SV/I

-*PTR:

~SAVE

SYS PIP; 13000:::6003

Example 3:
:R ABSLDR

!PTR:C89G)$

One binary tape is loaded from the paper tape reader. Areas
00000-01777 and 10000-11777 of core are not used by the program. The starting address of the program is considered to be
00200; control is transferred to the user program.

Notes On Using ABSLDR Correctly
ABSLDR is a complex program which, when used incorrectly,
can give unrecoverable errors. Points to remember when using
ABSLDR are:

1. If an erroneous starting address is specified, control will be
passed to that address, however random it may be. Thus,
specifying a starting address in non-existent memory, for
example, will very likely produce erroneous results, and
should not be attempted.
2. Trying to load a program into non-existent memory should
not be attempted.
3. Programs which load into 07600 or 17600 are ignored by
ABSLDR. No error is generated, but these locations are
never loaded. (It is a good idea not to use 7600 in any
field.)
4. Old versions of ABSLDR should not be used with a new
monitor.
5. New versions of ABSLDR should not be used with old monitors.
1-112

ABSLDR Error M~sages
Table 1-27 lists the error messages output by ABSLDR. In each
case, control returns to the Command Decoder'; the entire procedure may be attemped again by resetting tlIe loader (with the
/Roption) and using different inputs.

Table 1-27 ABSLDR Error Messages

Message

Meaning

BAD CHECKSUM,
FILE # n

File number n of the input file list has
a checksum error.

BAD INPUT, ,FILE # n

Attempt was made to load a non-binary
file as file number n of the input file
list, or a non-core image with I I option.

10 ERROR FILE # n

An II 0 error has occurred in input file
number n.

NO INPUT

No input file was found on the designated device.

NOlI!

Use of II is prohibited at this point.

OCTAL DEBUGGING TECHNIQUE (ODT)
ODT allows the programmer to run his program on the computer, control its execution, and make alterations to the program by
typing instructions at the keyboard.
Features
ODT features include location examination and modification;
and instruction breakpoints to return control to ODT (breakpoints). ODT makes no use of the program interrupt facility and is .
/
invisible to the user program.
The breakpoint is one of· ODT's most useful features. When debugging a program, it is often desirable to allow the program to
run normally up to a predetermined point, at which the programmer may examine and possibly modify the contents of the accumulator (AC), the link (L), or various instructions or storage locations within his program, depending on the results he finds. To
ac~omplish this, ODT acts as a monitor to the user program .
. 1-113

The user decides how far he wishes the program to run and ODT
inserts an instruction in the user's program which, when encountered, causes cont.rol to transfer back to ODT. ODT immediately
preserves in designated storage locations the contents of the AC
and L at the breakpoint. It then prints out the location at which
the breakpoint occurred, as well as the contents of the AC at that
point. ODT will then allow examination and modification of any
location of the user's program (or those locations containing the
AC and L). The user may also move the breakpoint, and request
that ODT continue running his program. This will cause ODT to
restore the AC and L, execute the trapped instruction and continue
in the user's pr-ogram until the breakpoint is again encountered
or the program is terminated normally.
Calling and Using ODT
As explained in the section concerning the Keyboard Monitor,
ODT is called into use by typing:
ODT

in response to the dot printed by the Keyboard Monitor. Before
ODT is called, the user should have a running version of his program in memory. None of the user's memory is disturbed by the
running of ODT, because the sections of the program which ODT
may occupy when in memory are preserved on the syste~ device
and swapped back into memory as necessary. ODT uses the Job
Status Word of the particular program to determine whether or
not swapping occurs. If the program does not use locations 0-1777
in field 0, less swapping occurs during use of the breakpoint
feature.
If the user is typing any amount of a program directly into
memory (in octal), the memory control block of the program may
not reflect the true extent of the program. If octal additions are
made below location 2000 in field 0, ODTmay give erron~ous
. results. The user can correct this condition by correcting the Job
Status Word, which is location 7746 of field 0, and which c~n be
examined and changed using ODT. Location 7745 of field is the
12-bit starting address of the program in memory and location
7744 contains the field designation in the form 62n3, where n is
the field designation of the starting address. .
When using the breakpoint feature of ODT, the user should
.
keep certain operating characteristics in mind:

1-114

1. If a breakpoint is inserted at a location which contains
. an auto-indexed instruction, the auto-indexed register is
bumped immediately after the breakpoint is hit. Thus, when
control returns to the user in ODT, the register will have
been increased by one. The breakpoint .instruction is executed properly, but the index register, if examined, may ap·pear one greater than it should.
2~ ·ODT keeps track of the TTY flag and restores the TTY
flag when it continues from a breakpoint.
3. The breakpoint feature uses locations 4, 5, and 6 in the
memory field in which the breakpoint is set.
4. The breakpoint feature of ODT uses the table of user-defined device names as scratch storage, destroying any device
names the user may have created. After a session with ODT
in which breakpoints are used, the user should give a DEASSIGN command to clear out the user-device name table.
5. Breakpoints must not be set in the Monitor, in the device .
handlers, or between a CIF and the following IMP instruction.
The us.er is advised not to use user-defint~d device names in'programs being developed with ODT breakpoints.
If any operations are attempted in non-existent memory, ODT
ignores the command and types "?". Thus, assuming the machine
in use has 8K (fields 0 and.1) and the user attempts to examine
locations in field 2 and above, ODT responds with?
ODT should not be used to debug programs which use interrupts. Typing CRTL/C returns control to the Keyboard Monitor;
the program can be saved on any device.

Commands
SPECIAL CHARACTERS
Slash(/ }-Open Preceding Location
The location examination character (/) causes the location ad-dressed by the octal number preceding the slash to be opened and
its contents printed in octal. The open location can then be modified
by typing the desired octal number and closing the location. Any
octal number from· 1 to 4 digits in length is legal input. If more
than 4 digits are entered, only the last 4 entered are accepted by
ODT. Typing / with no preceding argument causes the latest
named location to be opened.
1-115

For example:
400/1540
400/1540 246d?
400/1:'40 12345
/2345

Return-Close Location
If the user has typed a valid octal number after the content of a
location is printed by aDT, typing the RETURN key causes the
binary value of that number to replace the original contents of the
opened location and the location to be closed. If nothing has been
typed by the user, the location is closed but the content of the location is not changed. For example:
400/6046
400/6046 2345
/2345 6046

location 400 is unchanged.
location 400 is changed to contain 2345.
replace 6046 in location 400.

Typing another command will also close an opened register. For
example:
400/6046 401/6031 2346
400/6046 4~1/2346

location 400 is closed and unchanged
and401 is opened and changed to 2346.

Line Feed-Close Location, Open Next Location
The LINE FEED key has the same effect as the RETURN key,
but, in addition, the next sequential location is opened and its contents printed. For example:
40e,/1540'
00Ll01 /23LlS
e,eLlC:)2 17 (:50.

location 400 is closed unchanged and 401 is
1234 opened. "User types change, 401 is closed containing 1234 and 402 is opened.

t(Shitt/N)-Close Location, Take C;ontents as Memory Reference
and Open Same
The up arrow will close an open location just as will the RETURN key. Further, it will interpret the contents of the locatiori as
a memory reference instruction, open the location referenced and
print its contents. For example:
1-116

404/3270 t
00470 /4512 0000

3270 symbolically is "DCA,· this page,
relative location 70," so ODT opens location 470.

~(Shift/O) Close Location, Open Indirectly

The back arrow will close the currently open location and then
interpret its contents as the address of the location wh()se contents
it is to print and open for modification. For example: .
36S/32CZl3 t
00203 /3572 ..
03572 /0216

ILLEGAL CHARACTERS
Any character that is neither a valid control character nor an
octal digit causes the current line to be ignored and a question
mark printed. For example:
Lj:

4U?
406/113667K?

/1136

} ODT opens no location.
ODT ignores modification and closes
location 406.

CONTROL COMMANDS
nnnnG-Transfer Control to User at Location nnnn
Clear the AC then go to the location specified before the G. All
indicators and registers will be intialized and the breakpoint, if
any, will be inserted. Typing G alone will ca~se a jump to location O.
n~nnB-Set Breakpoint at User Location nnnn -

Instructs ODT to establish a breakpoint at the location specified before the B. If B is typed alone, ODT removes any previously established breakpoint and restores the original contents of
the break location. A breakpoint may be changed to another location whenever ODT is in control, by simply typing nnnnB where
nnnn is the new location. Only one breakpoint may be in effect at
one time; therefore, requesting a new breakpoint removes any pre- .
viously existing one.
A restriction in this regard is that a breakpoint may not be set
on any of the floating-point instructions which appear as arguments of a JMS.
1-117

The breakpoint (B) command does not make the actual exchange of OnT instruction for user instruction, it only sets up the
mechanism for doing so. The actual exchange does not occur until
a "go to" or a "proceed from breakpoint" command is executed.
When, during execution, the user's program encounters the location containing the breakpoint, control passes immediately to OnT
(via location 0004). The C(AC) and C(L) at the point of the
interruption are saved in special locations accessible to OnTo The
user instruction that the ~reakpoint was replacing is restored, before the address of the trap and the content of the AC are printed.
The restored instruction has not been executed at this time. It will
not be executed until the "proceed from breakpoint" command is
o
{Yiven_. Anv user location. includim! those containill!! the stored AC
and Link, can now be modified in the usual manner. The breakpoint can also be moved or removed at this time.
An example of breakpoint usage follows the section "Continue
and Iterate Loop ... "
J

A-Open C(AC)
When the breakpoint is encountered the C(AC) and C(L) are
saved for later restoration.- Typing A after having encountered a
breakpoint, opens for modification the location in which the AC
was saved and prints its contents. This location may now be modified in the normal manner (see Slash) and the modification will be
restored to the AC when the "proceed from breakpoint" command
IS gIven.
Open C(L)
Typing L opens the Link storage location for modification and
prints its contents. The Link location may now be modified as usual
(see Slash) and that modification will be restored to the Link when
the "proceed from the breakpoint" command is given.
C-Proceed (Continue) From a Breakpoint
Typing C, after having encountered a breakpoint, causes OnT
to insert the latest specified breakpoint (if any), restore the contents of the AC and Link, execute the instruction trapped by the
previous breakpoint, and transfer control back to the user program
at the appropriate location. The user program then runs until the
breakpoint is again encountered.
.
1-118

NOTE
If a breakpoint-set by ODT is not encountered while ODT is running. the object
(user's) program, the instruction which
causes the break to occur will not be removed from the user's program.

nnnnC--Continue and Iterate Loop nnnn Times Before Break
The programmer may wish to establish the breakpoint at ·some
location within a loop of his program. Since loops often run to
many iterations, some means must be available to prevent a break
from occurring each time. the break location is encountered. This
is the function of nnnnC (where nnnn is an octal number). After
. having encountered the breakpoint for the first time, this command
specifies how many additional times the loop is to be iterated before another break is to occur. The break operations have been
'- described previously in the section on the B command.
Given the following program, ~hich increases the value of the
AC by increments of 1, the use of the Breakpoint command may
be illustrated.
*20.0.
0.0.20.0.
0.0.20.1
0.0202

0.20.0.
730.0.
120.6
2207

002e'3

52e,2

0.10204
00.205
01020.6
1002107

5201
7402
100101
000.10

A
CNT
O\lE

02018
200G
00201
C
0020.1
C
00.20.1
4C
0.0.20.1

CLA Cll
TAD CNE
I Sl CNT

JMP B
JMP A
HLT
Q\J E~
CNT~

1
0.

*20.0
8

*20.0.

1020.1
0.20.2
.0.20.7
0206
(0; 0.0.0.0
(0.; 0.0.0.1
(0; 0.0.0.2
( 0; 0.0.0.6

1-119

ODT has been loaded and started. A breakpoint is inserted at
location 0201 and execution stops here showing the AC initially
set to 0000. The use of the Proceed command (C) executes the
program until the breakpoint is again encountered (after one complete loop) and shows the AC to contain a value of 0001. Again
execution continues, incrementing the AC to 0002. At this point,
the command 4C is used, allowing execution of the loop to continue 4 more times (following the initial encounter) before stopping at the breakpoint. The contents of the AC have now been
incremented to 0007.

M-Open Search Mask
Typing M causes ODT to open for modification the location
" containing the current' value of the search mask and print its contents. Initially the mask is set to 7777. It may be changed by opening the mask location and typing the desired value after the value
printed by ODT, then closing the location.
M Line Feed-Open lower search limit
The word immediately following the mask storage location contains the location at which the search is to begin. Typing the LINE
FEED key to close the mask location causes the lower search limit
to be opened for modification and its contents printed. Initially the
lower search limit is set to 0001. It may be changed by typing the
desired lower limit after that printed by ODT, then closing the
location.
M Line Feed-Open upper search limit

The next sequential word contains the location with which the
search is to terminate. Typing the LINE FEED key to close the
lower search limit causes the upper search limit to be opened for
modification and its contents printed. Initially, the upper search
limit is the beginning of ODT itself, 7000 (1000 for low version).
It may also be changed by typing the desired upper search limit
after the one printed by ODT, then closing the location with theRETURN key.

nnnn w-word Search
The command nnnn W (where nnnn is an octal number) will
cause ODT to conduct a search of a defined section of memory,
using the mask and the lower and upper limits which the user has
1-120

specified, as indicated above. The word searching operations. are
used to determine if a given quantity is present in any of the locations of a particular section of memory.
The search is conducted. as follows: ODT masks the expression
nnnn which the user types .preceding the Wand saves the result as
the quantity for whic~ it is searching. (All masking is done by performing a Boolean AND between the contents of the mask word,
C(M), and the word containing the instruction to be masked.)
ODT then masks each locatiori within the user's specified limits
and compares the result to the quantity for which it is searching.
If the two quantities are identical, the address and the actual unmasked contents of the matching location are printed and the
search continues until the upper lir.nit is reached.
.
A search never alters the contents of any location. For example:
search locations 3000 to 4000 for all ISZ instructions, regardless
. of what location they refer to (i.e. search for all locations beginning with an octal 2) .
1

M/7777 7000
7453/5273 3000

Change the mask to 7000, open l~wer
search limit.
Change the lower limit to 3000, open
upper limit.

7454/1335·4000
2000W
00005 12331
00006 12324
00011 12222
00033 12575

Change the upper limit to 4000, dose
location.
Initiate the search for ISZ instructions
These are 4 ISZ instructions in this
section of core.

Additional Techniques
CURRENT LOCATION
The address of the current location or last location examined is
remembered by ODT and remains the same, even after the commands G, C, and B are typed. This location may be opened for inspection merely by typing the slash (I) character.
INDIRECT REFERENCES
When. an indirect memory reference instruction or an address
constant is encountered, the actual address may be opened by
typing t and ~ (SHIFT IN and SHIFT10, respectively).
1-121

Errors
The only legal inputs are control characters and octal digits. Any
other character will cause the character or line to be ignored and
a question mark to be printed by ODT. Typing G alone is an
error. It must be preceded by an address to which control will be
transferred. This will elicit no question mark also if not preceded
by an address, but will cause control to be transferred to location O.
Programming Notes.Summary
.
. ODT will not tun~ on the program interrupt, since it does not
know if the user's program' is using the interrupt. Ii does, however,
turn off the interrupt when a breakpoint is encountered, to prevent
spurious interrupts.
Breakpoints are fully invisible to "open location" commands;
however, breakpoints may not be placed in locations which the
user program will modify in the course of execution or the breakpoint will be destroyed. Caution should be used in placing a breakpoint between a call to USR function code 1o and the following
call to USR function code J 1.
If a trap set by ODT is not encountered by the user's program,
the breakpoint instruction will not be removed.
ODT can be used to debug programs using floating-point instructions, since the intercom location is 0004, and since breakpoints may be set on a JMS with arguments following.
Summary of OnT Commands The following table presents a brief summary of the ODT commands. All addresses can be input as 5 digits. and are printed as
5 digits.

Table 1·28 ODT Command Summary
Meaning

Command
,
nnnnn/

Open location designated by the octal number
nnnnn, where the first digit represents the merpory field. ODT prints the contents of the location, a space, and waits for the user to enter a
new value for that location or close the location.
Reopen Jatest opened location.

1-122

Table··1-28

ODT Command Summary (Cont.)

Comrpand

Meaning

nnnn;

Deposit nnnn in the currently opened location,
close that location and open the next sequential
location for modification. A· series of octal
values can be deposited in sequential locations
through use of the; character. Multiple ;'s skip
a. memory location for each ;> 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<SYS:/f>
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<OTA1:P~OG.PA

(;PEF
*OTA1:PROG.I.S
ItNO OF EXAMPL.E .'2 AND ENO OF INPUT FILE
St:NO
Figure 2-1: Sample BATCH Input File
.~UN

DS~

allowing a total of 260 spool device files, which is more than adequate in view of the limited maximum size of the OS/8 file directory (about 240 entries). If output to a spool device file is generated
by a program that appends a default extension to output file names,
the spool device file will be assigned a standard default extension.
All of the spool device files may then be transferred to the terminal
or line printer by using the program FOTP, with the input file
specification dev:BTCH?? *.
1

2-8

Returning to the example of Figure 2-1, PIP executes the file
specification that appears in the fifth record, of the input file ,and
recalls the Command Decoder.
The Command Decoder then instructs BATCH to scan the input
file fo~ the next file specification record. BATCH processes the
comment record by copying it onto the line printer, then processes
the $MSG command by ringing the terminal bell, copying the
$MSG record onto the terminal, and, assuming that an operator
is present, pausing until any key is typed at the terminal.
Once the operator has resumed processing by typing any character, BATCH reads the eighth record in the file, recognizes it as a
Command Decoder specification record, and transfers control back
to the Command Decoder.
. Processing continues in this manner until the third Commqud'
Decoder specification record is read. When' BATCH searches for
the next file specification record, it reads and executes the last
$MSG command, then encounters a Keyboard Monitor command.
BATCH passes this command to the Keyboard Monitor, which
terminates PIP and calls the FORTRAN compiler to load and com'"
_pile source program FORTSl. Upon completion of these operations, FORTRAN routes its output to the specified files and.returns
control to .the monitor level. BATCH then encounters the second
$JOB record, causing it to terminate the current job and print a
new header.
The second job calIs P AL8 to assemble a source program from
disk. The output listing is directed to the user's DECtape #2,
mounted on unit 1, while the binary output file is dumped onto
high-speed paper tape. The job concludes by running CREF to
produce a cross-referenced listing of the assembled program.
This job illustrates how OS/8 BATCH may be used to execute
multiprogram utility routines. If user #2 is a programmer who
usually follows a PAL8 assembly by running CREF, job #2 could
be a utility routine that combines the call to P AL8, the call to
CREF and both file specifications into a single software package
which may be run under batch processing or in an interactive environment.
The $END record that appears as the last record in Figure 2-1
serves as a signal that batch processing has concluded and causes
BATCH to recall the Keyboard Monitor and re-establish interactive
2-9

processing under OS/8. This command is always the last record of
.
the BATCH input file.
BATCH Error Messages .
BATCH generates two types of error messages. BATCH generates run-time error messages which appear in the form:
#BATCH ERR
the second type of error message is generated when the Keyboard
Monitor or the Command Decoder recognizes a command error in
the BATCH input file. When this occurs, either the Keyboard
Monitor or the Command Decoder will transmit a standard OS/8
error message and BATCH will append a "#" character to the
horr; ...... .,..,,1·....... o~ +hO ...,....·OC"C'I'l .....'O
V'"'5~HH

u~'"'

H~,",':>':>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 <i:emonstration programs are
1:_
.. ~,.1 .... l.."..tln tnprpafter
11~l~U t3.l~V.I. \'.LJ .......&_ ... .-- '-::

.R BATCH
*SYS:DEMO/U
SJOB 05/8 SATCH DEMO
SMSG 6EGt~ BY LISTING BATCH INPUT FILE ON TERMI~.LI
~H PIP
*TTYI<OEMO.IH
.DATE 3/5/74
~MSG SYSTEM D~YICE ASSIGNED LOGICAL NAME "IN"
.ASSIGN SYS IN
$MSG MOUNT 8tH.TCM OECTAPE ON UNIT 1
.w PIP
IZERO DECTAPE OI~ECTORY
SMSG ~RITE ENABLE UNIT 1
*DTA11</Z
I~IST SYSTEM OI~ECTORY ON LINE PRINTEw
*l.PTlcIN:/E
ITRANSFER DEMO PROGRAMS TO DECTAPE
*OTAlaOEM01.PAcUEM01.PA
*OTA1:0EM02.FTcUEM02.FT
*OTA1;O~M03.FTcOEM03.FT
I~IST THE FIRST DEMO PROGRAM

*TTYlclNIUEM01.PA/T
Il.IST THE SECONU OEMQ PROGRAM
*TTYlctNIOEMO~.FT/T

ILIST T"E THIRD DiMO PROGRAM
.TT~I<INIOEM03.FT/T

JASSEMBLE n~M01.PA
.R PALS
*INZOE M01,RN,DEM01.L5<INIUEM01.PA
IPRINT CROS~ WEfF~ENCE LISTING
.~ CREF
*~PTI<IN:OEMa1.~S
I~OAO ASSEMBLEO aINARY

.w A8l5LJFl

INTO CORE

2-16

*DEM01.SN$
IRUN FI~ST DEMO PROGRAM
.START ~0kl
INOW SAVE CORE I~AGE OF DEMOI.PA, BUT MUST
. I~ELOAO FiRST, SINCE DEMOl IS SELf.MOOIFYING
.
,R ABSLOR
,rdN:OEM01,ElNS
.SAVE SYS D~M01 0,2~0
/RUN D~M01.SV TO ~E SURE THAT IT wAS SAVED CORRECTLY
."WN. SYS DEMOl
_
'NOW COMPILE FORT~AN MAINLINE PROGRAM
.~ FORT
*IN:OEM02_BN~LPT:<IN20EM02.FT$

ICOMPILE fORTHAN FUNCTION HOWTINE
.1< FORT
*IN:DE M03.BN,LPT:cTN:DEM03.FTS
ITRANSF£~ ROTH BINARY FILES TO DECTAPE
.R PIP
*DTA1:DEM02.BNcOEMO~.eN/B
*DTA1:0~M03.BN<DEM03.~N/B

ILOAD AND f-XECUTE FOKTRAN PACKAGE
,t< LOADE.R
.DEM02.~N,DEM03.RN/G

IRENAME O~M03,BN FOR FUTURE REFERENCE
_R PIP
*FACTcOt:M03.6N/J:
*DEM03."N c /lJ
IADO FORTRAN FUNCTION TO FORTRAN LI8RARY

.R LI"SE.T
*l.IB8,~N/S
*FACT~

IFINALLY,
.t< ""IP
*FACTc/L)
INOW

O~LET~

CL~AN

TEMPORARY FILE "FACT"

DIS~

AREA

*OEM01.~N,DEM01.SV,DF.MO~,BN</D
~MSG

DE~ICE

NAMES DtASSIGNED

.DEASSHiN
$tND

$MSG SYSTEM DEVICE ASSIGNED LOGIC!~L NAME" IN"
$MSG MOUNT SCRATCH DECTAPE ON UNIT 1~
$MSG WRITE ENABLE UNIT 1

2-17

*10

IR 1,

~00

START,

TYPE,

TEST,

300
CLA CLL
TLS
TAD I IR 1
JMS TYPE
JMS TEST
JMP .-4

TSF'
JMP .-1
TLS
CLA
JMP I TYPE

TAD IRI
TAD M335
SZA CLA
JMP I TEST
TSF'
JM? .- 1
JMP 7600
-335
215;212;212;241;241;241;305;330;305;303
325;324;311;317;316;240;303;317;315;320
314;305;324;305;241;241;241;215;212;212

F'ORTRAN DEMONSTRATION PROGRAM
A(35)
DO 10 N=2,34,2
A(N)= F'ACTCN)
WRITE (1,60) N,AOn
STOP
F'ORMAT (13,'! =' ',EI4.7)
END
DIME~SION

10
50

C
1

FORTRAN FUNCTION TO COMPUTE FACTORIALS
F'U NCT I ON F' ACT ( N)
IF (N- 34) 1,5,5
IF' (N) 2,4,,2

1'1= N-2

3
4
5

FACT= ~
DO 3 K= 1 t M
C= N-K
FACT= FACT*C
RETURN
.F'ACT= 1 •
RETUR N
WRITE (1,6) N

2-18

FACT=I2I.
RETUR N
F:JRMAT C15, 'I EXCEEDS CAPACITY" OF PROGRAM. ')
E~D

. !! ! EXECUTION COMPLETE! !!
!! ! EXECUT ION CO[,!PLETE!!!

2! = 0.200000I21E+01
4! = 0.2420000E+02
6! = 0.7200000E+03
8! = 0.4032~0~E+05
10! = 0.3628800E+07
12! = 0.4790016E+09
1 4! = 0 • 8 7 1 7829 E+- 1 1
1 <5! = 0 .2 0922 79 8- 14 .
18! = 0.6402374E+16
20! :: 0.2432902 8-19
22! = 0.1124001 8-22
24! = 0.6204484E+24
26! = 0.4032915E+27
28!.- 0.J048883E+30
30! = 0.26525298-33
32·! = ,0.2 631308E+3~
34! EXCEEDS CAPACITY OF PROGRAM.
34! = 0.0000000E+00
$MSG DEVICE NAMES DEASSIGNED

IE!I4D Br\TCH

The next run is initiated via the SUBMIT command .
• SUBMIT SYS:<SYS:DEMO/U/T
SJOB OS/8 BATCH DEMO
$MSG BEGIN BY LISTING BATCH INPUT FILE O~ TELETYPE:
.R PIP
tTTYI<OEMO.SI
'SPOOL TO FILE BTCHAI
.DATE 8/3/72$MSG SYSTEM DEVICE ASSIGNED LOGICAL ·NAME "IN"
.ASSI GN' SYS IN
$MSG MOUNT SCRATCH DECTAPE ON UNIT 1
.R" PIP
IZERO DECTAPE DIRECTORY

2-19

$MSG WRITE ENABLE UNIT I
*DTAl: .../Z
ILIST SYSTEM DI~ECTORY ON LINE PRI~TER
!.PT: ...1 N: IE

ISPOOL TO FILE BTCHA2
ITRANSFER DEMO PROGRAMS TO DECTAPE
* DTAI: DEMOI • PA ...DEMOI. PA
* DTA I: DEMC2 • FT ...DEMC2 • FT
*DTAl: DEMo'). F'T"'DEM03. FT
ILIST FlijST DEMO PROGRAM
* TTY: ... 1 N: LEMOI • PAIT
ISPOOL TO FILE BTCHA3
ILIST SECO~D DEMO P~OGRAM
*TTY: "'1~: IEMm • F'T IT

ISPOOL TO PILE BTCHA4
ILIST THIRD DEMO PROGRAM
* TTY: ...I~: IEM03. F'T IT
ISPOOL TO FILE BTCHA5
IASSEIWSLE DEMOI. PA
.R PALS
*1 ~: IEMOl .B N, DEMOI • LS+-I N: rEMOI • PA
IPR I NT CR OSS REFERE NCE LIST I NG
.R CREF
*LPT: ... I N: DEMOl.LS
TO FILE BTCHA6
!LOAD ASSEMBLED B I NARY I NT 0 CORE
.R A3SLDR
*DEMOl.B N$
IRU~ FIRST DEMO PROGRAM
.STArtT 20~
~SPOOL

If! EXECUTI!)N COMPLETE!!!

INOW SAVE CORE IMA3E OF DEMOI.PA, SUT MUST
~ELOAD

FIRST, SINCE DEMOI IS SELF-MODIFYING
.R ASSLDR
*1 N: IEMOl .B N$

~~~ED~~~l ~§OOt00Ei~~RE THAT IT WAS SAVED CORRECTLY
.R U~ SYS DEMOI
II ! EXECUTION COMPLETE! !!
INOW COMPILE FORTRAN MAINLINE PROGRAM
.R FORT
*1 N: lEMa2.B N,LPT: "'IN: LEMa2. F'T$

2-20

ISPOOl TO FILE BTCHA7
/cOMPILE FORTRAN FUNCT ION· R OUT I N£
.R FORT
*1 N: IEM03 .B~, LPT: 4-1 N: IEM03. FT$
ISPOOL TO FILE BTCHAS
/TRA~SFER BOT:-I ,BI~ARY FILES TO DECTA·PE
.R PIP
* DTAI : lEM~ .B N+-D EM CE .B NIB
*DTAl: DEM03.8 ~4-DEM05.BN/B
JLOAD AND EXECUTE FORTRAN PACKAGE
.R LOADER
OEM 02 .B Nt DEM05.8 N/G

2! = 0.2000000E+01
4! = 0.2400000E+02
6! = 0.7200000E+0581: 0.4052000E+05
10! = 0.5628800E+07
12! = 0.4790016E+09
141 =0.8117829E+-11
16! = 0.2092219 EH 4
ISS = 0.6402514E+16
20! = 0.24529028-1922! :
0.1124001 &22
241 = 0.6204484E+24
26! = 0.4052,915 E+21
28'! = 0.5048885 E+50
50!'" 0.26525298-55
52! = 0.2651308E+36
54! EXCEEOS CAPACITY OF PROGRAM.
541 = 0.0000000E+00
!RENAME DEM05.BN FOR FUTURE REFERENCE
.R PIP
*FACT4-DEM05.B NIL
rEM05.8 N4-/D
IADD FOHTRA~ FUNCTION TO FORTRAN LIBRARY
.R LIBSET
*LIB8.B N/S
*FACT$
I.fINALLY, DELETE TEMPORARY FILE '"FACT"
.R PIP
*FACT4-/D
INOW CLEAN UP DISK AREA
* DEMOI .B N, DEMOI .SV, DEM~ • BN4-1 D
$MSG DEVICE NAMES DEASSIGNED
.DEASSIGN
$END

IE.NO BATCH

2-21

Loading and Saving BATCH
The paper tape binary version of OS/8 BATCH may be loaded
and saved on the OS/8 system device by typing the following commands in response to the dot generated by the OS/8 monitor:
• R ABSLDR
*pn~: (9 P> $f

.SAVE

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 * 2 TO SYSTEM DEVICE
.R MCPIP
*SVS CCL.SV<CSA0'CC~.SV
*SVS DIRECT.SV<CSA0IDIRECT.SV
*SYS FOTP.SV<CSA0;FOTP.SV
-*sys PIP.SV<CSA0IPIP.SV
*SYS LIB8.RL<CSA0ZLIB8iRL
*SYS EDIT.SVcCSA0IEOIT,SV
*SYS PAL8,SvcCSA0;PA~8.SV
*S'S CREF.SV~CSA0;CREF,SV
*S'S BITMAP.SV<CSA0C8ITMAP.SV
*SYS BOOT.SV<CSA0;BOOT,SV
*S'S CAMP,SV<CSA0ICAMP.SV
.SYS RK8FMT.SV<CSA0;RK8FMT.SV
,*SYs RKEFMT.SV<CSA0:RKEFMT.SV
SEND
.-"v'·

SJOB JOB TO LOAD SySTEM CASSETTE #3 TO SYSTEM DEVICE
.R MCPIP
*SVSIFORT.SV<CSA1 I FORT,SV
*SYSISABR.SvcCSAlISABR.SV .SYS'LOAOER.SV<CSA1'LOADER.SV
*SYSISRCCOM.SV<CSA1ISRCCOM.SV
*svsrEPIC.SV<CSA1 I EPIC.SV
*SYSIPIP10.SvcCSA1,PIP10.SV
*SVS.RESORC.SV<CSA1IRESORC.SV
*SYSJDTCOPY.SV~CSA1'OTCOPY.SV

*SYS'TDCOPV.SV<CSA1JTDCOPY.SV
*SYSITOFRMT.SV<CSA1'TDFRMT.SV
*SYSIDTFRMT.SV<CSA110TFRMT.SV
SEND

SJOB JOB TO LOAD SYSTEM .4 TO SYSTEM DEVICE
.R MCPIP
*SYS TC08SY.8N<CSA0;TC08SY.BN
*SYS T08ESY.BN<CSA0:TD8ESY.BN
*SYS LINCSY.BNcCSA0:LINCSY.BN
*SYS DF32SY,BN<CSA0'DF!2SY.8N *SYS RF08SY.8N<CSA0.RF06SY.BN
*SYS RK08SV.8N<CSA0;RK08SV.BN
~SYS RK8ESY,8N<CSA0ZRK8ESY,BN
*S,S ROMMSY,8N<CSA0:ROMMSV.8N
*S'S LINCNS,SN<CSA0:LINCNS,BN
*SVS TC08NS,BN<CS40ITC08NS.8N
*SYS RK8ENS.8N<CSA0:RK8ENS,BN
*SYS PT8E,8NctSA0IPT8E.8N
*SYS LSPT.BNCCSA01LSPT,BN

2-23

*SYSI~&45.BN<CSA0C~&45.BN

*SYSIASR33.BN<CSA0lASRj3,BN
*SYSIRK08NS.8NcCSA0'R~08NS.BN

*SYSICR8E,BN<CSA0=CR8E.BN
*SYSI8AT.BNcCSA0IBAT.BN
*SYSIT08EA.BNcCSA0IT08EA.BN
*SYSI108EB.BNcCSA0IT08EB.BN
*SY~'T08EC.BNcCSA0IT08EC.BN

*SVscT08ED.BN<CSA0ITD8EO.BN
*SYSIVR12.BNcCSA0 I VR12.BN
*SVS:RF08NS.BN<CSA0IRF08NS.BN
*SVSIDF32NS.BNcCSA0:0F32NS.BN
*SVSIK~8E.BN<CSA0ZK~8E.BN
*SVS:~PSV.BN<CSA0;LPSV.BN
*SVSITM8E.BN~CSA0ITM8E,BN

*SVS CSA.BNcCSA0ICSA,BN
*SYS CSB.BNcCSA0:CSB.BN
*SYS CSC.BNCCSA0ICSC.BN
*SYS CSO.BNcCSA0:CSO,BN
*SYS OIRECT,~~cCSA0;OIRECT.H~
*SYS BATCH.HL<CSA0IBATCH.HL
*SYS SABR.HL<CSA0:SABR.H~
*SYS PIP,HLcCSA0IP1P.HL
*SVS FOTP,HL<CSA0IFOTP.HL
*SVS ABSLDR.HLcCSA.;ABS~DR.HL
*SVS PIP10.HLcCSA0IPIP10,H~
*SYS BOOT.HLcCSA0 I BOOT.HL
*SVS LOAOER.HLcCSA0:LOADER,HL
*SYS BITMAP.HLcCSA0'BITMAP,H~
*SYS EDIT.~L<CSA0IEDIT.HL
*SYS CREF.HLcCSA0ICREF.HL
*SVS BUILO.HL<CSA0IBUILO.HL
*SYS PAL8.HLcCSA0 I PAL8.HL
*SVS OOT.HLcCSA0100T,H~
*SVS SRCCOM,HLcCSA0;SRCCOM.H~
*SVSICCL.HLcCSA0ICCL,HL
*SYSITECO.HLcCSA0ITECO,HL
*SYSJFORT.HLcCSA0IFORT,HL
*SYSILOAO.HLcCSA0;LOAO.HL
*SYSILIBRA,HLcCSA01LIBRA.HL
*SVSIEPIC.HLcCSA0 I EPIC.HL
S!ND

SJOB JOB TO LOAD SYSTEM CASSETTE • 5 TO SYSTEM OEVICE
.R MCPIP
*SYS'~IB8,RLcCSA1;LIBe,RL

*SYSIGENIOX.RLcCSA1IGENIOX.RL
*SVSII0H.RLcCSA1IIOH.RL
*SVSIFLOAT.RLcCSAllrLOAT.RL
tSYSIINTEGR,RLcCSA1;INTEGR.RL
2~4

*SYS'UTIlTY.RL~CSAlIUTlLTY.RL

*SYS,POWERS.RL<CSAl I POWfRS.Rl
*SYSIIPOWRS,RL<CSA1IIPOWRS.RL
*SYSISQRT.RL<CSAfISQRT.RL
*SYSITAIG.RLcCSAlITRIG.RL
*SVSIAT~~.RLcCSA1'ATAN.RL

*SVSIRWTAPE.RLcCSA1IAWTAPE,RL
*SYSIIOPEN.RLcCSA11IOPEN.RL
*SVSILIBSET.SYcCSA1ILI&SfT.5Y
.SYSIKL8E.PA<CSA1 I KL8E.PA
SEND

SJOB JOB TO LOAD SYSTEM CASSETTE #6 TO SYSTEM DEVICE
-.R MCPIP
*SYSICCL.PAcCSA0:CCL,PA
SEND

~SJOB

JOB TO LOAD 05/8 EXTENSION CASSETTE TO SYSTEM DEYICE
,R MCPIP
*SYS BATCH.SycCSAlIBATCH.SV
*SYS BA5IC.SvcC~AlI8ASIC,SV
.SYS BCOMP,SycCSA1IBCOMP.5V
*SYS BLOAD.SY<CSA11~LOAD.SV
*SVS BRTS.SVcCSA1'BRTS.SY
*SYS BASIC.AFcCSA1,8ASIC,AF
-SYS BASIC.SFcCSAlIBASIC.SF
*SYS BASIC.FFcCSAlIBASIC.FF
-SYS 8ASIC,UFcCSAlIBASIC.UF
-SYS EAEOYR.8NcCSAlIEAEOVR.BN
-SYS RESEQ.BAcCSAlIRESEQ.BA
*SYS TECO.SVcCSAlITECO.SY
*SYS MSBAT.SycCSA1IMSBAT,SV
*SYS GENIOX.RLcCSAlIGENIOX.RL
SEND

2-25

BITMAP
BITMAP is an OSj8 utility program which constructs a· table
(map) showing the memory locations used by given binary files.
Hardware and Software Requirements
BITMAP runs on the standard OSj8 configuration and requires
the OSj8 software package. BITMAP uses 8K of core to map
programs that use up to 16K of core, but requires 12K of core· to
map programs using more than 16K of core.
Loading Bitmap
Type
• R 81 TMAP

to call the BITMAP program from the system device!. The system responds by printing an asterisk (*) at the left margin. Type
the input line to BITMAP, indicating input devices and file name
(if input is from a mass storage device), any options desired, and
an output device and file name (if output is to a mass storage
device).
The standard input devices for BITMAP are: PTR, DTAn, DSK,
and SYS. Any other device which can contain absolute binary files
can be used as an input device if a device handler exists. TTY
should not be used, as the binary code may appear to the TTY
handler as control characters.
BITMAP accepts only absolute binary files. Relocatable and
core image files may not be used. If no extension to the input
'file name is typed, BITMAP assumes the .BN extension. If more
than one program is present in a file, only the first program is bitmapped. (This feature allows BITMAP to ignore any noise characters which might be caused by reading over the end of a paper
tape.) This feature can be overridden by the jS switch.
Type the RETURN key at the end of an input specification line
to signal th~t more input is to be given on the next line. Use the
ALT MODE key as a line terminator when there is no more input;
the Command Decoder is not recalled, and control returns to the
Keyboard Monitor. The last line typed specifies the output device
! System output is underscored throughout this manual.

= carriage return.

2-26

on which the bit map is to be produced. Any legal OS/8 output
device may be specified. If no output device is specified, output is
to the console terminal. For example:
.• R 81 TMAP
*DTA 1: FI LEI, FI LE2, FILE3, FILE4
*LPT: <PTR: $1

If an output file is specified without an extension, BiTMAP inserts
a .MP extension. The preceding lines cause FILEl, FILE2, FILE3,
and FILEA from DECtape 1 to be considered. Then a file is read
from thehighspeed paper tape reader. The $ character is printed
by the ALT MODE key which indicates a return to the Keyboard
Monitor. The resulting bit map combining all the files read is produced on the line printer.
The various options accepted by BITMAP are given below:

Table 2-4
Option

/S
/n
/T

Bitmap Options
Meaning

Reset internal bit map of BITMAP to look as· though
nothing has been input.
Consider all binary programs in the specified input
file(s) (instead of only the first program in each file,
which is normally done).
Where.n is an integer, forces mapping o~ all files specified .on this input line as if it were initially n field n.
This is used to change the style of output-Le., put te1e-type style output on non-teletype or non-teletype style
output on teletypes.

Examples of command lines to BITMAP:
• RBI TMAP
*SYS: PROG. 01
*DTA1:MAP<OTA5: PATCH $

The above commands create a bit map of the cOD)bined files
PROG.Ol on the system device and PATCH.BN on DECtape 5
. and stores the output in the file MAP .MP on DECtape 1.
2-27

• R Bl TMAP
*LPT: <A, B, C$

This example shows a bit map being produced on the line printer
for the combination of three binary files (A, B, and C) on the
device DSK: .

• R Bl TMAP

* TTY: <PTR: /5$'
.One binary tape is read from the high-speed paper tape reader, and
a bit map is produced on the terminal combining all binary files on
that paper tape.

BITMAP Output
The output of BITMAP is a series of lines, each of which is
comprised of a string of digits. Each digit represents a single core
. location, and can have the value 0, 1, 2 or 3. The value is assigned
as follows:
. 0 means that the location was not loaded into.
1 means that the location was loaded into once.
2 means that the location was loaded into twice.
3 means that the location was loaded into three or more
times .
. Appearance of a 2 or 3 may imply a programming error (e.g., two
separate routines are each trying to load values into the same location).
Each line of digits represents 100g core locations and lines are
blocked in pairs to represent pages. On teletype output, the bit
map is botdered by a set of octal coordinates which associates
one core location to each digit. For any given entry in the map
the correspqnding core location can be determined by adding the
horizontal and vertical coordinates that lie directly to the left and
above the entry.

2-28

The following is an example of teletype style output:

BITMAP V4

~tELO"

~~0e0~0e11111111~222~222333333334444444455555555&&&&&&&&77777777
~12345&70123Q~&7012345&7012345&7012345&7012345&7012345&7012345&7
~00~~

22?~?222211111tI10~000~0000e000000000000000000000000000000000000

001c:'10
00200 2222222222222222222~22~~2222222~22222222222222222222222222222222
00300 2222222222222222221111111111111111111111111111111111111111122221
004~0

2222222222~22c2?222222222222222222222222222222222222222222222222

1110500 22222222? 22,222 22222 2? 2 22n 22 2 2 22 22 22 22 22 22 222 2222 222 2 2 22 22222222
00600 '1111111111111111111111111111111111111111111111111111111111111111
00700 1111111111111111111111111111111111111111111111111110111111111111
0111!00
01100
012e0
~13e(ll

014~0
01S0~

01611'0
01700
020t<H'I
021 Nil

The following is an example of non-teletype style out:put:
BITMAP V4

FIELD ~

0001'>0 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<OEV: BITMAP

The listing file shown in parentheses is optional.
Use ABSLDR to make BITMAP.SV from BITMAP.BN on a
DECtape file:
• R A8SLOR
*OEV: 81 TMAP= 1200019 $
• SAVE OEV BI TMAP

...

2-30

To load and save the binary paper tape (DEC-S8-0SYSA-C-PB 17):
• R ABSLOR
*PTR: 12000/9 $t
• SAVE: OE:V 81 TMAP

and store in the file MAP.MP on DECtape 1.

2-31

BOOT
BOOT is an OS/8 program used to bootstrap from one PDP-8
system to another and to bootstrap from one device to another by
typing commands on the keyboard. BOOT can run conveniently
from OS/8 and COS 300 and can also run from any other PDP-8
monitor system (e.g., CAPS-8).
To run BOOT from COS 300, see the COS 300 System Reference Manual, Chapter 9 (DEC-08-OCOSA-E-D).
To run BOOT from OS/8, type:
.RBOOT/dv
or
.RUN DEV:BOOT/dv
where dv is a 2-character mnemonic which must immediately follow a slash. This mnemonic represents the device type and the
system to be bootstrapped. Do not attempt to bootstrap onto a
device which is not ready or does not exist.
To run BOOT from an OS/8 device with CCL enabled, type:
.BOOTjdv
If the above form of call is used, BOOT .SV must be present on

the system device.
If the following is typed:
• R BOOT

the system responds with a slash and the user can respond with
the dv mnemonic.
If an illegal mnemonic is typed, the system prints:
NO
I

to allow a new mnemonic to be entered. Type RUB OUT to erase
the line, then enter the command correctly.
If the device mnemonic is followed by a period, the program
loads the correct bootstrap into core and then halts. Press CONT
to branch to the bootstrap.
Table 2-5 lists the legal mnemonics for BOOT.
2-32

Table 2-5
Mnemonic

Boot Mnemonics

Device

System or Comments

TA8E cassette

CAPS-8

Any disk (RF08,
DF32, RK8E, RK8)

OS/8, COS 300

LINCtape

DIAL-V2, DIAL-MS

RF08 or DF32

Disk Monitor

Any tape (TC08,
TD8E, LINCtape)

OS/8, COS 300

LINCtape

OS/8, COS 300

PT8E paper tape

Loads BIN/loader into field 0

RK8E disk

OS/8, COS 300

RF08, DF32 disks

OS/8, COS 300

RK8 disk

OS/8, COS 300

TC08 DECtape

OS/8, COS 300, Disk Monitor,
DEC library system, and others

TD8E DECtape

OS/8, COS 300

TC08 DECtape unit 4

Typeset bootstrap

Types BOOT's version number

Zeroes core (field 0)

More than one device of a particular type (e.g., disk, DECtape)
may be present on the OS/8 system. When the DK or DT
mnemonic is used, BOOT assumes the following priorities:
Disk

1. RF08 or DF32
2.· RK8E
3. RK8

DECtape
1. TC08
2. TD8E
3. LINCtape

2-33

BUILD
BUILD is the system generation program for OS/8 which allows
the user to:
1. Create an OS/8 monitor system from cassettes or paper tapes.
2. Maintain and update device handlers in an existing OS/8
system.
3. Add device handlers supplied by Digital to a new or existing
system.
4. Add user-written device handlers to a new or existing system.
With BUILD, simple keyboard commands are used to manipulate
the device handlers which make up the OS/8 peripheral configuration. BUILD allows the user to quickly and easily insert devices
which are not standard on the system.

os /8 Device Handlers
Each OS/8 configuration has certain device handlers that are
available within BUILD when the system is supplied by Digital.
The handlers supplied with BUILD depend on the distribution
media of OS/8 software, i.e., DECtape (LINCtape), cassettes, or
paper tape. The device handlers supplied with BUILD are detailed
for specific distribution media in Tables 2-6, 2-7, and 2-8. (See
Appendix H for more detailed information concerning OS/8 device
handlers.)
Device handlers that are included with BUILD must be made
active before they can be used by the OS/8 system. The BUILD
commands INSERT, REPLACE, and SYSTEM are used to make
device handlers active. A maximum of 15 handlers can be made
active, including the system device (SYS) and the default mass
storage device (DSK).
Inactive devices, even though they are included with the original
BUILD, cannot be used on the system until they are made active.
For example, several system handlers may be supplied with BUILD,
but only one may be marked active.
All other device handlers supported on OS/8 are supplied with
every configuration but those not inc1uded in the original BUILD
must be loaded into BUILD before they can be used. This is accomplished with the BUILD command LOAD. See Table 2-9 for
a .complete list of the device handlers available with OS/8.

2-34

Handlers in BUILD are identified by two names, the first of
which is the group name. This is the name assigned to an entire
group of handlers all of the -same type. For example, the nonsystem
TC08 DECtape handler as supplied with a DECtape system, which'
has four separate handlers internally, has the group name TC .
. In addition to the group name, a device also has a permanent
device name. This is the name by which OS/8 identifies the physical device. For example, TC08 DECtape unit 3 has the group
name TC and the permanent name DTA3.
DECTAPE (LINCTAPE) SYSTEMS
When OS/8 'software is supplied on DECtape or LINCtape, the
. device handlers shown in Table 2-6 are included in BUILD. The
handlers in Table 2-6 can be made active with the INSERT, SYSTEM, or REPLACE commands.
Table 2-6. Standard DECtape System Device Handlers
Group
Name

Permanent
Name(s)

TC08 DECtape system handler
TC08
TC08 non system DECtape
TC
drives 0-3
12K TD8E DECtape system
TD8E
handler and drives and 1
8K ROM TD8E DECtape system ROM
handler and drives and 1
TD8E nonsystem DECtape
TD8A
-drives and 1
TD8E nonsystem DECtape
. TP8B
drives 2 and 3
RK8E disk system handler
RK8E
RK8E disk nonsystem handler
RK05

SYS
DTAO-DTA3

Handler

°
°

RK8 disk system handler
RK8 disk non system handler
. Ll"NCtape system handler
LINCtape non system handler
RF08 disk system handler
Console terminal (2-page handler)
High-speed II 0 simulated on
ASR-33 Teletype
High-speed reader / pun~h
LP08, LS8E, LV8E line printers TA8E cassette drives and 1
PDP-l2 scope

SYS, DTAO, DTA1
SYS, DTAO, DTAl
DTAO, DTAl
DTA2,DTA3

RK8
RKOl
LINC
LNC
RF08
KL8E.
KS33

SYS, RKBO
RKAO, RKA1,
RKBO, RKBl
SYS, RKAl
RKAO, RKAl
SYS
LTAO-LTA3
SYS
TTY
PTR, PTP

PT8E
LPSV
TA8A
VRl2

PTR,PTP
LPT
CSAO, CSAl
TV

2-35

Other device handlers available with OS/8 but not included in
BUILD are listed in Table 2-9. The handlers supplied with a
DECtape or LINCtape system are on the System Tape #2 (DECS8-0SYSB-A-UC2). To include extra handlers in BUIl;D, mount
this tape and use the LOAD command.
CASSETTE SYSTEMS
When OS/8 software is supplied on cassettes, the device handlers
shown in Table 2-7 are included in BUILD. These handlers can be
made active with the INSERT, REPLACE, or SYSTEM com~
mands.

Table 2-7

Standard Cassette System Device Handlers
Group

Handler
RK8E disk system handler
RK8E disk system handler
RF08 disk system handler
DF32 disk system handler
Console terminal (2-page handler)
High-speed II 0 simulated
on ASR-33 Teletype
High-speed reader/punch
TA8E cassette drives 0 and 1
LP08, LS8E1 LV8E line printers

Name

Permanent
Name(s)

RK8E
RK8
RF08
DF32
KL8E
KS33

SYS, RKBO
SYS, RKAl
SYS
SYS
TTY
PTR, PTP

PT8E
TA8A
LPSV

PTR, PTP
CSAO, CSAI
LPT

Other handlers supplied with OS/8 but not included in BUILD
are listed in Table 2-9. These handlers are present on the system
cassette DEC-S8-0SYSB-A-TC4. To include extra handlers in
BUILD, build an OS/8 system, use MCPIP to move specific device
handlers onto the system device, then use the BUILD command
LOAD.
PAPER TAPE SYSTEMS
When OS/8 software is supplied on paper tape, the device handlers shown in Table 2-8 are included in BUILD. These handlers
can be made active with the INSERT, REPLACE, or SYSTEM
commands.
2-36

Table 2-8

StandaFd Paper Tape System °Device Handlers
Group
Name

Handler
RK8E disk system handler
RK8 disk system handler
RF08 disk system handler
'DF32 disk system handler
Console terminal (2-page handler)
High-speed II 0 simulated
on ASR-33 Teletype
High-speed reader/punch
TA8E cassette drives 0 and 1
LP08, LS8E, LV8E line printers

Permanent
. Name(s)

RK8E
RK8
RF08
DF32
KL8E
KS33

SYS, RKBO
SYS, RKAI
SYS
SYS
TIY
PTR, PTP

PT8E
TA8A
LPSV

PTR,PTP
CSAO,CSAI
LPT

Other handlers supplied with OS/8 but not includt!d in BUILD
are provided on two binary paper tapes. DEC-S8-0SYSB-A-PB2
contains the file-structured handlers. DEC-S8-0SYSB-A-PB3 contains character:oriented handlers. These tapes contain handlers
which can be loaded into core using the BUILD command LOAD.
The BUILD device handler tapes are composed of separate segments, with a short length of leader/trailer code between them.
(All of these handlers are in the special format described in BUILD
Device Handler Format in this section.) Table 2-9 contains a list
of the handlers that are included on the tapes. The handlers are
listed in the order that they appear on the tapes. The TC08 handler
is the first segment on handler tape # 1 and the KL8E terminal
handler is the first segment on handler tape #2. It is suggested that
either the segments be labeled or separated for easier use.
To utilize a binary handler file, place the desired segment into
the paper tape reader. Use the BUILD command LOAD to load
that segment as follows:
$LOAD PTR[:]
t

Type a colon (:) after the device name if
BUILD was loaded from an OS/8 system
device. The t allows time to place the tape
in the reader. Type any keyboard character to load the' tape. When the $ reappears, the handler has been loaded into
BUILD's table. Type the BUILD comm~d PRINT to verify that the handler
has been loaded.
2-37

Table 2-9

OS/8 Device Handlers
File Name
onDECta~e

Handler

Group
Name

Permanent
Name(s)

LINCtapeor
Cassette

TCOS DECtape system handler TCOS SYS,DTAO
TCOSSY.BN
12K TDSE DECtape system
TDSE SYS, DTAO, DTAI TDSESY.BN
handler
SK ROM roSE DECtape
ROM SYS, DTAO, DTAI ROMMSY.BN
system handler
LINCtape system handler
LINC SYS,LTAO
LINCSY.BN
RKSE disk system handler
RKSE SYS, RKAO, RKBO RKSESY .BN
SYS, RKAO,RKAI RKOSSY .BN
RKS disk system handler
RKS
RFOS disk system handler
RFOS SYS RFOSSY.BN
DF32 disk system handler
DF32SY.EN
DF32 SYS
TDSE DECtape drives 0 and 1 TDSA DTAO,DTAI
TDSEA.BN
TDSE DECtape drives 2 and 3 TDSB DTA2,DTA3
TDSEB .BN
TDSE DECtape drives 4 and 5 TDSC DTA4,DTA5
TDSEC.BN
TDSE DECtape drives 6 and 7 TDSD DTA6,DTA7
TDSED.BN
TCOS DECtape drives 0-7
DTAO-DTA7
TCOSNS.BN
TC
LINCtape drives 0-7
LINCNS.BN
LNC LTAO-LTA7
RKSE disk non system handler RK05 RKAO-3, RKBO-3 RKSENS.BN
RKS disk nonsystem handler
RKOSNS.BN
RKOI RKAO-RKA3
RFOS disk nonsystem handler RF
RF,NVLL
RF08NS .BN
DF32 disk nonsystem handler DF
DF
DF32NS.BN
Console terminal (2-page
handler)
Console terminal (l-page
handler)
High-speed I/O simulated on '
ASR-33 Teletype
High-speed reader I punch
LPOS, LSSE, L VSE line
printers
Anelex 645 line printer
Card reader
BATCH handler
PDP-12 scope
TV 10 magnetic tape drives 0-7
TASE cassette drives 0 and 1
TA8E cassette drives 2 and 3
T ASE cassette drives 4 and 5
T ASE cassette drives 6 and 7

KLSE TTY

KLSE.BN

AS33

TTY

ASR33.BN

KS33

PTR, PTP

LSPT .BN

PT8E PTR,PTP
LPSV LPT

PT8E.BN
LPSV.BN

L645 LPT
CRSE CDR
BAT BAT
VR12 TV
TMSE MTAO-MTA7
TA8A CSAO, CSAI
TA8B CSA2,CSA3
TA8C CSA4, CSA5
TA8D CSA6, CSA7

L645.BN
CRSE.BN
BAT .BN
VR12.BN
TMSE .BN
CSA.BN
CSB.BN
CSC.BN
CSD .BN

Calling and Using BUILD
BUILD is distributed as both a binary paper tape or cassette and
as a core image file (BUILD.SV) on the system DECtape or LINCtape. The binary BUILD file should be loaded and saved on the
2-38

system device when the initial system is built (see Getting On Line
,with OS/8 in Chapter 1). To use the BUILD.SV fil~ on the system
device, type the following command in response to the dot printed
by the OS/8 Keyboard Monitor:
RUN SY S SUI LD

NOTE
It is important that the user specify the RUN
or RU command, rather than the R command, when loading BUILD into core. This
will allow the use of the SAVE command
without specifying SAVE arguments.
BUILD responds by printing a $, signaling that it is ready to accept
commands.
BUILD uses a keyboard monitor similar to that contained in
the OS/8 system. Text is input from the terminal and interpreted
by BUILD. Table 2-10 lists the special charac!ers that are available
for editing.
Table 2-10

BUILD Editing Cbaract.ers
Function

Character

Terminate command; begin command execution. No carriage returnlline feed is generated.
CARRIAGE RETURN Terminate command; begin command execution. Also generate ca'rriage r,eturnl line
feed combination .
. Terminate command; return immediately to
CTRL/C
the OS/8 Keyboard Monitor.
Terminate printing; return control to BUILD.
CTRL/O
Ignore line; the line may be typed again.
CTRL/U
Examine contents of the command line.
LINE FEED key
Delete the last typed character from the
RUBOUT key
command.
ALT MODE key

The standard characters pexmitted in a BUILD command .line
are:
A-Z, 0-9, SPACE, PERIOD, =, COMMA, COLON, HYPHEN,
2-39

Typing any other character causes the error message:
SYNTAX ERROR

BUILD Commands
The commands available in BUILD are:
ALTER
BOOT
BUILD
CORE
CTL
DCB
DELETE
DSK
EXAMINE
INSERT
LOAD
NAME
PRINT
QLIST
REPLACE
SYSTEM
UNLOAD
VERSION
The general format of the command string is:
$command args
where command represents a legal command from the list and
args represents a file name, device, group name, or other argument associated with the command. The command can be typed. in
full or abbreviated to the first two characters. For example:
$PRINT
$PR
are the same. If the user 3;ttempts to issue an illegal command.
BUILD replies by printing the illegal command preceded by a ?
. Thus the illegal command ERASE would appear:
2-40

$ERASE
?ERASE
$

THE HYPHEN CONSTRUCTION
Certain BUILD commands (DELETE, INSERT, REPLACE)
allow the use of the hyphen construction to specify more than one
permanent name. These permanent names must be four characters
long and must differ only in the last character. Permanent names
which meet this restriction can be inserted with the hyphen construction so long as the last characters form a'sequence of consecutive ASCII characters.
For example, if the user wishes to delete DECtape handlers
DTAO, DTAl, DTA2, and.DTA3, he can type:

or he can use the hyphen construction and type:
$DEL ETE DTA0- 3

PRINT
Syntax: .$PRINT or $PR
.
Function: Prints the detailed list of the BUILD devices tables.
The following example shows five handlers.
RF08:
Ri<8 E:
KL8E:
PT8E:
LPSV:

SYS
*SY S
*TTY
PTR
LPT

*RKB0
*PTP

.Group names are printed first in each line followed by a colon.
Following the group name arethe list of permanent names available
with each group. If one of the permanent names in a group is SYS,
then this handler can be a system handler. An OS /8 system must
have just one system handler. Some system handlers have other
handlers coresident with them.
Any handler that is active is marked with an asterisk to the
-left of its permanent name (RKBO, TTY, PTP in the printout), and
the devices will be included in the new OS/8 system. (i.e., these
handlers were inserted with the INSERT, SYS, or REPLACE
2-41

commands. Other commands are available for removing, loading,
and deactivating handlers.) The preceding printout indicates that
RK8E is the system device. The handler RK8E:RKBO is also
marked as being active.
After printing the list of available handlers, the PRINT command might also print some additional information. If, for example,
the user specified RK8E:RKBO with the DSK command, the following is printed:
DSK = RK8 E: RK Bel

If the user specified that core is to be restricted to 12K with the
CORE command, the message:
CORE= 2

is printed, indicating that field 2 is to be the. highest core field
available to the OS/8 system.
QLIST
Syntax: $QLIST or $QL
Function: List the active permanent names on the system. No *
is printed and the system device is the only group name printed.
For example:
S0LI ST
PTR DTA3 RKel8:SYS LPT DTA4

LOAD
Syntax: $LOAD activename or $LOAD dev:filename
Function: LOAD is used to load a new device handler into
BUILD. This handler can be one supplied by Digital or one written by the user. See the OS/8 Software Support Manual (DECS8-0SSMB-A-D) for instructions on writing device handlers. This
handler is input into BUILD as a binary file or image.
If BUILD is being run stand-alone, e.g., to create an initial OS/8
system, the LOAD command has the form:
$LOAD activename
2-42

where activename is the permanent name of an input device han- _
dler that has been made active with the INSERT, REPLACE, or
SYSTEM command. It must be a handler for a non-file structured
device. For example, to load a new handler from a binary paper
tape with the PTR handl(!r already in BUILD, type:
$LOAD PTR

IF BUILD is being run under control of OS/8, the LOAD command has the form:
$LOAD dev:filename
where dev is an input device handler that exists in the current 08/8
system. (These are not the same as the handlers which are marked
active by BUILD.) If no dev: is specified, DSK: is assumed.
If dey: is non-file structured (i.e., paper tape), the filename may
be omitted. The filename has the form:
name. extension
Filename is the binary file of the new handler to be loaded.. The
default extension is .BN. If no extension is used, the dot (.)may
be omitted.
Example:
$LOAD DTA3:HANDLR.03

A file named HANDLR, with an
extension of 03 is loaded from
DTA3.

Several files to be loaded may be specified on one line, separated by commas. A device must be specified for each file orDSK
-will be assumed. If multiple files are specified, each file must cOiltain a separate handler to be loaded. For example:
$LOAD DTA3:FILEl,DTA5:FILE2

Once the LOAD command-has been successfully issued, the new
device handlers are available for further manipulation. The new
handlers will appear in the PRINT output, but will not be marked
as active.
2-43

INSERT
Syntax: $INSERT gname, pname
Function: After a LOAD command has made a handler or
group of handlers available for insertion in the OS/8 system, the
INSERT command is used to make particular entry points active.
The INSERT command uses two arguments; gname and pname.
Gname is the group name of the handler, for example, the gname
for TC08 DECtape is TC. Pname is the permanent name by which
the device is currently known to BUILD. See Table 2-9 for a complete list of permanent device names. TC08 DECtape thus has the
group name TC and the permanent names DTAO-DTA7.
Examples:
$1 N KL8 E" TTY
$IN TC08"SYS

If no permanent name is specified (and no :), the first name in

the device group is assumed. For example:
SINSERT TC

would assign DTAO as the permanent name.
Several handlers in the same group can be inserted in the same
command by separating the permanent names with commas. For
example:

If several permanent names (each four characters long) differ

only in the last character, they can be simultaneously inserted with
the hyphen construction so long as the last characters form a
sequence of consecutive ASCII characters.
Example:
$INSERT TC"DTA2-5

is the same as

2-44

and
$INSERT RK01 .. RKA0-2

is the same as
$INSERT RK0) .. RKA0 .. RKAl .. RKA2

If the permanent name specified is not part of the group name
specified or if the group name does not exist, the following message
is printed:

name NOT FOUND
If disk is the device being inserted, the group name can be followed by a construction of the form:

pname=n
Where n is a digit in the range 1 to 7 and represents the number
of platters available. This option is used for the ~08 and DF32
disks. For example:
$IN RF .. RF=2

If no su~h option is specified, =1 is assumed. If n is too large for
the device specified, the following message is printed:
?PLAT

DELETE
. Syntax: $DELETE aname
Function:· DELETE taKes a device which is currently marked
as active and makes it inactive. (Devices which are active are
marked with an * in the PRINT command output and are printed
by ·the QLIST command.)
The argument for DELETE is the permanent name of the device.
The current permanent name can be obtained from the PRINT or
QLIST output. The major function ·of DELETE is make device
slots available to BUILD.
2-45

For example, assume that the QLIST command output is:
DTA0 DTA 1 RK8 E: SY S RKB0 TTY L PT CSA0 CSA I

CSA2 CSA3

If the following command is issued to BUILD:

CSAO, CSAl, CSA2, and CSA3 will no longer be permanent
devices and the slots used by the T A8A and T A8B device groups
will be made available to BUILD. The QLIST output after the
above command will be:
DTA0 DTA 1 RK8 E: SY S RKB0 TTY LPT

Note that, as previously explained, the hyphen construction can
'be used in DELETE to remove a sequence of devices. Thus the
command to make the cassette handlers inactive could also be
typed as follows:
$DEL ETE CSA0- 3

REPLACE
Syntax: $REPLACE pname=gname, pname2
Function: REPLACE combines the functions of DELETE and
INSERT to provide a means of deleting one device and activating
another in a single step. The arguments for REPLACE are:
The permanent name of the device to be de:leted. (Same as ar:e argument of the DELETE
command.)
gname, pname2 The group name and permanent name of the
particular device to be inserted into the system
(see INSERT for more details).
pname

Example: Assume the PRINT output is:
PT8 E:
CR8E:
RK05:

* PTP
* CDR

RKA0

* PTR
RKB0

RKAI

2-46

RKBI

REPLACE can be used to delete the card reader (CDR) and insert
the RK05 group handler for RKAO:
$REPLACE CDR= RK 05., RKA0

The output of PRINT after this REPLACE is:
PTB E:
CRBE:
RK 0 5:

* PTP * PTR
CD~
* RK A 0 RK B 0

RK A 1

RK B 1

The hyphen construction can be used with REPLACE to delete
and insert more than one device handler. For example, assume
that LINCtape handlers LTAO, LTAl, LTA2, and LTA5 are to
be replaced with DECtape handlers DTAO; DTAl, DTA2, and
DTA5. This replacement could be accomplished with the command:

UNLOAD·
Syntax: $UNLOAD gname, or $UNLOAD gname, pname
Function: UNLOAD is used to physically delete a handler group
(gname) or a permanent name (pname) from. the BUILD system.
(This differs from DELETE, which does not physically eliminate
a device.) UNLOAD is primarily used when the NO ROOM error
occurs during a LOAD command.
For example, assume that the entire gr,oup of LINCtape han- '
dlers is to be removed. The command is typed as:
$UNLDAD LNC

This command unloads the LINCtape handler LNC and/all permanent names (LTAO, LTAi, LTA2, LTA3, etc.) associated with
it.

To remove a particular permanent name· from BUILD, e.g.,
DTA3, type:
$UNL DAD TC., DTA3

2-4-=/

This command does not unload the handler, just the entry point
name.
To remove several permanent names, but not the entire group,
the UNLOAD command is used with commas separating the permanent names. For example:

The hyphen construction cannot be used with the UNLOAD
command.
NAME
Syntax: $NAME pname=pname2
Function: The NAME command allows the user to alter the
device name which will be used by OS/8. 'The first argument,
pname, must be the current name of a device marked active in
the PRINT output. Pname2 is the name the user wishes to call
this device. Only 4-character device names may be used in the
NAME command. If longer names are entered, all characters beyond the first four are ignored. After the NAME command is used,
pname2 is .the current permanent name; pname is unknown to
BUILD.
Example: Assume that the PRINT output is:
TC
RKB E:

*DTA0

* SV S

*DTAI

* RK 80

DTA2

DTA3

To change the paper tape reader so that it is recognized by the
permanent name READ, the following command is used:
$NAME . PTR= READ

The output from PRINT would then be:
TC
RKB E:
KKBE:

*DTA0

* SV S

*TTV
PTBE: *PTP

*DTAI

* RK 80

DTA2

DTA3

*READ

2-48

If the permanent name specified as pname is not a currently
active device, thy message:

pname NOT FOUND
is printed. If this message appears, check the PRINT output to,
determine the correct permanent name.
ALTER Syntax: $ALTER gname, loc'=newvalue
Function: The ALTER command allows the user· to change
locations in device handlers. The arguments are:
gname
loc

newvalue

Group name of the handler.
Relative octal location to be altered. If the handler is a I-page handler, loc must be an octal
number in the range 0-0177. If it is a 2-page
handler, loc must be an octal number in the
range 0-0377.
An octal number specifying the new contents of
the location specified by loco If no '=newvalue
is entered, BUILD prints" the old value of loc
followed by a slash. Newvalue can then Be entered or a carriage return can be typed to retain
the old value .

•
EXAMINE
Syntax: $EXl\MINE gname, loc
Function: EXAMINE allows the user to examine, but not
modify, a location within a device handler. See the ALTER command.

DSK
Syntax: $DSK=gname, pname or $DSK=aname
Function: The DSK command is us~d to specify which device
is to be designated as DSK, the default storage device for OS/8. If
the first form of the command is used, i.e.,
$DSK=gname,pname
the gname is the group name of the device and pname is the permanent name. For example:
$DSK=TC08: DTA0

2-49

assigns DTAO as the device called DSK.
When the DSK command is issued, the permanent name need
not have been entered. However, the permanent name· must be
entered, via an INSERT, REPLACE, or SYSTEM command before the BOOT command is issued.
If the second form of the command is used, i.e.,
$DSK=aname
aname must be a permanent name marked as active by BUILD.
For example, the following command specifies the already active
device RKAO as the default device DSK:

$DSK=RKAii

If no DSK command is entered, or if the command is issued

without an argument, i.e.,

$DSK=

or
$DSK

BUILD specifies SYS as DSK when a BOOT command is issued:
CORE
Syntax: SCORE n
Function: The CORE command is used to specify the highest
core field available to the 05/8 system being built. The n is
an octal number in the range 0 to 7. If n is 0 or omitted, or if the
CORE command is not used, the system built will use all of the
available core. If n specifies more core than is physically available,
the following message is printed:
?CORE

2-50

.....

The following table indicates the. value of n for the available
core SIZes:
n
core

o
1
2
3
4

5
6
7-

all available core
8K
12K
16K
20K
24K
28K
32K

For example, a system which is to use only 24K of a 32K system
would have the following CORE command:
$CORE 5

DCB
Syntax: $DCB aname or $DCBaname=newvalue .
Function: The DCB .command allows examination or modification of the DCB word associated with a permanent name. (See the
section on BUILD Device Handler Formats for information on
DCB words.
The DeB word is the first word after the permanent name in a
description (from the handler header information words). Aname
must be the permanent name of a device currently marked as active
in the PRINT output.
Example:
$DCB DTA4= 6160

changes the DCB of DTA4 so that this handler becomes a readonly device. This command could also be typed _~:
$DCB DTA4
4160/6160

CTL
Syntax: $CTL aname=loc
Function: The CTL command allows modification of the control
2-51

word which is the word after the DCB word in the handler head~r
block. For example:
$CTL L TA3=24

changes the entry point of the LTA3 handler to be relative location 24.
VERSION
Syntax: $VERSION or $VE
Function: The VERSION command prints the version number
of BUILD on the terminal.
SYSTEM
Syntax: $SYSTEM sname=n
Function: The SYSTEM command specifies devices which are
system handlers or coresident with system handlers. The number
n reflects the number of platters included in the system device
(valid only for multiple platter RF08 and DF32 disks). The available system handlers and their ,ssociated values for n are listed
in Table 1-6). The argument sname must be one of the legal device
system names, If it is not, BUILD prints:
?SYS

thus requesting a new system specification.
Action is not taken on the SYSTEM command until'the BOOTSTRAP command is given, so the user may respecify a device
with SYS. The system device used is the last one issued prior to
the BOOT command. Specifying a new system device is not always
necessary. For example, if the user wishes to insert new peripheral
handlers, then this command is not needed. If it is not issued, the
OS/8 system which is resident is not affected beyond altering the
device tables.
The SYSTEM ~ommand is included only for compatibility with
older versions of BUILD. The system device can be specified with
the INSERT command. For example, the command:
$SY S RF08= 2

2-52

is the same as the command:
!lINSERT

RF08~ SY 5=2

If the device specified in the SYS command is not the current
system device, the user will have an opportunity to have a zero
directory placed on his new system device. If the system device
is the same as the current system device, no new directory will be
written.

BUILD
Syntax: $BUILD or $BU
Function: The BUILD command is used only when building an
initial OS/8 system from cassettes or paper tape. When the BUILD
command is typed, BUILD prints:
LOAD 05/8:

to which the user must respond with the device that contains the
new OS/8 monitor, e.g.,
LOAD 05/8:

CSA0

BUILD then loads and writes the various parts of OS/8 onto the
system device. After writing OS/8, BUILD prints:,
LOAD CD:

"to which the user responds with the appropriate device, or types
carriage return to specify that the device is the same as that specified
in the LOAD OS/8: message. BUILD loads the Command Decoder
and writes it onto the system device.
The BUILD command must not be used at any time other than
while building an initial OS/8 system; When this command is typed, ..
OS/8 assumes that the user is building a new OS/8 system and
automatically zeroes the system device directory. See Getting On
Line With OS/8 in Chapter 1 for instructions on building an initial
system.
2-53

BOOTSTRAP
Syntax: $BOOTSTRAP or $BO
Functio~: BOOTSTRAP is the command which finally implements all the changes that have been made using BUILD. BOOT
rewrites all relevant Monitor tables and device handlers to reflect
the updated system status. The devices which BUILD had marked
active now become device handlers in the system.
When a BOOTSTRAP command is typed, the system device
must have been explicitly specified with either the SYSTEM or
INSERT command. If no SYS is specified, the message:
SY S NOT I'OUN D

is printed.
If the system device specified is different from the current system
device, BUILD copies the system from the current system device to
the new system device. After the copy is complete, BUILD asks:
WRI TE ZERO DI REeT ?

to determine whether a new (zero) directory is to be written on the
new system device. If the reply is YES, a zero directory will be
placed on the device. Any other reply causes the old directory to be
retained.
NOTE
Care should be exercised if the old directory
is to be retained. The directory must be that
of an OS/8 system device.

After this question has been answered, BUILD updates the system
and prints:
SY S SUI L T

•

Control returns to the Keyboard Monitor. When the BOOTSTRAP command has performed its functions and the Keyboard
Monitor is once again active, it is a good idea to save the copy of
BUILD just used. In this way, an image of the current system
status is preserved, and the saved copy of BUILD can be used
2-54

again. When it is used again, the devices which were initially
marked active are still marked active. To save BUILD, type:
• SAVE SY S SUI J-D

in response to the dot printed by the Keyboard'Monitor. This assumes that the user originally loaded .BUILD into core with a RU
or RUN command.
BUILD Error Messages
The following is a list of error messages which may appear when
using BUILD. These messages are usually indicative of a syntax or
user error.
Table 2-11 BUILD Error Messages
Message
?BADARG
?BAD INPUT
?BADLOAD
?BAD ORIGIN
?CORE

?DSK·
?HANDLERS
I/O ERR
?NAME
NO ROOM

Explanation
No devi~e name was included in the LOAD
command.
An error was detected in the binary file; it is
not a proper input for the LOAD command.
An attempt was made to load a binary handler
that is not in the correct format.·
The origin in a binary file is not in the range
200-577.
A CORE command specified more memory
than is physically available, or the BOOT command was· issued on an 8K system with a 2page system handler active. Two page system
handlers require at least 12K of core to be
present o~ the OS/~. system.
The device specified in a DSK command is not
a file-structured device.
More than 15 handlers, including SYS and
DSK, were active when a BOOT command was
issued.
An error occurred while reading from an input
device during a LOAD command.
A device or file name was not designated in a
command that requires one to be present.
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.

2-55

TableZ-ll

BUILD Error Messages (Cont.)

Message
name NOT FOUND
?PLAT
?SYNTAX
?SYS

SYS ERR

SYS NOT FOUND

Explanation
The device or file name designated in the command was not found.
The =n in a SYS command is too large for the
device specified, e.g., RF08=5.
An illegal character was typed in a BUILD
command line. The line must be retyped.
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 or
more system handlers were active.
c. A BOOT command was issued when an active handler which must be coresident with a
SYS handler did not have the system handler
active.
An II 0 error occurred with 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.
No active handler with the name SYS was present when a BOOTSTRAP .command was issued.

BUILD Device Handler Fonnat
The BUILD command LOAD is used to load device handlers
not provided by BUILD it;1to core where they can be inserted into
the OSj8 system. The format of the input to LOAD is p. binary file
containing the handler, as well as a header block which contains
information pertaining to the devices included in that file. The user
should code the handler in PAL8 machine language according to
the following format.
The structure of the source for a BUILD device handler is:

*0
HEADER BLOCK
*200
BODY OF DEVICE
HANDLER
2-56

The origins at 0 and 200 are vital to BUILD. The *0 is an important part of tpe, header block and, if it is omitted, no load is
done. The *200 is also necessary for the load. If the handler contains an origin outside the range 200-577, an error message is
generated and the load is aborted.

HEADER BLOCK
The header block contains the following information:
Word 1:

-X, where X is the number of separate handlers
contained in this file. Thus a handler for TC08
has the first word equal to -10 ( octal).

Words 2-9:

Descriptor block for the first handler in the
group. -

Words 10-17:

Description block for second handler in the
group.

Descriptor block for second handler in the
group. If the handler is a system handler, this
is followed by the length of the bootstrap and
the bootstrap itselt
Thus, each handler in the group' must have an 8-word block
describing its characteristics. _If more than 12 handlers are in a
-group, an error is generated during the LOAD.
DESCRIPTOR BLOCK
Each 8-word descriptor block contains the following information.
Words 1,2:

. Device type name.. This name is the group
name,. or type, of all the handlers in this group
and is usually designated by the DEVICE
pseud·o-op.
Example: DEVICE RK8
2-57

Words 3,4:

OS/8 device name. This is the name (permanent name) by which the particular device will
be recognized in the OS/8 system to be configured. It can be altered by the NAME command.
Example: DEVICE RKAO

Word 5:

Device Control Block. This word reflects the
type of device, in accordance with Table 2-12.
Bits 9-11 specify the maximum number of platters on the device (0= 1).
Example: 4050

Word 6:

EntrY'point word. This word must contain the
entry point offset in bits 5-11 (see ENTRY
POINT OFFSET). Bit 0 should be a 1 if the
handler is a 2-page handler. Bit 1 should be a
1 if the entry point is SYS. Bit 2 should be a
1 if the entry point is coresident with SYS.
Example: 0020

Word 7:

MustbeO.

Word 8:

Must be 0, except for a system handler which
uses it to specify the block length of the device.

As an example, consider the handler for the nonsystem RK05
handlers. This file contains four separate handlers; the source code
would appear as follows:

*0
-4

/4 DEVICES

DEVICE RK05; DEVICE RKAO; 4050; 0020; ZBLOCK 2
DEVICE RK05; DEVICE RKBO; 4050; 0021; ZBLOCK 2
DEVICE RK05; DEVICE RKA1; 4050; 0022; ZBLOCK 2
DEVICE RK05; DEVICE RKBl; 4050; 0023; ZBLOCK 2
*200
(HANDLER BODY)
2-58

The device type of the group is RK05 (Words 1-2). The permanent device names are RKAO, RKBO, RKA1, RKBl. Since each
device is RK05, the device control block (DeB) word for each is
identical.
The entry point word indicates where the entry point for that
particular device occurs relative to. the top of the page. Thus, in the
above example, RKAO enters at the 20th location from the top of
the page, RKBO at the 21st, etc.
~t is vital that this information be accurate. If errors are made in
this data, unpredictable results occur when the system is generated.
BREAKDOWN OF DeB WORD
The DeB word for a device provides specific information which
is used in the OSj8 Monitor. Its structure is detailed in Table 2-12.
Table 2-12

DCB Word

Meaning

Bit

if file-structured device

if read-only device (e.g., PTR)

if write-only device (e.g., LPT)
. Device Type

3-8

00= console terminal
01 = high-speed paper tape reader
02 '= high-speed ,paper tape punch
03 = card reader
04 '= line printer
05= RK8 Disk
06 '= RF08 (1 platter)
07= RF08 (2 platter)
10 '= RF08 (3 platter)
11 = RF08 (4 platter)
12 '= DF32 (1 platter)
13= DF32 (2 platter)
14 '= DF32 (3 platter)
15= DF32 (4 platter)
16 '= TC08 DECtape
17 == LINCtape
20 == TM8E magnetIc tape
21= TD8E DECtape
22:-:- BAT-BA"fCR handler
23 '= RK8E disk

2-59

Table 2-12

DCB Word (Cont.)

Meaning

Bit

24 = NULL-NULL handler
25-26 = Unused
21= TA8E cassettes
30= PDP-12 scope
31-37 = Unused by Digital
40-77 = Reserved for user-written handlers
9-11

Used only by OS/8 Monitor

Whenever a device is to be inserted into OS/8, this structure
must be followed to obtain correct results.
ENTRY POINT OFFSET
Word 6 of· each device descriptor block specifies the -relative
entry point of that particular handler. Devices supplied by Digital
have a fixed set of entry points, described below.
Care should be used when coding new device handlers for insertion into the system. The entry point offset for the new handler
must not be the same as that for any other file-structured device in
the system. For example, OS/8 currently uses relative entry points
7-23 for file structured devices. No new handler should have entry
points at 7 to 23 of the page. If this occurs, the system may perform
incorrectly.
Current file device and entry point offsets are listed below:
Device

Entry Relative to Top of Page

TC08 DECtape
TD8E DECtape
LINCtape
System device
RK8 disk

-10-17 .
10-17
10-17
7
20-23

Thus, the user-coded file devices should use entry points other
than 7-23.
If a new file-structured user devIce is added to the system, it will
be necessary to alter the device length table in PIP to permit zeroing
of the device directory. To do this, ODT is used as follows:
2-60

.GET SYS PIP
.ODT
136nn/0000 xxxx
'tC
user types C'fR.t/C
.SAVB .SYS PIP
The nn represents the 2-digit device indicated in Table 2-12.
The .xxxx is the negative of the last block number on the device.
Both nn and xxxx are octal numbers.
For example, if the new device is assigned a code of 40 (currently the first unused entry), and the last OS/8 block on the device
was block 1000, PIP would be changed as follows:
• GET SY S PI P
.ODT
13640/0000 7000

• SAVE SY S PI P

2-61

CAMP (CASSETTE AND MAGNETIC TAPE POSITIONER)
The CAMP (Cassette and Magnetic Tape Positioner) program
is used to position cassettes, magnetic tapes, and certain other
devices. To call CAMP from the system device, type:
R CAMP

in response to the dot printed by the Keyboard Monitor. CAMP
prints a # to indicate that it is ready to receive a command. The
command line entered may be terminated wIth a carriage return
(CAMP retains control) or an ALTMODE (control returns to
the Keyboard Monitor).
CAMP Commands
Each CAMP command begins with a keyword, consIstmg of
two or more letters. The full CAMP command need not be typed;
each command has letters that a.re required. The CAMP commands are listed below in alphabetic order. Letters that are not
required are printed in italics.
BACKSPACE
EOF

HELP
REWIND
SKIP
UNLOAD
VERSION

BACKSPACE COMMAND
The BACKSPACE command spaces a magnetic tape or cassette backward a specified number of files or records. Thi~ command may also be issued indirectly with the CCL BACKSPACE
command. (See the CCL section of Chapter 1.)
The BACKSPACE command has the form:
BA dev: nnnn

J Records
) Files

Where "dev" is the permanent name of a cassette or magnetic
tape drive. The "nnnn" is an unsigned decimal number representing the number of records or files to backspace. This number must
be in the range 0-4095. If no number is entered, nnnn=l is assumed. This number is followed by a keyword beginning with
2-62

either an R, indicating records, or an F indicating files. If neither
F nor R is entered, F is assumed.
Examples:
ISA CSA0:

2 F

positions the cassette mounted on GSAO backward two files..
ISA MTAt:

positions the magnetic tape mounted on MTAl backward two files.
If a file mark is read before the proper. number of records have
been spaced over, the mesSage:
% CAN' T -

AT SOl'

is printed and the ctevice is moved forward one record to leave the
device positioned at the beginning of the file (just before a data
record).
The file at which the device is currently positioned is not counted
when an attempt is made to backspace a number of files. For example, the command:",
ISA MTAt:

moves backward over four file marks and then move's forward one
record, leaving the tape positioned at the beginning of the. file. If
nnnn=O, this command backspaces to the beginning of the file at
which the tape is currently positioned.
EOFCOMMAND
The EOF command writes a single file mark (file gap) on the
specified magnetic tape or cassette. _This command may also be
issued indirectly with the eeL EOF command.
The EOF command has the form:
EOF dev:
where "dev" is the permanent name of a cassette or magnetic tape
drive.
2-63

Example:
IEOF CSAI:

HELP COMMAND
The HELP command prints a short message on the console
terminal, reminding the user of the CAMP command syntax. This
command is of the form:
#HELP

REWIND COMMAND
The REWIND command issues a rewind command to one of the
following aS! R device controllers: cassette, magnetic tape, or
TC08 DECtape.
The REWIND command is of the form:
REWIND dev:
where "dev:" can be any OS/8 file-structured device. If "dev" is a
cassette, control returns to CAMP while the cassette is rewinding:
CAMP prints another #, indicating that it is ready to receive another command. If "dev" is magnetic tape Ot TC08 DECtape, the
device rewinds immediately and control returns to the OSj8 Keyboard Monitor while the device is rewinding. If a REWIND command is issued to any other OS/8 device (e.g., LINCtape), control
returns to CAMP after the device is rewound ..
Example:
IRE DTAI:

SKIP COMMAND
The SKIP command advances over the number of files or records
specified on a magnetic tape. This command may also be issued
indirectly with the CCL SKIP command. The SKIP command is not
implemented for cassettes.
The SKIP command has the form:
nnnn Records
#SKIP MTAn:
Files
{ EOD
2-64

where MT An may be any magnetic tape drive, depending upon the
number of magnetic tape drives on the, OS/8 system. The "nnnn"
is an unsigned decimal number representing the number of files or
records to be advanced over. This number must be in the'range
0-4095. EOD indicates that the tape is to be advanced to the end
of data. The end of data on a magnetic tape is a point between two
file marks. If EOD is specified, the tape must be rewound before
issuing the command if it is already past the end of data. If neither
,"nunn" nor EOD is specified, 'nnnn=l is assumed.
If a, number is specified, it 'may be followed by a keyword be- _
ginning with either an R, indicating records, or an F, ~ndicating
files. If neither F nor R is entered, F is assumed.
Examples:
ISKIP MTA0:2 RECORDS

advances the magnetic tape on MTAO forward two records.
ISKI P MTA1:

6 I'

advances the magnenic tape on MTAl forward six files.
If a file mark is read before the proper number of records have
been advanced over, the warning message: ~
% CAN'T -

AT EOI'

is printed and the tape is ~oved backward one record to position
the tape at the end of the file (just after the last data record but
before'the file
when skip, mark). If nnnn=O, nnnn=l is assumed
.
ping records.
The file at which the tape is currently positioned is counted when
an attempt is made to advance over a number of files. Thus nnnn= 1
means to advance to the beginning of the next file. If nnnn is
greater than 0; the tape is positioned at the beginning of a file (just
after a file mark but before any data records). If nnnn=O, the tape
,is advanced to the end of the 'file at which it is currently positioned
(before a file mark, but after all data records).
If the end of data is enc~)Untered before the specified number of
files have been skipped, the warning message:

2-65

% CAN'T - AT EOD

is printed and the tape is positioned at the end of data. If a tape is
already positioned at the end of data, the SKIP command produces
meaningless results.
UNLOAD COMMAND
The UNLOAD command rewinds and turns off line a magnetic
tape controller and returns to CAMP for another command while
the tape rewinds. Since the magnetic tape is turn~d off line, it must
be manually turned on line to be used after a UNLOAD command.
The UNLOAD command may also be used to unload TC08 and
TD8E DECtapes off of their reels. When used on DECtapes, the
UNLOAD command rewinds the nECtape on the unit specjfied,
selects a different unit, and returns control to CAMP for another
command. This DECtape unit cannot be used until another legal
command, e.g., the Keyboard Monitor ASSIGN command, is issued
to the DECtape controller.
The UNLOAD command can also be used to write-lock an
RK8E disk.
The UNLOAD command is of the form:
#UNLOAD dev:
where "dev" may be anyone of the following:
magnetic tape
TC08 DECtape
TD8E DECtape
RK8E disk
VERSION COMMAND
The VERSION command prints the version number of CAMP
on the terminal. This command is of the form:
IVERSI CN

CAMP EIT6r Message Summary
The error messages listed in Table 2-13 may appear during a
CAMP operation.

2-66

Table 2-13 CAMP Er~or Messages

Messages

Explanation

% CAN'T-AT BOF

? CAN'T-AT lJOT

% CAN'T-AT EOD

% CAN'T-AT EOF

? CAN'T-DEVICE DOESN'T EXIST

? CAN'T-DEVICE IS READ-ONLY

? CAN'T-DEVICE IS WRITE-ONLY

? CAN'T FOR THIS DEVICE

2-67·

A file mark was read before
the specified number of records were read over in a
BACKSP ACE com.l)land.
The device is moved forward so that it is positioned
at the beginning of the file.
A BACKSPACE command
cannot move the device
backward
the
specified
number of files because the
device is positioned at the
beginning of the first file.
The specified number of
files cannot be advanced
over because the End of
data was encountered .. The
tape is positioned at the
end of data.
A file mark was read before the specified number
of records were advanced
over in a SKIP command.
The tape is moved backward one record to leave it
positioned at the end of the
file.
The device specified in a
CAMP command is not
present on the OS/8 system.
The device specified in a
CAMP command is a readonly device, e.g., PTR.
The device specified in a
CAMP command IS .a
write-only
device,
e.g.,
TIY.
The· operation specified
does not make sense for the
device sp,ecified, e.g., REWIND LPT:.

Table 2-13

CAMP Error Messages (Cont.)

Messages

.Explanation

? CAN'T II 0 ERROR

This message is folJowed by
a brief explanation of the
input/ output error that occurred.
The "nnnn" specified in a
BACKSP ACE or SKIP
command is greater than
4095.
An illegal character was
typed in a CAMP command or a command was
iormatted incorrectiy. Tne
command must be retyped.

? NUMBER TOO BIG

? SYNTAX ERROR

2-68

CROSS-REFERENCE PROGRAM (CREF)
CREF aids the programmer in writing, debugging and maintaining assembly language programs by providing the ability to pinpoint all references to a particular symbol. CREF _operates on
output from either the PALS, SABR, or RALF assembler.
Calling and Using eREF
To call CREF from the system device, type
R eREF

in response to the .dot printed. by the Keyboard Monitor. The
Command Decoder is loaded and replies by printing-an asterisk
at the left margin. T1}e user enters one output file specification and
one input file specification.
NOTE
The input to CREF must be the listing pass
output from either the PALS, SABR, or
RALF assembler. If this is not the case,
CREF will not operate properly.
If no output file is specified, CREF assumes the output is to be
sent to the line printer. If no input file extetision or output file
extension is specified, the extension .LS is assumed. If no input file
is specified, control returns to the Command Decoder until an input file is specified. 1Jle CREF version number is printed at the
end of the CREF table in the form Vn, where n is the current
version number.

CREF OPTIONS
The following options are available to the user. ~The option is
placed in the command string, along with the file specifications.
Table 2·14

CREF Options

Option Code

Meaning

Disable pass one listing output. The output is reenabled when $ (or END if SABR code) is en- ,
countered. Thus the $ (END) and symbol table
are printed if the jP option is used. Inoperable.
for RALF output.

Disable pass one listing output and the symbol
table. Inoperable for RALF output.

2-69

Table 2-14

CREF Options (Cont.)

Option Code

Meaning

Interpret input as RALF code.

Interpret input as SABR code. Signal CREF to
accept special SABR characters. If the IQ option
is used, the IX option is forced. on.

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

Do not eliminate the file CREFLS. TM. If the IE
option is not specified, and CREF was chained
to from PALS, the file CREFLS.T~.1 is eliminated,

Cross-reference mammoth files in two major
passes. Pass one processes the symbols from A
through LGnnnn; pass two processes the symbols
from LHnnnn through Z and literals. This permits
significantly large files to be cross-referenced. If
the 1M option is used, the file CREF.SV must be
on the system device.

EXAMPLES OF CREF USAGE
Examples of calling and using CREF are given below.
Example 1:

•~

CR£F

*~TEMP

The Command Decoder prints an *, CREF assigns LPT: as the
output device. The input file is PTEMP, assumed to be on device
SYS, with the extension .LS. If the file SYS:PTEMP.LS is not
found, a search for SYS:PTEMP is attempted.
2-70

Example 2:

.w CREF
*58RLS/R
Given to the Command Decoder, this command string causes
output to be sent to the lineprinter. 1.'he input is expected to be
a SABR listing file named SBRLS.LS or SBRLS from device
SYS:.
Example 3:
.R CREf
*OTA1:LIST<DTA3:PALIST/X

This command string causes output to be sent to DECtape unit
1, as a file named LIST.LS. Input is expected to be a PAL8 list----ing file called PALIST.LS or PALIST. No literals appear in the
CREF output table.
Example 4:
.R CREF
*DTA2:LIST<$YS:BIGLST

The source listing, symbol table, and cross-reference of symbols
in the file BIGLST or BIGLST.LS on SYS is in the file LIST.LS
on DTA2. To list the CREF output the user may now run PIP.SV
as follows:
.R PIP
*LFT:<DTA2:LIST.LS

Pseudo-Op Handling

CREF recognizes certain pseudo-ops of the PAL8 and SABR
assemblers, these certain pseudo-ops caUse CREF to perform actions similar -to those taken by the assembler whose output IS
being processed. These pseudo-ops are described below:

2-71

P AL8 Pseudo-Op

Action Taken by CREF

EXPUNGE

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

FIXTAB

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

TEXT

Ignores characters between delimiters.

End-of-input signal.

SABR Pseudo-Op

Action Taken by CREF

END

End-of-input signal.

OPDEF

Creates a new permanent symbol table, a n9nskip type instruction.

SKPDF

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

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

Ignores characters between delimiters.

Interpreting CREF Output

The output of CREF consists of two parts. 'On the first pass
through the input file CREF generates a sequence numbered listing file. The sequence numbers are decimal. The IP and IV
options disable this part of the output.
The cross-reference table appears after the listing. This table
contains every user-defined symbol and literal, sorted alphabetically. Each literal is indicated by an underline (or back-arrow on
most DEC terminals) and followed by the field and address at
which the literal occurs. For each symbol and literal there appears
a list of numbers specifying the line in which each is referenced.
If CREF finds too many references to fit into core at one time,
2-72

multiple passes are required to process all symbols. The minimum
number of passes is two. The maximum number of.passes depends
on the size of the input file, and the '!ffiount of core available.
CREE .calculates the number 'of core fields available.and uses all
available space for reference tables. If there is not enough core
available, three or more passes are required. For example, the·
current OS/8 SABR assembler (5518 source lines, 849 symbols)
requires four passes through CREF on an 8K machine.
The following example illustrates a program which has been
assembled with PAL8 and listed with CREF. Form feeds on the
terminal have be·en converted to a series of carriage return/line
feed combinations and a dotted tear line. Notice that in the CREF
table the line where the symbol is defined is followed by a # .
Symbols defined by OPDEF or SKPDF in SABR, and all literals
do not have a # following them.
/EXAMPLE PROGRAM

EXAMPLE PROGRAM

1
2

I
I
I

9
10
11
12
13
14

15
1&

18
19
i/0
21
22
i!3

24
25
2&
27
is

10200
10201
10202
10203
10317
10177

0002

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&

·03/05/74 . PAGE 1

EXAMPl.E PROGIUM
ILLUSTRATI~G OETAILS OF LISTI~G ~ORMAT
USING PALS AND CREF

0200 020111
7300 START, CLl Cl.L
TAO A
1207
1777' .
TAO B
1177
TAO 12
137&
TAO (3
3777'
DCA LINK
JMP I ADDRP2
5&10
0011
0011 A,
0400 ADDRP2. P2
11101113
11141117
0400 *400
121117 P2.
TAO l.I~K
TAD (3
1377
TAO (2
1177
TAO (3
1377
DCA B
3207
&213
CDF CIF 10
5771>'
JMP Fl.Dl
000111 lINK,
0
041117
B-l.INK
0200
0003
0002
0001 FIElD 1
TAO (3
1377 FlD1.
TAO 12
1177
CIF CDI' 0
&20.3
JMP START
5200
0003

5
&
7

PALe-Vge

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 2 START
INOT.E THAT nns IS A NEW LITERAL
INOTE THAT THIS IS SAME OLD l.ITERAL
ISAME 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<CLA;TAn 8; HLT \ERROR>
\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 <XLIST>
IFNZRO EXOR <CLA,TAU SI
IFZERO EXOR <XLIST>

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
\<JNXX
• BA

718

118-JAN-74
1 18-JAi'J-74
119-JAN-74
1 19-JAN-74
1 21-JAi'J-74
121-JAN-74

WNTSTA. BA
\oJNT STB. SA
WNPALA. PA
WNTSTD.BA
MTPALC. PA
.SA
WNXY

1
1
1
1
1
1

IB-JAN-74
19-JAN-74
19-JAN-74
21-JAN-74
21-JAN-74
21-JAN-74

fREE BL OCK S

Example 2:
This example shows' all files that have a file name beginning
with WN, have any
extens,ion, ana do not have the current
date. The directory is listed in two columns on TTY.

file

*DTA0:\OJN????*IO=2
21-JAN-74
\OJNTSTA. SA
\olNTSTC. BA
WNPPPA.PA

1 18-JAN-74
1 19-JAN-74
119-JP.N-74

WNTSTB.BA
\oJNPALA. PA

1 19-JAN-74
1 19 -JAN-7 4

7 18 fREE BL OCK S

Example 3:
This example shows files that have any file name, have a .BA
extension, and have the current date. The directory is listed in a
single column on TTY.
2-79

*DTA0: *. BAIC

21-JAN-74
WNTSTD.BA
WNXX
• SA
WNXY
• SA

1 21-JAN-74
1 21-JAN-74
1 21-JAN-74

718 FREE BL OCK S

Example 4:
This example demonstrates the use of the IU option to produce separate directories for each input spcification. The command
specifies that all files beginning with WN and having .BA exten"';,.,.... s kO 11'"tori
....'nn'n
.... ""1th
WN anrl haUln"
.:> ....""'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.

"""'13

.1.

.L.l.

"'",.&..1.

,Y..l."

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

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

* L P 1: < D T A 0: ~}N ?? ? ? • 8 A" Wi\) ? ? ? ? • P AI F' I u= 3
WNT~TA.BA

WNTSTb.BA

WNTSTC.8A

WNTSTO.liA

wtJU

WNXY

• BA

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

ILLEGAL *

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.

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<DTAl: XYZ. SV/2$

compare file ABC on the disk
with file XYZ on DTA 1 and
output block numbers and locations of each non.;,match on
the Teletype. .-

After one of these numeric options has been included in a command, it need not be specified again in subsequent sequential
commands requiring th~ same option. Specifying the number puts
EPIC in a mode and it remains in that mode until another number
is specified. Initially, EPIC is set to option O. The character ALTMODE, which prints as $ on the terminal, is used to end a command that includes a numeric option.
2-83

Restart Procedure
EPIC can be restarted at location 0200. Default options remain
active. The default options are discussed later in this section.
Paper Tape Facility
The paper tape option UO) of EPIC punches OS/8 files and file
patches onto paper tape and creates OS/8 files from paper tapes.
Whole files or patches (blocks) of files can be read or punched.
Parity checks are punched to assure accurate reads. Note that a
unique paper tape format is used so that tapes must be both
punched and read by EPIC. A file punched by PIP, for example, is
not acceptable to EPIC.
Command Format
To request the paper tape facility, the option 0 must be specified. The form of the response to the command decoder's * determines whether a tape is to be punched or read. In both cases,
no input files or devices are specified. To punch a tape, the file
name is specified; to read a tape, no file name is required (that information is encoded on the paper tape). The command line spec':'
ifying the mode of EPIC is terminated by ALTMODE.
To punch a tape, the response is:
*dev:name</O/other options$
To r"ead a tape, the response is:
*dev: </0/ other options$
If a file name is specified, EPIC looks up the name on the specified
device and punches the file (including the file name) onto paper
tape. If no file name is speci~ed, EPIC reads in a paper tape and
enters it onto the output device under the name it read in from
the tape.
The other options for handling paper tape are:
L
E
P
Z
=n
Y

Use low speed paper tape reader or punch
Do not punch end of tape upon completion
Punch or read a patch (instead of the whole file)
Set relative block to 0
Punch relative block n
Clear default name
2-84

These options can be combined to achieve the desired results.
L Option:

E Option:

•

P Option:

Y Option:

If the /L option is not specified, EPIC assumes a
high-speed paper tape device. Thus, SYS:</O
means read a tape from the high-speed reader to
device SYS but SYS:<IO/L means read it from
the low-speed device.
The IE option can be used to punch a series of
patches to a file for all patches except the last one.
With the /E option the end of tape mark is not
punched. The end of tape must have the "end of
tape" punch, a 377 punch and a length of leader/
trailer tape .
The IP option is required to indicate the tape to
be read or punched is a patch, not an entire file.
Generally, the command required to read in a patch
is simply dev: </P. File name and block specifications are already punched on the tape.
Option IZ or ==n mus(be used with the IP option
to indicate punching block 0 or some other block
(relative block n), respectively. The patch is read
on top of an existing file on the specified output .
device, i.e., modifying an old file, not creating a
new one.
The /Y option is used to clear the default file name
when switching from punching to reading paper
tape and when reading more than one paper tape.

Default Options

Throughout EPIC, if options, files, or devices are not specified,
the program defaults to the last such item specified. There IS an
initial default. device: SYS is assumed if no output device is specified. No options are assumed initially, however, except for relative
block O. Note,.that device and file name options carry between
. EPIC modes 0,' 1 and 2. Specifying an option (i.e., L, P, E, Z,
etc.) in a command string disables default to any options from the
previous command (except 0, 1, 2).
For example, to punch blocks 0, 1 and 30 of the file TRANS on .
the SYS device and read them back onto that file on DTA3, the
commands are:
2-85

Punch block 0 of TRANS on
high-speed punch with no end
of tape punch. Note that
EPIC defaults to the papertape option initially so 0 is
not required in this case.
Punch block 1 of file TRANS
with no end of tape character
on high speed device.

• R EPI C

Punch block 30 of the file
TRANS oil high-speed punch.
Punch end of tape (P disables E).
•
n __ ..J ..1...
.. _-the
.l'.l;dU lU e ldpl;; 11 UIU
1
IH O U
speed device ?nd put out to
file whose name is encoded
in the patch on device DTA3
until end of tape is reached.
File name and relative block
are punched on the tape so
this information is not necessary. Y clears the default
name. (TRANS)

*TRANS</P/E/Z$

.,-~-

*DTA3:</y

1...:~1...

Error Conditions
If an error occurs while reading a block of paper tape, EPIC
outputs an appropriate error message (the error messages are
listed at the end of this section), and halts; the user shouldreposition the paper tape to the leader/trailer just in front of the block
just read before continuing (refer to the section on Paper Tape
Format); three consecutive read errors terminate the command.
When EPIC is reading in a non-patch file it checks the initial
block read of every tape and every block that is reread because
of error to determine if the read was accurate up to name and
block number. If the wrong block number or file name is read,
EPIC outputs an appropriate message indicating the type of error
and halts with AC=:;7777 to allow the user to reposition the tape
over the correct block or enter the correct tape before continuing.
Low Speed I/O

The execution of EPIC differs for low speed I/O. Before starting a low speed punch EPIC halts with 7777 in the AC to allow
2-86

the user to tum on the low speed punch and then press the coNi'
key on the computer console. Upon completion of a punch com-mand EPIC halts with the AC==O to allow the user to tum off
the punch. When the CONT key is pressed, EPIC recalls the
cqmmand decoder. For low speed input EPIC. halts only upon
completion of the read.
If a file or a series of files to be punched exceeds 32 blocks,
EPIC segn:tents it by punching end of tape after 32 blocks. This
end of tape punch is done automatically and independently of
the E option; its purpose is to keep tapes physically short enough
to fit into a paper tape tray. Upon physical end of tape, EPIC
halts with the AC==O if the low speed punch is being used to allow
the user to tum off the punch before ~ontinuing. As soon as the
punch is turned off, EPIC outputs the message END OF TAPE
ENTER NEXT and then halts with the AC -7777 to allow both
high and low speed users to remove the paper tape. Note that low
speed users get both halts, but high speed users only get the 7777
halt. In general, a halt with AC==O means turn paper tape device
off and a halt with AC== 7777 means turn device' on. All halts are
terminated by depressing the console CONTinue key. If EPIC
encounters end of tape while reading a non-patch file it outputs
the message END OF TAPE. ENTER NEXT and halts with
AC==7777 indicating that the file is segmented across a number
of tapes and that the user should enter the next tape.
Device Codes
Most of the execution time is spent waiting for paper tape devices.
During 1/0 wait, EPIC holds the device code and version number
in the AC. The device code is in bits 3-5 and the version number
is in bits 6-11. The codes are as follows:

1 high speed reader
2 high speed punch
3 low speed reader (console TTY)
4 low speed punch (console TTY)
If the user forgets to turn on the high speed reader, EPIC hangs

with lxx in the AC. EPIC can always be restarted at 0200. The
OSj8 CTRLjC is normally in effect; the exceptions are when
EPIC is waiting for a paper tape device or when input is from the
low speed reader.
2-87

NOTE
When input is from the low speed reader
EPIC forces the output device to be SYS
because it is the only OS/8 I/O handler
that does not check for CTRL/C.
Thus, if the user were to enter the command:
DTA2: < /L

EPIC would force it to be

Sy s: < /L

Editing Capability
Option 1 of EPIC is the file editing and searching facility. With
this feature, patches can be added directly to the file by specifying
relative blocks and locations in the file.
INITIAL COMMAND FORMAT
The general format of a command for the editing option is:
• R EPI C
*DEV:NAME</OPTIO'JS/l$

. The /1$ specifies edit mode for EPIC.
As with the paper tape option, default conditions apply. If no
device and/or file name is specified, the last one mentioned is used.
When editing, the only option available in the initial command is
/Y

Clear default name (if one exists)

Editing is performed one block at a time. The relative block currently being processed is the current block; the location currently
being processed is the current location (0-377). Relative block 0 is
the first block of ,the file if a file name is specified or block 0 of
the device if no file name is specified.
2-88

EDITING COMMANDS
After the initial (file specification) command, a se~es of keyboard commands are used to perform the editing. The general
format of an editing command is

or
x,nl,n2
where x is a command letter and nl,n2 are octal numeric arguments. If a numeric argument is used, the letter is followed by a
comma. Up to 3210 characters can be typed on a line. Default conditions apply to these -commands as well. If carriage return is the
only character typed as an editing command, the last command
specified i~ executed. The commands available are as follows:

Table 2·18
Command

EPIC Commands
Meaning

Exit to command decoder; write out current block of
file if it has been modified.

R, n

Read relative block n (octal) offile and set current location to O. Do not write current block. If n is not specified, the current block is read. If the ,relative block is
out of range, a ? is printed. There are 1341 blocks per
OS/8 tape and 6260 per RK8 disk platter.

Write the current block of file if it has been modified
and read in the next sequential block of the file. If the
current block is the last block of the file, a ? IS printed
and the current location is unmodified.

S, nl, n2

Search the current block for the value nl with the mask
n2. If either n 1 or n2 or both are omitted, the last value
specified is used. The initial- mas~ is 7777. Masking
is performed in a logical AND fashion. If the S command is terminated by the RETURN key the search is
for the current block only. If terminated by the LINE
FEED key, the search continues to the end of the file.
If the search fails (either in the block for a carriage
return or at end of file for line feed) EPIC prints a ?
If the search is successful EPIC prints

2-89

Table 2·18
•

EPIC Commands (Cont.)
Meaning

Command

ml m2
m3 I
where ml is the relative block, m2 is the relative location within the block and m3 is the contents of the location. (ml is omitted if a previous match was found in
the same block.) To change the contents, type the new
contents (octal) after the slash. To continue the search
type the LINE FEED key; to terminate the search type
the RETURN key. (If the contents are not to be
changed, type one of the terminators.)
0, n

Open location n of the current biock. If n is not specified, the last opened location is the default. If there
is no default, location 0 is opened. EPIC responds with
mIl

which is the contents of location n. This location may
_be modified as in search. Terminating with the LINE
FEED key closes the current location and opens the
next. If the current location is the last one in the block,
location 0 of the next block is opened and the current
block is written out as if it had been modified.
C

Print current status, as:
m I (F or B) m2 m3 m4
where ml is the current block, m2 is the current location, m3 is the search word and m4 is the ,mask word.
If F is typed, the file has been modified since option I
was requested; B indicates the current block has been
modified. Once a modified block has been written to
the file, the F .is the only code output.

2-90

Thus a reasonable sequence is:
Call EPIC .
Edit file ISOMER on DSK.
Read block 2.
Search for a 312x mthat
block.
Not there.
Search for it throughout the
file~
.
.Found. at block 4, location
110.
Change contents to 3121.
Search .for 31xx throughout
the rest of the block (locations 110-377).
Found at location 132 of
block 4.,
Contains 3126. Change to
3127.
Check status.
At location 132 of block 4
which has been modified; the
current search word is 3126
and mask is 7777.
Write block 4.
Block 4 written but file is
only four blocks long, no
block 5 to read.
Read block 2.
Open location 10.
Contains 1367. Change to
1364.
Check next location. No
modifications.
Exit editing option.

• R EDI T
*DSK: I SOMER</I$

R,2
S,3126,7770
?
>

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 <SYS:file2joptionsj2$
The first file to be compared is specified to the left of the angle
bracket, the second file to the right. The options are:
A Abort when the first non-match is found.
B List physical block number for each file where a non-match
exists.
If no options are specified, the block numbers and locations of
each non-match are listed on the terminal.
For example, to compare files PYTHG 1 and PYTHG2 and find
all unequal locations, the sequence is as follows:
~SYS:PYT~GlcSYSIPYTHG?/?S

SYS:0174 SYS~0b31
e152 7450 3421
0153 5741 21d21
"154 34lil 302~

*
. To compare them and list unequal blocks the command is:
~~VSIPYTHG1SYStPYTHG2/B/2$

If this block match followed the preceding locations match com. mand, a sufficient command and its results are:
1:/8

SYSz0174

SYS:0b31

To abort after the first non-match, the sequence is:
~jA

SYSz0174

SYS:0b31

Error Messages
EPIC can print one of the following error messages when performing paper tape (option 0) operations.
2-92

Table 2-19

EPIC Error Messages
Explanation

Message
BAD =BLK

When EPIC is punching a patch it checks
the block specified by ·'=n" to see if it is
within range. If the block is out of range
EPIC outputs this error message and returns
to the command decoder. For example if a
file JOE were two- blocks long and the user
requested:
JOE:~/P=3

END OF TAPE

END OF TAPE
ENTER NEXT

I/O ERROR

LIT ERROR

NEED:namel
FOUND name2

the error message would be printed.
EPIC was expecting a block of tape and
found end of tape instead. EPIC halts with
AC==.7777 -to allow the user to reposition
the tape. When the user depresses CONTinue EPIC attempts to read the block.
When EPIC is reading a file that is segmented across a number of paper tapes and
encounters the end of a segment, it outputs
this message and halts with AC=7777 to
allow the user to enter the -next segment of
paper tape. Press the Console CONT key
to continue reading.
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, andreturns to the command decoder.
EPIC was expecting leader trailer and found
non-leader trailer while attempting to 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 Computer Console CONT key.
EPIC read a block of tape for the file
NAME2 when it was expecting a block of
the file NAME1. This error would typically
occur when a user comes to the end of a
segment for NAME 1 and enters some segment of NAME2 instead of the next segment for NAMEl. EPIC halts with AC=
7777 to allow the user to enter the correct
paper tape.

2-93

Table 2-19

EPIC Error Messages (COIit.)

Message

Explanation

NEED:n1FOUND:n2 EPIC read block n2 of the file when it was
expecting block n1 of the file. EPIC halts
with AC=7777 to allow the user to reposition the paper tape. This error typically
occurs when the user repositions the tape
to the wrong block after a read error.
PARITY ERROR

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.

PTR:NAME IS TOO The paper tape file NAME will not fit on
the specified output device DEV:. EPIC
BIG FOR dev:
aborts the command and returns to the command decoder. EPIC makes the check for
size before writing on the output device.,
USR n dev: name

The USR encountered an error while attempting to perform a fetch, lookup, enter,
or close on the file NAME on device DEV.
n=l 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. For example, if the user requests EPIC to punch
a file on SYS that does not exist:

EPIC outputs the message

USR

0~0~

SVSINILL

indicating that it could not find the file
NILL on the device SYS.

2-94

Paper Tape Format
Paper tapes punched -by EPIC have the following format:

2
FEET
LIT

DATA
BLOCK

8
INCHES
LIT

LSTART OF BLOCK
PUNCH

2
FEET·
LIT

8
DATA
.......
BLOCK INCHES
LIT

•

END OF TAPE PUNCH

Leader trailer is any string of 0 or 200 punches; usually it's just
200 punches; leader trailer is terminated by a 201 punch which
indicates the start of a data block. The first punch after the last
data block is 377 which is end of tape. Each data block has the
following fol1i1at:

Each byte is 12 punches (96 bits) and corresponds to 8 12 bit
words; each byte is followed by an even odd' parity punch of the
eight words in the byte. Each block is terminated by two CRC
punches of longitudinal parity.
The h,eader byte contains information about the file e.g., file name
and relative block number. The data bytes constitute the actual
data of the block; there are 32 data bytes per 256 word block.

Loading EPIC From Paper Tape
For users who receive EPIC on paper-tape, use the following
procedure to load the tape and save it on a mass storage device.
- . ~f<

Use ABSLDR
Read from reader; after t is
output, type any key to start
reader
Save on mass storage with
starting address of 200

~8SLI.lR

:!PT k I i.t

2-95

EPIC Assembly Instructions,
The PAL8 (version 9) assembler is used to assemble EPIC as follows:
,R pAL.S
.OEVIEPIC.8f11,DE VIEPIC,L.scOEVIEPlt.PA

To create the save file, use ABSLDR:.

,R ABSLDR
.. OEVI~PIC.8NS
~SA OEV E~IC ~~7~77'0~00.0

Call ABSLDR.
Load EPIC.BN on device
specified.
Save EPIC on device specified.
0-7577
area in core used
reduring execution. 0200
start address.

2-96

FILE ORIENTED TRANSFER PROGRAM (FOTP)
FOTP is an OS/8 program used to transfer filesJrom one device
to another, to delete files from a device, and to rename files. FOTP
is significantly faster than PIP and performs certain functions not
available with PIP. For example, FOTP can transfer files longer
than 256 blocks and can perform multiple file transfers and
deletions without requiring multiple accesses of the directory.
FOTP copies files in image mode, i.e., it copies the file word for
word, character for character, without making any changes in the
file. (Tbis corresponds to the /1 option in PIP.) Thus FOTP may be
used to copy core image and' binary files as well as ASCII files,
without specifying options to identify the type of file.
Calling FOTP
To call FOTP from the system device, type:
R I'OTP

In response to the dot printed by the Keyboard Monitor. (FOTP
may also be called indirectly by' several CCL commands. See the
CCL section of Chapter 1.) The, Command Decoder prints an
asterisk at the left margin and waits to receive a line of I/O files
and options. FOTP accepts one output specification and up to five
input specifications. The I/O specification line may be terminated
with a carriage return (FOTP retains control) or with an
ALTMODE (control returns to the Keyboard Monitor).
INPUT SPECIFICATIONS
FOTP input specifications consist of a device, a file name, and
a file name extension. Input specifications are optional but must be .
present if no output specification is included.
Within the input specification, FOTP allows a wild card construction to be used. This means that the file name or the extension
may be replaced totally with an asterisk or partially with a question
mark to designate certain file names or extensions. The asterisk is
used as a wild field to designate the entire file name or extension.
For example:
TESTl.*
*.BN

All files with the name TEST 1 and any extension.
All files with a BN extension and any file name.
All files.
2-97

The question mark is used as a wild character to designate part
of the file name or extension. A question mark is used for each
character that is to be matched; e.g., PR?? matches on four characters or less. For example:
TEST2.B?
TES??PA
????

All files with the name TEST2 and any extension
beginning with B.
All files with a PA extension and any file name up
to five characters beginning with TES.
All files with file names of two characters or less.

The asterisk and the question mark can be specified together in
the same command line.
??? . *

All files with file names of three characters or less.

The following are examples of legal FOTP input specifications:
DSK:
SYS:A
LTA3:TESTIA
DTA7:A.BN
FILE
FILE3.DA
4
NAME?TX,NAM??BN
N?ME.
??????D?

*.BN
PRN:*.??
?W?B?Z.?A
A specification may not contain embedded *'s, e.g., A *B. * is an
ilJegal specification. The following are illegal input specifications:
A,B,C
A:B:C
A?*.B
.AB
DAT:A.*B
A?B:C
*:BIN
2-98

For each input specification given, if no device is explicitly
given, then the device associated with the previous specification is
assumed. If no device is explicitly given for the first specification,
then DSK: is assumed. Thus, the following input specifications are
equivalent: .
DSK:B
SYS:B. *,C. *,D. *
B. *,DT AO:,SYS: *.BN

B
SYS:B. *,SYS:C. *,sYS:D. *
DK:B. *,DTAO:,SYS:* .BN

As many as five input specifications can be included in a single
command line. If all the files are on the same device, the input
device need be specified only once. For example:
DTAO:* .BN, * .SY, *.RL
refers to files on DTAO that have .BN, .SY, or .RL extensions with
any file name.
OUTPUT SPECIFICATIONS
FOTP output specifications consist of a device, a file name, and
a file extension. Output specifications are optional. The wild card
asterisk may be used in output specifications, but the question
mark is illegal.
If no output device is specified but a file name is given, then
DSK: .is assumed. If no file name is'specified, then *. * is assumed ..
Thus the following output specifications are equivalent:
A
A.*
DTA3:

DSK:A
DSK:A.*
DTA3:*.*

Using FOTP
Since FOTP perfonns file transfers in a different manner than
other OS/8 transfer.programs, the"following is a detailed description of the way in which FOTP works. One of the main uses of
FOTP is to copy files from one device to another. The following
examples are used to show how FOTP examines each aspect of a
command to detennine what operation will actually take place.
2-99

Example 1:
To copy the file SMILE.PA from DTA3 to DTA5, changinR its
name to FROWN~PA, type:
.
DTA5:FROWN.PA<DTA3:SMILE.PS

in response to the.>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<DTA3:SMILE.PAIN

begins to copy SMILE.PA to DTA5 without deleting the old
FROWN.PA. FOTP does this by opening a tentative file
named FROWN.PA on DTA5. When the transfer operation is
successfully completed, the tentative file is closed. Closing this
tentative file makes it a permanent file and, at the same time,
deletes any old files of the same name. This process is known
as postdeletion.
4. FOTP assigns the creation date of SMILE.PA to FROWN .PA.
This is an advantage over PIP, which would assign the current
date to the new file. If files are always transferred' with FOTP,
the original creation date of the file is preserved. Thus this
feature of FOTP allows the user to differentiate between versions of a file since the more recent version should have a later
date.
5. The IT option of FOTP can be used to assign the current date
to a file. For example, if SMILE.PA is undated, FOTP assigns
the current date to the newly created FROWN.PA.
I

2-100

DTA5: FROWN. PA<DTA3:SMILE. PA/T

•
6. Advanced users may be using the additional information words
feature of OS/8. This feature allows the knowledgeable user
to associate additional information (other than the creation
date) with each file entry in a device directory. FOTP transfers
such additional information words from SMILE.PA to
FROWN.PA. (PIP does not perform this function.)
If the file -structure on DTAS has space for more additional
information words than appeared with SMILE.PA, then those
extra words are set to O. .
If the file structure on DTAS does not have enough space for
all the additional information words associated with
SMILE.PA, then FROWN.PA is given as many as CC:Ul fit (from
the left). Excess information words (on the right) are not
transferred.
Example 2:
Normally, one copies files from one .device to another without
changing the file name. For example, to copy the file TEST.PA
from DTA1 to DTA2, type:
DTA2:TEST.PA<DTAl:TEST.PA

in response to the * printed by the Command Decoder. Since this
transfer eperation is so common, FOTP allows the output file
name to be abbreviated to *. *. The *. * means that the input file
name is to be used as the output file name. Thus the preceding
command could be typed as:
DTA2:*.*<DTAl:TEST.PA

Since the *. * specification is so frequently used, it is the default,
i.e., if no output file name is specified, *. * isassumed~ Thus the
precedIng command may be further simplified to:
DTA2:<DTAt:TEST.PA

Example 3:
One of the more attractive features of FOTP is that it allows
multiple files being transferred from one device to another to be
2-101

included in the same command line. For example, to transfer five
FOR TRAN source files from SYS to RKA2, the user could type:

The wild card characters * and ?, explained previously, are
particularly useful when doing multiple file transfers. For example,
to transfer all FORTRAN II source files from SYS to RKA2,
type:

The specification *.FT means files with any name that have the
.FT extension.
To copy all files from DTA1 to DSK, type:

Note that the *. * specification has different meaning when
placed on the left side of the < than it does when placed on the
right When used on the output (left) side, *. * means that the
output file name is the same as the input file name. When used on
the input (right) side, *. * means transfer or consider all files on
this device. For example:

copies three files from SYS to RKA2. PIP would require three
commands, each transferring. one file, to perform the same operation.
Note that in the preceding example, no output file name is
specified, so *. * is assumed. No device is specified for the files
TEST2.PA and l'EST3.PA, so the device specified as the previous
input device (SYS) is assumed.
Frequently, several files with similar names (as above) are to be
copied from one device to another. In many cases, these files can
be referenced by a single file specification by using the ? wild
character. For example the command:
DTA21~ •• <DTA1:TEST?PA

2-102

transfers all files on DTA1 that have the extension .PA and that
have names beginning with TEST followed by one other character.'
ADVANTAGESOFPREDELETION
The default mode (and the recommended vne) of FOTP is to
use predeletion when copying files. Predeletion creates space on
the output device for the new file. Suppose that, in Example 1
above, DTA5 were almost full. There might not be enough sp~ce
on DTA5 fot SMILE.PA. If, however, FROWN.PA is first deleted,
this could create enough space for SMILE.PA
Predeletion normally places the new file in the space occupied
by the file being replaced. In Example 1 above, if FROWN.PA is
first deleted, the space where it resided is empty. This empty space
could then be used for the new copy of FROWN.PA (the former
SMILE.PA).If predeletion were not used, the new tentative file
for FROWN.PA would probably be placed at the end of the fape.
This procedure would create a gap (EMPTY) when the old copy
of FROWN.PA was deleted; thus the files on DTA5 -would be
ordered differently.
ADVANTAGES OF POSTDELETION
Postdeletion IS a slightly safer method of transferring files since
the original file is not deleted until a transfer is successfully completed. Suppose that, in Example 1 abOve,' SMILE.PA is an, updated version of the FROWN.PA that-exists on DTA5 and that
these are the only tWo copies of a certain source file. If predeletion
is performed and SMILE.PA is discovered to have a permanent
input error, that source file will have ceased to exist because
SMILE.PA will be unreadable and FROWN.PA will have been'
deleted. The use of postdeletion in this case would save the original
copy (FROWN.PA) even though the updated version (SMILE.PA)
could not be read.
CONTROL CHARACTERS
The special characters CTRL/C and CTRL/P are used to
terminate FOTP operations. When CTRL/C is typed~ FOTP continues operation until the files on the output device are the same as
those in the output device directory. Control then returns to the
OS/8 Keyboard Monitor.
CTRL/P causes FOTP to te:r;minate the current operation but
FOTP retains control. The output device directory is updated to
2-103

reflect the operations completed before the termination occurred.
FOTP prints an asterisk and can receive another I/O specification
line.
If CTRL/C or CTRL/P is typed when deleting (lD) or renaming (lR), no FOTP operations are performed and the message:
ORIGINAL DIRECTORY PRESERVED

is printed.
FOTP Options
The options listed in Table 2-20 may be used in a FOTP specification line.
Table 2-20

FOTP Options

Option

Meaning

Current date. Consider only those input files with the current date when performing a FOTP operation. For example, if the command:

*OSK:<OTA0:*.-/C
Is typed, FOTP transfers from DTAD to DSK only those
input files that have the current date.
ID

Do not perform any I/O transfers, i.e., perform only deletions. I D is not an abbreviation for delete although it
usually performs that operation. This option compares the
input specification with the output specification, if any, for
matching files. If a match is made, FOTP performs as
though transferring the file, and then deletes the transferred file.
If no transfer occurs, no postdeletion occurs. Predeletion
might still occur unless the / N option is included. If no
output device is specified, FOTP assumes the first input
device specified as the output device. If no output files or
extensions are specified, i.e., *. * is specified or assumed,
the input file names become the output file names. If no
input files are specified, no deletion takes place.

Failsafe. The I F option protects files during a transfer
operation. It is particularly useful when transferring a great
number of files from disk to DECtape. The / F option allows a new volume to be mounted if a large file will not

2-104

Table 2,20

FOTP Options (Coot;)

Option

Meaning
fit on the output device or if all files_ will not fit on the-~
output device. If, for example, a user wishes to transfer.
all .BN files from DSK to DTAO, he types:
DTA0: <D51<:*. SN/F

If the output deviGe becomes fuil before transfer is complete (or if a large file will not fit), FOTP prints:
M()lJ.JT NEXT OUTPUT- VOLUME: •.

Dismount the current tape and mount a new tape on the
same unit. Type any character to. continue. The device
mounted must have a good OS/8 directory. FOTP then
continues the transfer on the new volume and updates
the directories of both volumes.
/L

List on the terminal the names of files affected during the
FOTP operation. Note that neither the device nor the output file is listed.

No predeletion. Delete output file. names after a successful
II 0 transfer occurs. If an II 0 transfer proceeds, any other
files of the same name will automatically be deleted when
the file is closed.'
.

Other than' the current date. Consider only. those input
files with a date other than the currerit date when performing a FOTP operation.

Query the user about each relevant file name to determine
whether he wants the specified operation to occur for that
file. This relevant file name could be either an input or output file name depending upon the type of FOTP operation
being performed. For example, if input files are being renamed, FOTP prints the affected input file names. If output files are being deleted, FOTP prints the output files
that will be affected. FOTP prints each relevant file name on
the termin?l and waits for the user to respond. A response
of Y causes the specified operation to be performed. Any
other response causes that file to be ignored and FOTP
prints the next relevant file name.

2-105

Table 2-20

FOTP Options (Cont.)

Option

Meaning

Rename the output file without performing any transfer.
This operation is performed by specifying the same device
as both the input and output device. For example:

DSK:TEST3.PA<DSK:TEST2.PA/R
would change the name of the DSK file TEST2.PA to
TEST3.PA without performing any transfer.
IT

Assign the current date to the corresponding input file.

Treat each input specification separately. This option causes
FOTP to find files in the same order as they are entered
in the input specifications. For example, the command:

TEST.PA
DATAl. JOT
TEST2.PA
finds the files in the order that they were specified in the
command, not in the order in which they may appear on
DSK.
IV

Consider only input files which do not have the form specified by the' input specifications. For example, the command:

transfers to DTAO all files on SYS other than those with
.SV or .HL extensions.
IW

Print the version number of FOTP on the terminal.

EXAMPLES OF FOTP SPECIFICATION COMMANDS
The following are legal command strings to FOTP. When FOTP
has completed an operation, control returns to the Command
Decoder for additional input, unless the ALTMODE is used to
.. tenhinate the FOTP command line.

2-106

Example 4:
DTA0z<A.B

This command string transfers the file A.B from the device DSK
to DTAO.
ExampleS:

. This command string transfers the files A, B, C, D, and E from
the system device to DTA3.
Example 6:
DTA2: <DTA5:

*. FT It.

This command string transfers all FORTRAN. source files from
DTAS to DTA2, producing a log of those ·copied. "
Example 7:

This command string lists all FORTRAN files, then all BASIC
files on the line printer.
Example 8:

This command string copies from DTA3 to DSK all files other
than core image (.SV) and binary (.BN); it then copies from DTA2
to DSK all files other than those with names beginning with K. A
listing is printed of all files copied.
E~ample 9:
DTAI: c. D<A. BIT

The above command copies the file A.B from DSK. to DTAl,
clianging its name to C.D, and assigns the current date to the file.
2-107

Example 10:
SY S:

* • PL < L T A2: * • PA IN

The above command copies from L T A2 to the system device all
files with .PA extension, changing the extension to .PL.
Example 11:

This command string deletes any disk file which has an extension of .LS, .TM, or .BK or has a name beginning with TMP if the
fila. Ana." .1..1."'''
nnt "h'3"(1P t"hp "'U1Tpn t datp
.L.I. ' "

u..,-,,,-,,~

.&. ................

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

,..".

........... .L£

Error Messages'
The error messages listed in Table 2-21 may appear during a
FOTP operation.
Table 2-21

FOTP Error Messages

Message'

Meaning

ALREADY EXISTS (file name)

An attempt was made to rename
an output file with the name of
an existing output file.

BAD INPUT DIRECTORY

'The directory on the specified
input device is not a valid OS/8
device directory.

BAD OUTPUT DEVICE

Self-explanatory. This message
usually appears when a non-file
structured device is specified as
the output device.

BAD OUTPUT DIRECTORY

The directory on the specified
output device is not a valid
OS/ 8 device directory.

DELETES PERFORMED
ONLY ON INPUT
DEVICE GROUP 1
CAN'T HANDLE
MULTIPLE DEVICE
DELETES

More than one input device was
specified with the / D option
when no output specification
(device or file name) was included.

2-108

'JabJe 2-21

FOTP Error Messages (Cont.)

Message

Meaning

ERROR ON INPUT DEVICE,
SKIPPING (filename)

The file specified is not transferred, but any· previous or subsequent files are transferred and
indicated in the new directory.

ERROR ON OUTPUT DEVICE,
SKIPPING (file name) .

The file· specified is not trans",:
ferred, but any previous or subsequent files are transferred and
indicated in the new directory.

ERROR READING INPUT
DIRECTORY

Self-explanatory.

ERROR READING
OUTPUT DIRECTORY

Self-explanatory.

ERROR WRITING
OUTPUT DIRECTORY

Self-explanatory.

ILLEGAL *

. An * was entered as an embeded
character in a file name, e.g.,
TMP*.BN.

ILLEGAL?

A ? was entered in an output
specification.

NO FILES OF THE
FORM xxxx

No files of the form (xxxx) specified were found on the current
input device group.

NO ROOM, SKIPPING
(file name)

No space is available on the output device to perform the transfer. Predeletion may already.
have occurred.

SYSTEM ERROR-CLOSING
FILE

Self-explanatory.

USE PIP FOR NON-FILE
STRUCTURED DEVICE

An input device specified is not
a file-structured device, e.g.,
PTR.

2-109

· MAGTAPE/CASSETTE PERIPHERAL INTERCHANGE
PROGRAM (MCPIP)
MCPIP is an OS/8 program that is used to transfer files between
standard cassettes or magnetic tapes and other OS/8 system devices, delete such files, and transfer directories. MCPIP allows the
OS/8 user to read or write any standard cassette file on a cassette
or magnetic tape. In particular, MCPIP can read or write any file
created by or to be used by the CAPS-8 system or by the OS/8
system (using any OS/8 device handler). MCPIP can also read
or write any magnetic tape file that is in standard cassette file format, i.e., a file created by MCPIP or by CAPS-8.
MCPIP may be run on any OS/8 system equipped with at least
8K of memory and T A8E cassette or TM8E magnetic tape drives.
MCPIP supports any OS/8 system device. Before running MCPIP,
the user must load the OS/8 cassette or magnetic tape handlers as
described in Getting On Line with OS/8 in Chapter 1.
Calling and Using MCPIP
To call MCPIP from the OS/8 system device, the user types:
R MCPI P

in response to the dot printe~ by the Keyboard M~mitor. The
Command Decoder then prints an asterisk at the left margin of the
terminal and waits to receive a line of I/O files and options.
MCPIP accepts one input file and performs output to a single output file. The contents of the input file are transferred to the output
file in image mode. In response to the asterisk, the user types an
I/O specification of the following form:
*outfile<infile/(options) = size
Each file specification consists of a device and an optional file
name (for file-structured devices). To perform I/O on a given cassette drive, the user's OS/8 system should be configured with an
OS/8 cassette handler for that drive.
.
The permanent device names for cassettes are CSAO-CSA7.
Magnetic tapes have the permanent device names MTAO-MTA7.
Permanent device names for other OS/8 devices are listed in the
Keyboard Monitor section of Chapter 1. These device names ate
used in the' I/O specification, along with any file name that is
2-110

necessary. For examp~e, to transfer a CAPS-8 file named
DATA01 to the disk, the user types:
*DSK:DATA01<CSAl:DATA01

if the standard cassette is mounted on drive 1 and. if the user's
OS/8 system has a handler for drives 9 and 1 (unit 0) with entry
point names of CSAO and CSA1. If a cassette handler is specified
without any file name, MCPIP uses the handler without modification, i.e., it uses the cassette as a non-file structured device
similar to a paper tape reader or punch. Thus, the command:

*CSA2:<DSK:SISCO.BN

would perform the same operation with MCPIP as the command:
*CSA2: < SI sco. aN II

would perform with OS/8 PIP.
If the user specifies a magnetic tape handler with a file name,
MCPIP considers the magnetic tape as a file-structured device and
assumes that it has the same format as a standard cassette.
Since MCPIP performs file transfers for all file types, there are
no assumed extensions assigned by MCPIP to file names for either
input or output files. All extensions, where present, must be explicitly specified, except when the /B option is used.
Following completion of a MCPIP operation, the Command
Decoder again prints an asterisk at the left margin and waits for
another MCPIP I/O specification line. The user can return to the
Keyboard Monitor by typing CTRL/C or by ending a Me::PIP
specification line with an ALTMODE.

MCPIP OPTIONS
The various options allowed on a MCPIP I/O specification line
are detailed in Table 2-22.
2-111

Table 2-22

MCPIPOptions.

Option

Meaning

Transfer files in special CAPS-8 binary format. If the / B
option is used and no extensions are specified, MCPIP assumes .BN for OS/8 files and .BIN· for cassette files .. If
input is from PTR: (high-speed paper tape reader), the
paper tape must be positioned on the leader.

[]

The square bracKet ([]) option allows the user to specify a
decimal file type on a cassette output file. The notation in
brackets does not refer to the file sizes in this case. Hence,
to create a file with the name CAS50.BI on cassette drive 1
and give it a file type of 3, the user types:
*CSAl:CA550.BIC3]<

For output files other than cassette, square brackets have
the same meaning as in OS/8 PIP. For information on file
types, see the Cassette Programming System User's Manual
(DEC-8E-OCASA-H-D), Appendix E.
/D

Delete the file specified from the output cassette or magnet:.; tape. The / D option is only valid if the output device
is a cassette or magnetic tape. For example:
*MTA1: OF'lLE< 10

will delete OFILE from the magnetic tape on drive 1.
=n

Specify in the low order 12 bits of n the number of words
(characters) per record which occur in the cassette or magnetic tape output file. The low order 12 bits of the n specification may be between 0 and 1000 (octal), inclusive.
If not specified, 200 is assumed.
The = option need not be specified for cassette or magnetic tape input files because MCPIP will determine the
record size from the file's header record. If the output
record size specified is greater than 1000 or if an input
record size is 0, MCPIP prints an error message since it
cannot handle variable-length records. The high order 11
bits of the = option are used to specify the version number for the file. The = option is ignored if the output file
is not a cassette or magnetic tape file.
2-112

Table 2-22

MCPIP Options (Cont.)

Option

Meaning

Read the input cassette or magnetic tape ~irectory and
write it onto the output file. Notice that in. this case the
input file itself is not transferred, only the directory. The
IL option applies only if the input device is a cassette or
magnetic tape.

If no filename is specified, zero the cassette or magnetic

tape on the drive specified as output, by writing a sentinel
file on it. Every magnetic tape or cassette should be zeroed
before it is used for the first time. If a filename is specified (for a cassette or magnetic tape drive), write a sentinel
file after the file specified.

Although cassette or magnetic tape file names may have 3charader extensions, OS/8 allows only 2-character extensions.
Thus, when looking up a cassette file, although all three characters
may be specified, only the first two are significant. For example,
CSAO:FILE.PAL might match a file called FILE.PAT. All files
on a standard cassette must be unique with respect to the file name
and the first two characters in the extension. On output, the third
character of the extension is always a space (unless the /B option
is specified).

NOTE
If CTRL/C is typed while a write operation
is in progress on a cassette or magnetic tape,
MCPIP writes an end-of-file before returning to the Keyboard Monitor.

MCPIP Error Messages
Error messages which appear while MCPIP is rum~ing are
shown in Table 2-23. If an output file is specified on a cassette or
magnetic tape and a file by that name already exists, the file on
the output drive is deleted before any transfer is performed. If
MCPIP detects an error while a cassette or magnetic tape output
. file is open, it tries to close the output file by writing a sentinel
file on the output cassette or magnetic tape.
2-113

Table 2~23

MCPIP Error Messages

Message

Meaning

CANNOT HANDLE VARIABLE
LENGTH RECORDS

The records on the input and
output files specified are not the
same size. MCPIP cannot handle variable length records.

CLOSE ERROR

MCPIP is not able to close the
file. A bad file just created on
magnetic tape or cassette must
be removed by placing a sentinel
'file after the preceding file. (See
the /Z option.)

device DOES NOT EXIST

The device specified does not
exist on the OS/8 system. "Device" is a set of four characters
given when "MCPIP expected an
OS/8 device name such as
DTAO.

ENTER ERROR

Error occurred while trying to
enter an output file. This message usually means that the cassette or magnetic tape has no
sentinel file.

FETCH ERROR

Error occurred while trying to
fetch an OS/8 device handler.

file NOT FOUND

The file specified cannot be
found. "File" is the actual name
of the file that was not found.

ILLEGAL * OR ?

Wild card * or ? was specified
in a MCPIP command line.
MCPIP does not accept the
wild card construction.

ILLEGAL SYNTAX

The command line to the Command Decoder contains an illegal character or was incorrectly
formatted.

INPUT ERROR

An input error occurred while
reading the file.

2-114

Table2-23

MCPIP ,Error Messages (Cont.)

Meaning

Message
NO INPUT FILE

No input file was specified
when one was required.

NO OUTPUT FILE

No output file was -specified
when one was required.

OUT-IN

Both· the input and the output
devices were specified as the
same cassette or magnetic tape
drive.

OUTPUT DEVICE FULL

Either room on device or room
in the directory is lacking.

OUTPUT ERROR

Output error-possibly a
WRITE LOCKed device, parity
error, or attempt to output to a
read-only device.

RECORD SIZE TOO BIG

The output record size specified
is greater than 1000 or an input
record size is O.

TOO MANY FILES

More than 1 output device was
specified or more than 1 input
device was specified.

2-115

PIPIO
PIPlO is an OS/8 utility program used to provide file compatability with the DECsystem-lO computer. PIPlO is capable
of transferring files to and from DECsystem-lO formatted DECtapes. PIPlO provides the facilities for transferring ASCII, Image
(PALlO binary output), and sequenced ASCII (LINED output)
files.
PIPlO uses an internal DECsystem-lO DECtape routine. This
routine optimizes file storage in the same way that the DECsystem10 Monitor does, thus resulting in the most efficient algorithm for
block storage.
PIPlO has the following features:
• Automatically determines which of the specified DECtapes
is a DECsystem-lO tape (384(10) words/blocks).
• Works interchangeably on TC08 and TD8E DECtape controllers.
• Reads and writes to DECsystem-lO tapes in both forward
and reverse directions on TC08 tapes, forward only on
TD8E.
• Keeps the DECsystem-lO DECtape directory in. core during
the file-copying operations of PIPlO, thus eliminating the necessity for rereading the directory. The directories are purged from
core when PIPlO reads another command line.
• Permits transfers between two OS/8 devices as well as transfers between two DECsystem-lO tapes.
• Zeroes DECsystem-lO DECtape directories, deletes DECsystem-lO files, and lists DECsystem-lO directories.
Note that PIPlO cannot be used while running the OS/8 BATCH
program.
Calling and Using PIPIO
To use PIPlO, type: .
• R PI P10

PIPlO responds with an asterisk (*) and waits to receive a command line of I/O files and options. The command line must have
one output specification and may have from zero to nine input
specifications. Multiple input files are merged onto the output file.
2-116

A DECsystem-lO file name may have a 0- to 3-character file extension; an OS/8 file name may have a 0- to 2-character extension.
Remember that PIP 10 automatically determines which DECtape
mounted is a DECsystem-lO tape. Thus no indication of that nature is necessary ..
Following completion of a PIPIO operation, the PIPIO command decoder again prints an asterisk at the left margin and waits
for another PIPIO I/O command line. To return to the Keyboard
Monitor, type CTRL/C.
NOTE
PIPIO uses its own command decoder, not
. the standard OS/8; however, the command
decoders are functionally the same.
PIPIO Options
The various options allowed on a PIPIO I/O command line are ..
detailed in the following table. The general format for PIP 10 command lines is the same as that for the standard OS/8 Comman~
Decoder.
Option

Meaning

Transfer files in DECsystem-lO binary mode. The output device must be a DECsystem-lO DECtape.

Delete the old copy of the output file before continuing
the transfer. If /D is not used, the file is copied before
the old copy is deleted.

List the short form of DECsystem-lO DECtape directory.

Copy in Image mode (compatible with PAL 10 binary
files) rather than ASCII mode.

List the directory of the inpu~ device. This input device
must be a DECsystem-:-lO DECtape. If no output device
is specified, TTY is assumed to be the output device.

Preserve LINED sequence numbers in DECsystem-lO
format. Sequence numbers are normally deleted.

Zero the output device directory. The output must be
a DECsystem-lO DECtape.
2-117

PIPIO Examples
The following examples assume that a DECsystem-10 DECtape
is mounted on DT A 7. In an actual operation, any unit may be used
since PIP 10 can access any of the tape drives.
Example 1:
*DTA7: FI LE. EXT< FI LE. EX /l

The command line in Example 1 zeroes the DECsystem-10
directory on DTA7 and transfers FILE. EX from DSK to the
DECsystem-10 DECtape on DTA7. If IZ is not specified, the
DECsystem-10 tape should always have a valid directory on it
Example 2:

In Example 2, five input files are merged onto 'one DEC system10 output file (FILE.EXT). The fi~st input file is an OSj8 file
(P 1) on DT AI; the second and third files are read from the paper
tape reader; the fourth is a DECsystem-lO file named P ARZ on
DT A7; and the fifth is from the terminal. This example shows that
input files need not be all OS/8 or an DECsystem-10.
Example 3:
*OTAl: FILE. BNC 10J<OTA7: rILE.BIN/I

The command line in Example 3 copies the DECsystem-10 file
(FILE.BIN) in Image mode since the DECsystem-10 file is a
binary file. II must be used to copy DECsystem-lO binaries. Note
the use of square brackets [] in the command; they have the same
meaning as in the OS/8 command decoder.
Example 4:
*01 A7: FI L E. EX1< 10

Example 4 indicates the deletion of a DECsystem-lO file
(FILE.EXT) from a device.
2-118

Example 5:
*DTA7: IL

If DTA 7 has a DECsystem-l 0 DECtape mounted, the command
line in Example 5 will produce a directory listing of the device.

Error Messages
All errors cause PIP 10 to abort the current command and print
another asterisk. The command can then be entered correctly.
Yessage

Meaning
D~Csystem-l 0

DEVICE FULL

ran out
of space on the output
file during a transfer.

ERROR DELETING FILE

The output file of a /D
command was not found,
or an error occurred
which deleted the file.

FILE NOT FOUND

The requested file was
not found on the specified device.

I/O ERROR

I/O device _error, e.g.,
parity, write lock, out -of
paper.

NO SUCH DEVICE

Device name used is not
legal in· this OS/8 system.

NOT OS8 FILE

The output device specified with a /L or IF option was not an OS/8 device or file.

NOT PDP-lO FILE

The output device specified with a /Z option was
not a DECsystem-lO
tape, or the input device
specified with a /L or /F
option was not a DECsystem-lO tape.
2-119

~essage

~eaning

OUTPUT FILE OPEN ERROR

The output file could not
be opened. Check output
directory to ensure that
enough space exists on
the device ..

PIPIO CANNOT BE CHAINED TO

Self-explanatory.

SYNTAX ERROR

Invalid PIPIO command
line.

2-120

RESOURCES (RESORC)
RESORC is an OS/8 programihatis used to determine the
device handlers present on a given OS/8 system. Other information about the handlers is available through the use of RESORC
options.
Calling and Using RESORC
To call RESORC from the system device, type:
R RESORC

in response to the dot printed by the Keyboard Monitor. RESORC
may also be called via the CCL command RES (see the CCL
section in Chapter 1). The Command Decoder prints an asterisk at
the left margin and waits to receive a line of I/O files and options.
RESORC accepts up to nine input files and performs output to a
single output file; options generally are placed at the end of a command string.
. The output specification is the device, and optionally the file
name -and extension, to which the RESORC listing is sent. TTY is
assumed if no output device is specified: If no file name is specified,
RE is assumed. If no file name extension is specified, .LS is assumed.
The input specification may be one of three types:
A. No input specification
If no input specification is entered, the OS/8 system device
is assumed.
B. A device name only (dev:)
If the input specification is a device name only, the device
must be file-structured and is presumed to contain a valid
OS/8 directory and Keyboard Monitor. The device handlers
built into the system on that device are the ones listed by
RESORC. These handlers are not available to the user
unless he bootst~aps onto the specified device (see the
BOOT program in this chapter).
C. A device and a file name (dev:file.ex)
If this type of input specification is used, the file must be
what is known as a system-head file. (Such files are created
by the /Y option in PIP and are copies of the system portions of devices.) If no file name .extension is specified, the
2-121

extension .SY is assumed. RESORC prints the· handlers in
the system that were saved on the specified file. System-head
files are 50 (decimal) blocks long.
RESORC Options
RES aRC has three operating modes which are specified by
options in the command line. These modes are:
Option Mode

IE
IF
IL

Extended mode-detailed handler information
Fast mode-1-line printout (default)
Limited m<Jde-3-column printout
FAST MODE (IF OPTION)
If the IF option is specified in a R~SORC command line", or
if no options are specified, RESORC prints the permanent device
names for handlers which exist on the system. If RES aRC cannot
determine the ASCII device name for one of the devices, it prints
the internal octal representation of the device name and encloses it
in parentheses. (This octal representation is included in the OSI8
Software Support Manual.) For ,example:
• R RESORC

*/F
SYS,DSK,DTA2,DTA0,DTA1,(4667),TTY,LPT

The first two devices are always SYS and DSK. When the fast
mode is used, the devices are separated by commas and listed in
order of their internal device numbers.
LIMITED MODE (lL OPTION)
If the IL option is used in a RESORC command line, the
handler information is printed in three columns. For example:
• R RESORC

*IL
128 FREE BL. OCK S
NAME TYPE USER
SYS RK8E
DSK
RK8E IN
DTA0 TCes 0
TTY
TTY
LPT LPTR LPT
05/8 V3F

2-122

Preceding the table of device names, RESORC prints the number of free blocks on the device. This information is not given for
system-head files since it is not available.
The first column (NAME) lists the permanent names of devices
on the system. The second column (TYPE) lists the physical type
of the handler. Each type of device is assigned a unique number by
OS/8. RESORC associates this number with a name as listed in
Table 2-24. Note that physically different devices which are simil~ in function have the same internal type code. For example,
line printers LP08, LS8E, and L645 have an internal code of 04.
The third column (USER) lists the name given to the device with
the Monitor ASSIGN command. If RESORC cannot determine the
name from the internal octal, it prints the octal code enclosed in
parentheses.
Table 2-24

RESORC Device Types

RESORC
Internal
Type Code
Name
00
01
02
03
04.
05
06
07
10
11

12
13
14
15
16
17
20
.21
22
23
24
27
30

TTY

PTR
PTP
CR8E
LPTR
RK.
RF08
RF08
RF08
RF08
DF32
DF32
DF32
DF32
TC08
LINC
TM8E
TD8E
BAT
RK8ENULL
TA8E
VR12

Explanation
Console terminal
Paper tape reader
Paper tape punch
Card reader
Line printer
RK8 disk
RF08 disk .(1 platter)
RF08 disk (2 platter)
RF08 disk (3 platter)
RF08 disk (4 platter)
DF32 disk (1 platter)
DF32 disk (2 platter)
DF32 disk (3 platter)
DF32 disk (4 platter)
TC08 DECtape
LINCtape
Magnetic tape
TD8E DECtape
Batch input handler
RK.8E disk
NULL handler
Cassette
PDP-12 scope

2-123

Codes 25-26 and 31-37 are reserved for future use by Digital.
Codes 40-57 are reserved for user handlers.
EXTENDED MODE (IE OPTION)
When the IE option is used in a command line, RESORC provides more detailed information about the handlers configured into
the system. The IE option produces a table with the following
headings.
Heading

NAME
TYPE
MODE

Meaning
Internal device number for the handler. If a number
is missing, there is no internal number for this
handler:.
Permanent device name for the handler. If RESORC
cannot determine the name, it prints the internal·
coding.
Type of device as listed in Table 2-24.
One or more of the following three letters:
R The handler may be used for reading.
W The handler may be used for writing.
F The handler controls file-structured devices.

SIZ

BLK

KIND

The size of the device in decimal OS/8 blocks. This
is only applicable for file-structured devices.
The block on the system device in which this handler
resides. If this number is followed by a +, this
indicates that the handler is two pages long. If this
entry is SYS, the handler is permanently resident in
core location 07600.
This entry tries to differentiate the handler more
specifically than the TYPE column. Since several
devices of the same type have the same device code,
there may be several handlers for the same device. If
the device type has only one handler, this entry may
be blank. The KIND specification has no meaning for
user-written handlers. Table 2-25 details the kinds of
handlers that may be on the system.
2-124

Table 2-25

Kinds of Handlers

Kind

Type

Description

AS33
KL8E
KS33
PT8E
KS33
PT8E
026
029
LP08
LS8E
LV8E

TTY
TTY
PTR
PTR
PTP
CR8E
CR8E
LPTR
LPTR
LPTR

by number of pages
by number of pages
by lOT codes
by lOT codes
by lOT codes
by lOT codes
by table codes
by table codes
location dependent
location dependent
location dependent

LV8E

LPTR

L645

LPTR

I-page handler
2-pagehandler
low-speed reader
high-speed reader
low-speed punch
high-spee<,l punch
DEC-026 card codes
DEC-029 card codes
old LP08 handler
old LS8E handler
LP08J LS8E/LV8E
handler
LPSV altered for
LV8E
Anelex line printer

AO
BO
Al
BI
A2
B2
A3
B3

PTP

2-125

How Identified

location dependent
location dependent

I
I
2
2
3
3

ENT
USER

Version number (letter) of handler. No entry means
the handler predates OS/8 Version 3. Version numbers are of the form A-Z. The 6-bit of the ASCII
representation of the handler version letter resides
in the handler's entry point location. For example, a
handler with a version of A has a representation of
01. (See Appendix A for a list 'of the 6-bit octal
codes.)
The relative entry point of the handler.
Same as for /L option. Current user name for the
handler as assigned by the Monitor ASSIGN command.

In addition to the preceding, the iE option also provides the.
following information. If a device was specified, as opposed to a
system-head file, RESORC prints: ,
• number of files in directory
• number of blocks used
• number of segments used
• number of free blocks
• number of empties
• number of additional information words
RESORC also lists the following:
• number of free device slots
• number of free block slots
• version number of Monitor if device is a system device
• R RESORC

*/E
164 FILES IN 1025 BLOCKS USING 6 SEGMENTS
2167 FREE 8L OCK S (14 EMPTI ES)

,
NAME TYPE
01 SYS
RKSE
02 OSK ,RKSE
03 OTA0 TOSE
04 OTAI TOSE
05 RKB0 RKSE
06 TTY . TTY
II

MODE SI Z
RWF 324S
RWF 324S
RWF 737
RWF 737
RWF 3248
RW

8LK KIND
SYS
SYS
16+ TOSA
16+ TOSA
SYS
17+ KL8E

2-126

U
0
0
0
1
1

\J ENT USER
8
07
07
B
A
10
14
A
8
21
C 176

01 PTP PTP W
10 PTR· PTR
R
11 LPT
LPTR W
FREE DEVI CE SLOTS:
0518 V3F

20
20
21

06#

PT8E
PT8E
LPSV

A 00
A 112
8
03

FREE BLOCK SL OTS:

RESORC Error ~essages
The following messages may appear during a RESORC opera-"
tion.
Table 2-26

RESORC Error Messages

Message
?BAD DIRECTORY
% BAD MONITOR
% DEV IS NOT FILE
STRUCTURED
?INPUT ERROR
%NON SYSTEM DEVICE
%NOT A SYSTEM HEAD
?OUTPUT DEVICE FULL
?OUTPUT DEVICE IS
READ ONLY
?OUTPUT ERROR
?TTY DOES NOT EXIST

Meaning
Input device directory cannot be read.
The input device may be a system device but the Monitor cannot be accessed.
The input device specified is not a filestructured device, e.g., PTR.
An input error occurred during a
RESORC operation.
The input device specified in a RESORC command line is not an OS/8
system device.
The file name specified is not a systemhead file.
The output device specified does not
have enough room to copy the RESORC file.
The output device specified is a readonly device, e.g., PTR.
An error occurred while attempting to
output during a RESORC operation.
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 this chapter for instructions on inserting TTY handlers.

2-127

SRCCOM
SRCCOM is an OS/8 utility program which compares two source
files line by line and prints all their differences. Usually, the two
files are different versions of a single program, in which case
SRCCOM prints all the editing changes which transpired between
the two versions, making it a useful debugging tool.
SRCCOM Assembly Instructions
To make SRCCOM.BN from SRCCOM.PA, type
.R PAL8
*dev:SRCCOM (,dev:SRCCOM.LS) ~dev:SRCCOM
The listing file shown in parentheses is optional.
To make SRCCOM.SV from SRCCOM.BN; type
.R ABSLDR
*dev:SRCCOM$
.SA dev SRCCOM
To load and save the binary papertape (DEC-S8-0SYSA-<-PB19)
.RABSLDR
*PTR:$t
(Type and character in response to t)
.SAVE dev SRCCOM
Loading SRCCOM
To use SRCCOM, type
• R SRCCOM

*OUTPUT<INPUTl#INPUT2

INPUT 1 and INPUT2 are the source files to be compared and the
input devices. Both files must be specified and be non-empty. If an
input device is omitted, it is assumed to be DSK.
OUTPUT specifies the output file and device where the differences
will be listed. If an output file name is specified, the default output
device is DSK. If the output device is non-file structured, a file na'me
is unnecessary. If output is to a file-structured device, an output
file name must be specified. If no output specification exists, TTY
is assumed.
The following tun-time options are accepted by SRCCOM:
2-128

Table 2-27

Run-TIme Options .

Option

Meaning

IC
IS

Do not count differing comment fields as a difference.
Do not compare tabs and spaces when considering lines
different.
Convert tab.s to spaces on output.
Count blank lines in the comparison. A blank line is con-

considered as a carriage return 011ly. In particular space
carriage return combination under jSjB is not treated
as a blank line.
Like Ie, but does not print comment fields on the out-

put file.

Examples:
• R SRCC(Xvl
*OSK: 01 FF1L<OTAl: ORI G" OTA2: COPY.

Compare the source files ORIG on DTA1 and COpy on DTA2,.
and store the differences on DSK as DIFFIL .
• R SRCCOM
*01 FFIL<FI RST" SEC(ND

Compare the source files FIRST and SECOND on DSK, and output the ditXerences to DIFFIL on DSK .
• R SRCCCM
*LPT:<DTAl:FILEl"PTR:
t

Compare source files FILE 1 on DTA 1 and one from the highspeed paper tape reader, and output the differences to the line
printer.
SRCCOM Output
The first line of output printed by SRCCOM is "SRCCOM Vx,
where x is the current version number, then two header lines followed by as many difference groups as necessary. The header lines
are printed as follows:

file 1)
file 2)

header line of file 1
header line of file 2
2-129

A difference group has the form:
1) Innn line 1, file 1
1)
line 2, file 1
1)
line 3, file 1
1)

line n, file 1

****
2) Innn line 1, file 2

line 2, file 2

2)
line m, file 2
where nnn is the number of the difIerencegroup and lines 1
through n-l of file 1 and 1 through m-l of file 2 did not agree.
SRCCOM compares areas of the two programs, and prints differences until it finds 3 lines which agree. The last lines printed (line
n of file 1 and line m of file 2) are the first lines that agreed. The
number of consecutive lines to check for agreement may be changed
to any number (k) with the option ==k in the command line.
Example:
File 1
File 2
SRCCOM OUTPUT
A
J""l.

file 1)
file 2)
1) B
1) C

A
A

A
X

C
D

E
G

2)
2)

********

F
G
H
I

****
X

F
G
H
I

1)
1)

****

2)
2)
2)
2-130

H
J

Occasionally a· decimal number appears following the close parenthesis after the file number. This decimal number indicates the
source page in this file from which this line and all following lines
(until the next such number) come.
If the two files are identical, SRCCOM prints the message:
NO DIFFERENCES
in the output file.

Error Messages
SRCCOM error messages are of the form:

?n
where, n is a single digit. The meaning of the various digits are
?O

Insufficient core; this means that the differences between the files are too large to allow for effective comparison. Use of the IX option may alleviate this
problem.

Input error on file # 1 or less than 2 input files specified.

Input error on file # 2.

. Output file too large for output device.

Output error.

Could not create output file.

2-131

TECO

Introduction
OS/8 TECO is a powerful text editing and correcting program
that runs under the OS/8 operating system. OS/8 TECO may be
used to edit any form of ASCII text such as program listings, manuscripts, correspondence and the like. Since OS/8 TECO is a
character-oriented editor rather than a line editor, text edited with
OS/8 TECO does not have line numbers associated with it, nor
is it necessary to replace an entire line of text in order to change
one character.
Because 05/8 TECO is very versatile, it is necessarily complex. This chapter is, therefore, divided into two parts. The first
part contains basic information and introduces enough OS/8
TECO commands to allow the novice OS/8 TECO user to begin
creating and editing text files after only a few hours of instruction.
The introductory commands are sufficient for any editing application; however, they are less convenient, in most cases, than the advanced commands presented later.
The second part introduces the full OS/8 TECO command set,
including a review of the introductory commands presented earlier.
This part also introduces the concept of OS/8 TECO as a programming language and explains how basic editing commands may
be combined into editing "programs" which are, sophisticated
enough to handle the most complicated editing tasks.
Specific examples of the use of OS/8 TEeO commands have
been de-emphasized throughout this manual. This was done because all of the OS/8 TECO commands have a consistent, logical
format which will quickly become apparent to the novice user.
However, each section of the chapter is concluded with one or
more elaborate examples which employ most of the comman~s
introduced up to that point. Users who are learning the TECO
commands should experiment with each command as it is introduced, then duplicate the examples on their computer. Hereafter,
OS/8 TECO will be referred to as simply TECO.

Introductory Commands
TECO considers text to be any string of ASCII· codes. Text
is broken down into units of pages, lines and characters. A page
of text consists of all the ASCII codes between two form feed

2-132

characters, including the second fonn feed. A line of text consists
of all the ASCII codes between two line feeds, including the second
line feed. A character is one ASCII code. Thus, every page of text
contains one fonn feed character, which is the last character on
the page. Every line of text contains one line feed, which is the
last character on the line.
- TECa maintalnsa text buffer in which text is stored. The buffer
usually contains one page of text consisting of up to 4000 characters, but the tenninating form feed character never appears in the
buffer. TEca also maintains a buffer pointer. The pointer is simply a movable position indicator which is always located between
two characters in the buffer, before the first character in the buffer,
or after the last character. The pointer is never located on a character.
Line feed and fonn feed characters are inserted automatically by
TECa. A line feed is automatically appended to every carriage
return entered into the buffer, and a fonn feed is appended to the
content of the buffer by certain output commands. Additional
line feed and fonn feed characters may be, entered into the
buffer as text. If a fonn feed character is entered into the buffer,
it will cause a page break upon output. That is, all text preceding
the fonn feed will appear on one page, and the text following the
form feed will appear on the next page.
Finally, TECa also maintains an input -file and an output file,
both of which are selected by the user through use of file specification commands. The input file is any device except the keyboard
~om which text may be accepted. For example, if a block of text
is stored oli paper tape, the paper tape reader would be specified as
an input device when the tape is edited.
The output file is any device except the user terminal on which
edited text may be written. If the paper tape file mentioned above
were to be edited and written onto DECtape, for example, the output file would be a user-named DECtape file (with optional file extion) on a specified DECtape transport unit.
If TECa resides on the system device it may be called from the
keyboard by typing:
R TEea
(teI1l1inated with a carriage return) in response to the dot gener~ted by the as/8 monitor. TECa will respond by printing an'asterisk at the left margin to indicate that it is ready to accept User _
2-133

commands. At this point, one or more commands may be typed
at the keyboard, and TECO will execute the commands upon receipt of two consecutive ALT MODE characters. The ALT MODE
is a non-printing character which may be labelled ESCAPE on
some keyboards. TECO echoes a dollar sign ($) whenever an ALT
MODE is received.
A TECO command consists of one or two characters which
cause a specific operation to be performed. Some TECO commands may be preceded or followed by arguments. Arguments may
be either numeric or textual. A numeric argument is simply an integer value which might be used to indicate such things as the
number of times a command should be executed. A text argument
is a string of ASCII characters which might be words of text, for
example, or the OS/8 designation of a storage file.
If a command requires a numeric argument, the numeric argu-

ment always precedes the command. It a command requires a text
argument, the text argument always follows the command. All
text arguments are terminated by a special character (usually an
ALT MODE) which indicates to TECO that the next character
typed will be the first character of a new command.
If more than one command is typed in response to the asterisk
generated by TECO, the command string will be executed from
left to right until either all commands have been executed or a
command error is rec·ognized. When an error is encountered, a
message is printed and the rest of the command string is ignored.
In any case, TECO prints another asterisk at the left mar-gin as
soon as it finishes execution of a cominand string, so that additional commands may be entered.
The extensive text editing capability of TECO implies a large"
and versatile" command set. However, the novice TECO user will
find that little more than a dozen basic commands suffice for most
editing requirements. The following section introduces the basic
TECO commands. The full command set will be described later in
this chapter.
TECO will accept input text from any input device in the OS/8.
system. If input is supplied from any device except the keyboard,
the input device must be specified by means of an ER command
terminated by an ALT MODE. If the input device is a file-structured device such as disk or DECtape, the file name and extension
2-134

(if any) should also be supplied. If a file name is specified but no

device is explicity defined, the OSj8 default device is assumed. The
ER command causes TECQ to search for the specified file and print
an error message if the file is not found. This command does not
cause any portion of the file to be read into the text buffer, however. The following examples illustrate use of the ER command.
Command

Function

ERdev:filnam.ex$

General form of the ER command where "dev:
. filnam.ex" is the 08/8 designation of the input
file. The command is terminated by an ALT
MODE, which echo~s as a dollar sign.

ERPTR: $

Prepare to read an input file from the reader.

ERPROG.PA$

Prepare to read input file PROG.PA from the
OS/8 default device DSK.

EI.UJTAI :PROG$

Prepare to read input
file PROG from DTAI.
.

TECO will write output text onto any device in the OSj8 system. If output is written onto' any device except the user terminal,
the output device must be specified by means of an EW command
terminated by an ALT MODE. If the output device is a file-structured device, a file name and extension (if any) must also be supplied. If a file name is specified but no device is explicitly defined,
,the OSj8 default device is assumed. The following examples illustrate use of the EW command, which has the same format as the
ERcommand.
Function

Command
EWdev:filnam.ex$

General form of the EW command where "dev:
filnam.ex" is the OSl.8 designation of the output
file. The command is terminated by an ALT
MODE, which echoes as a dollar sign.

EWSYS:<TEXT.LS$ Prepare to write output file TEXT.LS on the
system device.
EWDSK: PROG$
EWTEXT.AS$

Prepare to write output file PROG on the OS/8
default device DSK.
Prepare to write output file TEXT.AS on the
OS/8 default device DSK.

It is not always necessary to specify an input file. If the -user de-

sires to create a file without using any previously edited text as
2-135

input, he may insert the necessary text directly into the text buffer
from the keyboard and, at the end of each page, write the content
of the buffer onto an output file. Since all input is .supplied from
the keyboard, no input file is necessary.
An output file is unnecessary if the user desires only to examine
an input file, without making permanent changes or corrections.
In this case, the content of the input file may be read into the text
buffer page by page and examined at the terminal. Since all output
is printed on the user terminal, no output file is needed.
TEeO will only keep one input file and one output file open at a
time. The current input file may be changed by simply using the
ER command to specify a new input file. Before an output file may
be changed, it is essential that the current output file be closed by
means of an EF command (or one of the other file closing commands presented later). If this is not done, the content of the file
may be lost. The EF command is presented below, along with several examples of file specification command strings.
EF
Close the current output file. If the last EW command specified
a directory device file which already existed on the device (so that
TECO created a second file with the same file name and extension), the old version of the file is deleted at this time.
ERDTAI :INPUT.TX$EWDTA2:0UTPUT.TX$$
Open an input file "INPUT.TX" to be found on DECtape unit 1
and an output file "OUTPUT.TX" on DECtape unit 2. If the file
OUTPUT.TX does not already exist, it will be created. The double
ALT'MODE ($$) terminates the command string and causes the
string to be executed.
EFEWTEXT.AS$$
Close the current output file and open an output file "TEXT .AS"
on the OS/8 default device. Note that the ALT MODE which terminates the EW command may be one of the two ALT MODEs
which terminate the command string.
ERPTR:$EFEWSYS:FILE$$
Read the input file from the high-speed paper tape reader, then
close the current output file and open "FJLE" on the system device
as an output file.

The following commands permit pages of text to be read into
the TEeO text buffer from an input device or written from the buffer
2-136

onto an output device. Once a page of text has been written onto
the output file, it cannot be recalled into the text buffer unless the
output file is closed and then opened as an input file.
Command

Function

Clear the text buffer, then read the next page of the input
file into the buffer.

Write the content of the text buffer onto the next page of
the output file, then clear the buffer and read the next page
of the input file into the buffer.

Execute the P command n times, where n must be an integer inthe range O~n~4095. If n is not specified, a value
of 1 is assumed.

The buffer pointer provides the only means of specifying the location within a block of text at which insertions, deletions or corrections are to be made. The following commands permit the buffer
pointer to be moved to a position between any two adjacent characters in the buffer. TECO positions the pointer before the first
character in the buffer after every Y or P command.
Command

Function

Move the pointer forward to a position between the next
line feed and the first character on the next line. That is,
advance the pointer to the beginning of the next line.

Execute the L command n times, where n may be any
integer. A positive value of n moves the pointer to the
beginning of the nth line following the current pointer position. A negative value moves the pointer backward n lines .
and positions it at the beginning of the nth line preceding
the current position. If n is zero, the pointer is moved back
to the beginning of the line on which it is currently positioned.

Advance the pointer forward across one character.

Execute the Ccommand n times, where n must be an integer in the range -2048~n~2047. A positive value of n
moves the pointer forward across n characters (carriage
return/ line feed counts two characters). A negative value
of n moves the pointer backward across n characters. If n
is zero, the pointer position is not changed.

These commands may be used to move the buffer pointer across
any number of lines or characters in either directions, however they
2-137

will not move the pointer across a page boundary. If a C command attempts to move the pointer backward beyond the beginning of the buffer or forward past the end of the buffer, an error
message is printed and the command is ignored.
If an L command attempts to exceed the page boundaries in this
manner, the pointer is positioned at the boundary which would
have been exceeded. Thus, the command "-2000L" would position
the pointer before the first character in the buffer. The command
"2000L" would position the pointer after the last character in the
buffer. No error message is printed in either case.
The following commands permit portions of the text in the buffer
to be printed out for examination. These commands do not move
the buffer pointer:
Command

Function

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

Execute the T command n times, where n must be an integer in the range -2048:::;;n:::;;2047. A positive value of n
causes the n lines following the pointer to be typed. A negative value of n causes the n lines preceding the pointer to
be 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. This facilitates locating the buffer
po"inter.

Type the entire content of the text buffer.

The OT command is particularly useful for determining the position of the buffer pointer. This command should be used frequently to determine that the pointer is actually located where the
user expects it to be.
The following commands permit the user to insert or delete text
from the buffer.
Command
Itext$

Function
Where "text" is a string of ASCII characters terminated by
an ALT MODE, which echoes as a dollar sign. The specified text is inserted into the buffer at the current position
of the pointer, with the pointer positioned iJ:I?mediatelyafter
the last character of the insertion. Insertion commands
should be limited to a maximum length of 10 to 15 lines. "

2-138

Command
K

HK
D
nD

Function
Delete the content of the text buffer from the current position of the pointer through and including . the next line feed
character.
Execute the K c01l1mand n times, where n may be any integer. A positive value of n causes the n lines following the
pointer to be deleted. A negative value of n causes the n
lines preceding the pointer to be 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.
Delete the entire content of the text buffer.
Delete the character following the buffer pointer.
Execute the D command n times, where n may be any
integer. A positive value of n causes the n characters following the pointer to be deleted. A negative value of n
causes the n characters preceding the pointer to be deleted.
If n. is zero, the command is ignored.

Like the L command, D and K commands may not execute
across page boundaries. If any D or K command attempts to delete
text up to and across the beginning or end of the buffer, text will
be deleted only up to the buffer boundary and the pointer will be
positioned at the boundary. No error message is printed.
The following commands may be used to search for a specified
string of characters which may occur somewhere in the input file.
They cause the buffer pointer to be positioned immediately after
the last character in the specified string, if it is found.
COl1)mand
Stext$

N text$

Function
Where "text" is a string of from 1 to 31 ASCII characters
terminated with an ALT MODE, which echoes as a dollar
sign. This command searches the text buffer for the next
occurrence of the specified character string following the
current pointer position. If the string is found, the pointer
is positioned after the last character in the string. If it is
not found, the pointer is positioneq immediately before the
first character in the buffer and an error message is printed.
Performs the same function as the S command except that
the search is continued across page boundaries, if necessary, until the character string is found or the end of the
input file is reached. If the end of the input file is reached,
an error message is printed and it is necessary to close the
output file and reopen it as an input file before any further
editing commands may be executed.

2-139

Both the S command and the N command begin searching for
the specified character string at the current position of the pointer.
Therefore, neither command will locate any occurrence of the character string which precedes the current pointer position, nor will it'
'; locate any character string which continues across a page bound<
ary.
Both commands execute the search by attempting to match the
command argument character for character with some portion of
the buffer .contents. If an N cqmmand reaches the end of the buffer
without finding a match for its text argument, it writes the content
of the buffer onto the output file, clears the buffer, reads the next
page of the input file into the buffer, and continues the search.
At this point, all of the basic TEeo commands have been
introduced. Recall that TEeO indicates it is ready to accept user
commands by printing an asterisk (*). Once TEeO has printed an
asterisk, one or more commands may be typed at the terminal. Errors may be corrected by typing the RUB OUT key to delete characters. Each depression of the RUB OUT key deletes one cliaracter, beginning with the last character typed, and then prints the
deleted character at the terminal. An entire command string may
be deleted in this manner, if necessary. Once the correct command(s) have been entered, typing a double ALT MODE ($$)
causes TEeO to execute the command(s) in the order they were
entered, and print another asterisk so that additional commands
maybe typed.
/
If TEeO encounters an erroneous command, it prints an error
message and ignores the erroneous command as well as all commands which follow it. All error messages are of the form:
?n
where n is a number which references the list of error codes that
appears at the end of this chapter. Every error message is followed by an asterisk -at the left margin, indic~ting that TEeO is ready to
accept additional commands. If the first command entered after a
TEeO-generated error message is a single question mark character
(?), TEeO will print the erroneous command string up to and
including the character which caused the error message. This facilitates locating errors in long command strings and determining how
much of a command string was executed before the error was encountered.
2-140

•

..
At the conclusion of an editing job, users may type control-C to
exit TECO and return to the keyboard. Control-C may be typed
at any time during an editing run; it will cause an immediate exit
to the monitor as soon as it is' recognized by TECO. Control-C
should not be typed while any output file is open.
The following example illustrates how TECO may be used to
create an OS/8 FORTRAN program for immediate execution. The
same procedure may be employed to create and execute programs
under PAL8, SABR, and on so.
T-4:
• R TECO

* EvJATEST. I'T $$
*1
1

WRITEel .. l>
I'ORMAT< '
COMPI L ER TEST' >
RJ=3
RK=7

User calls TECO, specifies output file, and creX=.5
ates FORTRAN source
RI 1= RK IRJ* e 2- RK* RK 1 < 3. * RJ> ) program.

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<F10.2 .. I'12.S>
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

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

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

<I>text$ Where <I> 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<n<4095), the -1 is interpreted as a positive 4095. If the next

2-152

sequential command does not require an argument, it is excuted as
it stands. The following examples illustrate use of the colon modifier.
COMMANDS:

:Stext$
:nStext$
:Ntext$
:nNtext$
: ~text$
:n~text$

:FStextl $text2$
: nFStextl $text2$
:FNtext 1$text2$
:nFNtext1$text2$
FUNCTION:

In each case, execute the search command. If the
search is successful, execute the next sequential
command with an argument of -1 (or 4095, if it
is a command which must have a positive argument). If the search fails, execute the next command with an argument of zero. If the next command does not require a numeric argument, execute
it as it stands.

The @ character is another search command modifier. Inserting
an @ character between the numeric argument· of any search command and the command itself causes TEeO to accept the first character following the command as a delimiting character which will
will also be the command terminator. This character may be any
character which does not appear in the search command argument,
except for the special characters. When the @ command modifier
is used, search command arguments may contain ALT MODE
characters, as long as they do not contain two consecutive ALT
MODEs. The following examples illustrate use of the @ command
modifier.
COMMANDS:

@SJtextl
n@S/text!
@NJtext!
n@N/text!
@ ~Jtext!

. n@~/textl
@FS/ text 1I text21
n@FS/ text 1I text21
, @FN/ textl I text21
n@FNJtextl/text2/

2-153

FUNCTION:

In each case, execute the search command with
text string "text" as an argument. This argument
must be preceded and followed by a delimiting
character which does not appear in the argument
(a slash is shown here). The search command argument may contain ALT MODE characters, as long
as it does not contain two consecutive ALT
MODEs.

Match Control Characters
TECO executes a search command by attempting to match the
search command argument character-for-character with some portion of the input file.
There are four special control characters that may be used in
search command arguments. These characters alter the usual
matching process that occurs when a search is executed. TEeO
considers match control characters to be single characters (they
echo as two characters) and counts them as one of the maximum
31 characters in the search command argument. Table 2-36 lists the·
match control characters and their functions.
Table 2·36

Match Control Characters

Character

Function

CTRLI X

A CTRLI X character indicates that this position in the
character string is unimportant: TECO accepts every
other character as a match for control-X.
A CTR LI S character indicates that any separator character is acceptable in this position. TECO accepts any
character that is not a letter (upper or lower case A to
Z) or a digit (0 to 9) as a match for CTRLI S.
The CTRLI N character and the character following it
are treated as a single character in the" search command
argument, but counted as 2 of the maximum 31 characters. TECO accepts any character as a match for the
, control-NI character combination EXCEPT the character
which follows the CTRLI N. The combination CTRLI N I
CTRLI S is legal; TECD accepts any character which is
not a separator as a match for tNtS.
A CTRLI Q character in a search command argument
indicates that the character following the CTRLI Q is to
be interpreted literally rather than as a command. This
character may be used to search for tX,tN, and tS characters. It does not count as one of the maximum 31
characters in the search command argument.

CTRLI S

CTRLI N

CTRLI Q

2-154

As with all other control characters entered into text arguments,
match control characters must be typed by holding the CONTROL
key depressed while striking the character key. The uparrow construction may not be used.
Command Loops

The user may cause a command string to be executed any number of times by placing the command string within angle brackets
and preceding the brackets with a numeric argument which designates the number of iterations. Iterated command strings are
called command loops. Loops may be nested in such a way that
one command loop contains another command loop which, in
tum, .contains other command loops, and so on. Command loops
should not be nested to more than about 15 levels.
The general form of a command loop is:
n<command string>
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

Function

tUqstring$

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.

@tU/stringi

nUq

n%q$

n% $

nXq

m,nXq

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:
m<stringln;string2>string3
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<n <2047. If n falls outside this range, the nj command
2-159

is ignored and "striRg2'~;':is executed-next. The semicolon may be >:
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<n<4095, since 4095
is the largest. number which may be stored in one 12-bit word.
Commands which may have positive or negative arguments require
an argument in the range -2048<n<2047, because -2048 is the
smallest number which may be stored in 12 bits using 2's complement notation, while 2047 is the largest number which may be
stored in this manner.
TECO maintains several internal counters which record conditions within the text buffer. Each of the counters has a onecharacter name which is equivalent to the current contents of the
counter. These characters may be entered as numeric arguments to
TECO commands. When the command is executed, the current
value of the designated counter is substituted for the character and
used in the numeric argument of the command .

....

2-160

Some of the characters which stand for specific values associated
with the text buffer have been introduced earlier in this section.
For example, the dot character (.), which references a counter that
always contains t.he number of characters between the beginning
of the buffer and the current pointer position, may be used in the
argument of a T command. The command ". , .+5T" causes the
5 characters following the buffer pointer to be typed out. When
this command is executed, the number of characters preceding the
buffer pointer Js substituted (twice) for the character "dot." The
addition is then carried out, and the command is executed as
though it were of the form "m,nT".
Table 2-40 lists all of the characters which have special
numeric values. Any of these characters may be used as numeric
arguments in place of the values they represent.

Table 2-40

Character

Characters Associated with Numeric Quantities
Function

Always equivalent to zero. Thus, B represents the position
at the beginning of the buffer, preceding the first character
in the buffer.

Equivalent to the number of characters currently contained in the buffer. Thus, Z represents the position at the
end of the buffer, following the last character in the buffer.
Equivalent to the number of characters between the beginning of the buffer and the current position of the
pointer, thus represents the current position of the pointer.

Equivalent to the numeric argument pair, "B,Z", or "from
the beginning of the buffer up to the end of the buffer."
Thus, H represents the whole buffer.

CTRL/,Z (or uparrow/Z) is equivalent to the number of
characters presently stored in the entire Q-register storage
area, including storage requirements for the command string
. containing the tZ character. Maximum capacity of the
Q-register storage area is 2000 characters on an 8K system, or 2944 characters on a 12K system.

Where n is a positive integer. Equivalent to the ASCII code
for the n+ 1th character following the current position of
the pointer.

2-161

Table 2-40
Character

Characters Associated with Numeric Quantities (Cont.)
Function

CTRL/E (or uparrow/E) is equivalent to 4095 (-1) if
the buffer currently contains a full page of text (which was
terminated by a form feed in the input file) or 0 if the
buffer contains only part of a page of text (which filledthe buffer to capacity before the terminating form feed
was read). The tE flag is tested by N, EC and EX commands to determine whether a form feed should be appended to the content of the buffer on output.

CTRLIF (or uparrow/F) is equivalent to the current
value of the console switch register.

ttX

The combination of CTRL-shift-N (or a doubie uparrow)
followed by any character is equivalent to the value of the
ASCII code for the character. The "X" in· this example
may be any character except CTRL/ C and CTRL/ P.
A backslash (shift-L) character which is not preceded by
a numeric argument is equivalent to the value of the digit
string (if any) that begins with the character immediately
following the buffer pointer and is terminated by the next
character that is not a digit. The first character may be a
digit or one of the characters + or -. As each backslash
is evaluated, TECO moves the buffer pointer to a position
immediately following the digit string. If there is no digit
string following the pointer, the backslash is equivalent
to zero and the pointer position remains unchanged.

CTRLI T (or uparrow I T) is equivalent to the ASCII code

for the next character typed at the terminal. CTRL/ T
(or uparrow / T) may be entered in the numeric argument
of any command. When TECO executes a command string,
every tT character encountered causes it to pause and
accept one character typed at the terminal. The ASCII
code for this character is then substituted for the tT.
tV

CTRL/V (or uparrow/V) is equivalent to the version number of the version of TECO which is currently being run.
This manual describes TECO version 3.

CTRL/H (or uparrow/H) is equivalent to zero.

The Mq command (execute the content of the text storage
area of Q-register "q" as a command string) may return
a numeric value if the last command in the string returns
a numeric value and is not followed by an ALT MODE.

2-162

The numeric -argument of a TECO command may consist of a
single integer, ·any of the characters listed in Table 2-40, or an
arithmetic combination of integers and the characters listed in
Table 2-40. If an arithmetic expression is supplied as a numeric
argument, TECO will evaluate the expression. All arithmetic expressions are evaluated from left to right. Parentheses may be used
to override the normal order of evaluating an expression. If par.entheses are used, all operations within the parentheses are per..;
formed, from left to right, before performing operations outside
-the parentheses. Parentheses may be nested, in which case the
innermost expression contained by parentheses will be evaluated'
first. Table 2-41 lists all of the arithmetic operators that may be
used in arithmetic expressions. All arithmetic is two's complement
arithmetic modulo 4096.
Table 2-41

Operator

Example

+2=2

Arithmetic Operators

Function
Ignore~ if used before the first term in an

expressIon.
5+6=11

Addition, if used between terms.

-2=4094

Negation, if used before the first term in an
expression.

8-2=6

. Subtraction, if used between terms.

8*2=16

Multiplication. Used between terms.

8/3=2

Integer divide and drop the remainder. Used
between terms.

12&10~8

Bitwise logical AND of the binary representation of the two terms. Used between
terms.

12# 10=14

Bitwise logical OR of the binary representation of two terms. Used between terms.

Table 2-42 lists three .commands which may be used to facilitate
entering' arithmetic expressions into TECO command strings.
2-163

Table 2-42

Command

Radix Control Commands

Function

Where n is an arithmetic expression which may contain
the operators listed in Table 2-12B. Upon execution,
this command causes the value of. the expression to be
typed out at the terminal.

CTRL/O

The CTRL/O command causes all subsequent numeric
input to be accepted as octal numbers and all subsequent numeric output to be transmitted in octal. This
command must not be typed while TECO is executing
a T command. The octal radix will continue to be used
until the next CTRLI D command is executed or a
command error is encountered. All error. messages are
printed as decimal numbers, and the decimal radix remains set after any error message is printed.

CTRL/D

The CTRLI D command causes all subsequent numeric
input to be accepted as decimal numbers and all subsequent numeric output to be transmitted in decimal.
This is the initial setting.

n"'-

Where n is any arithmetic expression. The backslash
command (preceded by an expression) inserts the value
of n into the text buffer at the current position of the
pointer, leaving the pointer positioned after the last
digit of the insertion. The octal value of n will be inserted if the octal radix is set.

Some TECO commands generate numeric arguments which they
pass on to subsequent commands. An example is any colon-modified search command, which causes the next sequential command
to be executed with an argument of -lor 0, depending upon the
outcome of the search. Commands of this sort are very useful, but
occasionally it may be undesirable to have arguments passed in
this manner. A single ALT'MODE character may be inserted between any two commands in a command string, as long as it is not
placed adjacent to another ALTMODE character. This ALTMODE has no effect on the individual commands, however a
numeric argument will never be passed across the extraneous ALT MODE.
Programming Aids
The characters carriage return, line feed, vertical tab and space
are ignored in command strings, except. when they appear as part
2-164

of a text argument. These characters may be inserted between any
two TECO commands to lend clarity to a long command string.
The carriage return/line feed combination is particularly useful
for typing command strings which are too long to fit on a single
line.
One of the most powerful features of TECO is its abil!!y to store
very long command strings so that a given sequence of commands
may be executed whenever needed. Long command ~~rings may be
thought of as edited programs and, like any other type of program, they should be documented by. means of comments.
Comments may be inserted between any two commands by
using a tag construction of the form:
!THIS IS A COMMENT!
Comments may contain any number of characters and any characters except the special characters. It is often convenient to include carriage return and line feed characters within the com~
ments so that the command string looks like:
TECO commands!
!TECOcommands!
!more commands!
!$$[

This comment describes line 1
This cominent describes line. 2
end _of command string!

The CTRL/ A command maybe used to print out a statement
at any point during the execution of a command string. The
CTRL/ A command has the general form:
tAtexttA
where the first t A is the actual command, which may be entered by
striking the control key and the A key simultaneously or by typing
an uparrow followed by an A character. The second CTRL/ A
character is the command terminator, which must be entered by
- typing the control key and the A key simultaneously. The message
which appears between the CTRLj A characters may contain any
characters except the special characters and the t A character.
Upon execution, this command causes TECO to print the speci..
fied message at the terminal.
The t AmessagetA command is particularly useful when it pre-:
c~des a command whose numeric' argument contains tT or tF
2-165

characters. The message may contain instructions notifying the
computer operator what sort of input is required.
A question mark character entered between any two commands
in a command string causes TECO to print all subsequent commands at the terminal as they are executed. Commands will be
printed as they are executed until another question mark character
is encountered. The second question mark character may be in
the same command string as the first question mark, or it may
appear in a later command string. It may not be first character
typed after a TECO-generated error message, however.
If an error is typed while entering a command string, the error
may be corrected at any time before the double ALT MODE
which terminates the command string is typed. Characters may be
deleted individually by striking the RUB OUT key. Each depression
of the R UBOUT key deletes one character, beginning with the last
character typed, and causes the deleted character to be printed at
the terminal. If an entire command string is deleted in this manner,
TECO responds by printing a new asterisk at the left margin.
Typing two successive CTRL/G characters causes the current
command string to be erased completely. The double CTRL/G
command should not be confused with the single tG command.
The double CTRLjG must be produced by holding the control
key depressed while striking the G key twice (if the terminal has
a bell, it will ring). The uparrow form of CTRL/G may not be
used for the double CTRLjG command.

Error Messages
When TECO encounters an illegal command or a command
that cannot be executed, a numeric error message is printed at
the terminal. Error messages are of the form:
?n
where "n" is a 1- or 2-digit decimal number that references an
error message from the list contained at the end of this section.
When an error message is generated, the command to which it refers is not executed, the rest of the. current command string is
ignored, and TECO prints an asterisk at the left margin to indicate
that it is ready to accept further commands'.
The tS character can be very useful. For instance, if long
insertion is typed without the "I" in front of it and an error results, tS can be. used to save the insertion, and the GZ command

2-166

•

can be used to put it into the text buffer (including the trailing ALT
MODEs).
In some cases it may be difficult to determine which command
in a long command string resulted in an error message. Typing a
question mark immediately after the TECO-generated error message causes TECO to print current command string up to and
including the erroneous character. When used in this manner, the
question mark must be the first character typed after the error
message is printed. It is not necessary to follow the question mark
with an ALT MODE.
In general, TECO command strings should be limited to a maximum of 2000 characters. Command strings exceeding 2000 characters in length should be split into smaller strings. Long command
strings are impractical because the probability of a command error
is increased and because a string which contains more than 2000
characters is too long to be stored in a Q-register.
TECO'reserves a limited amount of core for command string
storage. If a very long command, string (or a long insertion command) uses all but the last 10. command string storage locations,
TECO prints one CTRL/G character as soon as only 10 storage
locations remain and another CTRL/G after every additional
character that is entered. (CTRLjG "prints" as a bell ring if the
terminal has a bell.) Should this occur, the current command string
must be tefI!'lnated. Attempting to enter more than 10 additional
characters results in a.fatal error.
Manipulating Large Pages
TECO is designed to operate most efficiently when edited files
that contain no more than 3800 characters per page. If any page
of an input file contains more than 3800. characters, the various
TECO input commands will terminate reading that page into core
when the 'first line feed following the 3800th character is read or
when the 4000th character is read, whichever occurs first. Thus, it
is never possible for a page which contains more than 4000 characters to reside entirely within the text buffer.
Most of the-TECO output commands append a form feed to the
content of the buffer whenever a page of text is written, onto the
output file. If an input file contains pages which are more than
4000 characters long, these output commands will cause form feed
characters to be inserted into the file at locations where they may

2-167

not be desired. To prevent this, the user must understand exactly
how the output commands operate. These commands are described
briefly in Table 2-43.
Table 2-43

Form Feed Processing Output Commands

Output Command

Form Feeding Processing

P, nP, PW and nPW

Always append a form feed character to the
text contained in the buffer, regardless of
whether this text actually constitutes a complete page of the file. That is, a form feed
is appended on output even though one may
not have been present upon input.

HP, HPW, m,nP and
m, nPW

N ever appends a form feed character to the
text contained in the buffer.

N, EC and EX

If the text contained in the buffer was fol-

lowed by a form feed character in the input
file, a form feed will be appended to this
text upon output. If this text was not followed by a form feed character (i.e. if input
was terminated because the buffer had
reached the prescribed capacity), no form
feed will be appended.

If it becomes necessary to edit text that consists of large pages
without introducing extraneous form feed characters into the output, this may be accomplished by avoiding all output commands
except the N, EC and EX commands. For example, if use of a P
command would introduce an extraneous form feed, use an N
command, instead, to search for a character string contained in
the next page of the input file.

Techniques and Examples
TECO may be used in three ways. The most elementary application involves using TECO to create and edit ASCII files on-line.
The user enters short command strings, often consisting of a single
command, and proceeds from task to task until the file is complet.ely edited.
Since every edited job is simply a sequence of TECO commands, an entire job may be accomplished with one long command
string consisting of all the short command strings placed end to
end with the intervening double ALT MODE characters removed.
This leads to the cqncept of a TECO editing program, which is
2-168

simply a-Iong.-command string that p~rforms a certain- editing task. '¥:. -:"
Editing ·programs maybe written (using,TECD) and sto:red-.itTthe·
same manner: as limy other ASCII· file. Whenever the program is ..
needed, it 'may be read into the. buffer as text, stor.ed in a Q~register,
and executed by an Mq command {where "q" is the Q-regisrer·
name).
This is fine for. clear-cut editing assignments, such as converting
from one format to another or editing--certaincharacters oot of a
file, but many. editing jobs are so complex that ~a given editing
program will only solve a small class oLproblems. We solution,~
in this case, is to write very specialized "editing subroutines."
TECO subroutines might. perform such elementary functions as
replacing every occurrence of two or more consecutive spaces with
a tabulation character, for example, or ensuring that words are
not hyphenated across a page boundary. When an editing problem
arises, the right combination of subroutines may be loaded into
various Q-registers, augmented with. additional commands if
necessary, and. called by a "mainline" command string.
Editing subroutines are essentially macros; that is, sequences of
commands which perform· commonly required editing functions.
Thus, the third and most powerful application of TECO is the
creation and use of a macro library. As each editing job is undertaken, the user may look for sequences of operatlons which might
be required in future editing asignments. All of the TECO commands required to perform such an operation may be loaded into
a Q-register and executed by means of an Mqor' nMq command.
When the job is finished, the content of any Q-register which contains a 'useful macro may be written onto an output file (via the
buffer) and saved in the macro library. The nMq command, which
was designed to facilitate use' of macros, permits one run-time
numeric argument to be passed to the macro.
The following examples are intended to illustrate some of the
techniques discussed earlier .. It would not be practical to include
examples of the use of every TEeO command, since most of the
commands admit to many diverse applications. Instead, users are
encouraged to experiment with the individual commands.
Example 1:

Splitting, Merging, and Rearranging Files

Assume that the user has a file named PGM.PA on the system
device and this file contains data in the following form:
2-169

AB FORM CD FORM'EF FORM GH FORM IJ FORM KL
FORM MN FORM OP where each of the letters A, B, C, etc.,
represents 20 lines of text and FORM represents a form feed character. The user intends to rearrange the file so that it appears in
the following format:
AOB FORM D FORM MN FORM EF FORM ICJ FORM KL
FORM P FORM GH
The following sequence of commands will achieve this rearrangement. (Search command arguments are not listed explicitly.)
.R TECD
*EBPGM.PA$Y$$
*Ne$$

*J20X1$$
*20K$$
*NG$$
*HX2$$
*Y$$
*20L$$
*Gl$$
*NM$$
*HX1$$
*Y$$
*J20X3$$
*20K$$
*P$$
*G2$$
*HPEF$$
*EBPGM.PA$Y$$
*20L$$
*G3$$
*ND$$
*PWHK$$
$Gl$$
*EX$$

Call TEeD.
Specify input file and get first page.
Search for a character string in C to write A
and B on the output file.
Save all of C in Q-register 1.
Delete C from the buffer.
Search for a character string in G to write D,
E and F on the output file.
Save G and H in Q-register 2.
Delete G H from the buffer and read IJ.
Move pointer to the beginning of J.
Insert e, which was stored in Q-register 1..
Search for a character string in M to write ICJ
and KL on the output file.
Save MN in Q-register 1 (the previous content
is overwritten).
Delete MN and read OP.
Save all of D in Q-register 3.
Delete D from the buffer.
Write P onto the output file, leaving the buffer
cleared (the input file is exhausted).
Bring GH into the buffer from Q-register 2.
Write GH on the output file and close it.
Open the partially revised file.
Move the pointer to the beginning of B.
Insert all of 0 from Q-register 3.
Search for a character string in D to write
AOB on the output file.
Write D on the output file and clear buffer.
Bring al~ of MN from Q-register 1 into the
buffer.
Write MN onto the output file, then close the
file and exit to the OS/8 monitor.

At this point, the file has been rearranged in the desired format.
Of course, this rearrangement could have been accomplished in
2-170

fewer steps if the commands listed above had been combined into
longer command strings. Note that .the asterisks shown at the left
margin in this example are generated by TECO, and not typed by
the user.
Assume, now, that the s,ame input file mentioned earlier, containing data, in the form:
AB FORM CD FORM EF FORM ... FORM OF
is to be split into two separate files, with the first file containing
AB FORM CD and the second file containing KL FORM M, while
the rest of the data is to be discarded. The following commands
could be used to achieve this rearrangement:
.R TECO
*ERFILE$EWFILE.l $$
*Y$$
*P$$
*HPEF$$
*~K$$

*EWFILE.2$P$$
. *20LO,.P$$
*EFtC$$

Call TECD.
Open the input file and the first output
file.
Read AB into the buffer.
Write AB FORM onto the output file and
read CD into the buffer. ,
Write CD onto the output file (without
appending a form feed), and close the
first output file.
Search for a character string in· K. After
this command has been executed, the
buffer will contain KL. No output is gen.
erated by the search.
Open the second output file and write
KL onto.it. Read MN into the buffer .
Move the pointer to the end of M, then
write M onto the output file.
Close the second output file and exit to
the OS/8 monitor.

As a final example of file manipulation techniques, assume that
the user has two files. One file is MATH.BK, which contains information in the form:
AB FORM CD FORM EF FORM GH FORM II FORM KL
and the other is MATH.FT, which contains:
MN FORM OP FORM OR
If both of these files are stored on DECtape unit 1, the following
sequence of commands may be used to merge the two files into a·
single file, MATH.NW, which contains all of MATH.FT followed
by the latter half of file MATH.BK in the following format:
MN FORM OP FORM OR FORM GH FORM II FORM KL
2-171

*R TECO
*ERDTAI :MATII.FT$$
*EWMATIf.NW$$
*Y$$
*NR$$
*PW$$
. *ERDTAI :MATII.BK$$
*Y$$
*~$$

*NK$$
*HPEFtG$$

Call.TECO.
Open the first input file.
Open the output file on the OS/8 default
device.
Read MN into the text buffer.
Search for a character string in R to write
MN and OP onto the output file.
Write QR onto the output file, appending
a form feed .
Open the second input file.
Read AB into the buffer. QR is overwritten.
Search for a character string in G to delete AB, CD and EF, leaving GH in the
buffer.
Search· for a character strin.e: in K to
write GH and IJ on the output file, leaving KL in the buffer.
Write KL onto the output file (without
appending a form feed) and close the
file, then exit to the OS/8 monitor.

Example 2: Alphabetizing by Binary S!arch
Assume that TECO is running and the buffer contains many
short lines of text, each beginning with an alphabetic character at
the left margin (i.e. immediately following a line feed). The lines
might consist of names in a roster, for example, or entries in an
index. Figure 2-3 shows a command string which will rearrange the
lines into rough alphabetical order. This command string groups
all lines which begin with the character "A" at the beginning of the
page, followed by all lines beginning with "B," and so on.
Figure 2-4 is a flowchart showing the sequence of operations
performed by this command string. The algorithm could be extended to place the entries in strict alphabetical order by having it
loop back to perform the same binary sorting operation on successive characters in each line.
Example 3: An Elementary TECO Macro
Figure 2-5 shows a TECO macro which right justifies the content
of the text buffer on a 60-space line. This macro assumes that the
buffer contains paragraphs of text in manuscript form,' and that
every line which is· not the last line of a paragraph contains between 40 and 60 characters.
.
When the macro is run, it counts the number of spaces and the
2-172

number of characters in each line. It then adds spaces between
words until. the -line contains a total of 60 characters. Lines' which
contain fewer than 40 characters are assumed to be; paragraph
terminators. These lines are not justified. Figure 2-6 shows how the
macro may/be stored, loaded and executed using DECtape unit 1
as the storage device. In this example, DECtape file "TEXT.AS"
is the file to be justified.
I

TECO FIGURE 1
!START! J 0AUA!
!!CONT! L 0AUB!
!QA-QB"G XA K -L GA IUZ'!
!QBUA!
! L Z - • "G

- LOCO NT$ , !

!QZ"G 0UZ OSTART$'!
!$$

Figure 2-3

Command String for Example 2

2-173

FIND FIRST LINE AND
PUT ASCII CODE FOR
....---------INITIAL CHARACTER IN
Q-REGISTER A

FIND NEXT LINE AND
PUT ASC II CODE FOR
....---~INITIAL CHARACTER IN
Q-REGISTER B

A B

SWITCH THE LINES

SET A FLAG TO
I----""-~ INDICATE THAT A
SWITCH WAS MADE

C[EAR SWITCH FLAG

YES

SWITCH
FLAG SET

STOP

Figure 2-4

Flowchart for Example 2

2-174

! I! 0UN 0US!

!z -. "G !
!<Q'-JA-32"E I%S$'!
! Ql./A- 13"E OJUSTI FY $' !
! 1 %N$> !

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<S $1 $StN $>"!
!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<A> HX0 HK 0Ut 0U2
<G0QIJ:S
$; • U 1 2R 0X 4 HK
IERDSK:S G4 tH.S. HX3
M3 HK 1\$ G4 1\$ 0U5
!A! AZ"N PW HK 0U5 0AS'
%2$> 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 <Y -Z J 0P-92"E
:2S\$"L .-13"L 1.,.-lX4
0.,.K Q2"E OAS' EF
!A! %2$ I EWDSK: $ G4
@I.$. 0.,.X3 M3 0.,.K' I I
PW> 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: $$
*<STRING$$

where "string" is part of the first page of the desired file (for instance, the title line). STECO will search the entire device for the
first occurrence of the specified strings. The device may contain
many old copies of the desired file. The user should examine the
text following each occurrence of the string; if it is an earlier version, or a listing file, the user should continue searching until the
correct occurrence is found. Once the correct file is found, type:
*ERDEV:$EWDEV2:FILE$$
*N< STRI NG SNENDSTRINGSPWEF$$

where n is the number of times you had to search for the specified
string on your investigation pass, and "endstring" is a string located
at the end of the file. This operation retrieves your file and copies
it onto another device. There may be meaningless characters preceding the first good line of your file, if so, delete them.
Incompatabilities Between OS/8 TECO and DECsystem-lO TECO

OS/8 TECO is a proper subset of DECsystem-10 TECO with
the following exceptions:
1. The tU and tR commands do not exist on DECsystem-10
TECO.
2. The tS command as described on page 2-154 is implemented
differently on DECsystem-10 TECO (refer to the DECsystem-l0 Users Handbook).
2-178

3. OSj8 TECO assumes a semicolon after failing search commands in interation brackets, DECsystem-10 TECO does
not.
4. The EC, tD, to, and tW command do not exist in DECsystem-10 TECO.
5. DECsystem-10 TECO ignores the number n in the nA
command and is equivalent to the OSj8 TECO OA command.
6. The "A and "B compares are not needed by DECsystem-10
TECO because "G ~d "L are adequate to compare character pointers. .
7. The tZ and tV numeric values are not implemented by
DECsystem-10 TECO.

Table 2-44 TECO Command Summary

Function

Command
ERdev:filnam.ex$
EWdev:filnam.ex$
EBdev:filnam.ex$
y

Input file selection.
Output file selection.
II 0 file selection with backup protection.
Clear buffer and read one page of input file.
Read one page of input file and append to current
buffer content .

.. BUFFER POINTER POSITIONS
B
Before first. character.
Current pointer position (number of characters
to left of pointer) .
Z
After last character (number of characters in
buffer.
From .m+ 1th character through and including nth
m,n
character.
H
Entire buffer; equivalent to B,Z.
ARITHMETIC OPERATORS
-'n
Negation.
Addition.
m+n
m-n
Subtraction.
m*n
Multiplication.
Divide and truncate.
min
m&n
Bitwjse logical AND.
Bitwise logical OR.m#n
( )
Perform enclosed operations first.

2-179

Table 2·44

TECO Command Summary (Cont.)

Command

Function

POINTER POSITIONS
nJ
Position pointer between n tb and n+ 1tb characters.
nC
Move pointer forward across n characters.
nR
Move pointer backward across n characters.
mL
Position pointer at beginning of n tb line following
current position.
TYPE-OUT COMMANDS
nT
Type buffer. content from pointer position to beginning of n tb followirig line.
m,nT
Type m+ 1tb character through and including n tb
character.
n=
Type the integer equivalent of expression n.
t AtexttA
Type the enclosed text.
to
Inhibit typeout.
DELETION COMMANDS
nD
Delete the n characters following the pointer.
-nD
Delete the n characters preceding-the pointer.
nK
Delete the n lines following the pointer.
m,nK
Delete the m+ 1tb character through and including
the n tb character.
INSERTION COMMANDS
Itext$
Insert text delimited by I and ALT MOOE.
<I>text$
Insert tabulation, then text. <I> 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.8N<DTAl:TECQ.PA

will produce a TECa binary file on the system device.
Once a TECa binary file has been created on the system device,
the following commands will create a core image file called TECa.
SV on the system device:
• R ABSLDR
*TECQ. BN$
• SAVE SY S TECQ

The binary paper tape of TECa (DEC-S8-UEXTB-A-PB8) may
be loaded and saved on the system device by the following sequence
of commands:
• R ABSLDR
*PTR: $
• SAVE SY S TECD

The system will print an uparrow after the ALT MaDE character
to ind~cate that a paper tape should be loaded into the reader.
Strike any key at the terminal to continue.
KSR-35 T~letype users who want to take advantage of the KSR35 hardware tabulation feature should change the starting address
of TECa to location 5200. This may be accomplished by the
commands:
• GET SY S TECQ
.SAVE SYS TEC0J5200

2-183

Error Messages
TECO error messages consist of a question mark followed by a
number. Typing a second question mark immediately after an
error message printout causes the command string to be printed
up to and including the character which caused the error message.
Table 2-45

Error
1
2

3
4

5
6
7

8
9
10
11

12
13
14
15
16

TECOError Messages

Cause
Illegal command.
Incomplete command. Can mean either:
a. Character missing from command.
b. Iteration brackets do not match.
c. Conditional delimiters (double quote and apostrophe) do
match.
..
d. 0 command references nonexistent tag.
Non-alphanumeric Q-register name.
Command iterations or macro calls nested too deeply.
Text buffer overflow.
Search string longer than 31 characters.
Numeric argument missing before comma, equals sign, U, or
quote (").
Illegal file name in ER, EW or EB command.
Semicolon or failing search encountered on command level.
Iteration close (» without matching open «)'.
Attempt to move pointer outside of text buffer.
Q-register storage overflow.
Incomplete command,
Output file too large, or else output parity error.
Input file parity error.
File error; can mean either:
a. Input file not found by ER command.
b. Cannot enter output file with EW or EB command.
c. Device specified for file does not exist.
d. EB command specifies a file on a non-file-structured device.
An output command was encountered which would have
caused TECO to overflow its current output file. User should
close the current output file and write all further output onto
one (or more) additional files. These files may be combined
if necessa~y.
Attempt to execute an output command without opening an
output file.

2-184

pals .
sabrrlap/ralr .

pals
INTRODUCTION
P AL8 is an 8K, tW0 pass assembler designed to run under the
OS/8 Operating System. Pass 1 reads the input file and sets up the
symbol table. Pass 2 reads the input file and uses the symbol table
created in pass 1 to generate the binary (object) file. The binary
file is an absolute binary tape and may be loaded into core with
the Absolute Loader or Binary Loader. As an optional third pass,
a side-by-side octal and symbolic listing and the symbol table are
output .. (Using the options available, the three passes may be
automatically executed. However, if the source file is to be read
from the paper tape reader, the user must reload the tape for each
pass.) The listing file may be used as an input to the Cross Reference Program (CREF), and the symbol table may be requested to
be in a form suitable for input to DDT. If a listing file, but no
binary file or /L or /Q option was specified, P AL8 does not execute pass 2, but instead goes directly from pass 1 to pass 3.
PAL8 can handle I/O from any OS/8' device which handles
ASCII text, and has pseudo-ops and options not available in the
other PDP-8 assemblers. It is loaded and saved by way of the OS/8
Monitor and Absolute Loader. It will accept input generated by
the Editor and will generate output acceptable to Absolute Loader
and CREF.
CALLING AND USING.PALS

, P AL8 is called from the system device by typing:
RPAL8
in response to the dot printed by the Keyboard Monitor. The system replies by activating the Command Decoder, which in turn
prints an asterisk (*) at the left margin of the teleprinter paper. At
this point a command string is entered which indicates the binary

3-1

and listing output devices and file names, the input devices and file .
names, and any options selected by the user. 1 to 9 input files may
be specified. The format of the command string is:
*DEV:BINARY,DEV:LISTING,DEV:CREFLS<DEV:INPUT /OPTIONS

If the extension to the file name is omitted, the following assumed
extensions are assigned:

.PA for input file .
.Bl'f for binary output file .
.LS 'for listing output file .
.TM for intermediate CREF file (if the /C option was specified).
A null output file indicates no output file of that type is to be
generated. For example, to. assemble, load and run a P AL8 program named PROGRM which is stored on DECtape unit 1, the
user would type:
.RPAL8
*BIN <DTAl :PROGRM/G
After the assembly, the program will be loaded and run with the
starting address assumed to be location 0200 in field 0, and the
binary stored on the system device as BIN.BN.
The assembler prints any error messages encountered in the
program on the teleprinter. Typing CTRL/O at the keyboard
during an assembly will suppress the printing of error messages on
the teleprinter; however, messages are still printed in the output .file
and occur immediately before the line that is in error.
'PALS OPTIONS
Table 3-1 lists the options available in P AL8 which can be indicated in the command string typed to the Command Decoder.
When the /L or /G option is specified, the user can also include
any option to the Absolute Loader in the I/O specification line for
P AL8, such as starting address option. If no address is specified,
execution begins at 200. If no binary output file is specified with
/L or /G a temporary file, PAL8BN.TM, is created and loaded.

3-2

Table 3-1 "PAL8 Ron-Time Options

Option

Meaning

This option makes the operator ! a 6-bit left shift instead of
an inclusiv~ OR. (AlB equals At100+B)

Chain to SYS:CREF.SY after assembly. The second output
file specified is the output file passed to CREF. The third
output file is where P AL8 generates its output. If no third
output file is given, SYS:CREFLS.TM is assumed. The IC
op.tion supersedes the I G and I L options if specified in the
same command string.

Generate a DDT compatible symbol table (applicable only if
a listing file is specified).
.

Enable error messages if a link is generated. The LG error
message would be generated as well as the link being flagged.

Disable extra zero fill. in TEXT pseudo-op. If the text in the
TEXT. pseudo-op contains an even number of characters; no
word of zeroes will be added to the end.

Call the Absolute Loader, load the binary file, and begin executionat the indicated starting address. If no starting address
is indicated, start at 200.

Generate non-paginated output. Header, page "numbers and
page format are suppressed (applicable only if a listing file is
specified).

Do not list lines containing code in conditional brackets
which is conditionalized out.

Used in assembling very large programs; causes systems containing 12K or more of core to use field(s) 2 and up as symbol
table storage.

Call the Absolute Loader at the end of the assembly and load
the binary file (applicable only if a binary file was specified).

Generate the symbol table, but not the listing (applicable
only if a listing file is specified. The I H option is assumed).

Disable origining to 200 after pseudo-op. The origin remains
what it was before the FIELD pseudo- op. -

Omit the symbol table normally generated with the listing
(applicable only if a listing file is specified).

3-3

Table 3-1 PAL8 Run-Time Options (Cont.)
Option

Meaning

Output a carriage return I line feed in place of the form feed
character(s) in the program (applicable only if a listing file is
specified).

Do not remember the number of literals that were previously
stored on a page after origining off page and then back on
again.

EXAMPLES OF SPECIFICATION STRINGS
Example 1:
.RPAL8
*PTP:,LPT:<SOURCE
The above lines cause the PAL8 assembler to be loaded from the
system device and the program SOURCE.PA (or SOURCE) to be
assembled. The binary output of the assembly is put onto the paper
tape punch, and the listing and symbol table on the line printer.
Example 2:
.RPAL8
*,LISTIN<PROG/S
The above specification line causes PAL8 to assemble PROG.PA
(or PROG), putting the listing only into the file LISTIN.LS on the
default device DSK. No binary output and no symbol table are
generated.
Example 3:
.R PAL8
*BIN <INPUT.XY /G=600
The above specification line assembles INPUT .XY, putting the
binary output into a file named BIN .BN, and then calls the Absolute Loader, which loads the file BIN.BN and starts it at 600.
(=600 is an option to the Absolute Loader specifying the starting
address.)
- Example 4:
.RPAL8
*DTA1:PROG
3-4

The preceding lines will assemble the file PROG from device
DTAl, checking for errors, which are listed on the teleprinter.
There are no output files.
RESTARTING AND TERMINATING PAL8
PAL8 may only be restarted if the Command Decoder has not
been dismissed. For example:

.RPAL8
*tC
.ASSIGN DT A7 DSK
.ST

*
If a restart is attempted after the Command Decoder has been dismissed, NO! ! is typed and control returns to the Keyboard Monitor. The user must call PAL8 for each assembly.

CHARACTER SET
The following characters are acceptable as input to PAL8:

1. -The alphabetic characters: A through Z.
2. The numeric characters: 0 through 9.
3. The-Characters described in following sections as special
characters and operators.
4. Characters- which are ignored during assembly such as LINE
FEED, FORM FEED, and RUBOUT.
All other characters are illegal{except when used in a comment)
and cause the error message:

Ie nnnn
-

to be printed during pass 1; nnnn represents the location at which
the illegal character occurred. (As assembly proceeds, each instruction is assigned a location determined by the current location
counter, detailed later in this chapter. When an illegal character or
any other error is encountered during assembly, the value of the
current location counter is returned in the error message.) Illegal
characters do not gener~lly cause assembly to halt. If an illegal
character occurs in the middle of a symbot the symbol is terminated at that point.
3-5

STATEMENTS
P AL8 source programs are. usually prepared on the .console
terminal (using the OS/8 EDITOR) as a sequence of statements.
Each statement is written on a single line and is terminated by
typing the RETURN key. There are four types of elements in a
PAL8 statement which are identified by the order of their appearance in the statement and by the separating (or delimiting) character which follows or precedes the element. These are:

1.
2.
3.
4.

label,
instruction
operand
/comment

A statement must contain at least one of these elements and may
contain all four types. The assembler interprets and processes' the
statements, generating one or more binary instructions or data
words, or performing an assembly process.
Labels

A label is the symbolic name created by the programmer to
identify the location of a statement in the program. If present, the
label is written first in a statement. It must begin with JW,.alphabetic
character, contain only alphanumeric .characters, and be terminated
by a comma; there must be no intervening spaces between any of
the characters and the corr~T)]a.
Instructions

An instruction may be one or more of the mnemonic machine
instructions or a pseudo-operation which directs assembly processing. (Assembly pseudo-ops are described later in· this chapter.)
Instructions are terminated with one or more spaces (or tabs if an
operand follows) or with a semicolon, slash, or carriage return.
Operands

Operands are the octal or symbolic addresses of an assembly
language instruction or the argument of a pseudo-operator, and
can be any expression. In each case, interpretation of an operand
depends upon the instruction or the pseudo-op. Operands are terminated by a semicolon, slash, or carriage return.
3-6

Comments

The programmer may add notes or comments to a statement by
separating these from the remainder of the line with a slash. Such
comments do not affect assembly processing or program execution
but are useful in the program listing for later analysis or debugging.
The assembler ignores everything from the slash to the next carriage
return.
It is possible to have only a carriage return on a lint!, reSUlting
in a blank line in the final listing. No error message is given.
FORMAT EFFECTORS

The following characters are useful in controlling the format of
an assembly listing. They allow a neat readable listing to be produced by providing a means of spacing through the program.
Fonn Feed

The form feed code causes the assembler to output blank lines in
order to skip to a new page in the output listing during pass 3; this
is useful in creating a page-by-page listing. The form feed is generated by typing a CTRL/L on the console terminal.
Tabulations

Tabulations are used in the body of a source program to separate,
fields into columns. For example, a line written:
GO, TAD TOTAL/MAIN LOOP
is much easier to read if tabs, are inserted to form:
GO,

TAD TOTAL

/MAIN LOOP

Statement Tenninators

The RETURN key is used to terminate a statement and causes
a carriage return/line feed combination to occur in the listing. The
semicolon (;) may also be used as a statement terminator and is
considered ideriti~al to a carriage return except that it will not terminate a comment. For example:
TAD A

/THIS IS A COMMENT;

TAD B

The entire expression between the slash and the' carriage return is
considered a comment. Thus in this case the assembler ignores the
TAD B. If, for example, the user wishes to write' a sequence of
3-7

instructions to rotate the contents of the accumulator and link six
places to the right, it might look like the following:
RTR
RTR
RTR
However, the programmer can alternatively place all three instructions on a single line by separating them with the special character
semicolon and terminating the entire line with a carriage return.
The above sequence of instructions can then be written:
RTR;RTR;RTR
NOTE
If an as /8 CREF listing is desired, there
are certain restrictions on the use of semicolons. Refer to the section on CREF in
Chapter 2 of this handbook.

These multi-statement lines are particularly useful when setting
aside a section of data storage for use during processing. For example, a 4-word cleared block could be reserved by specifying
either of the following:
LIST,

o·,

LIST,

o·,

o
o
o

Either format may be used to input data words (data words may be
in the form of numbers, symbols, or expressions, explained next).
Each of. the following lines generates one storage word in the object
program:
DATA,

7777
A+C-B
S
123+B2

3-8

NUMBERS
Any sequence of digits delimited by either a SPACE, TAB, semicolon, or carriage return forms a number. P AL8 initially interprets
numbers in octal (base 8). This can be changed to decimal using a
special pseudo-operator (explained l~ter in this chapter). Numbers
are used in conjunction with symbols to form expressions.

SYMBOLS
A symbol is a string 'Of alphanumeric characters beginning with a
letter and delimited by a non-alphanumeric character. Although a
symbol may be any length only the first six characters are recognized; since additional characters are ignored, symbols which are
identical in their first six characters are considered identical.

Permanent Symbols
The assembler' contains a table (called its permanent s~Q.?l
table) which lists the 'symbols for all PDP-8 pseudo-op codes, memory reference instructions? operate and lOT (input/output transfer)
instructions. These instructions are symbols which are permanently
defined by P AL8 and need no further definition by the user; they
are summarized at the end of the chapter. For example:
HLT

This is a symbolic instruction assigned the value 7402
by the assembler and stored in its permanent symbol
table.

User-Defined Symbols
All symbols not defined by the assembler (and represented in its
permanent symbol table) must be defined within the source program.
.
A symbol may be used as a statement label, in which case it is
assigned a value equal to the current location counter; it is called a
symbolic address and can be used as an operand or as a reference
to an instruction. Permanent symbols (instructions, special characters, and pseudo-ops) may not be used as symbolic addresses.
The following are examples of legal symbolic addresses:
ADDR,
TOTAL,
SUM,

AI,
3-9

The following are illegal symbolic addresses:

AD>M,
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 CLC
/DOES NOT UPDATE CLC
/THE VALUE 500 IS ASSEMBLED AT
LOC.200
/THE VALUE 1200 IS ASSEMBLED AT
LOC.201

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

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
t 1
r
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 <source code>
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 <source code>
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 <source code>
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 <source code>
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 <IFNZRO X2 < ... > >
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 E?

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

Operation

Code

Time

, 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

2.6
2.6
2.6
2.6
2.6
1.2
. 1.2

Group 1 Operate Microinstru~tions (1 cycle = 1.2 microseconds)
NOP
lAC
BSW
RAL
RTL

7000
7001
70Q2
7004
7006

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

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<INPUT FILE(S)/OPTION(S)
where BINARY represents the binary output, LISTING the listing output, and MAP the Linking Loader loading map input. Unless alternate extensions are indicated, SABR assumes the following
extensions:
4-1

File Type

Extension

input file
binary output
listing output

.SB

.RL
.LS

If no binary output file is indicated, no binary output will be gen-

erated. However, if the /L or /0 options are specified, a binary
file will be generated under the assigned name SYS:FORTRL.TM.
OS/8 SABR OPTIONS
The options which can be included in a command string to OS/8
SABR are listed in Table 4-1 .

Table 4-1

SABR Options

Option

Meaning

Indicates that the input file is an 8K FORTRAN
output file.

Calls the Linking Loader, loads the program into
core and begins execution. If a binary output file is
not specified, then FORTRL.TM is loaded into core
and deleted from the file device, If a starting address
is not specified (using the options to the Linking
Loader), control is sent to the program entry point
MAIN (the FORTRAN compiler gives this name
automatically to the main program).

Calls the Linking Loader at the end of the assembly
and loads the specified binary file. If a binary output file is not specified, then the temporary file
FORTRL.TM is loaded into core and deleted from'
the file device. The Loader then either returns to the
Keyboard Monitor with a core image or asks for
more input, depending on whether an ALT MODE
or RETURN key has terminated the input line.

Outputs the symbol table but not the rest of the listing (applicable only if a listing file is specified).

Omits the symbol table from the listing ( applicable
only if a listing file is specified) .

When the /L or /G options are specified, ~'any options to the
. Linking Loader (described. in the section concerning~lhe Linking
Loader) can be included in the command string for SABR. This
does not include the /L (Library) option of the Linking Loader,
. since it would confli.ct with theSABR /L option.

NOTE
The FORTRAN compiler_ automatically.
generates an entry point named., MAIN
. whose address is the beginning of the program. When writing a main program in
SABR, the user should specify the entry
point MAIN with the entry pseudo-op in
order to symbolically specify the starting address to the Linking Loader. (Otherwise the
starting address must be specified to the
Loader as a five digit address.)
EXAMPLES OF OS/8 SABR I/O
SPECIFICATION COMMANDS
Example 1:
.:.R SABR
!FORTRN. TM/F /G

DSK:FORTRN.TM is assembled as a FORTRAN output file.and
the relocatable binary is loaded and started at the entry point
MAIN.
Example 2:
• R SABR
*SYS TEERL,TTY:<TEE/S

The input file TEE.SB (or TEE) on DSK: is assembled. The relocatable binary goes to the output file TEERL.RL on SYS:, the
listing without a symbol tabte goes to the terminal .
4-3

THE CHARACTER SET
ALPHABETIC
In addition to the letters A through Z, the following are considered by SABR to be alphabetic:
[ left bracket
] right bracket
'" back slash
t up arrow
NUMERIC
SABR recognizes the numbers:

0-9
SPECIAL CHARACTERS
The following printing and non-printing characters are legal:
/
(

"
#

Comma
Slash
Left parenthesis
Quote
Minus sign
Number sign
RETURN
(carriage return)
Semicolon
LINE FEED
FORM FEED
SPACE
TAB
RUB OUT

delimits a symbolic address label
indicates start of a comment
indicates a literal
precedes an ASCII constant
negates a constant
increases value of preceding symbol by one
terminates a statement
terminates an instruction
ignored
ignored
separates and delimits items on
the statement line
same as space
ignored

All other characters are illegal except when used as ASCII
constants following a quote ("), or in comments or text strings.
Legal characters used in ways different from the above, and all
illegal characters, cause the error message C (Illegal Character) to
. be printed by SABR.
4-4

STATEMENTS
SABR symbolic programs are written as a sequence of statements and are usually prepared on the terminal, on-line, with the'
aid of the Symbolic Editor program. SABR statements are virtually
format free. Each statement is terminated by typing the RETURN
key. (Editor automatically provides a line feed). Two or more
statements can be typed on the same line using- the semicolon as a
separator.
A statement line is composed of one or all of the following elements: la~el, operator, operand and comment, separated by spaces
or tabs (labels require a following comma). The types of elements
in a statement are identified by the order of appearance in the line.
and 'by the separating or delimiting character which follows or
precedes the element.
Statements are written in the general form:
labei,

operator

operand

/ comment (preceded by slash)

SABR generates one, or possibly more, machine (binary) instructions or data words for each source statement.
An input line may be up to 72 10 characters long, including
spaces and tabs. Any characters beyond this limit are ignored.
, The RETURN key (CR/LF) is both an instruction and a line
termimitor. The semicolon may be used to terminate an instruction
without terminating a line. If, for example, the programmer wishes
to write a sequence of instructions to rotate the contents of the
accumulator (AC) and link (L) six places to the right, it might
look like this:

RTR
RTR
RTR

Using the semicolon, the programmer may place all three RTR's on
a single line, separating each RTR with a semicolon and termi,.
nating the line with the RETURN key. The preceding sequence of
instructions could then be written:
4-5

RTR;RTR;RTR

(terminated with the RETURN key)

This format is particularly useful when creating a list of data:
0200
0201
0202
0203

0020
0050
7750
0062

.LISTJ

Null lines may be used to format program listings. A null line
is a line containing only a carriage return and possibly spaces or
tabs. Such lines appear as blank lines in the program listing.
Labels·
A label is a symbolic name or location tag created by the programmer to identify the address of a statement in the program.
Subsequent references to the statement can be made merely by
referencing the label. If present, the label is written first in a statement and terminated with a comma.

0201

1200

SAVE ..
ABC,

(}I

TAD SAVE

SAVE and ABC are labels referencing the statements in location
0200 and 0201, respectively.

Operators
An operator is a symbol or code which indicates an action or
operation to be performed, and may be one of the following:
1. A direct or indirect memory reference instruction
2. An operate or lOT microinstruction
3. A pseudo-operator
All SABR operators, microinstructions and memory reference
instructions are summarized in Appendix C.
4-6

Operands
An operand represents that part of the statement which is manipulated or operated upon, and may be a numeric constant, a literal
or a user-defined address symbol.
In the example ,last given , SAVE represents an operand.
CONSTANTS
Constants are data used but not changed by a~ program and are
of two types: numeric and ASCII. ASCII constants are used, only
as parameters. Numeric constants may be used as parameters or as
operand addresses, for example:
0200

1412

TAD I

Constant operand addresses are treated as absolute addresses,
just as a symbol defined by an ABSYM statement (see Symbol
Definition). References to them are not generally relocatable,
therefore, they should be used only with great care. The primary
use of constant operand addresses is to reference locations on page
o (see Linkage Routine Locations for free locations on page 0 of
each field). All constant operand addresses are assumed to be in
the field into which the program is loaded by the Linking Loader.
Constants may not be added to or subtracted fr()m each other or
from symbols.
Numeric Constants
A numeric constant consists of a single string of from one to
four digits. It may be preceded by a minus sign (-) to negate .the
constant. The digit string will be interpreted as either octal or
decimal according to the latest permanent mode setting by an
. OCTAL or DECIM pseudo-operator (explained under Assembly
Control). Octal mode is assumed at the beginning of assembly.
The digits 8 and 9 must not appear in an octal string.
0200
0201

5020
7575

5020
-203

0202

0120

DECIM
80

ASCII Cpnstants
Eight-bit ASCII values may be created as constants by typing
the ASCII character immediately following a double quotation
4-7

marks ("). A minus sign may be used to negate an alphabetic constant. The minus sign must precede the quotation mark.
0200
0201
0202

0273
7477
0207

II •
~

-"A
"

/-301

/BELL FOLLOwS

,
The following are illegal as alphabetic constants: carriage return,
line feed, fonn feed and rubout.

LITERALS
A literal is a numeric or ASCII constant preceded by a left
parenthesis. The us-e of literals provides a special and convenient
way of generating constant data in a program. The value of the
literal will be assembled in a table near the end of the core page on
which the instruction referencing it is assembled. The instruction itself will be assembled as an appropriate reference to the location
where the numeric value of the literal is assembled. Literals are
normally used by TAD and AND instructions, as in the following
examples:
0200
0201
0202

0376
1375
1374

0374

0303

0375
037.6

7730
0777

AND
TAD
TAD

(777
(-50
("C

The numeric conversion mode is initially set to octal, but is controllable with the DECIM and OCTAL pseudo-operators. This
mode can be changed on a local basis by inserting a D (decimal)
or a K (octal) between the left parenthesis and the constant. For
example:
(D32 becomes 0040 (octal)
(K-32 becomes 7746 (octal)
This usage is confined only to the statement in which it is found
and does not alter the prevailing conversion mode.
A literal may also be used as a parameter (i.e., with no operator). In this case the numeric value of the literal is assembled as
4-8

usual in the literal table near the end of the core page currently
being assembled, and a relocatable pointer to the address· of the
literal is assembled in the location where the literal parameter
appeared.
0200

0376 01

0376

0020

<20

This feature is intended primarily for use in passing external
subroutine arguments with the ARG pseudo-operator, which is
explained in greater detail later in the chapter.
PARAMETERS
A parameter is generally either a numeric constant, a literal or
a user-defined address symbol, which is intended to represent data
rather than serve as an instruction. It appears as an operand in a·
statement line containing no operator. (An exception to this is a
parameter used in conjunction with the ARG pseudo-operator, explained in Subroutines.) In the following example, 200 and -320,
M, and PGOADR all represent parameters.
0200
0201
0202
0203

0200
7460
0315
0176

ABC"

200;-320;"M

-POINTR .. PGOADR

SYMBOLS
Symbols are composed of legal alphanumeric characters and are
delimited by a non-alphanumeric character. There are two major
types of symbols: permanent, and user-defined.
Permanent Symbols
Permanent symbols are predefined and maintained in SABR's
permanent symbol table. They include all of the basic instructions
and pseudo-operators in AppendiX: C. These symbols may be used
without prior definition by the user.

4-9

User-Defined Symbols
A user-defined symbol is a string of from one to six legal alpha..
numeric characters delimited by a non-alphanumeric character.
User-defined symbols must conform to the f?llowing rules:

1. The characters must be legal alphanumericsABCD ... XYZ, [] '" l' and 0123456789.
2. The first character must be alphabetic~
3. Only the first six characters are meaningful. A symbol
such as INTEGER would be interpreted as INTEGE.
Since the symbols GEORGE 1 and GEORGE2 differ only
in the' seventh character, they would be treated as the
same symbol: GEORGE.
4. A user-defined symbol cannot be the same as any of the
pre-defined permanent symbols.
5. A user-defined symbol must be defined only once. Subsequent definitions will be ineffective and will cause SABR
to type the error message M (Multiple Definition).
A symbol is defined when it appears as a symbolic address label
or when it appears in an ABSYM, COMMN, OPDEF or SKPDF
statement (see Pseudo-Operators). No more than 64 different userdefined symbo~~ may occur on anyone core page.

Equivalent Symbols
\Vhen an address label appears alone on a line-with no instruction or parameter-the label is assigned the value of the next address assembled.
TAGl,
TAG2,
TAG3,

TAG 1 and T AG2 are equivalent symbols in that they are assigned the same value. Therefore, a TAD TAG 1 will reference the
data at TAG2. TAG3, however, is not equivalent to TAG2. TAG3
would be defined as 1 greater than TAG2.
Comments

- A programmer may add notes to a statement by preceding them
with a slash mark. Such comments do not affect assembly or program execution but are useful in interpreting the program listing
4-10

for later analysis and debugging. Entire lines of comments may be
present in the program.
N one of the special characters or symbols have significance
when they appear in a comment.
/THIS I S A Cm-iMENT .L INE.
/THIS ALSO. TAD;CALL;#"-2C+=!
A~
TAD SAVE
/SLASH STARTS COMMENT

INCREMENTING OPERANDS
Because SABR is a one-pass assembler and also' because it
sometimes generates more than one machine instruction for a
single user instruction, operand arithmetic is impossible. Statements of the form:
TAD TAG+3
TAD LIST-LIST2
JMP

• +6

are illegaL· However, by appending a number sign to an operand
the user can refere~ce a location exactly one greater than the
location of the operand ( the next .sequential , location) : TAD
LOC# is equivalent to the PAL language statement TAD LOC+ 1.
0200
0201
0202
0203

00-20
0030
1200
1201

LOC~

0400
0401

0200
0201

START~

20
30
TAD LOC
TAD LOC#
PAGE
LOC
LOC#

/GET 20
/GET 30

In assembling I-type references SABR does not attempt to determine if multiple machine code words are generated at the symbolic address referenced.
START~

TAD I
NOP
•

LOC

/LOC IS. OFF-PAGE
/USER HOPES TO MODIFY

TAD
DCA

(7500
START#

/SMA

4-11

In the preceding example the user wishes to change the NOP instruction to an SMA. However, this is not possible because TAD
I LOC will be assembled as three machine code words; if START
is at 0200, the NOP will be at 0203. The SMA will be inserted at
0201, thus destroying the second word of the TAD I LOC execution.
To avoid this error, the user should carefully examine the assembly listing before attempting to modify a program with # -type
references. In the previous example the proper sequence is:
0202
0203
0204
0205
0206
0207
0377

4067
0200 01
1407
7000
1377
3205
7500

START,

TAD I LOC

VAR,

NOP
TAD (7500
DCA VAR

The # -sign feature is intended primarily for manipulating
DUMMY variables when picking up arguments from external subroutines and returning from external subroutines (see Passing Subroutine Arguments).
PSEUDO-OPERATORS

Table 4-2 lists all the pseudo-operators available in SABR,
whether used as a free-standing assembler, or in conjunction with
the Fortran compiler. The pseudo-operators are categorized and
explained in the following paragraphs.

4-12

Table 4-2

SABR Pseudo-Operators

Mnemonic Code

Operation

ABSYM

Direct absolute symbol definition, used to indicate an absolute core address .. For example:
ABSYM TEM 177

ARG

Argument for subroutine call, indicating a value
to be transmitted, one value per ARG statement. Used only with CALL. For example:
N 1..
N2..

BLOCK

ARG (50
ARG LOCATN

Reserve storage block; reserves n words of core
by placing zeros in them. For example:
BLOCK 200
BLOCK 100

CALL

IPAGE ZERO ADDRESS

IRESERVE 300
ICOCTAL) LOCATIONS

Call external subroutine. For example:
CALL 2 .. SUBR'

where 2 is the number of arguments to be
passed and SUBR is the subroutine name.
COMMN

Common storage definition, used to name locations in field 1 as externals to be referenced by
any program. For example:
COMMN 20

120 WORDS IN COMMON

CPAGE

Check if page will hold data, followed by the
number .of words of code which must be kept
together in a unit on a page. That number of
words following the CPAGE will be assembled
as a unit on the next available core page.

DECIM

Decimal conversion,· numeric conversion interprets all numbers input. as . being decimal
numbers.

4-13

Table 4-2

SABR Pseudo-Operators (Cont.)

Mnemonic Code

Operation

DUMMY

Dummy argument definition, used in passing
arguments to and from subroutines. DUMMY
vari~bles are defined in the subprograms which
reference them. For example:
ENTRY Al

DUMMY X
DUMMY Y

EAP

Enter automatic paging mode, restore-automatic
paging (See LAP) .

END

End of program or subprogram.

ENTRY

Define program entry point, used at beginning
of subprograms to give name of entry point for
the Linking Loader. For example:

SUBROU"

ENTRY SUBROU
BLO CK 2

FORTR

Assemble FORTRAN tape.

Symbolic representation for indirect addressing.
For example:
DCA I ADD

Conditional assembly, of form:
IF NAME"

If the symbol NAME has been previously defined, the statement has no effect. If NAME is
not defined, the next 7 symbolic instructions
are not assembled.

LAP

Leave automatic paging. Assembler is initially
set for automatic jumps to the next core page
when the current page is full (or upon· REORG
or PAGE statements). This feature can be suppressed with LAP.

4-14

Table 4-2

SABR Pseudo-Operators (Cont.)

Mnemonic Code

Operation

OCTAL

Octal conversion, numeric conversion is originally set to octal and can be changed back to
octal after a DECIM pseudo-op has been used.

OPDEF

Define non-skip operator. For example:
OPDEF DTAA 6761

PAGE·

Terminate current page, begin assembly of succeeding instructions on next core page.

PAUSE

Pause for next tape, designed to allow large .
source tapes to be broken into several smaller '
segments. Assembly is continued by pressing
the CONT switch.

REORG

Terminate page and reset origin; origin settings
are always to the first address of (l page. For
example:
REORG 1000

RETRN

Return from external subroutine, the name of
'the subroutine being left must be specified. Before the RETRN statement is used, the pointer
in the second word of the subprogram entry
-must be incremented to the point following all
arguments in the calling program (after the
CALL statement).

SKPDF

Define skip-type operator. For example:
SKPDF DTSF 6771

TEXT

Text string similar to BLOCK,. except that the
argument is a text string. Characters are stored
in six-bit stripped ASCII with a printing character used to delimit the string. For example:

the string would be stored as:
6162
6352

4-15

Table 4-2 SABR Pseudo-Operators (Cont.)

Mnemonic Code

Operation
Odd characters are filled with zeros on the
right.
The floating-point accumulator (in field 1).
,

ACH

High-order word.

ACM

Middle word.

ACL

Low-order word.

Assembly Control
END
Every program or subprogram to be assembled
must contain the END pseudo-op as its last line.
If this requirement is not met, an error message
(E) is given.
PAUSE
The PAUSE pseudo-op causes assembly to halt
and is designed to allow the programmer to break
up a large source tape into several' smaller segments. To do this, the programmer need only
place a PAUSE statement at the end of each section of his source program except the last. Each
of these sections of the program is then output as
an individual tape. \"hen assembly halts at a
PAUSE, the user removes the source tape just
read from the reader and inserts the next one .
. Assembly may then be continued by pressing the
CONTinue switch.
o(

WARNING
The PAUSE pseudo-op is designed specifically for use at the end of partial tapes and
should not 'be used otherwise.

The reason for this is that the reader routine may
have read data from the paper tape into its buffer
that is actually beyond the PAUSE statement.
4-16

DECIM

OCTAL·

Consequently, when CONTinue is pressed after
. the PAUSE is found by the line interpreting routine, the entire content of the' reader buffer· following the PAUSE is destroyed, and the next tape
begins reading into a fresh buffer. Thus, if there
is any meaningful data on the tape beyond the
PAUSE statement, it will be lost.
Initially the numeric conversion mode is set for
octal conversion. However, if the user wishes, he
may change .it to decimal by use of the DECIM
pseudo-op.
If the numeric conversion mode has been set to
decimal, it may be changed back to octal by useof the OCTAL pseudo-op.
No matter which conversion mode has been permanently set, it may always be changed locally
for literals by use of the CD or (K syntax described
earlier. For example:
0200

0320

ST..ART,

0201
0202
0203

0500
0377 01
1000

0204
0205
0206

0512
0376 01
0320

320
DECIM
320
(K320
512
OCTAL
512
(D512
320
Et;JD

0376
0377

LAP

EAP

1000
0320

The assembler is initially set for automatic generation of jumps to the next core page when the page
being assembled fills up (Page Escapes), or when
PAGE or REORG pseudo-ops are encountered.
This feature may be suppressed by use of the
LAP (Leave Automatic Paging) pseudo-op.
If the user has previously suppressed the automatic paging feature, it .may be restored to operation by use of the EAP (Enter Automatic
Paging) pseudo-op.
>

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, IS used with the
following syntax:.
IF NAME...

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 TEM
ABSYM AX
OPDEF DTRA
SKPDF DTSF
SKPDF 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): 211
COtv:MN 10
COMMN 300
CCrv:MN 0
COMMN 10
ENTRY SUERUT

B,
c~
D~

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

(Calling Program)

SUBROUTINE TWOCIARG)
H\RG = IARG + IARG
RETURN
END

(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 136
13225 62131 135
12'226 12'21312' 12'1
13227 6212'1 12'5
132312' 12'212'3 12'1
13231 6201 12'5
12'232 ·12'204 12'1

CALL 3,ADD
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

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 01
0000
0000
0000
0000
1206
3207
1377
3210
4067
0211 01
1407
2212
6201 05
3607
2207
2210
5217
4067
0202 01
1407
4033
0002 06

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·

/CALLED BY: CALL ADD (X ... K... Z)
ENTRY ADD
DUMMY X
DUMMY K
'DUMMY Z
X...
BLOCK 2
K...

BLOCK 2

Z ...

BLOCK 2

XPNT ...
PNTR ...
CNTR ...
ADD ...

X
0
0
BLOCK 2

Al ...

TAD XPNT
DCA PNTR
TAD (-6
DCA CNTR
TAD I ADD

/ENTRY POINT '

INC ADD'
DCA I PNTR
INC PNTR
ISZ CNTR
JMP A1
TAD I K

/GET 2ND ARG

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 06
6211
0200
4033
0103 06
6211
0200
4033
0104 06
6211
0200
4040
0001 06

C..

CSQR ..

COMMN 3
. ENTRY CSQR
BLOCK 2

/RESERVES COMMON
/STORAGE
/DEFINES ENTRY PT.
/ACTUAL ENTRY POINT

CALL l .. FAD

/GET THE ARGUMENT

ARG C
CALL l .. FMP

/MUL T IPLY IT

ARG C
CALL 1 .. STO

/REPLACE WITH RESULT

ARG C
RETRN CSQR

/RETURN TO CALLING
/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. Change data field to current and skip
2. Change data field to 1 (common) and skip
3. Off-page indirect reference linkage
4. 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

•••
•••
1, IOH
-0

/TERMINATES READ

CALL
ARG·

2, WRITE

jINITIALIZES WRITE

ARG

CALL
ARG

•••
(n

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.
1, IFAD
ptr
/ptr=2 WORD POINTER
/TO HIGH ORDER
/ADDRESS OF FLOATING
/POINT ARGUMENT

CALL
ARG

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.
0, CLEAR

CALL

"pr.L.. OAT auu.
" .... ,;1 "PT.L..'-J
nT al \..- \..-a,l1\..-u.
".;"11"r/ 4-"
c",-ue""
..l-.~ : .... 4-e~e- ~~- .. ~:-e...t
tV
VlI" I l Ull;; 111t 2:; 1 ,",Vl1laUI U
~

n .. ".

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 III
"addr" in the AC.
CALL
ARG

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

MODE OF
OPERAND 1 •
(BASE)
"

II POW
IFPOW
FIPOW
FFPOW

INTEGE'R
INTEGER
FLOATING POINT
.FLOATING POI NT

CALL

2, FFPOW
addr 2

ARG

MODE OF
OPERAND 2
(EXPONENT)

MODE OF
RESULT

INTEGER
FLOATING POINT
INTEGER
FLOATING POINT

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 WTAPE
CALL WTAPE
CALL WTAPE
CALL 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 (177
JMS PUNCH
TAD ORG
AND <177
JMS PUNCH
TAD I ORG
CLL RTR;RTR;RTR

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

AND (77
JMS PUNCH
TAD I ORG
AND (77
JMS PUNCH
INC ORG

JMS LT
OSR
DCA ORG

IPUNCH LEADING
IDIGITS OF ADDRESS
IPUNCH SECOND
IDIGITS OF ADD~ESS
INOW PUNCH CONTENTS
10F THAT LOCATION

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 AND I
OPDEF TADI
OPDEF ISZI
OPDEF 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.

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

Option

Linking Loader Options (Cont.)

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 of free pages in field 0)
(number of free pages in field 1)
(number of free pages in field 2)
(number of free pages in field 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 U
1Zl1Zl1Zl1Zl1Zl U
1Zl4722
1Zl5247
1Zl5131
1Zl4632
1Zl51Zl74
1Zl4447
1Zl5211Zl
1Zl41Zl11Zl
1Zl1Zl1Zl1Zl1Zl U
1Zl1Zl1Zl1Zl1Zl U
041Zl1Zl1Zl
1Zl5046
1Zl4513
04561
1Zl5231

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 <DEV:INPUT FILE(S)
* (additional iriput files) $
No more than nine input files are allowed on anyone line, but
several input lines can be entered. The last input line must end
with the user typing the ALT MODE key (which echoes as $).
Only the first line can contain an output file. If no output file is
specified, a file named LIBS.RL is created on the system device.
The assumed extension for both input and output files is .RL.

NOTE
Files output from LIBSET are in a special
relocatable library format and must not be
copied with the IB option in PIP. Instead,
they should be copied by PIP in image. (II)
mode.
LIB SET OPTIONS
Only one option is allowed in the use of LIBSET, and this is
described below:
Option

Meaning

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

NOTE
If IS is used on a line that contains no input

files, input from PTR: is assumed.
EXAMPLES OF LIB SET USAGE
Example 1:
1DTA2:SUBS<DTAl:SUBl~SUB2~SUB3~PTR:

.!.!SYS: FUN C1 ~ FUN C2. V5$

4-69

This example creates a relocatable library file on DTA2 named
SUBS.RL. This library will contain six FORTRAN (or SABR)
subroutines built by combining the relocatable binary file SUB 1.RL,
SUB2.RL, and SUB3.RL from DTAl together with one relocatable binary paper tape (note the t printed by OS/8 before loading
from PTR:) and the files FUNCl.RL and FUNC2.V5 from the
system device.
Example 2:
i,AS IN ~ ACO S
*1 S$t

Since no output file was specified, this example creates a re1ocatable library file LIB8.RL on the system device. This produces a
new FORTRAN library including the subroutines contained.in
the files ASIN and ACOS on device DSK, and several subroutines
combined on a single paper tape loaded from the high-speed reader.
Subroutine Names
It is important to distinguish between the OS/8 file name of a
relocatable binary program and its assigned Entry Point name.
The fIle name has meaning only to the Command Decoder; the
Entry Point name (or names) are the true subroutine names that
are meaningful to the Loader.
Further details on the format of relocatable binary files and relocatable library files can be found in the OS/8 Software Support
Manual (DEC-S8-0SSMA-A-D).
Sequence for Loading Subroutines
LIB SET can combine files in any sequence to form a re1ocatable library file. However, the subroutines in any single library are
loaded by the Loader in the order in which they were originally
specified to LIBSET. Therefore, it is important to make sure that
subroutines are specified in order of size, with the largest subroutine being loaded first. If this is not done, cases can occur in
which insufficient core is available in any single field to load a
subroutine, whereas space would have been available if the subroutine had been loaded earlier.

4-70

LIBSET Error Messages
All errors are fatal. .LIBSET recalls the Keyboard Monitor upon
encountering any of the following error conditions, and must be
recalled in order to enter another command string.
Table 4-6

LIBSET Error Messages

Error Message

Meaning

BAD FORMAT OR
CHECKSUMTRY AGAIN

Error in reading relocatable binary file.

ERROR WHILE WRITING
OUTPUT FILE

Fatal output error occurred.

INPUT ERROR

Parity error on input.

LIBRARY DIRECTORY
OVERFLOW

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

LIBRARY PROGRAMS
During execution, the Library programs check for certain errors
and type out the appropriate error messages· in the form:
XXXX ERROR AT LOC NNNN
where XXXX specifies the type of error, and NNNN is the loca- '
tion of the error. When an error is encountered, execution stops,
and the error must be corrected.
When multiple error messages are typed, the location of the
last error message is relevant to the user program. The other error
messages are relevant to subprograms. called by the statement at
the relevant location.
4-71

Table 4-7

Library Error Messages

Error Message·

Explanation

ALOG
ATAN
DIVZ
EXP
FIPW

Attempt to compute log of negative number
Result exceeds capacity of computer
Attempt to divide by 0
Result exceeds capacity of computer
Error in raising a number to a power
Multiple decimal points
E or . in integer
Illegal character in I, E, or F field
Multiple minus signs
Invalid FORMAT statement
Negative number raised to floating power
Floating-point error; may be caused by
division by zero; floating- point overflow; attempt to fix too large a number.
Attempt to take root of a negative number

FMTI
FMT2
FMT3
FMT4
FMT5
FLPW
FPNT

SQRT

OS/8 includes, in addition, the error message:
USER

ERRC~

1 AT 00537

which means that the user tried to reference an entry point of a
program which was not loaded.
To pinpoint the location of a Library execution error:
1. From the Storage Map, determine the next lowest numbered
location (e~ternal 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
subroutine containing the error from the LOC of the error
in the error message.
3. From the assembly symbol table, determine the relative address of the external symbot' 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.
4-72

DEMONSTRATION PROGRAM USING LmRARY ROUTINES
The following demonstration program is a SABR program showing the use of the library routines. The program was written to add
two integer numbers, convert the result into floating-point, and
type the result in both integer and floating-point format. The source
program was written using the Symbolic Editor, assembled with
SABR, ami loaded with the Linking Loader, under the 08/8
Operating System.

A
B
C
D
FLOAT
FORMT
10H
N
OPEN
START
STO
WRITE

21257
212621
21261
21262
21212121 EXT
212421
0000EXT
21256
21212121 EXT
21 22121 EXT
21212121 EXT
21212121 EXT

.
ENTRY START

2122121
212211

42133
2121212 216

21202 1257
212213 12621
212214 3261
212215 42133
212216 . 21121 3 216

START,

CALL 21, OPEN
TAD A
TAD B
DCA C
CALL 1,FLOAT

/INITIALIZE
/1/0 DEVICES
/COMPUTE C=A+B
/CONVERT TO
/FLOATING POINT

212217
21.210
21211
21212
. 21213
21214
21215
21216

6201 215
21261 211
42133
211214.216
62211 215
21262 211
42133
.212215 216

ARG C

CALL 2, WRITE

/ IN IT IALIZE

21217
212221

62211 215
21256 211

ARG N

/1/0 HANDLER
/DEVICE NUMBER

21221
21222

62211 215
212421 211 .

ARG FORMT

/1=TELETYPE
/FORMAT SPECI-

21223
21224

42133
21121.6 216

CALL

/FICATION
/TYPE INTEGER

CALL 1,STO
ARG D

l~IOH

/NUM3ER

4-73

0225
0226
0227
0230

6201 05
0261 01
4033
0106 06

ARG C

0231
0232
0233
0234
0235
0236
0237

6201 05
0262 01
4033
0106 06
6211
0000
7402

ARG D

0240
0241
0242
0243
0244
0245
0246
0247
0250
0251
0252
0253
0254
0255
0256
0257
0260
0261
0262
0263
1Zl264

5047
2410
0540
0116
2327
0522
2340
0122
0547
5411
6554
0667
5662
5100
0001
0002
0002
0000
0000
1Zl1Zl00
1Zl1Zl1Zl1Zl

CALL 1,IOH

/TYFE FLOATING
/POINT NUMBER

CALL 1,IOH

/COMPLETE THE I/O

ARG 0
HLT
FORMT,

TEXT "('THE ANSWERS ARE',I5,F7.2)"

N,
A,
B,
C,
D,

1
2
2
0
BLOCK 3
'L"l\TT"\
.L...o.l.V J.J

The binary tape produced by the assembly was then run using
05/8 with the following results:
THE ANSWERS ARE

4-74

5
~Iap/ralr:
INTRODUCTION
FLAP and RALF are assemblers that translate PDP-8 or
PDP-12 processor and floating point processor (FPP) operation
codes in a source program into bInary codes in two or three passes.
The first pass assigns numeric values to the symbols and places
them in the symbol table, the second pass generates the binary
coding, and the third pass generates the program listing. FLAP /
RALF is used to assemble programs using the FPP instructions
and capabilities. Numeric values can be calculated as 12-bit integers, IS-bit integers, 24-bit double precision fractions, 3-word
floating point values, or 6-word extended precision floating point
values. Refer to the FPP User's Guide, DEC-12-GQZA-D, for de. tailed information on the floating point processor. and its instruction set.
FLAP is designed to run on an OS/8 System with a Floating
Point Processor (FPP) without any other supporting programs. It
generates absolute binary output which is legal input to the OS/8
Absolute Loader (ABSLDR). RALF, an extension of FLAP, is
part of the OS/8 FORTRAN IV System. It accepts assembly language files, or FORTRAN compiler output and generates relocatable binary modules that can be loaded by the relocatable loader
LOAD (also part of the OS/8 FORTRAN IV System).
The following sections describe the syntax, instruction formats,
addressing modes, and pseudo-operators in the assemblers. The
special features of RALF involving relocatable assembly are described in the- section entitled "RALF Features."
HARDWARE REQUIREMENTS
The minimum hardware configuration for FLAP is aPDP-8 or
PDP-12 with a Floating Point Processor (FPP). The minimum
hardware configuration for RALF is a PDP-8 or PDP-12 OS/8
System.
'

5-1

STATEMENT SYNTAX
A source program is a sequence of coding statements in the general format:
tag, instruction (space)expression (space)/ comment
A physical line of coding may be up to 127 characters long and is
terminated by a carriage return. A semicolon can be used in a line
of code (except in the comment field) to terminate a logical statement, thus permitting several statements to be typed on a single
line. However, a set of logical statements separated by semicolons
must not exceed the 127 character limit.
A space is required in a statement:
• after an instruction mnemonic
• before a slash U) used to indicate a comment
• as an OR operator
Multiple spaces or tabs are equivalent to a single space. These
characters are optional after the comma defining a tag, af~er the
= sign that sets a value, and before a statement.
Tags
A statement tag is indicated by preceding the statement to be
labeled with a user-defined symbol followed by a comma. This
format assigns the current value of the location counter to the tag.
Instructions
An instruction may be a PDP-8 operation code, an FPP12 operation code, a FLAP pseudo-operator, _or a RALF pseudooperator.
Expressions
An expression can contain:

1. A user-defined symbol (equated symbol or tag).
2. The symbol ".", which has a value equal to the currerit location counter.
3. A numeric constant.
4. Two or more of the above combined by operators.
FPP and PDP-8 instructions are illegal symbols in expressions.
User symbols can be 1 to 6 alphanumeric characters in length and

5-2

must start with a # or an alphabetic character. Any additional
characters are ignored. Thus, the symbols:
#100
A
A1234
are acceptable, but in the symbol:
ASYMBOLMAYBEMORETHAN6CHARACTERS
only the first six characters are stored as the symbol name. In this
case, all characters after ASYMBO are ignored. Up to 500 symbols
may be defined by the user in an assembly.
All integer expressions are computed in IS-bit 2's complement
arithmetic and then truncated if necessary (15 bits for 2-word FPP
memory reference instructions and 12 bits for expressions). The
following are examples of legal integer (address) expressions:
START+l
123
BUFSIZ*2+7600+300
(ADDRES+2
The radix pseudo-ops OCTAL and DECIMAL control the interpretation of numbers used in expressions. Decimal numbers larger
than 32,767 and octal numbers larger than 77777 will be incorrectly converted, and cause the NE error. (Error messages are
listed at the end of the chapter.)
Comments

A comment is a note added by the programmer at the end of a
line of code, usually to -indicate the logical sequence of the program. A slash (/), preceded by one or more spaces or tabs,is typed
to specify the start of a comment. Comments must not contain
angle brackets (or).
ARITHMETIC AND LOGICAL OPERATIONS
The operators used by FLAP/RALF and their functions III
combining numbers or symbols to form expressions are:

5-3

Operator

space or tab

Function

2's complement addition
2's complement subtraction
multiplication
division
inclusive OR used to separate
two instructions
In.-.lnsl'UP
OR
.........
"""
.... " ..........
precedes an ASCII constant; e.g.,
"A has the octal value 301
~

Expressions are evaluated from left to right. They may not contain
floating point constants.
PDP-8 OPERATION CODES
PDP-8 operation codes are legal defined mnemonics for use with
FLAP /RALF. The following table lists the mnemonic, octal value,
and operation of each PDP-8 operation code. PDP-8 code must be
executed by the PDP-8 or PDP-12 processor. Assembler statements using these codes are said to be coded (or executed) in
PDP-8 mode.
Table 5.;1

Mnemonic

Octal

PDP-8 Operation Codes

Operation

Memory Reference Instructions:
AND
0000
logical AND
TAD
2's complement add
1000
ISZ
increment anq skip if zero
2000
deposit and clear AC
DCA
3000
JMS.
jump to subroutine
4000
jump
5000
JMP
Group 1 Operate Microinstructions:
NOP
7000
no operation
7200
clear AC
CLA
7100
clear link
CLL
CMA
7040
complement AC
CML
7020
complement link
RAR
7010
rotate AC and link right one
7004
rotate AC and link left one
RAL
RTR
7012
rotate AC and link right two

5-4

Table 5-1

PDP-8 Operation Codes (Cont.)

Mnemonic

Octal

Operation

RTL
lAC

7006
7001

rotate AC and link left two
increment AC

Group 2 Operate Microinstructions:
SMA
7500
skip on minus AC
SZA
7440
skip on zero AC
SPA
7510
skip on positive AC
SNA
7450
skip on non-zero AC
SNL
7420
skip on non-zero link
7430
skip on zero link
SZL
SKP
7410
skip
OSR
7404
inclusive OR switch register with AC
HLT
7402
halt
Combined Microinstructions:
CIA
7401
CMA lAC
LAS
7604
CLA OSR
lOT Microinstructions:
Keyboard/Reader
KSF
6031
KCC
6032
KRS
6034
KRB
6036
Teleprinter/Punch
TSF
6041
TCF
6042
TPC
6044
TLS

6046

Program Interrupt
ION
6001
IOF
6002

skip if keyboard/reader flag = 1
clear AC and keyboard! reader flag
read keyboard/reader buffer
clear AC a.l'}d read keyboard buffer and clear
,
keyboard' flag
skip if teleprinter/punch flag = 1
clear teleprinter Ipunch flag
load teleprinter/punch buffer, select and
print
load teleprinter/punch buffer, sel€~ct and
print, and clear teleprinter/punch flag
turn interrupt on
turn interrupt off

Extended Memory (Type MC8/1)
'CDF
62n1
change to data field n
CIF
62n2
change to instruction n
RDF
6214
read data field into AC
RIF
6224
read instruction field into AC
RMF
6244
restore memory field
RIB
6234
read interrupt

5-5

·PDP-8 MODE ADDRESSING

In PDP-8 Mode, addressing is specified by the contents of the
Memory Reference Instruction modified by the Data Field and Instruction Field Registers. Direct addressing, specified by bit 3=0,
causes reference to the address given in bits 5-11 in page of the
current field, if bit 4=0, or to the current page, if bit 4= 1. Indirect
addressing, specified by bit 3 =1, causes reference to the indirect
. address contained in the location specified by bits 4-11, used as
above. Tne indirect address for AND,TADJSZ, and DCA refers
not to the current field, but to the field specified in the Data Field
Register: The JMP and JMS instructions refer to locations in the
field specified in the Instruction Field Register.
.
The Data Field Register and Instruction Field Register are
originally set through the console switches, and can be set under
program control Oy means or'the CIF and CDF instructions. The
CIF instruction causes the Instruction Field Buffer to be set to the
specified field. The CDF instruction causes the Data Field Register
to be changed immediately. Other instructions allow the program to read, save, and restore the Data Field and Instruction Field
Registers. Completion of execution of a JMP or JMS instruction
causes the Instructlon Field Register to be set to the contents of the
Instruct:on Field Buffer. This procedure permits a program to
choose a new field, then execute a jump from the current field to
a chosen address in the new fieid.
The character % appended to the end of a memory reference
instruction indicates indirect addressing and the character Z indicates a page reference:

PAGE ZERO
DIRECT
INDIRECT

CURRENT PAGE
DIRECT
INDIRECT
TAD A
DCA B

TADZ A
DCAZ B

TAD% A
DCA% B

TADZ% A
DCAZ% B

Spaces are not allowed between Memory Reference Instructions
and either the Z or % characters. The Z must precede the % when
both are used, i.e., do not'write "DCA%Z".
FPP OPERATION CODES
The Floating Point Processor recognizes the following operation
code formats. There are three forms of Data Reference Instructions

5-6

analogous to the Memory Reference Instructions, and three Special
Format instruction forms analogous to the Operate Micro-Instructions.

Data Reference Instructions
Data Reference Instructions cause transfer between memory and
the floating point accumulator, a 36-bit register in the FPP. The
transfer may be 36 bits of floating point data or 24 bits of double
precision- fixed point fraction data, depending upon where STARTF
or STARTD was most recently executed. In fixed point mode, the
last 24 bits of the F AC or memory are used, and the exponent is
unchanged. All eight of the Data Reference' Instructions can be
used in any of the three forms.
Throughout the description of the instructions that follow, these conventional symbols are used:
-C()
FAC
M

contents of enclosed quantity
floating accumulator
a variable multiplier
=2 in Double Precision Mode
=3 in Floating Point Mode
an indexing variable
X=O, do not ,index
1:::;X:::;7, use specified index register
origin of index registers
address computed
an increment bit
=0, no incrementing
= 1, increment before using index
symbol to avoid indexing
X=O
S(X)==O
X-=/=O
S(X)==l

x
XO
Y

+
SeX)

Op Code

-Mnemonic

FLDA
FADD
FSUB

1
2
3
4

Data Function
C(Y)~FAC

C(Y) + C(FAC)~ FAC
C(FAC) - C(Y)~C FAC
C(FAC)/C(Y)~ FAC
C(FAC * C(Y)~ FAC ...

FDIV
FMUL
5-7

Op Code

Mnemonic

Data Function

5
6
7

FADDM
FSTA
FMULM

C(Y) + C(FAC)~ Y
C(FAC)~Y

C(FAC) * C(Y)~ Y

DATA REFERENCE INSTRUCTION FORMATS
o

I I I I

. OP CODE

11
ADDRESS

12
.

ADDRESS

OOUBLE-WORD DATA REFERENCE INSTRUCTIONS

Y = C(bits 9-23) + M * (C(X + XO) + C(bit 5» * SeX)

OP CODE

OFFSET

SINGLt:-wmm DIRECT REFERENCE

Y'= C(base register) + 3 * (offset)

OP CODE

OFFSET

SINGLE-WORD INDIRECT REFERENCE

Y = C(bits 21-36 of C((base register) + 3 * offset»
+ (M) * (C(X + XO) + C(bit 5» * SeX)
SeX) = 1 if Xi- 0 and 0 if X= 0
M '= 2 if fixed-point mode
= 3 if floating-point mode
5-8

SPECIAL FORMAT 1 - Jump on count + trap
Op Code

Mnemonic

Function

JXN

The index register X IS mcremented if bit 5=1 and a jump is
~xecuted to the address contained
in bits 9-23, if index register X is
nonzero.
The instruction-trap status bit is
set and the FPP12 exits causing
a PDP interrupt. The unindexed
operand address is dumped into
the APT.

3
4

5
6

The two trap instructions with op c;odes 3 and 4 are assigried a
special meaning by RALF, and the mnemonics TRAP3 and
TRAP4 respectively. TRAP3 acts as' a JMP to PDP-8 Mode;
TRAP4 acts as a JMS to PDP-8 Mode. See the FORTRAN IV
SOFTWARE SUPPORT MANUAL for details.
2

0
OP CODE

I ADDRESS

23
ADDRESS
SPECIAL FORMAT 1

SPECIAL FORMAT 2 - Load index and add index
Op Code

Extension

Mnemonic

Function

LDX

ADDX

The contents of the index
register specified by the bits
9-11 are replaced by the contents of bits 12-23.
The contents of bits 12-23
ate added to the index register .specified by bits 9-11.

5-9

SPECIAL FORMAT 2 - Conditional jumps
Jumps, if perfonned, are to the location specified by bits 9-23
of the instruction.
Op Code

Extension

Mnemonic

Function

1
1
1
1
1
1
1
1

0
1
2
3
4
5
6
7

JEOJGE
JLE
JA
JNE
JLT
JGT
JAL

Jump if FAC= 0
Jump if FAC ~ 0
Jump if FAC :::; 0
Jump always
Jump if FAC 0
Jump if FAC < 0
Jump if FAC > 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

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.

ATX

The contents of the FAC are
fixed and the least significant
12 bits .of the mantissa are

5-11

Op Code Extension

Mnemonic

XTA

NOP

o
o

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 <

assemble if symbol was previously defined or referenced.

IFNDEF symbol <

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 B

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 0\102
01c:l2\11 21C01/l
00202 '0000
00203 0iC0&!
021204 3\10~
021205 0000
1i1020& 01d03
00207 ~40icl
1il1il210 000\1
00211 00010
00212 01rj0kl
00213 01101il

QRG 21il0
F 2.0
A,

3.0

5,0

0,O

SE.TB 200

00214 1110
014215 02011
00216 112101
00217 0/,j00
0"'220

13,

HLT
BASE 1/1

H0&!
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:
LVL-

"'r1

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 SUB
JSR
SUB
JA
BYARG
JA
X
JA
Y
JA
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

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
ILONG ENOUGH TO GET RETURN ADDRESS
ISTART OF' INTEGER ROUTINE SAME AS
MOD,
ISTART OF REAL NU~. ROUTINE
IAMOD, STARTD
F'LDA
IGET RETURN JUMP
Ifll*3
F'STA
ISAVE IN THIS PROGRAM
AMDRTN
()
F'LDA
IGET POINTER TO PASSED ARG
SETX
XRAMOJ
•
IASSIGN MOD'S INDEX REGS
SETS
BPAMOD
IANJ ITS BASE PAGE
BASE
BPAMO~
1, 1
LDX
F'STA
BPAMO:J
F'LDAi.
BPAMOD,l
IADDR OF X
F'STA
AMODX
FLDA i.
IA !)DR Of Y
BPA!"lO:J, 1+
F'STA
B?AMOD
,.. ... ,.n .... _
;) 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<ORG
.-SECNAM&7600+ 200+SECN AM>
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 name

Define name as a special common section restricted to load into page 0 of field 1.

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 = to value of expression on right.

5-41

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. Editor
-2. Compiler
3. Loader
4. 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
Assign a value to a variable.
PRINT
Print out the indicated information.
READ
Initialize variables to values from the data list.
DATA
Provide initial data for a program.
GOTO
Change order of program execution.
IF GOTO} Conditionally change order of program execution.
IF THEN
FOR TO } Set up a program loop.
STEP
NEXT
End a program loop.
Go to a subroutine.
GOSUB
RETURN
Return from a subroutine.
INPUT
Get initial values from the terminal.
REM
Insert a program comment.
RESTORE 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~<N<10616. OS/8 BASIC treats all numbers as decimal
numbers; that is, it accepts any number containing a decimal, and
assumes a decimal point after an integer. The advantage of treating all numbers as decimal numbers is that the programmer can
use any number or symbol in any mathematical expression without regard to its type.
In addition to integer and decimal formats, a third format is
recognized and .accepted by OS/8 BASIC and is used to express
numbers outside the range .000001 ~x ~999999. This format is

6-6

called exponential or E-type notation and in this format, a number
is expressed as a decimal' number times some power of 10. The
form is:
xxEn
where E represents "times 10 to the power of," thusthe number is
read: "xx times 10 to the power of n." For example:
23.4E2=23.4* 102 =2340
Data may be input in anyone or all three of these forms. Results
of computations are output as decimals if they are within the range
previously stated; otherwise, they are output in E format. OS/8
BASIC handles six significant digits in normal operation and input/ output, as illustrated
below:
,
,

Value Typed in

Value Output By OS/8 BASIC

;01
0.0099999
0.0099
.0099
999999 .
999999·
.100000E+007
1000000
.899999E-006
.0000009
OS/8 BASIC automaticallysuppresses,tbe printing of leading and
trailing zeros in integer numbers and all but one leading zero in
decimal numbers. As can be seen from the ,preceding examrHes,
OS/8 BASIC formats all exponefl;tial numbers in the form: '
sign .xxxxxxE( + or-)n
where x represents the number carried to six decimal places, E
stands for "times 10 to the power of," and n represents the exponential value.
For example:
-.347021E+OO9 is equal to -347,021,000
.726000E-003 is equal to 0.000726

6-7

Variables
A simple variable in 08/8 BASIC is an algebraic symbol representing a number, and is formed by a single letter or a letter followed by a digit. For example:
Acceptable Variables

Unacceptable Variables

2C-a digit cannot begin
a variable
AB-two or more letters
cannot form a variable

The user may assign values to variables either by indicating the
values in a LET statement, or by inputting the values as data.
10 LET 1=53721
20 LET B3=456.9
30 LET X-20E9
40 INPUT Q
These operations, as well as subscripted variables, are discussed in
detail in the section entitled LISTS AND TABLES. A discussion
of subscripted and unsubscripted string variables is provided in the
section entitled ALPHANUMERIC fNf10RMATION.

Arithmetic Operations
OS/8 BASIC performs addition, subtraction, multiplication,
division and exponentiation, as well as more complicated operations explained in detail later in the manual. The five operators
used in writing most formulas are:
Symbol
Operator

+
*

t (or **)

Meaning

Example

A+B
Addition
A-B
Subtraction
Multiplication
A*B
Division
AlB
At B or (A**B)
Exponentiation
(Raise A to the B Power)
6-8

PRIORITY OF ARITHMETIC OPERATIONS
In any given mathematical formula, OS/8 BASIC performs the
arithmetic operations in the following order:
1. Parentheses receive top priority. Any expression within
parentheses is evaluated before an unparenthesized expresSIon.
2. In absence of parentheses, the order of priority is:
a. Exponentiation
b. Multiplication and Division (of equal priority)
c. Addition and Subtraction (of equal priority)
3. If either 1 or 2 a~ove does not clearly designate the order
of priority, then the 'evaluation of expressions proceeds from
left to right.

The ,expression A tB t C js evaluated from left to right as follows:
1. A t B
= step 1
2. (result of step 1) t C = answer

The expression AlB *C is also evaluated from left to right since
multiplication ~nd division are of equal priority:

1. AlB
= step 1 .
2. (result of step l)*C = answer
PARENTHESES
Parentheses maybe used by the programmer to change the order
or priority (as listed in rule 2 above), because expressions within
parentheses are ,always evaluated first. Thus, by enclosing expressions appropriately, the programmer can control the order of evaluation. Parentheses may be nested, or enclosed by a second set (or
more) of parentheses. In this case, the expression within the innermost parentheses is evaluated first, and then the next innermost,
and so on, until all have been evaluated.
Consider the following eXanlple:
A=7*«B t 2+4)/X)
The order of priority is:
l.B t 2
= step 1
2. , (result of step 1)+4 = step 2

6-9

3. (result of step 2)/X = step 3
4. (result of step 3)*7 = A
Parentheses also prevent any confusion or doubt as to how the expression is evaluated. For example:
A*B l' 2/7+B/C+D 1'2
((A *B l' 2)/7)+((B/C)+D l' 2)
Both of these formulas will be executed in the same way. However, the inexperienced programmer or student may find that the
second is easier to understand. Spaces may also be used to increase
readability. Since the OS/8 BASIC compiler ignores spaces, the
two statements:
10 LET B = D l' 2 + 1
10 LETB=D1' 2+1
are identical, but spaces in the first statement provide ease jn readmg.
RELATIONAL OPERATORS
A program may require that two values be compared' at some
'point to discover their relation to one another. To accomplish this,
OS/8 BASIC makes use of the following relational operators:

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 B<O, then A t B=O
Ot-2=0
and a DV error message is printed
(See Appendix C)
3 t 5=3*3*3*3*3=243
4. If B is an integer >9, 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<O,
EM printed.
program halts due to fatal error

OSj8 BASIC STATEMENTS
The following Example Program is included at this point as an
illustration of the format of an OS/8 BASIC program, the ease in
running it, and the type of output that may be produced. This
program and its results are for the most part self-explanatory. Following sections cover the program statements and system commands used in OS/8 BASIC programming.
6-11

REM - PROGRAM TO TAKE AVERAGE OF
REM - STUDENT GRADES AND a..ASS GRADES
PRI NT '"H OW MANY STUDENTS.. H OW MANY GRADES PER STUDENT "J
30 INPUT A.. B
40 LET 1=0
50 FOR J=I TO A- 1
55 LET V= 0
60 PRINT "STUDENT NlJIo!BER = "1 J
75 PRI NT "ENTER GRADES"
76 LET D=J
80 FOR K=D TO D+C B-1>
81
INPUT G
,82 LET V=V+G
85 NEXT K
90 LET V=V/B
95 PRI N T "AVERAGE GRADE - "J V
96 PRINT
'99 LET Q=Q+V
109 NEXT J
191 PRJ NT
102 PRJNT
103 PRINT "Q..ASS AVERAGE ="; Q/A
104 STOP
149 END
10
15
20

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

= 2

?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<B+I0
100 A=A t B+10

110 LET L=L+1
,110 L=L+1

The LET statement is not strictly an equality. LET means "eval-'
uate the expression to the right of the equal sign and assign this
value to the variable on the left." Thus, the statement L=L+ 1 .
means "set L equal to a value one greater than it was before."
Input/ Output Statements and Functions

Input/ output statements allow the user to bring data into a
program and output results or data at any time during execution.
THE INPUT STATEMENT
The INPUT statement is used when data is to be supplied by
the user from the terminal keyboard while a program is executing
and is of the form:
(line number) INPUT xl, x2, ... , xn
where xl through xn represent variable names. For example:
25 INPUT A
This statement will cause the program to pause during execution,
print a question mark on the terminal console, and wait for the
user to type in a numerical value.
The following rules apply to the use of the INPUT statement.
Rule
1. The following characters are recognized as acceptable when
inputting numeric data:

+ or- sign
digits 0 through 9
,6-15

the letter E
leading spaces (ignored)
. (first decimal point)
All other characters are treated as delimiters for separating
numeric data.
.
10 INPUT

A~ B, C~ D~ E

•
•
•
RUNNH
?10~32A16~8

READY

In the above example, A=10, B=32, C=16, D=8, and E=1.
2. When inputting numeric data, two delimiters read in succession imply that the data between the delimiters is 0.
10 INPUT

A~ 8~ C" D, E

•
•
RU\JNH
?5" i0n i2, i5

READY

In the above example A=5, B=10, C=O, D=12, and E=15.
3. In response to an INPUT statement the user can provide
more data than is requested by the INPUT statement. The
remaining or unused data is saved for subsequent use by the
next INPUT statement. The question mark (?) is not printed
until the program is out of data.
4. When inputting string data, all characters are recognized as
part of the string. See ALPHANUMERIC INFORMATION
(Strings) for further information relating to strings.
THE PRINT STATEMENT
General
The PRINT statement is used to output results ~f computations,
6-16

comments, values of variables, or plot points of a graph on a
terminal. The format is:
(line number) PRINT expression
When used without an expression, a blank line will be output on the
terminal. For more complicated uses, the type of expression' and the
type of format control characters (comma or'semicolon) following
the word PRINT determines which formats will'be created.
In order.to have the computer print out the results of a computation, or the value of a variable at any point in the program; the user
types the line number, PRINT, and the variable name(s) separated
by a format control character, in this case, commas:
5 A=16 B=5 C=4
10 PRINT A, C+B, SQR(A)
15 END
The PRINT statement may also be used to output a message or line
of text. The desired message is simply placed in quotation marks in
the PRINT statement as follows:
10 PRINT "THIS IS A TEST"
When line lOis encountered during. execution, the following will be
printed:
THIS IS A TEST
A message may be' combined with the result of a calculation or a
variable as follows:
80 PRINT "AMOUNT PER PAYMENT="'R
,
.

Assuming R=344.961 when line 80 is encountered during execuo:.
tion, this will be output as:
AMOUNT PER PAYMENT -; 344.961
The PRINT statement can also cause a constant to be printed on
the console. For example:
10 PRINT 1.234, SQR(10014)
will cause the following to be output at execution time:
1.234

100.07
6-17

Any algebraic expression in a PRINT statement will be evaluated
using the current value of the variables. Numbers will be printed
according to the format specified in the section entitled PRINTING
NUMBERS.
Format Control Characters
In OSj8 BASIC, a terminal line is formatted into five fixed zones
( called print zones) of 14 columns each. A program such as:

5 A=2.3"J3=21"'"C=156.75 "'-D= 1. 134 "'-E=23.4
10 PRINT A,B,C,D,E
15 END
where the control character comma (,) is used to separate the variables in the PRINT statement, will cause the values of the variables
to be printed using all five zones.
RUNNH

2.3

156.7 ':J

1. 134

READY

It is not necessary to use the standard five zone format for output.
The control character semicolon (;) causes the text or data to be
output immediately after the last character printed.
The following example program illustrates the use of the control
characters in PRINT statements.
5
READ A,B,C
10 PRINT A,B,C,At2,Bt2,Ct2
15 PRINT
20 PRINT AJ B; C; At 2; Bt 2; Ct 2
25 DATA 4,5,6
30 END
RUNNH
4
5
36
4·

READY

6-18

As this example illustrates, when more than· five variables are listed
in the PRINT statement, OS/8 BASIC automatically. moves the
sixth·
. number to the beginning of the next line.
.

Printing Numbers
For any format (integer, decimal, or E-type) OS/8 BASIC prints
numbers in the form: -

sign number space
where sign is either minus (-) or blank (for plus) and a blank
space always trails the number.
10 A=64'B=- 32'C=72·
20 PRI N T A; B; C
21 END
READY
RUNNH
64 - 32

READY

PRINT Used With INPUT
Another use of the PRINT statement is to combine it with an
INPUT statement so as to identify the data expected to be entered.
As an e;x:ample, consider the following program:
10 REM -

PROGRAM TO C(J.1PuTE ·INTEREST PAYMENTS

20 PRI NT "r NTEREST I N PERCENT";
25 INPUT J
26 LET J=J/100
310 PRINT "AMOUNT OF LOAN";
35 INPUT A
40 PRI NT "N UM BER OF YEARS to;
45 INPUT N
50 PRINT "NUMBER OF PAYMENTS PER 'fEAR'"
55 INPUT M
60 LET N=N*M
65 LET I =J 1M
70 LET B= 1+1
75 LET R=A*1 I( 1-1 /BtN)

6-19

78 PRINT
.
80 PRINT HAMOUNT PER PAYMENT
R
85 PRINT "TOTAL INTEREST
="; R*N-A
88 PRINT
90 LET B=A
95 PRINT" INTEREST
APP TO PRIN
100 LET L=B*I
110 LET P=R-L
120 LET B=B-P
130. PRINT L,P,B
140 IF B>=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: I I
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

X t 2= 1
X t 2= 25
X t 2= }0e,
X t 2= 225
X t 2= 400
X t 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} x

(line number) IF vI <relation>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

=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

[ ~~~;
[

[NEXT
[ [

FOR
FOR

FOR

NEXT
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

'L ,-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

18-MAR-7 L!

10 REM - PROGRAM DEMCNSTRATING .READING
11 REM - Of SUB~CRIPT£D VARIABLES
15 DIM A(5).rB(2 1 3).
16 PRINT "An) WHERE A= 1 TO 51"
2 0 f OR I = 1 TO 5
25 READ A( I)
30 PRI NT A( I ) 1
35 NEXT I
38 PRINT
39 PRINT
L!0 PRINT "B( I IJ) WHERE 1=1 TO 2:"
41 PRINT"
AND J= 1 TO 3:"
42 f OR I = 1 TO 2
43 PRINT
44 fOR J= 1 TO 3
48 READ B(IIJ)
50 PRINT B<IIJH
55 NEXT J
56 NEXT I
•
60 DATA 112131415161718
61 DATA 8 I 7 I 61 51 41 3121 1
65 END
READY
RUNNH
ACI) WHERE A=l TO 5.;
1 2
3
L!
:,
BCl,J>

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 REM - MATRIX CHECK PROGRAM
1 5 Dl M A< 6, 10}
20 FOR 1=0 TO 6
22 LET A<I,0)=I
25 FOR J=0 TO 10
28 LET AC0,J)=J
30 PRINT ACI,J)J

35 NEXTJ
40 P~'INT
45 NEXT I
50 END
REt&DY
RUi'JNH
!2l

'"'

3
4
5
6

0
0
0
0
0
0

2
/2)

0
0
0
0
£1

3
0
0
0

0
£1
0

/2)

£1

0
£1
0

':
0
0
0
0
[1

(2)

7
0
0
0
0
£1
0

"
.....

/2)

0
0

eo
(1

0
0

(),

€I
0

READY

Notice that a variable assumes a value of zero until another
value has been assigned. If the user wishes to conserve core space
by not making use of the extra variables set up within the array, he
should set his DIM statement to one less than necessary, DIM
A(5,9). This results in a 6 by 10 array which may then be refer, enced beginning with the A(O,O) element.
More than one array can be defined in a single DIM statement:
10 DIM A(20), B(4,7)
This dimensions both the list A and the matrix B.
6-32

A number must be used to define the maximum. size 'of the array.
A variable' inside the parentheses is ,Dot acceptable and will result
in an error message by BASIC at compile time. The amount of
user core· not filled by the program will determine the amount of'
data the computer can accept as input to the program at any. one
time. In some programs a TB error (too'big) may occur; indicating,
that core will not hold an array of the .size 'requested. In that event,
the user should change his program to process part of the data in
one run and the rest later. .
NOTE'
If a subscripted variable is not defined by
a DIM statement; the variable is assigned an
array size· of ten.
OS/8 BASIC FUNCTIONS AND SUBROUTINES
General Information On OS/8 BASIC Functions
OS/8 BASIO~provides a number of-functions, as part':ofthe
language, which' perform_ calculations. The use of these functions
eliminates the need for. writing small programs to perform the
calculations. Functions have a three letter call name, .followed by
an argument, X, which can be a number, variable,' expression or
another function. Generally, functions may be used anywhere a.
number or a. variable is legal in a mathematical .expression.
The following OS/8 BASIC functions are discussed in this chapter.
Meaning

Function
SIN(X)
COS(X)
ATN(X)
EXP(X)
LOG(X) .
RND(X)
ABS(X)
lNT(X)
SGN(X)
SQR(X)
FNA(X)
TRC(X)

Sine of X (X is expressed in radians)
Cosine of X (X is expressed in radians)
Arctangent. of X (result expressed in radians)
eX (e=2.718282)
Naturallog of X (log){)
Random number
Absolute value of X (IXI)
Integer value of X
Sign of X - assign a value of +1 if X is positive,
o if X is zero, or ·-1 if X is negative
Square root of X (X)
User-defined function
Trace' function - Used for debugging OS/8
BASIC programs.
6-33

In_ addition, there are a number of other functions provided by
OSj8 BASIC, which include printing functions and string handling
functions.
Function
PNT(X)}
Printing functions
TAB (X)
I
LEN(X$)
ASC(X)
CHR$(X)
VAL(X)
String handling functions
STR$(X)
POS(X$, Y$ ,Z)
SEG$(X$,Y:Z)
DAT$(X)
Arithmetic Functions

THE RANDOM NUMBER FUNCTION - RND(X)
The RND(X) function produces pseudo-random numbers between 0 and 1. The argument X is a dummy argument and can be
any number.
If the user wants the first 20 random numbers, he can write the
nrncrr':ltn chnu,"
hplnu, ","rl 6"''''
opt ")f\
rlpf';1:'n",lc
u .......
"'.A...1. v ......... \J Y"
... V clv_rllolt
..., ...
......... e,.a. ... """",,",..I.A...l...l.,,,,,.&u.

1"'" . . . . 0 .............. .1.

~:I..

"",,'&'..1.'-10

'\.J

10 FOR L=l TO 20
20 PRINT RND(X).
30 NEXT L
40 END
READY
RUNNH
0.361572
0.539795
0.125244
0.440186

0.332764
0.8479
0. 389404
0.970947

0.633051
0.026123
0.974853
0.285889

0.350342

0.670166

0.~4126

(0.934326

~.~163~7

~. 46508~

~"'867432

(0. 178467

READY

A second RUN gives exactly the same sequence of numbers as the
first RUN; this is done to facilitate the debugging of programs.
If the user wants 20 random one-digit integers, he can change line
20 to read as follows:
6-34

20 PRINT INT< 10*RND
RUNNH

<X»,

The results will be as follows:
3

5
4

3
8
3

9
2

'3
5

5
8

6
9

"4
1

READY
,

To vary the type of random numbers (20 random numbers ranging
from 1 to 9, inclusive), the user can change line 20 as follows:

20 PRINT INT<9*RND<X)+1>.;

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:
1 0 REM - I N T fUN CTI ON EX AM PL E
20 PRI NT "NUMBER TO BE ROUNDED"';
30 INPUT A
40 PRINT ''NO. OF DECIMAL PLACES:".;
50 INPUT 0
60 LET B=INTCA* 10fD+. 5)/10tD
70 PRINT "A ROUNDED =".;B
80 GO TO 20
9 0- 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<Bt2-4*A*C>
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

Without 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

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·

READY
RUNNH

% 65 %
% 70 %
% 77 %
1

% 65 %

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 %
%
% 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<INT(X»
20 INPUT AI 81 C
30 GOSUB 100
40 LET A= FNA< A>
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 PRI N T "MU ST BE 20 OR LESS"
130 GOTO LIe;
200 I F N 1 TH EN 230
210 N=N- 1
. 220 G OSUB 200
225 N=N+ 1
227 X=X*N
230 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<Y, then SEG$(X$,Y,Z) = null string
THE DAT$ FUNCTION
The DAT$ function is of the form:
DAT$(X)
The function returns an eight character string giving the current
date in the form MMjDD/YY. For example:
SCRATCH

"--

REAOY
20 PHINT DAT!;(lt)
30 END
RLJNNjoI

04/"8/74

The use of DAT$ function assumes the user has specified the
date in the OSj8 monitor command DATE. If the DATE command was not used, the DAT$ function outputs a null string (no
characters).
EDITING AND CONTROL COMMANDS
Several commands for editing OSj 8 BASIC programs and for
controlling their execution enable the user to perform such operations as:
• erase characters or lines
• list part or all of a program
• save programs on various storage devices, and
• call program from storage devices.
6-54

Correcting Programs
ERASING CHARACTERS AND LINES
Errors made while typing programs at the terminal are easily
corrected. Typing a SHIFT/O or pressing the RUBOUT key
causes deletion of the last character typed, and echoes as a back
arrow (~) on the terminaL One character is deleted each time the
key is typed. For example:
20 DEN

F~~~F

FNAeX .. ¥)=Xt 2+3*Y

The user types N instead of F and immediately notices his mistake.
He presses the RUB OUT key (or SHIFT/O) three time, which is
once for as many characters including spaces to, be deleted. He
makes the correction and continues typing the line. The typed line
enters the computer only when the RETURN key is pressed.
20 DEF FNA(X .. Y)=Xt2+3*Y

Sometimes it is easier to 'delete a line being typed and retype the
line rather than attempt a correction uSIng rubouts. Typing
CTRL/U or pressing the ALTMODE key will delete the line currently being worked on and echoes DELETED and a carriage
return-line feed. Use of the CTRL/U or ALTMODE command is
equivalent to typing rub outs back to the beginning of the line.
To delete a line that has already been entered into the computer
the user simply types the line number followed by a carriage return.
Both the line number and the line are removed from his program.
The user may change individual lines by simply typing them in
again. Whenever a line is entered, it replaces any existing line which
has the same line number. New lines may be inserted anywhere in
the program by giving them line numbers which are between two
other existing line numbers. Using these editing capabilities, the
pro'gram may.be modified and re-run until it works properly.
THE RESEQ PROGRAM
After the user has extensively modified his program, he may find
that some portions of the program have line numbers spaced so
closely together that they do not permit any further addition of
statements should he wish to do so. Renumbering the lines in the
program so as to provide a, practical increment between line num-

6-55

bers can be accomplished automatically by using the RESEQ
program. It should also be noted that the RESEQ program modifies
the line numbers in GOSUB and IF-THEN statements to agree
with the new line numbers assigned to statements by the program.
Line lengths must not exceed 72 characters.
Typically, the program would be used as follows:
SAVE DSK:SAMPLE

User saves program SAMPLE
which requires renumbering.

READY

BASIC is ready for next command.

OLD DSK:RESEQ

User calls for program RESEQ.

. READY

BASIC is. ready for next command .

RUNNH

User runs program.

FILE? DSK:SAMPLE.BA

Program asks for filename.
User responds with name of program to be renumbered.

START ,STEP? 100, 10

Program asks for a starting line
number (START) and for the increment between line numbers
(STEP). User requested that SAM..
PLE start with line number 100
and each line be incremented by
10.

READY

Renumbering is accomplished.
BASIC ready for next command.

OLD DSK:SAMPLE

User calls back his program.

READY

BASIC ready for next command.

LISTNH

User-gets listing .of program SAMPLE for further modification.

The LIST and LISTNH Commands
An entire program can be listed on the terminal by typing
LIST. ·A heading is printed before the' program itself and is of
the form:
'. FILE EX VERSION NO. DATE
6-56

For example, if the user is working on a programJlamed ,USER.BA
and wants a listing he types:
LIST
and BASIC responds with:
,USER BA 1.0
100 LET X=l

26-JUL-72

200 END
READY
NOTE
, When any OSj8 BASIC command is com'pleted, the message READY is printed at
the terminal. OS/8 BASIC- is then ready to
accept any"other commands from the user.
A part of a program may be listed by typing LIST followed by a
line number. This. causes' that line and all following lines in the
programto . be listed. For.example:
LIST 100
will list line' 100 ·and all'remaining lines ,in the 'program. Typing
CTRLjO while the listing is being printed terminates the printing
and outputs the READY'message.
The LISTNH command may be used exactly as the LIST command,but it eliminates the heading from the listing. .
The SCRATCH Command
The command:
SCRATCH
'is provided to allow the programmer to clear his storage area; deleting any commands, or a .program which may have been previously
, entered, and leaving a ~clean "area in which to work. If the storage
area is not cleared before entering a new, program, lines from. pre':'
vious programs may be executed along with the new program, causing errors or misinformation. The SCRATCH command eliminates
6-57

all old statement~ and numbers and should be used before new
programs are created.
The NEW Command

The NEW Command is used to name a program to be created
and performs an inherent SCRATCH on the storage area. The
command is in the form:
NEWFILE.EX
It assigns the filename to the program to be created. For example:

NEW USERA.BA
creates file USERA.BA.
An alternate method of naming programs is to type NEW followed
by the RETURN key. BASIC responds with:
FILENAMEThe user types the filename and extension followed by the RETURN key.
NEW
FILE NAME-USERA.BA

(.BA is assumed and need not
be typed)

NOTE
Extension .BA is assumed in the OLD,
NEW, NAME, and SAVE commands unless otherwise specified. If no extension is
specified in the OLD command, OS/8
BASIC first tries to load FILE.BA and if
unsuccessful tries to locate and load FILE
without the extension.
The OLD Command

This command retrieves a previously created file from a storage
device and places the file in the storage area of the computer. The
command is of the form:
OLD DEV:FILE.EX
For example:
OLD DTAl:SAMPLE.BA
6-58

retrieves file SAMPLE from DECtape number 1 and places it in the
storage area of the computer.
An alternate method of retrieving a file is to type OLD followed
by the RETURN key. BASIC responds with:
FILE NAME-

•

The user types the device, filename and extension followed by the
RETURN key.
OLD
FILE NAME-DTAl:SAMPLE.BA
If the device is omitted, DSK: is assumed.
--The NAME Command
This command permits the user to rename the program in the
storage area of the computer. The command is of the form:
NAME FILE.EX
Since this command' changes only the name of the storage area of
the computer-not its contents, it can be used to create two almost
identical versions of the same program. This is accomplished by
retrieving the first file, making modifications to it, and then SAVEing the modified version under the new name.
The SAVE Command
The SAVE command saves on the specified device the file
currently in the storage area of the computer. The command is of
the form:
SAVE DEV:FILE.EX
If device is omitted, DSK: is assumed. If filename and extension
are omitted, the current filename and' extension are used.
The SAVE command also provides a convenient method for
listing large programs quickly on the line printer rather than the
terminal. For example:
SAVE LPT:
will list the current program on the line printer.

6-59

The RUN and RUNNH Commands
After a BASIC program has been typed and is in core, it is ready
to be run. This is accomplished by simply typing the command:
RUN
The program heading is printed· and the program will. begin
execution. If errors are encountered, appropriate error messages
will be printed on the keyboard; otherwise, the program will run to
completion, printing whatever output was requested. When the
END statement is reached, OS/8 BASIC stops execution and
prints:
READY
If the program does not run properly, or contains an infinite loop
and, hence, will never stop, it may be terminated by typing
CTRL/C, which returns control to the OS/8 BASIC editor
(READY).
The RUNNH command suppresses printing of the heading and
may be used in place of the RUN command.

NOTE
If a program that is not SAVEd is RUN,
and for some reason is not retrievable by
LISTing, the program may be retrieved by
"'nll;~,,"

~a.l.u115

~~_

l.V.l

AT 1""\ ~1~ D A. C'Tr'I 'nrC'
\JLJ.J HIe; Ur\.Jl\"-. 'V'V J.

Tile BYE Command
The BYE command instructs the computer to exit from OS/8
BASIC and returns control to the OS/8 Keyboard Monitor. Typing a CTRL/C while in the OS/8 BASIC editor (READY) mode
also returns control to the OS/8 Keyboard Monitor.
NOTE
Never type BYE before SAVEing a newly
typed program. Unless the SAVE command
is used, the program will be lost.
FILES, FILE STATEMENTS AND CHAINING
General Information On OS /8 BASIC Files
SYSTEM DEVICES
.
The file capability provided by OS/8 BASIC allows the user to
write information into (PRINT#) or read information from
6-60

(INPUT #) files on devices other than the terminal. Devices such
as disks, DECtapes, and line printers permit the user the flexibility
and advantage of mass storage' and high speed I/O, when writing
OS/8 BASIC programs. Each device in the OS/8 system is referenced by means of its standard OS/8 permanent device name.
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.
A' fixed lengt~file is, one which is already in existence. That is,
it has been created and CLOSEd. The length of a fixed length file
is equal to the number of blocks in the file and cannot be changed.
A variable length file is a newly created file. Until the file is
CLOSEd, it is equal in length to the largest free space oh the device. When the file is CLOSEd it becomes a fixed length file equal
in length to the actual number of blocks it occupies. Unless the file
is CLOSEd, the CHAIN, STOP or END statements will cause a
loss of the file.
Data in numeric files are stored as successive three-word floatingpoint numbers (85 to each OS/8 block) with the last word in each
block unused.
Data in ASCII files are stored in standard OS/8 format (three
8-bit characters to every two words). Refer to the next section of
this chapter and the PS/8 Software Support Manual (DEC-08MEXB-D).
File Statements

OS/8 BASIC provides a number of statements for operating on
files. They include:
FILE#
PRINT#
INPUT #
RESTORE #
CLOSE:#:
IF END:#:
The statements are distinguishable from other OS/8 BASIC statements by the number sign (#) which appends the statement name.
6-61

The FILE # statement is used to open a file and is of the form:
(line number) FILEtype # numeric expression: string expression
where:
a. FILEtype is one of four possibilities:
FILEtyp~

Definition

FILE
FILEV
FILEN
FILEVN

Fixed length-ASCII
Variable length-ASCII
Fixed length-numeric
V clriable length-numeric

b. The numeric expression has a value of from one to four and
represents the internal file number for the file number being
opened and is used in any other statements referencing this
file. FILE #O.references the Teletype.
c. The string expression is either a string variable or string
constant which has a value of the form:
DEV:FILE.EX
For example, the following program:
10 LET A$="DTA 1:NETSAK.BA"
20 FILEN # 1:A$
is equivalent to:
10 FILEN #1:"DTA1:NETSAK.BA"
for opening fixed length numeric file NETSAK on DECtape number 1 and assigning it internal file number 1. If DEY: is missing
from the string expression, the devic'e DSK is assumed by default.
Only four files, (numbered 1 through 4) besides the Teletype
(FILE #0) may be open in a program at any time. However, the
ability to open and close (CLOSE#) files under program control
permits the user to access an unlimited number of files.
When selecting a FILEtype, the user shoul<;l keep in mind that
variable length files (FILEV and FILEYN) are restricted to outputting only. That is, variable length files should be used in conjunction with the PRINT# statement only. An attempt to read
6-62

(INPUT #) from a variable length file results in error message
YR. Only one FILEy or FILEVN may be active per device at a
given time.
The use of fixed length ASCII files (FILE) should be restricted
to use with the INPUT # statement, but may be used with the
PRINT # statement when the user is certain that the ASCII or
numeric data he is PRINTING (i.e., the number of characters) replaces, exactly, the ASCII or numeric data on the file. It is recommende~ that the use of fixed length ASCII files (FILE) for output
be entirely avoided.
.
The PRINT # statement writes data into files and is of the form:
(line number) PRINT#N: list of expressions and delimiters
where N is the numerical expression for a file number. For ASCII .
files, the expressions in the list can be string or numeric, and the
TAB and pNT functions can both be used. The delimiters can be
commas or semicolons and have the same meanings that they have
in the PRINT statement for the terminal. For numeric files, the
expressions may only be numeric variables separated by commas
or semicolons.
10 FILEV #1:"LPT:"
20 LET F=1
30 PRINT #F: 'TAB(28);DAT$(X)
40 CLOSE #F
50 END
This routine prints the date, starting at column 28 on the lineprinter.
The INPUT# statement reads data from files and is of the form:
(Hne number) INPUT #N: list of variables
where N is the numerical expression for a file number. The
INPUT # statement does not expect a line number on each line
of data. in the file. If one is present, it is read as data:
,

10 DIM N$(19,15)
20 FILE #1:"LARRY"
30 FOR 1=1 TO 19
40 INPUT #1: N$(I)
50 NEXT I

6-63

The above routine reads 19 strings from DSK: file LARRY.
The previous paragraph indicated that numbers may be written
into an ASCII file. The reading of numbers from an ASCII file
requ~res some precaution if the data delimiter is other than a
comma or semicolon. In line 30 of the example below,the data
written into file numb~r 1 will be separated by a carriage return
and line feed which are both written into the file. The subsequent
reading of numbers, from the file in line number 80 shows the use
of a pair of dummy arguments (C and L) to compensate for the
carriage return and line feed since they would otherwise be read
as numeric data with a value of O.
10 FILEY #1:A$
20 FOR 1= 1 TO 10
30 PRINT #1:1
40 NEXT I
50 CLOSE #1
60 FILE # 1:A$
70 FOR I = 1 TO 10
80 INPUT # 1:J ,C,L
90 NEXT I
The RESTORE# statement is of the form:

where N is a numerical expression for the file number to be reset
to the beginning. If N is equal to zero, or if # N is missing from the
statement, the DATA list in the program is reset to the beginning.
10 FILE #2: "SUSAN"
2f) INPUT #2: A,B,C,D
25 RESTORE #2
30 INPUT #2: E,F,G,H
This program uses the same values from disk file SUSAN for
variables A, B, C, and D as it does for variables E, F, G, and H.
The CLOSE# statement is of the form:
(line number) CLOSE #N
where N is the numerical. expression for the file number to be
closed. For example:
6-64

10 DIM A$(5,10)
15 FOR 1=1 TO 4
20 LET A$(I) .= "SHERY" & CHR$(I+48)
25 FILE .#I:A$(I)
30 INPUT #I:B$
35 IF B$="SANDY" THEN 60
40 CLOSE #1
45 NEXT I
50 PRINT "CANNOT FIND SANDY"
55·STOP·
60 PRINT "FOUND~SANDY"

90 END
This program searches. through four disk .files (SHERYl through
SHERY4) for the file that has SANDY as the first entry. If the
first entry in the file is not SANDY, the file is closed (statement 40)
and the next file is opened.
NOTE

The user must CLOSE# all output files before ending the program in order to prevent
the loss of data.
The IF END# statement allows the user ta determine whether
or not there has been an End-of-File detected· for the ASCII file in
question. The statement has the form:
(line number) IF END # N THEN line number
where N is a numerical expression for the ASCII file number. The
line number must refer to a line in the program._

100 IF END #1 THEN 170
6-65

170 END

If the IF END# statement is found true, the last INPUT# or
PRINT# (read or write) should be discarded.
The IF END# statement is not used to determine if more data is
available, but rather to determine if the last read or write was valid.
The first attempt, in an INPUT# or PRINT# statement, to read
or write past an end-of-file causes an abort of the I/O associated
with that read or write, and the program passes control to the next
npTfnTmp~
T'hP Cef"on~
and "nu C'l1hs.,.nu~"t
OnpT-::Itinn
y_..a."""'''.................... tn
"'''"' bp
""" ,.t'
...........
""'1
attempts, to read or write past an end-of-file, causes an RE or WE
runtime error to be printed for each syntactical item in the INPUT# or PRINT# list. To avoid a lengthy list of error messages,
avoid using long INPUT# or PRINT# lists in situations which
may approach an end-of-file. '
Core image files have been implemented under OS/8 BASIC V3.
To create a core image file from a BASIC language source, type:
'\JJL.L.I.

""""-"-

..&. ..1..1.""

'""

""""',

U.I.)

..:lULl

""J.J.

.RBCOMP
*DEV:PROG.BA/K
'llhere PROG.Bi~.. is the source. The K s"litch indicates that a core
image file is to be created. The following additional switch/option
designations apply:

If the resulting core image will never be executed on a
12K TD8E system. This saves 400 words of memory but
reduces configuration independence.

If a copy of the run-time system should be loaded into the
core image. This increases the size of the core image file
by 10-50% (exactly 15 blocks) but eliminates the need for
a file access to read in BRTS at run-time. BRTS and
overlays must still exist on the system device, when the
program is run.

Where n is an octal digit in the range 1 ~n ~m and m is
the highest memory field available on the host machine.
The highest memory field on the target machine will be n.
This may reduce· configuration independence, since the
6-66

resulting core image will not load correctly on a machine
with fewer than n+ 1 memory banks. If n is not specified,
n= 1 is assumed. If n is specified larger than m, n=m is
assumed.
In the absence of error conditions, the compiler post-processor
(BLOAD) will exit to OS/8. At this time, type:
~

.SA DEV:PROG
to create an executable core image. Additional arguments to the
save command must not be specified. The core image is· executed
by typing:
.RPROG
or
.RUN DEV:PROG
as appropriate. Any errors flagged during compilation will prevent
creation of an executable core image file.
In contrast to normal BASIC program execution, which requires a
minimum of 6 file access operations, core image file execution
requires no· more· than two file accesses; one to -read the core
image file and one to read BRTS if /B was not specified. Compiler/loader overhead is also eliminated, so that the reduction in
execution time is very significant, especially on DECtape systems.
The following error messages may occur during execution of a
BASIC core image file:
USER ERROR 1 AT nnnn
One of the files:
BRTS.SV
BASIC.AF.
BASIC.SF
BASIC.FF
was missing from the system device.
USER ERROR 2 AT nnnn
An attempt was made to load a core image file produced under the
IN option on a 12K TD8E system (without ROM).
USER ERROR 3 AT nnnn
Insufficient core to load this core image file.

6-67

When executing BASIC core image files on a DECtape system,
the following techniques will ensure minimum execution time:
1. Follow the recommended procedure for grouping calls to
functions according to the overlay in which the function
resides, to minimize overlaying at run-time. (Refer to the
section entitled THE OS/8 BASIC RUN-TIME SYSTEM)
2. Prepare a system DECtape which contains all of the BASIC
core image files, followed by:

BRTS.SV
BASIC.AF
BASIC.FF
BASIC. SF
BASIC.UF (optional)
The BASIC core image files should reside near the beginning of
the DECtape. If chaining is employed, the least frequently run
programs should appear first on the DECtape.
The CHAIN statement provides a convenient means for dividing
large programs into a series of smaller programs which are written
and stored separately, and executed in a chain. The CHAIN statement is of the form:
(line number) CHAIN "DEV:Filename.extension"
When BASIC encounters a CHAIN statement in a program, it
stops execution of that program, retrieves the program named in
the CHAIN statement from the specified device and file, compiles
the chained program and begins execution of the program. The
use of the CHAIN statement, therefore, is the automatic equivalent
of running an OLD with no header (RUNNH). The file BASIC.WS
will contain the original program in the chain and when execution
is complete, the BASIC storage area will contain the original
program.
Since BASIC removes the program which contains the CHAIN
statement from core before retrieving the chained program, t1~e
user should make certain to CLOSE# all output files that are
opened by FILE statements in the program which contains the
CHAIN. statement in order to avoid the loss of data generated l]y
the program.
6-68

A BASIC core image file may also execute CHAIN statements,
subject to the following restrictions:
1. A BASIC language source may not CHAIN to a BASIC
core image and vice versa.
2. When a BASIC language source chains to another BASIC
language source as described above, the extension of the
target" file must not be ".SV". When a BASIC core image
chains to another BASIC core image, the extension of the
target file must be ".SV". This is the standard extension for
BASIC core image files.
In general,any departure from. these procedures will cause a '~CL"
error.

NOTES
1. Control commands OLD, RUNNH, and
SAVE are described in Chapter 8.
2. If DEV: is not specified, DSK: is
assumed by default.
CREATING ASSEMBLY LANGUAGE FUNCTIONS
Introduction

OS/8 BASIC has a facility which allows experienced PDP-8
assembiy language programmers to interface their own assembly
language routines to OS/8 BASIC. This facility permits the user
to add functions to OSj8 BASIC which can operate directly on
special purpose peripheral devices. This section describes in some
detail the organization and internal characteristics of the OS/8
BASIC Run-time System (BRTS)and is intended to serve as a
programming guide for the creation of such user-coded assembly
language functions. This material. assumes the user to be familiar
with OS/8 andPDP-8 assembly language.
In addition to this section the programmer would find most useful
a listing of the OS/8 BASIC Run-time System (DEC-S8-LBASAA-LA).
6-69

The O~/8 BASIC System
The OS/8 BASIC system is divided into the following discrete
parts:

1. The BASIC editor
(BASIC.SV)
2. The BASIC compiler
(BCOMP.SV)
3. The BASIC loader
(BLOAD.SV)
4. The BASIC run-time system (BRTS.SV)
5. The run-time system
(BASIC.AF)
overlays
(BASIC. SF)
(BASIC.FF)
(BASIC. UF) (if needed)
The OS/8 BASIC editor is used to create and edit the source
program. On receipt of a RUN command, the editor creates a
temporary file called BASIC.WS, stores the source in that file, then
chains to the compiler. The compiler compiles the program into a
12-bit pseudo-code which is loaded into core along with the runtime system by -the loader. The run-time 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, and the cycle is repeated. Following is a diagram showing the files on the systems device associated with or used by each
system component.
BASIC Component

Associated
Files

Usage

Editor

BASIC.WS

program storage

Compiler

BASIC.WS
BASIC.TM

program storage
compiled code storage

Loader

BASIC.TM

compiled code storage

Run-time
System

BASIC.AF }
BASIC. SF
BASIC.FF
BASIC.UF

overlays
(if needed)

The user must avoid the filenam~s above; they are reserved for the
OS/8 BASIC System.
6-70

The OSj8 BASIC Run-tUne System
At the time the. user's BASIC program is actually being executed, the portion of the BASIC system in- control is the Run-time
System (aRTS). BRTS is also in core when user-coded functions
are executed, therefore, a knowledge of it is essential to writing
an OS/8 BASIC assembly language function. Note that the
following
sections refer frequently to specific core locations
in
.
.
BRTS by symbolic names (always capitalized). The actual value of
these symbols can be obtained from the symbol table for the
version of BASIC being used. Note that this symbol table is for a
non-EAE system; if the EAE overlay is used some of the minor
symbols will change. The major routine entry points mentioned in
this chapter, however, are the same for both systems. All diasrams
in this chapter have the lowest core address at the bottom.' This
chapter also makes use of the variable names A, A(O,O), A$, and
A$(O) to represent the general case. All references in this chapter
to "page- 0" refer to the BRTS page (Page 0, Field 0).
BRTS CORE LAYOUT
When executing, BRTS has the· following configuration:
.

INTERPRETER
OVERLAY AREA

FIELD 0

FLOATING POINT
PACKAGE
FILE TABLE
OS/8 HANDLERS OS/8 RESIDENT

FIELD 1
B

0340
0460

BRTS
.0667 7 0700
0760 o
1000

FILE BUFFERS
PSEUDO CODE

1200 o

ARRAY SPACE
FIE LDN
(WHER E N:HIGHEST CORE
FIELD IN THE
MAC HINEI

INCORE
DATA LIST
SYMBOL TABLES
OS/8 RESIDENT

6-71

N740 o OR N7600

The highest core field is used for BRTS symbol tables, storing
of the field 1 and field 2 (if non-ROM TD8/E) resident portions of
the OS/8 Monitor, the incore DATA list (data generated by
DATA statements in the program) and pseudo-code (generated by
the compiler). The bottom of the array space (marked by line A)
can exceed the field boundary and proceed into lower fields, but
this will only. happen for large programs. Note thatif the bottom of
. the pseudo-code extends below line B (12000), some file buffer
space must be sacrificed, with corresponding loss of runtime file
capabilities. As the bottom of the pseudo-code approaches 10000,
the number of files which may be simultaneously open at runtime
approaches O. At least 400 words of buffer must be free for each
file opened at runtime. The 8 file buffers and OS./8 handler areas
are allocated dyriamically at runtime in response to FILE commands in the BASIC program, and if not fully used may be used
as buffer space by the user function.
BRTS OVERLAYS
Locations 3400-4577 of field 0 serve as an overlay area, into
. which the currently needed overlay is read. The overlays consist
mainly of functions which are infrequently used, and are constructed as follows:
BASIC.AF

Arithmetic Functions
SIN, COS, ATN, EXP, FIX, FLOAT, !NT,
RND, EXPONENTIATION, SGN, SQR, LOG

BASIC. SF

String Functions
ASC, CHR$, DAT$, LEN, POS, SEG$, STR$,
VAL, Error processing, TRC

BASIC.FF

File Functions
CHAIN, CLOSE, FILE, STOP

BASIC.UF

User Function

This last overlay, BASIC.UF is reserved for user-written assern~
bly language subroutines. Each time a call to the user routine is
issued, the overlay BASIC.UF is read into the overlay buffer, and
control is dispatched to the appropriate routine.
6-72 ...

Note that the overlay driver reads in a new overlay only if the
overlay currently resident does not contain the function spe_cified
in a given function call. If the function can is for a function which
is found in the currently resident overlay,·· no overlay I/O takes
p]ace.
BRTS SYMBOL TABLES
BRTS locates variables and strings at runtime via four permanently resident symbol tables. These tables, which always r~side in
the highest core field, are the Scalar Table (for variables like A,
Bl), the Scalar Array Table (A(1),B(1,I», the String Symbol
Table (A$, Al $), and the String Array Table, (BI$(2}).

Data Fonnats

VARIABLES
Variables are· stored in core. as standard· three word floating
point numbers. The first word is a signed, two's complement exponent, while the second and third word represent the signed, two's
complement mantissa.

EXPONENT

! HIGH MANTISSA
. LOW MANTISSA

Single variables are stored as three word entries in: the Scalar Table.
Arrays are stored in core as successive three word entries, with the
first subscript varying the fastest, and A(O,O) occupying the lowest
. core address. The address and field of A(O,O) are specified in
the Scalar Array Table.

6-73

- - - - - AIO,O)
- - - - - A(1,O)
- - - - - A(2,O)

:----------,

..;-=-~=-=~-=~-==_1 A(M-2, N)

- - - - - A!M-1,N)

- - - - - A(M,N)

STRINGS
Strings are stored as 6-bit ASCII characters, with a character
count as the first word of the string. The left half of each character
word is used first, with unused characters padded with spaces (40~).
The character count is a signed, two's complement number representing the actual number of characters in the string, not the number of words devoted to that string. Each string is allocated
[INT(n~ 1)+ 1] words, where n is the maximum length specified,
in a DIM statement, whether that many words are actually used or
not.

-F I

"BASIC"

COUNT
"SA"

':,s~:;

"BRTS"

7773]

7774

I
I

COUNT--COUNT FOR
NEXT STING

COUNT
"BR"

"TS"
COUNT FOR
NEXT STRING

The mllllmum string is one character long. The address of the
count word for each string is pointed to by its entry in the String
Symbol Table.
String arrays are stored as successive strings, with A$(O) occupying
the lowest core address. Each string is allocated enough space for
its maximum length, even though all of this space may not be used.

6-74

--COUNT

INT(N+l)

_ _ COUNT

WORDS WHERE N IS
THE MAXIMUM
LENGTH OF STRING
SPECIFIED IN DIM
STATEMENT.

I
I
I

I
I

A$!N)

{

~--COUNT
b===j

NOTE
For any of the, above data types, a field
boundary may fall anywhere within any individual item. Routines that use successive
words in any data item must be careful to
check for a field boundary within. that item .
INCORE DATA LIST
. The incore DATA list is stored as sequential data items in core.
Strings again are devoted even numbers of words, and are 'prefixed by a count. There is no separator or identifier of DATA items
and the DATA list is always in the highest core field. A page 0,
field pointer to the starting address of the DATA list less 1 is
maintained at DLSTRT, and the address of the last word of the
list can be found at DLSTOP.

6-75

Example:

IN BASIC:
DATA
;t~

1, 2."THREE". 4

CORE:

STARTING
ADDRESS OF
DATA LIST

r------;

}
}>

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 TO ARRAY T A-1S : J LI E
COFIO I COF X
I

ARSTRT
FIELD 0

START OF ARRAY ...... - - - - - - - - ----,
I
SYMS OL TABL~ II

I
.1
--}NMI
~
A(O,O)

POINTER TO A/O,O)

I ~ ENTRY 2

COF Y
ARRAY SYMBOl i-----=-=-----11
M+!
iABLE ii'iELD X)

+_1_----11 J

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 X
: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:
Starting Address Operation

Function

FFADD
ADD
SUBTRACT
FFSUB
MULTIPLY
FFMPY
DIVIDE
FFDIV
INVERSE SUBTRACT FFSUBI
INVERSE DIVIDE
FFDIVI
LOADFAC
FFG~T
STOREFAC
FFPUT

FAC~FAC+OPERAND
FAC~FAC-OPERAND
FAC~FAC*OPERAND

FAC~FAC/OPERAND
FAC~PERAND-FAC
FAC~PERAND/FAC
FAC~PERAND
OPERAND~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 In AC on call to floating-point
routine.

CI.A lAC
CCA H

CD' N
TAD OPAODR
JMS I POtNTR
(UNUSED)

I~f

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

•

FFAOO
FMPYLK, FFMPV
TWO,
0002
FADDLI~,

ONE,

2000
0000
0001
2~00

IRESULT NOW IN fAC
ILINK TO ADO ROUTINE
I~INK TO F~OATING MULTIFLY
IFlOATING POINT CONSTANT
12.ft,

IFLOATING POINT CONSTANT
11.0

\ 0000
X,

• ••

• ••
• ••
0

/VARIABLE
IFLOATING POINT TEMPORARY

2. Routine to add 5 successive floating-point numbers starting
at location 0 of field 2.

START,

elA
DCA OPADDR

JMS I FCLR
lAC
Ff
DCA
•
AlOOP,
CDF 20
TAO OPADDR
" JMS I FADOLI<
MINUS5, ... 5
TAD OPAonl<

IFI~ST

OPERAND AT LOCATION"

IZEF(O FAC

ICALlS ARE MODE 2
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.

1(215,

1(212,

elA
TAD K215
JM5 I XPUT
TAD 1(212
JMS I XPUT
HLT

IL.OAD CR It.,jTO AC
ICALl XPUTCH VIA PAGE 0 lINK
ILOAD LINE. FEED INTO AC
IPUT IN BUFFER

215
212

I 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 I P1SWAP
CL.A lAC
ClF 10
JMS I 1<7700
2

FNAME

ML.T
JMS t P1SWAP
•

lAC S~OUL.O BE 0 ON CAL.L.
IRESTORE OS/8 PAGE 17&00 RESIOENT
IDEVICE • FOR SYSI IS 1

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

·
•

I( 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 I OLREAL.
DCA EXP
JMS I DLREAL
DCA HORD
JMS I DLREAL.
DCA 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.

SACP,

SAC

PL.,
MI,
FADOL.,
fSU6L,
tAL. ,

JMP I EXr;
-2014
·1511
FFAOO
FFSUB
IA

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

11HIS LOC SKIPPEO BV Fsue

/RETURN ~ITH VALUE IN,FAt

6-92

If the function is to return any value, that value should ~e 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 BPTR
TAO I lIRS
DCA DIMl
TAO 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 (V)
,Jl...1
4.....J..L.~

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

Function

FFATN
FFCOS
FFEXP
EXPON
INT
FFLOG
SGN
FFSIN
RND
FROOT
ASC
CHR
DATE
LEN

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

pas

SEG
STR
VAL
TRC
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,

SERR,

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

UD "PLUS
SZA ClA
JllIP MC
TAO JMSlOD
JMP I SEVAl
TAO SCNTV
AND 1(7700
TAO "'MINUS
52A ClA
JMP SERR
TAD JflSSUB
JMP I SEVAL
TAD EMESSA

lIS IT

",..
......
Ho I XIU
.. It"

An.

ElOOP,

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

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 E~ROR MESSAGE
IRETURN

UC:

SZA CL.A
JMP SERR
JMP t SCNTV

ITHE ~oOY OF THE FUNCTION ITSELF
PLY,

nCDF,

TAO STRlEN
JMS SCNTV
TAD I SAcP
JM5 UVAL
DCA OP1
DCA INUVE
CLl
JMS I STFINL.
DCA 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 IFFSQl
DCA INSAV
JMS t A'RGPRL
JMS I FMPYl
ARGP'Rl, ARGPQE
JMS I FPUTl
AXSQD
UC
DCA INSAV

COFU,

JMS I ARGPQL
JMS I F'GETl
COF 121
JI'IS 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 uOEF OUACD),!)l,)8(O),OUCCO),DUOCO),QUE(I1),DUF(O),DUGCD),AOCCN'
20 REM SINCE ADe IS EIGHTH FUNCTION IN PACKAGE,
30 REM IT MUST BE EIGHTH FUNCTIO~ IN UDEF
40 REM 'IRST SEVEN ARE DUMMIES
30 y.,ADC(0}
40 PRINT Y
50 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 eXP
DCA HORO
DCA LORD
TIIO 1(13
OCA EXP
JMS I FNORL
JMP I FFLOT
13

. 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 DECtape and paper tape
(8/E with KE-SE-EAE)
Run-time system save
DECtape only
BRTS.SV
image (from BRTS.BN)
Arithmetic function
DECtape only
BASIC.AF
overlay
BASIC.SF
String function overlay
DECtape only
-BASIC;FF
File manipulation over- DECtape only
lay
. 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 SYS:BRTS 0-6777
.SAVE SYS:BASIC.AF 3400-4577
.SAVB SYS:BASIC.SF 12000-13177
.SAVE 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.BN<DEV :BASIC.03
2.

To assemble the compiler:
.R PAL8
*DEV:BLOAD.BN<DEV:BLOAD.03

3. To assemble the loader:
.R PAL8
*DEV:BCOMP.BN<DEV:BCOMP.03
4. The.ron-time system source is conditionalized for PDP-8/E
with EAE. Assembly "instructions for each of the supported
configurations' follow.
6-120

To assemble for PDP-12,PDP-8, PDP-8/1 'or. PDP-8/L,
or PDP-8E without EAE, create a' source file named
NOEAE.PA with EDIT that works as follows:
EAE=O
PAUSE
Then
.R PAL8
*DEV:BRTS.BN<DEV:NOEAE,DEV:BRTS.03/K
To assemble the run-time system overlay for, PDP-8E,
PDP-8F or PDP-8/M with KE-8/E EAE option, prepare a
,file called EAE.PA that looks as follows:
,

EAE=l
PDP8E=1
PAUSE
Then:
.R PAL8
*DEV:EAEOVR.BN<DEV :EAE,DEV :BRTS.03 /K
Optimizing System Performance

There are several steps theOS/8 BASIC user. can take to speed
up BASIC execution and compilation tjmes, thus speeding up OS/8
BASIC throughput rates.
, BYPASSING THE EDITOR
The OS/8 BASIC compiler is constructed such that it will accept
any source file for input. Thus, it is possible to execute an already
existing BASIC program directly, saving the overhead of an OLD
and RUN command to the editor. The format is as follows:
.R BCOMP
*DEV:FILE.BA
If OS/8 BASIC is used in this fashion, it returns to the OS/8
Monitor on completion, rather than the OS/8 BASIC editor.

6-121

Normal Usage

Faster Equivalent

.R BASIC
NEW OR OLD-FILE

.R BCOMP
*FILE

READY
RUNNH
READY
In general, use R BASIC when:
a. Creating new programs or modifying old programs
b. Debugging old programs
UseRBCOMP:
a. To run existing programs
b. In BATCH stream to run BASIC programs
Source files for use by BCOMP must conform to the following rules:
a. There should be no blank lines.
b. Statements must be in the order in which they are to be
executed.
c. Line numbers are only required for statements that are referenced in IF, GOSUB, and GOTO statements. In other words,
if the only way a statement may be reached is for the preceding statement to be executed,. it does not require a line number. In the following example, there are no unnecessary line
numbers.
FOR 1=1 TO 10
IF 1=2 THEN 400
PRINT I
·GO TO 410
400 PRINT "TWO".
410 NEXT I
END
Note that the source file can be created in one of two ways: it
may be created in the normal fashion with the OS/8 BASIC editor
and saved (in which case all lines will contain line numbers), or it
may be prepared using any of the other OS/8 editors (EDIT,
TECO). In this second case, the user can take advantage of the
extra features supported by these sophisticated editors over the
OS/8 BASIC editor.

6-122

PLACEMENT OF BASIC OVERLAYS ON SYS:
For DECtape system users, the performance of the system can be
improved by two simple steps:
a. Use a DECtape drive other than DTAO for DSK: (via the
ASSIGN statement).
b. Place the OS/8 BASIC system files as close together on the
SYS tape as possible. The best approach is to make a "BASIC
tape" containing only the OS/8 system, PIP, and the BASIC
system image files.
Both actions have the effect of speeding up OS/8 BASIC by the
simple reduction of the tape motion required for overlaying and
compiling.
PLACEMENT OF FUNCTION CALLS WITHIN BASIC
PROGRAMS
Most of the BASIC functions and file operations reside in one of
the three system overlays. Since the system overlay driver reads in
an overlay only if the function desired is not present in the currently
resident overlay, overlaying overhead can'be reduce? by the simple
mechanism of placing calls to functions that reside in the same overlay as close as possible in the BASIC program. For example:
10 INPUT A$
20 Z$= SEG$(A$,1,6)
30 FILEN #1: Z$
40 INPUT A$
50 Z$= SEG$(A$,I,6)
60 FILEN #2: Z$

The above BASIC program uses the first six characters of a string
typed by the user as a file name to open a BASIC file. It uses the
SEG$ function, a File command, the SEG$ function, and the File
command again. Since SEG$ and FILE are in different overlays,
. the overlayer will be used four times. A faster way to accomplish
the same operations follows:
10 INPUT A$,B$
20 Z$=SEG$(A$,1,6)
30 X$=SEG$(B$,1,6)
40 FILEN #1: Z$
50 FILEN #2: X$

6-123

The above only overlays twice, saving considerable time in the program execution. The functions are grouped in the overlays as follows:
Overlay 1 (BASIC.AF):
Overlay 2 (BASIC.SF):
Overlay 3 (BASIC.FF):

SIN,COS,ATN,LOG,EXP,RND,
SQR,SGN,POWER(AiB)
ASC,CHR$,DAT$,LEN,POS,
SEG$,STR$,V AL
CLOSE,FILE,FILEN,FILEV,
FILEVN

LAB8/E FUNCTIONS FOR OS/8 BASIC
Introduction

The addition of LAB8/E functions to OS/8 BASIC enables the
user to solve a range of real-time and pseudo_ real-time problems
using a higher-level language. The benefits of approaching realtime problems using BASIC are numerous. A novice programmer
can solve problems with little or no assembly language expertise,
and in general, the programming effort required for specific problems is dramatically reduced.
'T"Le
~--ro~~L +~1~~_
.1
app
taJ\.\;,u .c1. o - s..... ",..:.cv : ... g 0a"''h ~" .... ",t;,.. ... "'''''' tA
v """,'lvi
.u.u....
mize functional flexibility rather than to stress -simplicity. Slaving
the computer to external events is accomplished by recognizing
Schmitt trigger firings. One of the design goals for the LAB8/E
functions was -to utilize memory efficiently for single precision and
displayable data arrays. Another design goal was to incorporate a
masking ability for the recognition of bit patterns when reading
digital data. This featur~ allows easy conversion of decimal data
into floating-point format when data is received from decimal devices interfaced to the LAB8/E's digital input registers (DR8-E's).
11

a~l1

jJ~\'<llJ 111

\.<

\.<11

J..UU,,",UVH

YY U>J

.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:
0<ARGUMENT~4095

Hence, negative arguments «0) will cause a fatal error, FM; .
and positive arguments greater than 4095 (>4095) 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:

3521
4400
4432
4211
4313

GET
PUT
DRI
DRO

.&AvE SYS 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

Simultane~usly

-8

9
10
11
12
13
14
15

-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<N)~ADCCN)
5 UDEF GETCM"L)"PUTCM"L)"DRICN)"UROCM"N)
6 01 M AC 342)
9 REM 10 REM
CALC 1024 PTS &. DISPLAY CN FLY.
11 REM - WHEN DCNE DISPLAY EVERY 10TH PT.
12 REM 20 USE A
22 Z=INI(0)
24 FOR N=1 TO 1024
26 Y= ( 3*N- 2) /307 1
28 X=PLY(Y)
30 W=DLY( 1024)
32 NEXT \II
34 V=DI S( 1" 1024" 10" 1>
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 Y=<2+N+l)/61.1
66 Z=PLY <Y)
68 NEXT N
70 V=DI S< I, 30, I, 1>
80 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 REM 20 USE A
22 Z=INI(0)
24 FOR N=-300 TO 300
26 Y=(N*N)/100000
28 X=PLY(Y)
30 ~;=DLY( 601>
32 NEXT N
34 V=DI S( 1.. 601 .. 10" 1>
50 REM.
51 REM - CALC A CU8I C OF 6e.. PTS g 01 SPLAY
52 REM - WHEN DCNE 01 SPLAY EVERY 10TH PT.
53 REM 60 Z=INI(0)
62 FOR N=-300 TO 300
64 Y=(~*N*N+27000000) 154000010
66 X=PLY< Y)
68 W=DL Y ( 60 1>
70 NEXT N
72 V=DI S( 1.. 601 .. 10" 1>
80 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 -

PUT NUMbERS

1-10 !NTO EUF !N THAT ORDEF·

13 REM - & READ THEM OUT IN THE REVERSE ORDER.
14 REM 20 Z=INI(0)
22 FOR N=1 TO 10
24 PRINT N
26 T=N
28 R=PUT< T"N)
30 NEXT N
32 FOR N=1 TO 10
34 N= II-N
36 P=GET< 0 .. M)
38 PRINT P
40 NEXT N
50 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 REM - USE CLK AS A 51 MPL E TI MER.
12 REM - SAMPLE CHAN 0 EvERY 4TH SEC AND PUT VAL TO TTY
13 REM - DO THIS 10 TIMES
14 REM 210 X=CLKC 3, 401010, 0)
22 I' OR 1= 1 TO 10
24 Y=CU1( 0)
26 Z=ADC( (il)
28 PRINT Z
310 NEXT I
40 REM , 4 1 REM - USE CL K A S A S I MPL E TI MER
42 REM - SAMPLE CHAN 1 TEN TU·1I~~5 & SYNC OFF ANY

6-139

43
44
50
52

REM - SCHMI TT TRI GG ER
REM X=CLK ( 4" 4000" 1)
FOR 1=1 TO 10
54 Y=CLW(0)
56 Z=ADC( 0)
58 PRINT Z
60 NEXT I
70 END

1 REM PROGRAM NAME: TEST7A.PG
2 REM 3 UDEF INICN)"PLY(Y)IDLY(N)ID1S(SIEINIX)
4 UDEF SAMCC"NIPIT)ICLK(RIOIS)ICLW(N)IADC(N}
5 UDEF GET(MIL)IPUT(MIL)IDRI(N)IDRG(M"N)
6 DHl A(342)
7 USE A
8 REt'l - D1 S.PLAY A TRIANGLE
10 Z.=INI(0~
12 FOR ~= 1 TO 30
14 Y=N/3001
16 W=PLY{Y)
18 Z=1/30ol

20 U=PLY(Z)
22 P=DLY( 118)
24 NEXT N
26 FOR N=l TO 29
27 t-1=30 -N
28 Y=N/30.1
30 W=PLY(Y)
32 Z=1/30.1
34 U=PLY(Z)
36 P=DLY(118)
38 NEXT N
40 V=D1S(1111811 1 1)
42 END

1 REM PROGRAM NAME:
TEST8A.PG
2 REM 3 UDEF INICN)IPLY(Y)"DLYCN)IDISCS"E1N"X)
4 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.

6-140

14 REM 32 USE A
34 W=INI(0)
36 W=DISCI .. 100 .. 1.. 0)
38 X=SAM(0 .. I .. 1011' .. 11')
40 Y=CLKC3 .. 1011' .. 1)
42 Z=DIS(I .. 100 .. 1.. 1>
511' END

1 REM -

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 REM PROGRAM NAME:
TST10A.PG
2 REM 3 UDEF INI<N)"PLYCY)" DLYCN) .. DISCS .. E .. N.. X)
4 UDEF SAMC C.. N.. P; T> .. CLKC R.. 0 .. S) .. CLWCN) .. ADCCN)
5 UDEF GETCM .. L) .. PUTCM .. L) .. DRICN) .. DROCM .. N)
6 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 P=GETC 35841 1>
25 PRINT P
26 GOTO 12
30 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 PRO GR.At1 NAtvlE:
TST 13A. PG
2 REM 3 REM - TEST THE OUTPUT REG-SEE THE LIGHTS LITE
4 REM - UP.
OCTAL INPUT LIGHTS THE LIGHTS AND
5 RE!1 - THE LAMP? AN INPUT OF 0 CLEARS THE OUTPUT REG
10 UDEF INICN)IPLY(Y)IDLYCN)IDISCSIEIN1X)
11 UDEF SAMCCINIP1TbCLK(R101S)ICUJ(N)IADC(N)
12 UDEF 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 FOR N= 1 TO 313
32 X=GET(13"N)
34 PRINT X
36 NEXT N
413 END

1 REM PROGRA.1I1 NA"1E:
T$T19A. PG
2 REM 3 UDEF INI<N)"PLY(Y)"DLY(N)"DIS(S"E"N"X)
4 UDEF SAM (C"N" P" T)" CLK(R"O" S)" CL\\T(N)" ADC (N)
5 UDEF GET(M" L)" PUT (M"L)" DRI (N)" DRO (M"N)
6 DH1 A(16)113 REM - SAMPLE CHAN 13 513 TIMES; SYNC 0 IT scmHTT,;
11 REM - Ie INTERRUPTS/SEC;\\THEN DONE DISPLAY TILL· fN;
12 REt1 - THEN \\TRITE OUT DATA TO DTAt;
20 USE A
21W= IN I (13)
22 vT=DIS(I"513,, 1,,13)
24 X=SAM (13" 1" 513" I1n
26 Y=CLK(3"le4,,1>
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 <I )
34 NEXT I
36 CLOSE 11
38 REM - DISPLAY A PARABOLA
413 P= IN I (e)
4R FOR N=-25 TO 25
44 Y=(N*N)/625.1
46 X=PLY(Y)
48 'toJ=DLY(51)
50 NEXT N
52 V=DIS(1,,51,,1,,1)
54 REM - READ DATA BACK IN & DI SPLAY I T AS BEFORE"
56 FILEN 61:"DTAI:SAM.DA"
58 FORI=0 TO 16
60 INPUT 111: A( 1)
62 NEXT I
64 W::INI(0)
66 Z=DIS(1"50,,1,,I)
68 ,END

1 REM -

PROGRAM NAME:

TST20A.PG

2 REM 3 UDEF
4 ·UDEF
5 UDEF
Ie DIM

INI(N)"PLY(Y)"DLY(N)"DIS(S"E"N"X)
SAM (C"N" P" T)" CLK (R"O" S)" CLW(N)" ADC (N.)
GETCM"L)"PUT(M"L)"DRI(N)"DRO(M"N)
X(I13e)"YC100)"A(67)

6-145

i l REM - Jl=BINS IN LATENCY(HEPOCHS TILL DONE)
12 REM - Tl=BIN WIDTH(TIH) IN MS(HMS/CLK O.F.)
13 REM - T2=BIN WIDTH OF LATENCY(ICLK 0.F./EPOCHS)
16 PRINT "J1"Tl"T2?"
18 INPUT Jl"Tl"T2
20 1=0
21 J=0
22 K=0
23 Y=CLKe3"Tl" 1)
25 Z=CLW(0)
30 IF Z=0 GOTO 100
32 1 F Z<0 GOTO 36
34 IF Z<8 GOTO 20121
35 GOTO
38
36 IF Z>-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 Z=X(I)
554 Y=Z/(Q+l)
555 'YJ=PLY(Y)
556 NEXT I
598 REM - GET LARGEST LATENCY VAL TO BE
599 REM - USED AS A SCALE FACTOR FOR DISPLAY
600 Q=0
602 FOR 1=0 TO 100
604 .Z=Y( I)
606 IF Q>=Z GOTO 610
608 Q=Z
610 NEXT I
699 REM - SCALE ALL LATENCY VALS FOR MAX DISPLAY
700 FOR 1=0 TO 100·
702 Z=Y( 1)
704 Y=Z/(Q+!)
706 l.t,T=PLY(Y)
708 NEXT I
710 REM - DISPLAY 'TIH'
711 V=DIS(1.,101.,l.,l)
712 REM - D! SPLAY LATENCY
720 V=DIS(102~2021111)
725 REN - DISPLAY BOTH 'TIH' & LATENCY SIDE BY SIDE
726 V=DIS(1~20211~1)
800 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<DTAn:BASIC.UF /1
(where n=0,1,2, ... ,7)
*tC

•

Papertape users:
.
Use the ABSLDR to read into core the user overlays which
are in binary format on the paper tape, provided with the
software kit. Then create a 'save file' on the system device .
. .RABSLDR
*PHR:$t (where $ symbolizes striking the ALT MODE
key)
.SAVE SYS BASIC.UF 3400-4577
6-147

LAB8/E Function Summary
Table 6-4

LABS/E Function Summary

Function

Explanation

INI(N)

Locate the address of the user array and initialize a
pointer to start of the array_ N is a dummy argument.

PLY(Y)

Y-data created \ria the BASIC program is deposited
into the user array sequentially. O~Y <.0

DLY(N)

Used in conjunction with PLY, the scope is refreshed
with the contents of the user array after each point
is processed. 1~N ~ 1024 and N specifies the maximum number of points to be eventually displayed.

DIS(S,E,N,X)

Meaning #1 (X=O). Set up parameters to display
ADC data once sampling begins.
Meaning # 2 (X=O). An array of y-data is to be displayed immediately. In both cases, the display begins
with point S of the array, and every Nth point is displayed while not exceeding the desired point E.

SAM(C,N,P,T)

Used to set up parameters for subsequent sampling
of the ADC's (T=O) or sampling of digital input
1'egisters (Tt=O). C is the first channel # or digital
input register #. N is the number of consecutive
£'1-."' ...... 1"1" Ar
Tprr,dpro;:
tn O;:~Hnnlp
P i~
thpv'"
- 0 .......... _ .....................
_ ....... ,t" .. -........
... ...........
"""..I...I._.l."A"~.lU

£.

nllmher
,;- of
-----~-~--

samples per channel or register.
CLK(R,O,S)

Set up the clock for AID sampling, digital input
sampling or for use as a simple timer. R is the desired
rate, 0 is the overflow count and S activates the
Schmitt triggers.

CLW(N)

This function returns to the caller a number, indicating whether the clock overflowed or a Schmitt
trigger fired and whether these occurred before or
after CLW was called.

ADC(Ni

This function is issued any time the. user wishes to
sample AI D channel N.

GET(M,L)

A twelve (12) bit number from the user array at
location L is masked with the number M and returned to the caller.

PUT(M,L)

A floating point number, M, is fixed to 12 bits and
stored in the user array at location L.

6-148

Table 6-4

LABS/E Function Summary (Cont.)
Explanation

Function
DRN(N)

This function is used any time the user wishes to sample a digital input register N.

DRO(M,N)

The bits of digital output register N are set via the
value of M.

6-149

6-150

·7
~ortran II

INTRODUCTION
OS/8 FORTRAN is an improved version of the 'paper tape 8K
FORTRAN. OS/8 FORTRAN contains such added features as·
Hollerith constants, implied DO loops, chaining, mixing of SABR
and FORTRAN statements, and device-independent I/O.
It is assumed that the reader is familiar with the basic concepts
.of FORTRAN programmil1g. Several excellent elementary texts
are available (such as FORTRAN \ Programming by Frederic
Stuart,published by John Wiley and Sons, New York; 1969, and
A Guide to FORTRAN Programming by Daniel D. McCracken,
.published by John Wiley and Sons, New York) if review is needed.
Calling and Using the OSl8 FORTRAN Compiler
The user calls the FORTRAN compiler by typing:
R FORT

in reply to the dot generated by the Keyboard Mollitor. When the
Command Decoder prints an asterisk at the left margin, the user
types the appropriate device designations, I/O files, and any of
the acceptable specification options allowed for 8K FORTRAN.
A carriage return is used to terminate a command string and begin
compilation.
The line to the Command Decoder consists of 0 to 3 output files,
1 t09 input files, and any of the available options. The format of
the command line is:

*BINARY,LISTING,MAP <INPUT/OPTION(S)
The first output file holds the binary output in relocatable binary
format. If no extension is specified, the extension .RL is assumed.
7-1

If a binary output file is not indicated in the command line, then
no binary output will be generated. (An exception to this occurs'
when either the IL or 10 options are used; this is explained in the
section describing the individual options). The second output file
- contains the listing; if no extension'is specified, the extension .LS
is assumed. If no listing file is specified, a listing will not be generated. The third output file is the Linking Loader output, and,
unless otherwise specified, this file assumes the extension .?'vfP.
(This output is produced by use of the 1M; IV and jP options,
which are discussed in the section of this chapter concerning the
Linking Loader.) 1 to 9 input files are available with OS/8 FORTRAN, although ordinarily only 1 is used. The default extension
for input files is .FT.

FORTRAN OPTIONS
The following table provides a list of the options which are
available under OS/8 FORTRAN. In addition to these, the IN
and IS options to the SABR Assembler may be specified to the
FORTRAN compiler, and' options to the Linking Loader other
than IL may be used. (The us~r is referred to the respective sections for details.)

Table 7-1

FORTRAN Options

Option

Meaning

Load and execute the file. The Linking Loader is
called, the binary output file is loaded and executed.
(If a binary file is not specified, a temporary file
named FORTRL.TM is created and stored on the file
device. This file is loaded into core and then deleted
from the file device.) If a starting address is not specified (using the options described under the Linking
Loader) control is sent to the program entry point
MAIN (the. FORTRAN compiler gives this name
. automatically to -the main program ..

Keep the file FORTRAN.TM as a permanent file.
The' FORTRAN compiler produces an output file
named FORTRN.TM on the system device. This
file is the FORTRAN source program converted into
SABR assembly language, and serves as input to the
8K SABR assembler, which is automatically called by

7-2

Table 7-1

FORTRAN Options (Cont.)

Option

Meaning
the compiler. The file FORTRAN.TM is then deleted
unI,ess the / K option has been specified. The / K option saves the file as a permanent file, allowing future
editing and assembling.

Load, but do not start execution. Call the Linking
Loader at the end of the assembly and load the specified binary file. (If a binary output file is not specified, then the temporary file FORTRL.TM is loaded
into core and deleted from the file device.) When
using the / L option, the user has· the choice _of terminating the command string with either an· ALT
MODE or a carriage return. If ALT MODE is typed,
the Loader returns to the Keyboard Monitor with a
core image in core; while the RETURN key instructs
the Loader to ask for more input.

EXAMPLE PROGRAM
The following example illustrates the ease with which a FORTRAN program can be executed under OS/8. The program TEST
has been created with the Symbolic Editor and saved on device
SYS:

C
C

15
20
25

FORTRAN DEMO 'TEST'
COMPUTE AND PRINT POWERS OF TWO
DIMENSION A( 16)
WRITE (1,15)
FORMAT (/'POWERS OF TWO •• EXAMPLE PROGRAM'/)
DO 20 N= 1, 16
ACN)=2.**N
WRITE (1,25) (N,A(N),N=1,16)
FORMAT ('2** 'I2'='F10.2)
CALL EXIT
END

By issuing the following commands, TEST is loaded and executed;
execution is automatic with the /G option:
7-3

• R FORT
*TEST/G
POWERS OF TWO •• EXAMPLE PROGRAM
2**
2**
2**
2**
2**

2**

2**
2**
2**
2**
2**
2**
2**
2**
2**
2**

2.1010
4.1010
8.1010

1=
2=
3=
4=
5=

32.1010

&..u
-

£ II
nn
U""i. ~."u

7=
8=
9=
110=
11 =
12=
13=
14=
15=
16=

128.1010
256.1010
512.1010
11024.1010
21048.1010
41096.1010
8192.1010
16384.1010
32768.1010
65536.100

16.00

FORTRAN assembles one main program or subroutine per call.
A job with multiple subprograms is run by compiling each routine
separately and combining them with the Linking Loader.
Typing a CTRL/C (tC) at run time during a non-compute
bound job will return control to the Keyboard lYlonitor. Typing
.ST at this point will restart the user's FORTRAN program. If tC
is typed when compiling a program, FORTRAN will have to be
recalled.
EXAMPLES OF FORTRAN I/O
SPECIFICATION COMMANDS
Example 1:
..!,R FORT
,!DTA1: TEST/G

The input file TEST.FT (or TEST) on DT Al is compiled, the
output stored in FORTRN.TM on the system device, and SABR
is called. SABR uses FORTRN.TM as input and outputs the assembled file into FORTRL.TM, deleting the old FORTRN.TM.
The /0 option specifies that the Linking Loader then loads
7-4

FORTRL.TM and the Library Subroutines, deletes FORtRL.TM
upon loading, and sends control to the entry point MAIN.
Example 2:
• R FORT
*MATRIX<MATRIX.AB/G/U

The input file MATRIX.AB on DSK is compiled and the output
stored in SYS:FORTRN.TM. SABR is called and assembles
SYS:FORTRN.TM, putting the relocatable binary output into
DSK:MATRIX.RL, deleting the file FORTRN.MT; The IG option
specifies that the Linking Loader then loads MATRIX.RL and the
Library Subroutines, and then prints on the teleprinter (via IU)
a list of undefined external symbols and a count of the unused
pages in each memory field.
Example 3:
.:.R FORT
!~~LPT:<INPUT/L/M

-*
The FORTRAN Compiler compiles and SABR assembles the
file DSK: INPUT .FT (or INPUT), outputting the binary file as
SYS:FORTRL.TM. The Linking Loader is automatically called
.' (/L) to load SYS:FORTRL.TM into core and delete that file from
SYS. The Linking Loader puts a full loading map on the LPT
device (1M). The Loader then asks for another command string.
If the line had been terminated with the ALT MODE key instead
of the RETURN key, control would be returned to the Keyboard
Monitor after loading.
Example 4:
!oR FORT
*SUBl<SUBl
:R FORT
iSUB2<SUB2
!R FORT
!MAIN/L
!SUBl~SUB2/G

The subroutines and the MAIN program are each compiled separately, and the MAIN program is loaded but not executed (as. the
IL option indicates). The Linking Loader is called at the end of
7-5

the assembly and waits for more input. The /G option is used to
load the FORTRAN Library Subroutines and initiate execution of
. the MAIN program.
Example 5:
• R FORT
~DTA5:S0URCE/L

The file SOURCE on DT AS is compiled, assembled, and loaded
but not executed.
Example 6:
• R FORT
iDTA1:PROG,PTP:,PTP:<DTA1:PROGCNMG)

For those users with DECtape systems, keeping the source program on a non-system DECtape and putting the binary on a nonsystem DECtape gives the best possible results in terms of
minimizing tape motion. The above file, PROG, is loaded and
executed. The binary is stored on DT At under the' name
PROG.RL, and the symbol table, the map of the loaded program
and the count of the free pages in each field are punched onto
paper tape.
In DECtape systems, excessive DECtape motion can also be
eliminated by storing LIBS.RL on a non-system tape. The user
would then specify to the Loader:
!DTA2:LIB8. RL/L

Using FORTRAN or SABR with the Interrupt On
SABR code can be run with the interrupt on, providing the user
supplies his own interrupt handling code. That code which is executed when the interrupt is off must not call any of the SABR
subroutines and must be independent of all SABR or library subroutines and linkage subroutin:es. With the interrupt on, the user
should not call exit routines or do any generalized (device-independent) I/O, unless those routines are modified to make allowances for interrupts.
7-6

Using P AL8 with SABR or FORTRAN'
It is possible to call PAL8 subroutines from a SABR or FORTRAN program. The user should build a core image of the running
FORTRAN or SABR program and return to the Keyboard Monitor by typing $ (ALT MODE key) on the last Linking Loader
Command. He should then save the core image. The core image
file (.SV) can be used as input to the Absolute Loader (ABSLDR)
with the II option, followed by the binary of the P AL8 routine.
For example:
.:..R ABSLDR
!DTA7:CHAIN2.~V/I

!PALSUB.BN/G$

The above calls the Absolute Loader, loads the core image
CHAIN2.SV and then merges the PALSUB.BN program with it.
Execution starts at location 200 and, when completed, the system
returns to the Keyboard Monitor for further instructions.
FORTRAN Data Files
When doing FORTRAN output onto DECtape or disk into a
file which is to be read only as a data file by another FORTRAN
program, a significant time saving can be obtained by using A6
format to output floating-point variables and A2 format to output
integer values. The same format specifications must be used when
the data is read. The data file is not an ASCII file and should not
be edited with EDIT. The file should only be moved by PIP in
image mode (II option) .
The following caution sh~uld be observed concerning programs
which may have been written and compiled with a previous ver'sion of OS/8 FORTRAN:
CAUTION
A FORTRAN compiler and its corresponding Library constitute an interlocking set of
programs. No user should attempt to compile a program under OS/8 and load it with
the paper tape FORTRAN, or vice versa.
Similarly, programs developed with the current FORTRAN compiler should not be run
under an old FORTRAN system.
7-7

FORTRAN II SOURCE LANGUAGE

Character Set
The following characters are used in the FORTRAN language. 1
1. The alphabetic characters, A through Z.
2. The numeric characters, 0 through 9.
3. The special characters:2

t
"
$
%
&

(
)

[
]

#
?

<
>

(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 + or a - sign are also arithmetic
expressions. For example:
+X

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

<lX .. 'THE FOLLO~ING DATA IS GROUPED INTO THREE
1 PARTS UNDER THE HEADINGS X.. Y, AND Z.')

FOR~AT

There is no limit to the number of continuation lines which may
appear. However, one restriction is that an implied DO loop must
not be broken, but must be on one line. For ease in program correction, it is recommended that continuation lines be minimized.

Comments
The letter C in column 1 of a line designates that line as a com~
ment line. A comment appears in a program listing but has no
effect on program compilation. Any number of comment lines may
. appear in a given program, and comments that are too long for
one line may be continued by placing a C in the first column of the
next line. A comment line may not appear between another line
and its continuation.
FORTRAN statements are of five types:
1. Arithmetic, defining calculations to be performed;
2. Input/Output, directing communication between the program and input/output devices;
3. Control, governing the sequence of execution of statements
within a program;
4. Specification, describing the form and content of data within
the program;
5. Subprogram, defining the form and occurrence of subprograms and subroutines.
Each of these five types is explained in the following paragraphs.
7-15

Arithmetic Statements
Constants and variables, identified as to type and connected by
logical. and arithmetic operators form expressions: one or more
expressions form an· arithmetic statement. Arithmetic statements
are of the general form:

V=E
where V is a variable name (subscripted or nonsubscripted), E is
an expression, and = is a replacement operator. The arithmetic
statement causes the FORTRAN object program to evaluate the
expression E and assign the resultant value to the variable V. Note
that = signifies replacement, not equality. Thus, expressions of the
form:
A=A+B
A=A*B

are quite meaningful and indicate that the value of the variable A
is to be changed.
For example:
Y=l.l*Y
P=X**2+3.*X+2.0
X(~)=EN*ZETA*(ALPHA+EM/PI)

The expression value is made to agree in type with the variable
before replacement occurs. In the statement:
META=W*(ABETA+E)

since MET A is an integer and the expression is real, the expression
value is truncated to an integer before assignment to META.

Input/ Output Statements
Input/Output (I/O) statements are used to control the transfer
of data beween computer memory and peripheral devices and to
specify the format of the output data. I/O statements may bedivided into two categories:
7-16

1. Data transmission statements, READ and WRITE, specify
transmission of data between computer memory and I/O
devices.
2. Nonexecutable FORMAT statements enable conversion between internal data (within core memory) and external data.
DATA TRANSMISSION STATEMENTS
The two data transmission statements, READ and WRITE, accomplish input/output transfer of data listed in a FORMAT statement. The two statements are of the form:
,READ (unit; format) I/O list
WRITE (unit, format) I/O list
where unit is a device designation which can be an integer constant
or an .integer variable, format is a FORMAT statement line number, and the I/O list is a list specifying the order of transmission of
the variable values. During input, the new values of listed variables
may be used in subscript or control expressions for variables appearing later in the list.
For example:
REA D ( 2 .. 1 000 ) L .. A ( L }') B ( L + 1 )

reads a new value of L and uses this value in the subscripts of A
and B; where 2 is the device designation code, and 1000 is a
FORMAT statement number.
An element in an I/O list can take one of the following forms:
1. Arithmetic expression: expressions more complicated than a
single variable (which can be subscripted) are meaningless
in an input operation.
2. The name of an array (1 or 2 dimensional) : this indicates
that every element of the array ~s to be transmitted. Elements
are transmitted in the order in which they are stored in core.

For example:
A(2,2)
(1,100) A

01 IVJENS1 ON

READ

7-17·

reads:

3. Implied DO Loops of the form:

repeat the list elements (Sll) with the value of i being equal
to ml through m2 having an optional step value of m3. The
m's are integer constanfs or variables, i is an integer variable,
and Sl-Sll are the I/O list elements (possibly including an implied DO loop). For example:
DIM EN S I ON A ( 3 .. 6 )

WRITE (1 .. 100) I .. (A(J .. IlJ=I .. 3)

will output the values:

It is important to remember that when using implied DO
loops, the entire implied DO loop must be on the same input
line or card. An implied DO Joop cannot be continued onto
the next line with a continuation character.
If no I/O list is specified for a WRITE statement, then information is read directly from the specified FORMAT statement
and written on the device designated.
Data appears on the external device in the form.of records. 3 All
information appearing on input is grouped into records. On output
to the printer a record is one line. The amount of information contained in each- ASCII record is specified by the FORMAT statement and the I/O list.

3 This should not be confused with the OS/8 record, which is equal to 25610
words (2 DECtape blocks with the 129th word of each block ignored.)

7-18

Each e:xecution of an I/O statement initiates the transmission of
a new data record. Thus, the statement:
READCl,100)FIRST,SECOND,THIRD

is not necessarily equivalent to the· statements below where 100 is
the FORMAT statement referenced:
READCl,100)FIRST
READ(1,100)SECOND
READCl,100)THIRD

In the second case, at least three separate records are required,
whereas, the single statement
READ (d, f) FIRST, SECOND, THIRD
may require one, two, th~ee, or more records depending upon
FORMAT statement f.

If an I/O statement requests less than a full record of information, the unrequested part of the record is lost and cannot be re'covered by another I/O statement without repositioning the record.
If an I/O list requires more than one ASCII record of information, successive records are read.

READ Statement
The READ statem~nt specifies transfer of information from a
selected input device to internal memory,corresponding to a list·
of named variables, arrays or array elements. The READ statement assumes the following form:·
READ (d, f) list
where d is a device designation which may be an integer constant
or an integer variaole, f is a· FORMAT statement line number, and
list is a list of variables whose values are to be input.
The READ statement causes ASCII information to be read from
the device designated and stored in memory as values of the
variables in the list. The data is converted to internal form as
specified by the referenced FORMAT statement.
7-19

For example:
READC1,15>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 IS made between E and F format on input.
Thus:
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
for ::In lntpopr v::Irl::1hlp. thp. m::lximnm j.;: two·
--i", ';:lY
---- rh::lr::lrtpr..: ----- -----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

Octal

. ASCII

M1
M2
M3
M4

-928
-864

- 6140
6240
6340
0140
0240
0340
4040
4040.

M6
M7

~800

96
160
224
-2016
-2016

2
3
A
B
C
blank
. blank

If the above had been re.ad in 4A2 format~ the values would be as
follows:
Variable

Decimal

Octal

ASCII

M1
M2
M3
M4

-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 <VALUE,123,275)

The identifier used to name the subroutine is not assigned a
type and has no relation to the types of the arguments. Arguments
which are constants or formed as expressions must not be modified
by the subroutine.
7-39

RETURN Statement
The RETURN statement has the form:
RETURN
This statement returns control from a subprogram to the calling
program. Each subprogram must contain at least one RETURN
statement. Normally, the last statement executed in a subprogram
is a RETURN statement; however, any number of RETURN statements may appear in a subprogram. The RETURN statement may
not be used in a main program.
FUNCTION CALLS
Function calls are provided to facilitate the evaluation of functions such as sine, cosine, and square root. A function is a subprogram which acts upon one or more quantities (arguments) to
produce a single quantity called the function value. A function call
may be used in place of a variable name in any arithmetic expressIon.
Function calls are denoted by the identifier which names the
function (i.e., SIN, COS, etc.) followed by an argument enclosed
in parentheses as shown below:
IDENT (ARG, ARG, ... , ARG)
where IDENT is the identifying function name and ARG is an
argument which may be any expression. A function call is evaluated before the expression in which it is contained.
FUNCTION LIBRARY
The standard FORTRAN library contains built-in functions, including user-defined functions and subroutine subprograms.
Table 7-4 lists the built-in functions. These are open subroutines: they are incorporated into the compiled program each time
the source program names them.
Function and subroutine subprograms are closed routines; their
coding appears only once in the compiled program. These routines
are entered from various points in a program through jump-type
linkages.

7-40

NOTE
A FORTRAN compiler and its corresponding Library constitute an interlocking set of
programs. No user should attempt to compile
, a program under OS/8 and load it with the
paper tape FORTRAN, or vice versa. Similarly, programs developed with the current
FORTRAN compiler should not be run under an old FORTRAN system.
Table 7-4

FORTRAN Function Library

Function

Definition

ABS(x)
IABS(x)
FLOAT(x)

the absolute value of x
the absolute value of x
convert x from integer to real
format
convert x from real to integer
format
remainder of last integer divide
is returned
remainder of xl y is returned

IFIX(x)
IREM(O)
IREM(x/y)

EXP(x)
ALOG(x)
SIN (x)
COS (x)
TAN(x)
ATA,N(x)

exponential of x, ex
natural logarithm of x, logex
sine of x, where x is given in
radians
cosine of x, where x is given in
radians
tangent of x, where x is given in
radians
arc tangent of x, where x is given
in radians

Type
of Argument(s)
real
integer
integer
real
-integer
integer
real
real
real
real
real
real

SQRT(x)

square root of x is returned

real

IRDSW(O)

read the console switch register,
returning a decimal equivalent
of the octal integer in the switch
register. The switch register can
. be set before executing the
FORTRAN program or, using
the PAUSE statement, during
execution.

integer

7-41

FLOATING' POINT' ARITHMETIC

In general, floating point arithmetic calculations are accurate to
seven digits with the eighth digit being questionable. Subsequent
digits are not significant even though several may be typed to satisfy
a field width requirement With the exception of the arctangent
function, which is accurate to seven places over the entire range,
results of function operations are accurate to six decimal places.
The floating point arithmetic routines check for both overflow
and underflow. Overflow wi1l cause the OVFL error message
to be printed and program execution will be terminated. Underflow is detected but will not cause an error message. The arithmetic operation involved will yield a zero result.

DEVICE INDEPENDENT I/O AND CHAINING

OS/8 FORTRAN provides for device independent, file-oriented,
formatted I/O through use of the device number 4 in the READ
and' WRITE statements and several utility subroutines. These are
described below.

The IOPEN Subroutine

The subroutine IOPEN prepares the system to accept input
from a specified device when device code 4 is used in a READ
statement. 10PEN takes two arguments which are interpreted as
Hollerith stdngs. After a
CALL IOPEN(A .. B)

any READ statement reading from device 4 wili read from the file
specified by B (which must have the extension .DA) on the device
specified by A. For example:
CALL IOPEN('DTA5','INPUT')

will prepare for input from the file DTA5:INPUT.DA
CALL IOPENC'Fl',0)

7-42

will prepare for input from the device Fl, which, in this case, is a
non-file-structured device.
If the file and· device names are· inpnt via READ statements .
which use A format in their FORMAT statements, then A6 format
must be used.@ signs rather than spaces should ,be used to fill in
empty characters. For example, the following statements are -con':'
tained in a program:
20
82

WRItE (1,,20)
FORMAT ('ENTER FILE NAME')
READ (1,,22)FNAME
FORMAT (A6)
CALL IOPEN('DSK'"FNAME}
•
•

The Teletype prints:
ENTER FILE NAME

and the user responds:
ABC@@@

The OOPEN Subroutine
The subroutine OOPEN prepares the system to send output to
a specified device when device code 4 is used in a WRITE statement. The arguments of OOPEN are treated like those of IOPEN.
Future WRITE statements using device 4 write on the device and
file specified in the call to OOPEN. An error message is printed
if the program has previously issued a CALL OOPEN without
issuing a subsequent CALL OCLOSE. For example:
CALL OOPEN( 'PTP',0)

prepares device 4 to output on device PTP.
CALL OOPEN( 'SYS', 'LAD~')

prepares device 4 to output to the file SYS:LADE.DA.
7-43

The OCLOSE Subroutine
The subroutine OCLOSE is called with no arguments. Its function is to terminate output on the output file opened by OOPEN.
If OCLOSE is not called after a file has been written, that output
file will never exist on the specified device.
The CHAIN Subroutine
A call to the subroutine CHAIN terminates execution of the calling program and starts execution of the core image on the system
device as specified by the argument to CHAIN. Variables in common storage are not disturbed. For example:
CALL CPAIN('PROG2')

causes the file SYS:PROG2.SV to be loaded and started. Notice
that PROG2 must be compiled and stored on the system device as
a core image (.SV) file in order to be successfully accessed.

The EXIT Subroutine
To return to the Keyboard Monitor from a FORTRAN program,
the EXIT subroutine is used, as follows:
CALL EXIT

DECTAPE I/O ROUTINES
RTAPE and WTAPE (read tape and write tape) are the DECtape read and write subprograms for the 8K FORTRAN and 8K
SABR systems. For the paper tape FORTRAN system, these 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-filestructured 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.
R TAPE and WT APE are subprograms which may be called with
standard, explicit CALL statements in any 8K FORTRAN or
7-44

SABR program. Each subprogram requires four arguments separated by commas. The arguments are the same for both subprograms 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 directiqn

rather than the nsual backward· direction by making this
argument the two's complement of the block number. For
additional information on this and other features the reader
is referred to the DECtape Programmer's Reference Manual (DEC-08-SUCO-D).
3. Number of words to be transferred (l <N < 4096) .
4. Core address at which the transfer is to start.
The general form is:

where nl is the DECtape unit number, n2 is the block number, n3
is the number of words.to be transferred, and i14 is the starting
address.
In 8K FORTRAN, an example CALL statement to RTAPE
could be written in the following format (arguments are taken as
decimal numbers) :

In this example, LOCA 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.
7-45

Since PDP-8 DECtape is formatted with 1474 blocks (numbered
0-2701 octal) of 129 words each (for a total of 190,146 worns) 7,
A,B, C, and D will require 16, 4, 4, and 1 blocks respectively.
DIMENSION IDIR(258)
CALL RTAPE(5J2J258JIDIR)

would read Block 2 (OS/8 Block 1) of DECtape # 5.

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

WTAPEC0J1J2000JA)
WTAPE(0J17J400JB)
WTAPE(0J21J400JC)
WTAPE(0J25J20JD)

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;19;129~B(259))

CALL RTAPE(0J20J13JB(388»

As shown above, it is possible to read or write less than 129
words 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 ..

7 The block numbers used by RTAPE and WTAPE should not be confused
with the record numbers used by OS/8. An 05/8 record is 256 wordsroughly twice the size of a DECtape block. An RTAPE or WTAPE record
number is exactly twice the corresponding OS/8 record number. For example, to read the first segment of the OS/8 directory on DECtape #5,
the statements:

7-46

A DECtape read or write is normally initiated with a backward
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 specifying 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 RTAPEC0,1,2000,~)
CALL RTAPEC0,-27,20,O)

The following section of a program demonstrates the use of
DECt~pe I/O. Assume that values are already present on the
DECtape.

DIMENSION DATAC5(0)

50
100

110

NB=0
SUM=0.
DO 100 N=1,10
CALL RTAPEC1,-NB,1500,DATA)
TEM=0.
DO 50 K=1,500
TEM=TEM+DATACK)
SUM=SUt':+TEM
NB=NB+2L!
AMEAN=SUM/500.0. ,
WRITE (1,\10) SUM, AMEAN
CALL EXIT
FORMAT ('SUM=',E15.7' MEAN=',E15.7///)
END

OS/8 FORTRAN LIBRARY SUBROUTINES
Table 7-5 contains a summary of the 05/8 FORTRAN library
subroutines. This list describes the routines available under 05/8
FORTRAN, their functions, and other routines which must also
7-47

be present in order for them to 'be used. The Subroutine Names
listed are the files which comprise OS/8 Source DECtape #3
(available from the Software Distribution Center upon request).

Table 7-5

FORTRAN II Library -Subroutines

Entry
Points, Routines
Core
or Defined That are RequireSubroutine External
Prements
Symbols requisites (Pages)
Name
.IOH

FLOAT

'READ'
'WRITE'
'IOH'
'FAD'
'FSB'
'FMP'
'FDV'
'STO'
'FLOT'
'FLOAT'

FLOAT
UTILTY
INTEGR
UTILTY

Function the
Routine
Performs
Handles Input
and Output
Conversion
Floating
Point Arithmetic Package

'PlY'
..... .J...i.1r..

'IFIX'
'IFAD'
'ISTO'
'ABS'
'CHS'
UTILTY 'OPEN' INTEGR
'GENIO'
'EXIT'
'ERROR'
'CKIO'

FORTRAN Device Routines,
Error Exit,
Normal Exit

POWERS 'IFPOW' FLOAT
'FFPOW' UTILTY
IPOWRS
'EXP'
'ALOG' INTEGR

Handles Numbers to
Floating
Powers

7-48

Table 7-5 FORTRAN II Library Subroutines (Cont.)

Entry
Points, Routines
or Defined That are
PreSubroutine External
Symbols requisites
Name

Core
Requirements
(Pages)

Function the
Routine
Performs

INTEGR 'IREM' . UTILTY
'lABS'
'DIV'
'MPY'
'IRDSW'
'CLEAR'
'SUBSC'
TRIG
'SIN'
FLOAT
'COS'
'TAN'

Integer Math
Package

Handles Sine,
Cosine, and
Tangent

ATAN

'ATAN'

FLOAT

Handles· Arctangents

SQRT

'SQRT'

FLOAT
UTILTY

. Handles Square
Roots

IPOWRS

'IIPOW' FLOAT
'FIPOW' INTEGR

Handles Numbers to Integer
Powers

IOPEN

'IOPEN' UTILTY
'OOPEN'
'OeLOS'
'CHAIN'

OS/8 DeviceIndependent
I/O, and
Chaining
Routines

RWTAPE 'RTAPE' UTILTY
'WTAPE'

OS/ Independent -DECtape
I/O Routines

7-49

MIXING SABR AND FORTRAN STATEMENTS
An S in column 1 of an input line identifies that line as containing SABR code. This feature is very useful for performing instructions which are undefined in the FORTRAN language. For
example:
D IMEN S I ON M ( 1 Vl )

J=t-1 ( 1 )

DO 55 K=2,lVl
L=M<K) .
S
TAD
,L
SAND
\J
S
DCA
\J
55
CONTINUE

This section of code will form the logiCal AND of M( 1) through
M( 10) in the variable J.
Notice that whenever a FORTRAN variable is used in a SABR
statement, the variable name is preceded by a backslash (""-).
FORTRAN line numbers referenced in SABR statements are also
preceded by a backslash for identification purposes. (A backslash
is produced by typing a SHIFT /L. )
Information on calling subroutines which are written in SABR
assembly language from a FORTRAN program may be found in
the SABR chapter.

SIZE OF A FORTRAN PROGRAM
The maximum size of any FORTRAN program is 36 octal or
30 decimal pages of code.
OS/8 can run FORTRAN programs in 8 to 32K of core; No
one program or subprogram can be longer than 4K, however.
The user can estimate the sIze of' his: program as follows: Take
the amount of core available on the system (at least 8~) and from
jt subtract 4K for the linkage subroutines-,: external symbol table,
and I/O, math, error, and utility subroutines. From the remainder
subtract the amount of storage required for data. T.he remaining
space can be used to hold FORTRAN coding, at the ~ate of 50-70
FORTRAN statements per lK of core.
7-50

One way to have a longer FORTRAN program in core than is
usually possible is to· divide a FORTRAN program into three
chained segments:
Segment 1-.inputs data into common storage
Segment 2-FORTRAN program for data processing
Segment 3--does output to desired device(s)
This gives two space advantages:
·1. The entire program does not have to fit into available core, .
.
only the largest segment.
. 2. If no I/O statements are used in the middle (computational)
segment, the I/O conversion routines will not be loaded with
that segment. Since ~hese routines occupy over 110010 words,
this technique allows the computational segment to be from
50 to 80 statements longer than a similar program containing I/O statements.
When chaining to a subroutine, the user must be sure he has com":'
piled, loaded, and saved a complete runnable main program on the
system device. This program is brought into core by the FORTRAN
CHAIN subroutine.
··FORTRAN STATEMENT SUMMARY
.A summary of the statements available under OS/8 FORTRAN
follows.

Table 7-6

FORTR~N Language Summary

.Statement

Definition

Arithmetic Statements

v=e

v is a variable (scalar. or array);
e is an expression .

. Control Statements

GOTOn

Transfer control to the statement
numbered n.

7-51

Table 7-6 FORTRAN Language Summary (Cont.)

Statement

CONTINUE

PAUSE
PAUSE n

STOP
END

Definition
Where nl-ni are statement numbers and j is a scalar integer variable. This statement transfers
control to the jth member of the
series of ni'
This statement transfers control
to the statement numbered nl,n21
or n3 if the value of the numeric
expression is less than, equal to,
or greater than zero, respectively.
The expression can be simple or
complex.
Repeat execution through statement n, beginning with i=mh incrementing by m3' while i is less
than or equal to m2' If m3 is
omitted, it is assumed to be 1.
m's and i's cannot be subscripted. m's can be either integer numbers or integer variables; i is an integer variable.
Dummy statement, used primarily as a target for transfers, particularly the last statement in the
range of a DO loop. A DO loop
need not end with a CONTINUE
statement.
Temporarily suspend execution.
The octal equivalent of the decimal number n is displayed in the
accumulator. Program execution
can be resumed by following the
statement with a call to the
OPEN subroutine.
Terminate execution.
Terminate compilation; must be
the last statement in a program.

Input! Output Statements

FORMAT (Sl,S2, .. "Sn)

Where Sl-Sn are data field specifications, this statement is used
with either a READ or WRITE
statement.

7-52

Table 7-6 FORTRAN Language Summary (Cont.)

Statement

Definition

READ (u,f) list

Where u is a device designation
(integer constant or integer variable), f is a FORMAT statement" numb~r, and list is a list of
variables.

WRITE (u,f) list

Where u is a device designation
(integer constant or integer variable), f is a· format statement
number, and list is a list of variables.

Specification Statements

Specified variables or arrays are
stored in an area available to
other programs.
Used to declare variable names
to be array names and specify
the number and bounds of each
one and two dimensional array.
EQUIVALENCE (V1,V2,'''')'
(Vi,Vi+l,"')

The inclusion of two or more
variable or array names in a
parenthetical list indicates that
the quantities in the list are to
share the same memory location
and hence have the same value.
Subscripts of array variables
must be integer constants. Names .
must not appear in both EQUIVALENcE and COMMON statements.

Subprogram Statements

Declares the program which follows to be a function subpro~
gram. vis the name of the function being defined. v must appear
as a scalar variable and be assigned a value during execution
of the subprogram.

7-53

Table 7- 6 FORTRAN Language Summary (Cont.)
Statement

Definition
Declares the program which follows to be a subroutine subprogram. The arguments in the
list(s) are dummy arguments
representing the arguments of the
subprogram. Dummy arguments
must agree in number, order,
and type with the arguments
used by the calling program.

CALL v
CALL v (a1,a2, ... ,a l1 )

Statement used to transfer control to a subroutine subprogram.
v is the subroutine name in the
SUBROUTINE statement. The
arguments can be of any type,
but must agree in number,
order, type and array size with
the arguments in the SUBROUTINE statement. One or more of
the arguments can be used to return results to the calling program. For example:
CALL EXIT

CALL TECK ('MAS',3)

RETURN

Returns control from a sub pro.gram to the calling program.
Each subprogram must contain
at least one RETURN statement. RETURN cannot be used
in the main program.

FORTRAN ERROR MESSAGES

Compiler Error Messages
The following OS/8 FORTRAN Compiler error messages are
self-explana tory.
7-54

ARITHMETIC -EXPRESSION TOO COMPLEX
EXCESSIVE SUBSCRIPTS
ILLEGAL 'ARITHMETIC EXPRESSION
ILLEGAL CONSTANT
ILLEGAL CONTINUATION
ILLEGAL EQUIVALENCING
ILLEGAL OR EXCESSIVE DO NESTING
ILLEGAL STATEMENT
ILLEGAL STATEMENT NUMBER
ILLEGAL VARIABLE

MIXED MODE EXPRESSION
SYMBOL TABLE EXCEEDED
SYNTAX ERROR (usually indicates illegal
punctuation)
SUBR. OR FUNCT. STMT. NOT FIRST
In addition, OS/8 FORTRAN contains the following error
messages:
Message

Explanation

COMPILER
MALFUNCTION

The meaning of this message has been
extended to cover various unlikely Monitor errors.

A device handler has signalled an' II 0
error.

NO END STATEMENT

The input to the Compiler has been exhausted.

NO ROOM FOR
OUTPUT

The file FORTRN.TM cannot fit on the
system device.

SABR.SV NOT FOUND

The SABR assembler is not present on
the system device.

Library Error Messages
During execution, the various library programs check for certain
errors and print error messages in the form:
XXXX ERROR AT LOC NNNNN
where XXXX is the error code and NNNNN is the location of
the error.
7-55

Table 7-7 FORTRAN Library Error Messages

Error Code

Meaning

The following errors are fatal and cause a return to the Keyboard
Monitor.

ALoa

Attempt to compute log of negative number.

IOER

One of the fol1owing has occurred:
or... {)ntnnt
- - r-.... a t- tempted without / I or /0 options, or user
attempted to specify a device requiring a
. two-page handler for device-independent
II 0 without using the / H option.
2. Bad arguments to IOPEN or O<1PEN, or
3. Transmission error while doing II O.
1.
-

Dp'liCP_inrlenpndpn,t
t
Y_A.Jt. _A.a. .... l·nn11
""': .... 1:"'_1''&'

........... __

CHER

File specified as argument to CHAIN not found
on,system device.

FMTI

Invalid Format statement.

The following input errors are fatal unless input is coming from
the Teletype, in which case the entire READ statement is tried
again.

FMT2

Illegal character in I format.

FMT3

Illegal character in F or E format.

The following errors do not termniate execution of the user's
program.

DIVZ

Division -by zero-very large number is returned.

EXP

Argument to EXP too large-very large number is returned.

OVFL

Floating point overflow-very large number is
returned.

FLPW

Negative number raised to floating
power-absolute value taken.

SQRT

Attempt to take square root of negative number
-absolute value used.

FIX

Attempt to fix a number >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

MAP

Assembling, Loading, an~ 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 IS
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<DEV:IFl.FT, ... ,DEV:IF9.FT(options)

(terminated by a carriage return) in response to the asterisk
generated by the Command Decoder, where DEV:RALF.RA,
DEV:LIST.LS, and DEV:MAP.LS are output files, RALF assembly source file, listing file, and loader symbol map file, respectively.
The files DEV:IFl.FT, ... ,DEV:IF9.FT are input files 1 to 9.
Options is a string of alphabetic characters, enclosed in parentheses, that designates any run-time options desired. The "~,,
character may be used in place' of the "<" character to separate
output file specifications from input file specifications. The parentheses may be omitted if each run-time option specification character is preceded by a "I" character.
When any input file name is entered with a null extension, the
compiler will search for the indicated file name with an assumed extension of ".FT", and, if this is unsuccessful, it will then search for
. the indicated file with a null extension. If the first output file
RALF.RA is entered with a null extension, the compiler appends
the default extension ".RA". If the second output file is a directory
device file with a null extension, the compiler appends the default
extension ".LS". Note that unless chaining to RALF, the first output file is always written onto the OS/8 system device; any user
device specification entered for this file will be ignored when the A
option is specified. When there is more than one input file, all of
the input files are assUmed to contain a single FORTRAN program
or subroutine.
8-10

After accepting and decoding the file/ option sp~cification ,command, the compiler reads the input files in the order they were
entered, and compiles each FORTRAN source-statement until an
END statement is encountered. Any text following the first END'
~taten'1ent is ignored. The compiler then writes a RALF assembly
language version of the source program onto the first output file,
or onto file SYS:FORTRN.RA if no first output file was, specified.
It also copies an annotated source program listing onto the second
output file; however, this listing is not produced unless a second
output file was specifically defin~d. The third output file is not
. used by the compiler; it receives a loader. symbol map only when
chaining to the loader.
An internal 'statement number (lSN) is assigned to each
FORTRAN IV statement sequentially, in octal, beginning with
ISN 2 at the first FORTRAN statement. When an error is encountered during compilation, the compiler prints a 2-character
error code, followed by the ISNof the offending statement, on the
console terminal during pass 2. An extended error message is
printed below every erroneous statement in the listing, provided
that a listing is produced. Certain errors cause an immediate re-.
turn to the Keyboard Monitor, however, in which case the listing
file is never produced. Table 8-3 lists the FORTRAN compiler
error messages and describes the error condition inqicated by each
mes.sage.
The compiler ~ccepts four run-time option specifications, listed
in Table 8-2, any combination of which may be requested by
entering the appropriate alphabetic character(s) in the Command
Decoder file/option specification line. Any run-time options recognized by the RALF assembler, 'the loader, or the run-time system
may be entered along with the compiler options; they will be
passed to the assembler automatically unless chaining is suppressed
(by an error condition or the A option) in which case they will be
ignored.

8-11

Table 8-2

FORTRAN IV Compiler Run-Time Options

Option

Operation

Return to the Keyboard Monitor when compilation is complete. If the A option is not requested, the compiler will
automatically chain to the RALF assembler.

Produce an annotated listing of the RALF assembly language output file. The listing is actually produced by the
assembler; thus, the F option is only valid when chaining to
RALF. The listing is routed to the same output file as the
FORTRAN source listing. It will overwrite the FORTRAN
listing if the second output file resides on a directory device.
It will not be produced if a second output file was not specifically defined.

Suppress compilation of ISNs. This reduces program memory requirements by two words per executable statement;
however it also prevents full error traceback at run time.

Optimize cross-statement sUbscripting during compilation.
This option should not be requested when any variable
which appears in a subscript is modified either by referencing a variable equivalent to it or via a SUBROUTINE or
FUNCTION call (whether as an argument or through COMMON).

Examples
Compile, assemble, load, and execute a FORTRAN IV source
program:
Compiles DSK:PROG.FT Of
DSK:PROG into DSK:FOR
TRN .RA, assembles it into
DSK:FORTRN.RL, links it
into DSK:FORTRN.LD, then
loads it into core and executes it. No listing files are·
produced.

Compile any source program by calling F4 and specifying the
file (or files) containing the source as input:
8-12

Compiles DSK:PROG.FT or
else DSK:PROG. into SYS:FORTRN.RA. The backarrow is optional when there
are no output file specifications .
Compiles SYS:PROG.FT into SYS:FORTRN.RA under _
the N option.

• R F4
*SYS: PROG. FreNA)

Obtain a source listing with error messages by specifying a listing output file as the second output file. In these examples, the first
output file is a null file.
• R F4
*ILPT: <PROG/A·

Identical to the first example
above, except that a listing is
produced on the line printer.

.R F4
*1 DTAt: PROG<DTA2: PROG. FT /A/N

Compiles DTA2:PROG.FT
into SYS:FORTRN.RA and
writes a source listing onto
file DTAl:PROG.LS under
the N option. .

Designate a specific output file to receive the compiler output by
specifying it .as the first output file:

* PROG< PROG/A

.R F4

Compiles DSK:PROG.FT or
else DSK:PROG. into SYS:
PROG.RA.

• R F4

Compiles

LTAO:WHAT.FT

*W~EN.R~,WI'iERE.LSCLTAIiHWtolAT(AQ)or else LTAO:WHAT. into

SYS:WHEN.RA with a listing routed to DSK:WHERE.
LS under the Q option.

Compiler Error Messages
During compilation pass 2, error messages are printed at the
console terminal as a 2-character error message followed by the
ISN of the erroneous statement. Typing CTRLjO at the terminal
suppresses the printing of error messages. If a listing was requested,
an extended error message is appended to the listing, immediately
following the erroneous statement, during pass 3. Except where
indicated in Table 8-3, errors located by the compiler do not halt
processmg.

8-13

Table 8-3
Error
Code
AA
AS
BD

BS
CL
CO
DA
DE
DF
DH
DL
DN
DO
DP
EX
GT
GV
TT,",

nv
IE

IF
LI

LT
MK
ML
MM
MO
MT
OF
OP
OT
PD
PH

FORTRAN IV Compiler Error Messages

Meaning
More than six subroutine arguments are arrays.
Bad ASSIGN statement.
Bad dimensions (too big, or syntax) in DIMENSION,
COMMON, or type declaration.
Illegal in BLOCK DATA program.
Bad COMPLEX literal.
Syntax error in COMMON statement.
Bad syntax in DATA statement.
This type of statement illegal as end of DO loop (i.e., GO
TO, another DO).
Bad DEFINE FILE statement.
Hollerith field error in DATA statement.
Data list and variable list are not same length.
DO-end missing or incorrectly nested. This message is
not printed during pass 3. It is followed by the statement
number of the erroneous statement, rather than the ISN.
Syntax error in DO or implied DO.
DO loop parameter not integer or real.
Syntax error in EXTERNAL statement.
Syntax error in .GO TO statement.
Assigned or computed GO TO variable must be integer
or real.
Hollerith field error.
Error reading input file. Control returns to the Keyboard
Monitor.
Logical IF statement cannot be used with DO, DATA,
INTEGER, etc.
Argument of logical IF is not type Logical.
Input line too long, too many continuations.
Misspelled keyword.
Multiply defined line number.
Mismatched parenthesis.
Expected operand is missing.
Mixed variable types (other than integer and real).
Error writing output file. Control returns to the Keyboard Monitor.
Illegal operator.
Type / operator use illegal (e.g., A.AND.B where A and /
or B not typed Logical).
Compiler stack overflow; statement too big and/ or too
many nested loops.
Bad program header line.

8-14

Table 8-3

FORTRAN IV Compiler Error Messages (Cont.)

Error
Code
QL
QS
RD
RT
RW

SF
SN
SS
ST
SY
TD
US
VE

Meaning
Nesting error in EQUIVALENCE statement.
Syntax error in EQUIVALENCE statement.
Attempt to re-define the dimensions of a variable.
Attempt to re-define the type of variable.
Syntax error in READ/WRITE statement.
Bad arithmetic statement function.
Illegal subroutine name in CALL.
Error in subscript expression, i.e., wrong number, syntax.·
.
Compiler symbol table full, program too big. Causes an
immediate return to the Keyboard Monitor.
Syslem error, i.e., PASS20.SV or PASS2.SV missing, or
no room on system for output file. Causes an immediate
return to the Keyboard Monitor.
Bad syntax in type declaration statement.
Undefined statement number. This message is not printed
during pass 3. It is followed by the statement number of
the erroneous statement, rather than the ISN.
Version error. On~ of the compiler programs is absent
from SYS: or is present in the wrong version.

THE RALF ASSEMBLER
The RALF assembler accepts one RALF assembly language
program or subroutine as input and produces a relocatable binary
file, called a RALF module, as output. An optional annotated listing of the input file may also be produced~ RALF terminates an
assembly by returning to the Keyboard Monitor unless it was
requested to chain to the loader.
A RALF module is composed of an external symbol dictionary
(ESD table) and associated text. The ESD table lists all symbols
defined in the RALF input file, which may be sections, entry points,
or externs. Each of these symbols is assigned a relative address to
be used by the loader when it relocates the relative code by assigning absolute core addre~ses. The text produced by RALF is a
relocatable binary version of the assembly language input file. All
text addresses are relative to the ESD table symbols.
A section can be thought of as a contiguous block of relocatable .
code having a definite beginning and- end, which is temporarily
8-15

assigned a relative starting address of 00000: A RALF file can
have more than one section defined in its ESD table., For example,
consider a subroutine containing a COMMON section which is
assembled by RALF. Both COMMON and the subroutine itself
are sections. An ·entry point is a location within a given section that
is referenced by code in other sections. An extern is a section or
entry point in some other. module that is referenced within the.
module currently being assembled.
Unless the A option is specified,to the FORTRAN IV compiler,
the RALF assembler is called automatically to assemble. the. output
of a successful compilation. In this case, RALF reads the assembly
language file just produced by the compiler as input and routes its
output, consisting of the assembled RALF module, to the first
output file that was specified to the compiler. If this file had a null
extension, the default extension ".RL" is supplied. If no first out~
put file was specified, the module is written onto default file
SYS:FORTRN.RL.
The RALF language output produced by the compiler is then
deleted, and an annotated listing of the RALF assembly language
input is written on the second output file specified to the compiler,
provided that a second output· file and the F option were both
specifioo. This listing will overwrite the compiler source listing if
the second output file is a directory device file. Note, however, that
the RALF language listing is rarely required for most applications,
and should not be routinely requested.
The RALF assembler might also be called separately to assemble the output of a compilation produced under the A option or to
assemble a user-generated file written in RALF assembly language.
This is accomplished by typing:
R RALF'

(terminated by a carriage return) in response to the dot generated
by the Keyboard Monitor. RALF 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:IMLF.RA,DEV:LIST.LS,DEV:MAP.LS<DEV:IFl.R A, ... ,DEV:IF9.RA(options)

8-16

(terminated by a carriage return) in response to the asterisk
generated by the Command Decoder7 where DEV:RALF.RA,
DEV:LIST.LS and DEV:MAP.LS are the relocatable binary
RALF module, annotated listing of EALF source, and loader,
symbol map, respectively; DEV:IFl.RA, ... ,DEV:IF9.RA are
input files 1 to 9; and "options" is a string.of alphabetic characters
that designates any run-time options desired. If" any input file name
is entered with a null extension, the assembler will search for the
indicated file name with an assumed extension of ".RA" and, if
this is unsuccessful, it will then search for the indicated file with a
null extension. If the first output file is entered with a null extension, the assembler appends the default ex,tension ".RL". If the
second- output ,file is a directory device file with a null extension,
the assembler appends the default extension ".LS".
When there is more than one input file, all of the input files are
assumed to contain the assembly language sourc~ for a single"
RALF module. After accepting and decoding the file/option
specification command, RALF reads the input files in the order
they were entered, and assembles every, RALF language statement. RALF terminates the assembly by writing a--relocatable
binary version of the input program or subroutine onto the first
output file, or onto file SYS:FORTRN.RL if no output files were
specified. It also copies an annotated source listing and symbol
table onto the second output file; however, this listing is not produced unless a second output file was specifically defined. The
third output file is not used by the assembler; it receives. a loader
symbol map only when chaining to the loader.
When an error is encountered during assembly, the assembler
prints a 2-character error code, followed by the label associated
with the erroneous statement, on the console terminal during pass
2. Error codes are also appended to the listing, on a line by themselves immediately preceding the statement to which they apply
(except EG, which follows the line in error). Certain errors cause
an immediate return to the Keyboard Monitor, however, in which.
case the listing is never produced. Table 5-2 lists the RALF assembler error messages and describes the error condition indicated by
each message.
The assembler accepts the three run-time option specifications
listed in Table 8-4, any combination of which may be requested by
entering the appropriate alphabetic character(s) in the Command.
8-17

Decoder file/option specification line. Any options recognized by
the loader or the run-time system may be entered along with the
assembler options; they will be passed to the loader automatically
unless chaining is suppressed (by an error condition or omission of
the L option specification), in which case they will be ignored.

Table 8-4

RALF Assembler Run-Time Options

Option

Operation

Chain to the loader when assembly is complete and chain
to the run-time system following creation of a loader
image file.

Chain to the loader when assembly is complete. If the L
option is not specified, RALF will return to the Keyboard
Monitor upon completion.

Suppress the RALF assembly language listing and produce only a symbol table. The T option is ignored by the
assembler when a second output file was not specifical1y
defined. When chaining from the compiler, it is ignored
un'Iess the F option and a listing output file were both
specified.

The symbol tabl~ produced by RALF and appenaea to the
RALF 'anguage listing includes the assembler version number,
system date, and the listing page number, followed by the number
of errors encountered during assembly, the number of symbols
defined in the program, and the number of absolute references
encountered in FPP instructions. All symbols referenced during
the assembly are then listed in alphabetical order, from left to right
across the page. An alphabetic code follows certain classes of
symbols and identifies them by type. The alphabetic codes are:
C
F
S
U
X
Z
8

symbol names a COMMON section
symbol names a FIELD 1 section
symbol is the name of a section
symbol is undefined
symbol is external to this assembly
symbol names a COMMZ section
symbol names an 8-mode section
8-18

If no alphabetic code is shown, the symbol is an ordinary address
symbol. A numeric code is also printed after each symbol in the
list. The numeric code indicates the relative octal value of the
symbol except for the case of:
C, F, S"
Z, or 8 codes

where the numeric code indicates the length
of the section or common' block.

U or X codes-

where 00000 indicates undefined or external
symbols.

Examples
When chaining from the compiler to the assembler, RALF
deletes the compiler output after reading it as input:
• R F4

*PROG

• R F4

~PROG. V3"LPT: :C:PROG/F

• R F4

*DTA2:0BJ"DTA1:LIST<DTA2:PROGCTF)

Produces RALF module
SYS:FORTRN.RL and deletes compiler output file
SYS:FORTRAN.RA.
Produces RALF module
SYS:PROG.V3 and lists both
the FORTRAN source and
the RALF language compiler
outPl!t on the line printer .
Produces RALF module
DTA2:0BJ.RL and writes a
symbol map onto file DTA1:
LIST.LS. The FORTRAN
source listing is overwritten
and destroyed.

When calling the assembler to assemble and relocate the output
of a successful compilation produced under the A option or a userwritten RALF language source, the procedure is closely analogous
to that for running the compiler:
• R RALF
*PROG
• R RALF'
•
*" SYS:LI ST<DTA1: FILE. RA

• R RALF
*DTA1:TEMP.TM"LPT:<RALF'.RA

8-19

Assembles DSK:PROG.RA
or else DSK:PROG. into
SYS:FORTRN.RL.
Assembles DTA 1:FILE.RA
into SYS:FORTRN.RL and
writes a listing on SYS:LIST.
LS.
Assembles DSK:RALF.RA
into DTAI :TEMP .TM and
writes a listing on the line
printer.

- RALF Assembler Error Messages
During assembly pass 2, error messages are printed at the
console terminal as a 2:...character error code followed by the label
associated with the erroneous statement. If a listing was requested,
error codes are printed during pass 3 on a line by themselves
immediately preceding the statement to which they apply (except
for EO, which follows the line in error). RALF error messages are
listed in Table 5-2.

THE LOADER
The OS/8 FORTRAN IV loader accepts up to 128 RALF
modules as input and links the modules, along with any necessary
library components, to form a loader image file that may be loaded
and executed by the run-time system. This is accomplished by
replacing the relative starting location (00000) of each section with
an absolute core address. Absolute addresses are also assigned to
all entry points defined in the input modules. Once all RALF
modules and library components have been assigned to some
portion of memory and linked, absolute addresses are assigned to
the relocatable binary text and the externs.
The overlay feature of the loader facilitates running programs
which are too large to be contained in avail~ble memory, making it
possible to run programs that require up to 300K words of storage
in
1e:"" th~n
me:moTV Thi"
hv
------------ i?K
---- of
-- ~rtn~l
------- rOTe:
---- ---------,;----- i"-- ~rromnli"he:iI
-------r--------,;

dividing very large FORTRAN programs into a set of subroutines
linked by one mainline. Unlike the subroutines, each of which has
a section name by which it is called, the mainline does -not have a
name and is therefore assigned section name # MAIN by the system. An overlay scheme is then designed in such a way that the
memory .requirement of those subroutines that are core-resident at
any given time does not exceed the available core memory.
An overlay is a set of subroutines stored on a bulk storage
device. When any subroutine in an overlay is called by the mainline or another subroutine, the entire overlay is read into core,
where it generally replaces another overlay of equivalent size.
Levels are variable-size portions of memory reserved for specific
sets of overlays. OS/8 FORTRAN IV permits up to 8 levels,designated level 0, levell, and so on up to level 7. Level 0 is
always present and always contains only one overlay, called overlay MAIN, which always includes section #MAIN (the
8-20

FORTRAN or RALF mainline) as well as all COMMON sections,
8-mode sections and library components. Additional subroutines
may also reside in overlay MAIN; in fact, the entire program
shoyJd be loaded into level 0 if there is sufficient core available.
Levels 1 to 7 may each contain up to 16 overlays, only one of
which is core-resident at any given time during program execution.
If no subroutines are loaded into a given level, that level does not
exist for the current execution and no memory is allocated to it.
As execution begins, overlay MAIN is loaded into level 0 (where it
remains throughout execution) and started at the entry point of
section #MAIN. Other overlays are read into the block of memory
reserved for their particular level whenever one of their constituent
subroutines is called. As an overlay is read into a given level, it
overwrites any other overlay which may have been resident in that
level. Thus, no two overlays from the same level are ever coreresident simultaneously.
When section#MAIN or any subroutine calls another subroutine, the flow of execution from calling routine to called routine
is referred to as part of a calling sequence. Every calling sequence
begins with a call from section #MAIN and ends with a call to
some subroutine that does not contain any further CALL state-.
ments. Calling sequences generally contain branches, and they may
be very intricate. For example, assume that:
Routine /Subroutine

Contains Calls To

mainline (# MAIN)
SUB1
SUB2
SUB 3
ALPHA
BETA

SUB1, SUB2, SUB3
ALPHA,BETA
SUB3

SUB2

Then the calling sequences could be mapped as:
~ALPHA
SUBl

ilMAIN

BETA~·

SUB2~
-SUB3

8-21

When any' subroutine CALL is executed, the system determines
whether the overlay containing the called routine is core-resident
and, if not, reads this overlay into its proper level in core, overwriting any overlay which was previously resident in that level. No
such determination is possible for RETURN statements, however.
For this reason, it is extremely important to ensure that, at the end
of a calling sequence, all subroutines in the calling sequence are
still core-resident. In other words, no subroutine may execute a
CALL that will cause it, or any subroutine which called it, to be
overlaid. In the previous example, if SUB 1, SUB2 and SUB3 occupy separate overlays in level 1 while ALPHA and BETA reside
in level 2, the calling sequence from # MAIN to SUB 1 to BETA
to SUB2 will cause a fatal error because SUB2 will overwrite SUB 1
and prevent control from returning to level O. The FORTRAN
system guards against some errors of this type by enforcing the
following rules:
a. Subroutines in a given level cannot call other subroutines in
the same level if the called subroutine is in a different overlay.
b. Subroutines in high numbered levels cannot call subroutines
in lower numbered levels unless the call is to level O. (This
convention is not enforced when the U option is specified to
the run-time system.)
previous example, if subroutine BETA is placed in level 0 instead
of levell, the calling sequence from # MAIN to SUB 1 to BET A
to SUB2s~ill causes a fatal error, even though neither of the enforced conventions is violated. Thus, any overlay scheme must be
designed with careful attention to calling sequences.
If the L or G option is specified to F4 or RALF, the loader is
called automatically to relocate the output of a successful assembly.
When chained to via F4, the loader reacts in one of two ways. If
the last Command Decoder file/option line was terminated with a
carriage return, it immediately fetches the Command Decoder and
proceeds as though it had been called from the monitor, as described below. The only difference, in this case, is that certain
loader or run-time system options may have been passed to the
loader from RALF, and cannot be suppressed at this point. Also,
unless two different files are specified as output files, the loader
automatically routes its loader image to the first output file specified
8-22

to F4 or RALF at the start of the chain, with default extension
".LD" assigned if this file had a null extension, or to file SYS:
FORTRAN.LD if no output files were specified. The relocatable
binary output produced by the assembler is deleted after it has been
read as input. A loader symbol map is routed to the third output
file speCified at the s(art of the chain sequence, if any, or to the
second output file, if any, specified to the loader as described below.
When this is a directorY device file with a null extension, the default
extension ".LS" is supplied.
If the last file/option specification supplied to the Command
Decoder was terminated with an ALTMODE character instead of
a carriage return, the loader reacts differently when chained to from
RALF. In this case, the loader assumes that the RALF module just
produced is a stand-alone mainline that requires no subroutines
(other than library components) in order to execute. The loader
does not call the Command Decoder under these circumstances.,
since level 0 is the only level that· will be defined. Output is produced exactly as described above, and the loader either returns to
the Keyboard Monitor upon completion or, if a 0 option specification was previously entered, chains to the run-time system.
The loader may be called separately, to link and relocate a set
of previously assembled RALF modules. This is accomplished by
typing:
R LOAD

(terminated by a carriage return) in response to the dot generated
by the Keyboard Monitor. The loader replies by calling the OS/8
Command Decoder, which accepts and decodes one or more standard command lines, each of which designates 0 to 9 input files, 0
to 2 output files, and any run-time option specifications desired.
Each file/option specification line is entered by typing:
DEV:IMAGE.LD,DEV:MAP.LS<DEV:PROGA.RL, ... ,DEV:PROGX.RL(options)

(terminated by a carriage return) in response to the asterisk generated by the Command Decoder. IMAOE.LD is the loader image
output file and MAP .LS is the loader symbol map output file. The
input files may be either relocatable binary RALF modules or a
library file, and "options" is a string of alphabetic characters that
designates any run-time options desired.
8-23

The loader accepts up to 128 input file specifications, one of
which may designate a library file to be used in place of the standard system library. The OS/8 Command Decoder, however, accepts a maximum of only 9 input file specifications per command .
line. Thus, after each file/option command line is entered, the
loader recalls the Command Decoder to accept another command
line, and continues this process until the /'0 option is received or a
line is terminated. with an ALTMODE. Input file specifications
should be entered in sequence, beginning with all RALF files to be
loaded into level 0, foliowed by files for level 1 overlay 1, level 1
overlay 2, and so on until all level 1 overlays are filled. Level 2
overlays are then built in the same manner, using as many file/
option specification lines as necessary, and the process continues
until all levels are filled. Each line may contain from 0 to 9 input
file specifications; null lines will be ignored by the loader.
At some point during this process, two output files and one
library (input) file may also be specified. The loader image file built
by the loader is routed to the first output file, which must reside on
a directory device,or to file SYS:FORTRN.LD if no output files are
specified. When the first output file has a null extension, the default
extension ".LD" is supplied. The loader symbol map is routed to
the second output file, provided that a second file is specifically
defined. If this is a directory device file with a null extension, the
defau1t extension" .LS" is supplied. One libra..'"'j file may be specified
as an input file, to be used in phice of the standard system library.
This must be a specially formatted file, prepared with LIBRA as
described in the section concerning the FORTRAN IV Library,
and it must be specified on a command line that contains no other
input file names. This command line may appear anywhere in the
file/ option specification sequence. It is identified by the presence of
an L option specification.
If more than one first output file, second output file, or library

file is specified to the loader, only the last specification in each
category is used. Previous specifications, including those supplied
- to F4 or RALF when chaining to the loader, are ignored.
Run-time option specifications are used to group the sequence· of
input files into discrete overlays, allocate overlays to certain levels,
and identify the user-generated library file, if any. Table 8-5 lists
the run-time options recognized by the loader and describes their
8-24

.
use. The E and H options, recognized by the run-time system, may
be entered on the same line as the G option when chaining to the
run-time system.
-

Table 8-5

Loader Run-Time Options

Option

Operation

Continue the current line of input on the next line of in ..
put. When specifying RALF files to the loader, there
may be more than 9 files that belong in a given overlay.
Since the Command Decoder will not allow more than
nine input files in one file option specification line, the C
option permits the additional files to be put on the following line. If the C option is not specified at the end of a
line, the current overlay is closed when the terminating
carriage return is received and subsequent input files are
placed in a new overlay in the current level. An exception to this is level 0, which only contains one overlay.
The presence of a C option specification is. assumed on
every line-until level 0 has. been closed by an 0 specification.

Treat the current line as the last line of input, and chain
to the FORTRAN IV run-time system when finished.

Accept the single input file specified on this line as an alternate library to be used in place of the system library,
FORLIB.RL..

Close the level that is currently open, and open the next
sequential level for input.. RALF files specified on subsequent lines are assigned to overlays in the new level
until the new level is closed by the next 0 specification (or
the end of input).

Include system symbols in the loader symbol map. System symbols. are identified by an initial "#" character.
This option is only valid when a symbol map output file
was specifically defined.

Ignore the rules governing subroutine calls between
overlays. This option should only be used when subroutines making illegal calls will not be accessed during
execution since, in general, any illegal subroutine call
will cause unpredictable behavior at run time.

8-25

Input may be terminated by entering a G option specification on
the last line and/or by terminating the last line with an ALTMODE
character rather than a carriage return. If the G specification and
the ALTMODE both appear, this indicates that the user has no
file/option specification input for the run-time system and prevents
the run-time system from calling-the Command Decoder.
The following sequence of Command Decoder specification lines
illustrates the use of option specifications to allocate RALF files to
particular overlays.

• R LOAD

Loader is called from Keyboard Monitor.

*SYS: PRQG.LD .. LPT: <PROG. RL

Loader image file will be
routed to SYS:PROG.LD
while the symbol map is
printed on the line printer.
PROG.RL is placed in level
o overlay MAIN. Since the
presence of a C option specification is assumed on every
line preceding the first 0 option specification, level 0
overlay MAIN remains open.
Place subroutines ALPHA
and BETA in level 0 overlay
M A.a..........
TN . ThO .........
_~
r"
,t'.1.
VoL a '-"
option specification is assumed.
....

.&.~

011['101""',...",

.&. .I. ... "'"

'-'~""'J..1\",.. "

Close level 0 and open level
1 overlay 1.
Place SUB 1, SUB2 and SUB3
in level 1 overlay 1. Close
overlay 1 and open overlay 2.
*<SUB4.RL .. SUB5.RL .. SUB6.RL/C

Place SUB4, SUBS and
SUB6 in level 1 overiay 2.
Accept further input for this
overlay on the next line.

*<DTA1:SUB1.RL/O

Place SUB7 in level 1 overlay 2. Close levelland open
level 2 overlay 1.

* < DT AI: SUB8 ~ RL

Place SUB8 in level 2 overlay 1. Close overlay 1 and
open overlay 2.
Place SUB9in level 2 overlay 2. Close overlay 2 and
open overlay 3.

*< SUB9. RL

Use file DSK:LIB. RL in
place of SYS:FORLIB.RL as
the library file. In spite of its
position in the specification
list, any library components
will be placed in level O. The
S option specification re-·
quests an augmented loader
symbol map.

*<LI B. RL( LS)

*<SUB10.RL/O

Place SUB lOin level 2 overlay 3. Close level 2 and open
level 3 overlay 1.

Place SUB 11 and SUB 12 in
level 3 overlay 1. Close level
3, terminate input, and chain
to the run-time system when
finished.

This sequence of commands will provide the following overlay
scheme:
.
Level

o
I
I
2
2
2
3

Overlay Contents
MAIN
1
2
1
2
3
1

PROG, ALPHA, BETA library subroutines
SUB 1, SUB2, SUB3
SUB4, SUBS; SUB6, SUB7
SUB8
SUB9
SUBIO
SUBII, SUBl2

Note that all of the input files except those containing SUB 7 ,
SUB8, and SUBl2 are taken from device DSK:, the OS/8 default
device. The left angle bracket (or backarrow) character 'is optional
when a file/option specification line contains only input file specifications, but it has been included here for clarity. Obviously, there
are many other ways in which the sequence of file/option specifi8-27

cations shown above could have been entered to produce an identical result.
Considerable foresight is required when designing an overlay
scheme. Since an overlay may have to be read into core whenever
one of its constituent subroutines is called, a great deal of useless
I/O results from inefficient overlay design. The system does verify
that an overlay is not already resident before reading it into core.
Levels must be an integral number of system blocks (400 octal
words) in size and big enough to accommodate the largest overlay
they contain.
Ideally, then, the largest overlay in a level should occupy slightly
less than some multiple of 400 (octal) words of storage, and all
overlays in a level should be nearly equal in size. For example, if
level 1 contains three overlays requiring 300, 100, and 150 octal
words of storage, respectively, then the two smaller overlays should
be combined because level 1 will be 400 octal words long in any
case. If the three overlays require 500, 100, and 150 octal words
of storage, all three should be combined because level 1 will be
1000 octal words long in any case.
Frequently called subroutines should be kept core-resident whenever possible, perhaps by placing them in level 0 or in a level that
contains rarely accessed overlays. Within the loader image file, subroutines are stored in the order in which they were specified to the
. loader. Thus, grouping frequently called subroutines into adjacent
levels also speeds execution by reducing the access time required to
read an overlay into core, particularly from DECtape or LINCtape:
When running very large programs with many overlay levels, it may
be desirable to make level 0 as small as possible, in spite of the
resulting excess I/O. This is accomplished by minimizing COMMON (which always occupies level 0), dividing the mainline into a
series of subroutines, and creating a new mainline that contains
predominately CALL statements. Note, however, that all library
subroutines will reside in level 0, regardless of the location of subroutines that call them.
Any error recognized by the loader during generation of a loader
image file results in an error message, printed on the console terminal, immediately following the input specification line that caused
the error condition. Table 8-6 lists the loader error messages and
describes the error condition indicated by each message.
8-28

The optional loader symbol map lists all symbols defined in the
loader image file and identifies each symbol by overlay, level, and
memory address:
LOADER 1J21

04 /30 /73

5YM30L VALUE LVL OVLY
10400

ARGERR 00204
B
10400
C

EXI I
#MAIN
12~00

1
1

11214
00223
10000

00
00
01

00
o 00
= 15, FREE LOCA II ON

LVI,. OVLY LENGIH

o
1
1

00
01

10143
0127J
01240

Following the alphabetical list of symbols, the loader prints the
address of the first free' memory location and the length, in octal
words, of each overlay defined. This information is useful in optimizing memory requirements.
Loader Error Messages
The loader prints error messages on the console terminal during
generation of a loader image file. Except where indicated in Table
8-6, loader errors are fatal. The loader returns control to the Keyboard Monitor when a fatal error condition is encountered.
Table 8-6

Loader Error Messages

Error Message

Meaning

BAD INPUT FILE

An input file was not a RALF module.

BAD OUTPUT DEVICE

. The loader image file device was not a
directory device, or the symbol map
file device was a read-only device.
The entire line is ignored.

ILLEGAL ORIGIN

A RALF routine tried to store data
outside the bounds of its overlay.

8-29

Table 8-6

Loader Error Messages (Coot.)

Error Message

Meaning

MIXED INPUT

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 .

MULTSECT

. Any
.
combination of entf}T point,
COMMON section (with the exception of multiple COMMONs) or program - section of the same name
causes this error, except as shown in
the following table.

ENTRY
. POINT SECT SECT8 COMMON COMMZ FIELD1
SECT
SECT8
COMMON
COMMZ
FIELD 1

MS
MS
MS
MS
MS

NO MAIN

MS
MS
MS
MS
MS

OK
OK
OK
MS
OK

OK
OK
MS
OK
MS

OK
OK
OK
MS
OK

No RALF module contained section
#MAIN.
The loader image requires more than
32K of core memory.

OVER IMAG

Output file overflow in the loader image file.

OVER SYMB

Symbol table overflow. More than 253
(decimal) symbols in one FORTRAN
job.

TOO MANY LEVELS

The 0 option was specified more than
7 times.

TOO MANY OVERLAYS

More than 16 overlays were defined in
the current level.

TOO MANY RALF FILES

More than 128 input files were specified.

8-30

The following FATAL error mess~ges occur when the Loader is
linking and relocating:
SY STEM ERROR
LOADER I/O ERROR
OS/8 ENTER ERROR

and indic.ate an error detected by OS/8 while trying to perform a
USR function.
All errors identified during the loading procedure are followed
by a line of the form:
1 00 nnn
where "1" is the level in which the error occurred, ~'oo" is the
overlay in which the error .occurred, and "nnn" is the module number, within the referenced overlay, that caused the error. Some
errors (e.g., NO MAIN) are 'attributable to a single module, and the
module numbers for this type of error are meaningless.
FORTRAN IV RUN-TIME SYSTEM (FRTS)
The OS/8 FORTRAN IV run-time system reads, loads, and
executes a loader image file produced by. the loader. It also.
configures a software I/O interface between the FORTRAN IV
program and the OS/8 operating system, then monitors program
execution to direct I/O processes anh identify certain types of runtime errors. The run-time system is called automatically to load
and execute the loader image file produced by the loader whenever
the G option is specified to the loader.
When chained to from F4, RALF, or LOAD, the run-tim.e system
reacts in one of two ways. If the last Command Decoder file/
option line was terminated with a carriage return, it immediately<
fetches the Command Decoder and proceeds ~s though it had been.
called from the Keyboard Monitor, as described below. The only
differ~nce, in this case, is that certain run-time -system options may
have been passed to the run-time system from the loader, and cannot be suppressed at this point. If the last file/option specification
line suppiied to the Command Decoder was terminated with. an
ALTMODE character instead of a carriage return, however, the
loader assumes that no user input is required. The Command
Decoder is not called. The loader image file just produced is read

8-31

as input, and, unless the H option was previously specified, it is
loaded and executed.
The FORTRAN IV Run-Time System is able to accept file I/O
specifications. This allows the user to write a source program which
refers to I/O devices as integer constants or variables. This program may be compiled, assembled, and loaded into an image file.
This image file may be run any number of times, each time specifying different physical I/O devices. Thus logical unit 8 may refer in
one run to the console terminal, in another run to a disk file, and in
another run to a paper tape punch.
These run-time specifications allow the FORTRAN program to
use the OS/8 file handling capabilities, to use any OS/8 supported
I/O device, and potentially to use any I/O device for which an
OS18 device handler can be written.
The following pages explain how the user gives the run-time
system the connections between OS/8 device and file names and
the FORTRAN logical unit numbers.
FORTRAN IV programs are usually saved as loader image files
and executed by calling the run-time system from the Keyboard
Monitor to load and execute the saved loader image. This is accomplished by typing:
R F'RTS

(terminated by a carriage return) in response to the dot generated
by the Keyboard Monitor. The run-time system replies by calling
the OS/8 Command Decoder to accept one or more stfu~dard file/
option specification lines. It recalls the Command Decoder after
processing each line, until a line terminated by an ALTMODE
character is received.
The run-time system accepts two classes of Command Decoder
file/ option specifications. The first class specifies the load module
to be executed; the second class specifies the run-time file assignment. When it is called from the Keyboard Monit'or, the run-time
system loads the Command Decoder to accept one input file name,
perhaps followed by the E or H option specifications, described in
cTable 8-7. This information is not required when the loader chains
to the run-time system because the loader image file just produced
is automatically read as input, while the Ecand/or H options could
8-32

have been specified to the loader along with the G specification that
requested chaining.
Thus, the loader image input file to be executed must be identified on the first file/option specification line when FRTS is called
from the Monitor, and must not be specified at all when the loader_
chains to FRTS. This Command Decoder line has the form:
*DEV:IMAGE.LD(options)
where IMAGE.LD is the loader image input file and ~'options" is E
or H or both. If this line is terminated by an ALTMODE, the program is executed; if it is terminated with a carriage return, the
Command Decoder is recalled to ~ccept run-time file specifications.
Once the loader image file to be executed has been identified, the run-time system recalls the Command Decoder to accept any
FORTRAN I/O device specifications. Of the nine I/O unit numbers available under FORTRAN IV, four are initially assigned to
FORTRAN internal device handlers by the system as follows:
I/O Unit Internal Handler Comments
1

2
3
4

paper tape reader Single character buffer.
paper tape punch Single character buffeJ.
line printer
LP8 and LS8E only. Ring buffered.
console terminal Double buffered ·output, single
character input.

The FORTRAN internal handlers listed_ above are not the same
as the OS/8 device handlers. The FORTRAN internal-handlers are
designed for ASCII text only and will _not execute -binary or core
image I/O. Also, FORTRAN internal handlers are interrupt driven
to execute foreground I/O concurrently with background computation.
FORTRAN internal device handlers may be assigned different
unit numbers, in addition to those listed above, by typing:
/n=m
(in response to the asterisk generated by the Command Decoder)
where m is the I/O unit number (1 to 4) of one of the internal
handiers listed above and n is a different unit number (1 to 9) which
is also to be assigned to that internal handler. This specification
8-33

causes ali program references to logicai unit n to perform I/O to
device m in the preceding table. For example:
/6=2

Assigns the FORTRAN internal paper tape punch
handler as I/O unit number 6, in addition to unit number 2.

/1=2

Assigns I/O unit number 1 to the FORTRAN internal
paper tape punch handler instead of the internal paper
tape reader handler.

OS/8 device handlers for non-directory devices may be assigned
I/O unit numbers by typing:
DEV:/n
(in response to the asterisk generated by the Command Decoder)
where n is an I/O unit number (1 to 9) and DEV: is the standard or
assigned designation for any supported non-directory device. For
example:
.
LPT:/3

Specifies the OS/8 line printer handler to be used instead of the FORTRAN internal line printer handler,
possibly because the line printer is not an LP08 or
LS8E.

Existing directory device files may be assigned I/O unit numbers
by typing:
DEV:FILE.EX/n
(in response to the asterisk generated by the Command Decoder)
where n is an I/O unit number (1 to 9) and DEV:FILE.EX is the

standard OS/8 designation for an existing directory device file. For
example:
DTAl:FORI0.TM/2

Assigns unit number 2 to DECtape file
FORIO.TM rather than to the FORTRAN internal paper tape punch handler, where FORIO.TM is an existing
file on D ECtape unit 1..

A directory device file that does not presently exist may be assigned a FORTRAN I/O unit number in the same manner by
entering it as an output file on the specification line; however, only
8-34

one such file may be created on any. particular d~vice. For example:
FORIO.TM</9

Assigns unit number 9 to file DSK:FORIO.
TM, which has not been created at load time.

In any case, only one device or file specification is permitted on
each line, and no more than 6 directory device files may be created
by the FORTRAN program. Excess files after the sixth are accepted and written, but they will not be closed. If a file created by
the program has the same file name and extension as a pre-existing
file, the old file is automatically deleted when the new file is closed.
The Command Decoder ''[n]!,: specification may be used to optimize storage allocation when assigning files that do not yet exist,
where n is a decimal number that indicates the maximum expected
length of the file, in blocks.
Each time a run-time I/O specification is terminated with a
carriage return, the Command Decoder is recalled to accept another
specification. When a specification is terminated with an ALTMODE, the program is run.
Although existing files are specified as though they were input
files and nonexistent files are specified as though they were output
files, any file that has been assigned a unit number may be used for
either input or output. The content of a nonexistent file is undefined
until it has been written by the program.

Table 8-7

Run-Time System Option Specifications
Operation

Option

Halt after loading but before starting the program.
Press the CONTinue switch on the processor, to commence execution.

Ignore the following run-time system errors, any of
which indicates that· an error was detected earlier in
the compilation/ assembly/loading process:
a. Illegal subroutine call.
b. Reference to an extern in an overlay other than
in the. form "JSR EXTERN" (i.e., CALL statement).
c. Reference to an undefined symbol.

8-35

Table 8-7

Run-Time System Option Specifications (Cont.)

Option

Operation
Any of the above may lead to unpredictable program
behavior as, in general, some portion of the program
will not be loaded or executed:

Carriage control switch. The first character on every
output line is processed as a carriage control character
(see FORTRAN IV LANGUAGE SUMMARY by all
FORTRAN internal handlers and aiso by the OS/8
hard copy handlers TTY .and LPT. The first character
on every output line is processed as data, in the same
manner as any other character, by all OS/8 handlers
except TTY and LPT. Entering a C option specification on the command line that assigns an II 0 unit
number to a particular handler reverses the processing
of carriage control characters for that device. Thus:
TEMP(2C)
assigns file DSK: TEMP. as II 0 unit 2. The C option
causes the first character of every output line to be
processed as a carriage control character. If C were
not specified, these characters would be processed as
data.
IC/6=3
assigns the FORTRAN internal line printer handler
as !/ OUDit 6, as well as unit 3. The first character of
every line will be processed as a carriage control character on unit 3, and as a character of data on unit 6.

The 08/8 FORTRAN IV run-time system executes with the
PDP-8/E interrupt system enabled. OS/8 device handlers are not
interrupt driven; however, certain handlers may execute with the
interrupt system enabled because the devices they control have interrupt enable switches which the handlers do not set. FRTS allows
for this by running with the interrupt system enabled when driving
handlers of this type, and disabling the interrupt system when a
handler that does not run under interrupts is loaded. Handlers that
can run with the interrupt system enabled include:
TC08 DECtape system handler and nonsystem handlers DTAO
to DTA7
RF08 system handler
8-36

RK8 system handler and non system handlers RKAO to· RKA3
RK8E system handler and nonsystem handlers RKAO to RKA3
and RKBO to RKB3
Any FORTRAN internal handlers
These OSj8 handle~s do not permit interrupts from these devices,
but they do permit other devic~s, e.g., CLOCK, to interrupt the
data transfer. Note that TD8E is absent from this list because the
TD8E data transfer cannot be interrupted.
The run-time system recognizes two classes {)f error conditions.
Certain errors are diagnosed while the tore image file is being read
from a storage device and loaded into core memory. Other errors
may occur during execution of the FORTRAN program. Both
classes of run-time errors are identified on the console terminal.
Table 8-8 lists the FRTS error messages and describes the error
condition indicated by -each message. The run-time system error
traceback feature provides automatic printout of statement numbers
corresponding to the sequence of executable statements that terminated in an error condition. At least one statement number is
always printed. This .number identifies the erroneous statement or,
, in certain cases, the last correct statement executed prior to the
error. When"ft statement was compiled under the N option, 'however, the system cannot generate meaningful statement numbers
during traceback.
The console terminal serves as FORTRAN I/O·unit 4 for both
input and output. Terminal input is automatically echoed on the
. console printer. In addition, the run-time system monitors the keyboard continually during execution of a FORTRAN program.
Typing CTRLjC at any time causes an immediate return to the
OS/8 Monitor. Typing CTRL/B branches to the system traceback
routine, and then exits to the monitor. This traceback routine
causes a printout, similar to the error traceback, including the current subroutine, the line number in the next higher level subroutine
from which it was called, etc., to the main program. This facilitates
locating infinite loops when debugging a program. The following
additional special characters are recognized by the console terminal
handler and processed as shown:
RUB OUT

Deletes last character accepted.

CTRL/U

Deletes current line of input.
8-37

CTRLjI

(Tabulation.) Converted to appropriate number of
spaces.

CTRLjZ

Signals end-of-file on input.

Tentative output files (that is, files created by the FORTRAN
program) are closed automatically upon successful completion of
program execution provided that either:
1. An END FILE statement referencing the file was executed.
FRTS assigns a file length equal to the actual length of the file.
2. The last operation performed ()n the file was a write operation.
FRTS proceeds as though an END FILE statement had_been
executed.
3. A DEFINE FILE statement referencing t!Ie file was executed
but an END FILE statement was not executed. Upon completion of program execution, FRTS assigns a file length equal to
the length specified in the DEFINE FILE statement.
Execution of a REWIND statement does not close a tentative
file, nor does it modify the tentative file length.
Run-Time System Error Messages
The run-time system generates two classes of error messages.
Messages listed in Table 8-8 identify errors that may occur during
execution of a FORTRAN program and errors that· may be en'countered when the run-time system is -reading a loader image file
into memory in preparation for execution, or accepting I/O unit
specifications. Except where indicated, all run-time system errors
cause full traceback and an immediate return to the monitor. Nonfatal errors cause partial traceback, sufficient to locate the error,
and execution continues.
Table 8-8

Run-Time System Error Messages

Error Message

Meaning

BAD ARG

Illegal argument to library function.

CAN'T READ IT!

II 0 error on reading loader image file.

CAUTION-NO DP

The present hardware configuration
does not include an FPP-12 FloatingPoint Processor with double precision
option. Execution continues; however,

8-38

Table 8-8. Run-Time Syst~m ~or Messages (ConL)
Meaning

Error Message

all double precision operations ~efau1t
to real arithmetic (with unpredictable
results) and all complex operations
also produce unpredictable results.
D.F. TOO BIG

Product of number of records times
number of blocks per record exceeds
number of blocks in file. Note that for
a random access file the length in
OS/8 block-s must be no less than the
number of records times the integer
but must be greater than the quotient
of floating point variables per record
/
divided by 85.

DIVIDE BY 0

Attempt to divide by zero. The resulting quotient is set to zero and
execution continues.

EOF ERROR

End of file encountered on input.

FILE ERROR

Any of:
a. A file specified as an existing file
was not found.
b. A file specified as a nonexistent file
would not fit on the designated device.
c. More than 1 nonexistent file was
specified on a single device.
d. File specification contained "*,, as
name or extension.

FILE OVERFLOW

Attempt to write outside file boundanes.

FORMAT ERROR

Illegal syntax in FORMAT statement.

FPP ERROR

Hardware error on FPP start-up.

INPUT ERROR

Illegal character received as input.

I/O ERROR

Error reading or writing a.file, tried to
read from an output device, or· tried to
-write on an input device.

MORE CORE REQUIRED

The space required for the program,
the 110 device handlers, II 0 buffers
and the resident Monitor exceeds the
available core.

-.-.-"- ---.'- .......

8-39

Table 8-8

Run-Time System Error Messages (Cont.)
w

Error Message

Meaning

NO DEFINE FILE

Direct access I/O attempted without a
DEFINE FILE statement.

NO NUMERIC SWITCH

The referenced FORTRAN 1/0 unit
was not specified to .the run-time system.

NOT A LOADER IMAGE

The first input file specified to the runtime system was not a loader image
file.

OVERFLOW

Result of a 'computation exceeds upper
bound for that class of variable. The
result is set equal to zero and execution continues. This error is detected
~nly if an FPP is present.

OVERLAY ERROR

Error while reading overlay.

PARENS TOO DEEP

Parentheses nested too deeply in FORMAT statement.

SYSTEM DEVICE ERROR

II 0 failure on the system device.

TOO MANY HANDLERS

Too many II 0 device handlers are
resident in memory, or files have been
defined on too many devices.

USER ERROR

Illegal subroutine call, or call to undefined subroutine. Execution continues
only if the E option was requested.

UNIT ERROR

II 0 unit not assigned, or. incapable of
executing the requested operation.

FORTRAN IV LIBRARY
The OS/8 FORTRAN IV system contains a general purpose
FORTRAN library FORLIB.RL, which may be extended and
modified by the librarian LIBRA. The library gives the programmer the capacity to compute arithmetic and transcendental functions, use, the complex and'double precision options of the FPP,
read console -switches,' and interface with standard laboratory
peripherals.

8-40

The 05/8 FORTRAN librarian, LffiRA, is used to create and
maintain libraries of RALF modules. The loader uses one such
library, specified by the us~r, to resolve undefined external symbols.
Each library contains· a collection of RALF modules and a catalog,- .
which lists the program section names and entry points defined in
the modules, along with sufficient information for the loader to find
them.
LffiRA's tasks are to create libraries (and their catalogs) from
user-specified sets of modules (RALF output files), to add new
modules to existing libraries, to copy the contents of a library to a
new library (all with various options on selective deletion and replacement during the copy), and to list the catalogs of libraries.
To create a library, call LmRA by typing:
R LI BRA

in response to the dot generated by the Keyboard Monitor. LIBRA
loads the OS /8 Command Decoder, which prints an asterisk at the
left margin. In response to the Command Decoder's asterisk, type.
in the following order:
1. The output device and name of the library to be created (LIBRA
assigns the extension .RL unless one is specified). If no output
file is specified, the default name FORLIB.RL is used and output is to the system device;2. The desired number 'of .index blocks (decimal, maximum 255)
enclosed in square brackets. LIBRA allocates two index blocks
if no specification is given.
3. The output device for the catalog listing when the library build
is complete (preceded by a comma). If no device is specified,
the listing is suppressed.
4. The input files (RALF output modUles) or libraries to be in- .
eluded in the library (preceded by a backarrow or left angle
bracket).
5.· Options: .
/C to continue input specification on next line.
/1 if a decision is to be made on insertion of each entry point
or section name.
, /Z if an existing file··of the same name is to be replaced by the
•
new library.
8-41

IR if a new input file is to replace a module of the same name
already in the library.
The option if extra blocks are to be allowed for library expan,..

Slon.
• R LI BRA
*LI Bl. RL[ 5] .. TTY: <LI 80. RL .. Rl .. R2 .. R3 .. R4 .. RS .. R6/Z=20

For the above command, a library named LIB1.RL is created on
the system device containing the existing library, LIBO.RL, and
the files R1, R2, ... , R6. Five blocks are allocated for the index;
the catalog is printed on the console terminal and 20 (octal) extra
blocks are reserved for future expansion. The IZ indicates that if a
file already exists with the name LIB 1.RL, it is to be replaced by
the newly created library.
If there are more than nine,modules to be included, type Ie to
continue input specification on the next line. Note that the "="
option and the output device for the catalog listing must be specified
on the last line (that is, the one without Ie). The IZ, if it is used,
must appear on the first line.
• R LI BRA
*LI 81. RLIZ ( 5] <R 1.. .R2 .. R3 .. R4 .. R5 .. R6 .. R7 .. R8 .. R9 .. R t0/e
TTY: < R 1 0 .. R 1 1 20

In this case the library now contains the additionai fiies R 7, R8,
... ; Rl1. The II and /R options can be specified at any point in the
command line. Both II and IR apply only to modules listed on the
line in which they appear.
.
To expand a previously created library, call LIBRA as usual.
Specify the name of the old library file as the first output file, the
catalog listing file, if desired, next, and then the modules or libraries
to be added as input. DOflot specify IZ. '
• R LI BRA

*LIB 1• RL .. TTY: < R OU T.. M00
LIBRA adds the contents of ROUT and MOD to LIB 1. If the old
library file name does not exist, a new library is created using default options if necessary. Since LIBRA cannot change the size of
the index or the room left for expansion at this time, it is useless
to specify index blocks and expansion blocks.
8-42

If a module entry point or section name being added to a library

duplicates a name in the library catalog,· the, duplicate name is
printed on the terminal. The name in the catalog continues to refer
to the original module, unless:

IR is specified on a command line, then the new module is put in
the library and the old module of the same name is deleted (unless there are other names for the
old module, in which case only
I
the d!lplicate name is deleted). For example:

causes any of the input modules Rl, R2, and R3 to replace existing modules in LIBO.RL with the same entry point or section
name.

II is specified on the LIBRA command line, then input file entry
points and section names are listed on· the console terminal. If
the names duplicate names in the catalog, the message printed is:
xxxx IS DUPLICATE NAME; KEEP OLD OR NEW?
where xxxx is an entry point or section name. LIBRA waits for
the user to type OLD and a RETURN (or just a RETURN or 0
and a RETURN) to keep the old name; NEW and a RETURN
(or N and a RETURN) to delete the use of the old name and
include the new. The question is repeated if any other character
is typed.
If the new names do not appear in the catalog, the message typed
IS:

xxxx: INCLUDE?
where xxxx is the new entry point or section nanie.
Type YES and a RETURN (or just a RETURN or Y and a
RETURN) to include the name or NO and a RETURN (or N
and- a RETURN) to omit it. The question is repe~ted if any other
character is typed.
A catalog listing can be obtained at any time by omitting the
input file specification in the call to LIBRA. For example:
.R LIBRA

* FORLI B. RL~ LPT: <
8-43

prints the catalog of FORLIB on the line printer. LIBRA:s version
number (V xx) is output as part of the _catalog heading.
Entry points and section names may be deleted from the catalog
by combining the I and Z options. Each catalog entry is listed on
the console terminal with the message:
name: INCLUDE?
Type Y and RETURN to include the section name or entry point;
type N and RETURN to delete'it. If all catalog entries corresponding to a particular module are deleted from the catalog in this
manner, the module is deleted from the library and the message:
MODULE IS DELETED
is printed on the console terminal.
FORLIB.RL, the standard library supplied with the FORTRAN
IV system, contains functions and subroutines that perform mathematical calculations and drive various peripheral devices. This
library may be modified with LIBRA to fit the needs of a particular
installation. Although at least one copy of the standard library
should be ~aintained as a backup, it may be desirable to delete
unwanted routines from FORLIB in order to reduce storage requirements. For example, double precision routines may be deleted
if an installation does not include an FPP-12 with extended precision option. Care should be exercised not to delete subroutines
that may be called by the various system programs or by other
library routines that are not deleted. Table 8-9 lists the library
routines that execute calls to entry points in other routines; in general, when an entry in the right column of Table 8-9 is· deleted, the
corresponding entry in the left column may not be called.
Table 8-9

FORLm Calling Relationships

Section N arne:

Executes Calls to:

SYNC
DISP
EXPIR
EXP3
ALOGIO
COS
TAN
SIND

DISP,ONQI
ONQB
EXP3
ALOG, EXP
ALOG
SIN
SIN, COS
SIN

8-44

Table 8,;,9

FORLIB Calling ReJationships (Cont.)

Section Name:

Executes Calls to:

COSD
TAND
ASIN
ACOS
ATAN2
SINH
COSH
TANH

SIN
TAN
ATAN, SQRT
ATAN, SQRT
ATAN

EXP
EXP
SINH, COSH

For example, to delete the entry points ABS, lABS, and LSW
from the catalog, the proper command to LIBRA is:

.R LIBRA
*LIBi.RLcLIB1.RL/I/Z

Respond with Y and a carriage return to all of the messages except:

lABS: INCLUDE? N
ABS: INCLUDE? N
MODULE I S DELETED

•
L SW :

I N CL UDE? N

The module containing ABS and lABS is deleted from the library
because all of its section names and entry points have been deleted
from the catalog. Entry point LSW is deleted from the catalog, but
the corresponding module remains in the library because other
entry points are still present in the catalog. Table 8-10 lists the
FORLIB entry points that are contained in modules with different
section names.
8-45

Table 8-10
Section N arne
lABS
SIGN
AMINO
AMAXO
DIM

PLOT
REALTM
CHARS
I FIX
AMOD
RSW
ONQI
SYNC

FORLm Multiple Entry Points by Section
Other Entry Points
ABS
ISIGN
AMINI, MINO, MINI
AMAXl, MAXO, MAXI
IDIM
SCALE, CLRPLT, #DISP
SAMPLE, ADB
CGET, CPUT, CHAR
AINT,INT
MOD
LSW, SSW, ROPEN, EXTLVL, RCLOSE
ONQB
CLOCK, TIME, #CLINT

,!,he catalog entries #FIX, #RFDV, #LTR, #EQ, #NE, #GE,
#LE, #GT, #LT, #EXPIR, #CLINT, and #EXPII are used
by the compiler and should not be deleted.
Library Functions and Subroutines
Library functions and subroutines are called in the same manner
as user written functions and subroutines. The following section lists
the iibrary components that are available to FORTRAN programs
and illustrates calling sequences, where necessary. Arguments must
be of the correct number and type, but need not have the same
name as those shown in the illustrative examples. Routines that
require LAB8/E or PDP-12 hardware are marked with an
asterisk*. Routines that will run on the FPP with extended precision option are marked with a dagger sign (t). Neither symbol
may be used in the actual FORTRAN program. Certain library
routines are used by the FORTRAN system programs and are not
available to a user's FORTRAN program. These routines may be
identified by the initial "#" character in the entry point or section
name, and are not listed in the following section.

ABS (SINGLE-PRECISION ABSOLUTE VALUE)
ABS calculates the absolute value of a real variable by leaving
the variab!e unchanged if it is positive (or zero) and negating the
variable if it is-negative.
8-46

ACOS (SINGLE-PRECISION ARC-COSINE FUNCTION)
ACOS calculates and returns the primary arc-cosine (in radians)
of a real argument less than. or equal to 1.0 according to the
relation:
If x> 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< f

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

atan(x) = x
atan(x) = l/x
atan(x)
1r12 - atan(11 x)
-atan(-x)
atan(x)

=
=

and the arc-tangent is then computed by a power series approximation.
8-49

ATAN2 (SINGLE-PRECISION ARC-TANGENT OF TWO ARGUMENTS)
ATAN2 accepts two real arguments, assumed to be an abscissa
and an ordinate respectively, and calculates the arc-tangent of the
quotient of the first argument divided by the second argument. This
is accomplished by calling ATAN to find the principal arc-tangent
of the quotient and then adjusting the result, depending upon the
quadrant in which a point defined by the arguments fall~, according to the relations:
argument in first quadrant
argument in second quadrant
argument in third quadrant
argument in fourth quadrant

atan2(y,x)
atan(y/x)
atan2(y,x) = atan(y/x)--1T
atan2(y,x) = atan(y/x)-1T
atan2(y,x)
atan(v / x H 11'

CABS'r (COMPLEX ABSOLUTE VALUE)
CABS accepts a complex argument and returns the ahsolute
value of the arl!ument as a real variable defined by:
.
~

CABS(X+iY) = SQRT(X**2+Y**7)
eCOSt (COMPLEX COSINE)
CCOS accepts a complex argument and returns the cosine of the
argument, a. complex number defined hy:
CCOS(X+iY) '= COS(X)*COSH(Y)--i*SIN(X)*SINH(Y)
CEXPt (COMPLbX EXPONENTIAL)
CEXP accepts a complex argument and returns the exponential
function of the argument, a complex variable defined by:
CEXP(X"l-iY) == EXP(X)*(COS(Y)+i*SIN(Y))
CGET (CHARACTER GET SUBROUTINE)
The calling sequence:
CALL COET (STRING,N,CHAR)
causes the Nth character to be unpacked from STRING and s~ored
in CHAR as a variable in the range 0, 63, where STRING is a
character string in A6 format.
CHKEOF (CHECK FOR END-OF-FILE SUBROUTINE)
CHKEOF accepts one real, integer or logical argument. After
the next formatted read operation, this argument will be set to
non-zero if the logical end-of-file was encountered,. or to 0 if the

8-50

logical end-of-file was not encountered. The following is an example of the use of CHKEOF:

,
CALL CHKEOF(EOF)
READ (N,101)DATA
IF (EOF.NE.O) GO TO 999

CLOCK* (INITIALIZE CLOCK SUBROUTINE)
The purpose of the CLOCK subroutine is to initialize certain
features of the KW12A or DK8ES real-time clock. The calling
sequence IS:
CALL CLOCK (FUNCTN,RATE)
Depending upon the arguments FUNCTN and RATE, CLOCK.
can enable Schmitt triggers, clock controlled AID conversions, or
run the clock at a variable rate. The clock is· always run on interrupt. Both arguments maibe either integer, real, or logical in
type. The first argument indicates a. class of clock functions, and
the second specifies a clock rate in Hertz. A common use of the
clock routine will be in conjunction with the REALTM subroutine.
With one exception rioted below, the clock routine is independent
of hardware type. That is, a program employing the KW12A clock
on a PDP-12 does not require modification to run on a PDP-8. The
FUNCTN argument controls. the enabling of all Schmitt triggers,
clock controlled AID conversions, and clock rate or external input
according to the scheme shown in Table 8-11 ..
Combinations of the conditions in Table 8-11 may be enabled by
setting FUNCTN to a value equal to the sum of the values of the
desired conditions. For example, to enable all Schmitt triggers, set
FUNCTN=7 (the sum of 4, 2, and 1); to enable clocked AID
conversion at an external rate, set FUNCTN. 24, etc. If a clock
condition is not specified, the clock is disabled. Every call to
CLOCK clears any functions which may have been enabled by
previo1.Js calls to CLOCK and redefines clock conditions according
to the new arguments. If the FUNCTN argument is out of range
8-51

(e.g., negative), the clock conditions enabled are arbitrary. Once
the clock has been started, the calling program may disposition a
Schmitt trigger via the SYNC subroutine, read the tiine of day via
TIME, or use the clock in conjunction with some other routine
such as REALTM. Schmitt triggers 1, 2 and 3 correspond to the
DK,8ES events 1, 2 and 4, respective1y, or the KW12A clock channels I, 2 and 3, respectively.
Table 8-11

CLOCK Subroutine FUNCTN Arguments

Value of
FUNCTN

o
1
2
4
8
16

Effect
none, or enable clocked AI D conversion, more than one
channel
enable Schmitt trigger 1
enable Schmitt trigger 2
enable Schmitt trigger 3
enable clocked AI D conversion, one channel
enable the clock to run under external input

The rate at which the clock runs is specified by the argument
RA TE, wh~ch has two different meanings that are dependent upon
tl,&> 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)

100'
?~~R
()?~
........ 'oe...................
_-

= EXP(lxj - 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
100 FOhMATC'
. clEf! IN A~CII
'1 A6)
WRI lEe 41 101>
101 FORMAT<'
tiE'f! IN DECIMAL'}
DO 10 1= 114
CALL CGETC SlIu III CrlAFO
WhITE,(41102) ICnAR
10 CONTINUE
102 FORo1ATC 16)
DO 20 1= 1.. 6
J=2*I
CiLL CPlITC SI& II J)
20 COl~TINUE
WRITE(41103) SIR
103 FOhMATC'
NEW STRING
'IA6)
CALL EXI T
E.'l'D
~RITEt41

.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<X<l.O, ATAN(X) = ATAN(1I2)+ATAN(2X-l)
X+2

and the arc-tangent is then calculated as a continued fraction
approXImatIon.
•

4-'

DATAN2t (DOUBLE-PRECISION ARC-TANGENT OF TWO
ARGUMENTS)
DATAN2 accepts two double-precision arguments, assumed to
be an abscissa and an ordinate respectively, and calculates the arctangent of the quotient of the first argument divided by the second
argument. The result is then adjusted, depending upon the quadrant in which a point defined by the arguments falls, in the same
manner as for the ATAN2 function.
DATE (OS/8 DATE SUBROUTINE)
DATE accepts three integer arguments, accesses the current
OS/8 system date, and returns an integer from 1 to 12 corresponding to the current month as the first argument, an integer from 1
to 31 corresponding to the current day as the second argument, and
an integer from 1970 to 1977 corresponding to the current year as
the third argument.
DBLEt (SINGLE- TO DOUBLE-PRECISION CONVERSION)
DBLE accepts a real argument and returns a double-precision
value equal to the argument, filled out with zeroes in the low-order
three words.
DCOSt· (DOUBLE-PRECISION COSINE FUNCTION)
DCOS calculates and· returns the cosine of a double-precision
argument (in radians). This is accomplished by adding PI/2 to the
'argument and passing this result to the DSIN function.
DEXPt (DOUBLE-PRECISION EXPONENTIAL FUNCTION)
DEXP calculates and· retut:D.s the exponential function of its
double-precision argument by applying the method of Kogbetliantz
(ffiM Journal of Research and. Development, April, 1957, pp
i 10-5).
8-56

DIM (SINGLE-PRECISION POSITIVE REAL- DIFFERENCE)
DIM calculates and returns the positive difference of two real
arguments. That is, if the first argument is larger than the second
argument, DIM returns the difference between the arguments; if
the first argument is less than or equal to the _second argument,
DIM returns 0.0.
DLOGt (DOUBLE-PRECISION NATURAL LOGARITHM)
, DLOG .calculates. and returns the natural (Naperian) logarithm
of its double-precision argument. Thi~ is accomplished by reducing
the range of the argument through application of a method described by Ralston and Wilf in their text, Numerical Methods for
Digital Computers, and then performing a Taylor series expansion.
'"

DLOGIOt (DOUBLE-PRECISION COMMON LOGARITHM)
DLOG 10 calculates and returns the common (base 10) logarithm
of its double-precision argument by extracting the natural logarithm:and executing a change of base.
DMAXJ t (DOUBLE-PRECISION MAXIMUM VALUE).
DMAXI accepts an arbitrary number of double-precision arguments and returns the largest of the arguments.
DMINI t (DOUBLE-PRECISION MINIMUM VALUE)
DMINI accepts an; arbitrary number of double-precision arguments and returns the smallest of the arguments.
DMODt (DOUBLE-PRECISION A MODULO B FUNCTION)
- DMOD accepts two double-precision arguments and returns a
double-precision 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.
DSIGNt (DOUBLE-PRECISION TRANSFER-OF-SIGN)
DSIGN accepts two double-precision 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 this value
if the second -argument is negative.
8-57

DSINt (DOUBLE-PRECISION SINE FUNCTION)
DSIN calculates and returns the sine of a double-precision
argument (in radians). The argument is first reduced to the range
[0, Plj2] , and the sine is .then calculated from a Taylor series
.
approximation.
DSQRTt (DOUBLE-PRECISION SQUARE ROOT)
DSQRT calculates and returns the (positive) square root of a
positive double-precision argument. Any negative argumen.t results
III an error message.
EXP (SINGLE-PRECISION EXPONENTIAL FUNCTION)
EXP calculates and returns the exponential function of a real
argument. The algorithm uses a nQmerical method after
Kogbetliantz (IBM Journal of Research and Development, April,
1957, pp 110-5).
EXTLVL* (READ PDp.. 12 EXTERNAL LEVEL)
EXTLVL accepts two integer, real or logical arguments. The
first argument is assumed to be a PDP-12 external level number in
the range [0, 12]. If the referenced external level is at +3 volts
(floating), the second argument is set equal to O. If the referenced
external level is at 0 volts (ground), the second argument is set
equal to 1. If the first argument is outside the range [0, 12], the
value returned in the second argument is unpredictable. If
EX'fLVL is called on a PDP-8, the second argument wiil aiways
be set to zero.
FLOAT (INTEGER-TO-FLOATING-POINT CONVERSION)
FLOAT accepts an integer argument and returns a real variable
equal to the argument.
lABS (INTEGER ABSOLUTE VALUE FUNCTION)
lABS calculates and returns the absolute. value of an integer
variable by leaving the variable unchanged if it is positive (or
zero), and negating the variable if it is negative.
IDIM (INTEGER POSITIVE DIFFERENCE FUNCTION)
IDIM calculates and returns the positive difference of two
integer arguments. That is, if the first argument is larger than the
second argument, IDIM returns the difference between the arguments; if the first argument is less than or equal to the second
argument, IDIM returns a value of O.
8-58

IDINT (DOUBLE-PRECISION INTEGER TRUNCATION)
IDINT accepts a double-precision argument and returns the
largest integer that is less than or equal to the argument.
IFIX. (SINGLE-PRECISION FLOATING-POINT-TO-INTEGER FUNCTION)
IFIX 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. IFIX, AINT and INT perform the·
same function.
TNT (SINGLE-PRECISIONFLOATING-POINT-TO-INTEGER)
INT· is a floating-point truncation function that performs the
same function as AINT and IFIX.
ISIGN (INTEGER TRANSFER OF SIGN FUNCTION)
ISIGN accepts two integer 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 this value if the
second argument is negative.
LSW* (READ PDP-12 LEFT SWITCH REGISTER)
LSW accepts two real, integer or logical arguments. The first
argument is assumed to be a PDP-12 left switch register switch
number in the range [0, 11]. Upon return, the second argument is
set to the logical value of the referenced switch (either 0 or 1). If the
first argument is outside the range [0, 11], the result that will be
returned in the second argument is unpredictable. If LSW is. called
on a PDP-8, a value of Q is always returned.
MAXO (SINGLE-PRECISION MAXIMUM VALUE)
MAXO accepts an arbitrary number of integer arguments and
returns an integer result equal to the largest of the arguments.
MAXI (SINGLE-PRECISION MAXIMUM VALUE)
MAX 1 accepts an arbitrary number of real arguments and
returns an integer result equal to the largest of the arguments.
MINO (SINGLE-PRECISION MINIMUM VALUE FUNCTION)
MINO accepts an arbitrary number of integer arguments and
returns an integer value equal to the smallest of the arguments.

·8-59

MIN 1 (SINGLE-PRECISION MINIMUM VALUE FUNCTION)
MINI accepts an arbitrary number of real arguments and returns
an integer value equal to the smallest of the arguments.
MOD (INTEGER A MODULO B FUNCTION)
MOD accepts two integer arguments and returns an integer
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, 3...'1 error message and a value of 0 are
returned.
ONQB (PLACE TASK ON BACKGROUND JOB CHAIN)
ONQB is a subroutine which is called from PDP-8 mode RALF
code to place a PDP-8 mode task on the list of background tasks.
These background tasks are' executed in round-robin order whenever the PDP-8 processor has nothing to do (e.g., while waiting for
terminal input). If FPP-12 hardware is present, these background
subroutines execute in parallel with the execution of the
FORTRAN program by the FPP-12. ONQB is called by a
sequence such as:
JMS%
ADDR

XONQB+l
BRJOB

EXTERN ONQB
ONQB
XONQB, ADDR
where BRJOB is the address of the background job, a subroutine
which must obey all the conventions of ONQI. ONQB resides in
field 1 and should only be called from field 1. See the FORTRAN
IV Software Support Manual for details.
ONQI (PLACE INTERRUPT HANDLER ON SKIP CHAIN)
ONQI is a subroutine which is called from PDP-8 mode RALF
code to put the interrupt handler of a device on the interrupt skip
chain. When an interrupt is received by the PDP~8 processor, the
processor checks each device on the skip chain, then the FPP, then
the standard FORTRAN peripherals, e.g., line printer. If the
interrupt was caused by a device with a handler on the skip chain,
. the PDP-8 processor branches to the handler. ONQI is called by a
sequence such as:
8-60

JMS%
lOT
ADDR

XONQI+l
IHNDLR

XONQI,

ADDR
ONQI
EXTERN ONQI
where lOT is the actual lOT code for the device skip-on-flag instruction and IHNDLR is the address of the interrupt handler for
this device. ONQI always resides in field 1 and must be called by
PDP-8 mode RALF code in field 1 only. The interrupt handler is
entered with the AC cleared and the data and instruction fields set
to 1. It should return with these registers in the same state. ONQI
should not be called more than once for any given lOT.
PLOT* (DISPLAY DATA ON PDP-12 ORLAB-8/E SCOPE)
The calling sequence:
CALL PLOT (M,X;Y)
plots M points whose X coordinates are in the array X and whose
. Y coordinates are in the array Y into the plot buffer specified by
the CLRPLT routine. A background task plots the contents of aU
points entered into the plot buffer on the scope whenever the
PDP-8 processor would otherwise be idle. When X is 1, X and Y
are interpreted as scalars. The scope is scaled with (0,0) in the
lower left corner and (1.3,1.0) in the upper right corner.· These
values may be altered by a call to SCALE.
PLOTR * (CHANGE SCOPE BUFFER VALUES)
The calling sequence: .
CALL PLOTR (M,X,Y,I)
alters the M entries in the plot buffer beginning at the Ith entry)
getting the new X coordinates from the array X and the new Y
coordinates from the array Y. Calling this subroutine does not
alter the number of points displayed by the background display
task.
RCLOSE* (CLOSE A PDP-12 RELAY)
RCLOSE accepts an integer, real, or logical argument assumed
to be a PDP-12 relay number in the range [0, 5] and closes the
referenced relay. If the argument falls outside the specified range,
the result is unpredictable. RCLOSE has no effect when called
on a PDP-8.
8-61

REALt (COiVIPLEX-TO-REAL CONVERSION FUNCTION)
REAL accepts a complex argument and returns a real value
equal to the real part of the argument.
REALTM* (BUFFERED/CLOCKED SAMPLING)
. REALTM performs buffered/clocked sampling on the PDP-12
or LAB-8/E. The calling sequence is:
CALL

REALTM

where:
BUFFER

(BUFFER,LENGTH.CSTART,NCHANL, NPTS)

= array to be used by REALTM as a ring buffer.

LENGTH '= size of BUFFER.
CSTAR T = first channel to sample at each clock interrupt
(0-15).
NCHANL = number of channels to sample at each time step.
If NCHANL = 1, then argument 1 of the call to
CLOCK may specify clock-initiated AID sampling (8 images). If NCHANL> 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 -:.TY't1"\ 1.0

LV.&.

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

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.10<lxI<87.9~9, SINH(x) = 1/ 2 [EXP(x) - ~XP(X)-\

If Ixl::::;O.10, SINH(x) = X+X!1/fl + x5/12o
If Ixl>88.028. SINH(x) = [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 11~
~+-+--t-+-tB-Q."lI0, ,1,=,1,1"

,5,°1 '1,2,« I I

I I

I 1 I II

t I I I I

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

1111!

I:':' :::~'\~"5:ci~';'~T:
:(:1:\:):): :99: T8:4:::::::: ::::::::::::::::::::::: I::::::: i
105.1
.;.
~I

ITVPE

~ JRNT,I NU,E , , , "

""
~ ~+-+-t-"""""'+-+-+-+-+-+-+-+-I

105

.........,...............-;

I I

H-++-+++-++_: : : : : : : : : : : : : : : : : : : : : : I : : : : : : : : : : : : : : : : : : : : : :
I 1 I

, I

"FORMAT 114 'I S PR IME: ' l

....-+-+-

I-+-++++t->-++++++-+-!-+t-+ I ! 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.

Variable

Refers To

. ARRAY(l)

The first element of a onedimensional array named
ARRAY.

B(l,3)

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<;:) ~nn
nnm..
•• - ~n lntpoPT fn)
'-I <;:nf'rlfvlno
vr----,l---e> thp
.--- -----_~~~~~~~~v

~-~

--~~

~~_£~~~_£v,

-.~

.'~'-e>-~

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. Bw.a
2 .. Dw.d
3. Ew.d
4. Fw.d
5. Iw
6. 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<=M<l
l<'=M<lO

F(w-4).d,4X
F(w-4).(d-1),4X

lO(d-2)<=M<lO(d-l)
lO(d-l)<=M<lO(d)

F(w-4).1,4X
F(w-4).O,4X
Ew.d

All others

Scale factors may be written for B, D, E, F, and G conversion. A scale factor is written:
sP
where s is a signed or unsigned integer that specifies the scale
factor and P is the identifying character.
8-94

For F type conversions, the scale factor specifies a power of ten,
so that
external number

(scale factor)
(internal number) *10

For D and E conversions, the scale factor multiplies the fraction
by a power of ten, but the exponent is decreased accordingly leaving the number unchanged· except in form. For example, if the,
statement:

corresponds to the line
bb26.4S1 bbbb-0.41321E-Ol
then the statement

would correspond to the line
bbb2.64Sbbb-41.321SE-03
For G type output conversions, the scale factor is not used
unless the magnitude of the number is such that E format is used.
In input operations, the scale factor is not used if there is an exponent in the external field.
When no scale factor is specified, a scale factor of zero is assumed. Once a scale factor has been specified, however, it holds for
all subsequent B, D, E, F, and G type conversions within the same
format uriless another scale factor is encountered. A zero scale
factor may be resumed via an explicit specification. Scale factors
have no effect on I type conversions.

Logical Fields
Logical data can be described in a manner similar to numeric
data. A logical field description has the form:
Lw
where L IS the converSIOn code character and w IS an integer
8-95

specifying the field width. The data is transmitted as the value of
a logical variable in the input/output list. On input, the first nonblank character in the data field must be .T., T, .F. or F; the value
of the logical variable will be stored as .TRUE., .TRUE.; or
.FALSE., .FALSE., respectively. Leading blanks and the period
preceding the T or F are ignored. If the data field is blank, a value
of false will be stored. On output, w-l blanks followed by the
letter T or F, according to the variable's value, will be transmitted.
For example, if the specification were LIO, the output for the value
.TRUE. would be:
bbbbbbbbbT
Hollerith Data A Conversion
Hollerith data that is to be stored by the program is specified by:
Aw
where A is the conversion code character and w is. the number of
characters in the field. The alphanumeric characters are transmitted
as the value of a variable in an input/output list. The variable may
be of any type. The sequence:
READ (2 .. S)V

FORMAT CA4)

causes four characters to be read and placed in memory as the
value of the variable V.
The value of w is limited to the maximum number of characters
which can be stored in the space allotted for a single variable. If
w exceeds this amount, the extraneous rightmost characters are
lost on input, and on output the characters after the sixth (twelfth
with double precision) are not significant. If w i~ less than the number of characters which can be stored in the space allotted to the
variable, on input the characters are left justified and blank-filled on
the right of each list item. On output the leftmost w characters in
the variable are transmitted to the output field.
Hollerith Data H Conversion
Hollerith data which is not changed by the program is specified
by one of two forms. One, called H conversion, is:
nH
8-96

where H is the control character and n is the number of characters
in the string (including blanks). For example,-the format in the
statement below can be used to print PROGRAM COMPLETE on
the output listing.
FORMAT C17H PROGRAM COMPLETE) -

Referring to this format· in a READ· statement causes the 17
characters to be replaced with a new string of characters' from the
input file.
In the second form, the Hollerith data is simply enclosed in
single quotes. The output result is the same as in H conversion; on
output the characters. between the. quotes (including. . blanks) are_
written as part of the output data, as with Hollerith constants. This.
form is illegal on input. A quote character within the data is
represented by two successive single quotes. For example:
FORMAT CW PROGRAM.COMPLETE

A Hollerith format field may be placed among the other fields of
the format. For example, the statement:
FORMAT CISI7H FORCE=F.la.S)

can be used to output the line:
bbb22bFORCE=bb17.68901
Note that the separating comma may be omitted aft~r a
Hollerith format field. The legal characters in a Hollerith field are
the 64-character graphic subset of ASCII, with the exception of
" @ ", which must not be used.
I

Carriage Control

The first character of each ASCII record controls the spacing of
the line printer or Teletype. This character may be established by
beginning a FORMAT statement for aJ;l ASCII record with 1Hc,
where c is the desired control character. The line spacing actions,
listed below, occur before any printing:
8-97

Character
0
1

Effect

blank
zero
one

Advance carriage to next line.
Skip a line (double space).
Form feed-go to top of next page;
equivalent to 0 on TTY.
Suppress skipping-overprint previous line.

+ plus

For example, the program:
50

100

A= 14.
FORMAT C2F3.1)
X=CA-5.25)/2.5
WRITE C6" 100)X
FORMAT (lH!"F4.1)
STOP
END

moves the line printer paper to the top of the next sheet (lHl) and
prints b3.5 on the first line. If any unexpected character appears
first in the FORMAT statement, it is processed as a blank.
It is often desirable to print a prompting sequence, such as a
question, to which a response is to be entered on the same line.
To cause such prompting, a $ is included at the end of a FORMAT
statement that is associated with a- WRITE statement that has been
satisfied. This will inhibit the carriage return and line feed before
the next input. For example:

100
200

A=5
WRITEC4" 100)A
READC 4" 200) B .
FORMAT(' SAMPLE NO.'" 12,,' lSI'" $)
FORMATCA6)
WRITE(4" 200) B
END

The output is:
SAMPLE NO.
RED

5 ISs RED

8-98

Record Layout Specification
Input and output can be made to begin at any position within a
FORTRAN record by use of a field description of the form:

Tw
where T is the spacing control character and w is an unsigned
integer constant specifying the character position in a FORTRAN
record whe~e the transfer of datais to begin.
For printed output, w corresponds to the (w-l ph print position,
since the first character of the output buffer is a carriage control
character and is not printed. (A blank carriage control indicator is
assumed.) For example:
FORMAT (T30,,·' BLACK 'TS0" 'WHITE')

causes "BLACK" to appear in columns 29-33 and "WHITE" to
appear in columns 49-53. The statement:
FORMAT (TSI2I" 'BLACK'"T3I21'WHITE')

causes "BLACK" to appear in columns 49-53 of one line and »
"WHITE" to appear in columns 29-33 of the following line. Thetwo lines will constitute two separate records if later read as input.
On input, the statement:
1

FORMAT (T3S"FS.f2I)
READ (3" l)X

causes the first 34 characters of the input data to be skipped, and
the next f1ve characters to be used as the value of X. If an input
record containing
ABCbbbXYZ
is read with the format specification

then the characters XYZ and ABC are read, in that order. The
T -code can be used in a FORMAT statement with any other type
of format code.
8-99

Blanks can be introduced into an output record or characters
skipped on an input record by use of the specification:

nX
where the spacing control character is X and n is the number of
blanks or characters skipped and must be greater than zero. For
example, the statement:
FORMAi CSH

SiE?I5~ j~X2HY=F7.3)

can be used to output the line
bSTEPbbb28bbbbbbbbbbY=b-3.872
The preceding blank would not be printed on the terminal or line
printer.
DEFINE FILE STATEMENT
The FORTRAN program may read or write chosen records out
of a direct-access file without reading intermediate records. In the
more common. sequential access, the FORTRAN program must
read or write each record in turn until the correct record is found.
No DEFINE FILE statement is required for sequential access to
mass storage files.
The DEFINE FILE statement is required so that mass storage
files may be referenced as direct access files by input/output statements.
Form

DEFINE FILE al(bl,cl,U,vl),a2(b2,c2,U,v2), ..

Where

a is an integer constant or variable name that is the
symbolic designation for this file specified to the runtime system.
b is an integer expression that defines the number of
records in the file.
c is an integer expression that defines the .length (in
floating point variables) of each file record. Each
single precision integer or real variable or constant
requires one-floating point variable; double precision
and complex variables or constants require two.
8-100

U is a fixed argument designating that the file is
unformatted.
v is an -integer variable name, called the associated
variable, which is set at the conclusion of an input/
output operation on the file to point to the next
record.
Effect

Describes a: mass storage file for use with input/
output statements:

The associated variable (v) in a DEFINE FILE statement is
used to maintain an index of records processed.1t is set automatically after an input/output statement is executed. The statement:
DEFINE FILE 1<1000.,100.#U.#IVl)

specifies a lOOO-record file, each record of which is lOO floating
point variables long. The variable IVl will maintain an index of
records processed, providing a pointer to the next record.
The symbolic file designation (a) cannot be passed as a dummyargument to a define file statement in a subroutine.
INPUT/OUTPUT STATEMENTS
The input/output statements, READ and WRITE, govern
transfer of data records between internal storage and peripheral
devices. Each statement can contain an input/output list naming
the variables and array elements to be given values on input or
whose values are to be transmitted on output. Both formatted and
unformatted records can be transmitted. A formatted record requires the use of a format specification.
Input/Output Lists
,
An input/output list contains variable names and array elements -whose values
be assigned on input or written on output.
Constants are -not allowed as list items. During input, the new
values listed can be used in subscript or control expressions for
variables appearing later in the list. For example:

will

reads a new value for L and uses this value in subscripts of. A and

B.
8-101

The transmission of array variables may be controlled by indexing similar to that used in the DO statement. This is called an
implied DO and includes as a list element a parenthesized list of
control variables followed by the index control. For example:

is equivalent to:

The indexing may be compounded by nesting the implied DO's
as in the following:

The above statement reads in the elements of array MASS in the
following order:
MASS(l,I),MASS(2,1), ... ,MASS(4,l), MASS(l,2), ... ,MASS(45\

, If an entire array is to be transmitted, the indexing may be
omitted and only the array name wcitten. The array is transmitted
in order of increasing subscripts with the first subscript varying
most raoidlv.
Thus. the examole above could have been written:
..L.
~

assuming that the array MASS is dimensioned MASS(4,5). The
same statement can transmit integer and real quantities. If the data
to be transmitted exceeds the items in the list, the extra data is
ignored.

Input/Output Records
All data is transmitted by an input! output statement in terms of
records. The maximum amount of information in one record and
the manner of separation between tecords depends upon the
medium. For punched cards, each card constitutes one record; on
a terminal, a record is one line; for ASCII records, the amount of
information is specified by the FORMAT reference and the I/O
8-102

list; for magnetic tape binary records, the amount of information is
specified by the I/O list.
Each execution of an input or output statement initiates the
transmission of a new data record. If an input; output statement
requests less than a full record of information, the unrequested
part of the record is lost and cannot be recovered by another input/
output statement without repositioning the record. Repositioning is
not possible on all devices, however. If an input/ output statement
requires more than one ASCII record of information, successive
records are read in sequence.
The READ Statement
Form

Where

Effect

READ (u,f) list
READ (u,£)·
READ (u) list
READ (u)
READ (a'r) list

formatted READ
unformatted READ

direct access mass
storage READ
u is an input unit designation
f is a format statement reference number
list is an I/O list of yariable names
a is a symbolic mass storage file number (unsigned
integer constant or integer variable)
, designates direct access
r· is the record number where transfer begins
(integer expression)
Input is performed according to the arguments of
the READ statement.

The unit designation(u) referred to in READ statements must
be an integer in the range 1 to 9. Unit designations are assigned
via a, device specification command to the run-time system. If
device specifications are not made, the system assumes the standard
device designations. given in the section on the FORTRAN IV
Run-Time system. Thus; READ (1,10) could refer to input from
the high-speed paper tape reader, and READ (4,11) could refer to
input from the terminal. Formatted and unformatted records
should not be mixed on a single unit.
8-103

A formatted READ statement causes information to be read
from the specified unit and put in memory. The data are converted from· external to internal form as specified by the referenced
FORMAT statement. If an I/O list is provided, the data are stored
as the values of the listed variables. The second form of the for. matted READ statement is used if the data are transmitted directly
into the specified format. For example,
READ (5" 50) AI B" C
READ (ll" 100)

Detection of end-of-file during input causes a fatal run-time system
error unless the library subroutine CHKEOF was called. CHKEOF
should only be used with formatted I/O involving a single record.
When a comma is encountered on input, this signals the end of
the current field and causes the next input character to be read as
the first character of the next input field.
An unformatted READ statement causes binary information
to be read from the unit designated and stored in memory as values
of the variables in the I/O list, if any. If the record contains more
words than the list requires, that part of the record is lost. If more
items are in the list than are in one record, additional records are
read until the list is completed.
A direct access READ statement provides random access to
fixed-length records in a mass storage file. The file whose records
are to be read must be defined by a DEFINE FILE statement. For
example,
DEF1NE FILE ATC(100"100"U,,PT)
READ (ATC'S)ARRAY

The WRITE Statement
Form

WRITE (u,f) list
WRITE (u,f)
WRITE (u) list

formatted WRITE

WRITE (u)

unformatted WRITE

WRITE (a'r) list

Direct access
WRITE
8-104

mass

storage

Where

u is an output unit designation (unsigned integer
constant or variable)
f is a format statement number
. list is an I/O list of variable names
a is a symbolic mass storage file number
, designates direct access
r is an associated variable (record pointer)

Effect

Output is performed as specified by the arguments of
the WRITE statement.

The unit designation (u) referred to in WRITE statements may
be an integer in the range 1 to 9. 'Unit designations are assigned
via a device specification command to the run-time system.
A formatted WRITE' statement may appear with or without an
I/O list. If a list is provided, the values of the variables in the list
. are read from memory and written on the unit designated in ASCII
form. The data is converted to external form as specified by the
desi,gnated FORMAT statement. If no list is supplied, information
is read directly from the· specified format and written 'on the
designated unit in ASCII form. For example:
~JWITf:

1~0

(2,101il)

FORMAT t'

OUTPUT R~~CRO~)

. will produce the following record on unit 2:
OUTPUT RECOWO

In the case of an unformatted or direct-access WRITE, the
values of the variables in the list. are~read from memory and written
on the unit designated in binary form. A record holds 85 single
precision variables. If the list elements fill more than one record,
successive records are written until the list is completed. If the list
elements do not fill the record, the remaining part of the record
contains 'unknown data. Thus, if there are 100 variables' in the list,
two records are used; one record contains 85 variables and the
8-105

second record contains 15 variabies and unknown data. For
example:
OII'llENSIUN It(200)
WRITE (~) )(

will produce three records on unit 6, the first will contain X(l) to
X(85); the second will contain X(86) to X(170), and the third will
contain X( 171) to X(200).
A direct access WRITE statement outputs a fixed-length record
directly into a mass storage file. The file must have been d~fined
previously via the execution of an appropriate DEFINE FILE
statement. For example:
DIMENSIUN RAV(10)
nEFIN~

FILE 1(12,10,U,J)

J:al

00 5 1-1,1-2
ld~

RE..AD (2,11d0) RAY
FORMAT (10F~.0)
WRITE Cl"J) RAV

CONTlNUt:.
CALL. e,XIT

END

DEVICE CONTROL STATEMENTS
There are three device control statements-BACKSPACE,
END FILE, and REWIND, which apply to any file-structured
device (DECtape, and disk). Their forms and effects are listed in
. Table 8-16.
Table 8-16

Device Control Statements
Effect

Statement
BACKSPACE u

If the next record which would be read or written
on unit (u) is n, BACKSPACE repositions the
unit so that the next record to be read or written
will be n -1. If the first record is the next record
to be read or written, the BACKSPACE statement has no effect.

8-106

Table 8-16

Device Control Statements (Cont.)

Statement

Effect

REWIND u

Repositions the designated unit (u) to the beginning of the file. If the unit is at the beginning of
the file, the REWIND statement has no effect.

END FILEu

Writes an END-OF-FILE character in the specified file (u), provided that the file has been written on by a formatted WRITE. END FILE does
not execute a REWIND.

Specification Statements
Specification statements may be divided into three categories:
Storage specification statements, DIMENSION, COMMON and
EQUIVALENCE, which give the compiler storage allocation
instructions; data specification statements, DATA and BLOCK
DATA, which are used to enter values; and type declaration statements, INTEGER, REAL, DOUBLE PRECISION, COMPLEX,
and LOGICAL, which specify the type of variable.

STORAGE SPECIFICATION STATEMENTS
DIMENSION Statement
Form

DIMENSION name1 (u1, ... ,u7), name2

(v1;.~.,v7), ...

Where ul, ... ,u7 and vI, ... ,v7 are the maximum values of
the subscripts <they represent, up to a maximum of seven
subscripts.
r

Effect

The array name assigns the type to the array. Storage
is allocated according to the dimensions given.

Each array specification gives the array name and the maximum
size which each of its subscripts may assume. Array size is limited
to 4096_ elements. Each size specification must be a non-zero
positive integer constant. For example:

. defines A as a on'e dimensional array variable with storage locations for 10 FPP words. In floating-point FORTRAN, each FPP
8-107 .
•

word occupies three storage locations. Therefore allocating storage
locations for 10 words reserves 30 locations of core. Array B' is
defined as a two dimensional array with storage for 24 FPP words
( 4x6); 72 locations are reserved. Array X is a 3 dimensional array
with 125 FPP wQrds, reserving 375 locations.
In certain cases involving subroutines, a dimension may be an
unsubscripted integer parameter.
Any number of arrays may be declared in a single DIMENSION
- statement. Each array variable appearing in the program must
represent an element of an array declared in a DIMENSION
statems.nt, unless the dimension infonnation is given in a COMMON or TYPE statement.
Dimension information may appear only once for a given variable. The DIMENSION statement must precede any reference to
the variable including reference in a DATA or EQUIVALENCE
statement. TYPE declaration or COMMON statements may appear
anywhere in a program unless they include dimension information.
A subprogram can establish adjustable arrays at execution time
if both the ~nay name and the subscript size are expressed as
dummy arguments in the subroutine, as in:
SU8ROUTINE "WHAT(A,X,y,Z)
" OIMENSION A(X,V,Z)
"tYIllet PSf~hl1Sh .l-\.,
A
)(
V.... !'Ind
T A rlA fhlC fhP prAOr~m"tYIpr
VOL
4,.",
_........ -7 !'IS
required arguments The dummy array must not exceed the dimensions of the main program array but may be smaller if the call provides lower subscript sizes than those of the main program dimensioning or if the initial array element referenced is not the beginning
of the main program array.
v

"-.&v

'-.&. ....... .."

.... J..l.......

.I.

'-4

..I..&..&..&. ..... .L

• L .... .L'-+U

"'_V.I. ....... .1.

COMMON Statement

Form

COMMON/block 1/ a,b,c/block2/ d,e,f/ ...

Where

blockl ,block2, ... , are the block n"ames.
a,b,c, d,e,f are the variables to be assigned to each
block.

Effect

Specified variables or arrays are stored III an area
available to other programs.
8-108

By means of COMMON statements, the data of a main program
and/ or the data of _its subprograms can share a common storage
area. The common area can be divided into separate blocks which are identified by block names that may not be the same as any program variable names. A block is specified as follows:
/block name/varl,var2, ...
-The variables which follow the block name indicate scalar or
array variables assigned to the block. They are placed in the block
in the order in which they appear in the block specification. For
example, the statement:
COMMON/~/X,Y,T/C/U,V,W,Z

indicates that the elements X, Y, and T are to be placed in block
R in th~t order, and that U, V, W, and Z are to be placed in block
(~ Variables whose -names appear in the formal parameter list must
not also appear in COMMON declarations within the subroutine.
A COMMON block may not have the same name as a variable in
the same program. Also, a COMMON block may not have thesame name as any subprogram which is used at the same time as .
. the COMMON block.
Block en~ries are linked sequentially throughout the program,
beginning with the first COMMON statement. For example, the
statements:
COMMON/D/ALPHA/K/A,8/C/S
CQMMON/C/X,Y/R/U,V,w

have the same effect as the statement:
CO~MON/D/ALPHA/R/A,~,U,V,w/C/S,X,y

_ One block of COMMON storage, referred to as blank COMMON, can be left unlabeled. Blank COMMON is indicated by two
consecutive slashes, for example
COMMON/W/X,YIIB,C,D

indicates that B, C, and D are placed in blank COMMON. The
8-109

slashes may be omitted when blank COMMON is the first block of
the statement, as in:
CO,.,MON 8,e,0

Storage allocation for blocks of the same name begins at the same
location for all programs executed together. For example, if a
program contains:
CO,.,MON

A,~/~/X,y,Z

lC.]

as its first COMMON statement, and a subprogram has

as its first COMMON statement, the quantities represented by X
and U are stored in the same locati9n, i.e., X and U both equal 3.
A similar corresp()ndence holds for A and D in blank COMMON.
COMMO~ blocks may be of any length, subject to the limitations on available memory.
Array names appearing in COMMON statements may have dimension information appended if the arrays have not been declared
via a DIMENSION statement or a type declaration. For example:

specifies the dimensions of the array T while entering T in blank
COMMON. If array dimensions are not defined in a COMMON
statement, they must be defined in some other type statement.
EQUIVALENCE Statement
Form

EQUIVALENCE(v1,v2, ... ,),(vk,vk+ 1, ... ), ..

Where

v1,v2, .. ,vk are the variable naines.

Effect

The variables within the parentheses identify the same
storage location.

Example:

8-110

specifies that the values of the variables RED and BLUE are stored
in the same location. If used at different times, multiple variables
with different values can occupy the same storage location or if used
at the same time, multiple variables can be assigned the same value
through the use of EQUIVALENCE.
The master variable in an equivalence group is either the variable
!n the group that is in COMMON (only one such variable per group
is legal) or the first variable in the group. All the other variables of
an equivalence group are considered slaves and can only appear in
one group. The master of an equivalence group should be large
enough to encompass all of the slaves equivalenced to it.
The subscripts of array variables in an EQUIVALENCE statement must be integer constants. Example:

The formal parameters of a subroutine must not appear in EQUIVALENcE statements within that subprogram.
The variables assigned by an EQUIVALENCE statement must
be within the same main program or within the same subprogram.

EQUIVALENCE and COMMON
Variables may appear in both COMMON and EQUIVALENCE
statements, but no two quantities in COMMON may be set equivalent to one another.
Quantities placed in a COMMON block by means of. EQUIVALENCE statements can cause the -end of the COMMON block
to be extended. For example, the statements:
C:OMMON/R/X,Y,Z
DIMENSION A(II)
EQUIVALt.NCECA,V)

cause.the COMMON block R to extend from X to A( 4), arranged
as follows:
X
Y

A(l)

A(2)
A(3)
A(4)

8-111

EQUIVALENCE statements which would require 'extension of
the start of a COMMON block are not allowed. For example, the
sequence:
COMMONlkIX,y,Z
OlMtNSION 1(4)
EQUrV.LfNCE(~,1(3l)

is not permitted, since it would require A(1) and A(2) to extend·
the starting location of block R.
Care must be exercised when using EQUNALENCE and
COMMON statements.
THE DATA STATEMENT
Form

DATA,var listl/vallistl/var list2/vallist21 ,...

Where

var .list contains· a string of variables separated by
commas
. IvaI list/ contains a string of data items separated
by commas

Effect

A value from val list is assigned to the corresponding
variable in var list.

The DATA statement is used to supply initial or constant values
for variables. The specified values are compiied inio the object
program, and become the values assumed by the ,variables when
program execution begins. Such values may also be provided via a
BLOCK DATA subprogram. Initial values for variables in COMMON may not be specified in' subprograms which may be overlaid
at execution time. (refer to Loader description). It is recommended
that variables in COMMON be initialized only by means of a
BLOCK DATA subprogram.
Variables in the variable list may be either single subscripted
or unsubscripted arrays, or the name of an entire array.
When an entire array is given, data 'values must be specified for
each and every element of the array. Data elements are stored in
the array in the same order as that used for the data transmission
and storage arrays, i.e., in order of increasing subscripts with the
first subscript varying most rapidly.
8-112

Allocation to memory locations in the array stops when:
a. the data item list is exhausted, or,
b. data items have been allocated to the entire array. liso,
additional data items will be allocated to succeeding variables
listed.
When Hollerith or literal constants are encountered in the values
list, they are assigned to the associated variables in the same manner as in assignment statements.
A Hollerith value in a data statement will occupy (n+5)/6
words of storage (36-bit FPP words) ~ with any partial words filled
to the. right with blanks.
,
The data items following each list of variables must have a
one-to-one correspondence with the variables of the list, since
each item of the data specifies the value given· to its corresponding
variable.
Data items assigned may be numeric, Hollerith, octal, or logical
constants. For example,

specifies the value 5 for ALPHA and the value .16 for BETA. Any
. item o-f data may be preceded by an unsigned non-zero integer
constant followed by ah asterisk. This notation indicates that the
item is to be repeated. For example,

. specifies the value zero for array elements A ( 1 ).;A (3). As another
example:
DIMENSION A(2,2),8(3)
DATA A,S/2*1.0,3*2.0.l.0,4~1

will initialize
A(1,1) and A(2,1) to 1
A(1,2),A(2,2) and B(l) to 2
B(2) to 3, and B(3) to 4
8-113

TYPE DECLARATION STATEMENTS
Form

type vl,v2,v3, ...

Where

type may be INTEGER, REAL, DOUBLE PRECISION, COMPLEX, LOGICAL
vI ,v2,v3, ... represent variables

Effect

11 v~:l1'·1~b1es
l·n the 11st ar assioned
thp 0....
olven.....type •
u.t..............L
..LO ....

A
.L~""

..L.I."""""'A

.L·

"'.... -

A variable can appear in only one type statement. Type declaration statements override any implicit type specifications determined
by the first letter of a variable. Type statements can be us~d to give
dimension specifications for arrays. Adjustable arrays in subprograms can also be defined via type statements. Each variable or
function name in a type statement is defined to be of that specific
type throughout the program; the type cannot change.
Examples:
INTEGER A~C,IJK,XYZ
REAL A(2,Q),t,J,K
OOUB~E PRECISION 8,X,OARG1,OARG2

Subprogram Statements
Using subprograms, a statement or group of statements can be
written once and then referenced whenever the implemented operation is to be executed. The use of subprograms saves programming
time and computer memory. There are three categories of subprograms in FORTRAN: FUNCTION subprograms, SUBROUTINE subprograms and BLOCK DATA subprograms. Functions
and subroutines consist of one or more FORTRAN statements
which may be invoked by name and, as appropriate, with values
upon which they are to operate. A function differs from a subroutine in that it is always called with at least one parameter, and
always returns at least one value as the value to be used for the
function reference in the expression in which it occurs. A subroutine
may be called with or without parameters and may return values
only through its parameters or via COMMON. BLOCK DATA
subprograms contain specification statements only and are used to
specify initial values for variables in COMMON.
8-114

The transmission of arguments between a subprogram reference
and the subprogram itself is accomplished by the use of dummy
variables within the subprogram definition. Those variables in the
subprogram which are dummy variables are listed in the subprogram definition statement. References to the subprogram may then
supply values for these arguments in the same order and be substituted for them whenever they appear in the subprQgram.
FUNCTIONS
An internal function is defined via a form of the arithmetic statement and may be referenced only by the progr~m in which it is
defined.
Form

name (argl, ... ) =expression

Where

name is the function name
argl, ... are dummy arguments. These variables will
be altered whenever the function is used and should
not be referenced elsewhere in the program.
expression is the function definition

Effect

Defines an internaffunction.

An arithmetic statement function definition is a single statement.
The expression which defines the function may include dummy
arguments, ordinary variables, external functions and previously
defined internal functions.
In the following definition:
ACOSH(X) = (EXP(X/A) + EXP(-X/A))/2.

X is dummy argument and A an ordinary variable. When the
function is referenced, the current value of A and the supplied
value of X will be used to evaluate it. All function definitions of
this type must precede the first executable statement of the program
in which they appear, and follow the last specification statement
appearing in the program.
FUNCTION Statements
An external function, one· which may be referenced by other
programs, is defined via the FUNCTION statement. A function
reference may only appear within an. expression and must, like
other elements of expressions, have a specified type. Type may be

8-115

specified in the definition itself or via any other FORTRAN type
specification facility.
Form

t FUNCTION name (argl, ... )

Where

t is an optional type specification (e.g. real)
name is the function name
argl, ... are dummy arguments

Effect

Defines an external function subprogram.

The function name must be a legal symbol which is assigned a
value within the subprogram definition. The last value assigned
to this name is the function's value. There must be at least one·
argument and arguments must agree in number, order, and type
with actual arguments given by the calling program. A maximum
of six dummy arguments may be given in a FUNCTION statement.
Example:
FUNCTION MOO

(XIGE~12,0)

GO TO 50

M_U'." .. 2.5
R~TURN

MI.S ..

~.0

RETURN

END

Dummy arguments may represent the following elements in the
function definition: expressions, alphanumeric strings, array names,
or elements and subprogram names. Dummy arguments which
represent array names must appear within the subprogram either in
a DIMENSION statement, or in one of the type statements that
provide dimension information. Dimensions given as constants
must not exceed the dimensions of the corresponding arrays in the
calling program. Dimensions given as dummy variables may be
used to specify adjustable dimensions for array name arguments.
For example, in the statement sequence:
FUNctION TABLE (A,M,N,B,X,V)
It

•
•
DIMENSION
.(M,N)~e(10),C(50) .
8-116

the dimensions of array A are specified by the dummy arguments M
and N, while the dimension of array B is given as a constant. The
various values given for M and N by calling the program must be
within the limits of the actual arrays which the dummy array A
represents. Various arrays may be substituted for A. These arrays
may each be of different size. Dummy dimensions may only be
given for dummy arrays. Note in the above example that the array
C, which is not a dummy argument, must be given absolute -dimensions. A dummy argument can not appear in an EQUIVALENCE
statement in the function s u b p r o g r a m . ,
A function may modify any arguments which appear in the
FORTRAN arithmetic expression calling the function. The only
FORTRAN statements not allowed in a function subprogr~m are
SUBROUTINE, BLOCK DATA, and another FUNCTION statement.
A function is called by placing the function name in the program.
Control then passes to the function subroutine. The quantity resulting from the function subroutine replaces the function name'in the
calling expression.
SUBROUTINE SUBPROGRAMS
A subroutine subprogram is defined external to the program which
references it. Subroutine definition is initiatea by SUBROUTINE
statement. A subroutine is referenced by a CALL statement and
returns ~ontrol to the calling program by means of one or more
RETURN statements.

SUBROUTINE Statement -

Form

SUBROUTINE name
or
SUBROUTINE name (argl, ... )

Where

name is a subroutine name
argl, ... are optional dummy arguments

Effect

The progr~m which follows is declared a subroutine
program.

The arguments in the parenthesized list are dummy arguments
representing the arguments of the subprogram. The dummy arguments must agree in number, order, and type with the actual
arguments used by the calling program. A subroutine subprogram
8-117

need not have any arguments at all; a maximum of six· dummy
array arguments are allowed. When supplied, they may be expressions, alphanumeric strings, array names, array elements, scalar
variables, and subprogram names.
Dummy variables which represent array names must be dimensioned within the subprogram by a DIMENSION or type declaration statement. As in the case of a function subprogram, either
constants or dummy identifiers may be used to specify dimensions
in a DIMENSION statement. The dummy arguments may not
appear in an EQUIVALENCE. or COMMON statement in the
subroutine program.
A subroutine or function subprogram may use one or more of its
dummy arguments to represent results. For example:
SUBROUTINE COMPUT (A,B,ANS)

might require the user to supply numeric values for A and B to be
computed, and a variable for ANS in which to store the results.
The only FORTRAN statements not allowed in a subroutine subprogram are FUNCTION, BLOCK DATA, and another SUBROUTINE statement.
Constants in call lists of subroutines and function subprograms
are not protected. Therefore, a function such as the following will
result iIi erroneous values.
FUNCTION FNCl tV)
FNC1·101D.¥:l
V.V+2ji0

RETURN
ENO

CALL Statement
Form

CALL name
or
CALL name (argl, ... )

Where

name identifies a subprogram
argl,. .. are actual arguments

Effect

Control is' transferred to the subroutine subprogram.

The arguments of a CALL statement can be expressions, array
names, array elements, scalar variables, alphanumeric strings, or
8-118

subprogram names; arguments may be of any type, but must agree
in number, order, type and array size (except for adjustable arrays,
as discussed under the DIMENSION statement) with the corresponding arguments in the SUBROUTINE statement of the called
subroutine. A subroutine cannot be referred to as a basic element
.
.
III an expressIOn.
RETURN STATEMENT
The RETURN statement consists of the text:
RC:TURN

This statement returns control from a subprogram (subroutine or
function) to the calling program. Normally, the last statement
executed in a -subprogram is a RETURN statement. Any number
of RETURN statements can appear in a subprogram.
BLOCK DATA STATEMENT
The BLOCK DATA statement is used to establish a block data
subprogram, a data specification subprogram which is used to enter
initial values for variables in common blocks. No 'executable statements can appear in a block data subprogram. A block data subprogram is established by a BLOCK DATA statement consisting
of the text:
BLOCK DATA

This statement declares the program which follows to be a data
specification subprogram and must be the first statement of the _
subprogram. For example:

BL.OCI< DATA
COMMON A,t~,C
COMMON/X/ARRAV(100)
INTEGER A,e
REAL 6
DATA

A,~,C/5,1.5,01

LOGICAL AR(AY/100*01
f.NO

8-119

This subprogram causes blank common to be initialized with the
integer 5, a real variable 1.5~ an integer 0 as its first three variables
and an array with 100 zeroes.
The subprogram 'contains only type statements, EQUIVALENcE, DATA, DIMENSION, and COMMON arguments. A
complete set of specifications must be given for an entire common
block. A single block data subprogram can initialize any number
of named COMMON blocks.
EXTERNAL STATEMENT
Form

EXTERNAL identifier,identifier,.... ,identifier

Where

identifier is the name of a subprogram

Effect

The identifier is declared a subprogram name and
may be used as the argument of other subprograms.

Function and subroutine subprogram names can be used as the
actual arguments of subprograms. When they are, their names must
be distinguished, from ordinary variables by their appearance in an
EXTERNAL statement.
Any subprogram name given as an argument to another subprogram must have previously appeared in an external declaration in
the calling program (i.e., as an identifier in an EXTERNAL).
Example:
£XTERNAL SIGMA,THETA

•
•

CALL TRIGF(SIGMA,1.5,AN8 WER)

•

•
CALL TRIGFCT~ETA,181,ANSWER)
•

•
END
SU8~OUTINE

TRIG'CFUNC,ARG,ANSWER)
•

•
ANswER.FUNCtA-RG)

·•

,
RETURN
END

8-120

Table 8-17

Statement

FORTRAN IV Statement Summary

Form

Effect

Arithmetic

a=b

The value of expression b is assigned to
the variable a.

Arithmetic
statement
function
definition

t name(a 1... )=x

The value of expression x is assigned to
f(a 1...) after parameter substitution.

ASSIGN

ASSIGN n TO v

Statement number n
is assigned as the
value of integer variable v for use in an
assigned GO TO
statement.

BACKSPACE

BACKSPACE u

Peripheral device u
is backspaced one·
record.

BLOCK DATA BLOCK DATA

Identifies a block
data subprogram'

CALL

CALL prog
CALL prog(al...)

Invokes subroutine
named' prog, supplying arguments when
required.

COMMON

COMMON/blockll a,b,c/ u.

Variables (a,b,c} are
assigned to a common block.

CONTINUE

No processing, target
for transfers.

DATA

DATA var listl/val listl/ ...

Assigns initial.. or
constant values to
variables.

DEFINE FILE DEFINE FILE
al(b 1,cl,l!,vl) ...

Describes a mass
storage file for direct access 110.

DIMENSION

Storage allocated according to dimensions specified for
the array.

DIMENSION array
(vl...,v7) ...

8-121

Table 8-17

FORTRAN IV Statement Summary (Cont.)

Statement

Form

Effect

DO n i = ml,m2,m3

Statements following
the DO up to statement n are iterated
for values of integer
variable i, starting at
i =ml, incrementing
• by m3, terminating
when i>m2.

END

Cease program compilation; equivalent
to STOP In main
program or RETURN in subprogram.

END FILE

. 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.R4<PTH:

Use OS/8 PIP to read the
RALF modules, in ascending numerical order, onto'
temporary files.

*DEV:FILE2.RA<PTR:
l'

*DEV:F'ILE3.RA<PTR:

• R RALF'
*DEV:F'ILE3.RL<DEV:'ILE3.R
.R RALF'
*DEV:FILE2.RL<DEV:F'ILE2.RA
.R RALF
*DEV:F'ILEl.RL<DEV:F'ILEloRA
8-125

Assemble the temporary files
under RALF .

·R LI9RA
*DEV:TEMPLB.RL<DEV:FORLIB.RL=13

Use LIBRA to create a temporary library containing 13
extra blocks for expansion .

*tC

• R PIP
*DEV:FORLIB.RL<ID

Use PIP to delete the old
library.

*tC

• R LIBRA
*DEV:FORLIB.RL[3]<DEV:TEMPLB.RL,DEV:FILEI.RL,DEV:FILE2.RL,DEV:FILE3.RL/R

NOTE
Ose LIBRA to merge the temporary library
and the new RALF modules. LIBRA will
print a list of duplicate module names on the
. console terminal. When all output has ended
and LIBRA prints an asterisk at the left
margin, type CTRL/C to return to the
monitor.
The following program example provides a simple test, to verify
that the OS/8 FORTRAN IV system is operating correctly. When
duplicating the illustrated procedure, use care to distinguish between user input and machine output. Type CTRL/L at the point
to return the editor to command mode. Type ALT
marked
MODE (ESCAPE on some terminals) at the point marked@to
generate the dollar sign character ($) .

•R EDI T
*EXAMPL<
IIA

100

200

.wRITE (4,100)
FORMAT (IH dTHIS IS A SIMPLE EXAMPLE ~F A PROGRAM")
X=2.5
Y:3.14
z=x*y
WRITE (4,200) X,Y,Z
FORMAT (I H "x=" F4.2," V:" F4.2," X*Y:"F4.2)
END

ill

100

2f1J0

IIIRI TE (4,100)
FORMAT (IH "THIS IS A SIMPLE EXAMPLE OF A PROGRAM")
X:2.5
Y:3. 14
z=x*y
WRITE (4,200) X,Y,Z
FORMAT (IH "X:"F4.2," Y:"F4.2," X*Y:"F4.2)
END

8-126

.R F4
*,TTY:,TTY:<EXAMPL/G
OS/8
FORTRAN 'IV 3.1212
131211212
1211211213
1211211214
1211211215
0121136
1211211217
12112110
12112111

1121121

2121121

- JUN

1973

PAGE

ONE

WRITE (4,10121)
FORMAT (IH "THIS IS A SIMPLE EXAMPLE OF A PROGRAM K )
X=2.5
Y=3.14
Z=X*Y
WRITE (4,20121) X,Y,Z
FORMAT (IH "X="F4.2," ~="F4.2,· X*Y="F4.2)
END

LOADER I.e 1 1216 11211 173
SYMBOL VALUE LVL OVLY
ARGERR 12112121214 121 121121
EXIT
121121223 121 121121
#MAIN 11210121121 121 121121
11341313 = 1ST FREE LOCATION
LVL OVLY LENGTH
121

13121

112127121

THIS IS A SIMPLE EXAMPLE OF A PROGRAM
X=2.513 Y=3.14 X*Y=7.85

FORTRAN IV PLOTTER ROUTINES.
The X,Y plotter routines control. an incremental plotter (Calcomp 563, 565 or similar) for use with OSj8 FORTRAN IV. The
routines permit the user to generate a wide variety of plotted
information, including:
1. Labelled axes,
2. Textual data,
3. Graphs from data arrays (X and Y), with optional scaling of
either array' and centered symbols denoting the location of a
data point, .
4. Variables from the FORTRAN IV program plotted in F
format,
.5. Individual point and vector plotting.
The user also has control of:
1. Pen position (up or down),
2 .. Origin of plotted information,
3. Scaling of any plot,
4. Rotation of text and axes.
8-127

The routines included are:
Table 8-18

FORTRAN IV Plotter Routines

Name

Function

PLOTS

Initializes aU other plotter routines to the user's hardware configuration.

XYPLOT

Moves pen to specified X,Y location with pen in up or
down position, permits origin control.

FACTOR

Scales size of subsequent plotting data.

WHERE

Passes current position and factor to the user program.

SYMBOL

Prints textual information (such as titles) at any angle
and special symbols to indicate a data point.

NUMBER

Prints each digit in a variable, including optional decimal point and truncation.

PSCALE

Defines parameters for axis annotation and size of final
piot for data array.

AXIS

Plots an axis, at any angle, including segment markings
and title.

LINE

Generates the graph of data in two arrays (X and Y).

PLEXIT

Terminates all plotting.

The system must support any OS/8 FORTRAN IV configuration plus: XY /8e interface for PDP-8/E, or XY interface for
8-128

PDP-12, 8, or 8/1 and an incremental plotter suitable for one of
the above interfaces.
The system must have OS/8 (QFS8-A) and OS/8 FORTRAN
IV (QF008-AB).

'Plotter Operation
To optimize the use of the X,Y plot routines, a brief description.
of the plotter operation is presented here. The plotter permits six
basic functions: drum down (+ X movement), drum up (-X
movement), pen left (+ Y movement), pen right (-Y movement),
pen up and pen down. Diagonal movement is accomplished by' a
combination of pen and drum motion. The plotting increment is a .
function of the plotter itself, generally .005 or .01 inches. Each
line plotted i5 in' this incremental unit. Hence upon very close
examination vectors plotted at angles other than multiples of 45
degrees may appear sightly non-linear. This effect is unnoticeable
at normal viewing distances from the plotter where all vectors
appear smooth. If the user requests· a vector that exceeds the
. physical width of the plotter, the pen will move to the physical
limit and plot the remaining section at the margin. This may distort
subsequent plotting, depending on the user's sequence of commands. Therefore, be sure the pen is either physically located in' a
useful position at the start of the plot or use the plotting commands
to monitor its position to prevent such problems.
Plotter Commands
PLOTS
The routine PLOTS must be called once at the start of each plotting program to initialize internal parameters to the current configuration. The call -is:
CALL PLOTS (X,Y)
where:
X

is the increment size of the plotter in inches; generally .01
or .005 inches.

is 0 if running on a PDP-8/E;
1 if running on a PDP-8/1, PDP-8, or PDP-12.

PLOTS initializes the factor· (for overall plot size) to one and
clears old pen location and origin status. Note that although the
8-129 .

plotter may actually move in inches, the code can cause it to
behave as if it were millimeters (or any other unit) by including
the proper conversion in the FORTRAN code.
XYPLOT
XYPLOT is the routine that actually causes pen and drum movements on the plotter. Routines such as NUMBER and AXIS
eventually use XYPLOT. This routine is useful when a plot is to
be generated one vector at a time by the user program (rather than
saving an array, for example). It also controls the origin, defined as
the logical point (0,0) for future plotting.
The call is of the form:
CALL XYPLOT (X,Y,I)
where:
X, Y

is the X, Y coordinate in inches to which the pen is to
move relative to the most recently established origin
point.

is an integer of the set (-3, - 2,2,3) which controls pen
position and establishes the origin point, as follows:
If 1= 2, the pen is down during the move.
If I. ::. . : 3, the pen is up during the move.
Tf I is negative, the pen moves to point X,Y and this

point is then established as the current origin point (0,0).
If a value outside this set is called, the pen defaults to
down.
For example:
CALL XYPLOT(4,-2,-2)
moves from the current position to 4,-2 with the pen down and
establishes this location as the origin point (0,0).
CALL XYPLOT(-7,3,3)

•

moves the pen in the up position to-7,3. If these two commands
are sequential, then this move would be- - 7 inches of X and + 3 of
Y, from 0,0 to-7,3.
8-130

No single vector can be plotted longer than 4095 plotting increments, or approximately 40.9 inches for a .01 increment .plotter or
20.4 for a .005 increment plotter.
FACTOR
Overall plot size can be increased or reduced by usmg the
F ACTOR routine. The call is:
CALL FACTOR(Z)
where:
.Z

is the ratio of the desired plot size to the current size. This
value is initialized by PLOTS to 1. Calling FACTOR with
Z= 1 resets the plot to its initial size. The absolute value of
Z is used. For example, to double the size of the plot, the
call is CALL FACTOR (2); to halve it, is CALL FACTOR (.5).

WHERE
The WHERE routine passes three values to the user program:
current X position, current Y position and current factor. This
routine is most commonly used to determine the current location
of the pen in a long plotting s~quence, or to calculate a delta X or
Y value for the next step in a graph.
The call is:
CALL WHERE (X,Y,Z)
where:
X

is set to the current X position

is set to the current Y position

is set to the current factor

Consider the following ~xample:

CALL PLOTSC.01,1)
CALL XVeLOT(0 l 0,-3)
CALLXYPLOTC-5,l,i)
CALL WHERECA,B,C)
Wf'(ITE(4,10)A,B
FORMATC1X,'XVALI',I3,'YVAL_',I3)
CALL PLE.lCIT

END

8-131

At the completed running of this program the statement XV AL=
-5YVAL= 3 will be printed on device 4.
SYMBOL
The SY11BOL routine has two forms:
1. Print any number of letters and symbols

2. Print a single character
The available character set for both forms is found in Tables
8-19 and 8-20.

Table 8-19

SYMBOL

CODE

SYMBOL

10 0

II
I!

I
I

'I
-'-

Special Symbols

SYMBOL

CODE
,

" (:,

- "

COD};,

-'-

, '1

-,
I

--;7

10 2
I

20 3

10 4

--r:-

13 '-'Q

L-

'..,/

1 :J

1 J.

-'-

--/-

"--./
' /!

,..---'\

'. i /

10 S

-7k

8-132

"J. -

7"--

"
J. "
~o
,~

---,

Table 8-20

Regular Characters

S:YMBOL

CODE

SYMBOL

CODE

SYMBOL

B
C
0

Z
I
r
L
I
- \
I
]

51
5'">c

':l

'-'

Ll,.

r=-

'--

G
H
I
J
K
L
M
N
0
P

--'- J.

CODE

43
44
45

'"1

c:
5
'-.J

45
47
Ll.8-

53
,- 4

r--1

~.,j

55
55

1-4

:If

8
9

"IT

R
S
T

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-! _ _

... "' ..... 1 ...........

.:IlVL~

M-dLllUt;

v dIU\; dl1U ~~dHl1t; HI~l C:111C:l1l,

U11;,

~_...l

,._ ...... 1= __ ! __ ........ ____ L

_ _ _ "' ..

i:t~

_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

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 ~lements of the data array are the same,
the message:
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 NUMBER.RL
/ Mount AXIS.RL
/ Mount PSCALE.RL
I Mount LINE.RL

./V
./Y
·/Y

*1'C

The above puts the files on device SYS.
8-143

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

Y( I).0

YCJ+l)·SALESCJ)
VCI+2),SAL.ES(J)
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.

00°09

00°0S

l00J;Xl

S~3NOIIIONOJ

Figure 8-7

00°0~

00°0E

00°02

00°0];

~I~,

Histogram Plotter Example

8-147

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

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

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

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

Switch Register
Setting

012 345
000 000
111 111
110 000
110 000
101 011
110 000
111 001
111 -- DOD
111 101
101 011
111 000
110 000
101 011
110 000
111 100
011 111
011 011
101 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

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'

Time Cu.sec.)1

2.6
2.6
2.6
2.6
2.6
2.6
1.2
Sequence

Group 1 Operate Microinstructions (1 cycle2 )
NOP
IAC
RAL

RTL

7000
7001
7004
7006

RAR
RTR
CML
CMA
CLL
CLA

7010
7012
7020
7040
7100
7200

No operation
Increment AC
,
Rotate AC and link left one
Rotate AC and link left two
Rotate AC and link right one
Rotate AC and link right two
Complemented link
Complement AC
Clear link
Clear AC

1 Times are representative of the PDP-8/E.

2 1 cycle is equal to 1.2 microseconds.,

C-l

-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<IN:TEST2

CALL EXI T
l'

NO END STATEMENT

• RUN IN EDI T
*IN:TEST2.FT<TESTl.FT
[ NY

N/: 0055

#$35
35

•L
FORMAT ('THE AVERATE IS' ,20.2/)

#.S
35

FORMAT ( • THE AVERAT\GE IS' ,20.2/)

#.L
35

FORMAT (' THE AVERAGE IS' F20.2/)

#/L
CALL EXIT.

IA
END

D-3

The user instructs the Editor to list the entire FORTRAN
program.
,

Note the use of implied DO loops in the READ and WRITE
statements . . .

K and device independent I/O. A file named ABCD.DA is
opened on the default device DSK and data is written into it.
When all the data is entered, the file is closed. Later, this file
is again. opened, and the data is read and used by the program.
L An S in column 1 of a FORTRAN line indicates that the line
contains SABR code.
M CALL EXIT is used to return control to the Keyboard Monitor after execution.
;If,
N After listing the program,_ the E command to the Editor closes
the file and returns control to the Keyboard Monitor.

·D-4

#L
C
C
C
C

THIS PROGRAM PRESENTS A FEW OF THE FEATURES
OF OS/8 FORTRAN; SPECIFICALLY IT INCLUDES IMPLIED DO LOOPS, DIRECT INSERTION OF SABR .CODE
AND EXPANDED I/O.

C
C

. THI S SECTION READS DATA FROM THE TTY AND WRITES
IT ONTO THE DSK AS AN ARRAY.

K{5
10

c
C
C

K{20

J(
25
30

35
C

C
C
C

40
SX,
S
S
S
. S
S

SMYES,
50
60

{

DIMEN SION A( 10)
CALL OOPEN ('DSK','ABCD')
WRITE (1 .. 10)
FORMAT ('ENTER 10 NUMBERS IN F6.2 FORMAT~')
WRI TE (1 .. 11 )
FORMAT ('FOLLOW EACH WITH A CARRIAGE RETURN:'//)
READ (1; 15) CACN), N=.1, 10)
WRITE (4 .. 15) (ACN) .. N=1,10)
·FORMAT (F6.2)
CALL OCLOSE
THIS SECTION ADDS THE NUMBERS STORED ON THE DSK
A"JD AVERAGES THEM, PRINTING BOTH RESULTS ON
THE TELETYPE.
SUM=0.0
DO 20 1=1 .. 10
ACI)=0.0
CALL IOPEN ('DSK' .. 'ABCD')
READ (4 .. 15). (ACN) .. N=1 .. 10)
. DO 25 N=l, 10
SUM= SUM+ACN)
CONTINUE ..
WRITE (1 .. 30) SUM
FORMAT C/' THE SUM IS' F20.2)
AVR=.5UM/10.
WRITE (1, 35)AVR
FORM"AT ('THE AVERAGE IS' F20.2/)
THE SABR CODE FOLLOWING CHECKS FOR A CARRIAGE
RETURN CHARACTER TO INITIATE REPEATING THE
PROGRAM.
ANY OTHER CHARACTER TERMINATES THE
PROGRAM.
WRITE <1,40)
FORMAT ('TO REPEAT .. TYPE A CARRIAGE RETUH\J. 'II)
KSF
JMPX

KRB
TAD MYES
SZA
..1MP \50
GO TO ~
-215
.
WRITE (1 .. 60)
FORMAT C/'PROGRllM DONE'II)
CALL EXIT
END

N{ IE
D-5

o The ASSIGN command is used to change the assigned name
of DTA1 from IN to OUT. The FORTRAN compiler is called
again, and the program is loaded. An output relocatable binary
file named TEST2 is saved by SABR on DECtape Unit l.
P

The FORTRAN program is executed via the CCL command
EXECUTE. The /G, /1, and /0 options cause automatic
. loading and execution of the program and the device independent I/O, and results are calculated and returned. Execution
is not repeated.

Q The DEASSIGN command is used to delete all user-assigned
ASSIGN command is then used to give the
device names. The
•
name X to DTA1.
. R The tCL command DIR is used to obtain a directory listing
of DECtape Unit 1. TEST2.RL is the relocatable binary output file from the FORTRAN compilation.
S

Next, the CCL command DIR is used to print the directory of
. the system device on the line printer. ABCD.DA is the FORTRAN data file created in the preceding program.

T The CCL command DEL is used to delete the unwanted files
PROG3 and PROG4, from the system device. Then the ASCII
file TEST2 is copied from DECtape Unit 1 to the system device
with the ceL command COPY.

D-6

• AS DTAt OUT .
.O ( • C<MPI L E OUT: 1 EST2< OUT: TEST2
• EX ECUTE OUT: TEST2/G /1 /0
ENTEfi 10 NUMBERS IN F6.2FORMAT.
FQ..LOW EACH WI ~H A CARRI AGE RETURN:

16.2.3
32.00

171.45
2. 15

22. 10
77.35
2.9 t
66.00
.46
27.50
THE SUM IS
THE AVERAGE IS
TO REPEATI

418. 15
41.81

TYPE ,A CARRIAGE RETURN.

PROGRAM DCNE

.DEA

Q { • AS DTAI X
• DI R X:
1121- A:P R- 74

EDIT
.S\I
TEST2 .FT
TEST2 • RL

12 1121- APR-7 4
4 1121-APR-74
4 1 121- AP R- 7 4

710 FREE BLOCKS

D-7

'. Di R L P T; < SY S;

H')-APR .. 74

•

5 15-JAN-74
ABSlDR.SV
.sv 17 26-FES .. 74
eel
7 1S-JAN ... 74
DIRECT.SV
8 IS""JAN.74
FOTP .SV
PIP
.SV 11 la.JAN-74
LIsa .Rl 29 la""JAN-74
EDIT- .5\1 10 1S-JAN.74
PALS .SY 1& 18-JAN .. 74
CREF .SV 13 18-JAN .. 14
BITMAP.SY
5 lS-JAN·74
FORT .SV 25 16 .. JAN .. 74
SABR .SV 24 lS .. JAN.74
LOADER,SV 12 lS.JAN.74
5 18-JAN.74
SRCCOM .. SV
5 18-JAN.74
BOOT .Sv
BUILD .SY 33 l8.JAN.74
EPIC .BY 14 lS-JAN-?4
PIP10 .SY 17 18-JAN-74
RESORC.SV 10 18.JAN .. 74
OTFRMT.SY
'7 lS-JAN",,74
9 18 .. JAN-74
TOFRMT.SV
9 l8·JAN .. 74
Rf(8FMT.SY
& 18-JAN·74
RKEFMT.SV
8 18-JAN.74
CAMP .SV
MCPIP .SV 13 l8 .. JAN-74
OTCOPY.Sv
5 l8-JAN.74
TOCOPY.Sv
7 lS.JAN.74
5 is·JAN.14
LIBSET.SV
eei. .PA 130 2&.FEB-14
4 l1-APR.74
TESTl .8K
4
TEST1 .RL
4 10-APR .. 14
TEST1 .FT
4 10-APR·14
TEST2 .RL
1 10.APR-14
ABCD .OA
PROG3 •
1 10-APR.14
PROG4 •
1 10-APR.74

2295 FREE BLOCKS

• DEL PROG3, PROG4
FI L ES DEL E1'ED:
PRQG3.
PROG4 •

• COPY SYS:TEST2.FT<X:TEST2.FT

D-8

e
osja

error message
summary
.The following summary is provided for the user's convenience.
Error messages generated by OSj8 programs are listed in alphabetic order and identified by the system program ,by which they
are generated. This appendix is only a summary. Refer to the
appropriate chapters for more detailed information about error
conditions.
Message

Program

Explanation

SRCCOM

Insufficient core-this means
that the differences between
the files are too large to allow for effective comparison.
Use of the /X option may
alleviate this problem.

Editor

Editor failed in reading a device. Error occurred in device
handler; most likely a hardware malfunction.

0000

Linking
Loader

/1 or /0 specified too late.

0001

Linking
Loader

Symbol table overflow; more
than 64 subprogram names.

0002

Linking
Loader

Program will not fit into core.

0003

Linking
Loader

Program with largest common storage area was not
loaded first.

0004

Linking
Loader

Checksum error in input tape.

0005

Linking
Loader

Illegal relocation code.

E-l

Message

Program

Explanation

0006

Linking
Loader

An output error has occurred.

0007

Linking
Loader

An input error has occurred
(either a physical device error, or an. attempt was made
to read from a write-only device such as LPT:).

0010

Linking
Loader

No starting address has been
specified and there is no entry point named MAIN.

0011

Linking
Loader

An error occurred while the
Loader was attempting to
load a device handler.

0012

Linking
Loader

110 error on system device.

SRCCOM

Input error on file # 1 or less
than 2 input files specified.

Editor

Editor failed in writing onto
a device. Generally a hardware malfunction or WRITELOCKed device.

TECO

Illegal command.

SRCCOM

Input error on file # 2.

Editor

File close error occurred. The
output file could not be
closed; the file does not exist
on that device.

TECO

Incomplete command.
TECO in Chapter 2.)

2045 REFS

CREF

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

SRCCOM

Output file too large for output device.

Editor

File open error occurred.
This error occurs if the output device is a read-only device or if no output file
name is specified on a fileoriented output device.

E-2

(See

Message

Program

TECO

Non-alphanumeric
name.

SRCCOM

Output error.

Editor

Device handler error occurred. The Editor could not
load the device handler for
the specified device. This error should never occur.

TECO

Command iterations or macro calls nested too deeply.

SRCCOM

Could not create output file.

TECO

Text buffer overflow.

TECO

Search string longer than 31
characters.

TECO

Numeric argument missing
before comma, equal sign, U,
or quote (").

TECO

IIIegal filename in ER. EW,
or EB command.

TECO

Semicolon or failing search
encountered on command
level.

TECO

Iteration close (» without
matching open «).

TECO

Attempt to move pointer out- .
side of text buffer.

TECO

Q-register storage overflow.

TECO

Incomplete command.

TECO

Output file too large, or else
output parity error.

TECO

Input file parity error.

TECO

File error. (See Chapter 2.)

TECO

An output command was encountered which would have
caused TECO to overflow its
current output file. Users
should close the current output file and write all further

E-3

Explanation
Q-register

Message

Program

Explanation
output onto one (or more)
additional files. These files
may be combined if necessary.

TECO

Attempt to execute an output command without opening an output -fiie.

SABR

Too many or too few ARG
statements follow a CALL
statement.

More than six subroutine ar-_
guments are arrays.

ALOG

FORT
Library

Attempt to compute log of
negative number.

ALREADY EXISTS
(filename)

FOTP

An attempt. was made to .rename an output file with the
name of an existing output
file.

ARE YOU SURE?

PIP

Occurs when using the / S
option. A response of Y wiJI
compress the files.

ARITHMETIC
EXPRESSION TOO
COMPLEX

FORT

Self-explanatory.

Bad ASSIGN statement.

?BAD ARG

BUILD

No device name was included
in the LOAD command.

BAD ARG

FRTS

Illegal argument to library
function.

BAD ARGS

Keyboard
Monitor

The arguments to the SAVE
command are not consistent
and violate restrictions.

BAD-BLK

EPIC

When EPIC is punching a
patch it -checks the block specified by :=n to see if it is
within range. If the block is
out of range EPIC outputs
this error message an:! returns to the command decoder.

E-4

Message

Program

- Explanation

BAD CHECKSUM,
FILE #n

ABSLDR

File number n of the input
file list has a checksum error.

BAD CHECKSUM,
FILE #n

BITMAP

File number n of the input
file list had a checksum error.

BAD CORE IMAGE

Keyboard
Monitor

The file requested was not a
core image: file.

BAD DATE

Key-board
Monitor

The d,ate has not been en,.
tered correctly, or incorrect
arguments were used, or the
date was out of range. ,

BAD DEVICE

eCL

-The device specified In a
CCL command is not of the
correct form.

?BAD DIRECTORY

RESORC

Input _device directory cannot
be read.

BAD DIRECTORY ON
DEVICE #n

PIP

Error message occurs when:
1. PIP is trying to read the
directory, but it is not an
OS/8 directory.
2. The output device does
not have a system. directory; i.e., file storage begins at record 7 (occurs
during a /Y transfer).
n is the number of the file in
the input file list.

BAD EXTENSION

CCL

Either an extension was specified without a file name or
two extensions were specified.

BAD FORMAT OR
CHECKSUMTRY AGAIN

LIBSET

Error iI}. reading relocatable
binary file.

?BAD INPUT

BUILD

An error was detected in the,
binary file; 'it is not a proper
input - for the LOAD command.

BAD INPUT DIRECTORY

DIRECT
FOTP

The directory on the specified
input device is not a valid
OS/8 directory.

BAD INPUT FILE

Loader

An input file was not a RALF
module.

E-5

Program

Explanation

BAD INPUT, FILE #n

- ABSLDR

Attempt was made to load a
non-binary file as file number
n of the input file list; or a
non-core image with /1 option.

BAD INPUT, FILE #n

BITMAP

A physical end' of file was
logical end
reached before
of file, or extraneous characters were found in binary file

Message

#BAD LINE. JOB
ABORTED

BATCH

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.

?BAD LOAD

BUILD

An attempt was made tQ load
a binary handler that is not
in the correct format.

?BAD MONITOR

RESORC

The input device may be a
system device but the Monitor cannot be accessed.
The version of the Keyboard
Monitor being used is not
compatible with CCL. A
newer version of the monitor
must be obtained from Digital before CCL can be used.

BAD MONITOR

BAD NUMBER

eeL

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

?BAD ORIGIN

BUILD

The origin in a binary file is
not in the range 200-577.

BAD OUTPUT DEVICE

FOTP

This message usually appears
when a non-file structured de·
vice is specified as the output
device.

E-6

Message

Program

Explanation

BAD OUTPUT DEVICE

Loader

The loader image file device
was not a directory device, or
the symbol map file device
was a read-only device. The
entire line is ignored.

BAD OUTPUT
DIRECTORY

FOTP

The directory on the specified
output device is not a valid '
OS/8 device directory.

BAD RECOLLECTION

CCL

An 'attempt was made to us~_
a previously remembered ar-·
gument when no argument,
was saved.

BAD SWITCH OPTION

CCL

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

BAD SYSTEM HEAD

PIP

'If the /Y option is used and

the area being transferred does not contain OS/8, this message results.
BATCH.SV NOT FOUND
ON SYS:

BATCH

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

Bad dimensions (too big, or
syntax) in DIMENSION,
COMMON or TYPE declaration.

FLAP
RALF

Illegal equate. The symbol
had been defined previously.

PAL8

Two -PAL8 internal tables
have overlapped. Fatal error
-assembly cannot continue.

FLAP
RALF

Illegal index' register specification.

FRTS

No more file buffer available.

Illegal in BLOCK DATA program.

FLAP
RALF

Bad expression. Something in
the expression is incorrect, or
the expression is not valid in
this context. ,

B-7

Message

Program

Explanation

SABR

An illegal character appears
on the line.

CANNOT CHANGE CORE
CAPACITY- WHILE
RUNNING BATCH

CCL

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

CANNOT HANDLE VARIABLE LENGTH.
RECORDS

MCPIP

The records on the input and
output files specified are not
the same size.

% CANT-AT BOF

CAMP

A file mark was read before
the specified number of records were read over in a
BACKSPACE command. The
device is moved forward so
that it is positioned at the
beginning of the file.

? CAN'T-AT BOT

CAMP

A BACKSP ACE command
cannot move the device backward the specified number of
files because the device is positioned at the beginning of
the first file.

% CANT-AT EOD

CAMP

The specified number of files
cannot be advanced over because the end of data was encQuntered, The tape is positioned at the end of data.

% CAN'T-AT EOF

CAMP

A file mark was read before
the specified number of records were advanced over in a
SKIP command. The tape is
moved backward one record
to leave it positioned at the
end of the file.

? CAN'T-DEVICE
DOESN'T EXIST

CAMP

The device specified in a
CAMP command is not present on the OS/8 system.

? CANT-DEVICE IS
READ-ONLY

CAMP

The device specified in a
CAMP command is a readonly device; e.g., PTR.

? CAN'T-DEVICE IS
WRITE-ONLY

CAMP

The device specified in a
CAMP command is a writeonly device; e.g., TTY.

E-8

Message

Program

Explanation

? CAN'T FOR THIS
DEVICE

CAMP

The operation specified does
not make sense for the device
·specified.

? CAN'T I/O ERROR

CAMP

This message is followed by a
brief explanation of the input!
output error that occurred.

CAN'T OPEN OUTPUT
FILE

PIP

Message occurs due to one of
the following:
1. Output file is on a readonly device.
2. No name has been specified for the output file.
3. A /Y transfer has been attempted to a non-directory
device.
4. Output file has zero free
blocks.

CAN'T READ IT

FRTS

I/ 0 error on reading loader
image file.

%CAN'T REMEMBER

CCL

The argument specified in a
CCL commaQd line IS too
long to be remembered or an
I/O error occurred.

CAUTION- DO DP

FRTS

The present hardware configuration does not include an
FPP-12 Floating-Point Processor with double precision
option.

CCL #x OVERLAY &
MONITOR INCOMPATIBLE

CCL

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

BCOMP

Error in CHAIN statement.

PAL8

Chain to CREF errorCREF-SV was not found on
SYS:.

CHER

FORT
Library

File specified as argument to
CHAIN not found on system
device.

BRTS

Inquire failure in CHAIN,
Device not found.

E-9

Message

Program

Explanation

BRTS

Lookup failure in CHAIN.
Filename not found.

Bad COMPLEX literal.

CLOSE ERROR

MCPIP

M CPIP is not able to close
the file. A bad file just created on magnetic tape or cassette must be removed by
placing a sentinel file after
the preceding file.

CLOSE FAILED

CREF

CLOSE on output file failed.

Syntax error
statement.

COMMAND LINE OVERFLOW

eeL

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

COMMAND TOO LONG

eCL

The length of a text argument
in a MUNG command is too
long.

COMPLIER MALFUNCTION

FORT

The meaning of this message
has been extended to cover
various unlikely Monitor errors.

CONTRADICTORY
SWITCHES

eCl

Either two CCL processor
switches were specified in the
same command line or the
file extension and the processor switch do not agree.

?CORE

BUILD

A CORE command specified
more memory than is physically available, or the BOOT
command was issued on an
8K system with a 2-page system handler active. Two page
system handlers require at
least 12K of core to be present on the OS/8 system.

SABR

A device handler has returned
a fatal condition.

BRTS

Attempt to read past end of
data list.

E-10

III

COMMON

Message

Program

Bad syntax in _DATA statement.

BCQMP

Error in DEF statement.

BRTS

Device driver error. Caused
by hardware I/O failure.

This type of statement iliegal
as end of DO loop.

PAL8

Device error. An error was
detected when trying to read
or write a device. Fatal error-assembly cannot continue.

DELETES PERFORMED
ONLY ON INPUT
DEVICE GROUP 1
CAN'T HANDLE MULTIPLE DEVICE
DELETES

FOTP

More than one input device
was specified with the /D option when no output specification (device or filename) was
included.

?DEV IS NOT FILE
STRUCTURED

RESORC

The input device specified is
not a file-structured device;
e.g., PTR.

DEV LPT BAD

CREF

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

DEV NOT ·IMPLEMENTED

BATCH

BATCH cannot accept input
from the specified input device because its handler .is
not
permanently
resident
(SYS: or co-residenf with
SYS: ). Control returns to the
Command Decoder.

DEVICE DOES NOT
HAVE A DIRECTORY

DIRECT

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

DEVICE FULL

PIP 10

DECsystem-lO ran out of
space on the output file during a transfer.

DEVICE #n NOT A
DIRECTORY DEVICE

PIP

Message occurs when:
1. Trying -to list the directory
of a non-directory device.

E-11

Explanation

Message

Program

Explanation
2. The input designated in a
IY transfer is not on a di..:
rectory device.
n gives the number of the device in the input list.

PAL8

Device full. Fatal error-assembly cannot continue.

Bad DEFINE FILE statement.

D.F. TOO BIG

FRTS

Product of number of records
times number of blocks per
record exceeds number of
blocks in file.

Hollerith field error in DATA
statement.

BCOMP

Error in DIM statement syntax or string dimension greater
than 72, or array dimensioned
twice.

DIRECTORY ERROR

PIP

An error has occurred while
reading or writing the directory during a IS option.

DIVIDE BY 0

FRTS

Attempt to divide by zero.
The i't:::sulting quotient is set
to zero. and execution continues.

DIVZ

FORT
Library

Division . by zero; very large
nUInber is returned.

Data list and variable list are
not same length.

DO-end missing or incorrectly
nested. This message is not
printed during pass 3. It is
followed by the statement
number of the erroneous statement rather than the ISN:

BRTS

No more room for drivers.
Too many different devices
used in file commands.

Syntax error in DO or implied DO.

E-12

Message

Program

Explanation

name DOES NOT EXIST

CCL
Command
Decoder
MCPIP

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

DO loop p;:rrameter not integeror real.

?DSK

BUILD

The device specified in a DSK
command is not a file-structured device.

BRTS

- Attempt to divide by O. Result. is set to zero (NF).

FLAP
RALF

An attempt was made in an
expression evaluation to divide by zero .

SABR

.There .is no END statement.

BRTS

Logical end of file. Usually
caused when I/O device runs
out of medium.

FLAP
RALF

The preceding line contains
extra code which could not
be used by the assembler.

BRTS

Attempt to exponentiate a
negative number to a power.

BRTS

Enter error in opening file.
Device is read only or there
is already one variable file
open on that device or file
not found.

END OF TAPE

EPIC

EPIC was expecting a block
of tape and found end of tape
instead. Press CONT to retry.

END OF TAPE ENTER
NEXT

EPIC

When EPIC is reading a file
that· is segmented across a
number of paper tapes and
encounters the end of a segment, it outputs this message
and halts with AC=7777 to
allow the user to enter the
next segment of papertape.
Press CaNT to continue reading.

•

Message

Program

Explanation

ENTER ERROR

MCPIP

Error occurred while trying
to enter an output file. This
message usually means that
the cassette or magnetic tape
has no sentinel file.

. ENTER FAILED

CREF

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

EOF ERROR

FRTS

End of file encountered on
input.

EQUALS OPTION BAD

DIRECT

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

ERROR CLOSING FILE

DIRECT

System error.

ERROR DELETING FILE

PIP
PIPIO

An attempt was made to delete a file that does not exist.

ERROR IN COMMAND

eCL

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

ERROR ON INPUT DEVICE SKIPPING
(filename)

FOTP

The file specified is not transferred, but any previous or
subsequent files are', transferred and indicated in the
new directory.

. ERROR ON OUTPUT
DEVICE

BITMAP

Error occurred while writing
on output device; i.e., output
error on DEC tape write.

ERROR ON OUTPUT
DEVICE SKIPPING
(fiilename)

FOTP

The file specified is not transferred, but any previous or
subsequent files are transferred and indicated in the
new directory.

ERROR READING INPUT DIRECTORY

DIRECT
FOTP

An error occurred while reading the directory.

ERROR WHILE WRITING OUTPUT FILE

LIBSET

Fatal output error occurred.

ERROR WRITING FILE

DIRECT

An error occurred while writing the output file.

E-14

Message

. Program

Explanation

ERROR WRITING OUTPUT DIRECTORY

FOTP

Self-explanatory .

RALF

External symbol error.

Syntax error in EXTERNAL
statement.

EXCESSIVE SUBSCRIPTS

FORT

Self-explanatory .

FORT
Library

Argument to EXP too large;
very large number is returned.

BRTS

FILE busy. Attempt to use a
file already in use.

BRTS

OS/8 error while closing variable file. Device is read-only
on file already closed.

BRTS

Fetch error in opening file.
Device not found, or device
handler too big for avaihible
space.

FETCH ERROR

MCPIP

Error occurred while trying
to fetch an OS/8 device handler.

BRTS

Attempt to· close or use unopened file.

FILE ERROR

FRTS

Any of:
a. A file specified as an existing file was not found.
b. A file specified as a nonexistent file would not fit
on the designated device.
c. More than 1 nonexistent
file was specified on a single
device.
d. File specification contained
"*" as name or extension.

FILE NOT FOUND

PIPIO

The requested file was not
found on the specified device.

FILE OVERFLOW

FRTS

Attempt to write outside file
boundaries.

FIX

FORT
Library

Attempt to fix a number
> 2047; 2047 is returned.

E-15

Message

Program

Explanation

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

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

Explanation

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

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

INPUT ERROR, FILE # n

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.

Explanation

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

Explanation

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

.
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

Explanation

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.

. LIBRARY DIRECTORY
OVERFLOW

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

L/r ERROR

E-22

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

Explanation

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

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.

NO MAIN

LOADER

No RALF module contained
section # MAIN.

··NO NUMERIC SWITCH

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 1:'TT -C
~l'lr U.L .L u .... .LJ

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.

PARENS TOO DEEP

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

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

Explanation

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

READ/

Message

Program

Explanation

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

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

#SPOOL TO FILE
BTCHA1

BATCH

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

E-31

statement

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 In
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'

A_,A

.;:n...."'vuu. .Pu.~I,)I, """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<!t!:lnt<!
____ ..............._& ..... v,

BASIC string, 6-46
FORTRAN II, 7-8, 7-9, 7-53
FORTRAN IV, 8-67
SABR,4-7
Continuation lines, FORTRAN IV,
8-67
CONTINUE statement,
FORTRAN II, 7-32 .
FORTRAN IV, 8-86
Control characters, FORTRAN II,
7-21, 7-26
Control statements, BASIC, 6-25
FORTRAN II, 7-29
FORTRAN IV, 8-80
Conversion,
BASIC string, 6-51, 6-52
FORTRAN H Hollerith, 7-26
SABR numeric, 4-8, 4-17
COPY command, CCL, 1-60
CORE command, CCL, 1-61

Index-4

Core image files, 1-37
BASIC, 6-66
Core layout, BASIC, 6-71
Corrections, keyboard monitor, 1-34
COS function, .
FORTRAN II,7-41
FORTRAN IV, 8-54
Cosine function, BASIC, 6-39
CPAGE pseudo-op, SABR, 4-18
CREATE command, CCL, 1-62
CREF (binary tape) load, 1-22
CREF command, CCL, 1-62
Cross-Reference Program (CREF),
2-69
error messages, 2-76
options, 2-69
output, 2-72
pseudo-op handling, 2-71 .
restrictions, 2-73
CTRL/C
BATCH,2-6
FOTP, 2-103
TECO, 2-141
CTRL keys, keyboard monitor, 1-34
CTRL/P (FOTP), 2-103
CTRL/TAB, FORTRAN II, 7-14
CTRL/U, 6-55
Current location counter, PAL8, 3-5,
.
3-10, 3-19
Current location, ODT, 1-'121

D
DA T$ function, BASIC, 6-54
Data,
blocks, FORTRAN II, 7-44
files, FORTRAN II, 7-7
formats, BASIC, 6-73
generation, SABR, 4-22
reference instructions, FLAP/
RALF, 5-7, 5-14
specification, FLAP, 5-16
statement, BASIC, 6-22
statement, FORTRAN II, 7-17
statement, FORTRAN IV, 8-112
transfer-see Peripheral Interchange Program
transmission specification, FORTRAN II, 7-21
transmission statement,· FORTRAN IV, 8-88
word, SABR, 4-7, 4-49
DATE command,
CCL,I-62
keyboard monitor, 1-42
Dates, file creation, 1-105
D (decimal) conversion, SABR, 4-8
DEASSIGN command,
CCL, 1-63
keyboard monitor, 1-36

Debugging function, BASIC, 6-42
Decimal format, BASIC, 6-6
DECIM pseudo-op, SABR, 4-7, 4-17
DECsystem-l0 file compatibility,
. 2-116
DECsystem-l0 file names, 2-117
DECsystem-l0 TECO versus 05/8
TECO, 2-178
DECtape bootstrap, 1-3
TCOl/TC08, 1-3
TD8E,I-4
.
DECtape file for BATCH input, 2-1
DECtape format, SABR, 4-48
DECtape I/O routines,
FORTRAN II, 7-44
SABR,4-48
DECtape systems, BUILD, 2-35
DECtape systems software, 1-1
DEFINE FILE statement, FORTRAN IV, 8-100
Definition of symbols, SABR, 4-20
DEF statement, BASIC, 6-39
Delay function, LAB8/E, 6-128
DELETE command, CCL, 1-63
Deleting TECO commands, 2-166
Deletion commands, TECO, 2-149
Deletion of characters,
BASIC, 6-2, 6-55
keyboard monitor, 1-33, 1-34
Delimiters, PAL8 conditional, 3-21
Demonstration program,
BATCH, 2-15
OS/8, D-l
.
Descriptor block, BUILD, 2-57
Device codes for paper tape, EPIC,
2-87
Device Control Block (DCB) word,
BUILD,2-59
Device control statements, FORTRAN IV, 8-106
Device designations, FORTRAN II,
7-17,7-20
Device driver storage, BASIC, 6-96
Device entry points, 2-60
Device handler assignment, FORTRAN IV, 8-33
Device handler format, BUILD, 257
Device handlers, OS/8, 2-34, 2-38,
8-36, G-l
cassette, 2-36
DECtape, 2-35
LINCtape, 2-35
papertape, 2-37
Device handlers, RESORC, 2-121,
.
2-125
Device handlers, OS/8 USR (SABR),
4-60
Devi~e independent I/O and chainmg,

Index-5

FORTRAN II, 7-42
SABR,4-47
Device mnemonics, BOOT, 2-33

nD'(7fl"~
.A..J'""'" ......... _ n'!lmPQ
.L..L_........A_.."

assignment of, 1-35
deassignment of, 1-36
for cassettes, 2-110, 2-113
keyboard monitor, 1-30, 1-31
DEViCE pseudo-ops, OS/8, 3-32
Device specifications, FORTRAN
IV,8-33
Device types, RESORC, 2-123
DF32 disks, 1-26
Diagnostics, BASIC,
compile time, 6-115, 6-116
run-time, 6-116, 6-117, 6-118
Dimensioning strings, BASIC, 6-46
DIMENSION statement,
FORTRAN II, 7-11,-7-34, 7-36
FORTRAN IV, 8-107
DIM statement, BASIC, 6-31
Direct assignment statements, PAL8,
3-12
DIRECT binary tape load, 1-24
DIRECT command, CCL, 1-64
Direction of program flow, SABR,
4-24
DIRECT utility program, 2-77
error messages, 2-81, 2-82
examples, 2-79
options, 2-78
wild card construction, 2-77
Disk as system device, 1-25
Disk file for BATCH input, 2-1
Display function, LAB8/E, 6-129
Distribution,
OS/8, 1-1
OS/8 BASIC, 6-119
D~,-:,.SABR, 4-43
T"\"'Iu""'I"n
...., ... VIl3.LV.L1,

BASIC, 6-8
PAL8,3-15
DK8-ES real-time clock, 6-124
DO loops, implied, FORTRAN II,
7-18
DO statement,
FORTRAN II, 7-30, 7-31
FORTRAN IV, 8-83
Dollar sign ($),
ALTMODE echo, 1-21
BATCH usage, 2-4, 2-5
BUILD response, 1-12
PAL8 usage, 3-21
DOT (.) character,
monitor response, 1-3
PAL8,3-19
Double precision constants, FORTRAN IV, 8-69
Double quote (") character,
PAL8,3-19

SABR,4-7
DR8-EA,6-124
DTORGpseudo-op, PAL8, 3-32
Dummv anmments,
FORTRAN II, 7-36
FORTRAN IV, 8-116
DUMMY pseudo-op, SABR, 4-29
Dummy statement, FORTRAN II,
'7
'2"
1--,..,

Dummy variables, SABR, 4-12
DUM SUB Linkage routine, SABR,
4-36
E
EAP pseudo:op, SABR, 4-17
EDIT commands, CCL, 1-64
EDIT editing program, 8-1
EDIT (Editor binary tape) load, 122
Editing characters, BUILD, 2-39
Editing commands, EPIC, 2-88
Editor bypass, BASIC, 6-121
Edit, Punch and Compare (EPIC)
utility program-see EPIC
EJECT pseudo-op, P AL8, 3-31
END FILE statement, FORTRAN
IV, 8-107
End of file, PAL8, 3-29
End-of-tape punch, EPIC, 2-86
END pseudo-op, SABR, 4-16
END statement,
BASIC, 6-14
FORTRAN II, 7-33, 7-36
FORTRAN IV, 8-88
Entry point offset, BUILD, 2-60
Entry point, SABR, 4-27
ENTRY statement, SABR, 4-27
EO~ command, CCL, 1-65
EPIC (binary tape) load, 1-23
EPIC (Edit, Punch and Compare)
utility program, 2-83
assembly instructions, 2-95
command format, 2-84
compare commands, 2-91, 2-92
editing commands, 2-88 through
2-90
error conditions, 2-86
error messages, 2-93, 2-94
initial command format, 2-88
loading, 2-83
loading from paper tape, 2-95
low-speed I/O, 2-86
options, paper tape, 2-84
paper tape format, 2-95
restart, 2-84
.EQ. (relational operator), FORTRAN IV, 8-75
Equal sign (=)
arithmetic statements, 8-78
command decoder, 1-50

Index-6

Exponential format, BASIC, 6-7
EQUIVALENCE statement,
Exponential function, BASIC, 6-39
FORTRAN II, 7-35
Exponentiation, BASIC, 6-8; 6-11
FORTRAN IV, 8-110, 8-111
SABR,4-45
Equivalent symbols, SABR, 4-10
.EQV. (logical operator), FOR- . Expressions,
FLAP /RALF, 5-2
TRAN IV, 8-75
FORTRAN 11,7-12.7-13
Error codes, PAL8, 3-39, 3-40, 3-41
FORTRAN IV, 8-72
Error conditions,
PAL8,3-14
EPIC, 2-86
EXPUNGE pseudo-op PALS, 3-34
FRTS, 8-37
Extended memory, PAL8, 3-27
ODT,1-122
Extension for BATCH input file, 2-3
Error messages,
Extensions, CCL compiler-assemABSLDR, 1-113
bler, 1-59
BATCH, 2-10, 2-11, 2-12
Extensions to file names, keyboard
BITMAP, 2-30
'
monitor, 1-32
BUILD, 2-55
External
CAMP, 2-67
subprograms, FORTRAN II, 7-35
CCL, 1-75, 1-76, 1-77
subroutines, SABR, 4-25
Command Decoder, 1,.51
symbol definition, SABR, 4-50
CREF,2-76
Externals, SABR, 4-21
DIRECT, 2-81,2-82
EXTERNAL statement, FORTRAN
Editor, 1-89
IV, 8-120
EPIC, 2-93, 2-94
External symbol dictionary (ESD
FLAP/RALF, 5-37, 5-38, 5-39
table), RALF, 8-15
FORTRAN II, 7-54, 7-55
FOTP, 2-108
FRTS, 8-38, 8-39, 8-40
F
FORTRAN IV compiler, 8-13, 814, 8-15
F AC (floating point accumulator),
FORTRAN IV loader, 8-29, 8-30
BASIC, 6-80
keyboard monitor, 1-42,1-43, 1-44 FAD, (floating point addition),
Linking Loader (SABR), 4-67
SABR,4-41
Fake indirects, SABR, 4-57
MCPIP, 2-113, 2-114, 2-115
.FALSE. (logical value), FORTRAN
PIP, 1-106 through 1-108
IV, 8-74.
PIP10, 2-119, 2-120
FDV (floating point division), SABR,
RALF assembler, 8-20
RESORC, 2-127
4-41
SABR, 4-46, 4-60
Fields, FORTRAN II
SABR library, 4-71
alphanumeric, 7-21, 7-24
mixed,7-27
SRCCOM,2-131
TD8E initialization, 1-6
numeric, 7-21, 7-22
repetition of, 7-27
TECO, 2-166, 2-184
skip, 7-27
Error message summary, OS/8, E-1
ERROR routine, SABR, 4-46
Fields, FORTRAN IV, 8-90
Errors in FORTRAN N system
logical, 8-95
programs, 8-6
numeric, 8-92, 8-93
Errors in typing, BASIC, 6-2, 6-55
File gap on magnetic tape, 2-63
EXECUTIVE command, CCL, 1-65
File manip'ulation with TECO, 2169, 2~177
Executing RALF file (FORTRAN
specification commands, 2-144, 2IV), 8-5·
145
Exiting BASIC, 6-4
FILENAME pseudo-op, OS/8, 3-32
Exit, normal, FORTRAN II, 7-31,
File names,
7-54
CCL nonstandard, 1-57
EXIT subroutine,
DECsystem-l0,2;...117
FORTRAN 11,7-44
FORTRAN IV, 8-8, 8-9
SABR,4-46
Exit TECO, 2-141
keyboard monitor, 1-32
EXP function,
OS/8 extensions, F-1
FORTRAN II, 7-41
File Oriented Transfer Program
SABR, 4-45
(FOTP), 2-97

Index-7

error messages, i-l08
input specifications, 2-97
load, 1-24
options, 2-104
output specifications, 2-97
File pages, Editor, 1-78
Files, BASIC, 6-60
formats, 6-95
statements, 6-61
Files, FORTRAN IV
file/option specification command,
8-10
output, 8-8
File specifications,
Command Decoder, 1-46
FRTS, 8-32
File transfers, DECsystem-lO, 2-116
First pass assembly, SABR, 4-54
Fixed length ASCII files, BASIC, 663
Fixed point, FORTRAN II, 7-8
FIXMRI pseudo-op, PAL8, 3-34
FIX, SABR, 4-42
FIXTAB pseudo-op, PAL8, 3-34
FLAP /RALF assemblers
arithmetic operations, 5-2
data specification, 5-16
error messages, 5-37, 5-38
FPP mode addressing, 5-13
FPP operation codes, 5-6
hardware, 5-1
literals, 5-15
logical operations, 5-2
PDP-8 mode addressing, 5-6
PDP-8 operation codes, 5-4
pseudo-operators, 5-16, 5-39, 5-40
RALF features, 5-24
referencing memory, 5-22
statement syntax, 5-2
using assembler, 5-36
Floating point
arithmetic, FORTRAN II, 7-42
arithmetic, SABR, 4-40, 4-41
operations, BASIC, 6-80
routines, BASIC, 6-81
also see, FLAP /RALF; FPP;
RALF
FLOAT,
function, FORTRAN II, 7-41
library subroutine, FORTRAN II,
7-47
SABR,4-42
FLOT, SABR, 4-42
FMP, SABR, 4-41
FNA(x) function, BASIC, 6-39
FPP-12 floating point processor, 8-1
FPP mode addressing, FLAP/RALF,
5-13
FPP,~!t~ion codes, FLAP /RALF,

FRTS (FORTRAN IV run-time system), 8-~, 8-32
background/foreground operation,
8-33
error messages, 8-38, 8-39, 8-40
option specifications, 8-35, 8-36
FSB, SABR, 4-41
Foreground/background I/O, FORTRA.N IV, 8-33
FORLIB.RL (FORTRAN IV library
of functions and subroutines),
8-7, 8-40, 8-44
Format control characters, BASIC,
6-18
Formats,
assembly listing, P AL8, 3-7
DECtape, SABR, 4-48
error message, SABR, 4-46
stripped ASCII, FORTRAN II, 72 4 "
FORMAT statement,
FOR'rRAN II, 7-17, 7-18,7-21
FORTRAN IV, 8-89
Form feed, PALS, 3-7
FOR statement, BASIC, 6-27
FORTRAN library, 5-36
FORTRAN II,
calling, 7-1
character set, 7-8
compiler, 7-1
errors, 7-54
language, 7-8
load, 1-21
maximum size of program, 7-50
mixing SABR and FORTRAN II
statements, options, 7-2
program execution, 7-1
program segments, 7-51
FORTRAN IV, 8-1
compiler, 8-9
library, 8-40
loader, 8-20
'
paper tape loading instructions, 8- 124
plotter routines, 8-127
RALF assembler, 8-15
run-time system (FRTS), 8-31
source language, 8-65
FOTP- see File Oriented Transfer
Program
Functions
BASIC; 6-33, 6-39, 6-113, 6-114,
6-123
FORTRAN II, 7-40,7-41
FORTRAN IV, 8-46
LAB8/E,6-148
SABR,4-44
FUNCTION statements,
FORTRAN II, 7-36
F9RTRAN IV, 8-115

Index-8

G
Generating data, SABR, 4-22
GENIO, SABR, 4-47
.GE. (relational operator), FORTRAN IV, 8-75
GET command, keyboard monitor,
1-37
Get function, LAB8/E, 1-34
Getting on the air with OS/8 BASIC,
6-148
G format conversions, FORTRAN
IV, 8-94
GOSUB subroutine, BASIC, 6-43
GOTO statement,
BASIC, 6-25
FORTRAN II, 7-29, 7-30
FORTRAN IV, 8-80
Groups, repetition of, FORTRAN
II, 7-28
.GT. (relational operator), FORTRAN IV, 8-75
H

Handlers-see Device handlers
Hardware bootstrap, 1-2, 1-:3, 1-4,
also see Bootstraps
Hardware configuration, FLAP /
RALF,5-1
FORTRAN IV, 8-1
H conversion (FORTRAN IV), 8-96
Header block, BUILD, 2-57
HELP command, CCL, 1-66
High common, SABR, 4-53
Histogram plotter example, FORTRAN IV, 8-147
Hollerith, FORTRAN II
constants, 7-9
conversion, 7-26
strings, 7-42
Hollerith, FORTRAN IV
constants, 8-70
data, 8-96
Hyphen construction in BUILD, 2-41
I
IABS~

FORTRAN II, 7-41
SABR,4-43
- IF,
statement, FORTRAN II, 7-30
pseudo-op, SABR, 4-19
IFAD, SABR, 4-42
IFOEF pseudo-op (PAL8), 3-30
IF END# statement, BASIC, 6-65
IF-GOTO statement, BASIC, 6-26
IFIX,
FORTRAN II, 7-41
SABR,4-42

IFNDEF pseudo-op, PAL8, 3-31
IFNZRO pseudo-op, PAL8, 3-31
IF statements, FORTRAN IV, 8-82
IF-THEN statement, BASIC, 6-26
6-49
'
IFZERO pseudo-op, PAL8, 3-31
Image file, FRTS, 8-32
Implied DO loops, FORTRAN II
7-18
'
Incore DATA list, BASIC, 6-75
Incrementing operands SABR 4-11
,
Increment values; . '
FORTRAN II, 7-18, 7-32
FORTRAN IV, 8-84
Index,
. FORTRAN II, 7-30, 7-31
FORTRAN IV, 8-84
Indirect addressing, FLAP /RALF
5-6
'
PALS, 3-23, 3-27
Indirect commands, CCL, 1-56
Indirect references, ODT, 1-121
Initia1ization of TD8E system, 1-4
bootstraps, 1-7, 1-8
error messages, 1-6
Initialize function, LAB8/E, 6-127
Initial value,
FORTRAN 11,7-31
FORTRAN IV, 8-84 .
Input devices, BITMAP, 2-26
Input files,
BATCH, 2-1, 2-7, 2-8
Editor, 1-79
TEeo, 2-133
Input! output
BASIC Run Time System (BR TS),
6-94 6-96
list, FORTRAN II, 7-17
low speed, with EPIC, 2-86
SABR,4-40
transfer microinstructions P AL8
"
3-26
Input!output specifications,
CCL,I-54
Command Decoder, 1-49
DIRECT,2-77
FOTP,2-97
RESORC, 2-121
Input!output statements
BASIC, 6-15
FORTRAN II, 7-16
FORTRAN IV, 8-101 through 8106
.
Input register sampling, LAB8/E 6135
'
INPUT statement, BASIC, 6-15 619,6-47
'
INPUT # statement, BASIC 6-63
Input string, Command Dec~der 145
'

Index-9

Inputting string data, BASIC, 6-47
Insertion commaIfds, TECO, 2-150
Instruction codes, C-l
Instructions,
ELAP /RALF, 5-2
FORTRAN II operating, 7-1
PAL8, 3-6, 3-22
SABR multiple word, 4-34
SABR skip, 4-33, 4-37 _
Integer arithmetic, SABR, 4-43
Integer constants,
. FORTRAN II, 7'-8
FORTRAN IV, 8-67
Integer format, BASIC, 6-6
INTEGER function, BASIC, 6-37
Integer variables,
FORTRAN II, 7-10
FORTRAN IV, 8-71
INTEGR Library subroutine, FORTRAN II, 7-49
Inter-buffer character string search,
Editor, 1-87
Internal statement number (lSN),
FORTRAN IV, 8-11
Internal subroutines, SABR, 4-24
Internal symbol representation,
PAL8,3-14
Intra-buffer character string search,
Editor, 1-84
I/O-see Input/output
IOH Library subroutine, FORTRAN
II, 7-42, 7-48
IOPEN, SABR, 4-47
Library subroutine, FORTRAN
II, 7-42, 7-49
IPOWRS Library subroutine,· FORTRAN II, 7-49
IRDSW function FORTRAN II, 741
IRDSW. SABR. 4-43
IREM ftInction; FORTRAN II, 7-41
IREM, SABR, 4-43
IRFM .function, FORTRAN II, 7-41
IRFM, SABR, 4-43
ISTO, SABR, 4-42
J

Job status word, keyboard monitor,
1-37
K
KE8-E extended arithmetic element,
8-1
Keyboard Monitor, 1-30
commands, 1-35
file names and extensions, 1-32
permanent device names, 1-30,

system conventions, 1-30
using the monitor, 1-33
K (octal mode), SABR, 4-8
L
LAB8/E functions for OS/8 BASIC,
6-124
examples, 6-135
function summary, 6-148
preparation, 6-125
support functions, 6-127
Labels,
PAL8,3-6
SABR, 4-5, 4-6
LAP pseudo-op, SABR, 4-17
Large pages, TECO, 2-167
Leader/trailer code, SABR, 4-49
checksum, 4-53
LEN function (string length), BASIC,
6-50
.LE. (relational operator), FORTRAN IV; 8-75
LET statement, BASIC, 6-15, 6-49
Levels of overlays, FORTRAN IV
loader, 8-20, 8-28
LIB8 (LIB8 relocatable binary tape)
load, 1-22
LIBRA (FORTRAN IV system librarian), 8-7, 8-41, 8-126
Libraries, FORTRAN IV, 8-7, 8-40
functions and subroutines, 8-46
through 8-65
Library, FORTRAN II
error messages, 7-55
functions, 7-41
subroutines, 7-47, 7-48, 7-49
subprograms, 7-40
Librarv. SABR
programs, 4-71
subprograms, 4-39
error messages, 4-72
LIBSET (Library Setup binary tape)
load, 1-22,
LINCt~pe bootstrap for PDP-12
systems, 1-9
system BUILD, 2-35
system software, 1-1
Line continuation designator, FORTRAN II, 7-14
Line deletion, keyboard monitoF, 134
LINE FEED key, 1-34
Line of text (TECO), 2-132
Linkage routines, SABR, 4-34, 4-62
CDFSKP, 4-35
SDZSKP, 4-35
DUMSUB, 4-36

Index-lO

LINK, 4-27, 4-36
OBISUB, 4-36
OPISUB, 4-35
RTN,4-37
Link generation and storage,PAL8,
3-35
Linking Loader, SABR, 4-62
error messages, 4-68
loading, 4-63
operation, 4-62
options, 4-63
Links, FLAP, 5-16
LIST and LISTNH commands,
BASIC, 6-56
LIST command, CCL, 1-67
Listing files, FORTRAN IV, 8-8
Listing suppression, PAL8, 3-10
Lists, BASIC, 6-30
Lists, FORTRAN II, 7-18
subscript, 7-11
Literals,
PAL8, 3-20, 3..21
PDP-8 code (FLAP), 5-15
SABR, 4~8 .
LOAD command, CCL, 1-68
Loader, FORTRAN IV, 8-20
error messages, 8-29, 8-30
image file, 8-4, 8-8, 8-23
run-time options, 8-25
image files, FRTS, 8-32
symbol map output file, 8-23
LOADER (Linking Loader binary
tape) load, 1-22
LQader relocation codes, SABR, 449 through 4-53
Loading
BATCH,2-21
binary output, 1-108
BITMAP, 2-26
EPIC, 2-83
EPIC from paper tape, 2-95
instructions, paper. tape (FORTRAN IV), 8-124
plotter routines from paper tape,
8-143
procedures, summary, B-1
RALF file (FORTRAN IV), 8-5
relocatable programs, 2-62
SRCCOM,2-128
system from paper tape, 1-20
Location counter, resetting (PAL8),
3-29
Logarithm function, BASIC, 6-39
Logarithm, natural, SABR, 4-45
Logical constants, FORTRAN IV,
8-70
Logical expressions, FORTRAN IV,
8-74, 8-77
Logical fields, FORTRAN IV, 8-95

Logical operations, FLAP/RALF,
5-3
Logica1 operators, FORTRAN IV,
8-74
Looping commands, TECO, 2-155
Loops in BASIC program, 6-27
nesting, 6-29
.LT. (relational operator), FORTRAN IV, 8-75
.
. Low-speed I/O with EPIC, 2-86
M
Macro library management, TECO
2-175
.
Magnetic tape file names, 2-113
Magtape/Cassette Peripheral Interchange Program (MCPIP), lIS, 2-110
'
binary tape load, 1-23
error messages, 2-113, 2-114, 2115
options, 2-112, 2-113
Manipulating DUMMY variables,
SABR,4-12
MAP command, CCL, 1-69
Match control characters, TECO,
2-154
Maximum size of a FORTRAN program, FORTRAN II, 7-50
MCPIP-see Magtape/Cassette Peripheral Interchange Program
,Memory addresses, PAL8, 3-10
Memory, FPP (FLAP/RALF), 5-13,
5-22
Memory reference instructions,
PAL8,3-22
Memory reservation, P AL8, 3-30
Merging files with TECO, 2-169
Microinstructions, P AL8, 3-23
MI8-E hardware bootstrap, 1-2, 1-10
Mixed fields, FORTRAN II, 7-27
Mixing SABR and FORTRAN statements, FORTRAN 11,7-50 .
Mnemonics for devices, BOOT, 2-33
Monitor commands, BA'feH, 2-4
MPY, SABR, 4-43
Multiple entry points, FORLIB, 8-46
Multiple file specifications, Command Decoder, 1-45
Multiple record formats, FORTRAN II, 7-28
Multiple word instructions, SABR,
4-34
Multiplication,
BASIC, 6-8
PAL8, 3-15
Multistatement lines, PAL8, 3-8
MUNG command, CCL, 1-69

Index-ll

N
Octal Debugging Technique (ODT),
1-113
NAME command, BASIC, 6-59'
commands, 1-115,1-122
Names
errors, 1-122
of device nandiers, BUILD, 2-34,
special characters, 1-115
2-35, 2-41
techniques, 1-121
of files-, FORTRAN IV, 8-8, 8-43
OCTAL
pseudo-op, SABR, 4-17
Natural logarithm function,
ODT command, keyboard monitor,
BASIC. 6-39
1-40
SABR, . 4-45 .
ODT-see
Octal Debugging Tech.
.NE. (relational operator), FOR-,
nique
TRAN IV, 8-75
Off-page references, PAL8, 3-35
Nested DO loops, FORTRAN IV,
OLD command, BASIC, 6-58
8-86
OOPEN subroutine;
Nested literals, PALS, 3-21
FORTRAN II, 7-43
Nested loop commands,
SABR, 4-47
BASIC, 6-29
OPDEF pseudo-op, SABR, 4-20
TECO, 2-155
Operands,
Nested pseudo-ops, PAL8, 3-31
PAL8,3-6
Nested subroutines, BASIC, 6-45
SABR, 4-5, 4-7,4-11
NEW command, BASIC, 6-58
Operate microinstructions, 3-24
NEXT statement, BASIC; 6-27
Operations
Nonexecutable FORMAT statealgebraic, FORTRAN II, 7-12
ments, FORTRAN II, 7-17
arithmetic and logical, FLAP/
NOPUNCH pseudo-op, PAL8, 3-31
RALF,5-3
Normal exit, FORTRAN II, 7-31
Operators, BASIC
.NOT. (logical operator), FOR·
arithmetic, 6-8
TRAN IV, 8-74
6-10
relational,
Null extension, FORTRAN IV, 8-10
Operators, FORTRAN IV
Null lines, SABR, 4-6
logical, 8-74
Numbers, BASIC, 6-6
relational, 8-75
printing format, 6-19
arithmetic, 8-72
Numbers, PAL8, 3-9
Operators,
Number sign (#),
PAL8, 3-14, 3-15,3-16
CCL,I-57
SABR, 4-5, 4-6
Editor, 1-78
OPISUB Linkage routine, SABR,
SABR,4-12
4-35
Numeric,
Optimizing SABR code, SABR, 4-57
arguments, TECO, 2-160
Options,
characters, SABR, 4-4
1\ DC'T TYR 1 1 1 n
constants, SABR, 4-7
BATCH,2-3
conversion mode, SABR. 4-8, 4-17
BITMAP, 2-27
field codes, FORTRAN -II, 7-22
CCC, 1-55
field specifications, FORTRAN II,
CREF, 2-69,2-70
7-21
DIRECT, 2-78
fields, FORTRAN IV, 8-92, 8-93
Editor, 1-79
file format, BASIC,6-95
FOTP, 2-104
input conversion, FORTRAN II,
8-35, 8-36
FRTS,
7-23
PAL8, 3-2, 3-3, 3-4
PIP, 1-97 through 1-102
o
PIPI0, 2-117
RESORC, 2-122
OBISUB Linkage routines,
SABR, 4-36
SRCCOM, 2-129
Object files, FORTRAN IV, 8-8
switch register, 2-60
OCLOSE subroutine,
OR, Boolean inclusive (PAL8), 3-15
FORTRAN II, 7-44
OR group skip instructions, P AL8,
3-25
SABR,4-47
.OR. (logical operator), FORTRAN
Octal constants, FORTRAN IV,
IV, 8-74
8-69
J.1.L1U.L..ILJ.I.,

Index-12

.... .", ~.LV

pseudo operators, 3-26
Output,
restarting and terminating, 3-5
BITMAP, 2-28
statements, 3-6
CREF, 2-72
terminating assembly, 3-38
SRCCOM, 2-129
P AL8 pseudo-op handing, CREF,
Output commands, TECO, 2-168
- 2-72
Output control, PAL8, 3-31
Output file name default, FOR- Paper tape format, EPIC, 2-95
Paper tape loading instructions
TRAN IV, 8-8
(FORTRAN IV), S-124
Output files,
_Paper tape option, EPIC, 2-S4
BATCH,2-2
Paper tape system building, 1-17,
Editor, 1-79
2-36, 2-37
FORTRAN IV, 8-2, 8-7, 8-8
Paper tape system loading, 1-20
FORTRAN IV loader, 8-23
Parameters, SABR, 4-8, 4-10
TECO, 2-133
Parentheses,
Output register, LAB8/E, 6-135
BASIC arithmetic operations, 6-9
Output specifications,
Command Decoder, 1-50
DIRECT,2-77
_ FORTRAN II, 7-12
FOTP,2-99
PALS, 3-20RESORC, 2-121
PDP-8 expression (FLAP)
Output tape, binary SABR, 4-49
Pass 1, 2 and 3, PAL8, 3-1, 3-37
Overflow, FORTRAN II, 7-42
subroutine
arguments,
Overlays, BASIC, 6-66, 6-101, 6-122 . Passing
BRTS,6-72
SABR,4-29
Overlays, . FORTRAN IV loader,
PAUSE
pseudo-op, SABR, 4-16
8-20, 8-22
- levels, 8-28
statement, FORTRAN II, 7-32
MAIN,8-21
statement FORTRAN IV, 8-88
PDP-8 mode addressing, FLAP I
RALF,5-6
P
-PDP-8 operation codes, FLAPI
RALF, 5-4, 5-5
Packed 6-bit ASCII text strings,
PDP-S/E interrupt system, 8-36
SABR,4-23
Page-by-page assembly, SABR, 4-32
PDP-12 computer, ~-26
Page format control, PAL8, 3-31
PDP-12 and TECO, 2-182
Page format, SABR, 4-33
PDP-12 system, bootstrap procePage
manipulation
commands,
dure, 1-9
TECO,2-146
Period (.) character-s~e DOT (.)
Page of text, TECO, 2-132
character
PAGE pseudo-op, SABR, 4-18,4-57
Peripheral Interchange Program,
(PIP), 1-97
Page zero addressing, PAL8, 3-27
Page 0 reference, FLAP IRALF, 5-6
binary tape load, 1-23 .
Page 0 usage, BASIC run-time syserror messages, 1-106 through
tem, 6-102
1-108
Paging mode, automatic, SABR,
examples of specification com4-33
mands, 1-102
PAL command, CCL, 1-70
options, 1-98 through 1-102
Permanent device names, keyboard
P AL8 Assembler
monitor, 1-30, 1-31
binary tape load, 1-23
Permanent symbols,
calling, 3-1
PAL8,3-9
characters, 3-5, 3-18
SABR,4-9
coding practices, 3-36
Permanent symbol table,
error conditions, 3-40
link generation and storage, 3-35
PAL8, 3-11, 3-33, 3-41 through
3-44
memory reference instructions,
3-22
SABR, 4-3S, C-1
microinstructions, 3-23
PIP-see Peripheral Interchange
options, 3-2
Program
permanent symbol table, 3-41
PIP 10 utility program, 2-116
program preparation, 3-37
binary tape load, 1-24
Index-13

error messages, 2-119
options, 2-117
Plot function, LAB8/E, 6-128
Plotter, FORTRAN TV
commands, 8-129 through 8-142
examples, 8-144 through 8-147
initialization, 8-142
loading from paper tape, 8-143
routines, 8-127, 8-:128
Plotting routines added to FORTRAN library, 8-142
PNT(x) function, BASIC, 6-21
POS function, BASIC, 6-53
Postdeletion, FOTP, 2-103
POWER routines, SABR, 4-45
POWERS Library subroutine, FORTRAN II, 7-48
Predeletion, FOTP, 2-103
PRINT command, CCL, 1-71
PRINT statement, BASIC, 6-16,
6-19
PRINT # statement, BASIC, 6-63Priority of arithmetic operators,
BASIC, 6-9
Program addresses, SABR, 4-38
Program assembly, PAL8, 3-36
Program correction, BASIC, 6-55
- Program execution, BASIC, 6-3
Programming notes, SABR, 4-57
TECO, 2-164
Program termination statements,
BASIC, 6-14
Pseudo-operators,
FLAP, 5-16
FLAP/RALF, 5-40, 5-41
PAL8,3-26
PAL8 conditional, 3-30
PAL8 nested, 3-31
SABR, 4-12 through 4-29, C-l
Pseudo-op handHng, CREF, 2-71
Punch and Compare program-see
EPIC
PUNCH command, CCL, 1-71
Punched card program preparation,
FORTRAN N, 8-1
Punched cards, 2-12
input file, 2-14
PUNCH pseudo-op, PAL8, 3-31
Put function, LAB8/E, 6-135
Q

Q registers, TECO, 2-155, 2-156
Question mark (1) in ODT, 1-115wild character CCL, 1-55

R
Radix control
PAL8,3-27
TECO commands, 2-164

RALF assembler, 5-24, 8-15
assembly error, 8-17
error messages, 8-20
FORTRAN IV files, 8-8
hardware configuration, 5-1
output, 8-3
programming notes, 5-30
relocation and linking of modules,
~23
.
run-time options, 8-18
statements, 8-2
subroutines, 5-30
RANDOMIZE statement, BASIC,
6-35
Random number function, BASIC,
6-34
Range,
DO loop, FORTRAN N, 8-84,
8-85
integer constants, FORTRAN II,
7-9
integer variables, FORTRAN II,
7-10
real constants, FORTRAN II, 7-9
READ statement,
BASIC, 6-22
FORTRAN II, 7-17, 7-19
FORTRAN IV, 8-101, 8-103
SABR, 4-40
Real constants, FORTRAN IV, 8-68
Rearranging files with TECO, 2-169
Record formats, multiple, FORTRAN II, 7-28
Records, FORTRAN II, 7-18
Relational operators,
. BASIC, 6-10
FORTRAN IV, 8-75
Relative origin, SABR, 4-49
Relocatable binary files, FORTRAN
IV, 8-8
Relocatable linking loader. SABR,
4-24
RELOC pseudo-op (relocation).
PAL8, 3-33
REM statement, BASIC, 6-14
RENAME command, CCL, 1-71
REORG pseudo-op, SABR, 4-18
Re-origin, SABR, 4-51
Repetition,
of fields, FORTRAN II, 7-27
of groups, FORTRAN II, 7-28
Replacement operator, FORTRAN
II, 7-16
RES command, CCL, 1-71
RESEQ program, BASIC, 6-55
Reserving memory, PAL8, 3-30
Reserving words of core, SABR,
4-22
RESORC utility program, 2-121
binary tape load, 1-24

Index-14

error messages, 2-127
device types, 2-123
handlers, 2-125
options, 2-122
Restarting
EPIC, 2-84
PAL8,3-5
OS/8, 1-29
RESTORE statement, BASIC, 6-23
RESTORE# statement, BASIC,
6-64
Restrictions,
BATCH,2-13
CREF,2-73
RETRN, SABR, 4-27
RETURN key,
PAL8,3-7
SABR,4-5
RETURN statement,
FORTRAN-II, 7-36, 7-40
FORTRAN IV, 8-119
RETURN subroutine, BASIC, 6-43
REWIND command, CCL, 1-72
REWIND . statement, FORTRAN
.
,
IV, 8-107
RF08 disks, 1-26
RIM loader programs, 8-2
RK8 disk bootstrap, 1-28, 1-29
RK8E disk bootstrap, 1-26, 1-27
Routines, BASIC floating point, 6-81
Routines, FORTRAN II, 7-44
Routines, SABR
DECtape I/O, 4-47
DUMMY, 4-29
ERROR,4-46
LINK,4-27
POWER,4-45
RTN,4-36
Utility, 4-45
Routines unusable by assembly language functions, BASIC, 6-101
Rubout key,
BASIC, 6-2, 6-55 .
Editor, 1-84
keyboard monitor, 1-33, 1-34
RUN and RUNNH commands,
BASIC, 6-60
Run command, keyboard monitor,
1-41
Running TECO on PDP-12, 2-182
Run-time diagnostics, BASIC, 6-116.
6-117, 6-118
Run-time linkage routines, SABR.
4-34
Run-time options,
FORTRAN IV, 8-35
FORTRAN IV loader, 8-25
RALF assembler, 8-18
Run-time system,
BASIC, 6-71

FRTS.8-32
RWTAPE Library subroutine, FORTRANI!,7-49
- S
SABR assembler
binary tape load, 1-21
code optimization, 4-57
error messages, 4-60
mixing SABR and FORTRAN II
statement, 7 - 5 0 options, 4-2
permanent symbol table, C-l
programming notes, 4-57
sample listings, 4-53
SABR pseudo-op handling, CREF,
2-72
SAC (string accumulator) BASIC,
6-76
Sample function, LAB8/E, 6-130
'SAVE command,
BASIC, 6-59
keyboard monitor, 1-38, 1-39
Saving BATCH, 2-21
Scalar table, BASIC, 6-77
Scalar variables, FORTRAN II,
7-10
Scale factors, FORTRAN IV, 8-94,
8-95
SCRATCH command, BASIC, 6-57
Search commands, TECO, 2-150
Search mode, Symbolic Editor, 1-82
SEG$ function, BASIC, 6-53
Semicolon use,
. BASIC format control character,
6-18
FLAP/RALF, 5-2
P AL8 statement terminator, 3-7
SHIFT/O keys in BASIC, 6-2, 6-55
SIGN function, BASIC, 6-36
Simple relocation, SABR, 4-50
Sine function, BASIC, 6-38
SIN function
FORTRAN II, 7-41
FORTRAN IV, 8-63
SABR,4-44
Single character search, Editor, 1-83
Single quotes (') in Hollerith conversion, FORTRAN IV, 8-97
Six-bit ASCII text strings, packed,
SABR,4-23
Size of a FORTRAN II program,
7-50
SKIP command, CCL, 1-72
Skip fields, FORTRAN II, 7-27
Skip instructions,
.
PAL8, 3-25
SABR, 4-33, 4-37
SKPDF pseudo-op, SABR, 4-20

Index-I 5

Slash (/),
Command decoder, 1-49
FLAP /RALF, 5-3
FORTRAN II, 7-28
P AL8 comment field, 3-7
Slave computer, 6-124
Software -distribution OS/8, 1-1
Source Compare Utility Program
(SRCCOM), 2-128
assembly, 2-128
error messages, 2-131
loading, 2-128
options, 2-129
output, 2-129
Source language, FORTRAN IV,
8-65
Source program,
FORTRAN II, 7-3
preparation, FORTRAN IV, 8-1
Space character
FLAP/RALF, 5-2
PAL8, 3-16
Special characters,
PAL8, 3-18, 3-19
SABR,4-4
Specification statements,
FORTRAN II. 7-33
FORTRAN IV, 8-107
Specification strings, P AL8, 3-4
Splitting files with TECO, 2-169
Spool device files, BATCH, 2-2, 2-7,
2-8
Square brackets ([]) characters,
Command Decoder, 1-50
PAL8, 3-20
.
Square root function, BASIC, 6-37
SQR T function
FORTRAN II, 7-41
FORTRAN IV, 8-64
~A RD

V4. ................ ,

.:1.&&
I

SQRT library subroutine, FORTRAN II, 7-48
SQUISH command, CCL, t-72
SRCCOM-see Source Compare
Utility program
START command, keyboard monitor, 1-41
Starting OS/8 on
TC01/TC08 DECtape, 1-2, 1·3
TD8E DECtape, 1-4
LINCtape, 1-9
Statement field, FORTRAN II, 7-14
Statement label, PAL8, 3-9
Statement numbers,
BASIC, 6-13
FORTRAN II, 7-14
FORTRAN IV, 8-66
FORTRAN IV internal, 8-11
Statements,

BASIC, 6-12, 6-108 through 6-113
Statements, FORTRAN II
arithmetic, _7-16
control; 7-29
data transmission, 7-17, 7-21
input/output, 7-16
mixing SABR and FORTRAN II,
7-50
nonexecutable FORMAT, 7-17
specifications, 7-33
subprogram, 7-35
Statements, FORTRAN 11
CALL,7-39
CALL OPEN, 7-33
COMMON,7-34
CONTINUE,7-32
DIMENSION, 7-34, 7-36
DO, 7-30
END, 7-33, 7-36
EQUIVALENCE,7-35
FORMAT, 7-18, 7-21
FUNCTION, 7-36
GO TO, 7-30
IF, 7-30
PAUSE, 7-32
READ, 7-17, 7-19
RETURN, 7-36, 7-40
STOP, 7-33
SUBROUTINE, 7-38
WRITE, 7-17, 7-20
Statements, FORTRAN IV, 8-67
arithmetic, 8-77 ,
assignment, 8-75;8-79
carriage control, 8-97, 8-98, 8-99
control, 8-80
data transmission, 8-88
device control, 8-106
input/output, 8-101 through 8-106
specification, 8-107
summary, 8-121 through R-124
type declaration, 8-114
Statements, PAL8, 3-6
Statements, SABR, 4-5,4-27
Statement syntax, FLAP/RALF, 5-2
Statement terminators, PAL8, 3-7
Statement types, FORTRAN II,
7-15
STO, SABR, 4-42
STOP statement,
BASIC, 6-14
FORTRAN II, 7-33
FORTRAN IV, 8-88
Storage,
common, SABR, 4-21
conserving space, FORTRAN II,
7-35
location, FORTRAN II, 7-35
Storage specification, FORTRAN
IV, 8-107

Index-16

STR$ function, BASIC, 6-52
Strings, BASIC
array table, 6-79 .
concatenation, 6-50
conventions, 6-46
handling functions, 6-50
storage, 6-74
symbol table,6-78
Strings, Hollerith, FORTRAN II,
7-42
Stripped ASCII format, FORTRAN
II, 7-24
SUBMIT command, CeL, 1-72
Subprogram library, SABR, 4-39
Subprograms, FORTRAN II
external, 7-35
function, 7-36
library, 7 -40
subroutine, 7-37
Subprogram statements,
FORTRAN II,7-35
FORTRAN TV, 8-114
Subroutines, BASIC, 6-33, 6-43
nested, 6-45
BRTS, 6-85
Subroutines, FORTRAN II
chaining, 7-51
closed, 7-35
library, 7-47
subprograms, 7-37
Subroutines, FORTRAN II
CHAIN,7-44
EXIT,7-44
IOPEN,7-42
OCLOSE, 7-44
OOPEN, 7-43
Subroutines, FORTRAN IV, 8-46
through 8-65
Subroutines, PDP-8 mode, 5-30
Subroutines, RALF, 5-29
Subroutines, SABR
argument passing, 4-29
external,4-25
internal, 4-24
linkage code, 4-52
Subroutines, SABR
CKIO, 4-46
EXIT,4-46
SUBROUTINE statement, .
FORTRAN II, 7-38
FORTRAN IV, 8-117
SUBSC, SABR, 4-43
Subscripted variables,
BASIC, 6-30
FORTRAN II, 7-11
SABR,4-43
Subscript list, FORTRAN II, 7-11
Subscripts,
BASIC, 6-31

FORTRAN II array, 7-34
FORTRAN IV, 8-72
Subtraction,
BASIC, 6-8
PAL8,3-15
Suppression of
listing, PAL8, 3-30
printed error messages, FOR. TRAN IV, 8-13
Symbol definition, SABR, 4-20
Symbolic address, PAL8, 3-9
Symbolic Editor, 1-78
commands, 1-93 through 1;,.97
error messages; 1-89
key commands, 1-80
options, 1-79
search mode, 1-83
special characters, 1-81
Symbolic instructions, PAL8, 3-13
Symbolic operands, PAL8, 3-14
Symbol map output file, FORTRAN
IV loader, 8-23
Symbols,
PAL8,3-9
SABR, 4-9, 4-10
Symbol table, C-l
BRTS, 6-73,6-76
PAL8,3-11
SABR, 4-38·
System build instructions, BASIC,
6-119
System conventions, keyboard monitor, 1-30
System devices
for cassette build, 1-12,
for paper tape build, 1-18
System tape processing, nonstandard,
1-5

t
Tables, BASIC, 6-30
Tabs,
FLAP/RALF, 5-2
FORTRAN II, 7-15
Tabulations, PAL8, 3-7
TAB(x) function, BASIC, 6-21
Tags,FLAP/RALF, 5-2
TAN function,
FORTRAN II, 7-41
FORTRAN IV, 8-65
SABR,4-45
TCO l/TC08 systems software, 1-1,
1-2
TD8E DECtape system,
bootstraps, 1-7, 1-8
en:or messages, 1-6
initialization, 1-4
software, 1-1

Index-17

TECO command, CCL, 1-72
TECO (Text Editing and Correcting)
program, 2-132
arithrnetic operator, 2-163
assembly instructions, 2-183
branching commands, 2-157
buffer pointer manipulation commands, 2-147
character set, 2-142
command loops, 2-155
command summary, 2-179 through
~
2-182
conditional ex.ecution commands,
2-158
deletion commands, 2-149
error messages,. 2-167, 2-184
examples, 2-167 through 2-177
file specification commands, 2-144
incompatibilities with DECsystem10, 2-178
insertion commands, 2-149, 2-150
introductory commands, 2-132
large pages, 2-167
match control characters, 2-154
numeric arguments, 2-160
page manipulation . commands,
2-146
programming aids, 2-164
Q-registers, 2-155
retrieving lost files, 2-177
running on PDP-12, 2-182
search commands, 2-151
techniques, 2-169
text typeout commands, 2-148
Terminal value, FORTRAN II, 7-31
Terminating P AL8, 3-5
Termination of assembly, PAL8,
3-38
Terminators, PAL8 statement, 3-7
Text buffer, Editor, 1-82
Text collector, Editor, 1-82
Text Editing and Correcting program-see TECO
Text mode, Editor, 1-80
TEXT pseudo-op, SABR, 4-23
Text strings, packed six-bit ASCII,
SABR,4-23
Text strings, PAL8, 3-29
Text typeout commands, TECO,
2-148
.
Traceback feature, FRTS, 8-37
Transcendental functions, BASIC,
6-38
Transfer vector, SABR, 4-53
TRC(x) function, BASIC, 6-42
TRIG library subroutine, FORTRAN II, 7-49
.TRUE. (logical value), FORTRAN
IV, 8-74

Truncation,
FORTRAN II, 7-10
FORTRAN IV, 8-48, 8-59
Truth tahle for logical expressions,
FORTRAN IV, 8-77" Two's complement addition and subtraction, ·PAL8, 3-15
Two-word block, SABR, 4-27, 4-29
Two-word vector, S.l~1BR, 4-36
Type classification, FORTRAN IV,
8-71
TYPE command, CCL, 1-72
Type declaration statements, FORTRAN IV, 8-114
Typeset pseudo-operator, PAL8,
3-32
Typing error, BASIC, 6-2, 6-55
U
UA, UB, UC commands, CCL, 1-74
UDEF function, BASIC, 6-41
Unconditional GUTO,
FORTRAN II, 7-29
FORTRAN IV, 8-80
Underflow, FORTRAN II, 7-42UNLOAD command, CCL, 1-74
Uparrow (t) command decoder -response, 1-21
User assembly language function,
BASIC, 6-91
User-defined functions, BASIC, 6-39
User defined symbols,
PAL8, 3-9, 3-11
SABR, 4-10
User service routine,
called by PAL8, 3-32
USE statement, BASIC, 6-93
USR and device handler, SABR,
4-60
Utility commands; 2-1
UTILITY library subroutine, FORTRAN II, 7-48
.
Utility routines, SABR, 4-45
V
VAL function, BASIC, 6-52
Variable length files, BASIC, 6-62
Variables,
BASIC, 6-8, 6-30, 6-48, 6-73
FORTRAN II, 7-9, 7-17
array, 7-11
integer, 7-10
maximum, 7-24
real,7-10
scalar, 7-10
subscripted, 7-11
FORTRAN IV, 8-70
SABR, 4-12, 4-43
VC8-E display control, 6-124

Index-1S

VERSION command, eCL, 1-74
Version numbers, OS/8, H-1

WT APE routine,
FORTRAN II, 7-44
SABR,4-47

W
Wild card construction,
.
CCL, 1-55
DIRECT, 2-77
Wild field, FOTP, 2-97
WRITE function (SABR), 4-40
WRITE statement,
FORTRAN II, 7-17, 7-20
FORTRAN IV, 8-101, 8-104

X
,XOR (logical operator), FORTRAN
IV, 8-74

Z
Z character, FLAP/RALF, 5-6
ZERO command, CCL, 1-74
Zeroes, leading/trailing FORTRAN
IV, 8-66, 8-68

Index-19

ita I
Printed in U.S.A.