OS/8 SOFTWARE SUPPORT MANUAL
(Version 3)
DISCLAIMER
This document file was created by scanning the
original document and then editing the scanned
text. As much as possible, the original text
format was restored. Some format changes were
made to insure this document would print on
current laser printers using 60 lines per page.
The original spelling and grammar has been
preserved.
1-Sep-1996
OS/8 SOFTWARE SUPPORT MANUAL
(Version 3)
DEC-S8-OSSMB-A-D
-------------------------------------------------------
| Order additional copies as directed on the Software |
| Information page at the back of this document. |
-------------------------------------------------------
digital equipment corporation * maynard, massachusetts
First Printing, January 1973
Revised, June 1974
The information in this document is subject to change without notice
and should not be construed as a 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 (C) 1973, 1974 by Digital Equipment Corporation
The HOW TO OBTAIN SOFTWARE INFORMATION page, located at the back of
this document, explains the various services available to DIGITAL
software users.
The postage prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in
preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
CDP DIGITAL INDAC PS/8
COMPUTER LAB DNC KA10 QUICKPOINT
COMSYST EDGRIN LAB-8 RAD-8
COMTEX EDUSYSTEM LAB-8/e RSTS
DDT FLIP CHIP LAB-K RSX
DEC FOCAL OMNIBUS RTM
DECCOMM GLC-8 05/8 RT-ll
DECTAPE IDAC PDP SABR
DIBOL IDACS PHA TYPESET 8
UNIBUS
PREFACE
The 8K Operating System (OS/8) is an extremely powerful program
development system. OS/8 greatly expands the capabilities of any 8K
PDP-8, 8/I, 8/L, 8/E, or PDP-12 computer having the necessary disk or
DECtape storage. Use of OS/8, is described in detail in the OS/8
HANDBOOK (DEC-S8-OSHBA-A-D).
This manual covers a wide range of advanced topics pertinent to the
experienced user. In Chapter 1 the various basic system concepts are
described and terms are defined. Chapter 2 explains the process by
which user programs call upon the system for the performance of
important operations including loading device handlers, opening and
closing files, and chaining to other programs. Chapter 3 covers the
functions of the Command Decoder and the means by which the user
program can employ its services. Chapter 4 explains the use and
operation of the device handlers in detail. Chapter 5 covers the
details of "custom tailoring" a system, including how to write a
device handler for a non-standard device.
Technical information, intended to enhance the information in the OS/8
HANDBOOK, as well as this manual, can be found in the Appendices.
Appendix A details the OS/8 directory structure and gives standard
file format. Appendix B describes the system data base and gives the
layouts of the system areas. Appendix C gives a complete list of
system error messages. Appendix D illustrates some useful advanced
techniques and programming "tricks" for use with the OS/8 system.
Appendix E is a complete list of the standard ASCII character codes
meaningful to OS/8. Finally, Appendix F describes a set of generalized
I/O routines for use under the OS/8 system.
iii
CONTENTS
Page
CHAPTER 1 OS/8 CONCEPTS AND TERMINOLOGY 1-1
1.1 SOFTWARE COMPONENTS OF OS/8 1-1
1.2 FILES 1-2
1.2.1 File Names and Extensions 1-2
1.2.2 File Structured Devices 1-2
1.2.3 File Types 1-3
1.2.4 File Directories and Additional
Information Words 1-3
1.3 CORE CONTROL BLOCK 1-4
1.3.1 Program Starting Address 1-5
1.3.2 Job Status Word 1-5
1.3.3 Software Core Size 1-6
1.4 DEVICE NAMES AND DEVICE NUMBERS 1-6
1.5 THE DEVICE AND FILENAME PSEUDO-OPS 1-7
CHAPTER 2 USER SERVICE ROUTINE 2-1
2.1 CALLING THE USR 2-1
2.1.1 Standard USR Call 2-1
2.1.2 Direct and Indirect Calling Sequence 2-2
2.2 SUMMARY OF USR FUNCTIONS 2-3
2.2.1 FETCH Device Handler 2-4
2.2.2 LOOKUP Permanent File 2-6
2.2.3 ENTER Output (Tentative) File 2-7
2.2.4 The CLOSE Function 2-8
2.2.5 Call Command Decoder (DECODE) 2-10
2.2.6 CHAIN Function 2-10
2.2.7 Signal User Error 2-12
2.2.8 Lock USR in Core (USRIN) 2-13
2.2.9 Dismiss USR from Core (USROUT) 2-13
2.2.10 Ascertain Device Information (INQUIRE) 2-14
2.2.11 RESET System Tables 2-15
CHAPTER 3 THE COMMAND DECODER 3-1
3.1 COMMAND DECODER CONVENTION 3-1
3.2 COMMAND DECODER ERROR MESSAGES 3-3
3.3 CALLING THE COMMAND DECODER 3-3
3.4 COMMAND DECODER TABLES 3-4
3.4.1 Output Files 3-5
3.4.2 Input Files 3-5
3.4.3 Command Decoder Option Table 3-6
3.4.4 Example 3-7
iv
Page
3.5 SPECIAL MODE OF THE COMMAND DECODER 3-10
3.5.1 Calling the Command Decoder Special Mode 3-10
3.5.2 Operation of the Command Decoder in Special
Mode 3-10
3.6 CCL AND THE COMMAND DECODER 3-11
3.7 USEFUL LOCATIONS IN BATCH 3-11
3.8 CCL TABLES 3-12
CHAPTER 4 USING DEVICE HANDLERS 4-1
4.1 CALLING DEVICE HANDLERS 4-1
4.2 DEVICE DEPENDENT OPERATIONS 4-4
4.2.1 Teletype (TTY) 4-4
4.2.2 High-Speed Paper Tape Reader (PTR) 4-4
4.2.3 High-Speed Paper Tape Punch (PTP) 4-5
4.2.4 Line Printer (LPT) 4-5
4.2.5 Cassettes 4-7
4.2.6 Card Reader (CDR) 4-8
4.2.7 TM8E Handler 4-8
4.2.8 File Structured Devices 4-12
4.2.9 TD8E DECtape 4-12
4.2.10 KL8E Teletype Handler 4-13
CHAPTER 5 RECONFIGURING THE OS/8 SYSTEM 5-1
5.1 WRITING DEVICE HANDLERS 5-1
5.2 INSERTING DEVICE HANDLERS INTO OS/8 5-5
APPENDIX A OS/8 FILE STRUCTURES A-1
A.1 FILE DIRECTORIES A-1
A.1.1 Directory Entries A-2
A.1.2 Number and Size of 05/8 Files A-3
A.1.3 Sample Directory A-3
A.2 FILE FORMATS A-4
A.2.1 ASCII and Binary Files A-4
A.2.2 Core Image (.SV format) Files A-5
A.2.3 Relocatable FORTRAN Library File A-8
APPENDIX B DETAILED LAYOUT OF THE SYSTEM B-1
B.1 LAYOUT OF THE SYSTEM DEVICE B-1
B.2 LAYOUT OF THE OS/8 RESIDENT PROGRAM B-3
B.3 SYSTEM DEVICE TABLES B-5
B.3.1 Permanent Device Name Table B-5
v
Page
B.3.2 User Device Name Table B-6
B.3.3 Device Handler Residency Table B-6
B.3.4 Device Handler Information Table B-6
B.3.5 Device Control Word Table B-7
B.3.6 Device Length Table B-8
APPENDIX C SYSTEM ERROR CONDITIONS AND MESSAGES C-1
C.1 SYSTEM HALTS C-1
C.2 USR ERRORS C-2
C.3 KEYBOARD MONITOR ERRORS C-3
C.4 CCL ERROR MESSAGES C-4
C.5 COMMAND DECODER ERRORS C-7
APPENDIX D PROGRAMMING NOTES D-1
D.1 THE DEFAULT FILE STORAGE DEVICE, DSK D-1
D.2 MODIFICATION TO CARD READER HANDLER D-2
D.3 SUPPRESSION OF CARRIAGE RETURN/LINE FEED
IN FORTRAN D-4
D.4 ACCESSING THE SYSTEM DATE IN A FORTRAN
PROGRAM D-4
D.5 DETERMINING CORE SIZE ON PDP-8 FAMILY
COMPUTERS D-5
D.6 USING PRTC12-F TO CONVERT OS/8 DECTAPES
TO OS/12 LINCTAPES D-6
D.7 NOTES ON LOADING DEVICE HANDLERS D-7
D.7.1 Problem with Multiple Input Files D-7
D.7.2 Dynamically Loading Device Handlers D-8
D.8 AVAILABLE LOCATIONS IN THE USR AREA D-9
D.9 ACCESSING ADDITIONAL INFORMATION WORDS
IN OS/8 D-9
D.9.1 After a LOOKUP or ENTER D-9
D.9.2 After a CLOSE D-10
D.9.3 Rewriting the Current Directory Segment D-10
D.10 SABR PROGRAMMING NOTES D-11
D.10.1 Optimizing SABR Code D-11
D.10.2 Calling the USR and Device Handlers from
SABR Code D-13
vi
Page
APPENDIX E CHARACTER CODES AND CONVENTIONS E-1
APPENDIX F OS/8 INPUT/OUTPUT ROUTINES F-1
F.1 GENERAL DESCRIPTION F-1
F.2 SUBROUTINE FUNCTIONS F-1
F.3 SUBROUTINE PARAMETERS F-3
F.3.1 Example F-4
F.3.2 Subroutine Listing F-5
INDEX I-1
vii
CHAPTER 1
OS/8 CONCEPTS AND TERMINOLOGY
Before examining the details of the OS/8 system, the reader should
first be familiar with the simpler techniques and terms used within
the framework of the OS/8 system. The material in this chapter, along
with that contained in the OS/8 HANDBOOK, provides the tools needed to
pursue the later chapters.
1.1 SOFTWARE COMPONENTS OF OS/8
There are four main components of the OS/8 system:
1. The Keyboard Monitor performs commands specified by the user
at the keyboard console. The nine Keyboard Monitor commands
(ASSIGN, DEASSIGN, GET, SAVE, ODT, RUN, R, START, and DATE)
are explained in Chapter 1 of the OS/8 HANDBOOK.
User programs can exit to the Keyboard Monitor by executing a
JMP to location 7600 in field 0. All JMPs to 7600 must be
made with the DATA FIELD set to zero. This saves the
contents of locations 0000 to 1777 in field 0 and loads the
Keyboard Monitor which could be called by a JMP to location
7605 in field 0. In this latter case the contents of core are
not saved, which conserves some time.
Existing system programs, device handlers, and the Command
Decoder test for the CTRL/C character in the terminal input
buffer and, on finding this character, abort the current
operation and perform a JMP to 7600 in field 0. Thus, typing
CTRL/C is the conventional method of calling the Keyboard
Monitor from the console.
2. Device handlers, which are subroutines for performing all
device-oriented input/output operations, can be utilized by
any program. These subroutines have standard calling
sequences and "mask" from the user program the special
characteristics of the I/O device. In this way, device
independent I/O is achieved. A detailed description of
device handlers is found in Chapter 4.
3. The User Service Routine (USR) is to a program what the
Keyboard Monitor is to the user. For example, programs can
request the USR to fetch device handlers, perform file
operations on any device, chain to another program, or call
the Command Decoder. A full description of the USR functions
is found in Chapter 2.
1-1
OS/8 CONCEPTS AND TERMINOLOGY
4. The Command Decoder interprets a command line typed by the
user to indicate input and output files and various options.
The command line format is described in detail in Chapter 1
of the OS/8 HANDBOOK. The Command Decoder removes the burden
of this repetitive operation from the user's program. A full
description of the Command Decoder's function is found in
Chapter 3.
5. Two other components, ABSLDR and ODT, are not logically part
of the OS/8 system. However, in the sources and listings,
ABSLDR is combined with the Keyboard Monitor and USR. ODT is
combined with the command decoder.
1.2 FILES
Files are basic units of the OS/8 system, and a thorough understanding
of file structure is required for its use. A file is any collection
of data to be treated as a unit. The format of this data is
unimportant; for example, OS/8 can manipulate several standard
formats, including ASCII files, binary files, and core image files.
The important consideration is that the data forms a single unit
within the system.
1.2.1 File Names and Extensions
An individual file is identified by its file name and extension. The
file name consists of up to six alphanumeric characters, optionally
followed by a two character extension. The extension is often used to
clarify the format of the data within the file. For example, an ASCII
file used as input to PAL8 might be given a PA extension, while a core
image file has a SV extension.
1.2.2 File Structured Devices
Devices that can be logically divided into a number of 256-word blocks
and have the ability to read and write from any desired block are
called file structured devices. Disks and DECtapes are file
structured devices while a paper tape reader or terminal is not.
Cassettes and magnetic tapes form an intermediate case. They may be
treated directly as non-file structured devices, or the program MCPIP
may appear to be file structured.
The system device (SYS) in any OS/8 system is always file structured,
as is the default storage device, DSK.
All OS/8 file structured devices must be logically divided into these
256-word blocks. Hence, 256 words is considered the standard OS/8
1-2
OS/8 CONCEPTS AND TERMINOLOGY
block size. Some devices, like RK8, DECtape, and LINCtape, are
physically divided into blocks. These physical blocks should not be
confused with the logical 256-word blocks. For example, DECtapes must
be formatted with standard 129-word physical blocks. A logical OS/8
block consists of the first 128 words of two consecutive physical
DECtape blocks. The 129th word of every DECtape block is not used by
OS/8. Similarly, LINCtapes are formatted with 129 (or 128) words per
block but never 256, as this format is unacceptable to OS/8.
A given OS/8 file consists of one or more sequential blocks of 256
words each (consecutively numbered). A minimum of one block per file
is required, although a single file could occupy all of the blocks on
a device.
1.2.3 File Types
Three different types of files exist in the OS/8 system:
1. An "empty file" is a contiguous area of unused blocks. Empty
files are created when permanent files are deleted.
2. A "tentative file" is a file that is open to accept output
and has not yet been closed. Only one tentative file can be
open on any single device at one time.
3. A "permanent file" is a file that has been given a fixed size
and is no longer expandable. A tentative file becomes
permanent when it is closed.
To further understand file types, consider what occurs when a file is
created. Normally, the User Service Routine, in creating a tentative
file, first locates the largest empty file available and creates a
tentative file in that space. This establishes the maximum space into
which the file can expand. The user program then writes data into the
tentative file. At the end of the data, the program calls the USR to
close the tentative file, making it a permanent file. The USR does so
and allocates whatever space remains on the end of the tentative file
to a new, smaller, empty file.
1.2.4 File Directories and Additional Information Words
To maintain records of the files on a device, OS/8 allocates blocks 1
through 6 of each file structured device as the file directory.
Entries in this directory inform the system of the name, size, and
location of each file, including all empty files and the tentative
file, if one exists. For a detailed description of the entries in the
file directory, see Appendix A.
Each entry in a directory can, optionally, have extra storage words
called Additional Information Words. The number of Additional
1-3
OS/8 CONCEPTS AND TERMINOLOGY
Information Words is determined at the time the directory is initially
created (normally by using the /S or /Z features of PIP; see Chapter
1 of the OS/8 HANDBOOK.
Whenever Additional Information Words are used, the first one for each
file entry is used to store the value of the System Date Word at the
time the file was created. OS/8 automatically uses one extra word per
entry for the date. This value is set by executing a DATE command
(see Chapter 1 of the OS/8 HANDBOOK) which codes the current date into
memory location 07666 in the following format:
0 3 4 8 9 11
+---------+----------+----------+
| | | |
+---------+----------+----------+
MONTH DAY YEAR-1970
(1-14(8)) (1-37(8)) (0-7)
A date word of 0 implies that no DATE command has been executed since
the system initialization.
The values of Additional Information Words beyond the first are
user-defined. See Appendix D for further information on Additional
Information Words.
1.3 CORE CONTROL BLOCK
Associated with each core image file (SV file) is a block of data
called the Core Control Block. The Core Control Block is a table of
information containing the program's starting address, areas of core
into which the program is loaded, and the program's Job Status Word.
The Core Control Block is created at the time the program is loaded by
ABSLDR or other means and is written onto the SV file by the SAVE
operation. More information on the Core Control Block can be found in
the description of core image files in section A.2.2. Note that
specifying arguments to the SAVE command as described in Chapter 1 of
the OS/8 HANDBOOK, can alter the contents of the target program's Core
Control Block.
When a program is loaded, the starting address and Job Status Word are
read from the Core Control Block and saved in core. The Core Control
Block itself is saved in the last 200 (octal) words of block 37 on the
system device unless the program was loaded with the R (rather than
GET or RUN) command.
1-4
OS/8 CONCEPTS AND TERMINOLOGY
1.3.1 Program Starting Address
The current starting address (used by the START command) is stored in
two words at locations 07744 and 07745. The format of these words is:
LOCATION CONTENTS NOTES
________ ________ _____
07744 62n3 n is the field in
which to start.
07745 nnnn Starting address of
the program.
1.3.2 Job Status Word
The Job Status Word contains certain flags that affect OS/8
operations, such as whether to save core when loading the USR or
Command Decoder. The Job Status Word for the program currently in
core is saved at location 07746 and contains the following
information:
Bit Condition Meaning
_____________ _______
Bit 0 = 1 File does not load into locations 00000
to 01777.
Bit 1 = 1 File does not load into locations 00000
to 01777.
Bit 2 = 1 Program must be reloaded before it can
be restarted.
Bit 3 = 1 Program does not destroy the contents of
the highest existing memory field, an
optimization for the Batch system.
Bits 4 thru 9 Reserved for future use.
Bit 10 = 1 Locations 00000 to 01777 need not be
saved when calling the Command Decoder.
Bit 11 = 1 Locations 10000 to 11777 need not be
saved when calling the USR.
When bit 2 of the Job Status Word is 1, any attempt to perform a START
(without an explicit address) results in a
NO!!
error message being printed. As this bit is always zero in the Core
Control Block, the user program is expected to internally set this bit
(in location 7746) if a program is not restartable. This could be
1-5
OS/8 CONCEPTS AND TERMINOLOGY
done as follows:
CDF 0
TAD I (7746 /LOAD JOB STATUS WORD
AND (6777
TAD (1000
DCA I (7746 /JOB IS NOT RESTARTABLE
The Job Status Word can be updated from the user's program or with the
ABSLDR /P option, thus providing optimization of tape (disk) motion.
More information on the Core Control Block can be found in the
description of Core Image (SV) files found in Appendix A.
Bit 3 of the JSW (Job Status Word) is used as an optimization for the
Batch operating system. If a program can never cause the highest
existing memory field to be altered, this bit should be set. For
example, EDIT, PIP, FORT, and SABR can never use memory above 8K.
Thus, they should set bit 3 of the JSW. Programs such as ABSLDR,
LOADER, PAL8 and CREF can alter all of core. They should perhaps not
have bit 3 on. Note that the more core that exists, the more unlikely
it is that a program will destroy upper core. Thus, on 28K systems,
only the largest FORTRAN programs can alter field 6 and, in general,
bit 3 should be set.
1.3.3 Software Core Size
Location 07777 contains the software core size in bits 6-8. This
represents the highest memory field available for use by OS/8. If bits
6-8 contain 0, all of the available memory is used. Most OS/8 cusps
interrogate this word to determine how much memory is available. The
other bits of this location are reserved for use by BATCH and should
not be touched by user programs.
1.4 DEVICE NAMES AND DEVICE NUMBERS
The OS/8 system can accommodate up to 15 separate devices. In Chapter
1 of the OS/8 HANDBOOK the reader is introduced to the concept of
device names. Briefly, each device on the system is recognized by
either a permanent device name (such as PTR or DTAl) which is created
when the system is built, or a user-defined device name determined by
an ASSIGN command. The system insures that the user-defined device
name takes precedence. For example,
.ASSIGN DSK DTA4
causes all future references to DTA4 to address the device DSK.
In calling the User Service Routine, a device can be alternatively
recognized by a device number. Each device on the system has a unique
predefined number in the range 1 to 17 (octal) assigned at the time
1-6
OS/8 CONCEPTS AND TERMINOLOGY
the system is generated. Thus, user programs have the choice of
referring to a device by either name or number. Referencing a device
by name is preferable, as it maintains device independence for the
program.
Accessing devices by number should be done only when the appropriate
number has been obtained from a USR INQUIRE CALL. Except for SYS and
DSK, the 05/8 peripherals do not have fixed numbers; instead, device
numbers vary whenever BUILD is used to modify a system. Thus, it is
suggested that reference by name be used whenever possible.
To determine whether a device name is recognized in the system,
attempt to ASSIGN that device. For example, to determine whether
LINCtape handlers are called LTA or DTA, perform:
.DEASSIGN
.AS LTA0
If the system responds with a dot (.), LTA0 does indeed exist. If the
system responds with:
LTA0 NOT AVAILABLE
no device named LTA0 is present.
1.5 THE DEVICE AND FILENAME PSEUDO-OPS
Several of the USR functions take device names or file names as
arguments. To simplify the task of generating these arguments, the
DEVICE and FILENAME pseudo-ops have been added to the PAL8 Assembler.
A device name consists of a two word block, containing four
alphanumeric characters in six-bit ASCII format. A block in this
format can be created by the DEVICE pseudo-op as follows:
DEVICE DTA1
generates the following two words:
0424
0161
similarly, the FILENAME pseudo-op creates a four word block, the first
three words of which contain the file name and the fourth word of
which contains the file extension. For example:
FILENAME PIP.SV
generates the following four words:
1-7
OS/8 CONCEPTS AND TERMINOLOGY
2011
2000
0000
2326
Note that positions for characters 4 through 6 are filled with zeros.
The DEVICE and FILENAME pseudo-ops are used in examples in the
following chapters.
1-8
CHAPTER 2
USER SERVICE ROUTINE
The User Service Routine, or USR, is a collection of subroutines which
perform the operations of opening and closing files, loading device
handlers, program chaining, and calling the Command Decoder. The USR
provides these functions not only for the system itself, but for all
programs running under the OS/8 system.
2.1 CALLING THE USR
Performing any USR function is as simple as giving a JMS followed by
the proper arguments. Calls to the USR take a standardized calling
sequence. This standard call should be studied before progressing to
the operation of the various USR functions.
2.1.1 Standard USR Call
In the remainder of this chapter, the following calling sequence is
referenced:
TAD VAL The contents of the AC is applicable in
some cases only.
CDF N Where N is the value of the current
program field multiplied by 10 (octal).
CIF 10
JMS I (USR Where USR is either 7700 or 0200, (see
section 2.1.2).
FUNCTION This word contains an integer from 1 to
13 (octal) indicating which USR
operation is to be performed.
ARG(l) The number and meaning of these argument
words varies with the particular USR
function to be performed.
error return When applicable, this is the return
address for all errors.
normal return The operation was successful. The AC is
cleared and the data field is set to
current field.
2-1
USER SERVICE ROUTINE
This calling sequence can change from function to function. For
example, some functions take no value in the AC and others have fewer
or greater numbers of arguments. Nonetheless, this format is
generally followed.
The value of the data field preceding the JMS to the USR is
exceedingly important. The data field MUST be set to the current
field, and the instruction field MUST be set to 1. Note that a CDF is
not explicitly required if the data field is already correct. When a
doubt exists as to the data field setting, an explicit CDF should be
executed.
There are three other restrictions which apply to all USR calls, as
follows:
1. The USR can never be called from any address between 10000
and 11777. Attempting to do so results in the:
MONITOR ERROR 4 AT xxxxx (ILLEGAL USR CALL)
message and termination of program execution. The value of
xxxxx is the address of the calling sequence (in all such
MONITOR ERROR messages).
2. Several USR calls take address pointers as arguments. These
pointers always refer to data in the same memory field as the
call.
3. When calling the USR from field 1, these address pointers
must never refer to data that lies in the area 10000 to
11777.
2.1.2 Direct and Indirect Calling Sequence
A user program can call the USR in two ways. First, by performing a
JMS to location 17700 In this case, locations 10000 to 11777 are saved
on a special area on the system device, and the USR is then loaded
into 10000 to 11777. When the USR operation is completed, locations
10000 to 11777 are restored to their previous values.
NOTE
By setting bit 11 of the Job Status Word
to a 1, the user can avoid this saving
and restoring of core when preserving
core is unnecessary.
Alternatively, a program can opt to keep the USR permanently resident
in core at locations 10000 to 11777 by using the USRIN function (see
section 2.2.8). Once the USR has been brought into core, a USR call
can be made by performing a JMS to location 10200. This is the most
efficient way of calling the USR. When USR operations have been
2-2
USER SERVICE ROUTINE
completed, the program restores locations 10000 to 11777 to their
initial state by executing the USROUT function, if necessary (see
section 2.2.9).
2.2 Summary of USR Functions
Function
Code Name Operation
________ ____ _________
1 FETCH Loads a device handler into core.
Returns the entry address of the
handler.
2 LOOKUP Searches the file directory on any
device to locate a specified permanent
file.
3 ENTER Creates and opens for output a tentative
file on a specified device.
4 CLOSE Closes the currently open tentative file
on the specified device and becomes a
permanent file. Also, any previous
permanent file with the same file name
and extension is deleted.
5 DECODE Calls the Command Decoder. The function
of the Command Decoder is described in
Chapter 3.
6 CHAIN Loads a specified core image file from
the system device and starts it.
7 ERROR Prints an error message of the form USER
ERROR n AT LOCATION xxxxx.
10 USRIN Loads the USR into core. Subsequent
calls to the USR are by an effective JMS
to location 10200.
11 USROUT Dismisses the USR from core and restores
the previous contents of locations 10000
to 11777.
12 INQUIRE Ascertains whether a given device exists
and, if so, whether its handler is in
core.
13 RESET Resets system tables to their initial
cleared state.
14-17 Not currently used, these request
numbers are reserved for future use.
2-3
USER SERVICE ROUTINE
An attempt to call the USR with a code greater than 13 (octal) will
currently cause a Monitor Error 4 message to be printed and the
program to be aborted.
2.2.1 FETCH Device Handler Function Code = 1
Device handlers must be loaded into core so as to be available to the
USR and user program for I/O operations on that device. Before
performing a LOOKUP, ENTER, or CLOSE function on any device, the
handler for that device must be loaded by FETCH.
The FETCH function takes two distinct forms:
1. Load a device handler corresponding to a given device name.
2. Load a device handler corresponding to a given device number.
First, the following is an example of loading a handler by name from
memory field 0:
CLA /AC MUST BE CLEAR
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
1 /FUNCTION CODE = 1
DEVICE DTA3 /GENERATES TWO WORDS: ARG(1)
/AND ARG(2)
6001 /ARG(3)
JMP ERR /ERROR RETURN
. /NORMAL RETURN
.
.
ARG(1) and ARG(2) contain the device name in standard format. If the
normal return is taken, ARG(2) is changed to the device number
corresponding to the device loaded. ARG(3) contains the following
information:
Bits 0 to 4 contain the page number into which the handler is
loaded.
Bit 11 is 0 if the user program can only accept a 1-page
handler.
Bit 11 is 1 if there is room for a 2-page handler.
Notice that in the example above, the handler for DTA3 is to be loaded
into locations 6000 to 6177. If necessary, a two page handler could be
loaded; the second page would be placed in locations 6200 to 6377.
After a normal return, ARG(3) is changed to contain the entry point of
the handler.
2-4
USER SERVICE ROUTINE
A different set of arguments is used to fetch a device handler by
number. The following is an example of this form:
TAD VAL /AC IS NOT ZERO
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
1 /FUNCTION CODE = 1
6001 /ARG(1)
JMP ERR /ERROR RETURN
. /NORMAL RETURN
.
.
On entry to the USR, the AC contains the device number in bits 8 to 11
(bit 0 to 7 are ignored). The format for ARG(1) is the same as that
for ARG(3) in the previous example. Following a normal return ARG(1)
is replaced with the entry point of the handler.
The conditions that can cause an error return to occur in both cases
are as follows:
1. There is no device corresponding to the given device name or
device number, or
2. An attempt was made to load a two page handler into one page.
If this is an attempt to load the handler by name, the
contents of ARG(2) have been changed already to the internal
device number.
In addition, one of the following Monitor errors can be printed,
followed by a return to the Keyboard Monitor:
Error Message Meaning
_____________ _______
MONITOR ERROR 4 AT xxxxx Results if bits 8 to 11 of the AC
(ILLEGAL USR CALL) are zero (and bits 0 to 7 are
non-zero).
MONITOR ERROR 5 AT xxxxx Results if a read error occurs
(I/O ERROR ON SYS) while loading the device handler.
The FETCH function checks to see if the handler is in core, and if it
is not, then the handler and all co-resident handlers are loaded.
While the FETCH operation is essentially a simple one, the user should
be aware of the following points:
1. Device handlers are always loaded into memory field 0.
2. The entry point that is returned may not be on the page
desired. This would happen if the handler were already
resident.
3. Never attempt to load a handler into the 7600 page or into
page 0. Never load a two page handler into the 7400 page.
2-5
USER SERVICE ROUTINE
For more information on using device handlers, see Chapter 4.
NOTE
Two or more device handlers are
"co-resident" when they are both
included in the same one or two core
pages. For example, the paper tape
reader and punch routines are
co-resident, as are the eight DECtape
handler routines.
2.2.2 LOOKUP Permanent file Function Code = 2
This request locates a permanent file entry on a given device, if one
exists. An example of a typical LOOKUP would be:
TAD VAL /LOAD DEVICE NUMBER
CDF 0 /DF=CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
2 /FUNCTION CODE = 2
NAME /ARG(1), POINTS TO FILE NAME
O /ARG(2)
JMP ERR /ERROR RETURN
. /NORMAL RETURN
NAME, FILENAME PROG.PA
This request looks up a permanent file entry with the name PROG.PA.
The device number on which the lookup is to be performed is in AC bit
8 to 11. ARG(1) contains a pointer to the file name. Note that the
file name block must be in the same memory field as the call, and that
it cannot be in locations 10000 to 11777. The device handler must have
been previously loaded into core. If the normal return is taken,
ARG(l) is changed to the starting block of the file and ARG(2)
contains the file length in blocks as a negative number. If the
device specified is a readable, non-file structured device (for
example, the papertape reader), then ARG(1) and ARG(2) contain the
file length in blocks as a negative number. If the device specified
is a readable, non-file structured device (for example, the paper tape
reader), then ARG(1) and ARG(2) are both set to zero.
If the error return is taken, ARG(1) and ARG(2) are unchanged. The
following conditions cause an error return:
1. The device specified is a write-only device.
2. The file specified was not found.
In addition, specifying illegal arguments can cause one of the
following monitor errors, followed by a return to the Keyboard
Monitor:
2-6
USER SERVICE ROUTINE
Error Message Meaning
_____________ _______
MONITOR ERROR 2 AT xxxxx Results if an I/O error occurred
(DIRECTORY I/O ERROR) while reading the device directory.
MONITOR ERROR 3 AT xxxxx Results if the device handler for
(DEVICE HANDLER NOT IN CORE) the specified device is not in
core.
MONITOR ERROR 4 AT xxxxx Results if bits 8 to 11 of the AC
(ILLEGAL USR CALL) are zero.
The LOOKUP function is the standard method of opening a permanent file
for input.
2.2.3 ENTER Output (Tentative) File Function Code = 3
The ENTER function is used to create a tentative file entry to be used
for output. An example of a typical ENTER function is as follows:
TAD VAL /AC IS NOT ZERO
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
3 /FUNCTION CODE = 3
NAME /ARG(1) POINTS TO FILE NAME
0 /ARG(2)
JMP ERROR /ERROR RETURN
. /NORMAL RETURN
.
.
NAME, FILENAME PROG.LS
Bits 8 to 11 of the AC contain the device number of the selected
device; the device handler for this device must be loaded into core
before performing an ENTER function. If bits 0 to 7 of the AC are
non-zero, this value is considered to be a declaration of the maximum
length of the file. The ENTER function searches the file directory
for the smallest empty file that contains at least the declared number
of blocks. If bits 0 to 7 of the AC are zero, the ENTER function
locates the largest available empty file.
On a normal return, the contents of ARG(1) are replaced with the
starting block of the file. The 2's complement of the actual length
of the created tentative file in blocks (which can be equal to or
greater than the requested length) replaces ARG(2). If the file
directory contains any Additional Information Words, the system DATE
(location 17666) is written as the first Additional Information Word
of the newly created tentative file at this time.
2-7
USER SERVICE ROUTINE
NOTE
If the selected device is not file
structured but permits output operations
(e.g., the high speed punch), the ENTER
operation always succeeds. In this
case, ARG(l) and ARG(2) are both zeroed
on return.
If the error return is taken, ARG(1) and ARG(2) are unchanged. The
following conditions cause an error return:
1. The device specified by bits 8 to 11 of the AC is a read only
device.
2. No empty file exists which satisfies the requested length
requirement.
3. Another tentative file is already active on this device (only
one output file can be active at any given time).
4. The first word of the file name was 0 (an illegal file name).
In addition, one of the following monitor errors can occur, followed
by a return to the Keyboard Monitor:
Error Message Meaning
_____________ _______
MONITOR ERROR 2 AT xxxxx Result if an I/O error occurred
(DIRECTORY I/O ERROR) while reading or writing the device
directory.
MONITOR ERROR 3 AT xxxxx Results if the device handler for
(DEVICE HANDLER NOT IN CORE) the specified device is not in
core.
MONITOR ERROR 4 AT xxxxx Results if AC bits 8 to 11 are
(ILLEGAL USR CALL) zero.
MONITOR ERROR 5 AT xxxxx Read error on the system device
(I/O ERROR ON SYS) while bringing in the overlay code
for the ENTER function.
MONITOR ERROR 6 AT xxxxx Results if a directory overflow
(DIRECTORY OVERFLOW) occurred (no room for tentative
file entry in directory).
2.2.4 The CLOSE Function Function Code = 4
The CLOSE function has a dual purpose: first, it is used to close the
current active tentative file, making it a permanent file. Second,
when a tentative file becomes permanent it is necessary to remove any
2-8
USER SERVICE ROUTINE
permanent file having the same name; this operation is also performed
by the CLOSE function. An example of CLOSE usage follows:
TAD VAL /GET DEVICE NUMBER
CDF 0 /DF=CURRENT FIELD
CIF 10 /IF=1
JMS I (USR
4 /FUNCTION CODE = 4
NAME /ARG(1)
15 /ARG(2)
JMP ERR /ERROR RETURN
. /NORMAL RETURN
.
NAME, FILENAME PROG.LS
The device number is contained in AC bits 8 to 11 when calling the
USR. ARG(1) is a pointer to the name of the file to be deleted and
ARG(2) contains the number of blocks to be used for the new permanent
file.
The normal sequence of operations on an output file is:
1. FETCH the device handler for the output device.
2. ENTER the tentative file on the output device, getting the
starting block and the maximum number of blocks available for
the file.
3. Perform the actual output using the device handler, keeping
track of how many blocks are written, and checking to insure
that the file does not exceed the available space.
4. CLOSE the tentative file, making it permanent. The CLOSE
operation would always use the same file name as the ENTER
performed in step 2. The closing file length would have been
computed in step 3.
After a normal return from CLOSE, the active tentative file is
permanent and any permanent file having the specified file name
already stored on the device is deleted. If the specified device is a
non-file structured device that permits output (the paper tape punch,
for example) the CLOSE function will always succeed.
NOTE
The user must be careful to specify the
same file names to the ENTER and the
CLOSE functions. Failure to do so can
cause several permanent files with
identical names to appear in the
directory. If CLOSE is intended only to
be used to delete some existing file,
then the number of blocks, ARG(2) should
be zero.
2-9
USER SERVICE ROUTINE
The following conditions cause the error return to be taken:
1. The device specified by bits 8 to 11 of the AC is a read only
device.
2. There is neither an active tentative file to be made into a
permanent file, nor a permanent file with the specified name
to be deleted.
In addition, one of the following Monitor errors can occur:
Error Message Meaning
_____________ _______
MONITOR ERROR 1 AT xxxxx Results if the length specified by
(CLOSE,ERROR) ARG(2) exceeded the allotted space.
MONITOR ERROR 2 AT xxxxx Results if an I/O error occurred
(DIRECTORY I/O ERROR) while reading or writing the device
directory.
MONITOR ERROR 3 AT xxxxx Results if the device handler for
(DEVICE HANDLER NOT IN CORE) the specified device is not in
core.
MONITOR ERROR 4 AT xxxxx Results if AC bits 8 to 11 are
(ILLEGAL USR CALL) zero.
2.2.5 Call Command Decoder (DECODE) Function Code = 5
The DECODE function causes the USR to load and execute the Command
Decoder. The Command Decoder accepts (from the Teletype) a list of
input and output devices and files, along with various options. The
Command Decoder performs a LOOKUP on all input files, sets up
necessary tables in the top page of field 1, and returns to the user
program. These operations are described in detail in Chapter 3, which
should be read before attempting to use the DECODE function.
A typical call to the Command Decoder looks as follows:
CDF 0 /DF=CURRENT FIELD
CIF 10 /IF=1
JMS I (USR
5 /FUNCTION CODE = 5
2001 /ARG(1), ASSUMED INPUT EXTENSION
0 /ARG(2), ZERO TO PRESERVE ALL
/TENTATIVE FILES
. /NORMAL RETURN
.
.
ARG(1) is the assumed input extension, in the preceding example it is
2-10
USER SERVICE ROUTINE
".PA". On return from the Command Decoder, information is stored in
tables located in the top page of memory field 1. The DECODE function
also resets all system tables as in the RESET function (see RESET
function, section 2.2.11) if ARG(2) is 0 all currently active
tentative files remain open; if ARG(2) is non-zero all tentative
files are deleted and the normal return is to ARG(2) instead of
ARG(2)+1.
The DECODE function has no error return (Command Decoder error
messages are given in Chapter 3). However, the following Monitor error
can occur:
Error Message Meaning
_____________ _______
MONITOR ERROR 5 AT xxxxx I/O error occurred while reading or
(I/O ERROR ON SYS) writing on the system device.
2.2.6 CHAIN Function Function Code = 6
The CHAIN function permits a program to load and start another program
with the restriction that the program chained to must be a core image
(.SV) file located on the system device. A typical implementation of
the CHAIN function looks as follows:
CDF 0 /DF=CURRENT FIELD
CIF 10 /IF=1
JMS I (USR
6 /FUNCTION CODE = 6
BLOCK /ARG(1), STARTING BLOCK NUMBER
There is no normal or error return from CHAIN. However, the following
monitor error can occur:
Error Message Meaning
_____________ _______
MONITOR ERROR 5 AT xxxxx I/O error occurred while reading or
(I/O ERROR ON SYS) writing on the system device.
CHAIN ERR If an attempt is made to CHAIN to a
file which is not a core image
(.SV) file. Control returns to the
keyboard monitor.
The CHAIN function loads a core image file located on the system
device beginning at the block number specified as ARG(1) (which is
normally determined by performing a LOOKUP on the desired file name).
Once loaded, the program is started at an address one greater than the
starting address specified by the program's Core Control Block.
CHAIN automatically performs a USROUT function (see section 2.2.9) to
dismiss the USR from core, and a RESET to clear all system tables see
section 2.2.11), but CHAIN does not delete tentative files.
2-11
USER SERVICE ROUTINE
The areas of core altered by the CHAIN function are determined by the
contents of the Core Control Block of the core image file loaded by
CHAIN. The Core Control Block for the file is set up by other ABSLDR
or LOADER programs. It can be modified by performing a SAVE command
with specific arguments. Every page of core in which at least one
location was saved is loaded. If the page is one of the "odd
numbered" pages (pages 1, 3, etc.; locations 0200 to 0377, 0600 to
0777, etc.), the previous page is always loaded. In addition, CHAIN
always alters the contents of locations 07200 to 07577.
NOTE
CHAIN destroys a necessary part of the
ODT resident breakpoint routine. Thus
an ODT breakpoint should never be
maintained across a CHAIN.
With the above exceptions, programs can pass data back and forth in
core while chaining. For example, FORTRAN programs normally leave the
COMMON area in memory field 1 unchanged. This COMMON area can then be
accessed by the program activated by the CHAIN.
2.2.7 Signal User ERROR Function Code = 7
The USR can be called to print a user error message for a program.
The following is a possible ERROR call:
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
7 /FUNCTION CODE = 7
2 /ARG(1), ERROR NUMBER
The ERROR function causes a message of the form:
USER ERROR n AT xxxxx
to be printed. Here n is the error number given as ARG(1); n must be
between 0 and 11 (octal), and xxxxx is the address of ARG(1). If
ARG(1) in the sample call above were at location 500 in field 0, the
message:
USER ERROR 2 AT 00500
would be printed. Following the message, the USR returns control to
the Keyboard Monitor, preserving the user program intact.
The error number is arbitrary. Two numbers have currently assigned
meanings:
2-12
USER SERVICE ROUTINE
Error Message Meaning
_____________ _______
USER ERROR 0 AT xxxxx During a RUN, GET, or R command,
this error message indicates that
an error occurred while loading the
core image.
USER ERROR 1 AT xxxxx While executing a FORTRAN or SABR
program, this error indicates that
a call was made to a subroutine
that was not loaded.
2.2.8 Lock USR in Core (USRIN) Function Code = 10
When making a number of calls to the USR it is advantageous for a
program to avoid reloading the USR each time a USR call is made. The
USR can be brought into core and kept there for subsequent use by the
USRIN function. The calling sequence for the USRIN function looks as
follows:
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (7700
10 /FUNCTION CODE = 10
. /NORMAL RETURN
.
.
THE USRIN function saves the contents of locations 10000 to 11777 on
the system scratch blocks, provided the calling program loads into
this area as indicated by the current JSW, and loads the USR, then
returns control to the user program.
NOTE
If bit 11 of the current Job Status Word
is a one, the USRIN function will not
save the contents of locations 10000
thru 11777.
2.2.9 Dismiss USR from Core (USROUT) Function Code = 11
When a program has loaded the USR into core with the USRIN function
and no longer wants or needs the USR in core, the USROUT function is
used to restore the original contents of locations 10000 to 11777. The
calling sequence for the USROUT function is as follows:
2-13
USER SERVICE ROUTINE
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (200 /DO NOT JMS TO 17700!!
11 /FUNCTION CODE = 11
. /NORMAL RETURN
.
.
The USROUT function and the USRIN function are complementary
operations. Subsequent calls to the USR must be made by performing a
JMS to location 7700 in field 1.
NOTE
If bit 11 of the current Job Status Word
is a 1, the contents of core are not
changed by the USROUT function. In this
case USROUT is a redundant operation
since core was not preserved by the
USRIN function.
2.2.10 Ascertain Device Information (INQUIRE) Function Code = 12
On some occasions a user may wish to determine what internal device
number corresponds to a given device name or whether the device
handler for a specified device is in core, without actually performing
a FETCH operation. INQUIRE performs these operations for the user.
The function call for INQUIRE closely resembles the FETCH handler
call.
INQUIRE, like FETCH, has two distinct forms:
1. Obtain the device number corresponding to a given device name
and determine if the handler for that device is in core
(example shown below).
2. Determine if the handler corresponding to a given device
number is in core.
An example of the INQUIRE call is shown below:
CLA /AC MUST BE CLEAR
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
12 /FUNCTION CODE = 12
DEVICE DTA3 /GENERATES TWO WORDS:
/ARG(1) AND ARG(2)
0 /ARG(3)
JMP ERR /ERROR RETURN
. /NORMAL RETURN
.
.
2-14
USER SERVICE ROUTINE
ARG(1) and ARG(2) contain the device name in standard format. When
the normal return is taken ARG(2) is changed to the device number
corresponding to the given name, and ARG(3) contains either the entry
point of the device handler if it is already in core, or zero if the
corresponding device handler has not yet been loaded.
A slightly different set of arguments is used to inquire about a
device by its device number:
TAD VAL /AC IS NON-ZERO
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
12 /FUNCTION CODE = 12
0 /ARG(1)
JMP ERR /ERROR RETURN
. /NORMAL RETURN
.
.
On entry to INQUIRE, AC bits 8 to 11 contain the device number.
NOTE
If AC bits O to 7 are non-zero, and bits
8 to 11 are zero (an illegal device
number) a:
MONITOR ERROR 4 AT xxxxx
message is printed and program execution
is terminated.
On normal return ARG(1) is set to the entry point of the device
handler if it is already in core, or zero if the corresponding device
handler has not yet been loaded. The error return in both cases is
taken only if there is no device corresponding to the device name or
number specified.
2.2.11 RESET System Tables Function Code = 13
There are certain occasions when it is desired to reset the system
tables, effectively removing from core all device handlers except the
system handler. An example of the RESET function is shown below:
CDF 0 /DF = CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
13 /FUNCTION CODE = 13
0 /0 PRESERVES TENTATIVE FILES
. /NORMAL RETURN
.
.
2-15
USER SERVICE ROUTINE
RESET zeros all entries except the one for the system device in the
Device Handler Residency Table (see section B.3.3, removing all
device handlers, other than that for the system device, from core.
This should be done anytime a user program modifies any page in which
a device handler was loaded.
RESET has the additional function of deleting all currently active
tentative files (files that have been entered but not closed). This is
accomplished by zeroing bits 9 through 11 of every entry in the Device
Control Word Table (see section B.3.5).
If RESET is to be used in this last fashion, to delete all active
tentative files, then ARG(1) must be non-zero and the normal return is
to ARG(1) rather than to ARG(1)+1. For example, the following call
would serve this purpose
CDF 0 /DF:CURRENT FIELD
CIF 10 /IF = 1
JMS I (USR
13 /FUNCTION CODE = 13
CLA CMA /NON-ZERO:
The normal return would execute the CLA CMA and all active tentative
files on all devices would be deleted. The Keyboard Monitor currently
does not reset the Monitor tables. If user programs which do not call
the Command Decoder are used, it is wise to do a RESET operation
before loading device handlers. The RESET will ensure that the proper
handler will be loaded into core.
2-16
CHAPTER 3
THE COMMAND DECODER
OS/8 provides a powerful subroutine called the Command Decoder for use
by all system programs. The Command Decoder is normally called when a
program starts running. When called, the Command Decoder prints an *
and then accepts a command line from the console Teletype that
includes a list of I/O devices, file names, and various option
specifications. The Command Decoder validates the command line for
accuracy, performs a LOOKUP on all input files, and sets up various
tables for the calling program.
The operations performed by the Command Decoder greatly simplify the
initialization routines of all OS/8 programs. Also, since command
lines all have a standard basic structure, the Command Decoder makes
learning to use OS/8 much easier.
3.1 COMMAND DECODER CONVENTIONS
Chapter 1 of the OS/8 HANDBOOK describes the syntax for the command
line in detail. A brief synopsis is given here only to clarify the
later discussion in this chapter.
The command line has the following general form:
*output files < input files/ (options)
There can be 0 to 3 output files and 0 to 9 input files specified.
Output File Format Meaning
__________________ _______
EXPLE.EX Output to a file named EXPLE.EX on
device DSK (the default file
storage device).
LPT: Output to the LPT. This format
generally specifies a non-file
structured device.
DTA2:EXPLE.EX Output to a file named EXPLE.EX on
device DTA2.
DTA2:EXPLE.EX[99] Output to a file named EXPLE.EX on
device DTA2. A maximum output file
size of 99 blocks is specified.
null No output specified.
3-1
THE COMMAND DECODER
An input file specification has one of the following forms:
Input File Format Meaning
_________________ _______
DTA2:INPUT Input from a file named INPUT.df on
device DTA2. "df" is the assumed
input file extension specified in
the Command Decoder.
DTA2:INPUT.EX Input from a file named INPUT.EX on
device DTA2. In this case .EX
overrides the assumed input file
extension.
INPUT.EX Input from a file named INPUT.EX.
If there is no previously specified
input device, input is from device
DSK, the default file storage
device; otherwise, the input
device is the same as the last
specified input device.
PTR: Input from device PTR; no file
name is needed for non-file
structured devices.
DTA2: Input from device DTA2 treated as a
non-file structured device, as, for
example, in the PIP command line:
*TTY:/L<DTA2:
In both of the last two formats, no
LOOKUP operation is performed since
the device is assumed to be
non-file structured.
null Repeats input from the previous
device specified (must not be first
in input list, and must refer to a
non-file structured device). For
example:
* <PTR:,,
(two null files) indicates that
three paper tapes are to be loaded.
NOTE
Whenever a file extension is left off an
input file specification, the Command
Decoder first performs a LOOKUP for the
given name appending a specified assumed
extension. If the LOOKUP fails, a
3-2
THE COMMAND DECODER
second LOOKUP is made for the file
appending a null (zero) extension.
The Command Decoder verifies that the specified device names, file
names, and extensions consist only of the characters A through Z and 0
through 9. If not, a syntax error is generated and the command line is
considered to be valid.
There are two kinds of options that can be specified: first,
alphanumeric option switches are denoted by a single alphanumeric
character preceded by a slash (/) or a string of characters enclosed
in parentheses; secondly, a numeric option can be specified as an
octal number from 1 to 37777777 preceded by an equal sign (=). These
options are passed to the user program and are interpreted differently
by each program.
Finally, the Command Decoder permits the command line to be terminated
by either the RETURN or ALT MODE key. This information is also passed
to the user program.
3.2 COMMAND DECODER ERROR MESSAGES
If an error in the command line is detected by the Command Decoder,
one of the following error messages is printed. After the error
message, the Command Decoder starts a new line, prints an *, and waits
for another command line. The erroneous command is ignored.
Error Message Meaning
_____________ _______
ILLEGAL SYNTAX The command line is formatted
incorrectly.
TOO MANY FILES More than three output files or
nine input files were specified.
(Or in special mode, more than 1
output file or more than 5 input
files.)
device DOES NOT EXIST The specified device name does not
correspond to any permanent device
name or any user assigned device
name.
name NOT FOUND The specified input file name was
not found on the selected device.
3.3 CALLING THE COMMAND DECODER
The Command Decoder is initiated by the DECODE function of the USR.
DECODE causes the contents of locations 0 to 1777 of field 0 to be
3-3
THE COMMAND DECODER
saved on the system scratch blocks, and Command Decoder to be brought
into that area of core and started. When the command line has been
entered and properly interpreted, the Command Decoder exits to the
USR, which restores the original contents of 0 to 1777 and returns to
the calling program.
NOTE
By setting bit 10 of the Job Status Word
to a 1 the user can avoid this saving
and restoring of core for programs that
do not occupy locations 0 to 1777.
The DECODE call can reside in the area between 0000 to 1777 and still
function correctly. A typical call would appear as follows:
CDF 0 /SET DATA FIELD TO CURRENT FIELD
CIF 10 /INSTRUCTION FIELD MUST BE 1
JMS I (USR /USR=7700 IF USR IS NOT IN CORE
/OR USR=0200 IF USRIN WAS PERFORMED
5 /DECODE FUNCTION = 5
2001 /ARG(1),ASSUMED INPUT EXTENSION
0 /ARG(2),ZERO TO PRESERVE
/ALL TENTATIVE FILES
. /NORMAL RETURN
.
.
ARG(1) is the assumed input extension. If an input file name is given
with no specified extension, the Command Decoder first performs a
LOOKUP for a file having the given name with the assumed extension.
If the LOOKUP fails, the Command Decoder performs a second LOOKUP for
a file having the given name and a null (zero) extension. In this
example, the assumed input extension is ".PA".
DECODE performs an automatic RESET operation (see section 2.2.11) to
remove from core all device handlers except those equivalent to the
system device. As in the RESET function, if ARG(2) is zero all
currently active tentative files are preserved. If ARG(2) is
non-zero, all tentative files are deleted and DECODE returns to ARG(2)
instead of ARG(2)+1.
As the Command Decoder normally handles all of its own errors, there
is no error return from the DECODE operation.
3.4 COMMAND DECODER TABLES
The Command decoder sets up various tables in the top page of field 1
that describe the command line typed to the user program.
3-4
THE COMMAND DECODER
3.4.1 Output Files
There is room for three entries in the output file table that begins
at location 17600. Each entry is five words long and has the following
format:
0 1 2 3 4 5 6 7 8 9 10 11
+-------------------------------------+
WORD 1 | USER SPECIFIED |4 BIT-DEVICE |
| FILE LENGTH | NUMBER |
+-----------------+-----+-------------+
WORD 2 | FILE NAME | FILE NAME |\
| CHARACTER 1 | CHARACTER 2 | |
+-----------------+-------------------+ |
WORD 3 | FILE NAME | FILE NAME | \ OUTPUT FILE NAME
| CHARACTER 3 | CHARACTER 4 | / 6 CHARACTERS
+-----------------+-------------------+ |
WORD 4 | FILE NAME | FILE NAME | |
| CHARACTER 5 | CHARACTER 6 |/
+-----------------+-------------------+
WORD 5 | FILE EXTENSION | FILE EXTENSION |\ FILE EXTENSION
| CHARACTER 1 | CHARACTER 2 |/ 2 CHARACTERS
+-----------------+-------------------+
Bits 0 to 7 of word 1 in each entry contain the file length, if the
file length was specified with the square bracket construction in the
command line. Otherwise, those bits are zero.
The entry for the first output file is in locations 17600 to 17604,
the second is in locations 17605 to 17611, and the third is in
locations 17612 to 17616. If word 1 of any entry is zero, the
corresponding output file was not specified. A zero in word 2 means
that no file name was specified.
Also, if word 5 of any entry is zero no file extension was specified
for the corresponding file. It is left to the user program to take
the proper action in these cases.
These entries are in a format that is acceptable to the ENTER
function.
3.4.2 Input Files
There is room for nine entries in the input file table that begins at
location 17617. Each entry is two words long and has the following
format:
3-5
THE COMMAND DECODER
0 1 2 3 4 5 6 7 8 9 10 11
+-------------------------+--------------+
WORD 1 | MINUS FILE | 4-BIT DEVICE |
| LENGTH | NUMBER |
+-------------------------+--------------+
WORD 2 | STARTING BLOCK OF FILE |
+----------------------------------------+
Bits 0 to 7 of word 1 contain the file length as a negative number.
Thus, 377 (octal) in these bits is a length of one block, 376 (octal)
is a length of two blocks, etc. If bits 0 to 7 are zero, the
specified file has a length greater than or equal to 256 blocks or a
non-file structured device was specified.
NOTE
This restriction to 255 blocks of actual
specified size can cause some problems
if the program has no way of detecting
end-of-file conditions. For example,
PIP cannot copy in image mode any file
on a file structured device that is
greater than 255 blocks long, although
it can handle in /A or/B modes (ASCII or
Binary) files of unlimited size. In /A
or/B modes PIP will detect the CTRL/Z
marking the end-of-file.
If this is liable to be a problem, it is
suggested that the user program employ
the special mode of the Command Decoder
described in section 3.5 and perform its
own LOOKUP on the input files to obtain
the exact file length.
The two-word input file list entries beginning at odd numbered
locations from 17617 to 17637 inclusive. If location 17617 is zero,
no input files were indicated in the command line. If less than nine
input files were specified, the unused entries in the input file list
are zeroed (location 17641 is always set to zero to provide a
terminator even when no files are specified).
3.4.3 Command Decoder Option Table
Five words are reserved beginning at location 17642 to store the
various options specified in the command line. The format of these
five words is as follows:
3-6
THE COMMAND DECODER
0 1 2 3 4 5 6 7 8 9 10 11
+-----------------------------------+
17642 | HIGH ORDER 11 BITS OF |
| = N OPTIONS |
+--+--+--+--+--+--+--+--+--+--+--+--+
17643 |A |B |C |D |E |F |G |H |I |J |K |L |
| | | | | | | | | | | | |
17644 |M |N |O |P |Q |R |S |T |U |V |W |X |
| | | | | | | | | | | | |
17645 |Y |Z |0 |1 |2 |3 |4 |5 |6 |7 |8 |9 |
+--+--+--+--+--+--+--+--+--+--+--+--+
17646 | LOW ORDER 12 BITS OF = > OPTIONS |
+-----------------------------------+
Each of these bits corresponds to one of the possible alphanumeric
option switches. The corresponding bit is 1 if the switch was
specified, 0 otherwise.
NOTE
If no = n option is specified, the
Command Decoder zeroes 17646 and bits 1
to 11 of 17642. Thus, typing =0 is
meaningless since the user program
cannot tell that any option was
specified.
Bit 0 of location 17642 is 0 if the
command line was terminated by a
carriage return, 1 if it was terminated
by an ALT MODE.
3.4.4 Example
To clarify some of the preceding, consider the interpretation of the
following command line:
*BIN[10]<PTR:,,DTA2:PARA,MAIN /L=14200$
If this command line is typed to PAL8, it would cause assembly of a
Program consisting of four separate parts: two paper tapes, one file
named PARA.PA (or just PARA) on DTA2, and one file named MAIN.PA (or
just MAIN) also on DTA2. The binary output is placed on a file named
BIN.BN on device DSK, for which only 10 blocks need be allocated. No
listing is generated. In addition, automatic loading of the binary
output is specified by the /L option, with the starting address given
as 4200 in field 1. Finally, the line is terminated by the ALTMODE key
(which echoes as $) causing a return to the Keyboard Monitor after the
program is loaded.
In the case of this example, the Command Decoder returns to PAL8 with
the following values in the system tables:
3-7
THE COMMAND DECODER
NOTE
The entries for PTR (where no input file
name is specified) have a starting block
number and file size of zero. This is
always true of the input table for a
non-file structured device, or a file
structured device on which no file name
is given.
3-8
THE COMMAND DECODER
+-------+
17600| 0242 |-- DSK:IS DEVICE NUMBER 2
| |
| 0211 |\
| | |
| 1600 | > FILE NAME IS BIN
| | |
| 0000 |/
| |
17604| 0000 |-- NULL EXTENSION
|-------|
17605| |\
| | | REMAINING ENTRIES
~ ~ > IN OUTPUT TABLES
| | | ARE ZERO
17616|_______|/
17617| |\
| 0016 | |
| | > FIRST PTR INPUT
| 0000 | |
17620|_______|/
17621| |\
| 0016 | |
| | > SECOND PTR INPUT
| 0000 | |
17622|_______|/
17623| 7667 |\
| | | DTA2: PARA PA IS 5 BLOCKS LONG,
| 0100 | | BEGINNING AT 100(8)
17624|_______|/
17625| |\
| 0007 | | DTA2: MAIN PA IS 256(10) OR MORE
| | > BLOCKS LONG, BEGINNING AT BLOCK 105(8)
| 0105 | |
17626|_______|/
17627| |\
| | | REMAINING ENTRIES
~ ~ > IN INPUT TABLES
| | | ARE ZERO.
17641| |/
| |
17642| 4001 |-- LINE WAS TERMINATED BY ALT MODE
| |
17643| 0001 |\
| | |
17644| 0000 | \ /L WAS ONLY OPTION SWITCH
| | / SPECIFIED
| | |
17645| 0000 |/
| |
17646| 4200 |-- =14200 WAS SPECIFIED
+-------+
3-9
THE COMMAND DECODER
3.5 SPECIAL MODE OF THE COMMAND DECODER
Occasionally the user program does not want the Command Decoder to
perform the LOOKUP on input files, leaving this option to the user
program itself. Programs such as format conversion routines which
access non-standard file structures could use this special format. If
the input files were not OS/8 format, a command decoder LOOKUP
operation would fail. The capability to handle this case is provided
in the OS/8 Command Decoder. This capability is generally referred to
as the "special mode" of the Command Decoder.
3.5.1 Calling the Command Decoder Special Mode
The special mode call to the Command Decoder is identical to the
standard DECODE call except that the assumed input file extension,
specified by ARG(1), is equal to 5200. The value 5200 corresponds to
an assumed extension of ".*", which is illegal. Therefore, the
special mode of the Command Decoder in no way conflicts with the
normal mode.
3.5.2 Operation of the Command Decoder in Special Mode
In special mode the Command Decoder is loaded and inputs a command
line as usual. The appearance of the command line is altered by the
special mode in these respects:
1. Only one output file can be specified.
2. No more than five input files can be specified, rather than
the nine acceptable in normal mode.
3. The characters asterisk (*) and question mark (?) are legal
in file names and extensions, both in input files and on
output files. It is strongly suggested that these characters
be tested by the user program and treated either as special
options or as illegal file names. The user program must be
careful not to ENTER an output file with an asterisk or
question mark in its name as such a file cannot easily be
manipulated or deleted by the standard system programs.
The output and option table set up by the Command Decoder is not
altered in special mode. Entries in the input table are changed to
the following format:
3-10
THE COMMAND DECODER
0 1 2 3 4 5 6 7 8 9 10 11
+-----------------------+--------------+
WORD 1 | | 4-BIT DEVICE | BITS 0-7 ARE
| | NUMBER | ALWAYS 0
+-----------------+-----+--------------+
WORD 2 | FILE NAME | FILE NAME |\
| CHARACTER 1 | CHARACTER 2 | |
+-----------------+--------------------+ |
WORD 3 | FILE NAME | FILE NAME | \ INPUT FILE NAME
| CHARACTER 3 | CHARACTER 4 | / 6 CHARACTER
+-----------------+--------------------+ |
WORD 4 | FILE NAME | FILE NAME | |
| CHARACTER 5 | CHARACTER 6 |/
+-----------------+--------------------+
WORD 5 | FILE EXTENSION | FILE EXTENSION |\ FILE EXTENSION
| CHARACTER 1 | CHARACTER 1 |/ 2 CHARACTERS
+-----------------+--------------------+
The table entry for the first input file is in locations 17605 to
17611; the second in locations 17612 to 17616; the third in locations
17617 to 17623; the fourth in locations 17624 to 17630; and the fifth
in locations 17631 to 17635. A zero in word 1 terminates the list of
input files. If word 2 of an entry is zero, no input file name was
specified.
The OS/8 batch generating system will allow calls to the command
decoder in special mode.
3.6 CCL AND THE COMMAND DECODER
CCL uses its own copy of the Command Decoder instead of the copy
available from the monitor. Thus, the CCL Command Decoder has several
options not available via standard USR calls to the OS/8 Command
Decoder, e.g., multiple default extensions.
3.7 USEFUL LOCATIONS IN BATCH
BATCH will run whenever bit 0 of location 07777 is a 1. The user may
wish to access the following useful locations in BATCH. The locations
are in the highest memory field available to OS/8:
BATERR = 7000 JMP here to abort BATCH.
BATOUT = 7400 JMS here to print character
in AC in BATCH log.
BATSPL = 7200 JMS here to permit spooling
with default extension in AC.
3-11
THE COMMAND DECODER
3.8 CCL TABLES
A description of all tables used by CCL is included in the file CCL.PA
supplied to all users of OS/8 version 3.
3-12
CHAPTER 4
USING DEVICE HANDLERS
A device handler is a system subroutine that is used by all parts of
the OS/8 system and by all standard system programs to perform I/O
transfers. All device handlers are called in the same way and they
all perform the same basic operation: reading or writing a specified
number of 128 word records beginning at a selected core address.
These subroutines effectively mask the unique characteristics of
different I/O devices from the calling program; thus, programs that
use device handlers properly are effectively "device independent".
Changing devices involves merely changing the device handlers used for
I/O.
OS/8 device handlers have another important feature. They are able to
transfer a number of records as a single operation. On a device like
DECtape this permits many blocks of data to be transferred without
stopping the tape motion. On a disk, a single operation could
transfer an entire track or more. This capability significantly
increases the speed of operation of OS/8 programs, such as PIP, that
have large buffer areas.
NOTE
The word "record" is defined to mean 128
words of data; thus, an OS/8 block
consists of two 128 word records.
4.1 CALLING DEVICE HANDLERS
Device handlers are loaded into a user selected area in memory field 0
by the FETCH function. FETCH returns in ARG(1) the entry point of the
handler loaded. The handler is called by performing a JMS to the
specified entry point address. It has the following format:
CDF N /WHERE N IS THE VALUE OF THE CURRENT
/PROGRAM INSTRUCTION FIELD TIMES 10 (OCTAL)
CIF 0 /DEVICE HANDLER ALWAYS IN FIELD 0
JMS I ENTRY
ARG(1) /FUNCTION CONTROL WORD
ARG(2) /BUFFER ADDRESS
ARG(3) /STARTING BLOCK NUMBER
JMP ERR /ERROR RETURN
. /NORMAL RETURN (I/O TRANSFER COMPLETE)
.
ENTRY 0 /ENTRY CONTAINS THE ENTRY POINT OF THE
/HANDLER, DETERMINED WHEN LOADED BY FETCH
4-1
USING DEVICE HANDLERS
As with calls to the USR, it is important that the data field is set
to the current program field before teldevice handler is called. On
exit from the device handler, the data field will remain set to the
current program field.
ARG(1) is the function control word, and contains the following
information:
Bits Contents
Bit 0 0 for an input operation, 1 for an output
operation.
Bits 1 to 5 The number of 128 word records to be
transferred. If bits 1-5 are zero and the
device is non-file structured (i.e., TTY,
LPT, etc.) the operation is device dependent.
If the device is file structured (SYS,
DECtape, disk, etc.), a read/write of 40
(octal) pages is performed.
Bits 6 to 8 The memory field in which the transfer is to
be performed.
Bits 9 to 11 Device dependent bits, can be left zero.
Currently only bit 11 is used; on DECtape
bit 11 determines the direction in which the
tape is started. If bit 11 is 0, the tape
starts in reverse. If bit 11 is 1, the tape
starts forward. All other handlers ignore
these bits at present (except TM8E and TA8E).
NOTE
Starting forward saves time as long as
the block number, ARG(3), is about seven
or more blocks greater than the number
of the block at which the tape is
currently positioned.
ARG(2) is the starting location of the transfer buffer.
ARG(3) is the number of the block on which the transfer is to begin.
The user program initially determines this value by performing a
LOOKUP or ENTER operation. After each transfer the user program
should itself add to the current block number the actual number of
blocks transferred, equal to one-half the number of 128 word records
specified, rounded up if the number of records was odd.
There are two kinds of error returns: fatal and non-fatal. When an
error return occurs and the contents of the AC are negative, the error
is fatal. A fatal error can be caused by a parity error on input, a
write lock error on output, or an attempt to write on a read-only
device (or vice versa). The meaning can vary from device to device,
4-2
USING DEVICE HANDLERS
but in all cases it is serious enough to indicate that the data
transferred, if any, is invalid.
When an error return occurs and the contents of the AC are greater
than or equal to zero, a non-fatal error has occurred. This error
always indicates detection of the logical end-of-file. For example,
when the paper tape reader handler detects the end of a paper tape it
inserts a CTRL/Z code in the buffer and takes the error exit with the
AC equal to zero. While all non-file structured input devices can
detect the end-of-file condition, no file structured device can;
furthermore, no device handler takes the non-fatal error return when
doing output.
The following restrictions apply to the use of device handlers:
1. If bits 1 to 5 of the function control word, ARG(1), are
zero, a transfer of 40 (octal) pages or an entire memory
field is indicated. Care must be used to ensure that the
handler is not overlaid in this call. This only applies to
file-structured handlers.
2. The user program must never specify an input into locations
07600 to 07777, 17600 to 17777, or 27600-27777, or the
page(s) in which the device handler itself resides. In
general, 7600-7777 in every memory field are reserved for use
by system software. Those areas should be used with caution.
3. Note that the amount of data transferred is given as a number
of 128 word records, exactly one half of an OS/8 block.
Attempting to output an odd number of records can change the
contents of the last 128 words of the last block written.
For example, outputting 128 words to a block on the RK8 disk
causes the last 128 words of the block to be filled with
zeroes.
4. The specified buffer address does not have to begin at the
start of a page. The specified buffer cannot overlap fields,
rather the address will "wrap around" memory. For example, a
write of 2 pages starting at location 07600 would cause
locations 07600-07777 and 00000-00177 of field 0 to be
written.
5. If bits 1-5 of the function control word ARG(1) are zero, a
device-dependent operation occurs. Users should not expect a
40-page (full field) transfer of data. The CLOSE operation
of the USR calls the handler with bits 1-5 and 9-11 of the
function control word 0. This condition means 'perform any
special close operations desired'. Non-file structured
handlers which need no special handling on the conclusion of
data transfers should treat this case as a NOP. Examples of
usage of such special codes:
LPT - perform a form feed
CSAn, MTAn - write two file marks
4-3
USING DEVICE HANDLERS
4.2 DEVICE DEPENDENT OPERATIONS
This section describes briefly the operation of certain standard OS/8
device handlers, including normal operation, any special
initialization operations for block 0, terminating conditions, and
response to control characters typed at the keyboard. Further
information on device handlers can be found in Chapter 5.
4.2.1 1-Page Terminal (TTY) (AS33)
1. Normal Operation
This handler inputs characters from the terminal keyboard and
packs them into the buffer or unpacks characters from the
buffer and outputs them to the console terminal.
On input, characters are echoed as they are typed. Following
a carriage return, a line feed character is inserted into the
input buffer and printed on the terminal.
2. Initialization for Block 0
None.
3. Terminating Conditions
On input, detection of a CTRL/Z causes a CTRL/Z (octal code
232) to be placed in the input buffer, the remaining words of
the buffer to be filled with zeros, and a non-fatal error to
be returned. On output, detection of a CTRL/Z character in
the output buffer causes output to be terminated and the
normal return to be taken. There are no fatal errors
associated with the 1-page terminal handler.
4. Terminal Interaction
CTRL/C forces a return to the Keyboard Monitor. CTRL/Z
forces an end-of-file on input (see 3). CTRL/O terminates
printing of the contents of the current buffer on output.
4.2.2 High-Speed Paper Tape Reader (PTR)
1. Normal Operation
This handler inputs characters from the high-speed paper tape
reader and packs them into the buffer.
2. Initialization for Block 0
The handler prints an up-arrow (^) on the terminal and waits
4-4
USING DEVICE HANDLERS
for the user to load the paper tape reader. By typing any
single character (except CTRL/C) the user initiates reading
of the paper tape.
NOTE
On some terminals, up-arrow is replaced
by the circumflex (^) character.
3. Terminating Conditions
Detection of an end-of-tape condition, indicated by the
failure to get a character in a specified period of time,
causes a CTRL/Z to be entered in the buffer, the remaining
words of the buffer to be filled with zeros, and a non-fatal
error to be returned. Attempting output to the paper tape
reader causes a fatal error to be returned.
4. Terminal Interaction
Typing CTRL/C forces a return to the Keyboard Monitor.
4.2.3 High-Speed Paper Tape Punch (PTP)
1. Normal Operation
This handler unpacks characters from the output buffer and
punches them on the paper tape punch.
2. Initialization for Block 0
None.
3. Terminating Conditions
Attempting to input from the paper tape punch causes a fatal
error to be returned. There are no non-fatal errors
associated with this handler.
4. Terminal Interaction
Typing CTRL/C forces a return to the Keyboard Monitor, but
only when actual punching has begun, or if ^C is typed before
punching commences. If the punch is off line, ^C is only
effective immediately before punching would begin.
4.2.4 Line Printer (LPT) (LPSV)
1. Normal Operation
4-5
USING DEVICE HANDLERS
This handler unpacks characters from the buffer and prints
them on the line printer. The characters horizontal tab
(ASCII 211) causes sufficient spaces to be inserted to
position the next character at a "tab stop" (every eighth
column, by definition). The character vertical tab (ASCII
213) causes a skip to the next paper position for vertical
tabulation if the line printer hardware provides that
feature. The character form feed (ASCII 214) causes a skip
to the top of the next page. Finally, the handler maintains
a record of the current print column and starts a new line
after 80 or 128 columns have been printed. This handler
functions properly only on ASCII data. The handler for the
LS8E line printer handler utilizes the expanded character
capability of the printer. If a 216 (CTRL/N) character
appears anywhere in a line of text, the entire line is
printed in the expanded character mode. The 216 must be used
on a line-by-line basis.
2. Initialization for Block 0
Before printing begins, the line printer handler issues a
form feed to space to the top of the next page.
3. Terminating Condition
On detection of a CTRL/Z character in the buffer, the line
printer handler issues a form feed and immediately takes the
normal return. Attempting to input from the line printer
forces a fatal error to be returned. A fatal error is also
returned if the line printer error flag is set. There are no
non-fatal errors associated with the line printer handler.
4. Terminal Interaction
Typing CTRL/C forces a return to the Keyboard Monitor.
5. Patching the LPSV Handler
The following patches are available for the LPSV line printer
handler.
rel. loc 0: set to -printer width-l (i.e. set to -121(octal)
for an 80 column line
printer)
rel. loc 1: set to 4 for the LV8E line
printers
set to 14 for the LP08 and LS8E
printers
rel. loc 2: set to -40 to convert lower case to
upper case
set to 0 if your printer can print
lower case
4-6
USING DEVICE HANDLERS
4.2.5 Cassettes
1. Normal Operation
This handler performs character I/O between the cassettes and
the buffer. It treats cassettes as a non-file structured
device. Data appears on cassette in 192-byte records.
2. Initialization for Block 0
On input the cassette is rewound. On output the cassette is
rewound and a file gap is written.
3. Terminating Condition
An end-of-file on input is a software error.
4. Terminal Interaction
Typing CTRL/C forces a return to the Keyboard monitor.
5. Special Codes (device dependent features)
If the handler is called with bits 1-5 of the function word
=0, then bits 10-11 are examined. The meaning of these codes
are as follows:
0 write a file gap
1 rewind also, then write a file gap if bit 0=1
2 space backwards one record
3 skip one file (direction depends on bit 0)
NOTE
The handler neither reads nor writes
standard files. It is merely a paper
tape replacement. It writes raw data
(organized into 192-byte records) onto
the cassettes starting at the beginning;
and then later reads it back.
The source is already in OS/8 BUILD format. The handler has only two
entry points (for drives A and B of a controller). The decision as to
which controller it uses is made at assembly time by changing the
symbol code. The result is as follows:
CODE DEVICE NAME HANDLER DEVICE CODE
____ ___________ _______ ___________
0 TA8A A:CSA0 70
B:CSA1
1 TA8B A:CSA2 71
B:CSA3
4-7
USING DEVICE HANDLERS
2 TA8C A:CSA4 72
B:CSA5
3 TA8D A:CSA6 73
B:CSA7
The handler has the internal device code of 27 (see Table 2-12 in
Chapter 2 of the OS/8 HANDBOOK. The handler is two pages long.
4.2.6 Card Reader (CDR)
1. Normal Operation
This handler reads characters from the card reader and packs
them into the input buffer. Trailing spaces (blank columns)
on a card are deleted from input. The handler can accept
only alphanumeric format data on cards (the DEC029 standard
card codes are used).
2. Initialization for Block 0
None.
3. Terminating Conditions
A card which contains an underline character in column 1 (an
0-8-5 punch) with the remaining columns blank is an
end-of-file card. In addition, after reading each card the
handler checks to see if a CTRL/Z was typed at the keyboard.
After either an end-of-file card or a CTRL/Z being typed, a
CTRL/Z is inserted in the buffer, the remaining words of the
input buffer are filled with zeros, and a non-fatal error is
returned. Attempting to output to the card reader causes a
fatal error to be returned.
4. Terminal Interaction
Typing CTRL/C forces a return to the Keyboard Monitor.
Typing CTRL/Z forces an end-of-file to occur (see 3.).
4.2.7 TM8-E Handler
1. Normal Operation:
When the handler is used in its normal mode, single-file
mode, magtapes may consist of exactly one file. It starts at
the beginning of the tape and consists of consecutive records
until an end-of-file mark (EOF) is reached. In this sense, a
magtape is similar to one big paper tape. This is the same
way that OS/8 currently treats cassettes.
4-8
USING DEVICE HANDLERS
Since the capacity of magtapes is so big, provisions have
been made for storing multiple files per tape. In such a
structure, several files may exist on one magtape. They are
unlabeled and are separated from each other by a single file
mark. The last one is followed by two file marks. Each
'file' looks like a paper tape. It is referenced in a
non-file structured manner. The magtape handler must be
altered first to work in file mode. Then the magtape must be
positioned to exactly the correct spot where the read or
write operation will commence. This may be done with any
program using the auxiliary capabilities of the magtape
handler (described below), or the positioner program, CAMP.
To read a file, the handler must be positioned to just before
the first data record of that file. To write file #1, rewind
the tape (i.e., be at BOT). To write file #n, (n>1) the
handler should be positioned after the (n-1)st file mark on
the tape. Previous file n and all files past it then become
unreadable (non-existent).
A. Device-Dependent Capabilities:
The TM8-E handler has several auxiliary features which
may be invoked by a user program which calls the handler
in a device-dependent manner. These features all rely on
the contents of bits 9-11 of the function word (argument
1 of the handler call) and some require argument 3 in
addition.
These features are brought to life whenever the handler
is called with a page count of 0 (bits 1-5 of the
function word). Call bits 9-11 of the function word, the
Special Function Register (SFR) for short, and also refer
to bit 0 of the function word as the direction bit. If
the page count is not 0, the contents of the SFR are
ignored.
If the page count is 0, then the SFR together with the
direction bit (and possibly argument 3) determine what
special function to perform, as follows:
SFR OPERATION
___ _________
0. CLOSE. Write two EOF's.
1. Rewind.
2. Space forward/reverse records. The direction to
space is determined by the direction bit (0 means
space forward, 1 means space reverse). The negative
(two's complement) of the number of records to space
over is given by argument 3 of the handler call. (-1
means space past one record, 0 means 4096 records.)
The error return is taken if either a file mark or
BOT is encountered. In such cases, you would be left
4-9
USING DEVICE HANDLERS
positioned at the beginning of a file.
3. Space forward/reverse files. The direction to space
is determined by the direction bit (0 means space
forward, 1 means space reverse). The negative of the
number of file marks to space past is given by
argument 3 (-1 means space past one file mark; 0
means 4096 file marks). In reverse mode, the tape is
left positioned at the end of a file; an error is
given if BOT is encountered. In forward mode, the
tape is left positioned at the beginning of a file.
If EOD is reached, the handler automatically performs
a backspace record to leave you between the two file
marks; no error is given.
4. Rewind the unit and put drive off-line.
5. Write a single EOF.
6. Special read/write function. The direction bit (as
usual) determines read or write (0 means read, 1
means write). The specified I/O operation is
performed between the user's buffer (start is
specified by argument 2) and the very next magtape
record. Only one record is transferred and the
user's buffer must be large enough to contain it.
The record length is specified by the negative of
argument 3 (in words). 0 means a record length of
4096.
7. Unused. Reserved for future use. If specified, it
currently acts as a NO-OP.
In each case, the unit affected is determined by the handler entry
point.
B. Other Common Operations:
(a) To backspace n files, use Special Code 3 to pass over
n+1 file marks backwards, then use Special code 2 to
advance (forward) over one record (EOF) ignoring the
EOF error.
(b) To advance to EOD, first perform a backspace of one
record (or perform a rewind to play safe) then use
special code 3 to advance over 4096 files in the
forward direction (argument 3=0).
2. Special Handling for Block 0
If the handler is called to read or write block 0, it will
first perform a rewind. This feature can be patched out if
4-10
USING DEVICE HANDLERS
desired by altering relative location 1 from a 0 to a 1. This
altered handler should be operating in file mode. The
original handler should be operating in single-file mode.
A. Special Handling for CLOSE:
A close operation is signaled to the handler by calling
it with a function word which has a page Count of 0 (bits
1-5) and which has bits 9-11 all zeroes. This is how the
USR CLOSE operation calls the handler (OS/8 V3 only).
This causes the handler to write two Successive file
marks on the tape. Two Successive EOF's is the software
indication of end-of-data (EOD).
B. Restrictions:
In single-file mode, should not have more than 4095
blocks because on trying to write the 4096th block, the
handler will think it's writing block 0 and perform a
rewind. This restriction does not apply when using the
handler in file-mode; but beware, some CUSPs, Such as
PIP, are suspected to behave strangely on block 4096 of
non-file-structured devices.
3. Terminating Conditions
None.
4. Keyboard Interaction:
Typing ^C on the keyboard while the handler is in operation
causes the handler to abort and return to the OS/8 keyboard
monitor via location 7600. Such action is ill-advised since
it leaves the magtape without an end-of-file indicator.
5. Error Conditions:
On a hard error, the handler takes the error return (with a
negative AC) and the AC contains the Contents of the main
status register, as follows:
Bit on Meaning
______ _______
0 Error flag
1 Tape rewinding
2 BOT
3 Select error
4 Parity error (vertical, longitudinal, or
CRC)
5 EOF
6 Record length incorrect
7 Data request late
8 EOT
9 File protect
10 Read compare error
11 Illegal function
4-11
USING DEVICE HANDLERS
4.2.8 File-Structured Devices
1. Normal Operation
(DECtape, LINCtape, TD8E DECtape, DF32, RF08, and RK8, RK8E)
These handlers transfer data directly between the device and
the buffer.
2. Initialization for Block 0
None.
3. Terminating Conditions
A fatal error is returned whenever the transfer causes one of
the error flags in the device status register to be set. For
example, a fatal error would result if a parity error
occurred on input, or a write lock error occurred on output.
The device handlers generally try three times to perform the
operation before giving up and returning a fatal error.
There are no non-fatal errors associated with file structured
devices.
4. Terminal Interaction
Typing CTRL/C forces a return to the Keyboard Monitor.
NOTE
The system device handler does NOT
respond to a typed CTRL/C.
4.2.9 TD8E DECtape
TD8E DECtape is the new accumulator transfer DECtape. Since OS/8 is a
noninterrupt driven system, TD8E DECtape has data transfer rates
equivalent to those for TC08 DECtape; however, the interrupt should
never be used with the TD8E. Device handlers for TD8 DECtape are
supplied as a standard part of OS/8. Each pair of drives (0 and 1, 2
and 3, etc.) requires a 2-page device handler. Thus, to have all
eight TD8E drives in the system at one time will require four separate
handlers. Thus for TD8E, it is wise to restrict usage to those units
that physically exist. Also, the tape drives are hardwired to select
one of two possible unit numbers; thus, the first pair of drives
installed must be called units 0 to 1. Any others numbers will cause a
SELECT error. In this case, the computer hangs until the correct
drive is selected.
4-12
USING DEVICE HANDLERS
4.2.10 KL8E Terminal Handler
Listed are the features of the KL8E handler. Those that are
conditional are marked by an asterisk:
1. It reads a line at a time. Whenever the user types CR, it
enters CR, LF into the buffer; it echoes CR, LF; and then
pads the remainder of the buffer with nulls and returns to
the calling program. The characters get put into the buffer,
one character per word. Thus every third character is a null
as far as OS/8 is concerned.
2. RUBOUT deletes the previous character. It echoes as either a
back slash (\) or as the character rubbed out, depending on
assembly parameters. RUBOUT at the beginning of a line acts
as ^U.
3. CTRL/U echoes as ^U and erases the current line, allowing the
user to retype it. (It also echoes CR, LF.) The buffer
pointer is reset to the beginning of the buffer.
4. CTRL/Z echoes as ^Z (followed by CR, LF) and signals
end-of-input. The ^Z enters the buffer and the remainder of
the buffer is padded with nulls. The error return is taken
with a positive AC (non-fatal error).
5. Nulls are ignored.
*6. The altmode characters (octal 175 and 176) are converted to
escapes (octal 33).
*7. Lower-case characters typed may be automatically converted to
upper case.
8. CTRL/C echoes as ^C and returns control to the keyboard
monitor via location 07600.
On output: (either normal output or when echoing input)
1. CTRL/C on keyboard echoes as ^C and returns control to the
keyboard monitor via location 7600.
2. CTRL/O on keyboard stops further echoing. All echoing ceases
(through possibly many buffer loads) until either the handler
is reloaded into core or the user types a character other
than to on the keyboard. Not operative during input.
3. ^S causes the handler to stop sending to the terminal. No
characters are lost and outputting resumes when a ^Q is
typed. ^S and ^Q do not echo. These characters are
operative only upon output. On input, they are treated like
any other input characters. This is very useful on high
speed CRT displays.
4-13
USING DEVICE HANDLERS
4. Nulls are ignored.
*5. Lower case characters may be optionally printed as upper case
and flagged with an apostrophe.
*6. Tabs may be handled in one of three manners:
a. Output as actual tabs,
b. Output as actual tab followed by padding of two rubouts,
c. Output as the correct number of spaces to bring the text
to the start of the next tab stop.
7. Whenever the output line reaches the end of the physical line
(length set at assembly time), the handler automatically
performs a carriage-return line-feed.
*8. The escape character (octal 33) prints as a dollar sign.
*9. The handler may be set to delay about 16 ms after typing any
character (specified at assembly time), for example, line
feed.
*10. Control characters are printed as their corresponding letter
preceded by an up-arrow. Thus CTRL/K prints as ^K.
4-14
CHAPTER 5
RECONFIGURING THE OS/8 SYSTEM
It is sometimes necessary to construct an OS/8 system from scratch, or
to make a new peripheral device available to OS/8. Both of these tasks
are a part of reconfiguring the OS/8 system. OS/8 BUILD, which is
described in detail in Chapter 2 of the OS/8 HANDBOOK, allows the user
quickly and easily to build a new system or to alter the device
complement of an existing system.
5.1 WRITING DEVICE HANDLERS
A device handler is a page-independent subroutine one or two pages
long. The device handler must run properly in any single page or two
contiguous pages in field 0 (except 0000 to 0177 or 7600 to 7777). All
device handlers have the same calling sequence:
CDF N /N IS CURRENT FIELD TIMES 10 (OCTAL)
CIF 0 /DEVICE HANDLER LOCATED IN FIELD 0
JMS I ENTRY /ENTRY IS DETERMINED BY SR "FETCH"
FUNCTION /FUNCTION IS BROKEN DOWN AS FOLLOWS:
/BIT 0 = 0 FOR READ
/BIT 0 = 1 FOR WRITE
/BITS 1 TO 5 = NUMBER OF PGS TO TRANSFER
/BITS 6 TO 8 = FIELD FOR TRANSFER
/BITS 9 TO 11 = DEVICE DEPENDENT BITS
BUFFER /CORE ADDRESS OF TRANSFER BUFFER
BLOCK /BLOCK NUMBER TO START TRANSFER
ERROR /ERROR RETURN, AC>=0 MEANS END-OF-FILE
AC<0 MEANS FATAL ERROR
NORMAL /NORMAL RETURN
The device handler reads or writes a number of 128 word records
beginning at the selected block. In general, device handlers should
conform to the following standards:
1. On normal return from a device handler the AC is zero and the
DATA FIELD is always restored to its original entry value.
2. Although the starting block number has true significance only
for file structured devices, handlers for non-file structured
devices can check the block number and perform initialization
if the block number is zero. For example, the line printer
handler outputs a form feed before printing when the
specified block number is zero.
5-1
RECONFIGURING THE OS/8 SYSTEM
3. Handlers should be written to be as foolproof as possible
checking for the most common errors in the calling program.
Examples of typical user errors are: calling handler with
non-zero AC (always perform a CLA in the handler); trying to
read on a write only device, or trying to write on a read
only device (gives a fatal error return); specifying 0 pages
to be transferred (accept as meaning no actual transfer is to
take place); or attempting to access a nonexistent block
(gives a fatal error return).
4. Device handlers normally check to see if a CTRL/C (ASCII 203)
has been typed at the system console by the user. If one
has, the handler aborts I/O and JMP's to location 7600 in
field 0. The seven low order bits of the keyboard should be
checked for a 3 so as to allow parity terminals. KRS should
be used over KRB so that any paper tape in the reader will
not be advanced if its character is not ^C.
5. Device handlers should be able to detect standard error
conditions like checksum or parity errors. Whenever
possible, several attempts to perform the transfer should be
made before aborting I/O and taking the error exit. In
addition, when operator intervention is required, the handler
would normally wait for the action rather than take a fatal
error exit. For example, if the paper tape punch is not
turned on, the PTP handler waits for the punch to be turned
on.
6. By convention, in any handler for a device (like DECtape)
that can search either forward or backward for a block, Bit
11 of the function word (one of the device-dependent bits)
controls the starting direction of the search. Bit 11 is a 1
if the starting direction is forward and a 0 if it is
reverse. The other two device dependent bits are not
assigned any significance at the present time.
7. Remember that the user specifies a multiple of 128 words to
transfer, whereas the transfer starts at the beginning of a
128 or 256 word block. This means that the handler must
provide that capability of reading or writing the first half
of a block. Writing the first half of the block causes the
contents of the second half of the block to be altered. For
example, writing 128 words to the RK8 disk (256 word blocks)
causes the second half of the block to be filled with zeroes.
This is usually done by the hardware controller.
8. The entry point to a two page device handler must be in the
first page.
9. A number of handlers (maximum of 15 decimal) can be included
in the one or two pages of code. Where more than one handler
is included in a single handler subroutine, the handlers are
called co-resident. Co-resident handlers are always brought
5-2
RECONFIGURING THE OS/8 SYSTEM
into core together. For example, all eight DECtape handlers
fit into one page; hence, the DECtape handlers are
co-resident. One restriction on co-resident handlers is that
if they are two pages long all entry points must be in the
first page.
10. The USR, while doing file operations, maintains in core the
last directory block read in order to reduce the number of
directory reads necessary. The proper functioning of this
feature depends on the fact that every handler for a
file-structured device on a single system has a unique entry
point relative to the beginning of the handler. The relative
entry points currently assigned for file structured handlers
are:
Device Handlers Relative Entry Points
_______________ _____________________
System Device Handler 7
DECtape, LINCtape or TD8E DECtape 10 to 17
RKA0 20
RKA1 21
RKA2 22
RKA3 23
RK08 or DF32 24
Reserved for user 40 to 67
11. If the device is block oriented (such as DECtape, LINCtape,
or Disk), then the handler transfers data directly with no
alteration. However, if the device is character oriented
(such as a paper tape reader, Teletype, or line printer), the
handler is required to pack characters into the buffer on
input and unpack them on output. The standard OS/8 character
packing format puts three 8-bit characters into two words as
follows:
+---------------+------------------+
WORD 1 |CHARACTER 3 | |
| BITS 0-3 | CHARACTER 1 |
+---------------+------------------+
WORD 2 |CHARACTER 3 | |
| BITS 4-7 | CHARACTER 2 |
+---------------+------------------+
0 3 4 11
For example, the 3 characters 'ABC' would be packed into 2
words as follows:
Word 1: 6301
Word 2: 1702
When packing characters on input, the character CTRL/Z (octal
232) is inserted at the logical end-of-file (for example, at
the end of the tape in the paper tape reader handler).
Following CTRL/Z, the remaining words of the input buffer
should be zeroed.
5-3
RECONFIGURING THE OS/8 SYSTEM
12. A close operation should be performed by non-file structured
handlers if bits 1-5 and 9-11 of the function word are 0.
The device handler, whether one or two pages long, must be completely
page independent: it must be capable of executing in any page(s) in
field 0, except page 0 and 7600 to 7777. Page independent code can
have no address constants. Writing one page handlers is relatively
easy, since the addressing structure of the PDP-8 is essentially page
independent. Writing page relocatable code for two pages, however, is
considerably more difficult, as the two pages must communicate. The
usual technique utilized in writing two page handlers is to include
some initialization code which includes a JMS. This replaces that
location by an address on the page the handler was loaded on. Using
this, the handler can then determine where the relevant pieces of code
are in core.
As an example, the following is the initialization procedure performed
by the TD8E DECtape routine. This is by no means the only technique
that is possible, but it is a workable solution.
*200
/EXECUTED CODE
JINIT, JMP INIT /START INITIALIZATION
.
.
.
INIT, JMS. /FOUND OUT WHERE WE ARE.
BASE, TAD CRDQAD /INIT GETS ADDRESS OF BASE
SPA /NEGATIVE TERMINATES LIST
JMP NXINIT /INITIALIZE SECOND PAGE
TAD INIT /NOW UPDATE THE LIST OF
DCA CRDQAD /ADDRESS DEPENDENT LOCATIONS
ISZ .-1 /POINT TO NEXT ELEMENT
ISZ BASE /NEXT INPUT VALUE
JMP BASE /LOOP OVER INPUT TABLE.
.
.
.
.
CRDQAD, R4LINE-BASE /THESE ARE ALL POSITIVE DIFFERENCES,
CINIT2, INIT2-BASE /SINCE THE ROUTINES INDICATED ARE
CSELCT, SELECT-BASE /IN THE SECOND PAGE. AFTER
CXUNIT, XUNIT-BASE /INITIALIZATION, CRDQAD POINTS TO
BUFF, 4000 /THE ACTUAL ADDRESS OF R4LINE, ETC.
. /THE 4000 IN BUFF TERMINATES
. /THE FIRST INITIALIZATION.
. /MORE PAGE INDEPENDENT CODE
NXINIT, JMS I CINIT2 /INITIALIZE SECOND PAGE
BASE2, DCA JINIT /CLEAR OUT JINIT. NO MORE
JMP JINIT /RELOCATING IS NEEDED UNTIL THE
/HANDLER IS LOADED INTO CORE AGAIN.
5-4
RECONFIGURING THE OS/8 SYSTEM
*400 /SECOND PAGE OF HANDLER
INIT2, 0 /ADDRESS OF BASE2 GOES HERE
INIT3, TAD CTRY3
SNA /A 0 TERMINATES THIS LIST
JMP I INIT2
TAD INIT2 /ADD VALUE OF BASE2 TO LIST
DCA CTRY3 /PUT BACK INTO LIST
ISZ .-1 /NEXT LOC. TABLE
ISZ INIT3
JMP INIT3
.
.
.
.
CTRY3, TRY3-BASE2 /THIS LIST GETS VALUE OF BASE2
CRWCOM, TRWCOM-BSSE2 /ADDED IN TO POINT TO THE REAL
XBUFF, 0 /ROUTINE.
Writing 2 page independent code can be expensive in terms of core
required. The routines should be set up in such a way as to minimize
communication between the two pages. Some other points to keep in
mind are:
1. Relocation code is once-only code. It is done once when the
handler is loaded and need never be done again until the
handler is re-loaded from the system device. For this
reason, the relocation code can be placed in a buffer area or
setup in temporary scratch locations which are later used as
temporary storage.
2. A useful hint is that a JMP into the next page of code is not
required. The code can just as easily fall through 377 into
400. This may save a few locations of relocation code.
3. Useful techniques for writing 2-page handlers can be found in
the source of the KL8E handler.
5.2 INSERTING DEVICE HANDLERS INTO OS/8
After the handler has been written and thoroughly debugged as a
stand-alone routine, it can be integrated into the OS/8 Monitor, where
it will become a resident device handler. To accomplish the
integration, use OS/8 BUILD, described thoroughly in the BUILD section
in Chapter 2 of the OS/8 HANDBOOK.
Notes for writing system handlers system handlers may be integrated
into BUILD just like non-system handlers with the following additional
notes:
5-5
RECONFIGURING THE OS/8 SYSTEM
1. Body of system handler should be origined to 200 but must
start with a 2 BLOCK 7. Entry point must be at relative
location 7 (corresponds to location 7607).
2. Name of system handler must be SYS.
3. Each handler entry point has an 8-word handler block
associated with it. The following additions apply:
a. word 5: bits 9-11 should normally be 0.
If the device can have multiple platters (like RF08)
then this field specifies maximum number of platters
allowed. Each platter above first bumps internal DCB
code by 1.
word 6: bit 0=1 means system device is two pages long.
The second page is origined into 400 but resides in
field 2 location 7600. Bit 1=1 if entry point is SYS.
Bit 2=1 if entry point is coresident with SYS.
word 7: must be 0
word 10: number of blocks in device. Immediately
following the header records is the code for the
device's bootstrap. This is preceded by minus the
number of words in the bootstrap. No origins may appear
in this code. It must be less than 47 locations long.
5-6
APPENDIX A
OS/8 FILE STRUCTURES
A.1 FILE DIRECTORIES
Blocks 1 through 6 on all file structured devices are reserved for the
file directory of that device. Six blocks are always allocated,
though all are not necessarily active at any given time. To minimize
the number of directory reads and writes necessary, OS/8 fills one
directory block completely before overflowing onto a second block.
Thus the user with only a few files can perform directory LOOKUPs and
ENTERs faster than one with many files.
The directory blocks are each structured according to the following
format:
ENTRY
+--------------------------------+
0 | MINUS THE NUMBER OF ENTRIES |
| IN THIS SEGMENT |
+--------------------------------+
1 | THE STARTING BLOCK NUMBER |
| OF THE FIRST FILE IN THIS |
| SEGMENT |
+--------------------------------+
2 | LINK TO NEXT SEGMENT-ZERO |
| IF NO NEXT SEGMENT |
+--------------------------------+
3 | FLAG WORD-POINTS TO LAST WORD |
| OF TENTATIVE FILE ENTRY IN |
| THIS SEGMENT |
| DIRECTORY SEGMENTS ARE ALWAYS |
| LOADED INTO LOCATIONS 11400 |
| TO 117777 BY THE USR; THIS |
| POINTER IS EITHER 0 OR BETWEEN |
| 1400 TO 1777. |
+--------------------------------+
4 | MINUS THE NUMBER OF |
| ADDITIONAL INFORMATION WORDS. |
| THE NUMBER OF ADDITIONAL |
| INFORMATION WORDS SPECIFIED |
| MUST BE THE SAME IN ALL |
| DIRECTORY SEGMENTS |
+--------------------------------+
5 | BEGINNING OF FILE ENTRIES |
+--------------------------------+
. | |
. ~ ~
. | |
+--------------------------------+
377| END OF DIRECTORY BLOCK |
(8)+--------------------------------+
A-1
OS/8 FILE STRUCTURES
Locations 0 through 4 of each directory block are called the segment
header.
A.1.1 Directory Entries
There are three types of file directory entries. They are PERMANENT
FILE ENTRY, EMPTY FILE ENTRY, and TENTATIVE FILE ENTRY. A permanent
file entry appears as follows:
Location Contents Notes
+-------------------------------+
0 | FILE NAME FILE NAME |\
| CHARACTER 1 CHARACTER 2 | |
+-------------------------------+ |
1 | FILE NAME FILE NAME | |
| CHARACTER 3 CHARACTER 4 | | THE FILE NAME AND EXTENSION
+-------------------------------+ > ARE PACKED IN SIXBIT ASCII
2 | FILE NAME FILE NAME | | (i.e., "A" would be 01)
| CHARACTER 5 CHARACTER 6 | |
+-------------------------------+ |
3 | FILE EXTENSION FILE EXTENSION | |
| CHARACTER 1 CHARACTER 2 |/
+-------------------------------+
| |\
| | | N, THE NUMBER OF ADDITIONAL
+-------------------------------+ | INFORMATION WORDS, IS GIVEN
| ADDITIONAL | | BY WORD 4 OF THE DIRECTORY
~ INFORMATION ~ > HEADER. WORD 4 OF THE ENTRY
| WORDS | | IS EITHER 0 OR THE CREATION
+-------------------------------+ | DATE OF THE FILE.
| | |
N+3 | |/
+-------------------------------+
| |
N+4 | MINUS FILE LENGTH IN BLOCKS |
+-------------------------------+
NOTE
If word 3 is zero, the given file has a
null extension.
An empty file entry appears as follows:
Location Contents
+-----------------------------+
0 | ENTRY IS ALWAYS 0000 |
+-----------------------------+
1 | MINUS THE NUMBER OF BLOCKS |
| IN THIS EMPTY FILE |
+-----------------------------+
A-2
OS/8 FILE STRUCTURES
A tentative file entry appears as a permanent file entry with a length
of zero. It is always immediately followed by an empty file entry.
When the tentative file is entered in a directory, location 3 in the
segment header becomes a pointer to this entry. The CLOSE function
inserts the length word of the tentative file entry, making it a
permanent file, and adjusts the length of the following empty file
entry (deleting that entry if the length becomes zero).
Whether or not there is a tentative file open on any device is
determined by examination of bits 9 to 11 of the system Device Control
Word Table (see section B.3.5) not the contents of location 3 in the
segment header. Zeroing these bits in the Device Control Word Table
makes the active tentative file on the device inactive. The next time
that the system has to write the directory segment, the inactive
tentative file entry is removed. The distinction between active and
inactive tentative files is made so that OS/8 can avoid spending the
time required to perform an extra read and write of the device
directory.
A.1.2 Number and Size of OS/8 Files
All files on an OS/8 device must occupy a contiguous group of blocks
on the device. The length of any file is indicated in its directory
entry, and the starting block of the file is deduced by adding
together word 1 of the segment header and the lengths of all files
whose entries precede it in the directory segment.
Each directory segment must have enough unused words at the end to
accommodate a permanent file entry (N+5 words, where N is the number
of Additional Information Words). Thus, if N is the number of
Additional Information Words the maximum number of permanent file
entries in any one segment is:
256-7 - (N+5) 244-N
MIN = [-------------] = [-----]
N+7 N+7
with N=1, MAX=40, and MIN=30. Since there are six segments in the
directory, the maximum number of files possible (with N=1) would be
240.
Finally, OS/8 devices are limited to 4095 blocks, each block being 256
words long. Thus, the maximum size of any single OS/8 file structured
device is 1,048,320 words. Blocks 0 through 6 of the device are
unavailable for file storage; therefore, the largest possible file is
4088 blocks long, or 1,046,528 words.
A.1.3 Sample Directory
The initial directory written when the OS/8 system is built looks as
follows:
A-3
OS/8 FILE STRUCTURES
Location Contents Notes
+----------+
/ 0 | 7776 | TWO ENTRIES
| 1 | 0070 | FILE STORAGE STARTS AT BLOCK 70(8)*
HEADER < 2 | 0000 | NO ADDITIONAL DIRECTORY SEGMENTS
| 3 | 0000 | NO TENTATIVE FILES.
\ 4 | 7777 | ONE ADDITIONAL INFORMATION WORD
+----------+
/ 5 | 0102 | \
| 6 | 2314 | > FILE NAME IS "ABSLDR"
PERMANENT / 7 | 0422 | /
FILE \ 10 | 2326 | FILE EXTENSION IS SV
ENTRY | 11 | 5370 | DATE IS 10/31/70
\ 12 | 7773 | LENGTH IS FIVE BLOCKS
+----------+
EMPTY / 13 | 0000 | EMPTY FILE
FILE < | |
ENTRY \ 14 | 6534 | LENGTH IS 1244(8) (676(10))BLOCKS -
+----------+ THIS IS DEPENDENT ON THE SYSTEM
| | DEVICE USED. 676 IS THE VALUE
~ ~ FOR A DECTAPE SYSTEM
| |
377(8) +----------+
*This leaves room for the OS/8 System
Areas
A.2 FILE FORMATS
There are three different standard file formats used by OS/8 and
associated system programs:
1. ASCII and Binary files.
2, Core Image files (.SV format).
3. Relocatable FORTRAN library files (LIB8.RL is the only
current example of this format).
NOTE
Binary files can contain either absolute
binary data (i.e., output from PAL8) or
relocatable binary data (i.e., output
from SABR).
A.2.1 ASCII and Binary Files
ASCII and Binary files are packed three characters into two words, as
follows:
A-4
OS/8 FILE STRUCTURES
+---------------+------------------------+
WORD 1 | CHARACTER 3 | CHARACTER 1 |
| BITS 0-3 | |
+---------------+------------------------+
WORD 2 | CHARACTER 3 | CHARACTER 2 |
| BITS 4-7 | |
+---------------+------------------------+
0 3 4 11
The following conventions are used by OS/8 system programs:
1. In ASCII files the character NULL (ASCII 000) is always
ignored. Most programs only examine the low-order 7 bits, in
ASCII files. The parity bit is usually ignored; do not
assume that this bit is set or that data transfers will
preserve it (image mode transfers, always preserve it).
2. In Binary files the binary data must be preceded by one or
more frames of leader/trailer code (ASCII 200 code). The
first character of binary data must be either 100 to 177
(octal) (an origin setting for absolute binary files), 240 to
257 (octal) (a COMMON declaration frame for relocatable
binary files), or 300 (octal), which is an origin setting.
The end of binary data is indicated by one or more frames of
leader/trailer code.
3. ASCII and Binary files are terminated by a CTRL/Z code (ASCII
232). In binary files, a CTRL/Z code data rather than
end-of-file.
A.2.2 Core Image (.SV Format) Files
A core image file consists of a header by the actual core image. The
header block is called the Core Control Block. The Core Control Block
consists of the first 128 words of the 256 word block reserved for
that purpose. The second 128 words are unused. The Core Control
Block is formatted as follows:
A-5
OS/8 FILE STRUCTURES
Location Contents Notes
CORE CONTROL BLOCK
+------------------------------------+
0 | MINUS THE NUMBER OF CORE SEGMENTS |
+------------------------------------+ 62N3 WHERE N IS THE
1 | CDF CIF (STARTING FIELD) |<--STARTING FIELD
+------------------------------------+
2 | STARTING ADDRESS |
+------------------------------------+
3 | JOB STATUS WORD |
+------------------------------------+
4 | |\ CORE SEGMENT
+------------------------------------+ | CONTROL DOUBLE WORDS
~ ~ >
+------------------------------------+ | (K IS THE NUMBER OF
2K +3 | |/ CORE SEGMENTS)
+------------------------------------+
377(8) ~ ~ REMAINDER OF BLOCK
+------------------------------------+ IS UNUSED
The format of the Job Status Word is as follows:
Bit Condition Meaning
_____________ _______
Bit 0 = 1 File does not load into locations 0 to 1777
in field 0.
Bit 1 = 1 File does not load into locations 0 to 1777
in field 1.
Bit 2 = 1 Program must be reloaded before it can be
restarted.
Bit 3 = 1 Program never uses above 8K. This is used
when Batch processing is active.
Bit 10 = 1 Locations 0 to 1777 in field 0 need not be
preserved when the Command Decoder is called.
Bit 11 = 1 Locations 0 to 1777 in field 1 need not be
preserved when the USR is called.
A-6
OS/8 FILE STRUCTURES
The Core Segment Doublewords control the reading and writing of the
associated areas of core. The format of each entry is as follows:
Location Contents Notes
+---------------------------------------------+
1 | CORE ORIGIN | MULTIPLE OF 400(8)
+---+------------------+-----------+----------+
2 | |NUMBER OF PAGES | FIELD | | BITS 0 AND 9-11
| | TO LOAD | TO LOAD | | ARE ZERO
+---+------------------+-----------+----------+
0 1 5 6 8 9 11
The core origin must be a multiple of 400 (octal). The Core Segment
Control Doublewords are sorted within the header block in order of
decreasing field and increasing origin within the same field. There
can be no more than 32 (decimal) Core Segment Control Doublewords in
any Core Control Block.
The Core Control Block for the program at the time it is loaded into
core is always saved in words 200 (octal) through 377 (octal) of block
37 (octal) (one of the system scratch blocks) on the system device.
It is placed there by the GET and RUN operations or by the ABSLDR or
LOADER programs. This Core Control Block is used when performing a
SAVE without arguments.
NOTE
The R command differs from the RUN
command in that the program's Core
Control Block is not written onto the
scratch area when using the R command.
In order to SAVE a program that has been
loaded by the R command all of the
arguments of the SAVE command must be
explicitly stated.
A-7
OS/8 FILE STRUCTURES
A.2.3 Relocatable FORTRAN Library File
A relocatable FORTRAN library consists of a library directory block
followed by relocatable binary segments. The directory block has the
following format:
Location Contents Notes
________ ________ _____
+--------------+---------------+
0 | CH1 | CH2 |\
+--------------+---------------+ | NAME OF ENTRY IN
1 | CH3 | CH4 | > SIXBIT ASCII PADDED
+--------------+---------------+ | WITH TRAILING BLANKS
2 | CH5 | CH6 |/
+--------------+---------------+
3 +-| LOAD POINTER | |
| +--------------+---------------+
4 | | ADDITIONAL ENTRIES |
| ~ . ~
5 | | . |
| +------------------------------+
| | 0 |\
| +------------------------------+ |
| | 0 | |
| +------------------------------+ > DENOTES END OF
| | 0 | | NAME ENTRIES
| +------------------------------+ |
| | 0 |/
| +------------------------------+
/ ~ ~
| +------------------------------+
\->| |-> LOADER CONTROL WORD(S)
+------------------------------+
| 0 |-> END OF LOADER CONTROL
+------------------------------+ WORDS FOR THIS ENTRY
~ ~
+------------------------------+
377(8) | |
+------------------------------+
The Load Pointer is a number between 0 and 377 (octal) which points
(relative to the beginning of the block) to an array of Loader Control
Words. The Loader Control Words have the following information:
+--------------+--------------------+
| | |
+--------------+--------------------+
0 4 5 11
NUMBER OF PAGES OCCUPIED (STARTING BLOCK OF RELO-
BY THIS SEGMENT AFTER LOADING CATABLE BINARY DATA)
(DIRECTORY BLOCK #)-1
A-8
OS/8 FILE STRUCTURES
There can be one or more Loader Control Words for each entry. The
Loader Control Words for an entry are terminated by a word of zero.
The following is a simple directory block.
Location Contents
+---------------+
0 | 1117 | NAME OF ENTRY IS "IOH___"
+---------------+
1 | 1040 |
+---------------+
2 | 4040 |
+---------------+
3 | 0376 | LOAD POINTER FOR "IOH"
+---------------+
4 | 0530 |
+---------------+
5 | 1124 | NAME OF ENTRY IS "EXIT__"
+---------------+
6 | 4040 |
+---------------+
7 | 0373 | LOAD POINTER FOR "EXIT"
+---------------+
10 | 0000 |
+---------------+
11 | 0000 | MARKS END OF ENTRIES
+---------------+
12 | 0000 |
+---------------+
13 | 0000 |
+---------------+
~ ~
+---------------+
LOADER 373 | 0207 | (RELATIVE BLOCK 10(8))(ONE
CONTROL +---------------+ PAGE LONG)
WORDS FOR 374 | 0411 | (RELATIVE BLOCK 12(8))(TWO
"EXIT" +---------------+ PAGES LONG)
375 | 0000 |
+---------------+
LOADER 376 | 2400 | (RELATIVE BLOCK 1)(12(8) PAGES
CONTROL +---------------+ LONG)
WORDS FOR 377 | 0000 |
"IOH" +---------------+
A-9
APPENDIX B
DETAILED LAYOUT OF THE SYSTEM
This appendix covers three topics: the reserved areas on the system
device, the resident portion of OS/8, and the various system tables.
B.1 LAYOUT OF THE SYSTEM DEVICE
The first 70 octal blocks (14K words) on the system device are
reserved by the OS/8 system. These blocks are used as follows:
Block(s) in Octal Contents
_________________ ________
0 System Bootstrap Routine
1-6 Device Directory
7-12 Keyboard Monitor
13-15 User Service Routine
16-25 Device Handlers
26 ENTER Processor for USR
27-50 System Scratch Blocks
51-53 Command Decoder
54-55 SAVE and DATE Overlays
56 Monitor Error Routine
57 CHAIN Processor for USR
60-63 SYSTEM ODT
64 Reserved for System Expansion
65 CCL Reminiscences
66 12K TD8E Resident code
67 CCL Overlay
File storage begins with block 70 (octal).
The system scratch blocks are used for preserving the contents of core
when the Keyboard Monitor, USR, Command Decoder, or ODT are loaded.
In addition, various system programs use the scratch area. Most
importantly, the SAVE command expects the Core Control Block to be
loaded in words 200 (octal) to 377 (octal) of block 37 (octal). The
Core Control Block is stored at those locations by the GET or RUN
command or by the ABSLDR or LOADER program.
B-1
DETAILED LAYOUT OF THE SYSTEM
A detailed breakdown of system scratch block usage follows:
Block(s) in Octal Contents
_________________ ________
27-32 The contents of locations 10000 to 11777 are
saved in this area when the USR is loaded.
33-36 The contents of locations 0 to 1777 are saved
in this area when the Command Decoder,
Keyboard Monitor, or ODT is loaded.
37 Words 200 (octal) to 377 (octal) of this
block contain the Core Control Block for the
last program loaded by the GET or RUN
command, or the ABSLDR or LOADER program.
40-47 Used as scratch storage by the ABSLDR and
LOADER programs.
50 Reserved for future expansion.
B-2
DETAILED LAYOUT OF THE SYSTEM
B.2 LAYOUT OF THE OS/8 RESIDENT PROGRAM
The top core pages in fields 0, 1, and 2 are used by the resident
portion of OS/8 and are not accessible by the user. As a general
rule, system and user programs should never destroy the contents of
locations 7600 to 7777 of any field.
The resident portion of OS/8 is structured as follows:
Location Contents Notes
________ ________ _____
+-------------------------+
7600 | WRITE OPERATION |<- NON-DESTRUCTIVE
+-------------------------+ ENTRY TO OS/8
7605 | JMP TO FIELD 1 FOR READ |<- DESTRUCTIVE
+-------------------------+ ENTRY TO OS/8
7607 | |<- ENTRY TO SYSTEM
~ SYSTEM DEVICE HANDLER ~ DEVICE HANDLER
7743 | |
+-------------------------+
7744 | |
7745 | CURRENT STARTING ADDRESS|
+-------------------------+
7746 | JOB STATUS WORD |
+-------------------------+
7747 | 0 |<- MUST ALWAYS BE ZERO
+-------------------------+
7750 | |
| RESERVED FOR DATA BREAK |
| LOCATIONS |
7755 | |
+-------------------------+
7756 | |<- THE KEYBOARD MONITOR
~ PROGRAM SETUP AREA ~ AND ODT MODIFY THIS
7777 | | AREA
+-------------------------+
B-3
DETAILED LAYOUT OF THE SYSTEM
TOP PAGE OF FIELD 1
Location Contents Notes
+--------------------------------+ \
7600 ~ OUTPUT FILE LIST (3 ENTRIES)~ |
7616 +--------------------------------+ |
7617 ~ INPUT FILE LIST ~ 0 MARKS END |
| (MAXIMUM 9 ENTRIES) <--- OF LIST | COMMAND
7641 +--------------------------------+ >DECODER
7642 | * HIGH 11 BITS OF =N |<- * BIT 0=1 | AREA
+--------------------------------+ IF COMMAND |
7643 | SPECIFIED OPTIONS | LINE TERMI- |
7645 +--------------------------------+ NATED BY |
7646 | LOW 12 BITS OF =N | ALTMODE |
+--------------------------------+ |
7647 | DEVICE HANDLER | /
7665 ~ RESIDENCY TABLE ~
+--------------------------------+
7666 | SYSTEM DATE WORD |
+--------------------------------+
7667 ~ READ OPERATION ~
7677 | (LOAD KEYBOARD MONITOR) |
+--------------------------------+
7700 ~ USR CALL AND RETURN AREA ~<- ENTRY TO USR
7740 +--------------------------------+ NOTE
____
7741 ~ USER DEVICE ~ SYSTEM ODT DESTROYS
7757 | NAME TABLE | CONTENTS OF THIS TABLE
+--------------------------------+ WHEN SETTING BREAKPOINTS
7760 ~ DEVICE CONTROL WORD TABLE ~
7776 +--------------------------------+
7777 | UNUSED | RESERVED FOR FUTURE USE
+--------------------------------+
Systems built around TD8E DECtape without the Read-Only-Memory option
use 7600 in field 2 as an extension of the system device handler.
TOP PAGE OF FIELD 2.
7600 +------------------+
| |
| | Used only for 12K TD8E
| | systems. Part of system
| | handler resides here in that
| | case.
7773 |__________________|
7774 | |
| | Four words reserved for BATCH
| | use if machine has exactly
| | 12K. Contains pointers into
| | input file.
| |
7777 +------------------+
B-4
DETAILED LAYOUT OF THE SYSTEM
If the machine has more than 12K, the top 4 locations (7774-7777) of
the last field are reserved for use by BATCH.
If a ROM (Read-Only-Memory) is being used with an 8K TD8E system,
locations 7400-7777 of field 7 are inaccessible to the user. That
core is used for system handler functions.
B.3 SYSTEM DEVICE TABLES
Each device is described to the system by entries in five system
tables. Each of these tables is fifteen words long, where the device
number is the index into the table. The five tables are described
below.
B.3.1 Permanent Device Name Table
Entries in this table specify the permanent name of each device. The
entries are computed by encoding the actual four-character device name
in a single word as follows:
1. The device name is expressed as two words in the standard
DEVICE format. For example, if the device name were "PTR"
the two words would be:
WORD 1: 2024
WORD 2: 2200
Note that when the device name is left justified; 0's are
inserted to fill four characters.
2. A single word is created by adding together these two words.
3. If word 2 is non-zero, bit 0 of the resulting word is forced
to be a one. For example, the table entry for "PTR" would be
4224.
An entry of zero means that there is no device for the corresponding
device number.
NOTE
Conventionally, device names consist
only of the characters A to Z and 0 to
9. The first character of the device
name should be alphabetic. The coding
used makes all one and two character
device names unique; however, names of
more than two characters are not unique.
For example, "PTR" and "RTP" have the
same encoding.
B-5
DETAILED LAYOUT OF THE SYSTEM
The Permanent Device Name table is fifteen locations long; it resides
in the USR. When the USR is in core the beginning of the table is in
field 1 at a location the address of which is contained in location
10036.
B.3.2 User Device Name Table
Entries are made in this table whenever the user performs an ASSIGN
and are restored to zero by a DEASSIGN. These entries have the same
format as those in the Permanent Device Name Table.
The User Device Name Table resides in locations 17741 through 17757.
B.3.3 Device Handler Residency Table
When a device handler is loaded by the USR, the entry in this table
for the device loaded (and entries for all devices whose handlers are
co-resident, if any) is set to contain the entry point for the device
handler. Entries other than those that contain an address above 7600
(thus referring to the system handler) are restored to 0 when a RESET,
DECODE or CHAIN function is executed. When a program exits to the
Keyboard Monitor this table is not cleared. The Keyboard Monitor
Commands GET, RUN, R, SAVE, and START (with no explicit address) clear
this table.
NOTE
Since the system device handler is
always resident the first entry (SYS is
always device number 1) in the Device
Handler Residency Table is always 7607
(the entry point of the system device
handler).
The Device Handler Residency Table resides in locations 17647 through
17665.
B.3.4 Device Handler Information Table
Each entry in this table contains all the information needed by the
USR to load the corresponding handler. The format of these entries is
as follows:
B-6
DETAILED LAYOUT OF THE SYSTEM
Bit Condition Meaning
_____________ _______
Bits 0 = 1 If this is a two page device handler.
Bits 1 to 4 Contain the relative block location of
the device handler record on the system
device. This is computed by subtracting
15 (octal) (one less than the first
device handler block) from the actual
block number.
Bits 5 to 11 Contain the offset of the handler entry
point from the beginning of the page.
Note that the entry points to all
handlers must be in the first page.
If an entry is 0 the corresponding device handler is not saved in any
of the device handler storage blocks. This is always true of device
number 1 (the system device) and for all device numbers that are not
used in a given configuration. The Device Handler Information Table
is 15 locations long and resides in the USR. When the USR is in core
the beginning of the table is in field 1 at a location the address of
which is contained in location 10037.
B.3.5 Device Control Word Table
Entries in this table specify special device characteristics,
including the physical device type. The entry format is as follows:
Bit Condition Meaning
_____________ _______
Bit 0 = 1 If the device is file-structured.
Bit 1 = 1 If the device is read-only.
Bit 2 = 1 If the device is write-only.
Bits 3 to 8 Contain the physical device type code
(described below),
Bits 9 to 11 For file structured devices, these bits
contain the directory block number of
the currently active tentative file. If
bits 9 to 11 are zero, there is no
active tentative file on the device.
For non-file structured devices, bits 9
to 11 are always zero. Bits 9 to 11 are
reset to zero by the commands GET, RUN,
R, SAVE, START (with no explicit
address) and optionally by the USR
functions RESET and DECODE.
B-7
DETAILED LAYOUT OF THE SYSTEM
The device type is a number between 0 and 77 (octal), of which 0
through 20 (octal) are currently assigned to existing devices, as
follows:
Device Code Device
___________ ______
0 Teletype
1 High-speed paper tape reader
2 High-speed paper tape punch
3 Card Reader
4 Line Printer
5 RK8 Disk
6 256K Disk (RF08)
7 512K Disk (RF08 + RS08)
10 768K Disk (RF08 + 2 RS08's)
11 1024K disk (RF08 + 3 RS08's)
12 32K Disk (DF32)
13 64K Disk (DF32 + DS32)
14 96K Disk (DF32 + 2 DS32's)
15 128K Disk (DF32 + 3 DS32's)
16 DECtape
17 LINCtape (PDP-12 only)
20 TM8E Magnetic Tape
21 TD8E DECtape
22 BATCH handler
23 RK8E Disk
24 NULL
25-26 reserved for future disks
27 TA8E Cassette
30 VR12 Scope
31-37 reserved for future use by DEC
40-57 reserved for use by users
The Device Control Word Table resides in locations 17760 through
17776.
B.3.6 Device Length Table
There is a sixth table that is not normally considered part of the
system tables. This is the Device Length Table and is used only by
PIP to perform the /Z (zero directory) and /S (compress device)
options. This table is 64 locations long, one entry for each possible
device type. In this table an entry of 0 means that the corresponding
device is non-file structured; otherwise the entry contains the
negative of the number of available 256-word blocks on the device.
For example, the entry for a 256K disk would be 6000 (octal) (minus
2000 (octal), or 1024 (decimal), 256-word blocks).
B-8
DETAILED LAYOUT OF THE SYSTEM
The Device Length Table resides in PIP. When PIP is brought into core
the Device Length Table is in locations 13600 to 13677. When new
device types are added to the system this table should be patched with
ODT to reflect the device length of the new device.
A similar table occurs in RESORC which the user may wish to patch. It
is located in field 0 locations 2000-2377 and contains 64 four-word
entries; one entry for each device type. Words 1 and 2 of an entry
are the names of the device (in sixbit) and word 3 is the negative of
the number. Word 4 of the entry should be 0 for non-standard devices.
B-9
APPENDIX C
SYSTEM ERROR CONDITIONS AND MESSAGES
This is a summary of all error messages that are a result of system
errors. These errors are also described in the relevant sections of
this manual and in the OS/8 HANDBOOK.
C.1 SYSTEM HALTS
Errors that occur as a result of a major I/O failure on the system
device can cause a system halt to occur. These are as follows:
Value of PC Meaning
___________ _______
00601 A read error occurred while attempting to
load ODT. Return to the Keyboard Monitor by
restarting at 07605.
07461 An error occurred while reading a program
into core during a CHAIN. Return to the
Keyboard Monitor by restarting at 07605.
07605 An error occurred while attempting to write
the Keyboard Monitor area onto the system
scratch blocks. Verify that the system
device is not WRITE LOCKed and restart at
location 07600 to try again.
07702 A user program has performed a JMS to 7700 in
field 0. This is a result of trying to call
the USR without first performing a CIF 10. As
location 07700 has been destroyed, the user
must re-bootstrap the system.
07764 A read error occurred while loading a
program. Return to the Keyboard Monitor by
restarting at 07605.
07772 A read error occurred on the system scratch
area while loading a program. Return to the
Keyboard Monitor by restarting at 07605.
10066 An input error occurred while attempting to
restore the USR. Return to the Keyboard
Monitor by restarting at 07605.
10256 A read error occurred while attempting to
load the Monitor by restarting at 07605.
C-1
SYSTEM ERROR CONDITIONS AND MESSAGES
17676 An error occurred while attempting to read
the Keyboard Monitor from the system device.
Try again by restarting at location 07605. DO
NOT PRESS CONTINUE.
17721 An error occurred while saving the USR area.
Verify that the system device is not WRITE
LOCKed, and press CONTINUE to try again.
17727 An error occurred while attempting to read
the USR from the system device. Return to
the Keyboard Monitor by restarting at 07605.
17736 An error occurred while reading the scratch
blocks to restore the USR area. Return to
the Keyboard Monitor by restarting at 07605.
Also, there is one halt in the LOADER program:
00005 A parity error occurred when attempting to
overlay the LOADER from the system scratch
blocks. Return to the Keyboard Monitor by
restarting at 07605, and try again.
After retrying the operation which caused the failure, if the error
persists, it is the result of a hardware malfunction or a parity error
in the system area. Run the appropriate diagnostic program to check
the device and rebuild the system.
C.2 USR ERRORS
Fatal errors that occur during operation of the USR cause the message:
MONITOR ERROR n AT xxxxx
to be printed. In these cases, the value "n" describes the error and
"xxxxx" is the address of the call to the USR that caused the error.
The six Monitor errors are:
Message Meaning
_______ _______
MONITOR ERROR 1 AT xxxxx File length in CLOSE function is
[CLOSE ERROR] too large.
MONITOR ERROR 2 AT xxxxx An I/O error occurred while at-
[DIRECTORY I/O ERROR] tempting to read or write a
directory block. This is generally
caused by the device being WRITE
LOCKed.
MONITOR ERROR 3 AT xxxxx The device handler required for a
[DEVICE HANDLER NOT IN CORE] file operation (LOOKUP, ENTER,
CLOSE) is not in core.
C-2
SYSTEM ERROR CONDITIONS AND MESSAGES
MONITOR ERROR 4 AT xxxxx Illegal call to the USR; either an
[ILLEGAL USR CALL] attempt has been made to call the
USR from locations 10000 to 11777
or a device number of zero was
specified.
MONITOR ERROR 5 AT xxxxx I/O error occurred while reading or
[I/O ERROR ON SYS] writing on the system device.
Verify that the system device is
not WRITE LOCKed.
MONITOR ERROR 6 AT xxxxx Directory overflow occurred (see
[DIRECTORY OVERFLOW] section A.1.2 for limitations on
number of directory entries).
In addition to the MONITOR ERROR messages, system and user programs
can use the USR to print:
USER ERROR n AT xxxxx
by using the ERROR function. In this case the value of "n" is
user-defined and "xxxxx" is the address of the call to the USR.
Currently, two USER ERROR numbers have been assigned:
Message Meaning
_______ _______
USER ERROR 0 AT xxxxx An I/O error occurred while
attempting to load a program with
the GET, RUN, or R command.
USER ERROR 1 AT xxxxx While running a FORTRAN or SABR
program, an attempt was made to
call a subroutine that had not been
loaded.
If an I/O error is made during the monitor CHAIN function the message
CHAIN ERR
is generated, and control returns to the keyboard.
Following either a MONITOR ERROR message or a USER ERROR message the
USR exits to the keyboard Monitor; the current contents of core are
preserved and bit 2 of the Job Status Word is set to a 1 to prevent
continuing from the error.
C.3 KEYBOARD MONITOR ERRORS
In addition to the USR errors described previously, the following
errors can occur after a command is given to the Keyboard Monitor:
C-3
SYSTEM ERROR CONDITIONS AND MESSAGES
Message Meaning
_______ _______
aaaa? The Keyboard Monitor cannot interpret
the command "aaaa". For example if the
user types HELLO the system will respond
HELLO?
BAD ARGS Arguments to a SAVE command are
inconsistent, or illegal.
BAD CORE IMAGE The file requested with an R, RUN, or
GET command is not a core image file.
BAD DATE Improper syntax in a DATE command.
device NOT AVAILABLE The permanent device name specified in
an ASSIGN, SAVE, RUN, or GET command
does not exist.
ILLEGAL ARG The SAVE command was not expressed
correctly.
name NOT FOUND The file name specified was not located
on the device indicated. This error can
also be caused by trying to RUN or GET
from an output only device.
NO!! A START command (with no address
specified) is prohibited when bit 2 of
the Job Status Word (location 07746) is
a 1.
NO CCL! Command was a valid CCL command but
CCL.SV is not on the system.
SAVE ERROR An I/O error occurred while saving the
program. The contents of core remain
intact.
SYSTEM ERR An error occurred while doing I/O to the
system device.
TOO FEW ARGS An argument has been omitted from a
command.
C.4 CCL ERROR MESSAGES
Message Meaning
_______ _______
BAD DEVICE The device specified in a CCL command is
not of the correct form, (e.g.,
DTA0.PA:).
C-4
SYSTEM ERROR CONDITIONS AND MESSAGES
BAD EXTENSION Either an extension was specified
without a file name (e.g., DTA1:.PA) or
two extensions were specified (e.g.,
DTA1:FILE.PA.BN).
BAD MONITOR The version of the Keyboard Monitor
being used is not compatible with CCL.
A new version of the monitor must be
obtained from Digital before CCL can be
used.
BAD NUMBER A CCL command which uses the #
construction does not have the full
16-digit specification that is required.
BAD RECOLLECTION An attempt was made to use a previously
remembered argument when no argument was
saved. This error occurs when no
argument was previously saved or when
the DATE command has been used since the
argument was saved.
BAD SWITCH OPTION The character used with a slash (/) to
indicate an option is not a legal
option.
CANNOT CHANGE CORE A CORE command was issued while the
CAPACITY WHILE RUNNING BATCH program was running.
BATCH
%CANT REMEMBER The argument specified in a CCL command
line is too long to be remembered or an
I/O error occurred.
CCL 3X OVERLAY & The version of CCL being used is not
MONITOR INCOMPATIBLE compatible with the Keyboard Monitor
present on the system. Type R CCL to
retry.
COMMAND LINE OVERFLOW The command line specified with the @
construction is more than 512 characters
in length.
COMMAND TOO LONG The length of a text argument in a MUNG
command is too long.
CONTRADICTORY SWITCHES Either two CCL processor switches were
specified in the same command line
(e.g., FILE-PA-FT) or the file extension
and the processor switch do not agree
(e.g., FILE.FT-BA).
name DOES NOT EXIST The device with the name given is not
present on the OS/8 system.
C-5
SYSTEM ERROR CONDITIONS AND MESSAGES
ERROR IN COMMAND A command not entered directly from the
console terminal is not a legal CCL
command. This error occurs when the
argument of a UA, UB, or UC command was
not a legal command.
ILLEGAL * OR ? An * or ? was used in a CCL command that
does not accept the wild card
construction. Only CCL commands that
run FOTP or DIRECT allow the wild card
construction.
ILLEGAL SYNTAX The CCL command line was formatted
incorrectly.
INPUT ERROR READING CCL cannot read the file specified with
INDIRECT FILE the @ construction.
I/O ERROR ON SYS: An error occurred while doing I/O to the
system device. The system must be
restarted at 7600 or 7605. Do
not press CONT. as that will surely
cause further errors.
I/O ERROR TRYING TO An I/O error occurred while CCL was
RECALL trying to remember an argument.
NO CCL! CCL.SV is not present on the system
device.
NOT ENOUGH CORE The number specified in a CORE command
is larger than the number of 4K core
banks on the system.
name NOT FOUND The file with the name given is not
present on the specified device, or the
user tried to input from an output-only
device.
%SUPERCEDED The file specified in a MAKE command
already exists. This is a warning
message indicating that the file is
being replaced.
SWITCH NOT ALLOWED HERE Either a CCL option was specified on the
left side of the < or was used when not
allowed. For example: COMPARE FILE-NB.
TOO MANY FILES Too many files were included in a CCL
command.
C-6
SYSTEM ERROR CONDITIONS AND MESSAGES
C.5 COMMAND DECODER ERRORS
The following errors are printed by the Command Decoder. After the
error message, the Command Decoder starts a new line, prints a * and
waits for another command line. The erroneous command is ignored.
Message Meaning
ILLEGAL SYNTAX The command line is formatted
incorrectly.
TOO MANY FILES More than three output files or nine
input files were specified (regular
mode) or > 1 output or > 5 input
(special mode).
name NOT FOUND The specified input file name was not
found on the device indicated.
C-7
APPENDIX D
PROGRAMMING NOTES
This appendix is a potpourri of ideas and techniques that have proven
useful in programming the PDP-8. OS/8 users may find some use in their
own programs for the techniques mentioned here.
D.1 The Default File Storage Device, DSK
D.2 Modification to Card Reader Handler
D.3 Suppression of Carriage Return/Line Feed in FORTRAN I/O
D.4 Accessing the System Date in a FORTRAN Program
D.5 Determining Core Size on PDP-8 Family Computers
D.6 Using PRTC12-F to Convert OS/8 DECtapes to OS/12 LINCtapes
D.7 Notes on Loading Device Handlers
D.8 Available Locations in the USR Area
D.9 Accessing Additional Information Words in OS/8
D.10 SABR Programming Notes
D.1 THE DEFAULT FILE STORAGE DEVICE, DSK
The Command Decoder, as noted earlier, makes certain assumptions about
the I/O device where none is explicitly stated. Namely, on all output
files where no device name is given, the device DSK is assumed. On
the first input file where no device name is given, DSK is assumed.
Subsequent input files assume the same device as the previous input
file. This convention was adopted to simplify typing command lines.
The permanent device name DSK is assigned when the system is built.
On all standard systems, DSK is equivalent to SYS. A useful technique
is to use the ASSIGN command to redefine the meaning of DSK
temporarily. For example, where device DTA0 is equivalent to DSK and
it becomes desirable to change DSK to DTA1, the following command can
be given:
.ASSIGN DTA1 DSK
D-1
PROGRAMMING NOTES
DTA1 remains the default file storage device until it is assigned a
new name or a DEASSIGN command is executed. This technique is
considerably easier to use than rebuilding the entire system.
If 'DSK' has not been assigned via the ASSIGN command, then 'DSK'
always exists and has internal device number 2. User programs wishing
to use DSK should do an INQUIRE to find its number in case the
operator has re-assigned it.
D.2 MODIFICATION TO CARD READER HANDLER
The standard card reader handler for OS/8 uses the DEC029 standard
card codes. Some installations may prefer to use the DEC026 codes
instead. This can be done by changing the card conversion codes with
the BUILD command ALTER.
1. Call OS/8 BUILD by typing:
RUN SYS:BUILD
in response to the dot printed by the Keyboard Monitor.
2. Load the card reader handler as described on page 2-42 of the
OS/8 HANDBOOK.
3. Use the ALTER command (see page 2-49 of the OS/8 HANDBOOK)
to make the following changes:
CHANGE RELATIVE LOCATION FROM TO
________________________ ____ __
104 3203 7735
105 4007 4076
106 3502 0774
114 7514 3314
115 0577 1002
116 3637 0305
124 0104 3204
125 1211 1273
126 3374 3606
127 0641 1341
134 7316 3716
135 3410 1175
136 1376 3401
The new system will have modified card codes.
Note that this procedure does not affect FORTRAN run time card input
with READ (3,n). The conversion table for FORTRAN is UTILTY.SB on
source DECtape #2. (DEC-S8-OSYSB-A-UA2)
D-2
PROGRAMMING NOTES
026 PUNCH CARD CODES
Octal 8-bit DEC026 Octal 8-bit DEC026
CODE CODE CHARACTER CODE CODE CHARACTER
240 BLANK SPACE 300 8-4 @
241 12-8-7 ! 301 12-1 A
242 0-8-5 " 302 12-2 B
243 0-8-6 # 303 12-3 C
244 11-8-3 $ 304 12-4 D
245 0-8-7 % 305 12-5 E
246 11-8-7 & 306 12-6 F
247 8-6 ' 307 12-7 G
250 0-8-4 ( 310 12-8 H
251 12-8-4 ) 311 12-9 I
252 11-8-4 * 312 11-1 J
253 12 + 313 11-2 K
254 0-8-3 ' 314 11-3 L
255 11 - 315 11-4 M
256 12-8-3 . 316 11-5 N
257 0-1 / 317 11-6 O
260 0 0 320 11-7 P
261 1 1 321 11-8 Q
262 2 2 322 11-9 R
263 3 3 323 0-2 S
264 4 4 324 0-3 T
265 5 5 325 0-4 U
266 6 6 326 0-5 V
267 7 7 327 0-6 W
270 8 8 330 0-7 X
271 9 9 331 0-8 Y
272 11-8-2 : 332 0-9 Z
273 0-8-2 ; 333 11-8-5 [
274 12-8-6 < 334 8-7 \
275 8-3 = 335 12-8-5 ]
276 11-8-6 > 336 8-5 ^
277 12-8-2 ? 337 8-2
NOTE
On some IBM 026 Keyboards this character
is graphically represented as a [].
A card containing an 8-2 in column 1
with all remaining columns blank is an
end-of-file card.
D-3
PROGRAMMING NOTES
D.3 SUPPRESSION OF CARRIAGE RETURN/LINE FEED IN FORTRAN
It is often desirable to suppress the automatic carriage return/line
feed (CR/LF) following FORTRAN WRITE statements to achieve an easily
readable text. The following three methods in OS/8 FORTRAN can be
used to achieve this result:
1. Follow the I/O list of a WRITE statement with a comma. Thus,
the following statements:
WRITE (1,100) N,
100 FORMAT (1X,15HTHE VALUE OF A(,I2,5H) IS )
READ (1,101)A(N)
101 FORMAT (F8.4)
result in the following single line (assume N has a value of
12 and a value of 147.83 is being input):
THE VALUE OF A(12) IS 147.83
2. Use of an empty field print statement enables a text to be
printed without a following CR/LF when there is no variable
to be printed. For example:
WRITE (1,102)IDUMMY,
102 FORMAT ('DESIRED TEXT',I0)
3. READ statement using break character, as follows:
READ (1,101) IA,IB,IC
101 FORMAT ('A=',I1,'B=',I1,'C=',I1)
results in no CR/LF after each phrase is printed. That is,
the output is all printed on a single line.
D.4 ACCESSING THE SYSTEM DATE IN A FORTRAN PROGRAM
The availability of the system Date word in location 17666 is useful
to many OS/8 programs. The following FORTRAN program illustrates how
the Date can be accessed in SABR code:
C PROGRAM PRINTS THE CURRENT DATE
C
S DUMMY DATE
S TAD I DATE
S DCA TEMP
S TAD TEMP
S AND (7
S DCA \IYR
S TAD TEMP
S RAR;RTR
S AND (37
D-4
PROGRAMMING NOTES
S DCA \IDAY
S TAD TEMP
S CLL RAL;RTL;RTL
S AND (17
S DCA \IMO
WRITE (1,100) IMO,IDAY,IYR
100 FORMAT (/'DATE: 'I2'-'I2'-197'I1/)
CALL EXIT
S CPAGE 2
SDATE, 6211
S 7666
STEMP, 0
D.5 DETERMINING CORE SIZE ON PDP-8 FAMILY COMPUTERS
Many times system programs need to determine the amount of core
available to them at run time. For example, the OS/8 system programs
LOADER, PAL8, and CREF perform this calculation. Because of
differences in the extended memory control of PDP-8 family computers,
subroutines that work on one machine might not work on another.
The following three conditions cause the most difficulty:
1. On a PDP-8 with an extended memory control, addressing
nonexistent memory from field 0 causes the following
instruction to be skipped and the contents of the
corresponding field 0 location to be executed. For example:
CDF 70 /NONEXISTENT FIELD
TAD I(X) /EXECUTED LOCATION X
HLT /THIS INSTRUCTION SKIPPED
.
.
.
X, CLA CLL CML RAR /LOAD 4000
The preceding code causes 4000 to be loaded into the AC and
the HLT instruction to be skipped when executed on a PDP-8.
2. On a PDP-12 with an odd number of 4K banks (12K, 20K, 28K),
all reads in the first nonexistent field load zeros. Reads
to higher fields, as well as all reads to nonexistent memory
on a machine with an even number of 4K banks load all one
bits.
3. The PDP-8/L normally treats all CDF's to fields 2 through 7
as NOP's. (It tests bits 6 to 7 of all CDF and CIF
instructions for 0's before executing the IOT.) However,
there is a special 12K option for the PDP-8/L called a BM08.
With this option a CDF to field 2 is valid, but a CDF's to
fields 4 through 7 remain NOP's.
D-5
PROGRAMMING NOTES
For those who are interested, the following subroutine has been tested
on the PDP-8, 8/S, 8/L, 8/I, 8/E, PDP-12, and LINC-8 computers. For
the purpose of this example, it is assembled at 00200.
/SUBROUTINE TO DETERMINE CORE SIZE.
/THIS SUBROUTINE WORKS ON ANY PDP-8 FAMILY
/COMPUTER. THE VALUE, FROM 1 TO 10 (OCTAL),
/OF THE FIRST NON-EXISTENT MEMORY FIELD IS
/RETURNED IN THE AC.
/NOTE - THIS ROUTINE MUST BE PLACED IN FIELD 0
0200 0000 CORE, 0
0201 7300 CLA CLL
0202 6201 COR0, CDF 0 /(NEEDED FOR PDP-8L)
0203 1237 TAD CORSIZ /GET FIELD TO TEST
0204 7006 RTL
0205 7004 RAL
0206 0217 AND COR70 /MASK USEFUL BITS
0207 1232 TAD COREX
0210 3211 DCA .+1 /SET UP CDF TO FIELD
0211 6201 COR1, CDF \N /N IS FIELD TO TEST.
0201 1635 TAD I CORLOC /SAVE CURRENT CONTENTS
0213 7000 COR2, NOP /(HACK FOR PDP-8!)
0214 3211 DCA COR1
0215 1213 TAD COR2 /7000 IS A "GOOD" PATTERN
0216 3635 DCA I CORLOC
0217 0070 COR70, 70 /(HACK FOR PDP-8.,NO-OP)
0020 1635 TAD I CORLOC /TRY TO READ BACK 7000
0221 7400 CORX, 7400 /(HACK FOR PDP-8,.NO-OP)
0022 1221 TAD CORX /GUARD AGAINST "WRAP AROUND"
0223 1236 TAD CORV /TAD (1400)
0224 7640 SZA CLA
0225 5232 JMP COREX /NON-EXISTENT FIELD EXIT
0226 1211 TAD COR1 /RESTORE CONTENTS DESTROYED
0227 3635 DCA I CORLOC
0230 2237 ISZ CORSIZ /TRY NEXT HIGHER FIELD
0231 5202 JMP COR0
0232 6201 COREX, CDF0 /LEAVE WITH DATA FIELD 0
0233 1237 TAD CORSIZ /1ST NON-EXISTENT FIELD
0234 5600 JMP I CORE
0235 0221 CORLOC, CORX /ADDRESS TO TEST IN EACH FIELD
0236 1400 CORV, 1400 /7000+7400+1400=0
0237 0001 CORSIZ, 1 /CURRENT FIELD TO TEST
D.6 USING PRTC12-F TO CONVERT OS/8 DECTAPES TO OS/12 LINCTAPES
Many users of OS/8 on the PDP-12 will be interested in the fact that,
since OS/8 uses an identical file structure on all devices, PDP-8
DECtape in OS/8 format may be directly copied to OS/8 LINCtapes by the
PRTC12-F program.
D-6
PROGRAMMING NOTES
The PRTC12-F program uses the PDP-12 TC12-F hardware option to read
DECtapes and convert these tapes to LINCtape. This hardware option is
required to read DECtapes on the PDP-12
The PRTC12-F program is described in the document DEC-12-YIYA-D. This
document describes the program operation in detail, and must be read
before attempting to use PRTC12-F. The operations that convert OS/8
format DECtapes are as follows:
1. Mount the OS/8 DECtape on unit 1 and a PDP-12 LINCtape
formatted with 129 words per block on unit 2.
2. When the READ questionnaire is displayed, respond as follows
(responses are underlined; the character } stands for
carriage return and ~ stands for line feed):
READ 1777 } BLOCKS
TAPE FORMAT A } UNIT 1 }
STARTING WITH BLOCK 0 } ~
etc.
3. When the WRITE questionnaire is displayed, respond as
follows:
WRITE THE RESULT
IN TAPE FORMAT B } ON UNIT 2 }
STARTING AT BLOCK 0 } ~
etc.
D.7 NOTES ON LOADING DEVICE HANDLERS
D.7.1 Problem With Multiple Input Files
There is a problem associated with reusing Device Handler areas in
OS/8. This problem is best illustrated by an example:
Assume a program has reserved locations 1000-1377 for its input
handler and locations 7400-7577 for its output handler. If the
program gives a USR FETCH command to load the DTA1 handler as an input
device handler, all 8 DECtape handlers will load into 1000-1377, since
they are all co-resident. If another FETCH is issued to load the DTA2
handler as an output device handler, that handler will not be loaded,
because it shares space with the DTA1 handler currently in core. This
is fine - however, if the user now switches input devices and FETCHes
the paper tape reader handler as an input device handler it will
destroy the DTA2 handler and the next attempt to output using the DTA2
handler will produce errors. There are two ways to get around this
problem.
D-7
PROGRAMMING NOTES
1. Always assign the handler which you expect to stay in core
the longest first. Most programs can process more than one
input file per program step (e.g., an assembly pass is one
program step) but only one output file; therefore, they
assign the output handler before any of the input handlers.
In the above example, the problem would be eliminated if the
DTA2 handler were assigned first.
2. Always give a USR RESET call before each FETCH. Obviously,
this call should not delete any open output files. This
means that the USR will always load the new handler, even if
another copy is in core. The user must FETCH the output
handler again before issuing the USR CLOSE call, otherwise
the USR will determine that the output handler is not in core
and give a MONITOR ERROR 3 message.
8K FORTRAN uses this second method for device-independent I/O at run
time.
D.7.2 Dynamically Loading Device Handlers
Some programs which use dynamic core allocations will want to use OS/8
Device handlers but cannot afford to always allocate the maximum of
two pages per handler. The following is a subroutine which loads a
device handler dynamically, returning its entry in the AC. It assumes
that the name of the handler is in locations NAME1 and NAME2, and a
subroutine GETPAG exists which gets a page from the bottom of
available field 0 of storage and returns its address in the AC. This
example subroutine runs in field 1 and can only be called from field
1, but can be rewritten for any other possibility.
ASSIGN, 0
TAD NAME1
DCA N1
TAD NAME2
DCA N2 /MOVE DEVICE NAME INTO "INQUIRE" COMMAND
CDF CIF 10
JMS I (7700
10 /USRIN - FORCE USR INTO CORE
JMS I (200
12 /INQUIRE
N1, 0
N2, 0
LOC1, 0
JMP ASSERR /NO SUCH DEVICE - QUIT
TAD LOC1
SZA /IS THE HANDLER ALREADY IN CORE?
JMP I ASSIGN /YES - RETURN ITS ENTRY POINT
JMS GETPAG /GET A PAGE DYNAMICALLY
DCA LOC2
ASSTRY, TAD N2 /LOAD DEVICE NUMBER
D-8
PROGRAMMING NOTES
JMS I (200
1 /FETCH
LOC2, 0 /PAGE TO FETCH INTO
JMP TWOPAG /FAILED - MUST BE A TWO-PAGE HANDLER
TAD LOC2
JMP I ASSIGN /RETURN ENTRY POINT
TWOPAG, JMS GETPAG /GET ANOTHER PAGE
ISZ LOC2 /SET "TWO PAGE HANDLER ALLOWED" BIT
CLA
JMP ASSTRY /FETCH WILL SUCCEED THIS TIME
ASSERR, ..... /ERROR ROUTINE
D.8 AVAILABLE LOCATIONS IN THE USR AREA
A few programs may need additional storage space in field 1 when the
USR is in core. A number of locations in the USR area (10000 to
11777) are available and may be used whenever the USR is in core. The
locations are as follows:
1. Locations 10000 to 10006 are available for scratch storage
and/or ODT breakpoint usage, without restriction.
2. All auto-index registers (locations 10010 to 10017) may be
used, but these locations are destroyed by USR operations.
3. Location 10020 to 10037 may be used as scratch storage with
no restrictions.
4. Locations 11400 to 11777 are used by the USR to preserve the
last directory segment read while performing a LOOKUP, ENTER,
or CLOSE operation. Location 10007 contains a key specifying
which segment of which device is currently in core.
Any user program may use locations 11400 to 11777 as scratch
storage as long as location 10007 is set to 0 before the
first use. Of course, the LOOKUP, ENTER, and CLOSE
operations will read a directory segment into 11400 to 11777
and set 100007 to a non-zero value again.
D.9 ACCESSING ADDITIONAL INFORMATION WORDS IN OS/8
In all of these cases, the USR must have been previously brought into
core with the USRIN function.
D.9.1 After a LOOKUP or ENTER
After a LOOKUP or ENTER, location 10017 points to the length word of
the file entry. To get a pointer to the first Additional Information
Word, a program would execute the following code:
D-9
PROGRAMMING NOTES
CDF 10
TAD I (1404 /GET # OF ADDITIONAL INFORMATION WORDS
/FROM DIRECTORY
SNA
JMP NONE /NO ADDITIONAL INFORMATION WORDS
TAD I (0017
DCA POINTER
.
.
.
"POINTER" now points to the first Additional Information Word.
D.9.2 After a CLOSE
Because CLOSE is a legal operation even if no output file is present,
it is not suggested that Additional Information Words be modified
following a CLOSE. To alter the Additional Information Words of a
permanent file, do a LOOKUP to get the directory segment into core,
then alter the words and rewrite the directory segment.
D.9.3 Rewriting the Current Directory Segment
Whenever a user program changes the Additional Information Words of a
file, it must rewrite the directory segment containing that file entry
in order to make sure the changes are permanently recorded.
The following code, which must be in field 1, will rewrite the current
directory segment:
CDF 10 /CODE IS IN FIELD 1
TAD 7 /GET DIRECTORY KEY WORD
AND (7 /EXTRACT SEGMENT NUMBER
DCA SEGNO
CIF 0
JMS I 51 /LOC 51 POINTS TO THE DEVICE HANDLER
4210 /WRITE OPERATION
1400 /DIRECTORY SEGMENT CORE ADDRESS
SEGNO, 0
JMP ERROR /ERROR REWRITING DIRECTORY
Location 10051 will always point to the device handler entry point
used to read in the last directory segment, following a LOOKUP or
ENTER operation.
D-10
PROGRAMMING NOTES
D.10 SABR PROGRAMMING NOTES
D.10.1 Optimizing SABR Code
There are two types of users who will be using the SABR assembler -
those who like the convenience of page-boundary-independent code and
are willing to pay the price for it, and those who need a relocatable
assembler but are still very location conscious. These optimizing
hints are directed to the latter user.
One way to beat the high cost of non-paged code is to Page It
Yourself. This is done by using the LAP (Leave Automatic Paging)
pseudo-op and the PAGE pseudo-op to force paging where needed. This
saves 2 to 4 instructions per page from elimination of the page
escape. In addition, the fact that the program must be properly
segmented may save a considerable amount.
Wasted core may be reduced by eliminating the ever-present CDF
instructions which SABR inserts into a program. This is done by using
n fake indirects". Define the following op codes:
OPDEF ANDI 0400
OPDEF TADI 1400
OPDEF ISZI 2400
OPDEF DCAI 3400
.
.
.
These codes correspond to the PDP-8 memory reference instructions but
they include an indirect bit. The difference can best be appreciated
by an example:
If X is off-page, the sequence
LABEL, SZA
DCA X
is assembled by SABR into
LABEL, SZA
JMS 45
SKP
DCA I (X)
or four instructions and one literal.
The sequence
D-11
PROGRAMMING NOTES
PX, X
.
.
.
LABEL, SZA
DCAI PX
assembles into three instructions for a saving of 40 percent. Note,
however, that the user must be sure that the data field will be
correct when the code at LABEL is encountered. Also note that the
SABR assumes that the Data Field is equal to the Instruction Field
after a JMS instruction, so subroutine returns should not use the JMPI
op code.
The standard method to fetch a scalar integer argument of a subroutine
in SABR is:
Code
IARG, DUMMY X
0
SUBR, BLOCK 2
TAD I SUBR
DCA X
INC SUBR#
TAD I SUBR
DCA X#
INC SUBR#
TAD I X
DCA IARG
.
.
.
X, BLOCK 2
This code requires 19 words of core and takes several hundred
microseconds to execute. The following sequence:
Code
IARG, 0
SUBR, BLOCK 2
TAD I SUBR
DCA X
INC SUBR#
TADI SUBR#
DCA IARG
INC SUBR#
X, HLT /THIS IS A CDF
TAD I IARG
DCA IARG
.
.
.
takes only 14 words and executes in approximately 1/3 the time.
D-12
PROGRAMMING NOTES
D.10.2 Calling the USR and Device Handlers from SABR Code
One important thing to remember is that any code which calls the USR
must not reside in locations 10000 to 11777. Therefore, any SABR
routine which calls the USR must be loaded into a field other than 1
or above location 2000 in field 1. To call the USR from SABR use the
sequence:
CPAGE n /N=7+(# OF ARGUMENTS)
6212 /CIF 10
JMS 7700 /OR 200 IF USR IN CORE
REQUEST
ARGUMENTS /OPTIONAL DEPENDING ON REQUEST
ERROR RETURN /OPTIONAL DEPENDING ON REQUEST
To call a device handler from SABR use the sequence:
CPAGE12 /10 IF "HAND" IN PAGE 0
6202 /CIF 0
JMS I HAND /DO NOT USE JMSI
FUNCT
ADDR
BLOCK
ERROR RETURN
SKP
HAND, 0 /"HAND" MUST BE ON SAME PAGE
/AS CALL, OR IN PAGE 0!!
D-13
APPENDIX E
CHARACTER CODES AND CONVENTIONS
Table E-1 contains a list of the control characters used by OS/8 and
associated system programs. Table E-2 contains the OS/8 character
set, which is a subset of the complete ASCII code, the unlisted codes
are generally not used by OS/8 or the system programs. Note the
following:
1. On some terminals, the character back-arrow (_) is replaced
by an underline (_) character, and the up-arrow (^) is
replaced by circumflex (^).
2. Some terminals use parity codes rather than forcing the
leading bit of the 8-bit character code to be a 1. To avoid
problems, OS/8 system programs always ignore the parity bit
during ASCII input.
3. OS/8 does not handle lower case characters (octal codes 341
through 372). The exceptions to this are the editors, EDIT
and TECO. The KL8E and LPSV handlers can be modified to
handle lower case.
Table E-1
OS/8 Control Characters
+---------------------------------------------------------------------+
| Octal |
| 8-bit Character |
| Code Name Remarks |
+---------------------------------------------------------------------+
| 000 null Ignored in ASCII input. |
| |
| 200 leader/trailer Leader/trailer code precedes and|
| follows the data portion of binary|
| files. |
| |
| 203 CTRL/C OS/8 break character, forces return|
| to Keyboard Monitor, echoed as ^C. |
| |
| 207 BELL CTRL/G. |
| |
| 211 TAB CTRL/I, horizontal tabulation. |
| |
| 212 LINE FEED Used as a control character by the|
| Command Decoder and ODT. |
| |
| 213 VT CTRL/K, vertical tabulation. |
+---------------------------------------------------------------------+
E-1
CHARACTER CODES AND CONVENTIONS
Table E-1 (Cont.)
OS/8 Control Characters
+---------------------------------------------------------------------+
| Octal |
| 8-bit Character |
| Code Name Remarks |
+---------------------------------------------------------------------+
| 214 FORM CTRL/L, form feed. |
| |
| 215 RETURN Carriage return, generally echoed|
| as carriage return followed by a|
| line feed. |
| |
| 216 Used only on LS8E line printer.|
| Puts current line into expanded|
| character mode. |
| |
| 217 CTRL/O Break Character, used to suppress|
| Teletype output, echoed as ^O. |
| |
| 225 CTRL/U Delete current input line, echoed|
| as ^U. |
| |
| 232 CTRL/Z End-of-File character for all ASCII|
| and binary files (in relocatable|
| binary files CTRL/Z is not a|
| terminator if it occurs before the|
| trailer code). |
| |
| 233 ESC ESCape replaces ALTMODE on some|
| terminals. Considered equivalent|
| to ALTMODE. |
| |
| 375 ALTMODE Special break character for|
| Teletype input. |
| |
| 376 PREFIX PREFIX replaces ALTMODE on some|
| terminals. Considered equivalent|
| to ALTMODE. |
| |
| 377 RUBOUT Key is labeled DELETE on some|
| terminals. Deletes the previous|
| character typed. |
+---------------------------------------------------------------------+
E-2
CHARACTER CODES AND CONVENTIONS
Table E-2
ASCII Character Codes
+-------+--------+----------+--------------+--------------------------+
| Octal | | Punched | Character | |
| 8-bit | 6-bit | Card | Representa- | |
| Code | Code | Code | tion | Remarks |
+-------+--------+----------+--------------+--------------------------+
| | | | | |
| 240 | 40 | blank | | space (non-printing) |
| 241 | 41 | 11-8-2 | ! | exclamation point |
| 242 | 42 | 8-7 | " | quotation marks |
| 243 | 43 | 8-3 | # | number sign |
| 244 | 44 | 11-8-3 | $ | dollar sign |
| 245 | 45 | 0-8-3 | % | percent |
| 246 | 46 | 12 | & | ampersand |
| 247 | 47 | 8-5 | ' | apostrophe or acute |
| | | | | accent |
| | | | | |
| 250 | 50 | 12-8-5 | ( | opening parenthesis |
| 251 | 51 | 11-8-5 | ) | closing parenthesis |
| 252 | 52 | 11-8-4 | * | asterisk |
| 253 | 53 | 12-8-6 | + | plus |
| 254 | 54 | 0-8-3 | , | comma |
| 255 | 55 | 11 | _ | minus sign or hyphen |
| 256 | 56 | 12-8-3 | . | period or decimal point |
| 257 | 57 | 0-1 | / | slash |
| | | | | |
| 260 | 60 | 0 | 0 | |
| 261 | 61 | 1 | 1 | |
| 262 | 62 | 2 | 2 | |
| 263 | 63 | 3 | 3 | |
| 264 | 64 | 4 | 4 | |
| 265 | 65 | 5 | 5 | |
| 266 | 66 | 6 | 6 | |
| 267 | 67 | 7 | 7 | |
| | | | | |
| 270 | 70 | 8 | 8 | |
| 271 | 71 | 9 | 9 | |
| 272 | 72 | 8-2 | : | colon |
| 273 | 73 | 11-8-6 | ; | semicolon |
| 274 | 74 | 12-8-4 | < | less than |
| 275 | 75 | 8-6 | = | equals |
| 276 | 76 | 0-8-6 | > | greater than |
| 277 | 77 | 0-8-7 | ? | question mark |
| | | | | |
| 300 | 00 | 8-4 | @ | at sign |
| 301 | 01 | 12-1 | A | |
| 302 | 02 | 12-2 | B | |
| 303 | 03 | 12-3 | C | |
| 304 | 04 | 12-4 | D | |
| 305 | 05 | 12-5 | E | |
| 306 | 06 | 12-6 | F | |
| 307 | 07 | 12-7 | G | |
+-------+--------+----------+--------------+--------------------------+
E-3
CHARACTER CODES AND CONVENTIONS
Table E-2 (Cont.)
ASCII Character Codes
+-------+--------+----------+--------------+--------------------------+
| Octal | | Punched | Character | |
| 8-bit | 6-bit | Card | Representa- | |
| Code | Code | Code | tion | Remarks |
+-------+--------+----------+--------------+--------------------------+
| | | | | |
| 310 | 10 | 12-8 | H | |
| 311 | 11 | 12-9 | I | |
| 312 | 12 | 11-1 | J | |
| 313 | 13 | 11-2 | K | |
| 314 | 14 | 11-3 | L | |
| 315 | 15 | 11-4 | M | |
| 316 | 16 | 11-5 | N | |
| 317 | 17 | 11-6 | O | |
| | | | | |
| 320 | 20 | 11-7 | P | |
| 321 | 21 | 11-8 | Q | |
| 322 | 22 | 11-9 | R | |
| 323 | 23 | 0-2 | S | |
| 324 | 24 | 0-3 | T | |
| 325 | 25 | 0-4 | U | |
| 326 | 26 | 0-5 | V | |
| 327 | 27 | 0-6 | W | |
| | | | | |
| 330 | 30 | 0-7 | X | |
| 331 | 31 | 0-8 | Y | |
| 332 | 32 | 0-9 | Z | |
| 333 | 33 | 12-8-2 | [ | opening bracket,SHIFT/K |
| 334 | 34 | 11-8-7 | \ | backslash, SHIFT/L |
| 335 | 35 | 0-8-2 | ] | closing bracket, SHIFT/M|
| 336 | 36 | 12-8-7 | ^ | circumflex |
| 337 | 37 | 0-8-5 | _ | underline - EOF signal |
+-------+--------+----------+--------------+--------------------------+
NOTES
1. These are the DEC029 standard card codes.
2. On most DEC Teletypes circumflex is replaced by up-arrow (^).
3. A card containing 0-8-5 in column 1 with all remaining
columns blank is an end-of-file card.
4. On most DEC Teletypes underline is replaced by back-arrow
(_).
5. On some IBM 029 keyboards 1 is graphically represented as a
cent sign (c /).
6. On some IBM 029 keyboards \ is graphically represented as
logical NOT (-,).
E-4
CHARACTER CODES AND CONVENTIONS
7. On some IBM 029 keyboards ^ is graphically represented as
vertical bar (|).
8. On a very few LP08 line printers, the character diamond (<>)
is printed instead of backslash.
9. On a very few LP08 line printers, the character heart (V) is
printed instead of underline.
10. The character number sign on some terminals is replaced by
pound sign (L).
E-5
APPENDIX F
OS/8 INPUT/OUTPUT ROUTINES
Appendix F describes a set of generalized I/O routines for use under
the OS/8 system. The routines presented here are used in all the OS/8
CUSPs (Commonly Used System Programs) in more or less this form.
Variations are made depending on the particular application and how
errors are to be handled. The routines, as indicated, will work as
presented. The routines work most efficiently in field 1, since CIF
10's are not necessary when addressing the Monitor, and the Command
Decoder tables are similarly available. Obviously the routines can be
modified to run in any memory field or core locations.
F.1 GENERAL DESCRIPTION
These subroutines assume that the Command Decoder tables have been set
up to indicate the proper I/O devices. The routines handle device
handler assignment without user interference. All I/O is done by
simple subroutine calls. The user program never needs to interface
with the Monitor or device handlers. All buffering and internal
bookkeeping are performed by the routines. In these routines, it is
assumed that only one output device is used at a time, i.e., the
output routine does not automatically set up for the next output
device. This modification can be made if desired. As many as nine
inputs are handled automatically. When input from one device is
exhausted, the input routine will automatically utilize the next
device specified in the Command Decoder list of inputs.
F.2 SUBROUTINES FUNCTIONS
Following is a brief list of the subroutines and their functions.
ICHAR - Character input routine.
Call sequence:
JMS ICHAR
ERROR RETURN
NORMAL RETURN
Error:
If AC>0, an EOF on input has occurred. No more
input is available. If AC<0, a device error has
occurred.
F-1
OS/8 INPUT/OUTPUT ROUTINES
Normal:
8 bit character is in the AC.
OCHAR - Character output routine.
Call:
TAD CHAR /8 BIT CHARACTER
JMS OCHAR
ERROR RETURN
NORMAL RETURN
Error:
AC<0 implies a fatal error.
AC > or = 0 implies that the hole allotted for
output was exceeded.
Normal:
AC=0. The character has been put into the device
output buffer.
IOPEN - Input initialize routine.
Call:
JMS IOPEN
RETURN
Return:
Input pointers reset. The next call to ICHAR
will read from the first device in the Command
Decoder input list.
OOPEN - Output initialize routine.
Call:
JMS OOPEN
ERROR RETURN
NORMAL RETURN
Error:
If AC> or = 0, no output device was specified.
If AC<0, an error occurred opening the file.
Normal:
An output file has been opened. No action if
the output was a non-file structured device.
F-2
OS/8 INPUT/OUTPUT ROUTINES
OCLOSE - Output close routine.
Call:
JMS OCLOSE
ERROR RETURN
NORMAL RETURN
Error:
Either the closing length is too large for the
space allotted or an output error has occurred.
Normal:
The output file is now a permanent file on the
output device.
F.3 SUBROUTINE PARAMETERS
These subroutines handle device assignment and internal buffering
automatically. To accomplish this, certain parameters must be defined
at assembly time. These parameters specify all details of handler
location, and buffer size for the routines.
Parameter Definition
_________ __________
INBUF = Address of input buffer.
INCTL = Input buffer control word. See the section on
using device handlers for details of the control
word format.
OUBUF = Output buffer address.
OUCTL = Output buffer control word. This must be a
negative number to indicate a write operation.
INRECS = Number of input records in input buffer. INRECS =
INCTL/256 (DECIMAL).
INDEVH = Address of input device handler.
OUDEVH = Address of output device handler.
The parameters can either be a part of the actual subroutine source,
or they can be contained in a separate parameter file to be assembled
with the subroutine file. The latter approach provides greater
flexibility in using the routines.
F-3
OS/8 INPUT/OUTPUT ROUTINES
F.3.1 Example
Following is a sample of the use of the subroutines. The program
simply calls the Command Decoder, and transfers input from the input
devices to the output file, closes the output, and exits.
FIELD 1
*2000
JMS I (7700 /LOCK MONITOR INTO CORE.
10
CALLCD, JMS I (200 /CALL COMMAND DECODER
5 /TO PICK OPTIONS.
0
JMS I (IOPEN /SETUP TO START LOOKING AT
/CD INPUT FILE.
JMS I (OOPEN /OPEN UP AN OUTPUT FILE.
SMA CLA /IF AC<0, WE HAD A FATAL
JMP OK /TYPE ERROR. AC>0 IS O.K.
JMS TERR /ERROR.
TEXT /OPEN FAILED/
OK, JMS I (ICHAR
JMP TSTEOF /EITHER ERROR OR EOF.
/SAVE IT.
JMS I (OCHAR /TRANSFER THE CHARACTER
JMP OUTERR /OUTPUT ERROR
JMP OK /TRANSFER UNTIL EOF FOUND.
TSTEOF, SMA CLA /IF NEG., FATAL
JMP CLOSE /EOF. CLOSE OUTPUT
JMS TERR
TEXT /READ ERROR/
CLOSE, JMS I (OCLOSE /CLOSE OUTPUT FILE.
JMP CLERR /CLOSE ERROR
JMP CALLCD /NEXT.
OUTERR, JMS TERR
TEXT /OUTPUT ERROR/
CLERR, JMS TERR
TEXT /CLOSE ERROR/
TERR, 0
TAD I TERR
RTR;RTR;RTR
JMS TYPIT
TAD I TERR
JMS TYPIT
ISZ TERR
JMP TERR+1
TYPIT, 0
AND (77
SNA
JMP CRLF
TAD (300
JMS TTYOUT
JMP I TYPIT
F-4
OS/8 INPUT/OUTPUT ROUTINES
CRLF, TAD (215
JMS TTYOUT
TAD (212
JMS TTYOUT
JMP CALLCD
TTYOUT, 0
TLS
TSF
JMP.-1
CLA
JMP I TTYOUT
F.3.2 Subroutine Listing
A listing of the routines follows. The parameters are set up in such
a way as to allow them to be put into a separate file. Another
parameter, ORIGIN, determines the location of the routines.
F-5
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 1
/OS/8 GENERAL CHARACTER I/O ROUTINES FOR BLEEP
/CALLED AS FOLLOWS:
/JMS I (IOPEN INITIALIZES THE INPUT ROUTINE
/JMS I (ICHAR READS A CHARACTER
/ERROR RETURN AC>0 IF END OF FILE, AC<0 IF READ
/ ERROR
/JMS I (OOPEN INITIALIZES THE OUTPUT ROUTINE
/ERROR RETURN AC>0 IF NO OUTPUT DEVICE/FILE, AC<0
/ IF ERROR
/JMS I (OCHAR OUTPUTS A CHARACTER
/ERROR RETURN OUTPUT ERROR OR TOO MUCH OUTPUT
/JMS I (OCLOSE CLOSES THE OUTPUT FILE
/ERROR RETURN FILE TOO LARGE TO BE CLOSED OR OUTPUT
/ ERROR
/JMS I (OTYPE RETURNS DCB WORD OF OUTPUT DEVICE IN
/ AC
/PARAMETERS NEEDED:
/INBUF= ADDRESS OF INPUT BUFFER
/INCTL= INPUT BUFFER CONTROL WORD
/OUBUF= ADDRESS OF OUTPUT BUFFER
/OUCTL= OUTPUT BUFFER CONTROL WORD (MUST BE NEGATIVE)
/INRECS= [INCTL/256]
/INDEVH= ADDRESS OF PAGE FOR INPUT HANDLER
/OUDEVH= ADDRESS OF PAGE FOR OUTPUT HANDLER
/IORFLD= /FIELD OF THE SUBROUTINES.
/ORIGIN= /THE SUBROUTINES RESIDE AT 16600.
/ASSUMES I/O MONITOR IS RESIDENT IN CORE.
/CAN BE CALLED FROM ANY FIELD WITH BUFFERS IN ANY FIELD.
F-6
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 2
/PARAMETER DEFINITION:
5000 OUBUF= 5000 /OUTPUT BUFFER STARTS AT 05000
4200 OUCTL= 4200 /AND IS 2 PAGES LONG.
6600 OUDEVH= 6600 /OUTPUT HANDLER GETS LOADED AT 6600.
/WE ALLOW TWO PAGE HANDLERS.
5400 INBUF= 5400 /INPUT BUFFER STARTS AT 05400
0200 INCTL= 0200 /ALSO TWO PAGES LONG.
0001 INRECS= 1 /2 PAGES = 1 RECORD
7000 INDEVH= 7000 /ALLOW 2 PAGE INPUT HANDLER AT 7000.
0001 IORFLD= 1 /FIELD OF THE SUBROUTINES.
6600 ORIGIN= 6600 /THE SUBROUTINES RESIDE AT 16600.
0001 FIELD IORFLD
6600 *ORIGIN
0000 INFLD= INCTL&70 /INPUT BUFFER FIELD
0000 OUFLD= OUCTL&70 /OUTPUT BUFFER FIELD
7760 DCB= 7760 /DEVICE CONTROL TABLE
F-7
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 3
016600 0000 ICHAR, 0 /INPUT A CHARACTER
016601 7600 IN7600, 7600
016602 6214 RDF /SAVE CALLING FIELD FOR RETURN
016603 1232 TAD INCDIF
016604 3316 DCA INRTRN
016605 6201 INCHAR, CDF INFLD /DATA FIELD TO FIELD OF BUFFER
016606 2265 ISZ INJMP /3 - WAY UNPACKING SWITCH
016607 2325 ISZ INCHCT /INPUT BUFFER EXHAUSTED?
016610 5265 INJMPP, JMP INJMP /NO..UNPACK THE NEXT CHAR.
016611 1321 TAD INEOF /DID LAST READ GIVE EOF ON
016612 7650 SNA CLA / THIS DEVICE?
016613 5216 JMP INGBUF /NO. CONTINUE READING.
016614 4325 GETNEW, JMS INNEWF /YES..GET NEXT INPUT IF IT
/ EXISTS.
016615 5264 JMP EOFERR /TAKE EOF EXIT FROM ICHAR.
016616 1324 INGBUF, TAD INCTR /INCTR HOLDS THE CURRENT LENGTH
/ OF THE INPUT FILE. WHEN THE
/ AMOUNT REMAINING TO READ IS
/ LESS THAN THE SIZE OF THE
/ INPUT BUFFER, AN EOF IS
/ SIGNALED.
016617 7100 CLL
016620 1377 TAD (INRECS
016621 7420 SNL
016622 3324 DCA INCTR /UPDATE REMAINING LENGTH
016623 7430 SZL
016624 2321 ISZ INEOF /AND SIGNAL EOF FOR NEXT READ.
016625 7172 CLL CML CMA RTR /CONSTRUCT A CONTROL WORD FOR
016626 7012 RTR / THIS READ FROM THE OVERFLOW,
016627 7012 RTR / IF ANY, AND THE STANDARD
016630 1376 TAD (INCTL+1 / CONTROL WORD.
016631 3235 DCA INCTLW
016632 6203 INCDIF, CIF CDF 0 /NOW CALL THE INPUT HANDLER
016633 6211 CDF 10 /HANDLER IS IN FIELD 0
016634 4736 JMS I INHNDL
016635 0000 INCTLW, 0 /INPUT CONTROL WORLD
016636 5400 INBUFP, INBUF /INPUT BUFFER ADDRESS
016637 0000 INREC, 0 /POINTER TO INPUT RECORD
016640 5260 JMP INERRX
016641 1237 INBREC, TAD INREC
016642 1377 TAD (INRECS /UPDATE POINTER INTO FILE
016643 3237 DCA INREC
016644 1235 TAD INCTLW /NOW COMPUTE THE NUMBER OF
016645 0201 AND IN7600 / CHARACTERS IN THIS INPUT
016646 7104 CLL RAL / BUFFER
016647 1235 TAD INCTLW
016650 0201 AND IN7600
016651 7040 CMA
016652 3325 DCA INCHCT /NEW NUMBER OF CHARACTERS
016653 1210 TAD INJMPP /RESET 3 WAY SWITCH
016654 3265 DCA INJMP
F-8
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 3-1
016655 1236 TAD INBUFP
016656 3323 DCA INPTR /AND BUFFER POINTER
016657 5205 JMP INCHAR /NOW READ THE BUFFER
016660 2321 INERRX, ISZ INEOF /SET EOF JUST IN CASE
016661 7700 SMA CLA /IF <0, A PHYSICAL ERROR
016662 5241 JMP INBREC /EOF ON INPUT
016663 7330 INERR, CLA CLL CML RAR /FATAL
016664 5316 EOFERR, JMP INRTRN /GET OUT
016665 7402 INJMP, HLT /3 WAY UNPACK SWITCH
016666 5307 JMP ICHAR1 /GET 1ST OF 3
016667 5303 JMP ICHAR2 /SECOND
016670 1210 ICHAR3, TAD INJMPP
016671 3265 DCA INJMP /SET FOR FIRST CHAR. NEXT
016672 1723 TAD I INPTR /THE THIRD WORD IS MADE OF THE
016673 0320 IN200, AND IN7400 / HIGH ORDER FOUR BITS OF THE
016674 7112 CLL RTR / FIRST TWO.
016675 7012 RTR
016676 1235 TAD INCTLW
016677 7012 RTR
016700 7012 RTR
016701 2323 ISZ INPTR /POINT TO NEXT WORD
016702 5310 JMP INCOMN /GET OUT WITH CHAR IN AC
016703 1723 ICHAR2, TAD I INPTR
016704 0320 AND IN7400 /SAVE HIGH ORDER FOR THIRD
016705 3235 DCA INCTLW / WORD
016706 2323 ISZ INPTR
016707 1723 ICHAR1, TAD I INPTR
016710 0375 INCOMN, AND (377
016711 1374 TAD (-232 /IS IT A ^Z (EOF)?
016712 7450 SNA
016713 5214 JMP GETNEW /YES..LOOK AT NEXT INPUT
016714 1373 TAD (232
016715 2200 ISZ ICHAR /TAKE NORMAL RETURN
016716 0000 INRTRN, 0 /CIF CDF N.
016717 5600 JMP I ICHAR
016720 7400 IN7400, 7400
016721 0000 INEOF, 0 /END OF FILE FLAG
016722 0000 INFPTR, 0 /POINTER TO INPUT FILE NAMES
016723 0000 INPTR, 0 /INPUT BUFFER POINTER
016724 0000 INCTR, 0 /LENGTH OF CURRENT INPUT FILE
F-9
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 4
016725 7777 INNEWF, -1 /OPEN A NEW INPUT FILE
6725 INCHCT= INNEWF
016726 6211 CDF 10
016727 1372 TAD (INDEVH+1 /INITIALIZE JUST IN CASE
016730 3336 DCA INHNDL
016731 1722 TAD I INFPTR /MORE INPUT?
016732 7450 SNA
016733 5725 JMP I INNEWF /NOPE
016734 4673 JMS I IN200 /CALL MONITOR TO GET HANDLER
016735 0001 1
016736 0000 INHNDL, 0
016737 7402 HLT /VERY BAD!
016740 1722 TAD I INFPTR
016741 0371 AND (7760 /GET INPUT FILE LENGTH
016742 7440 SZA
016743 1370 TAD (17
016744 7132 CLL CML RTR
016745 7012 RTR /NEGATIVE OF FILE LENGTH
016746 3324 DCA INCTR
016747 2322 ISZ INFPTR /POINT TO STARTING BLOCK
016750 1722 TAD I INFPTR
016751 3237 DCA INREC /STORE IN HANDLER CALL
016752 2322 ISZ INFPTR /NEXT INPUT.
016753 3321 DCA INEOF /CLEAR EOF FLAG.
016754 2325 ISZ INNEWF
016755 5725 JMP I INNEWF
016770 0017
016771 7760
016772 7001
016773 0232
016774 7546
016775 0377
016776 0201
016777 0001
7000 PAGE
F-10
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 5
017000 0000 OOPEN, 0 /OPEN OUTPUT FILE
017001 7600 OU7600, 7600
017002 1347 TAD OU7601 /POINT TO OUTPUT FILE NAME IN
017003 3221 DCA OUBLK / CD AREA
017004 1377 TAD (OUDEVH+1
017005 3214 DCA OUHNDL /INITIALIZE OUTPUT HANDLER
017006 1601 TAD I OU7600 /PICK UP OUTPUT DEVICE NUMBER
017007 0376 AND (17
017010 7450 SNA /IS THERE ONE?
017011 5244 JMP ONOFIL /NO..INHIBIT OUTPUT
017012 4775 JMS I (200 /FETCH OUTPUT HANDLER
017013 0001 1
017014 0000 OUHNDL, 0
017015 7402 HLT /BAD THING
017016 1601 OUENTR, TAD I OU7600
017017 4775 JMS I (200 /ENTER THE OUTPUT FILE
017020 0003 3
017021 7601 OUBLK, 7601 /GETS STARTING BLOCK OF HOLE
017022 0000 OUELEN, 0 /GETS SIZE OF HOLE AVAILABLE
017023 5232 JMP OEFAIL /FAILURE. SEE WHAT WE DID.
017024 3350 DCA OUCCNT /CLEAR CLOSING LENGTH
017025 3774 DCA I (OUTINH /CLEAR OUTPUT INHIBIT
017026 4773 JMS I (OUSETP /SET UP POINTERS
017027 2200 ISZ OOPEN
017030 6213 OORETN, CDF CIF 10
017031 5600 JMP I OOPEN /RETURN O.K.
017032 1601 OEFAIL, TAD I OU7600 /IF LENGTH=0, GIVE OPEN ERROR
017033 0372 AND (7760 /IF NOT, MAKE IT 0 AND TRY
017034 7650 SNA CLA / AGAIN
017035 5242 JMP ONTERR /WAS 0. FAILED
017036 1601 TAD I OU7600
017037 0376 AND (17 /MAKE IT 0
017040 3601 DCA I OU7600
017041 5216 JMP OUENTR /AND TRY AGAIN
017042 7330 ONTERR, CLA CLL CML RAR
017043 5230 JMP OORETN
017044 2774 ONOFIL, ISZ I (OUTINH /INHIBIT OUTPUT
017045 5230 JMP OORETN
F-11
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 6
017046 0000 OUTDMP, 0 /DUMP OUTPUT BUFFER
017047 3300 DCA OUCTLW /STORE CONTROL WORD
017050 6211 CDF 10
017051 1774 TAD I (OUTINH /IS OUTPUT INHIBITED?
017052 7640 SZA CLA
017053 5304 JMP OUNOWR /YEP.
017054 1350 TAD OUCCNT /IF THIS IS FIRST WRITE, START
017055 7450 SNA / SEARCH FORWARD ON DECTAPE
017056 2300 ISZ OUCTLW
017057 1221 TAD OUBLK /GET STARTING BLOCK OF THIS
017060 3302 DCA OUREC / TRANSFER
017061 1300 TAD OUCTLW
017062 7106 CLL RTL
017063 7006 RTL
017064 7006 RTL /COMPUTE # OF RECORDS TO
017065 0376 AND (17 / OUTPUT
017066 1350 TAD OUCCNT /UPDATE CLOSING LENGTH
017067 3350 DCA OUCCNT
017070 1350 TAD OUCCNT /SEE IF CLOSING LENGTH WILL
017071 7120 CLL CML / BE BIGGER THAN OUTPUT HOLE
017072 1222 TAD OUELEN
017073 7660 SNL SZA CLA
017074 5646 JMP I OUTDMP /WILL BE TOO BIG
017075 6203 OUCDIV, CIF CDF 0
017076 6211 CDF 10
017077 4614 JMS I OUHNDL /DO THE WRITE
017100 0000 OUCTLW, 0
017101 5000 OUBUF
017102 0000 OUREC, 0
017103 7410 SKP /ERROR
017104 2246 OUNOWR, ISZ OUTDMP /TAKE NORMAL RETURN
017105 5646 JMP I OUTDMP
0020 PTP= 0020
F-12
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 7
017106 0000 OCLOSE, 0 /CLOSE OUTPUT FILE
017107 6211 CDF 10
017110 1774 TAD I (OUTINH /IF OUTPUT INHIBITED, CLOSE
/ IS A NOP.
017111 7640 SZA CLA
017112 5352 JMP OCISZ /A NOP
017113 4771 JMS I (OTYPE /DETERMINE IF OUTPUT IS TO PTP
017114 0370 AND (770 /IF IT IS, DON'T OUTPUT A ^Z.
017115 1372 TAD (-PTP
017116 7640 SZA CLA
017117 1367 TAD (232 /NOT PTP. OUTPUT ^Z AS EOF
017120 4766 JMS I (OCHAR
017121 5353 JMP OCRET /ERROR RETURN
017122 4766 JMS I (OCHAR /FILL WITH 0 CHARACTERS
017123 5353 JMP OCRET
017124 4766 FILLIP, JMS I (OCHAR /FILL TO BOUNDARY WITH 0
017125 5353 JMP OCRET
017126 4771 JMS I (OTYPE /IF OUTPUT IS DIRECTORY DEVICE,
017127 7710 SPA CLA / FILL WHOLE RECORD, ELSE HALF
017130 1365 TAD (100 / RECORD
017131 1364 TAD (77)
017132 0763 AND I (OUDWCT /ARE WE UP TO BOUNDARY YET?
017133 7640 SZA CLA
017134 5324 JMP FILLIP /NO
017135 1763 TAD I (OUDWCT
017136 1375 TAD (OUCTL&3700 /IS THERE A FULL WRITE LEFT?
017137 7450 SNA
017140 5344 JMP NODUMP /YES. BUT DON'T DO IT, AS ^Z
/ IS OUT.
017141 1362 TAD (4000+OUFLD
017142 4246 JMS OUTDMP /DUMP LAST BUFFER
017143 5353 JMP OCRET
017144 1601 NODUMP, TAD I OU7600 /GET DEVICE NUMBER
017145 4775 JMS I (200 /CLOSE THE OUTPUT FILE
017146 0004 4
017147 7601 OU7601, 7601 /POINTER TO FILE NAME
017150 0000 OUCCNT, 0 /CLOSING FILE LENGTH HERE
017151 7410 SKP /ERROR
017152 2306 OCISZ, ISZ OCLOSE /NORMAL RETURN
017153 6213 OCRET, CDF CIF 10 /RESTORE CALLING FIELDS
017154 5706 JMP I OCLOSE
017162 4000
017163 7272
017164 0077
017165 0100
017166 7211
017167 0232
017170 0770
017171 7274
017172 7760
F-13
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 7-1
017173 7200
017174 7273
017175 0200
017176 0017
017177 6601
7200 PAGE
F-14
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 8
017200 0000 OUSETP, 0 /INITIALIZE OUTPUT POINTERS
017201 1377 TAD (OUCTL&3700
017202 7041 CIA
017203 3272 DCA OUDWCT /DOUBLE WORD OUTPUT COUNT
017204 1376 TAD (OUBUF /INITIALIZE WORD POINTER
017205 3270 DCA OUPTR
017206 1271 TAD OUJMPE
017207 3224 DCA OUJMP /3 WAY UNPACK SWITCH
017210 5600 JMP I OUSETP
F-15
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 9
017211 0000 OCHAR, 0 /OUTPUT CHARACTER ROUTINE
017212 0375 AND (377 /ISOLATE EIGHT BITS
017213 3266 DCA OUTEMP
017214 6214 RDF /GET FIELD WE WERE CALLED
017215 1374 TAD (CIF CDF 0 / FROM
017216 3264 DCA OUCRET
017217 1273 TAD OUTINH /OUTPUT INHIBITED
017220 7640 SZA CLA
017221 5263 JMP OUCOMN /YES. NOP.
017222 6201 OUCHAR, CDF OUFLD /GO TO DATA FIELD OF BUFFER
017223 2224 ISZ OUJMP /BUMP CHARACTER SWITCH
017224 7402 OUJMP, HLT /GETS JMP.,JMP.+1,ETC.
017225 5261 JMP OCHAR1
017226 5256 JMP OCHAR2
017227 1266 OCHAR3, TAD OUTEMP /THIRD CHAR
017230 7106 CLL RTL /HIGH ORDER BITS GO INTO THE
017231 7006 RTL /HIGH ORDER 4 BITS OF THE
017232 0373 AND (7400 /FIRST OF TWO WORDS
017233 1667 TAD I OUPOLD
017234 3667 DCA I OUPOLD
017235 1266 TAD OUTEMP /THE SECOND DOUBLE WORD GETS
017236 7112 CLL RTR /THE LOW ORDER BITS OF
017237 7012 RTR /THE THIRD CHAR
017240 7010 RAR
017241 0373 AND (7400
017242 1670 TAD I OUPTR
017243 3670 DCA I OUPTR
017244 1271 TAD OUJMPE /RESET CHARACTER SWITCH
017245 3224 DCA OUJMP
017246 2270 ISZ OUPTR /POINT TO NEXT BUFFER WORD
017247 2272 ISZ OUDWCT /BUMP DOUBLE COUNT AFTER
/3 CHARS.
017250 5263 JMP OUCOMN /GET OUT
017251 1372 TAD (OUCTL /READY TO OUTPUT A BUFFER
017252 4771 JMS I (OUTDMP /OUTPUT IT
017253 5264 JMP OUCRET /AN ERROR
017254 4200 JMS OUSETP /RESET OUTPUT POINTERS
017255 5263 JMP OUCOMN
017256 1270 OCHAR2, TAD OUPTR /POINT TO FIRST DOUBLE WORD
017257 3267 DCA OUPOLD
017260 2270 ISZ OUPTR /POINT OUPTR TO SECOND
017261 1266 OCHAR1, TAD OUTEMP
017262 3670 DCA I OUPTR
017263 2211 OUCOMN, ISZ OCHAR /NORMAL EXIT
017264 7402 OUCRET, HLT
017265 5611 JMP I OCHAR
017266 0000 OUTEMP, 0
017267 0000 OUPOLD, 0
017270 0000 OUPTR, 0
017271 5224 OUJMPE, JMP OUJMP
017272 0000 OUDWCT, 0
F-16
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 9-1
017273 0000 OUTINH, 0
017274 0000 OTYPE, 0 /OTYPE LOOKS AT THE OUTPUT
017275 6214 RDF / DEVICE #.
017276 1374 TAD (CIF CDF 0
017277 3306 DCA OTRTN
017300 6211 CDF 10
017301 1770 TAD I (7600 /AND LOOKS UP THE DCB WORD
017302 0367 AND (17 / FOR THAT DEVICE.
017303 1366 TAD (DCB-1
017304 3266 DCA OUTEMP
017305 1666 TAD I OUTEMP /GET DCB ENTRY
017306 7402 OTRTN, HLT
017307 5674 JMP I OTYPE
F-17
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 10
017310 0000 IOPEN, 0 /INITIALIZE THE INPUT ROUTINE
017311 7240 CLA CMA /SET TO FORCE READ FROM NEW
017312 3765 DCA I (INCHCT / DEVICE
017313 2764 ISZ I (INEOF /FORCE A NEW INPUT FILE.
017314 1363 TAD (7617 /POINT TO CD INPUT LIST.
017315 3762 DCA I (INFPTR
017316 6214 RDF
017317 1761 TAD I (INCDIF
017320 3321 DCA .+1
017321 7402 HLT
017322 5710 JMP I IOPEN
017361 6632
017362 6722
017363 7617
017364 6721
017365 6725
017366 7757
017367 0017
017370 7600
017371 7046
017372 4200
017373 7400
017374 6203
017375 0377
017376 5000
017377 0200
7400 PAGE
F-18
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 11
/
/ EXAMPLE PROGRAM TO COPY A ASCII FILE
/
0001 FIELD 1
2000 *2000
012000 4777 JMS I (7700 /LOCK MONITOR INTO CORE
012001 0010 10
012002 4776 CALLCD, JMS I (200 /CALL THE COMMAND DECODER
012003 0005 5
012004 0000 0
012005 4775 JMS I (IOPEN /SETUP INPUT POINTERS
012006 4774 JMS I (OOPEN /OPEN OUTPUT FILE
012007 7700 SMA CLA /ERROR. IF AC<0, IT WAS FATAL
012010 5220 JMP OK /NON FILE STRUCTURED OUTPUT
012011 4263 JMS TERR
012012 1720 TEXT /OPEN FAILED/
012013 0516
012014 4006
012015 0111
012016 1405
012017 0400
012020 4773 OK, JMS I (ICHAR /READ A CHARACTER
012021 5227 JMP TSTEOF /ERROR. SEE IF EOF.
012022 7450 SNA /IGNORE BLANKS
012023 5220 JMP OK
012024 4772 JMS I (OCHAR /AND OUTPUT THE CHARACTER
012025 5243 JMP OUTERR
012026 5220 JMP OK /CONTINUE UNTIL EOF.
012027 7700 TSTEOF, SMA CLA /WAS IT FATAL?
012030 5240 JMP CLOSE /NO..EOF. CLOSE OUTPUT
012031 4263 JMS TERR
012032 2205 TEXT /READ ERROR/
012033 0104
012034 4005
012035 2222
012036 1722
012037 0000
012040 4771 CLOSE, JMS I (OCLOSE
012041 5253 JMP CLERR /FILE CLOSE FAILED
012042 5202 JMP CALLCD /NEW INPUT.
012043 4263 OUTERR, JMS TERR
012044 1725 TEXT /OUTPUT ERROR/
012045 2420
012046 2524
012047 4005
012050 2222
012051 1722
012052 0000
F-19
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 11-1
012053 4263 CLERR, JMS TERR /CLOSE FAILURE
012054 0314 TEXT /CLOSE FAILED/
012055 1723
012056 0540
012057 0601
012060 1114
012061 0504
012062 0000
012063 0000 TERR, 0 /ROUTINE TO PRINT ERROR
012064 1663 TAD I TERR / MESSAGES
012065 7012 RTR;RTR;RTR
012066 7012
012067 7012
012070 4275 JMS TYPIT /TYPE THE CHARACTER
012071 1663 TAD I TERR
012072 4275 JMS TYPIT
012073 2263 ISZ TERR
012074 5264 JMP TERR+1
012075 0000 TYPIT, 0
012076 0370 AND (77 /ISOLATE THE CHARACTER
012077 7450 SNA
012100 5304 JMP CRLF /0 TERMINATES IT
012101 1367 TAD (300
012102 4311 JMS TTYOUT
012103 5675 JMP I TYPIT
012104 1366 CRLF, TAD (215
012105 4311 JMS TTYOUT
012106 1365 TAD (212
012107 4311 JMS TTYOUT
012110 5202 JMP CALLCD
012111 0000 TTYOUT, 0
012112 6046 TLS
012113 6041 TSF
012114 5313 JMP .-1
012115 7200 CLA
012116 5711 JMP I TTYOUT
012165 0212
012166 0215
012167 0300
012170 0077
012171 7106
012172 7211
012173 6600
012174 7000
012175 7310
012176 0200
012177 7700
$$$$$$$$$$
F-20
OS/8 INPUT/OUTPUT ROUTINES
/OS/8 GENERAL CHARACTER I/O ROUTINES FO PAL8-VC0 05-OCT-96 PAGE 12
CALLCD 2002 OORETN 7030
CLERR 2053 ORIGIN 6600
CLOSE 2040 OTRTN 7306
CRLF 2104 OTYPE 7274
DCB 7760 OUBLK 7021
EOFERR 6664 OUBUF 5000
FILLIP 7124 OUCCNT 7150
GETNEW 6614 OUCDIV 7075
ICHAR 6600 OUCHAR 7222
ICHAR1 6707 OUCOMN 7263
ICHAR2 6703 OUCRET 7264
ICHAR3 6670 OUCTL 4200
INBREC 6641 OUCTLW 7100
INBUF 5400 OUDEVH 6600
INBUFP 6636 OUDWCT 7272
INCDIF 6632 OUELEN 7022
INCHAR 6605 OUENTR 7016
INCHCT 6725 OUFLD 0000
INCOMN 6710 OUHNDL 7014
INCTL 0200 OUJMP 7224
INCTLW 6635 OUJMPE 7271
INCTR 6724 OUNOWR 7104
INDEVH 7000 OUPOLD 7267
INEOF 6721 OUPTR 7270
INERR 6663 OUREC 7102
INERRX 6660 OUSETP 7200
INFLD 0000 OUTDMP 7046
INFPTR 6722 OUTEMP 7266
INGBUF 6616 OUTERR 2043
INHNDL 6736 OUTINH 7273
INJMP 6665 OU7600 7001
INJMPP 6610 OU7601 7147
INNEWF 6725 PTP 0020
INPTR 6723 TERR 2063
INREC 6637 TSTEOF 2027
INRECS 0001 TTYOUT 2111
INRTRN 6716 TYPIT 2075
IN200 6673
IN7400 6720
IN7600 6601
IOPEN 7310
IORFLD 0001
NODUMP 7144
OCHAR 7211
OCHAR1 7261
OCHAR2 7256
OCHAR3 7227
OCISZ 7152
OCLOSE 7106
OCRET 7153
OEFAIL 7032
OK 2020
F-21
OS/8 INPUT/OUTPUT ROUTINES
ONOFIL 7044
ONTERR 7042
OOPEN 7000
ERRORS DETECTED: 0
LINKS GENERATED: 0
F-22
INDEX
Additional information words, CLOSE function, 2-8, D-10
1-3, 2-7, D-10 Code, non-paged, D-11
Alphanumeric option, Command Command Decoder
Decoder, 3-3 calling, 3-3
switches, 3-6 conventions, 3-1
ALTMODE key, 3-3 error messages, 3-3
Ascertain device information errors summary, C-7
(INQUIRE function), 2-14 example, 3-7
ASCII character codes, E-3, E-4 options, 3-3
ASCII files format, A-4 output files, 3-5
ASSIGN command, 1-6 special mode, 3-10
Asterisk, caution in using, 3-9 tables, 3-4
COMMON area, 2-12
Control characters, OS/8, E-1
Batch mode, 3-11 Conventions
Batch operating system, 1-6 Command Decoder, 3-1
Binary file format, A-4 OS/8, E-1
Block, core control, 1-4 Core control block, 1-4, 2-11, A-5
Blocks Core image files (.SV format), A-5
directory, A-1 Core origin, A-7
system scratch, B-1 Core segment doublewords, A-7
Blocks of words, 1-2, 1-3 Core size, PDP-8 computers, D-5
BUILD program, 5-1 software, 1-6
Co-resident device handlers, 2-6
Creating files, 1-3
Call Command Decoder (DECODE
function), 2-10, 3-3
in Special Mode, 3-9 Data exchange in core, 2-12
Calling device handlers, 4-1 Data field value, 2-2
Calling USR and device handlers Data transfer, 4-1, 4-2
from SABR code, D-13 DATE command, 1-4, 2-7
Card codes, DEC029, 4-8 DECODE function, 2-10
Card Reader (CDR) operation, 4-8 DECtape operation, 4-1
Card Reader handler modification, Default file storage device, DSK,
D-2 D-1
Carriage return/line feed sup- Deleting tentative files, 2-16
pression in FORTRAN, D-4 Device control word table, B-7
Cassettes operation, 4-7 Device dependent operations, 4-4
CCL, 3-10 Device handler
CCL error messages, C-4 entry point, 2-15, 5-8
CHAIN function, 2-11 information table, B-6
Character codes residency table, 2-15, B-6
ASCII, E-3, E-4 Device handlers
OS/8, E-1 device dependent operations, 4-4
Character mode, expanded, 4-6 Card Reader (CDR), 4-8
Character packing format, 5-8 Cassettes operation, 4-7
Characters, lower case, E-1 High-Speed Paper Tape Punch
Circumflex (^) character, 4-5 (PTP), 4-5
INDEX 1
INDEX
Device handlers (Cont.) FETCH device handler function,
High-Speed Paper Tape Reader 2-4, 4-1
(PTR), 4-4 File creation, 1-3
file structured devices oper- File directories, A-1
ation, 4-12 block format, A-1
TD8E DECtape, 4-12 entries, A-2
TM8E Magtape, 4-8 example, A-4
Device handlers, 1-1 formats, A-4
calling, 4-1 number, A-3
co-resident, 2-6 size, A-3
inserting into OS/8, 5-5 File extension, omission of, 3-2
loading dynamically, D-8 File length restriction, Command
notes on loading, D-7 Decoder, 3-6
writing, 5-1 FILENAME pseudo-op, 1-7
Device length table, B-8 Files, 1-2
Device names and numbers, 1-6 additional information words, 1-3
DEVICE pseudo-op, 1-7 devices, 1-2
Devices, file structured, 1-2 directories, 1-3
DF32 disk operation, 4-12 names, 1-2
Direct calling sequence, USR, 2-2 types, 1-3
Directories, file, 1-3 File structured devices operation,
Directory block structure format, 4-12
A-1 Formats for
Directory entries, A-2 character packing, 5-3
Directory example, A-4 command line, 3-1
Directory segment, rewriting, directory block structure, A-1
D-10 files, A-4
Directory, system, 5-2 FORTRAN Library File, A-8
Dismiss USR from core, 2-13 input file, 3-2
Dot (.) used as system response, Job Status Word, A-6
1-6 Form feed, 4-6
Doublewords, core segment, A-7 FORTRAN Library File Format, A-8
Functions, USR see USR functions
Empty file entry, A-2
Empty files, 1-3 High-Speed Paper Tape Punch (PTP)
End-of-file card, 4-8 operation, 4-5
End-of-file Condition, 4-2, 4-4 High-Speed Paper Tape Reader (PTR)
ENTER output (tentative) file operation, 4-4
function, 2-7, D-9 Horizontal tab, 4-6
Entry points for device handlers,
5-2
ERROR function, 2-12 Indirect calling sequence, USR,
Error messages, Command Decoder, 2-2
3-3 Information words, additional, 1-3,
Error messages summary, C-1 2-7
Error returns, device handler, accessing, D-10
4-2 Input file format, 3-2
Exit to Keyboard Monitor, 1-1 Input files, Command Decoder, 3-5
Expanded character mode, 4-6 Input/output routines, F-1
Extensions of file names, 1-2 Input table, Command Decoder, 3-9
INQUIRE function, 2-14
Inserting device handlers into
OS/8, 5-5
INDEX-2
INDEX
Job Status Word, 1-5, A-6 Records (definition), 4-1
outputting odd number of, 4-3
RESET system table, 2-15
Keyboard Monitor, 1-1 Resident program layout, B-3
error summary, C-3 RESORC, B-9
KL8E terminal handler, 4-13 Restrictions to USR calls, 2-2
RETURN key, 3-3
RF08 disk
LAP pseudo-op, D-11 operation, 4-12
Layouts for OS/8 system, B-1 RK8E handlers, 4-12
LINCtape operation, 4-12 ROM (Read-Only-Memory), B-4
Line Printer (LPT) operation,
4-5, 4-6
Load and start subprogram, 2-11 SABR programming notes, D-11
Loading device handlers dynam- SAVE command, 1-4, 2-12
ically, D-8 Scratch blocks, B-1, B-2
Lock USR in core (USRIN), 2-13 Signal user ERROR function, 2-12
Logical blocks, 1-2 Size of OS files, A-3
LOOKUP permanent file function, Software components, 1-1
2-6, D-9 Software core size, 1-6
Lower case characters, E-1 Special mode of Command Decoder,
3-10
calling, 3-9
Names of devices, 1-6 operation, 3-9
Names of files, 1-2 Standard USR call, 2-1
Number and size of OS files, A-3 restrictions, 2-2
Numbers of devices, 1-6 START command, 1-5
Numeric option, Command Decoder, Starting address of program, 1-5
3-3 Storage space, additional, D-9
Storage words, 1-3
Subroutine
ODT breakpoint, 2-12 examples, F-4
Operations, device dependent, 4-4 functions, F-1, F-2
Options listing, F-5
Command decoder, 3-3, 3-6 parameters, F-3
Origin of core, A-7 Summary of USR functions, see USR
Output files, Command Decoder, functions
3-5 .SV file, 1-4
System DATE, 2-7
System device layout, B-1
PAGE pseudo-op, D-11 System devices, 1-6
Permanent device name table, B-5 System device table, B-5
Permanent file, 1-3 System halts error messages
deletion, 2-8, 2-9 summary, C-1
entry, A-2 System table values, Command
Physical blocks, 1-2 Decoder, 3-7
PIP, 3-6
Program, see specific subject
Programming notes, D-1 Tables
PRTC12-F used to convert DECtapes Command Decoder, 3-4
to LINCtapes, D-6 device control word, B-7
Pseudo-ops device handler information, B-6
DEVICE, 1-7 device handler residency, B-6
FILENAME, 1-7 device length, B-8
Punch card codes, DEC026, D-3
INDEX-3
INDEX
Tables (Cont.)
permanent device name, B-5
system device, B-5
user device name, B-6
TD8E DECtape
operation, 4-12
Teletype operation, 4-4
Tentative files, 1-3
closing, 2-8
deletion, 2-8
entry, A-3
Terminal handlers
1-page, 4-4
2-page, 4-13
up arrow (^) character, 4-5
User device name table, B-6
User Service Routine (USR), 1-1,
2-1
available location in area,
D-9
calling, 1-6, 2-1
calling sequences, 2-2
errors summary, C-2
restrictions on standard call,
2-2
USR functions
CHAIN, 2-11
CLOSE, 2-8
DECODE, 2-10
ENTER, 2-7
ERROR, 2-12
FETCH, 2-4
INQUIRE, 2-14
LOOKUP, 2-6
RESET, 2-15
summary, 2-3
USRIN, 2-13
USROUT, 2-13
Vertical tab, 4-6
Wrap around memory, 4-3
Writing device handlers, 5-1
Word blocks, 1-2
INDEX 4
HOW TO OBTAIN SOFTWARE INFORMATION
SOFTWARE NEWSLETTERS, MAILING LIST
__________________________________
The Software Communications Group, located at corporate headquarters in
Maynard, publishes newsletters and Software Performance Summaries (SPS)
for the various Digital products. Newsletters are published monthly,
___________
and contain announcements of new and revised software, programming
notes, software problems and solutions, and documentation corrections.
Software Performance Summaries are a collection of existing problems
______________________________
and solutions for a given software system, and are published periodi-
cally. For information on the distribution of these documents and how
to get on the software newsletter mailing list, write to:
Software Communications
P. O. Box F
Maynard, Massachusetts 01754
SOFTWARE PROBLEMS
_________________
Questions or problems relating to Digital's software should be reported
to a Software Support Specialist. A specialist is located in each
Digital Sales Office in the United States. In Europe, software problem
reporting centers are in the following cities.
Reading, England Milan, Italy
Paris, France Solna, Sweden
The Hague, Holland Geneva, Switzerland
Tel Aviv, Israel Munich, West Germany
Software Problem Report (SPR) forms are available from the specialists
or from the Software Distribution Centers cited below.
PROGRAMS AND MANUALS
____________________
Software and manuals should be ordered by title and order number. In
the United States, send orders to the nearest distribution center.
Digital Equipment Corporation Digital Equipment Corporation
Software Distribution Center Software Distribution Center
146 Main Street 1400 Terra Bella
Maynard, Massachusetts 01754 Mountain View, California 94043
Outside of the United States, orders should be directed to the nearest
Digital Field Sales Office or representative.
USERS SOCIETY
_____________
DECUS, Digital Equipment Computer Users Society, maintains a user ex-
change center for user-written programs and technical application in-
formation. A catalog of existing programs is available. The society
publishes a periodical, DECUSCOPE, and holds technical seminars in the
United States, Canada, Europet and Australia. For information on the
society and membership application forms, write to:
DECUS DECUS
Digital Equipment Corporation Digital Equipment, S.A.
146 Main Street 81 Route de l'Aire
Maynard, Massachusetts 01754 1211 Geneva 26
Switzerland
OS/8 Software Support Manual
DEC-S8-OSSMB-A-D
READER'S COMMENTS
NOTE: This form is for document comments only. Problems
with software should be reported on a Software
Problem Report (SPR) form (see the E10A' TO OBTAIN
SOFTWARE INFORMATION page).
Did you find errors in this manual? If so, specify by page.
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
Is there sufficient documentation on associated system programs
required for use of the software described in this manual? If not,
what material is missing and where should it be placed?
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
______________________________________________________________________
Please indicate the type of user/reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[] Student programmer
[] Non-programmer interested in computer concepts and capabilities
Name______________________________________Date________________________
Organization__________________________________________________________
Street________________________________________________________________
City__________________________State_____________Zip Code______________
or
Country
If you do not require a written reply, please check here. []
-------------------------------Fold Here------------------------------
-----------------Do Not Tear - Fold Here and Staple-------------------
+---------------+
| FIRST CLASS |
| PERMlT NO. 33 |
| MAYNARD. MASS.|
+---------------+
BUSINESS REPLY MAIL ========
NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES ========
======================================================================
Postage will be paid by: ========
========
+-+-+-+-+-+-+-+ ========
|d|i|g|i|t|a|l| ========
+-+-+-+-+-+-+-+ ========
========
Software Communications ========
P. O. Box F ========
Maynard, Massachusetts 01754 ========