Digital PDFs

AA-D859C-TM

September 1985

214 pages

Original

8.7MB

view download

OCR Version

7.9MB

view download

Document:	TOPS20monCallUG
Order Number:	AA-D859C-TM
Revision:	0
Pages:	214
Original Filename:	AA-D859C-TM_TOPS20monCallUG.pdf

OCR Text

TOPS-20

Monitor Calls User’s Guide
AA-D859C-TM

September, 1985
This manual describes the use of TOPS—20 monitor calls,
which provide user programs with system services such
as
input/output, process control, file handling, and device control.
This manual supersedes the DECSYSTEM-20 Monitor

User’s Guide, order number AA-D859B-~TM

Calls

Change bars in the margins indicate material that has been
added or changed since the previous printing of this manual.

Bullets indicate that material has been deleted.

OPERATING SYSTEM:

TOPS—20 V6.1

Software and manuals should be ordered by title and order number.
In the United States. send orders
to the nearest distribution center. Outside the United States. orders should
be directed to the nearest
DIGITAL Field Sales Office or representative.

Northeast/Mid—Atlantic Region

Central Region

Digital Equipment Corporation

Digital Equipment Corporation
Accessories and Supplies Center
1050 East Remington Road
Schaumburg, Illinois 60195
Telephone:(312)640-5612

PO Box CS2008
Nashua, New Hampshire 03061

Telephone:(603)884-6660

Western Region
Digital Equipment Corporation
Accessories and Supplies Center
632 Caribbean Drive
Sunnyvale, California 94086
Telephone:(408)734-4915

digital equipme:m corporatione marlboro, mossochUSefis

First Printing, May 1976
Revised, April 1982
Revised, September 1985

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

The software described in this document is furnished under a license and may
only be used or copied in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment
that is not supplied by DIGITAL or its affiliated companies.
The following are trademarks of Digital Equipment Corporation:

dlililtlal1
DEC

MASSBUS

RSX

DECmate

PDP

DECsystem—10

P/OS

UNIBUS

DECSYSTEM-20

Professional

VAX

DECUS

Q-BUS

vMS

DECwriter

Rainbow

DIBOL

RSTS

Work Processor

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.

CONTENTS

PREFACE

]

Error

Sequence

W
—

DD NN
!
1

1/0 DESIGNATORS
.

WRITING

NUMBER

INITIALIZING

AND TERMINATING

THE

PROGRAM

A
A

BYTE

READING

STRING

OO NN
I
I

READING
WRITING

pa—

USING

BYTE

OVERVIEW

Sl UVR UL R UL R UV VRN N

FILES

JOB

NUMBER

FILE

et
—_

]

ASSOCIATING

FILE

WITH

GTJFN% Monitor Call
Short Form Of GTJFN%
Long Form Of GTJFN%
Summary Of GTJFNZ%
OPENING

—

RESET% Monitor Call
HALTF% Monitor Call

SUMMARY

JFN

FILE

OPENF% Monitor Call
TRANSFERRING

ONCNON\JT
B
N —

OO0

STRING
NUMBER

NND
|

A
A

PRINTING
READING

TERMINAL

N OWWOWWO

PRIMARY

OUTPUT USING THE

NN
=
*»

NN
DD

@
&

2
&

— W0 O~ W
N

PROGRAM ENVIRONMENT

Returns

OVERVIEW

(SR UUR VLR VIR UVR VIR VIR SURUL R VTR VIR VIR UL RS R VIR UUR LR Y

CHAPTER

—

Calling

INPUT AND

(SARCARVIRV, RN RV RV RV RN, BN g

CHAPTER

CALLS

AN
—

OVERVIEW
MONITOR

INTRODUCT
1 ON
oD

CHAPTER

File

DATA

Pointer

Source

And

Dest:natlon

DeS|gnators

Transferring

Sequential

Transferring

Strings

Transferring

Nonsequentia]

Mapping

Bytes
e

Bytes

Pages

Mapping

File

Pages

Mapping

Process

Pages

A
To

Process
A

File

3-27
3-30

¢«

.
O

INTERRUPT TABLES

Priority

]

Interrupt TabIes

Level

Table

SOFTWARE

INTERRUPT SYSTEM

INTERRUPT

L.10.

—
N
NN
FFw

¢«

k=13

INTERRUPT MONITOR CALLS

L-17

L-17
L-17

The RIR% Monitor Call
I
The XRIR% Monitor Call . . . . . . .
Disabling the Interrupt System . . . .

.
.

L-18
L-18

Deactivating a Channel
Deassigning Terminal
Clearing

bL=-19

L-19

L=-19

L4=27

Interrupt

System

EXAMPLE

L.12

SOFTWARE

INTERRUPT

PROCESS
USES

Codes

the

SUMMARY

k=20

STRUCTURE

FOR

PROCESS

MULTIPLE

PROCESSES

COMMUNICATION

Direct

Process

Control

Software

Interrupts

IPCF

ENQ/DEQ FaCI]Itles

and

Sharing

FFw

Memory
PROCESS

Ll
YR & R

Testing for Enablement .
.
Obtaining Interrupt Table Addresses

L.vo.
L.

Interrupt

INTERRUPTS

INTERRUPT
An

ADDITIONAL SOFTWARE

L.10.

PROCESSING

o iN ol

GENERATING

CHANNELS

INTERRUPT

—
—
O o0 o o

ACTIVATING

Dismissing

—

oo~

ENABLING THE

PRIORITIES

the Software

Tabie

AND

CHANNELS

SOFTWARE
—

INTERRUPT

SOFTWARE

.
CONDITIONS

O\W oo~~~
W —

INTERRUPT SYSTEM

INTERRUPT

Channel

SOFTWARE
.

EXAMPLES

Specifying

FILE

Process

A Y AVIRVIRVIRVIRVIR
VL
OO0 ImwWww
— =

1/0 MONITOR CALLS

TERMINAL

NN
—

FILE

OVERVIEW

¢«

Ll
T
-

\VIR VIR VIRULRUIRULIRUVIRUIR
VIRV

GTSTS% Monitor Call
JFNS% Monitor Call
GNJFN% Monitor Call
SUMMARY

OO N~

Process
to a

CLOSF% Monitor Call

VERVE VA

O O~~~ ooV

FILE

ADDITIONAL

USING THE

(S ARCARUL VA RUARCARCA RV RV RV,

In A

File Sections

(VYR VIRVIR VIR UL R ULV

CLOSING

L.1o.

CHAPTER

Unmapping Pages
Mapping

il
i
reeesrrrrreresrrrerreresresresr
e

CHAPTER

.6.3

CREATING A PROCESS

.
.

IDENTIFIERS

OVERVIEW OF
Process

MONITOR CALLS
.

Capabilities

FOR

PROCESSES

5-2

5-3

5-4

5=4

b-§

5-§

5-8

5-8
5-11

U
o

CONTENTS

PROCESS

L]
L]

INFERIOR PROCESS

INFERIOR PROCESS TERMINATION

ADDRESS

SPACE

A
5-11

STARTING

5-16
5-16

INFERIOR PROCESS STATUS

5-17
5-18

PROCESS

5-22

COMMUNICATION

DELETING AN
PROCESS

.12

THE

5-11

GET% Monitor Cal]
PMAP% Monitor Call

vttt oot o
O 0O~ OO

SPECIFYING THE

INFERIOR

EXAMPLES

PROCESS

5-23
5-24

Information

AVOIDING

11
NN —

FACILITY
N|

COMMUNICATION

QUOTAS

PACKETS

Flags

Length

PiDs

Directories

Address

and

Packet

Block

Packet

Data

Capabilities

Block

Data

AND RECEIVING MESSAGES

oo oo

<SYSTEM>INFO

Format

<SYSTEM>INFO

Requests

EXTENDED

OVERVIEW

ADDRESSING

UTILITY

Responses

FUNCTIONS

ADDRESSING
.

MEMORY

AND

ACS

[
1

F
O~

IPCF

PERFORMING

SIS

Format

—1

Packet

]

Packet
a

SENDING MESSAGES TO <SYSTEM>INFO

USING

CHAPTER

Receiving

Sending
N

S
S~
SIS

AANUT'OTUN

SENDING

And

DEADLY EMBRACES

OVERVIEW

1
WO

Resources

.
About

Obtaining

et amad amd ad ot

—

Resource

SHARER GROUPS

SIS~
S
SIS

Resource

DEQ% Functions .
DEQ% Argument Block

INTER-PROCESS
wwiwowiww
N —

o
o

.
.

Use of

ENQ% Functions .
ENQ% Argument Block
Releasing

[

Requesting

CHAPTER

SIS

O ONSNNNNTOOW
N —

aoaooNoNOoO
O

N e

PR N
R
e
i

OWNERSHIP

PREPARING FOR THE ENQ/DEQ FACILITY
USING THE ENQ/DEQ FACILITY .

i
Lo ARV IS

OVERVIEW

RESOURCE

o~o~nOh"ONONOYOD

ENQUEUE/DEQUEUE FACILITY

CHAPTER

o«

for

Indirection

References

Extended

¢«

Addressing

Examples

.«

¢«

XMOVED

¢«

o«

XHLLT

Instructions

Other

7.1
.2
.3

]
1.1
1.2
1.3
1.h
2
3
L
L.
b2
b3

Instructions that Affect the PC
Stack Instructions . . . . . . .« .« .« « .
Byte Instructions
USING MONITOR CALLS
e e e e e e e
Mapping Memory . . .
.
e e e e e+
Mapping File Sectaons to a Process
Mapping Process Sections to a Process
Creating Sections
.
Unmapping a Process Sectlon
Starting A Process In Any Section
.
Setting the Entry Vector In Any Section
Obtaining Information About a Process
Memory Access Information
. . . . . . .
Entry Vector Information . . . . . . . .
Page-Failure Information . . . . . . . .
Program Data Vectors

]

Manipulating PDV Addresses
5.2
PDV Names
« ¢« v v v ¢ ¢« ¢
5.3
Version Number . . .
e
MODIFYING EXISTING PROGRAMS
e
5.

Instructions

¢«

Immediate

e
¢

..
+

8
8
8
8-11
8-11

e
o
e
e

e
o«
e
e

e
«
e
e

e
o«
e
e

e
o
e
e

e
«
4
e

e
o
e
e

.
.
e
.+
.

.
.
.

.
.
.
o

.
.
.
.
.
.
.

8-11
B-12
8-13
8-13
8-14
8-16
8-16
8-17
8-18
8-18
8-18
8-21
8-21
B8-22
8-22
8-23
B8-23

e
o

o«

8-24

8-23

]
1.1

Index Words

W«

8-24

Data Structures

Macros
AC

wWw
N —

Instruction Format lndlrect WOrd (IFIW)
Extended Format Indirect Word (EFIW)

OO 000000000000

O\WwW oo~~~V
U

—

.«

—

.
.

Indirection

NSNS OOV LW
N —

IndeXxing

1.2

Indirect Words

+«

8-24

0O
00 00 000000 00 OO0D 000000000 CO000000 00 00000 0000000200 0O 00 00 00 00 02 0000 Co O

Instruction format

1.3

Stack

8-24

Pointers

WRITING MULTISECTION PROGRAMS

INDEX

FIGURES

L-1

Basic Operational
Interrupt

System

Sequence of

the

Software

L-2
6-1
6-2

Channels and Priority Levels
Deadly Embrace Situation .
Use of Sharer Groups . « « +

7-1

|PCF

8-1
8-2

Program Counter Address F:elds
Instruction Word Address Fields

Packet

v
«

e
«

e
&

s
«

e
«

.
.

L=2

.
.

L-6
6-5
6-18

7-2

.
.

8-3
8-4

(?OCD

£ w

Instruction Format

Extended Format

Indirect Word

.«

8-6

¢«

o
.

2=7
2-11

Specnflcatlons

3-4

00NN

EWN

S UN R VIR VLR VIR VIR VIR VIR VIR VSR VIR VU N 3

—

TABLES

Channe]

Conditions

Process

Handles

G sB

—

Interrupt

UL BV

Flle

Codes

GTJFN% Flag Bits . . . .
. T
Bits Returned on GTJFN% Call e e e e e e e e e e
3-11
Long Form GTJFN% Argument Block
. . . . . . . .
3-14
OPENF% Access Bits « « v ¢« ¢ + « o o o « « « « .
3-19
PMAPE Access Bits
. ¢« ¢« v ¢ v v v « o« o« « o « .
3=29
SMAP% Access Bits
. + « v + + v ¢ v v v e v o .
3-32
CLOSF% Flag Bits . . .
« v e « o & e« & « .
3-33
Bits Returned on CTSTS% Call e+ « o e & « o o« .
3-35
JFNS% Format Options . .« + « « « « « « « « « . .
3-38
GNJFN% Return Bits . . .
e e e e e .
3=l
Software

SN0V

ULV IV

For

¢«

Terminal

——OVVTEFWN

e B e Ao AN oo AN e RN e ARV
N

+
.

Inferior

and

Process

Status Word

Characterlstlc

GET% Flag Bits « » « ¢« « v
GET% Argument Block
. . «
GET% Argument Block Flags
Process

Assngnments

R
.

)
L-14

+«

5-6

BltS

5-9

«
+«
.

.
.
.

B-12
bB=-13
5-14
b-19

¢«
«
.

«
«
.

v
v
.

v
«
.

v
v
.

«
v
.

«
«
.

o
v
«

«
«
«

G«

RFSTS% Status-Return Block
ENQZ FUNCLIONS « v ¢ v v v
ENQ% Argument Block
. . .

e+
v v«
. .

s
o
.

e
v
.

4 e
o v
.+«

4
v
.

e
v
.

o+
o
.

Lock

6-11

v
.

«
.

v
.
C

«
.
e

v
.
e

«
.
e

o
.
e

o«
.
e

«
.
.

6-14
6-15
B-17

Specification Flags

DEQ¥ FUNCLionS . &+ «
DEQ% Argument Block
ENQC% Flag Bits
. .
Packet

Descriptor

&
.
.

«
.

Block

Flags

.
.

b-27
b-7
6-9

EWN

System Values

«
.

Flags Meaningful on a MSEND% Call
Flags Meaningful on a MRECV% Call
MRECV% Return Bits . . .

SN OV

Standard

.
.

0
]

NOUT% Format Option
RDTTY% Control Bits

<SYSTEM>INFO

Functions

and

Arguments

<SYSTEM>INFO

Responses

+«

171-17

7-19

MUTIL% FUNCLions

.
.

. .
. .
e«

.
.
«

.
.
o«

.
.
«

.
.
.

7-9
7-12
7-14
[

PREFACE

The TOPS-20 Monitor

Calls

language

user

The manual

who

introduces

the

monitor

also

teaches

from
him

these

functions.

This

manual

according

Each

chapter

Once

the user

Manual for

the

understand
the

use

written

with

the

DECSYSTEM-20 monitor

the

basic

reference

from
not

a working
then

The TOPS-20 MACRO

the

gain

knowledge of

refer

examples

language

and

end.

the

all

manual,

the

user

monitor

the

organized

user

must

Manual

familiar

instructions.

documents

the

contains

the
should

and

should

the

referred

instruction

DECSYSTEM-20
by

assembly

language

analysis
In

the

system

file.

user

the

This
as

Finally,

the user

and

enter

questions

Another

useful

Press.

the

file

means

is
of

should

the

this

or JSHLT,

universal

producing

provides

examples.

TOPS-20

commands

and

system programs.

Manual

describes

all

MACRO

language

Introduction

Ralph

thorough

€E.

treatment

emphasizing

the

contain

macros

readable

the TOPS-20
User's

commands

and

from the MACSYM

definitions
and

Gorin,

synthesis.

for example)

The TOPS-20

system

the

manual

The TOPS-20

operating

TOPS-20.

Guide,

program

file of

familiar with

the

user

These three

User's

DECSYSTEM-20,

consistent

run

nonprivileged

MACRO

linking
Manual

Calls

reference

methods

examples

JSERR,

arise

Programming
for

and various

TMSG,

the Monitor

to when

programming

some of

(MOVX,

the machine instructions.
with

Language

Digital

programs

addition,

symbols

set.

Assembly

published

together

this

calls.

manuals

used

skips

Reference

The
TOPS-20
LINK
Reference Manual describes the
The
DECsystem-10/DECSYSTEM-20
Processor
Reference

information

the

manual.

Calls

language.
loader.

who
this

«calls

DECSYSTEM-20 machine

Reference

complete

performing

proceeding

benefit

the

calls.

The manual

the TOPS-20 Monitor

this

Assembier

nor

assembly
request

for

calls.

full

can

programs.

simple and

the

calls

monitor

beginning

complete descriptions
the

language

document,

starting with

for

that

monitor

set of

read

MACRO

functions

assembly

entire

should

Guide

reading will

has

his

the

should
his

document,

with

within

functions,

advanced.

user

not

around

the

how

documentation

User's

unfamiliar

available
programs.

Command

Guide

Language

describes

Commands

the

Reference

available

the

CHAPTER

INTRODUCT
I ON

1.1
A

OVERVIEW

program written

statements,

machine
may

language

one

in MACRO

each

MACRO

following

assembler

MACRO

assembled.

Each

statement

directive,

END.

and

for

These

are

Refer

Reference Manual

consists

corresponding

the

series
one

MACRO

of
more

program

types:

assembler

language

wusually

instructions.

the

such

assembly

statement

pseudo-operation

pseudo-ops

performed
the

when

DECSYSTEM-20

detailed

(pseudo-op),

are commands

the

program

MACRO

descriptions

Assembler

the

MACRO

pseudo-ops.

MACRO

assembler

statements

are

direct

the

assignment

statement.

These

form

symbol=value

and

are

wused

Assignment
when

the

program

generate
3.

MACRO

assign

statements
is

ONE:

EXP

These

statements

specific

processed

assembled.

instructions
assembler

are
or

data

constant

These

the

the MACRO

symbol.

assembler

statements

do
program.

assembled

declaration

statement,

such

not

are

processed when

instruction mnemonic,

MOVE

symbolic

the

operations

program

value

or
is

ADD.

These

performed

executed.

Processor

Reference

symbolic

instruction

symbolic

the

Refer

Manual
codes.

-1

for

the

program

instruction

central
the

assembled.

code,

codes

processor

such

represent
when

the

DECsystem-10/DECSYSTEM-20

detailed

descriptions

the

INTRODUCT
ION

A monitor
are

monitor

calls.

Monitor

Calls

relating

assigning

calls

instruction

Each monitor

symbolic

also

calls

when

the

the commonly-used

refer

detailed

the TOPS-20

descriptions

the MACRO assembier

instruction
numeric
or

codes

processes

to binary

the

codes.

values.

absolute memory

converts

(JSYS)

the

each

symbolic

addresses.

call

the

such

instruction.

These

code

indicates
has
to

monitor

predefined

calls

defined

are accomplished

the final

prior

indicating
example,

The current convention

part

the

call

symbol.

symbols

and

to cause

contain

them

that

This

the

all

system

require

monitor

follows

with

and

the

particular
to

indicate

file

called

later require a

symbol.

the %,

calls

that

defined

the

OPENF%

in the call

not

manual

Release

character

Release

during

function.

(for

input

where the address portion of

symbol

performed

it.

program must

calls

104),

the particular

functions,

and number conversions,

The symbols are defined

Monitor
(%)

handling,

program.

call

defined

request monitor

error

(operation

function

percent sign

(1/0),

opening a file).

the

should

for

These

performed

describes

the user

assembled,

relocatable

instruction

calls

BIN.

are

are used

data

the execution of

MONSYM.

and

CALLS

Monitor

monitor

However,

symbols

assemblier

output

the

RESET or

This manual

Reference Manual

program

translating

MONITOR

JSYS

monitor

the program by

into a Jump-to-System

1.2

such

the

executed.

The MACRO

JSYS,

the calls.

the MACRO

statements

or
to

program

all
When

call,

commands

but

use

Monitor
do

the

convention.

correctly,

the

use

user's

statement

SEARCH MONSYM
at
the

the

beginning

assembler

containing

the

function

code

Arguments

for

Any

data

returned

the

program.

operation

code

the

a JSYS

the

resulting

accumulator
executed,

replaces

right

104

instruction are
from

the

assembly
symbol

left

half

the

program,

with

instruction

and

the

appropriate

placed

accumulators

execution of

the

JSYS

in memory

the

Therefore,

appropriate

the

call

half.

accumulators

points.

During

monitor

address

before

arguments

accumulators.

1-2

must

the
be

JSYS

placed

(ACs).

instruction
to

which

instruction
in

the

can

are
an
be

specific

INTRODUCT
I ON

The

system

assembly
-

file

MACSYM.MAC

language

program must

contains

programmer.

contain

the

number

wuse

useful

MACSYM

macros

macros,

for

the

user's

statements

SEARCH MACSYM
.REQUIRE
at

the

SYS:MACREL

beginning

monitor

the

have

;include
program.

symbolic

support

Since most

names,

bits

macros

these bits without

knowledge of

MACSYM

macros

especially valuable

test
AC

that

programmer

instructions

with

provided

constant

the

constant's

all

combinations

are

are MOVX,
using

position

TXnn
by

the

exact

proper

MOVE

the word.

the

use with

position.

and

FLD.

Several

MOVX

instructions,

The TXnn macros

and

for

programmer

to the TOPS-20 assembly
indicates one of
the
64

hardware),

the

modification

their

(where

defined

enable

utilize
language

routines

testing

loads

depending
expand

an
on

allow

defined.

For

example

TXNN AC1,GS%EOF
tests

ACl

equal

for

the presence of

zero.

This

bit position of GS¥EOF.
Justified

field.

GS¥EOF,

no modification,

instruction will

work

The FLD macro causes
For

and

regardless

value

skip

not

the

actual

right

example

FLD (7,0F%BSZ)
places

the value 7

(OF%BSZ

consistently

]72.1

for

(ACT-ACL) .
call,

the

calls

These

symbol

names,

recommended

are

bit

that

the

makes
allows

requiring
and

the

symbol

names.

The

set

instructions

followed

symbol.

During

monitor when

the

one
the

this

wused
his

program

will

accumulators

1list

which

that

code

bit

through

used

accumulator

read by
symbols

with

the

code

arguments

giving

execution,

this

it is
whenever

user.
Use
redefined

manual,

both

the

are written

the particular

control

reached.

1-3

examples

fact,

another
to
be

changed.

program

|In

symbols

described

All

the

program.
using

are

place

program's

the

to be

<calls

1line of

program

easier

values

names.

line of

write

program

the monitor

symbol

justified

macros

<calls are specific bit settings or
and values
are
defined
in
MONSYM
with

can

also

the

user

This

for

the

possible.

settings

placed

settings

which

arguments

right

These

document.

are

arguments

values.

without

this

0-5).

I f more than four arguments are required for a particular
The

symbols

OF%BSZ,

bits

Sequence

arguments

points.

position

throughout

Calling

Arguments

defined

bit

using

accumulators

monitor

transferred

call
the

INTRODUCT
I ON

1.2.2

Error

Returns

TOPS-20

provides

monitor

calls

call

call,

the monitor

executed.

instruction
12-17,

illegal

JUMP
is

&4).

If
trap,

the

reason

To place

JUMP
using

ERJMPS

address

ERCALS

address

ERJMP

address

ERCAL

address

the

= JUMP
= JUMP
= JUMP
= JUMP

his

includes

17,

executes

address
a

POPJ

the

location

user

the

last

error

symbol

the

except

the

user's

ACT1.

original

contents
value

generates

which

system

the

(refer

a message

the

output

user

can

These

include

symbols

instruction.

(that

is,

the monitor

the address

been

error

The

no-op)

executes

and

which

the

executed.

I|f

returns

does

finished.

transferred

symbol,

the monitor

had

process

been

the

though

routine

user's

behaves

included,

stored

and message

ERCAL

ACl.

AC1

not

the error
the

far
JUMP

transferred

control

JUMP

the

specified,

control

routine

routine written

executed,

been

mnemonics,

same

are

program

the

except

the

same

that

user's

the TOPS-20 Monitor Calls Reference Manual

from when

prior

JUMP

control

except

ERJMPS

suppresses

Instead,

the

processing

symbol

the

the user's

monitor

address.

ERCAL.

ERJMPR

codes,
the

and

symbols.

control

had

the

ERJMP

encountered

halts,

the

instruction,

the

functions

returned

specified

is not prepared to process

the ERJMP symbol,
had

after

following

error

the

instruction,

interrupt

instruction

error

symbol,

to Appendix B of

list

instruction

monitor

illegal

However,

includes

ERCAL

includes

would

field

the

15, address)

generate

instruction

17,

call.

16, address)
17,address)

= JUMP

program

the

program,

transferring control

JUMPA

the

12,address)

= JUMP

beginning

the user
a

execution

13,address)
14,address)

concerned.

updated

his

return

predefined

hardware

though

(Refer

six

non-operation

the

For most

following

user-specified

software

program

user.,

the

to a

indicating an

errors.

failure.

assembler

instruction by

with

JSYS

instruction

following

instruction,

normaily

PUSHJ

instruction

program execution

address

the

during

control

JUMP

instruction

address

the

wuser's

for

ERCALR

cause

trap

the

ERJMPR

instruction

occurs

process via

one

to handle all
return,

instruction

the

instruction

statement

error

transfers
not

stating

user

examines

program can

Chapter

instruction

user's

successful

the monitor

instruction

and

AAATAA

the

consistent way

upon

the

and

preserved
call

and
was

for

strings.)

The

error

encountered

ERCALS

storing

the monitor
error.

the

the
ACl.

code

function
the

error

ERCALR

similarly
code

contains

either

given,

the

partially

INTRODUCT
I ON

Prior

the

monitor
locations

JSYSs

implementation of

calls

returned

after

return

the

calling

the +1

immediately following
the

«call.

conditions
in

return at all
TOPS-20

monitor

When

the

failure.
but

data

block.

with

the

occurs

This

can

the

trap

Illegal

memory write

Pushdown

list

Chapter

the

possible

monitor

GACTF%
do

not

the

returns

for

are

ERCALS
are

call,

the

program

and

translated

with

Two

message

processing

used

cause of

right
base

half

message

user's

associated

following

machine

conditions:

the

monitor

returns.

employ

either

the

with

all

unless

they

immediately

Error

codes

calls.

All

corresponding

error

and

ERSTR% monitor

calls.

macros

EJSHLT

and

They

EJSERR
to

prints

program.

1-5

subroutines

can

found

and

EJSHLT.

the

out

for
the

the

six

instruction

obtained
mnemonic

handling

system

EJSERR
error

handle
ERJMPR,

their

can

calls,

into

control

the

all

two

GETER¥

and

call.

fails.

routines.
returns

after

one

that

are

has

such macros

failing monitor

the

data

the

following

encouraged

convenient

error

the

ERSTR% call.

symbol

instruction

provides

obtain

also

no-ops,

call

can

call

TOPS-20

stored

the monitor's

the

can

the

users

symbols

strings

indicates

overflow

whether

ERJMPS,

read

facilities

consistently,

error

code

usually

can
for

memory

MACSYM.MAC.

calls

execution

you

|lilegal

message

on varying

some

and

the

location

execution of

dependent

see

the

The error

GETER¥ or

monitor

the

case,

using

stored

facilities

ERJMP/ERCAL

halts

code

instruction

the

third

ERSTR%

Refer
for

and

successful

examples,

WAIT%).

the

I|llegal

monitor

or +3,

Reference Manual);

code.

ERCALR,

error

and will

predefined jump

and

during

either

ERJMP/ERCAL

errors

(for

+2,

Reference Manual

error

also

error

regardless

failure,

address)

certain

program at various

Approximately one

return +1,

Calls

facilities,

user's

call.

instruction,

(the +2

failure

Calls

the

address.

(see HALTF% or-

stores

ACl,

The

failure

monitor

The

success

Monitor

each

that
calls

Monitor

ERJMP/ERCAL

address only on

few

the TOPS-20

the

control

prints

file

out

following

message

and

INTRODUCT
I ON

The following is an example of executing the BIN%
monitor
call
(see
Chapter 3 for more information on this monitor call) that has a single
return.

and

the

stores

successful,

routine

a
the

execution of

the call

character.

execution

program

processes

program sequence.

the

transfers

the

error

Note

that

and

successful,

control

then

ERCALS

returns

stores

the

program

the

<call

error

routine.

control

the

reads

back

return

not
This

the main

address

the

stack.

DOIT:

MOVE

T1, INJFN

;obtain

BIN%
ERCALS

ERROR:

7INPUT

ERROR

s;call

;store character

JRST

DOIT

;and

EOF

;yes,

HRRO |

T, [ASClZ/

ENVIRONMENT

parailel

is,

structure

Each
This

with

process

other

has

address

"window'"

(decimal)
and each

that

schedulable

associated with at

left-justified

a byte containing all

program environment
or

end-of-file

condition

;print message

1.3

runnable

problem

;no, data error

(that

job

CONTINUING

ASCIZ pesudo-op specifies

process

sreturn to program

PROGRAM

file

another

T2,GS%EOF

with a null

user

get

routine

JRST

RET

error

;read file status
send of file?

ERROR,

The

input

T2,CHAR

PSOUT%

The

for

MOVEM

GTSTS%
TXNE

JFN

; input one character

can

entity

(POPJ

ASCII|

string

bits equal

the TOPS-20 operating
contain many
of

performing

This

means

that

for

storing

terminated

to zero)

system

processes.

capable

processes.

17,)

byte.

consists

process

computations

runnable

a
in

program

least one process.

its

own

address

space

called

virtual

into physical

sections.

space

storage.

The address

Each section

is divided

page contains

512

(decimal)

its

because

space
Each

actually

is divided

into 512

words.

computations.

into

(decimal)

word

pages,

contains

bits.
A

process
e

can

communicate with

explicitly,

inter-process
e

implicitly,

space,

for

other

software

interrupts

communication

changing

instance)

processes

parts

that

are

processes.

1-6

facility,
its

the

system

following ways:
facilities

IPCF,

for

environment

being

shared

(the

example).

(its

with

address

other

INTRODUCT
I ON

A process can create other processes inferior to it, but there is
one
process
from which the chain of creations begins.
A process
is said to exist when a superior process creates it and is said to end
when
a
superior
process
deletes
it.
Refer to Chapter 5 for more
control

information on

the process

structure.

A set of one or more related
single user, is a job.
Each
system.
A job is defined by
files,
and a set of running
composed of

The

several

processes, nhormally under
control
of
a
active process is part of some job on the
a user name, an account number, some open
and/or suspended processes.
A job can be

running or

following diagram

suspended

illustrates

programs.

a job structure consisting

four

processes.

TOP PROCESS
Process A

Process B

Process C

Both

process

are

directly

thus

is directly

inferior

A and

process

inferior

the TOP

Job
'

——

MR-S-2037-82

B are created by

the TOP PROCESS

it.

created by process

Process

to process

B only.

Process C

and

thus
B and

indirectly

PROCESS.

In summary, processes can be considered as
independent
virtual
jobs
with
well-defined relationships to other processes in the system, and
a job

collection of

these processes.

1-7

CHAPTER

INPUT

One

from

and

the main
one

from

reasons

location

OVERVIEW

Data

transfers

bytes

strings

are

ASCI|

called

ASCIZ

written.
pointer,

using monitor

another.

from

the

text

strings

the desired

that

The
as

for

ending with

points

transfer

discusses

are

The bytes
a

moving

the

form

are

7-bit

byte.

MACRO

shown

the user's

beginning

the

pseudo-op,
the

POINT,

following

PTR:

POINT

7,MSG

ASCIZ/TEXT MESSAGE/

address

The
of

calls

string,

MSG:

string.

TERMINAL

chapter

terminal

ACI1,PTR

format

This

strings.

MOVE

Accumulator

USING THE

data

These

either

bytes.

The

strings

are

strings.

To designate
statement

OUTPUT

terminal.

to and

individual

the

the user's

2.1

AND

the

contains
specified

pointer
POINT

the

PTR

set

up by

pseudo-op

can

the

address
the

the

POINT

include

being

set

read

a
or

this

statements:

(PTR)

pointer

must

string

used

sequence of

symbolic

program
of

the pointer.

the

beginning

the

pseudo-op.

The

general

is:

POINT decimal-byte-size,address,decimal-byte-position

(Refer to the
information

TOPS-20
on

MACRO

Assembler

the POINT pseudo-op.)

pseudo-op

has

been written

left-most

bit

the

address

indicate
specified

Reference

7-bit
by

Manual

the example above,
bytes

MSG.

starting

for

the POINT
before

the

INPUT AND OUTPUT USING THE TERMINAL

Another way of setting up an accumulator to contain the address of the
pointer

is with

HRRO!

the following statement:

AC1, [ASCIZ/TEXT MESSAGE/]

The instruction mnemonic HRROI| causes a -1 to be placed
in
the
left
half
of
accumulator
1 and the address of the string to be placed in

the right half.
in

However,

square brackets)

literal

causes

in the above statement, a literal

has been used

(enclosed

instead of a symbolic address.

the MACRO assembler

The

to:

store data within brackets

(the string)

assign an address

insert that address as the operand to the HRROI

to the first word of

in a table.
the data.

instruction.

Literals have the advantage of showing the data at the
point
in
program where it will be used, instead of showing it at the end of

the
the

program.

As far

the

|/0 monitor

calls are concerned,

a word

this

format

(-1
in the left half and an address in the right half) designates the
system's standard pointer (that is, a pointer to a 7-bit ASCIZ
string
beginning
before the leftmost byte of the string).
The result of the
HRROI

statement

equivalent
is

the

interpreted

the word

recommended

assembled by

statement

to use

the

monitor

POINT 7,

functionally

address

in preparation

for

pseudo-op and

a monitor

However,
byte
manipulation
instructions
(for
example,
ADJBP) will not operate properly with this type of pointer.
After

string

following

the

read,

the

written,

the pointer

non-null

character written.

Most TOPS-20 monitor

executed

from

calls

are used with

Chapter

calls

this
do

advanced

nonzero

pointers
monitor

pointer

terminating character

not

advanced

the

section

the character

document.

(see

string.

the

After

following

accept one-word global

extended

byte

call.

|LDB,

character

string

last

pointers

when

8.3).

Global

addressing and are

fully

explained

two-word

specifically stated,

giobal

byte

the

Section

Unless

IBP,

pointers.

byte
in

TOPS-20

INPUT AND

2.2

PRIMARY

transfer

indicate

1/0

from one

source

destination where
terminal

overridden

Calls

user's

terminal

device.

using

Monitor

the

The

They

are

used

destination.
call

The

(refer

Examples
(input)

and

.PRIOU

represent

(output)
the

this

primary

system

the

book

the

user's

assume

the

(output)

terminal:

user's

terminal

the

user's

terminal

the

output designators

and

the

and

terminal

file MONSYM.MAC

program

the

input

represent

can

TOPS-20

device.

wuser's

default

destination

represent

used

the

placed.

user's program must
to be obtained and the
default,
the
user's

device.

called

are

.PRIIN

(input)

symbol

SPJFN% monitor

the

the data
and

source

are defined

defined

to be

Manual).

symbol

symbols

default

source

to be

destination

to another,

which

Reference

source

These

the

Two designators

location

from

the data

defined
by

TERMINAL

DESIGNATORS

data

the

OUTPUT USING THE

and

long

error

statement

running

the

not

program

the

program.

have

contains

the

SEARCH MONSYM

2.3

PRINTING

Many

times

string,

program may

such

terminal.

string on

string

from

the

terminal.

need

prompt

PSOUT¥

such

The

to
to

(Primary

the

program's

request

String

terminal.

address

address space,
program

need

This

space.

and

only

Accumulator

(AC1)

set

AC1

the

PSOUT%

used

up with

call.

supply

contain

the

pointer

example

HRRO1 AC1, [ASCIZ/TEXT MESSAGE/]
PSOUT%

2-3

some

the

user

monitor

call

Thus,

from

call

copies
the

the

source

pointer

address
the

string,

the

used

the

the data

PSOUT%

other
at

the designated

the destination for

the

Thus,

message

input

Output)

printed.

After

code

The

being

STRING

the

the
next

call

;string to print
sprint TEXT MESSAGE

string

pointer.
line

is:

INPUT AND OUTPUT USING THE TERMINAL

in the
the characters
all
The PSOUT% call prints on the terminal
is
string
the
that
Note
byte.
null
a
encounters
it
until
string
the
at
starting
program,
the
in
stored
is
it
as
exactly
printed
current position of the terminal's print head or cursor and ending
line
|f a carriage return and
with the last character in the string.
these
string,
the
after
or
before
either
output,
be
to
feed are
characters should be inserted as part of the string.

TEXT

feed after

MESSAGE

it,

the user's program

HRROI

For example,

on one line and to output a carriage return-line
includes the call

AC1,[ASCIZ/TEXT MESSAGE

PSOUT%

After the string is printed, the instruction following the PSOUT% call
in the
updated

the pointer in AC1 is
Also,
is executed.
wuser's program
last non-nul |
following the
to point to the character

character written.

The macro TMSG, found in the system file MACSYM, does the same thing
This macro offers the programmer a convenient
the example above.
as
way for printing messages on the terminal.

For example

TMSG <TEXT MESSAGE
>

caused
the text message contained between
the angle
brackets,
including the carriage return and line feed, to print on the terminal.
be used
The TMSG macro, along with others previously mentioned, will
Refer to the
this document.
throughout
in examples
consistently
system file MACSYM.MAC for further information on MACSYM macros.
Refer to Section 1.2.2 for

2.4

information concerning error returns.

READING A NUMBER

This
The NIN% (Number Input) monitor call is used to read an integer.
therefore,
call does not assume the terminal as the source designator;
the
accepts
The NIN% call
the user's program must specify this.
number from any valid source designator, including a string in memory.
terminal.
the
from
This section discusses reading a number directiy

Refer to Section 2.9 for an example of using the NIN¥ call to read the
is
the number
The destination for
number from a string in memory.

AC2, and the NIN% call places the binary value of the number read into
in AC3
The user's program also specifies a number
this accumulator.
given
radix
The
input.
being
number
the
of
radix
represents the
that
can be in the range 2-36.

2-4

INPUT AND

Thus,

the

setup for

MOVEI

OUTPUT USING THE TERMINAL

the NIN% monitor

AC1,.PRIIN

;AC1

call

contains

the

following:

the primary

input designator

the

the number

; (the user's terminal)
MOVE|

AC3,AD10

;AC3

contains

;input

NIN%
After
one

the

;The call

completion

two

places

execution

the

NIN¥

call,

(refer

Section

the

call,

call.

This

instruction

to an

error

processing

error

Monitor

code

Calls

the

placed

means

the error

following
from

terminates

The

call.

number

the

Section

codes).

32X1

from

character,

typed

because

the

the NIN%

a message

the

user

input

any

nondigit

with

any

that

input

read
he

and

the

typing

AC1, .PRIIN

;input

MOVE!I

AC3,AD10

suse

NINERR

NUMSEC:BLOCK

from

the

NUMSEC

serror-go

; save

number

because

terminal
radix

number

error

the

routine

entered

(for

2.9)
it

(for

character) .

return

characters

Section

it.

;input a decimal

ERJMP

the second
terminal

therefore,

terminal

the decimal

that

joutput a prompt message

MOVE!

MOVEM AC2,

the

accepts

Note

SEARCH MONSYM

NIN%

Also,
TOPS-20

the execution

control

HRRO!

AC1,[ASCIZ/
Enter # of seconds:
/]
PSOUT%

the

terminated when

then

editing

(refer

terminal,

call

character;

the

from

terminal.

The RDTTY% call

programs
his

jump-type

it encounters a nondigit character

program prints

his

edit

were

instruction

a
of

returns

during

1.2.2).

input

program
occurs

Appendix

control

The

punctuation

(octal)

CTRL/W).

the

reading on

edit

DELETE,

successful,

terminates when

that

user

for

letter,

the

used

Reference Manual

following

contains

cannot

(refer

should

(see

the

error

AC2.

example,

number

routine

returns

instruction
AC3

call

The NIN¥ call
This

placed

NIN¥

instruction

returns

1.2.2).

control

the

being

number)

input the number

control

following
an

radix of

(in this case a decimal

AC2

read

decimal
NIN%

call

the

user

example,

should

allows

the

INPUT AND OUTPUT USING THE TERMINAL

2.5

WRITING A NUMBER

integer.
The NOUT% (Number Output) monitor call is used to output an
The user's program moves the number to be output into AC2. The
and the
in ACI
program must specify the destination for the number
radix in which the number is to be output in AC3. The radix given
In addition, the user's program can
cannot be greater than base 36.
specify certain formatting options to be used when printing the
number.

Thus, the general setup for the NOUT% monitor call
AC1:

output designator

AC2:

number being output

AC3:

format options

in left half and radix in right half

The format options that can be specified
described

in Table

is as follows:

2-1.

2-6

in the left half of

AC3

are

INPUT AND

Table 2-1:

OUTPUT USING THE TERMINAL

NOUT% Format Option

Bit

Symbol

Meaning

NOBMAG

the

number .

number
For

example,

positive

36-bit

-1 would be printed

as 777777 777777 if radix=8).
]

NO%SGN

Print the appropriate sign (+ or -)
the

number.

both on,

NO%LFL

NO%ZRO

a plus

sign

leading filler.

set,

trailing

Use

NO%O0O0V

NO%AST

this bit

the

leading

the

1leading

not

filler

the

columns allows filling.
set,

blanks

are used

the number

overflow

this

bit

columns

1is

and
not

return
set,

column

not output.

Print asterisks when the column
overflows.
If
this bit is not set, and bit & (NO%OOV)
set,

all

necessary

the columns

digits

printed

number

(must be 0).

the

This

value

includes

this

field

columns

indicated.

the sign column.
as

necessary are printed.

2-7

are

overflow.

Reserved for Digital
NO%COL

1is

printed and bit

filling.

error.

11-17

filler

Output on column

when

6-10

ignored.

0O's

allows

printed.

|If this bit

filler

specified number of

is always

NO%ZRO

before

If bits NOYMAG and NO%SGN are

many

columns

|If
as

INPUT AND

The

following

instruction

call.

This

user's

terminal.

special

OUTPUT USING THE TERMINAL

sequence

sequence prints

The number

number,

an example of
stored

can be positive,

the NOUT%¥

location

monitor

NUMB,

negative or

the

2zero,

with

location

NUMB

formatting.

MOVX

AC1,.PRIOU

suse primary output

MOVE

AC2,NUMB

sget

MOVX

AC3,AD10

syno special

NOUT%

number

from

format,decimal

radix

sprint number

EJSHLT

sunexpected

fatal

error.

Halt

sand print message.
Refer

to Section

following
described
monitor

1.2.2

example
so

far,

calls

for

information

illustrates
as well

are described

MONSYM

HACSYTM

+REQUIRE

the

concerning
use

the TMSG macro.
in

Section

error

the
The

returns.

The

three monitor

calls

RESET%

and

HALTF%

2.6.

SYSIMACREL

ACL==1
AC2==2

ACT==]
START!

RESETXZ

HRROI

irrerare

AC1,LASCIZ/FLEASE

TYFE

DECIMAL

rrodgram

NUMERER:

environment

FSOUTZ
MOVEI

ACls .FRIIN

isource

MOVEI

AC3,"D10

idecimal

desidgnator

radix

NINYZ

ERJMFS

ERROR
«THE OCTAL

TMSG

1if
EQUIVALENT

inrut

IS8

error

MOVEI

ACLl,.FRIQU

idestination

MOVEI

AC3,"08

taoctasl

radix

ifatal

error,

messadger

halt,

desidgnator

NOUTZ
EJSHLT

ERRQR?!

HALTFZ

yreturn

JRST

ibegin

START

Same

command

ada2iny

ERJMFS

ERROR.

landuade

continued

TMSG-

TERROR-TYFE

START

HEGIN

AGAIN:

HALTFZ

JRST
ENDII

2.6

START

suser

tures

continue-start

START

adgain

INITIALIZING AND TERMINATING THE PROGRAM

Two monitor

calls

above program -

that

have

not

yet been described were

RESET% and HALTF%.

2-8

used

the

INPUT AND

2.6.1

OUTPUT USING THE TERMINAL

RESET% Monitor Call

A good programming practice is to include the RESET% monitor
the

beginning

every assembly

any existing open files and

processes,

clears

performs

various

compiete

1list

refer

language program.

releases

their

JFNs,

kills

the software interrupt system
other

process

call

This call
any

closes

inferior

(see Chapter L), and

initilization

functions.

For

the functions provided by the RESET% monitor call,

to the description of

Reference Manual.

the call

The format of

the

the call

TOPS-20

Monitor

Calls

RESET%
and control

2.6.2

always

returns

to the next

instruction following

HALTF% Monitor Call

To stop the execution of a program and

Command Language,
last

the call.

return control

the

TOPS-20

then

resume

command

the user must include the HALTF% monitor call as the

instruction performed

in the program.

The user can

execution

of the program at the instruction following the HALTF% call

by typing

the CONTINUE command after

control

has

returned

level.

2.7

READING

BYTE

The PBIN% (Primary Byte Input) monitor call is used to read
a
single
byte
(that
is, one character) from the terminal.
The user's program
does not have to specify

because

this

«call

user's terminal)

uses

the

source

and

destination

primary input designator

as the source and accumulator

the

for

the

(that is,

byte

the

destination.

After
execution of the PBIN% call, control returns to the instruction
following the PBIN%.
|f execution of the call is successful, the byte
read from the terminal is right-justified in ACl.
|f execution of
call is not successful, an illegal instruction trap is
generated,
explained

2.8

in Section

1.2.2.

WRITING A BYTE

The PBOUT%
single

byte;

(Primary Byte Output)

byte

designator

the

(that is,

thus,

the

monitor

terminal.

This

the user's terminal)
wuser's

program

does

<call
call

is
wuses

used

as the destination
not

have

write

before

the

call.

2-9

the primary output

for

the

specify

the

destination.
The source of the byte being written is
accumulator
therefore,
the
wuser's program must place the byte right-justified
AC1

the
as

13
in

INPUT AND OUTPUT USING THE TERMINAL

After execution of the PBOUT% call, control returns to the instruction
following
the
PBOUT%.
If
execution of the call is successful, the
byte

is written

the user's

not

successful,

illegal

Section

2.9

this

byte.

point,

monitor

and
call

and,

input

typing

The RDTTYZ

terminal

space.

|Input

terminating

read

terminal

(that

Delete
the

the

handles
the

call

explained

for

reading
a

the

printing

and writing

string

terminal

from
to

the

edit

his

call

wuser

reads

either

inputs

types

the

whichever

character

input

from

the

into the program's address
an

occurs

editing

appropriate

maximum

number

first.

printed

OQutput

the

user's

.PRIOU).

the following editing functions:

last character

types

the

user

.PRIIN)

string,

Delete

the

key while

the user

and

obtains

monitor

from

output to

DELETE

the

character

Delete back

the

typing

last

the
his

string

punctuation

CTRL/W while

the

user

presses

input.

character

typing

his

the

string

input.

current

line

the

Retype the current

line

the user types CTRL/R while typing

his

accept
by

user

types

CTRL/U while

typing

input.

Because the RDTTY%Z call
corrected

allows

is,

result

is,

The RDTTY% call

can

the

generated,

presented

integer,

discussed

until

(break)

generated

it.

(that

allowed

addition,

characters

have been
an

(Read from Terminal)

user's

calls

writing
to

terminal
as

exetution of

STRING

reading
The

|If
trap

1.2.2.

READING

string,

terminal.

instruction

input
the

call

should

that

input with

can handle these editing functions,

from

user

used
calls

the
he

read

such

terminal

typing

input
NIN%.

and

it.

from

the

program

allow

this

input

to be

this

reason,

the

RDTTY

terminal

before

For

processing

INPUT AND

AC1:

pointer

area

to be placed.
AC2:

control

in
AC3:

the

The

control

the

left

half,

input

to buffer

bits

Symbol

RD¥BRK

RDXTOP

buffer
for

the user

called

text

CTRL/R.

left

half

input.

the

text

AC2

number

bytes

half.

specify

These bits

input

input buffer.

to be output before

to be output on a
the

through AC3.

space where

right

CTRL/R,

the

in AC1

and maximum

the

types a

RDTTY% Control

Bit

TERMINAL

address

area

if
is

program's

This

input

terminate

Table 2-2:

bits

text

pointer

input

which

THE

accepts three words of arguments

the

if only

the

wuser's

the user's

characters

are described

in Table

2-2.

Bits

Meaning
Terminate

input

when

user

CTRL/Z or

presses

the

ESC key.

Terminate

input when user types one of

the

following:

CTRL/G

CTRL/L

CTRL/Z
ESC

key

RETURN

Line

N
¥

The RDTTY% call

OUTPUT USING

key

feed

key

types

INPUT AND

Table 2-2:

RDTTY% Control

OUTPUT USING THE

Bits

TERMINAL

(Cont.)

Bit

Symbol

Meaning

RD%PUN

Terminate input when user types one of
the

following:

CTRL/A-CTRL/F
CTRL/H-CTRL/|

CTRL/K
CTRL/N-CTRL/Q

CTRL/S-CTRL/T
CTRL/X-CTRL/Y
ASCI| codes 34-36
ASC!| codes LO-57
ASC!1

codes

72-100

"ASCI1

codes

133-140

ASCI|

codes

173-176

The ASCI|

codes

listed

the

punctuation

ASCI|

character

set.

ASC!I

character

the

set

RD%BEL

RD%CRF

the

Appendix

Monitor

for

these

Calls

characters.

Store only the

line feed

in the

the

presses

the

return

will
but

when

key.

still

will

not be

carriage

output

bit

user

the

terminal

the buffer.

not

set

the

RETURN

carriage

return

and

stored

part of

the

input.
take

past

This

delete

all

set,

not

the

wuser

key,

both

the

feed will

input.

the user attempts
beginning

the

his

input.

the

line

the

allows

control

program

wuser

|[|f

program waits

tries

this

2-12

his

to
to

bit

for more

input.

Reserved for Digital

|If

and

the

Return to program
delete

input

stored

presses

the
end

buffer

this

RDZRND

table

Terminate input when
user
types
RETURN
or line feed key (that is,
of line).

RETURN

represent

Refer

TOPS-20

Reference Manual

above

characters

(must be 0).

INPUT AND

Table

2-2:

RDTTY% Control

OUTPUT USING THE TERMINAL

Bits

(Cont.)

Bit

Symbol

Meaning

RDXRIE

Return

program

when

input

there

(that is, the text input buffer
is empty).
|If this bit
is
not
set,

the

program waits

Reserved

RD¥BEG

Return

for

RDZRA|

Digital

to user

attempts

the

for

input.

(must

be 0).

program

edit

beyond

the

beginning

input buffer.

Convert

lower

case

input

user

upper

case,

RD%SUI

Suppress

the

terminal

when

user.

indication on

CTRL/U

means

that

types

CTRL/U,

XXX

printed

and,

the

on
will

screen.

and

the

printed

user

screen.

stored

Disable
break

types

input

editing
mask.

|If

the
user

not

the

not

deleted
case

from

set

XXX will

appropriate,
from

the

the
the

CTRL/U

buffer.

characters

user

set,

then

this

bit

(AR,

AU,

any

editing

character

and

DELETE)

mask

does

not

function.

will

CTRL/U,

neither

the

be deleted

the

terminals,

bit

will

|In

not

typed
if

display

this

and,

characters

RDENED

This

characters

CTRL/U

the user
have

AV,

Ay,

supplied break
its

editing

INPUT AND OUTPUT USING THE TERMINAL

If no control bits are set in the left half of AC2, the input will

terminated when the user presses the RETURN or line feed key (that is,
terminated on an end-of-line condition only).

The count in the right half of AC2 specifies the number of bytes
available for storing the string in the program's address space. The
input is terminated when this count is exhausted, even if a specified
break character has not yet been typed.

The pointer in AC3 is to the beginning of a buffer containing the text
to be output if the user types a CTRL/R. When this happens, the text
in this separate buffer is output, followed by any text that has been
typed by the user. The text in this buffer cannot be edited with any

of the editing characters (that is, DELETE, CTRL/W,
the

contents

CTRL/V) .

AC3 is zero, then no such buffer exists, and if the

user types CTRL/R, only the text in the input buffer will be output.

|f execution of the RDTTY% call is successful, the input is in the
specified area in the program's address space. The character that
(If the terminating character is
terminated the input is also stored.
a carriage return followed by a line feed, the line feed is also
stored.) Control returns to the user's program at the second location
following the <call. The pointer in ACl is advanced to the character
following the last character stored. The count in the right half of
AC2 is updated to reflect the remaining bytes in the buffer, and
appropriate bits are set in the left half of AC2. The bits that can
be set on a successful

Bit 12

RD%BTM

return are:

The input was terminated
of

because

one

the specified break characters was

This break character is placed
typed.
|If this bit is
input buffer.
in the
terminated
input was
the
not set,
because the byte count was exhausted.

Bit 13

RD%BFE

Control was returned

because

there

RD%RIE was set

Bit 14

RD%BLR

1is

the

program

more input and

in the call.

The 1limit to which the user can backup
for editing his input was reached.

For consistent handling of error returns refer to Section 1.2.2.

INPUT AND

The

following example

data

from

the

OUTPUT USING THE TERMINAL

illustrates

terminal.

the

recommended method

This example

essentially

one in Section 2.5; however, the RDTTY%¥
call
number
before
the
NIN%
call processes it.
last error

encountered

1location

LASTER

for

reading
as

the

is
used
to
read
This program stores

the
the

and

the

same

therefore

uses

the

———in —————

ERJMPR pseudo-op.

SEARCH MONSYM

SEARCH MACSYM

—————r: Srt—

.REQUIRE

w———

AC2==
AC3==3

START:

RESET%
HRRO|

;prepare program environment

————

PSOUT%

————————

AC1,PROMPT

HRROI

AC1,BUFFER

slocation

MOVE!l

AC2,BUFLEN%*5S

;size of

buffer

———

—

SYS:MACREL

ACl==

; type prompt

HRRO|

AC3,PROMPT

;pointer

to prompt

————

RDTTY%

store

;read number from term. with editing
code,

print message

——

;jsave error

;source designhator

—

ERROR

AC1,BUFFER

MOVE!|

AC3,AD10

;decimal

———

ERJMPR

HRRO!

NIN%

Y———————

——

ERJMPR

TMSG

AC1,.PRIOU

S—
—

ERJMPR

ERROR

;save

Y —

JRST START

BLOCK

BUFLEN

LASTER:

BLOCK

ERROR:

MOVEM AC1,LASTER

t——

—

BUFLEN==10

TMSG

DECIMAL

error

NUMBER:

code,

print message

;save

error

language

continued

code

AGAIN>;print

r—

BEGIN

shalt

—

START TO

HALTF%
JRST

sstart

7ERROR-TYPE

print message

END

START
START

and

halt

radix

;begin again,

——

error,

;return to command

ASCIZ/PLEASE TYPE

halt

;destination designator

HALTF%
PROMPT:

and

radix

input

soctal

BUFFER:

———

EQUIVALENT

MOVE! AC3,~D8
NOUT%

———
——

;if

OCTAL

—

———

ERROR

<THE

MOVEI

number

general

over

error

message

continued

and

halt

INPUT AND OUTPUT USING THE TERMINAL

2.10

SUMMARY

Data transfers of sequential bytes or text strings can be made to

and

from the terminal. The monitor calls for transferring bytes are PBIN%
The
and PBOUTY and for transferring strings are PSOUT%¥ and RDTTY%.

NIN¥ and NOUT% monitor calls can be used for reading and writing a
number. In general, the user's program must specify a source from
which the data is to be obtained and a destination where the data is
in the case of terminal 1/0, the symbol .PRIIN
to be placed.
represents the wuser's terminal as the source, and the symbol .PRIOU
represents the user's terminal as the destination.

CHAPTER
USING

3.1

OVERVIEW

All

information

basic

stored

unit

length.

36 bits
most

cases,

same

manner,

particular
Programs

storage
have

certain

file

a sequence of pages constitutes a file.
names.

Although

operations

can

reference

files

sequential

multiple

are

random

several

all

files

are

unavailable

and

byte

memory

all

area

user's
512-word

input/output
programs

another.
to

string

files

the

particular

pages

manner.
manner

it.

section-mapping

are

perform

For

another,

terminal

In
the

methods:

byte-by-byte

page-mapping

string

Generally,

location

for

manner

for

disk.
Byte

handled

The
1

byte-by-byte manner.

file-storage device allows
®

s
kept
in
files.
page containing bytes from

devices.

FILES

the DECSYSTEM-20

Thus,

files

the most
1/0

from

memory

memory.

512-page

example,

common

moving

sections

vice versa.

3~1

bytes

programs

from

file,

operations.

data

can move

disk

addition,

types

files

from

bytes
and

one

from one
from

the

program can map multiple

disk

file

into

memory

USING

Data transfer
1.

operations on files

Establishing

Number
2.

because all

the file

byte

size

and

to be

accessed.

to establish
to

set

file and a

Job

File

files are referenced by JFNs.

the data mode,

the monitor

and

permit data

Closing the file to complete any 1/0, to update the directory
if
the file is on the disk, and to release the monitor table

steps

above.

file,

these

files

changing

the
do

not

require
code or

require all

the file has a JFN associated with
is

possible

read

for

possible,

all

directory

cause a

into a

disk

written by

the

number

instances

the

process

can

execution
are:

to a

allowed

Although

require

that

same data.

simultaneously

sharing

file

Therefore,

files

specific

data written

seen by other

processes

file.

assigned
access

to be

To make

Access to files is controlled by the 6-digit

owner

four

renaming

above).

specific

immediately

all

file.

they do

DECSYSTEM-20
a

the

steps,

(step

deleting or

account of
four

processes.

opening

reference

file by one

reading

files on

any

the

these operations

access

not

file.

Examples of

operations

from the

that

the

to or

access mode,

tables

Transferring data either

Some operations

steps:

space used by

require four

a correspondence between a

(JFN),

Opening

FILES

file when

the

file,

file

the

created.
for

users

the

with

(octal)

This

three

code

file access

indicates

<classes

group access

the

code

the

types

users:
file,

the

and

all

other users.
(Refer to the TOPS-20 User's Guide for more
information
on the file access codes.) If the user is allowed access to a file, he
requests

the

type

OPENF%

monitor

access

requested

access

current

access

Thus,

for

the

The

access

desired when

the OPENF% call
the

The

does

granted

set

the

first

granted

access

code must

allow

the

file

the

file

with

in his program.

not conflict with

wuser

access.
user

the current

Essentially,
who

the

If the

opens

the

it.

specific

file,

two

user

to access

the

file

be met:

file

access

in the desired manner
2.

opening

(refer to Section 3.4.1)

file,

user

conditions must

call

file must

not

the

(for example,

be opened

3-2

for

read, write).

conflicting

type

access.

USING FILES

3.2

JOB

FILE NUMBER

The Job File Number (JFN) is one of the more important concepts in the
operating system because it serves as the identifier of a particular
is a
It
execution.
file on a particular device during a process'
user's
the
from
request
a
upon
system
the
by
assigned
integer
small
JFNs are usually assigned sequentially starting with 1.
program.
The JFN is valid for the job in which it is assigned and may be used
by any process in the job. The system uses the JFN as an index into
the table of files associated with the job and always assigns a JFN
Even though a particular JFN within
is unique within the job.
that
the job can refer to only one file, a single file can be associated
than

one JFN.

This occurs when two or more processes are

with

will

be associated with the same file.

3.3

ASSOCIATING A FILE WITH A JFN

In this case, each of the processes
using the same file concurrently.
probably have a different JFN for the file, but all of the JFNs
will

In order to reference a file,

complete

associate

the first step

specific

the

file

correspondence is established with the GTJFN% (Get

user

with

Job

program

JFN.

File

must

This

Number)

One of the arguments to this call is the string
monitor call.
representing the desired file. The string can be specified within the
1is, come from memory) or can be accepted as input from
(that
program
the user's terminal or from another file.

The

string

can

represent

the complete specification for the file:

(account) ;
gen;T
;P (protection) ;A
ame.typ.
(temporary)
dev:<directory>n
(device dependent attributes)

If you omit any fields of the specification, the system can provide
except the name field. Refer to the TOPS-20 User's
values for all
Guide for a complete explanation of the specification for a file.

Table 3-1

lists the values

specified by the

the

input string.

system

will

assign

fields

not

USING

Table 3-1:

FILES

Standard System Values For File Specifications

Field

Value

Device

DSK:

directory

specification

<L I BRARY>MYF
I LE.F0%
identifies
and

all

the

files

three-character

.FO.

Upon

in directory <LIBRARY> with

file

type

in which

the

first

the

GTJFN

<call,

the

completion

associated

with

the

first

file

found

the

name

MYFILE

two characters

JFN

are

returned

the group according

the

following:

numerical

alphabetical

order

filename

alphabetical

order

file

ascending

The GNJFN¥
program

will

that

file

and not

obtain

the

code

execution of
in

half,

flag

returned
or

13 was

execution of

GTJFN% call.

all

for

returned

the

right

bits

half

11,

12,

successful

each

one.

not

not on
the

the

JFN

ACi.

half

following

AC1

and

13 were

various

are described

call,

program continues

the

not
The

left

half

the

second

same

JFN

problems

assigned

and

execution

the GTJFN% call.

JFN
are

assigned

set

call.

in Table

the

because
is

the
bits

Normally,

specification

using

successful

is successful,

file

the group

call,

right

number

to Section 3.7.3).

instruction

call

generation

can then be given to assign the

(refer
files

the

the GTJFN% call

the

on a

JFN

characters

performing

program continues

returned

12,

reference

number

type

monitor call

the group

the GTJFN% call

encountered

error

order

wildcard

another

|f execution of
were

accepts

successively

by directory

numerical

(Get Next JFN)

JFN to the next
a

order

ACl

the

(The

3-3.)

zero.

instruction

bit

after

is
left

bits

11,
The
the

USING

Table 3-3:

FILES

Bits Returned on GTJFN% Call

Bit

Symbol

Meaning

GJYDEV

The

device

field

specification

the

contains

file

wildcard

characters.

GJXUNT

The

unit

field

specifications
characters.

GJEDIR

This

bit

wildcard

allowed

in unit fields.

directory

never

characters

field

specification

file
wildcard

because

The

the

contains

the

contains

set

are not

file

wildcard

characters.

GJENAM

The

filename

field

specification

the

contains

file

wildcard

characters.

GJXEXT

The

file

type

field

specification

the

contains

file

wildcard

characters.

GJXVER

The generation
file

number

specification

field

the

contains wildcard.

characters.

GJEUHV

The

file

used

has

generation number

number

GJENHV

of O was given

The file
generation

used

has

number

number of 0 or

-1

the

highest

because a generation

the call.

the

higher

because a generation

was

given

the

call.

GJIULV

The

file

used

generation number
number

GJ%PRO

The

-2 was

protection

has

the

lowest

because a generation
given

field

the call.

the

file

the

file

specification was given.

GJXACT

The

account

field

specification was

3-11

given.

USING FILES

Bits Returned on GTJFN% Call

Table 3-3:

Bit

Symbol

Meaning

GJXTFS

The

GJXGND

GJENOD

(Cont.)

for

deletion

are

not

considered
when
assigning
JFNs
subsequent calls.
This bit is set
GJ%XDEL was not set in the call.

in
if

file

specification

temporary file.

Files

The

marked

node

name

for

field

the

file

not

considered

specification was given.

GJXGIV

Invisible files

were

when assigning JFNs.

Examples of the short form of the GTJFN% monitor call are shown in the
following

paragraphs.

The following sequence of instructions is used
to obtain,
user's terminal, the specification of an existing file.

from

the

MOVX AC1,GJYOLD+GJIY¥FNS+GJSSHT
MOVE AC2,[.PRIIN,,.PRIOU]
GTJFN%
The bits specified for ACl1

indicate that the file specification

given

must refer
to an existing file (GJ%0LD), that the file specification
is to be accepted from the input JFN in AC2
(GJ%FNS),
and that the
short form of
the GTJFN% call is being used (GJ%¥SHT).
Because the

right half of AC1 is zero, the standard
generation
number
algorithm
will be used.
In this GTJFN% call, the file with the highest existing
generation number is used.
Because GJYFNS is set in ACl1, the contents
of
AC2
are interpreted as containing an input JFN and an output JFN.
In this example, the file specification is obtained from the
terminal

(.PRIIN).

The following sequence of instructions is used
to
obtain,
from
the
user's
terminal,
the
specification of an output file and to require
confirmation from the
user
once
the
file
specification
has
been
obtained.

MOVX AC1,GJZFOU+GJIEMSG+GJECFM+GISFNS+GISSHT
MOVE AC2,[.PRIIN,,.PRIOU]
GTJFN%

USING

in this example,

FILES

the bits specified for ACl1

indicate that

the file obtained is to be an output file (GJ¥FOU),

after the file specification is obtained, a message is to
typed (GJ%MSG)
,

the user is required to confirm the file
was obtained (GJZCFM),

the file specification is to be obtained from the
in AC2 (GJ%FNS),

the short form of the GTJFN% call is being used (GJ¥SHT).

specification

that

input

JFN

Because the right half of ACl1 is zero, the generation number given to
than the highest generation number
be one greater
the file will
interpreted as
AC2 are
The contents of
existing for the file.

containing

input

and an output JFN because GJZFNS is set in

JFN

AC1.

The following sequence of instructions is used to obtain the
an existing file from a location in the user's program.

name

MOVX AC1,GJBOLD+GJ%SHT
MOVE AC2,[POINT 7,NAME]
GTJFN%

NAME:ASCIZ/MYFILE.TXT/

The bits specified for ACl1

existing

being used

file

indicate that the file obtained is to be an

(GJ¥OLD) and that the short form of the GTJFN¥ call

(GJ¥SHT).

highest

with

the

from

location NAME

Since the right half of ACl

generation number will be used.

=zero,

the

file

Because GJBFNS is

not set, the contents of AC2 are interpreted as containing a pointer
in memory that specifies the file to be associated with
to a string
at
the string begins
that
indicates
AC2
The setup of
the JFN.
obtained
specification
file
The
program.
user's
the
in
location NAME
is MYFILE.TXT.

USING FILES

An alternate way of specifying the same file is the sequence

MOVX AC1,GJREOLD+GJESHT
HRRO! AC2, [ASCIZ/MYFILE.TXT/]
GTJFN%

3.3.1.2
call

Long Form Of GTJFN% - The long form

requires

0
AC1

the

GTJFN%

monitor

the following two words of arguments:

!
!

=
address of argument table

!
!

AC2

!
!

pointer

The argument block for

Table 3-4:

to ASCIZ file specification string,

the

long form

is described

!
!

or O

in Table 3-L4.

Long Form GTJFN% Argument Block

Word

Symbol

.GJGEN

Meaning

Flag bits

appear

generation

number

the

left half

appears

the

and

right

half.

.GJSRC

input

JFN

appears

the

and an output JFN appears

half.

To omit either

program must

.
(377777)

.GJDEV

Pointer
the
used.

JFN,
the

to ASCIZ string

device

given.

specify

|If

this word

left

half

the

right

the

wuser's

symbol

.NULIO

that

specifies

wused when
is

none

DSK will

USING

Table 3-4:

FILES

Long Form GTJFN%® Argument Block

Word

Symbol

Meaning

.GJDIR

Pointer
the

to ASCIZ

directory

given.

|If

connected

.GJINAM

Pointer
the
must

LGJEXT

the
will

.GJPRO

to be

this word

the

|If

used.

used when

string

none

the

that

Pointer to ASCIZ string
code.

protection

| f

protection

This

input

specifies

none

null

type

3B2+octal

word

indicates

to be

used when

none

this

word

the

specified

Pointer

to ASCIZ

string or

number.

This

account

given.

|If

be used.

account

the

wuser's

to be used when

this word

directory will
.GJACT

none

the

be used.

given.

is 0,

filename.

ASCIZ
type

protection
the

specifies

to ASCIZ string that specifies

file

given.

that

directory will

specify

Pointer

string

to be used when

this word

filename

given.

(Cont.)

to be

used

this word

specified when

the

3B2+decimal

word

indicates

when

user

none

the account

logged

in will

be used.
10

.GJJFN

The

JFN

assign

specification

set

in word

argument

11-17

flag

.GJGEN

the

bit

(word

the

flag

bit

block.

Additional

words

allowed

GJEXTN
(bit 15) is set in word
(word 0) of the argument block.
additional

words

are

performing

command

input

are

Calls

file

GJ%¥JFN

described

the

Reference Manual.

.GJGEN
These

used

when

parsing

TOPS-20

and

Monitor

USING

FILES

The flag bits accepted

in the left half of

argument

same as

block are

GTJFN% call.
The

number

values

although O

3-2

explanations

accepted

the normal
of

half

3-3

for

the

right

flag bits
the

execution of
and

execution of

half

11,

12 or

explanations

program continues

assigned

the

(word

short

form of

the

listed

Refer

the
the

in Table 3-2.

right

-1,

-2,

half

.(GJGEN

-3, or a specified

to Bits

and various

13 were on
of

second

GTJFN

call

code

is successful,

ACl

the

error

case.

18-35

Table

these values.

|f execution of the GTJFN%¥ call
returned

.GJGEN

accepted

the argument block can be 0,

number,
for

those

The entire set of flag bits

generation

(word

the

not

program continues

assigned

set

Refer

returned.

instruction
is

JFN
are

the call.

bits

returned

the
bits

the
the

JFN

half

the

Table

instruction

the

call.

successful,
right

is
left

Execution of

following

the

not

ACl.

The

following

the

GTJFN% call.
The

following

existing
higher

used

sequence of

file

from

generation of

that

the user omits
MOVE!

instructions

the user's
a

file,

obtains

terminal,
and

field when

specification

assigns

specifies

he gives

the JFN

default

his

AC1,JFNTAB

GTJFN%

GJ%FOU
XWD

.PRIIN,.PRIOU

POINT 7,[ASCIZ/TRAIN/]

sdefault directory

POINT 7, [ASCIZ/MEM/]

;default file type

0
0
0

3-16

fields

for

the next
to

file specification.

SETZ AC2,

JFNTAB:

USING

The

address

given

pointer

will

string

block

(GJ%FOU)

the

The

the

AC].

thus,

flag

bit

the

(JFNTAB)

which means

for

the

file

The

GTJFN%

specification

first word of

the

call.

bit

next higher generation number
is

be printed

type MEM will

specification,

for

call

contains

terminal.

second word

GTJFN%

AC2

fields

generated

name

the

the user's

specification

<TRAIN> will

obtained

because

his

part

terminal.
his

be used.

And

the

used.

the argument

the user's

user

|If

the user

employing
does

3.3.1.3

Summary Of
a

does

not

the

give a

file

omits

other

fields

from

(refer

to Table 3-1)

will

the GTJFN% call

However,

the

long

program more

The

GTJFN% - The GTJFN% monitor

JFN with

file.

is sufficient for
form

control

following

particular
is more

over

summary

the

Assigns

the

characteristics

compares

JFN

Long

to a

the

from a

specification

fields

the

and

not

Allows

given

file

specification.

3.4

JFN

file

JFN of

byte

obtained.

two

forms

JFN to a

file.

the
a

request

JFN.

file

specification

string

in memory

file.

user-supplied values

to be

used

given

for

the

fields

not

file

specification.

OPENING A FILE

Once a

the

the user's

the

particular

from a

system values

that

to
form

association.

provides

program may

Accepts

in memory

file.

standard

for

file

string

User
a

short

Form

Assigns

assign.

Accepts

Uses

file.

the JFN

required
the

this

specification

Form

System decides
to

establishing
because

cases,

file

the GTJFN% monitor call.

Short

call

In most

powerful

not

specification,

the user
user

from

is to be
indicates

the

file

the system standard value

block

This

used.

associate

that

directory

directory
type,

and any output

recognition

for

given;

from

file.

file

terminal,

his

contains

the

table

half

only

indicates

assigned

supply

argument

right

taken

argument

that

the

FILES

has

the file

size,

been obtained

in order

to be opened

data mode,

for

transfer
and

and access

file,

data.

the

a word

file.

the

user's

The user's
bits

program must

open

program supplies

the

indicating

the desired

USING

FILES

The desired access to the file is specified by a separate bit for each
type of
access.
The file is successfully opened only if the desired

access does not conflict with the current access to the file (refer to

Section
3.1).
For example, if the user requests both read and write
access to the file, but write access is not allowed, then the file
s
not opened for
®

this user.

Read access.
random

The allowed types of access to a file are:

The file can be

read

with

byte,

string,

input.

Write access.

The

file can be written with byte,

random output.

Append access.

The

file

can be written only with

sequential

byte
or
dump output, and the current byte pointer (refer to
Section 3.5.1) cannot be changed.
The
initial
position
of
the
®

file pointer

Frozen
most

access.
one

reading
e

Thawed

are
®

user

3.4.1

access.

reading

the end
can

the

file,

This

The

access.
has

file

OPENF% Monitor

The

read

can

the

monitor

call
of

cannot

file

access
even

to a
if

accessed

can

the

opens: a

by
of

file.

other

users

another

read

regardless

specified

file.

18
!

JFN

file

—— 1

to be opened

18
=

byte

!data

size

Imode

!
==]

| ========

35
P

users

file.

——

number

arguments.

| =====

AC2

any

Call

two words

AC1

accessed

doing with

requires

following

but

file.

The OPENF% (Open File)
the

concurrently accessed

The

file.

file

access.
might

the

the default

the

opened

users

file

and writing

already

other

writing

file.

Unrestricted
what

The

wuser

the

Restricted

30 31

—

access

bits

!
!

3-18

USING

the

left

half

pointer

requests bits

AC1

returned

not

string,

in AC1

FILES

the

not

contents

JFN.

ACl

from the GTJFN% call,

interpreted

the user's

program

these bits must be

cleared before executing the OPENF% call.

The byte size (OF%BSZ) in AC2 specifies the number
of
byte of the file and can be between 1 and 36 (decimal).
is O a byte size of 36 (decimal) is assumed.

The file data mode field

(OF%¥MOD)

usually has one of

Value

bits
in
each
If this field

two values:

Meaning

Normal

data mode of

the file

1/0).

Dump

illegal.

1/0

Dump mode

(that

1is,

Byte

illegal

1/0

(that

unbuffered
and

is,

byte

word

1/0).

the byte size

ignored.
The

access

Table 3-5:

bits

are described

in Table

3-5.

OPENF% Access Bits

Bit

Symbol

Meaning

0-5

OF%BSZ

Byte size

(maximum of 36 decimal).

6-9

OF%MOD

Data mode

in which to open file.

OF3HER

Halt

the

occurrence

medium

device

subsequent
bit
is

not

generated

error

|/0

a
a

occurs during

error

software
device

OF%RD

Allow read access.

OF ZWR

Allow write access.

OF %EX

Allow execute access.

OF%APP

Allow append access.

1/0

during

this

interrupt
or

subsequent

3-19

to the file.

set,
if

medium

/0.

USING

Table 3-5:

OPENF% Access Bits

FILES

(Cont.)

Bit

Symbol

Meaning

OF%RDU

Allow unrestricted read access.

Reserved for Digital.

OFXTHW

Allow thawed access.
not

set,

the

file

this

opened

bit

for

frozen

access.

OFZAWT

Block

OF%PDT

(that

is,

the

program

permitted.

temporarily

until

access

suspend)

the

file

Do not update the access dates of

the

file.

OF 3NWT

Return an error
cannot

OF%RTD

OF%PLN

if access to the

file

permitted.

Allow access

process
30

(that

to the file to
only
one
is, restricted access).

Do not check for

line numbers

the

file.

OF%DUD

OF%O0FL

OF%FDT

Suppress system updating
pages

memory

disk

unless

CLOSF

Open device even
Force update of
FDB and

OF%ZRAR

identical

the

file

modified

UFPGS

files

issued.

.FBREF
RH

(last read)

.FBCNT

(number

references).

Wait

cannot

thawed

if off-line.

increment

if file off-line.

If bits OF¥AWT and OFYNWT are both off,
access

permitted

to OF%NWT being on).

3-20

an error code
(that

is,

the

returned

action

taken

if
is

USING

If execution of
opened,

and

the OPENF% monitor call

the

execution

instruction after
| f

execution of

opened,

and

program

FILES

the

successful,

program

continues

the
at

file
the

second

the OPENF% call.

the OPENF% call

error

continues

code

the

is not

successful,

returned

instruction

Two samples of

the OPENF% call

The sequence of

instructions

ACl.

the
The

file

not

execution of

after

the

OPENF%

file

for

input.

the

call.

follow.

below opens

HRRZ AC1,JFNEXT

MOVX AC2,FLD (LL,0F%BSZ)+0F%RD+0F%PLN
OPENF%
The JFN

the

file

opened

contained

indicated
by the address in AC1 (JFNEXT).
indicate that the byte size is
one
word
access

is being requested to the file

be made

for

not

can be

line

numbers

discarded
accessed

The following

for

the

file;

the

location

The bits specified for AC2
FLD(L4L,0F¥BSZ),
that
read

(OP%RD),
that

is,

and
the

that no check will
line

numbers

(OF¥PLN).

Because bit OFXTHW is not set,

reading

any

sequence of

number

instructions

will

the file

processes.

can be used

to open

the

JFN

indicate

that

file

for

the

output.

MOVE

AC1,JFN

MOVX FLD (7,0F%BSZ)
+OF ¥HER+OF ¥WR+OF XAWT
OPENF%
The

right

file

half

AC1

to be opened.

contains

The bits

the address

specified

that

for

AC2

has

the byte

size

is 7-bit bytes FLD(7,0F%BSZ), that the program is
to
be
halted
an
1/0
error occurs in the file (OF¥HER), that write access is
being requested to the file (OF¥WR), and that the
program
is
to
be
blocked
if
access cannot be granted (OF¥AWT).
Because bit OFXTHW is

when

not

set,

another

this

user's

3.5

TRANSFERRING

Data

transfers

transfer
bytes

and

user

program will

entire

been

granted write

access

the

file,

access can be granted.

DATA

can

has

be blocked until

sequential
be

used with

pages

can

bytes
any

are

file.

also be

the
For

transferred.

3-21

most

disk

common

files,

form

nonsequential

USING

3.5.1

File

FILES

Pointer

Every open file

is associated with a pointer

that

indicates

the

last

byte
read
from
or
opened, this pointer

written to the file.
When the file is initially
is normally positioned before
the
beginning
of

the

file

the

byte

data

that

the file.

first data operation will

The pointer

transferred.

However,

then advanced
if

the

file

access

(bit OF¥APP set

in the OPENF% call),

after

the

operation
For

disk

the

last

to append data
files,

file,

indication

updated

writes
(refer
it

file.

the end of

the

repositioned

when
the

end

the

the end of

the

data

positioned
first write

file,

a write

the

new data.

throughout

transfers.
an

program attempts

possible

the

for

indicator.

file,

the

file

contain

To allow sequential

program

should update

When

end-of-file

read operation

operation

beyond

end-of-file

indicator

However,

the

Source

And

Destination

Because

|1/0 operations occur

another,

the

user's

program

The

to be

<call

data beyond
performed

count

the

later

before closing

description

the

Designators

moving

program must

1/0 operation.

pages
|1/0

the byte

the file.
(Refer to
the
CHFDB%¥
monitor
TOPS-20 Monitor Calls Reference Manual.)

any

is
the

pages
beyond
the end of the file with the PMAP% monitor call
to section 3.5.6), the byte count is not
updated.
Therefore,

3.5.2

append-only

arbitrarily

the

program performs

file using byte output,

first

file

file.

nonsequential

the

for

allows

the

the pointer

This

may be

When

the

is opened

the case of

returned

to point

end-of-file
to

pointer

input.
of

the

positioned beyond

using byte
end

the

such

the pointer

the

byte

reference

through

most

supply

data
a

from

source

commonly-used

and

source

one
a

location

destination

for

and

destination

designators are the following:
1.

JFN

associated with

previously
before

The

obtained
can be

primary

respectively
should

input

particular

with

file.

The

JFN

must

the GTJFN% or GNJFN% monitor call

used.

and

(refer

used when

output

designators

Section

referring

3-22

2.2).
the

.PRIIN

These

terminal.

and

.PRIOU,

designators

USING

byte

pointer

program's

byte pointer
®

can

A word with

right
string

Most

monitor

strings.

of 0

full

calls

is,

optionally

accept
are

sizes

than

3.5.3

(Byte

given

from

AC2

that

the

assembled

byte

ASCII|

two

the

word

half

with

and

Sequential

and BOUT%

and

places
it

the

the OPENF%

reached,

this

the

call

generated.

instruction

and/or

the

to be output,

the

call,

call

Control

the

returns

ASCII

some

byte

calls

terminating byte.
strings

and

byte

used

are

takes

byte

from

takes

the

byte

AC2.

for

call,

not

call
The

the

BOUT%

byte

successful,

instead

call

a jump

The

size

ACl,

the

byte

the

style

illegal

the

byte.

and

right-justified

user's

end
The

error

the

program

return

AC2.

instruction

program

upon

can

the

file

process

the

the BIN% call.

accepts a destination designator
is

written

successful,
the

the

file.

returns

right-justified

byte

not

with

monitor calls

BIN%¥

given destination.

call

the

condition

following

The BOUT% monitor call
byte

bits.

(Byte Output)

the BiIN% call.

contains

end-of-file

instruction

The
in

Control

following

AC2

terminate with

non-ASCI!
I

accepts a source designator

execution

size

However

pseudo-op.

Bytes

transfers.

and writes

execution

the

ASCIZ

specified

successful

7-bit

specifically

count

handle

address

equivalent

The BIN% monitor call

trap

the

The

bits.

byte

the

byte

deal

byte

that

bytes

functionally
7,ADR

are assumed

explicit

byte

POINT

strings

read or written.

to designate a

form

the

string

forms:

left-most

pointer

strings

the

being

used

this
by

left

form

generally ones

source

given

Input)

for sequential
the

dealing with

Transferring

The BIN%

that

are assumed to be ASC|Z strings).

These calls
other

-1

This

word

Normally,

(that

starting

word

beginning

space

take one of

half.

address.

the

address

FILES

user's

AC2.

Upon

in ACl1

successful

the

destination.

|If

illegal

instruction

trap

program

BOUT% call.

3-23

the

instruction

and

execution

the

execution
of

generated

following

the

USING

The following sequence shows

FILES

the transferring of bytes from

file to an output file.
The bytes are read from the file
INJFN and written to the file indicated by OUTJFN.
LOOP:

MOVE

1,iINJFN

;get

BIN%
LOOP2:

DONE

;check

1,0UTJFN

;get destination from OUTJFN

for

end of

file,

swrite the byte to the destination
LOOP

scontinue until

O byte

GTSTS%
TXNN 2,GS%EOF

;obtain status of source
;test for end of file

JRST NOTYET

s;nho,

;yes,

process

input

JRST

2,0

test

for

end

input
of

found

file

file condition

file

LOOP2

Transferring Strings

The SIN%

(String

wused

string of
a

INJFN

ERJMP

NOTYET:MOVEI

are

from

MOVE
JRST

3.5.4

input

;read a byte from the source

BOUT%
DONE:

source designator

indicated by

specific

for
a

Input)

and SOUT%

(String Output)

string

transfers.

These calls

specified

number

bytes or

into the program's

string

in AC1

reads a string from

address

space.

terminated with

source designator

AC2:

pointer

AC3:

count

ACL:

byte on which to terminate

AC3

the

The call

specified

accepts

source

four words of

through ACL.

AC1:

The contents of

calls

either

byte.

The SIN% monitor call
arguments

monitor

transfer

area

program's

number

bytes

are

interpreted

address

space

read,

input

(optional)

the

number

characters

read.

|If

AC3

the

input.

|[f

AC3

specified

given
e

AC3

then

reading

positive,
number

in ACL

specified

The contents of

then
of

found

reading
is

input,

the

then

number

bytes

ACL needs

is a positive number.

reading
is

until

continues

bytes

negative,
of

continues

read,

in ACL

3-2k

until

either

byte

equal

found

the
that

whichever occurs first.

continues

wuntil

minus

the

the contents of

AC3

read.

to be specified only

The byte

a 0 byte

right-justified.

USING

The

input

terminated when one of

The byte

The

The end of

FILES

count

specified

error

becomes

zero.

terminating

the

file

occurs

during

the following occurs:

byte

reached.

reached.
the

transfer

(for

error occurs).
Control

returns

SIN¥
call.
reached), an
several

locations

the user's

If
an
illegal

the

instruction

are

the

1/0

to the file.

The

pointer

the

last

byte

read

or,

The count
number

requested

zero).
number

file's

string
if

pointer

updated

AC3

AC2

contained

accepts

the

four

updated,
actually

to be read
bytes

The SOUT% monitor call
space

bytes

(that

From this count,
of

writes a

updated

for

the

last

AC3:

count

ACL:

byte on which

contents

are

in the SIN% monitor

The

transfer

AC3

and

The

byte

The

specified

number

count

are

becomes

through

bytes

updated

the
the

occurs

program's
SINY

the

bytes

toward

call,

address
this

call

ACL.

to write,

interpreted

one

(optional)
the

same manner

the

following

occurs.

reached.

This

byte

the destination.

during

they

zero.

terminating

the

subtracting
number

call.

is written

error

AC1

to terminate output

ACL

reflect

nonzero byte

to be written

terminated when

byte

string

subsequent

the

the count

pointer

The

is,

from

AC2:

the

pertinent,

string

arguments

read

destination.

destination designator

the

transferred.

AC1:

following

the user's program can determune the

actually

specified

words

data

updated:

read.

error
occurs
(including the end of the file is
instruction
trap
is
generated.
In
addition,

The position of

program at

example,

the

transfer.

3-25

terminating

USING

FILES

Control returns to the user's program at the instruction following the
If an error occurs, an illegal instruction trap is
SOUT% call.
the
In addition, the position of the file's pointer,
generated.
if pertinent, are

to the string in AC2, and the count in AC3,

pointer

also updated in the same manner as in the SIN% monitor call.

input
The following code sequence shows transferring a string from an
file to an output file. The procedure is the same as at the end of

Section 3.5.3, using SIN% and SOUT% calls instead of BIN%¥ and BOUT%.
saet source Trom INJFN
svointer to string to read into

MOVE 1yINJFN
HRROI 2yRBUF128

LOOF:

sirmeut 3 masimum of 640 hutes
stransfer until end of buffer or end of

3,711 28%%

MOVUNTI
SINZ

(128

buffer)

sword

sfile

ERCAL

ANDT

MOUN

EOQOFQ

serror

3y "ND128XS

jdetermine negative rnumber of bwtes

MOVE

1 INJFN

sobtain status of source
stest for end of file
srmoy continue corwing

Transferring Nonsequential

As discussed

in Section 3.5.3,

sequentially,

The RIN%

Bytes

the BIN% and BOUT% calls transfer bytes

starting at the current position of

(Random Input)

and ROUT%

(Random Output)

the
wuser's
program
to
specify
where
accepting a byte number within the file.

size

given in the OPENF% call

The RIN% monitor call
and places

the file

in ACl

successful

for the file.

the accumulator.

from disk

The call

the byte number within

completion of

the call,

allow

The RIN¥ and ROUT% calls

takes a byte from the specified

into

and

the file's pointer.

monitor calls

the
transfer
will begin by
The size of the byte is
the

can only be used when transferring data to or

file

transferraed

rositive

$get destination from QUTJIFN
srointer to string to write from
stransfer as many bytes as read

GTSTSZ
TXNN 2yGSZEOF
RET

3.5.5

sconvert

303

MOVE 1y0UTJFN
HRROI 2yRUFI128
SOUTH
EQOFQ:

ocourred

the

the byte

files.

location

accepts

file

the

the JFN of
AC3.

Upon

right-justified

in AC2,

and

the file's pointer is updated to point to the byte
following
the
just
read.
If
an error occurs, an illegal instruction trap is
generated.
Control returns to the user's program at
the
instruction

one

following the RIN% call.
The ROUT% monitor call
into
the

the specified
file

byte

in AC1,

the byte

number within

call,

the byte

file's

pointer

written.

generated.

takes a byte from the accumulator and writes

location
the

is updated
an

error

Control

the file.

to write

file

is written

in
in

The call

right-justified

AC3.

Upon

to point
occurs,

returns

to
an

3-26

illegal

the JFN of

AC2,

and

the

completion of

the

file,

the byte following

to the user's

following the ROUT% call.

successful

into the specified byte

accepts

the one just

instruction

program at

the

and

trap

instruction

USING

3.5.6
Up

Mapping Pages

this

bytes

and

transfer

Both

point,

entire

files

word,

and

where

space can

the process

file

the

the
is

also be

pages
page

illustrates

are

file

spaces

are

the

called

the

right

address

refer

the
to

map

1left

process
file

that

has

into
and

where

the

right

the
a

of
page

process

identifier

The

identifiers

files.

half.

address

When

Each

space

identifiers

page map,

page.

pages

page within

process

page map.

the

used

left half and the page

the

identified by one

half

in the

transferring

process.

divided

half.

space

pages

the process

placed
process

and

identified by one word,

the

for

to be discussed

to Section 5.3)
for

actually

presented

call

within a file can be

file

process'

identifier

in what

page

between

address

file

(refer

within

process

the

have been

The

data

JFN

address

placed

process

the

calls

data.

words.

within

number

pages

number

one-word

monitor

strings

512 (decimal)

FILES

references
following

for

the

diagram

pages

from

one

two

File
1

Process Map

JFN1

Page 1

-+1

Page 1

File
2

JFN2

Page 2

=1 Page 2

MR-5-2033-82

The PMAP%
entire

file

from a

(for output),

general,

this

file page
Mapping
pages

(Page Mapping)

pages

call

file

between

(for

changes

between
two

from

identifiers

pages

monitor call

and
a

process

one

processes

process

the entries

process

file and
is

used

the

page

3-27

map
from

process

described

input),

another
process

process

to a

process.

map by

accepting

identifiers

arguments.

below;

described

Chapter

mapping

USING

FILES

3.5.6.1

Mapping File Pages To A Process - This use of

the PMAP¥

changes

the

to pages

map

the

process

reference pages

in a file.

transferred;

simply changes

when changes are made
will

also

specified for
Note

made to

references

This does

the actual
the page

that

not actually cause

the contents of

page

the

file,

the map.

the process,

the
data

Later

the

changes

if write access

has been

the file.

that you cannot map file pages

to pages

in a process

section

that

does not exist

in the the process map.

|f you use PMAP¥ to input file

pages

in a nonexistent section

to pages

generates an

illegal

process,

The PMAP% call
AC1l:

the

AC2:

accepts three words of arguments

JFN of

half,

AC3:

the file

file

process

the

in the
right

monitor

identifier

and

page

left half,

(refer

number

(of 512 pages each)

in AC1

through AC3.

and the page

number

half

to
the

Section
process

5.3)

the

right

the

left

half

repetition count and access

The repetition count and access bits

described

the

instruction trap.

In addition, you can map one or more file sections
into a process.
See Section 8.3.1 for details.

call
in

in Table 3-6.

3-28

that can be specified

in AC3

are

USING

Table 3-6:

FILES

PMAP% Access Bits

Bit

Symbol

Meaning

PMECNT

Repeat the mapping

times

right

the

half

file

page

number

and

incremented

the page.

the process
each

number

AC3.

The

page

time

number

the operation

performed.

PMIRD

Allow

PMZWR

Allow write

PM%E
X

read

access
access

the

page.

Reserved.

The symbol

PM%PLD

the

are

operation

specified by

Preload

PM3RWX can be used to set B2-4,

page

immediately

being

mapped

instead

(move

waiting

the

page

until

referenced)
.

PM3CPY

Create

private

process

writes

copy-on-write
so

that

even

This

allows

PMZEPN

PMXABT

was

the

not

that

have

Bits

18-35 of AC2

This

copy

containing

the

page does

section

created.

page

and

called
changed
of

the

copy

page of

data

other

processes

extended

(18-bit)

page.

contain
number .

the

the original.

to change a
the

instead

for

to be

allowed

page

Unmap

the data

also mapped

page.

the map

the

access

the

page.

causes

process

changing

process

identifies

Write

without

and

original.
if

copy
into

| f

not

discard

the

exist,

(abort)

section
private

changed

contents.

18-35

PMZRPT

The

number

operation

times

if bit O(PM¥CNT)

3-29

repeat

is set.

the

mapping

USING

With this use of the PMAP% call,
the

process

are

nonexistent,

This use of
least

removed.

it will

file was

file

(refer
After

page
it

the

file

page

if the file

requested

it was also specified

is opened for

the PMAP% call,

in the

OPENF%

call

closed while

Thus,

before

any of

file

its

pages

closed,

are

its

mapped

pages

when

into

must

returns

the

error

any

unmapped

to Section 3.5.6.3).
execution of
the

the PMAP%

control

illegal

instruction

3.5.6.2

Mapping Process Pages To A File - This use of the PMAP%

actually

transfers

trap

data

page

the
in

empty.

Both

the

page

private;

that

is,

no other

address

space.

the

page.

file

The

following

the

call.

user's

specified

instruction

call,

program

the

currently

is written.

is valid only
is

opened.

cannot

process.

the

|f write access

is not granted unless
the

the present contents of

created when

the PMAP% call

read access.

FILES

occurs,

generated.

moving

file.
the

the

The process

process

arguments

and

can

ownership of

The

specified

the

contents

for

the

page

the

page

the

page

call

process

is
into

its

transferred

now

file must

page mapped

process

map

the

have

page

the

file

are

5.3)

the

left

the

right

deleted.
The

three words

AC1:

process
half,

AC2:

AC3:

was

the

file

page

the

requested

the

(refer

number

file

the

follows:

the

right

left

process
half,

and

the

page

half

number

half

access

the PMAP¥ call

access

Section

the

specified

(refer

is
in

to Section

granted only
the

OPENF%

3.5.6.1)

call

it does
when

the

not
file

opened.

count

sequential
byte

JFN

with

This use of
byte

identifier

and

repetition count and

The access
conflict

are

count

the PMAP% call
and

the

byte

1/0 monitor
and

calls,

the

the byte

the TOPS-20 Monitor

does not

size.

Calls

size.

automatically

allow

the

program
(Refer

file

should
to

Reference Manual).

3-30

the

update

the

later

read

update

the

CHFDB% monitor

files
with

file's
call

USING

FILES

3.5.6.3
Unmapping Pages In A Process - As stated previously,
a
file
cannot
be
closed
if any of its pages are mapped in any process.
To
unmap a file's pages from a process,
the
program
must
execute
the

SMAP% call, or the following form of the PMAP% call:
AC1:

-1

AC2:

process

identifier

the process

AC3:

3.5.7

in the

the repeat count for

the process

left half,

and

page

number

the right half.

the number of pages

(refer to Section 3.5.6.1).

Mapping File Sections

remove

from

to a Process

section of memory is a unit of 512 pages of process
address
space.
File
sections
also
contain
512 pages.
The first page of each file
section has a page number that is an integral multiple of
512.
Like
memory pages, sections can be mapped from one process to another, from

a process to itself, or from a file to a process.
the SMAP% call

completely.

Chapter 8 describes

The SMAP% (Section Mapping) monitor call is similar to the PMAP% call.
The SMAP% call maps one or more sections from a file to a process (for

input), or from one process to another
process.
To map
a
process
section to a file, you must use the PMAP% call as described in Chapter

to map

each

page.

Mapping a file section to a process section with SMAP%¥ does not
cause
data
to move
from
the disk to memory.
Instead, SMAP% changes the
contents of the process memory map so that the process section pointer
points
to
a file section.
The monitor transfers data only when your
program references a memory page to which a file page is mapped.

3-31

USING

To map

file

section

FILES

process

section,

SMAP%

requires

arguments:

AC1:

source

identifier:

section

number

sections

are

that

JFN

the

to be mapped,

the

first

the

right

left

half.

the

section

destination
half,

and

several

AC3:

The

flags

Table 3-7:

identifier:
a

process

group of

contiguous

process

section

sections

the

are

is the number of
file section.

flags

that

control

access

left

half,

and,

the

to map

into

the

cannot

less

than

left

half

the

SMAPX Access

process.
1

AC3

the

right

nor

the

process

half,

The

number

than

are described

first

the
of
32

half

the

left

half.

the

sections

number

section

section
number

file

contiguous

right

be mapped,

the

contiguous

right

identifier

number

in
the right half
which SMAP% maps a

and

several

number

sections.

AC2:

half,

|If

three

into

the

sections
to

map

(decimal).

in Table 3-7.

Bits

Bit

Symbol

Meaning

SM3RD

Allow read access.

SM%WR

Allow write access.

SMIEX

Allow execute access.

SMZIND

Map the destination section using an
section pointer.

3-32

indirect

USING

3.6

FILES

CLOSING A FILE

Once data
must

has

performs

the

been

the

transferred

file.

When

to or
file

from a

file,

closed,

the

user's

program

system automatically

following:

Updates

the directory

information

for

file

sequential

bytes

byte

size

Releases

user's
JFN

to which

and

byte

the JFN

the

same

with

request

This

file.

had

are updated when

associated

program can

assignment.

reopen

count

the

file

the

to close

For

the

file

file.

the

example,

been written,
is

However,

file,

the

closed.
the

but

retain

the

plans

wuseful

the

program

later,

but

does

not want

execute

another GTJFN% call.

3.6.1

CLOSF% Monitor Call

The CLOSF%
or

all

(Close File)

files

CLOSF% call
left. half

that

are

Bit

for

closes either

the

process

accepts one word of arguments

and

the

JFN

flag bits are described

Table 3-8:

monitor call
opened

the

file

to be

in ACl1

closed

the specified

executing

the

- flag

the

bits

right

The

the

half.

The

in Table 3-8.

CLOSF% Flag Bits

Symbol

Meaning

CO%NRJ

Do not release the JFN from the file.

CZ%ABT

Abort

any

done.

output

That

is,

perform normal
do

not

buffers).
not

and

file

call.

CS%NUD

been

then

operations
<close

currently

the

file

cleanup operations

output

any

data

being

but

(for

not

example,

remaining

the

|f output to a new disk file that has
closed

aborted,

the

file

closed

deleted.

Do not update the copy of the directory
on
the
disk
(refer
to
the
CHFDB% description in the
TOPS-20 Monitor

Calls

information)
.

3-33

Reference

Manual

for

USING

the contents

process

are

ACl

closed,

continues at

all

files

the CLOSF% call

and

CO%NRJ was not set
the

closed

the

second

and

that

are

opened

for

this

code

the user's

the

file

specified

is released

The execution of the user's program

location after

error

successful,

associated with

the CLOSF% call

The execution of

JFN

in the call.

the execution of

not

-1,

closed.

the execution of

file

FILES

the CLOSF% call,

not successful,

returned

program

the

continues

the

right

file

half

the

is
ACl.

instruction

following the CLOSF% call.
The

following

CLOSIF:

sequence

HRRZ

illustrates

1, INJFN

sobtain

CLOSF%
ERJMP

CLOSOF:

HRRZ

;close
FATAL

;if

1,0UTJFN

3.7

ADDITIONAL

3.7.1

FILE

1/0

The GTSTS%

(Get Status)

call

accepts

right

half

Control

two

files.

JFN

input file

error,

print message

and

stop

print message and

stop

JFN

;if

MONITOR

error,

CALLS

Call

This

the

input

;close output file
FATAL

GTSTS% Monitor

closing

;obtain output

CLOSF%
ERJMP

the

monitor call

one

ACl1.

obtains the status of

argument word
The

left

always returns to the

half

user's

the
AC]

JFN
is

program

the

file

file.
in

the

zero.

the

instruction

following the GTSTS% call.

Upon return,

appropriate bits

reflecting

the

JFN

bits,

status

their

the

meanings,

illegal

specified

are described

unassigned,

bit

are

set

in Table

3-9.

(GS3NAM)

will

3-34

AC2.

Note

These

that

not be set.

the JFN

and

USING

Table 3-9:

FILES

Bits Returned on GTSTS% Call

Bit

Symbol

Meaning

GSYOPN

The file

is open.

set,

file

]

GS%RDF

the

If the
GS%0PN

If this bit
not

file
is
is
set),

not

open.

open
(for
example,
it is open for read

access.

GS%WRF

GS¥XCF

GSZRND

the file

is open,

is open for execute access.

the file

is open,

GSZLNG

can be

File has

GSYEOF

GSZERR

GSENAM

GSBAST
'

for

is,

its

GSZASG

existence

the

file

end

One

the

file

file.

in error

(for example,

read may be erroneous).

specification

this

set

beyond

511.

The file may be

with

open

reset).

pages

number

the bytes

(that

The last read operation
was

access

for

Reserved for Digital.

page

open

File

pointer

access.

non-append

5-6

write

JFN.

the

JFN

This
in

associated

bit will

any way

fields

not

illegal.

the

file

specification associated with
contain a wildcard character.

this

The JFN

assigned

currently

being

JFN

(that is, a process other than the one
executing

the

GTSTS

call

assigning

this JFN)
.
13

GSSHLT

|/0 error

terminating

That

considered

condition

is, the OPENF% call
had bit OF3HER set.

3-35

for

this

JFN.

this

JFN

USING

Table 3-9:

Bit

Bits Returned on GTSTS% Call

Symbol

Reserved for Digital.
GS%FRK

Access to the file
only

(Cont.)

Meaning

14-16
17

FILES

GS%PLN

one

If on,

file line

during

input;

numbers
if

32-35

Reserved for

GS%MOD

An example of

passed

line numbers

Digital.

file

Value

Symbol

Meaning

.GSNRM

Normal

.GSSMB

Small

.GSIMG

Image

.GSDMP

Dump

is shown

input.

The data mode of the
the OPENF% call).

the GTSTS% call

are

2zero,

are stripped before
19-31

restricted

process.

(refer

(sequential)

1/0

buffer mode

(binary)

1/0

in the first program in Section

3.9.

'3.7.2

JFNS% Monitor Call

The JFNS%

(JFN to String)

currently

associated

words

AC1:

arguments

monitor call

with
AC1

the

through

designator

associated

with
is

JFN.

specification

The call

accepts

three

AC3.

destination
specification

returns the file

specified

where

the

JFN

ASCIZ

string.

to string

AC2:

JFN or pointer

AC3:

format to be used when returning
below)

3-36

file
to

specification
written.

This

(see below)
the

specification

(see

USING

FILES

The contents of ACl
Section 3.5.2).

can be any valid destination designator

The contents

can be one of

word

with

right

half.

AC2

either

flag bits or

The bits

that

the ones

returned

from

left half

AC2

the GTJFN% call),
for

appropriate

corresponding
is

the

example,

JFN

string

ACZ

values

Calls

contents

written

bytes,

each

value

values

are:

and

-1,

the

exact
not

1is,

bit

contain

for

null

specified

the

upon

string

AC3

«JSAOF

not

for

the

AC2

half

the

file

fields).

and

the

unspecified

fields

and

alliowed

for

second

format

address

call.

not

(for

|If

in the GTJFN% call),

in which

space

Refer

the

that

the TOPS-20

this

format.

specification

are divided

into

3-bit
The

the

file

specification.

format

for

that

field.

return

The

possible

return

Suppress

AC3 is

zero,

this

field when

returning

the

this

field when

returning

the

specification.
this

value

3-1).
of

the
from

specification.

Always

.JSSSD

contents

the
are

Meaning

system

the

for
The

through

field

the

file

with

program's

format

When

number

left

any

explanation of

.JSNOF

for

the

indicates

the

returned

generation

When

representing

Symbol

execution

for

contain wildcard characters

specification

fields

format

3-3).

the bits

specification

fields.

byte

Value

to Table

the

specify

byte

first

and the JFN in
half
of
AC2

file

the

(refer

GJ¥0OFG was set

Bits

left

returned

file

the destination.

the

-2

are

Reference Manual

the

half

the JFNS¥ call.

The

left

contains

is,

characters

(that

pointer

(that

only with

returned

Monitor
The

returned will

actual

the GTJFN% call

returned

wildcard

the

the string returned will

bit

file

formats.

can be given

nonzero

fields

associated

actual

two
0

(refer

the

file

field

for

this

field

specification

the

standard

(refer

to Table

written

format

dev:<directory>name.typ.gen;T

with

fields

returned

bit

returned

the

same

and

protection

AC2

are

only

on,
the

the
and

standard
account

respectively.
file

system value
fields

The

temporary.

3-37

(see Table

returned

temporary

only

attribute

3-1)
bit

not
9

and

(GT)

USING

Table 3-10 describes

Table

3-10:

the bits

FILES

that can be set

in AC3.

JFNS% Format Options

Bit

Symbol

JSEZNOD

Meaning

node

name

node

name

present.

1-2

JSEDEV

Format for device field.

3-5

JS%DIR

Format for directory field.

6-8

JSENAM

Format for filename field.
A value of
2
(that is, bit 7 set) for this field
is

9-11

JSETYP

illegal.

Format for file type field.
of
2
(that
is, bit 10 set)
field

illegal.

12-14

JSIGEN

Format for generation number

0-14

JSESPC

Output

for

fields

named

all

file

above.

have

the

same bits

the

fields

(JSYPAF)

set

field.

specification

This

field

as would

above.

should
be

set

(See

B35

below.)

15-17

JS%PRO

Format for protection field.

18-20

JSXACT

Format for account field.

JSZTMP

Return temporary file
the

A
value
for this

file

temporary

indication ;T

specification

for

if
a

file.

JS%S1Z

Return size
below)
.

JS%CDR

Return
below)
.

JSZLWR

Return date of last write operation to
file (see below).

3-38

creation

file

pages

(see

date

file

(see

USING

Table 3-10:

JFNS% Format Options

FILES

(Cont.)

Bit

Symbo1

Meaning

JS%LRD

Return date

of
last
(see below).

from file
26

JSEPTR

read

AC2 contains a pointer
containing

the

(refer to the
Reference

field
for

the

to be

TOPS-20

Manual

operation

string
returned

Monitor

Calls

a description of

this use of the JFNS% call).
27

JSZATR

Return file
if

specification

attributes

appropriate.

JSZATI

Return
specification
referenced in ACAL.

JSEOFL

Return the "OFF-LINE" attribute.

30-31

Reserved

JS%PSD

for

attribute

Digital.

Punctuate the
size
and
date
fields
(see
below) in the file specification
returned.

JSETBR

Place a tab before all fields returned
(that
is, fields whose value is given
as 1 in the 3-bit field) in
the
file
specification,

except

for

the

first

field.

JSXTBP

Place a tab before all

returned

value

field)
except

JSXPAF

(that

given as

file

for

the
the

Punctuate

all

returned

from

fields

1is,
or

first

the device

3-bit

field.

(see

file

field

the

specification,

fields
the

that may

fields whose

below)

specification

through

the

field.
If

bits

punctuation
fields.

3-39

through

are

used

set,

between

not

the

USING

FILES

The punctuation used on each field

is shown below.

dev:<directory>name.typ.gen;A
(account) ;P (protection) ; T (temporary)
,Size,creation date,write date,read date

Refer

to Section

3.7.3

1.2.2 for

information on error

GNJFN% Monitor Call

Occasionally a program may be written
a

returns.

group

files

instead of

should not require the user

to perform similar operations on

only on one file.

to give

file

However,

the program

specification

file.

Because the GTJFN% call

a time,

the program needs a method of assigning a JFN

for

each

associates a JFN with only one file at
to all

the files

in
the
group.
By using the GTJFN% call to initially obtain the JFN
and the GNJFN% call to assign the same JFN to each subsequent file
in
the

group,

a program can accept a specification for a group of files
file in the group individually.
After the user gives
file
specification,
the program requires no additional

and process each

the

initial

input.

Before an example showing

description

the

interaction of

GNJFN%

(Get

these

two calls

JFN)

monitor

is given,

call

appropriate.

The GNJFN% monitor call
files

file
in

that

have

assigns a JFN to the next file

been

specified with wildcard

is determined by searching
Section

call

wusing

call

in the

half.

the directory

the current

accepts one argument word

GTJFN%
right

3.3.1.1

in AC1

left half and

|In other words,

the

file as
the

information

the

group

the

The

order

the first

flags

the JFN of

in a

characters.

described
item.

returned
in

This

from

current file

returned

of
next

AC1

the

in the

from

the

GTJFN% call
is
given as an argument to the GNJFN% call.
Therefore,
the program must save this information for use with the GNJFN% call.
If execution of
assigned

various

flags

the

the next
and

the

GNJFN%

call

file

the group.

right

half

successful,

contains

The

left

the JFN.

the
half
The

same
of

AC1

JFN

contains

execution

the program continues at the second

instruction after the GNJFN% call.

Table

can

3-11

successful

describes

the bits

that

GNJFN% call.

3-40

returned

ACl

USING

Table 3-11:

FILES

GNJFN% Return Bits

Bit

Symbol

GN%STR

Meaning

A change in structure occurred between
the previous

GN%DIR

A change

file and

A change

file and

the

because

file.

|If

also be on

system considers

two

files

the

file

type

the

name

and

type.

change

is not successful,

AC1,

Conditions

that

both

error

can

code

cause

error

are:

The

file

and

currently

associated with

the

This means

the program must

not.

that

CLOSF% call (with
CO%NRJ
executing a GNJFN% call.

set

There

this

group.

after all

files

the

are

no more

stepped

through.

files.

(Note:

execution

files

first GNJFN% call

associated with
The

this

same

right

half

the

file and

this bit will

filenames but with

the GNJFN% call

between

file.

different

| f execution of
return

this

with

returned

the

file.'

A change in file type occurred between
GNZNAM is on,

this

in filename occurred

the previous

GNIEXT

file.

in directory occurred between

the previous

GNINAM

this

the

The JFN

JFN

retain

This

released when

error may occur

the JFN

is deleted or

program

continues

3=k

the

closed,
execute

JFN)

before

return occurs

in the group have been

This

the GNJFN% call.

must

there are

if the file currently

renamed.)
next

instruction

after

USING FILES

Consider the following situation. The user wants to write a program
that will accept from his terminal a specification for a group of
files and then perform an operation on each file individually without
Assume the wuser's directory <TRAIN>
input.
requiring additional
contains the following files:
FIRST.MAC.1
FIRST.REL.1

SECOND.REL.1
THIRD.EXE.1

As discussed in Section 3.3.1.1, a group of files can be given to the
by supplying a specification that contains wildcard
GTJFN call
characters in one or more of its fields. Thus, the specification
%
<TRAIN>*

would refer to all four files in the user's directory <TRAIN>,

the

existing

file

in his program, the user includes a GTJFN% call that will
above specification.
The call

GJESHT
OLD+GJ%
I FG+GJEFLG+GJEFNS+
MOVX AC1,GJ%
MOVE AC2,[.PRIIN,,.PRIOU]
GTJFN%
and

indicates

that

The file specification given must refer to an

The file specification given
characters (GJ%IFG)
.

.
(GJ%OLD)

is allowed to

contain

Flags will be returned in AC1 on a successful call

The
flags must be returned because they will
GNJFN% call as arguments.

The contents of AC2 will

The short form of the GTJFN% call

The file specification

input and output JFN

.
(.PRIIN,,.PRIOU)

(GJ%FNS).

interpreted

wildcard

(GJ¥FLG).

be given to the

containing

is being used

(GJYSHT).

is to be read from the user's terminal

When the user types the specification <TRAIN>%.,% as input, the
system
associates
the
JFN with
one file only.
This file is the first one
found when searching the directory in the order specified
in
Section

3.3.1.1.

Thus

the

JFN

returned

FIRST.MAC.1.

3-42

associated

with

the

file

USING

After

the

GTJFN¥

call

flags

appropriate
half.

The

flags

the

successfully

left

that will

FILES

half

and

returned

executed,

the JFN

AC1

assigned

this

contains

the

particular

right

situation

are:

GJINAM

(bit 3)

A wildcard character
field

GJRZEXT

(bit &)

(bit

file

appeared

12)

the

file

the

name

specification given.

A wildcard character
field

GJXGND

the

appeared

specification

Any files marked for

deletion

the

type

given.

will

not

considered.

These

flags

inform

characters.

because

the program of

The

this

wuser's

word will

The

program

Once

its processing

then

used

performs

the

program

its desired

the

ready

the user,

the program executes

obtain

it.

The

argument

returned

from

the GNJFN% call

Thus,

of
the

file.

for

requesting
call

contents

the call

ACI

call.

first

the GNJFN%

GNJFN%

program

from

GTJFN% call.

the

instead

wildcard

contents

operation

specification

the previous

But

the

equivalent

file.

contained

save

specification

that

now

the argument

completed,

the

fields

must

this

the
the
to
ACI

case

to:

MOVE AC1, [GJENAM+GIBEXT+GJ%GND,
, JFN]
GNJFN%
Upon

successful

associated

with

AC1

contains

the

right

indicate

execution

the

file

appropriate

half.

that

this

the

file

flags

the
in

GNJFN¥
the

call,

group

the

left

half

example,

the

flag

returned

type

changed

between

the

(that
and

the

is,
the

JFN

now

FIRST.REL.1).
same

JFN

GNYEXT

(bit

16)

two

files.

After processing the second file, the user's program executes
another
GNJFN¥
call
wusing
the
original
contents
of AC] returned from the
GTJFN% call.
The original contents must be
used
because
this
word
indicates

the

fields

containing wildcard

characters.

the current

contents of AC1 (that is, the flags returned from the GNJFN% call) are
used,
a
subsequent GNJFN% call would fail because there are no flags
set

indicating

fields

containing

wildcard

characters.

This

second

GNJFN%
call associates the JFN with the file SECOND.REL.1.
returned in ACl are GN¥NAM (bit 15) and
GNZEXT
(bit
16)

The flags
indicating

that

two

the

filename

and

file

type

changed

between

the

files.

(Remember that a change in filename implies a change in file type even
if

the

two file

types are

the same.)

3-43

USING

FILES

After processing this third file, the user's program executes
another
GNJFN% call using the original contents of AC1.
Upon execution of the
call, the JFN is
now
associated
with
THIRD.EXE.1,
and
the
flags
returned
are
GN%NAM and GNZEXT, indicating a change in the filename
and file type.

After processing the file THIRD.EXE.1, the user's program
executes
a
final
GNJFN%
call,
Since there are no more files in the group, the
call returns an error code and releases the
JFN.
Execution
of
the

user's program continues at the instruction following the GNJFN% call.

3.8

SUMMARY

To read from or write to a file,

the user's program must:

Obtain a JFN on the file with the GTJFN% monitor call

(refer

to Section 3.3.1).

Open the file with the OPENF% monitor call

(refer to

Section

page

monitor

3.4.1).
3.

Transfer the data with byte,
calls (refer to Section 3.5).

Close the file with the CLOSF% monitor call
3.6.1).

3-bi

string,

1/0

(refer to Section

USING

3.9

FILE

FILES

EXAMPLES

Example

output

file,

- This

Data

copied

the

TOPS-20

program assigns

and

copies

data

JFNs,

from

until

the end of

Monitor

Calls

opens

the

input

Reference

input

file

Manual

file

reached.

for

FROGRAM

’

(USING

TITLE

COPY

QUTFUT

IGNORING

Refer

to
the

HEARCH

MACSYM

FILE.

XkX

NULLS)

sTITLE

MONSYM

ITMPURE

FILE
AND

FILEIQ

+REQUIRE

PRkk

INFUT

BINZ/ROUTZ

FOEARCH

PROGRAM

SYSTEM

JSYS-SYMROL

STORAGE

AND

DEFINITIONS

XXX

INJFN?

RBRLOCK

sHTORAGE

FOR

INFUT

DUTJFN:

RLOCK

FHTORAGE

FOR

QUTFUT

FOLST?:

FIOLEN:=3

PETACK

RLOCK

FOET

PFIDLEN

STHAC .
PRRK

FROGRAM

BTART:

XXXk

yOLOSE

FyLTOWD

INFUT

FILE

FOLENFOLET]

FILESy

SESTARLISH

FRROMPT

INFUT

FILESD

FOR

sON

MOVE

SEE

MACSYM.

ETC.

INFUYT

$§8EARCH

FILE

ERJMFG

[

FUSHJ
SJRET

MOVEM

FyWARN
INF I

T1sINJFN

OUTPUT

FILE

TMSG

FILED

JOB

§1F

ERRORy

$AND

LET

SFRINT

FROMPT

FOUTHUT

FILE

MESSAGEy

FRIINy» JFRIOUT

GTJFNZ

[

FUSHJ
JRET

MOVEM

JFN

FOR

FyWARN

QUTFIL

T1y0QUTJFN

5170

WITH

yOET

JOB

5TF

ERRORy

sAND

LET

FSAVE

NEW
IN

JFN

TRY

SHORT

WARNING
AGAIN

CALL

MODES

CONFIRMATION

NUMRER

GIVE

HIM

3-L5

T2y

CONTROLLING

FILE

THE

SGTUFN

GENERATIONy

REQUIRE

¥OFTLE-NR‘S

ERJMFEG

TERM

C(JFND

AGAIN

THE

T1yGJIZFOUFGILMEGHEGIACFMEGIZFNSHGIZLEBHT

T2y L

*kx

sEDEFAULT

MOVE

WARNING

TRY

SAVE

GTJFN

FILE-NRs

CONTROLLING

NUMRBER

GIVE

HIM

FOR

ONLY»
WITH

FILE

FOUCCESSy

DUTFIL:

MOVX

FILE

OGET

TERMINAL

MODES

sEHORT CALL
T2y LoFRIINy
» FRIOUDT
SGTIFN/G T/0

GTJFNZ

QUTFUT

ACs.

STACK

CONTROLILLING

TLyGJZOLDHEGIZFNSHOGILEHT

SEXTETING

GET

FOR

MOVX

sAkX

STORAGE

STANUARD

JFN

XXX

INFTL

TMEG

LLENGTH

JFN

XXX

RESETX

GET

HAS

ASIDE

SDEFINE

INITILIZATION

MOVE

LIBRARY

SYSIMACREL

DATA

file.

explanation of

ERSTR% monitor call.
PRRK

and

the output

TERMINAL

FILES

USING
FNOWy
i

OFEN THE FILES WE

JUST

GOT

INFUT

MOVE

FRETRIEVE THE INFUT JFN
FMODES FOR OPENF L7-BIT BRYTES
FOFEN THE FILE
$IF ERRORy GIVE MESSAGE ANIY STOF

T1yINJFN

MOVUX T2yFLOC7yOFZRSZ) HOFZRD
OFENF%
ERJMFS
’

FATAL

INFUTI

OUTFUT

MOVE

RYTES + OQUTFUTI

OFENFZ
ERJMFS

GTOF

FATAL

FXkk¥ MAIN LOOF:

COFPY RYTES

FROM

INFUT

BINZ

JUMPE T2y DONE
MOVE T1s0QUTJFN
BOUT

FOUTFUT THE RYTE TO DESTINATION

ERCALS ERROR
JRET L.OOF

$ LOOF»

STOF ONLY

§ (CFOUND

FXx¥

XokxX

QUTFUT

FGET THE INFUT JFN
FTAKE A RYTE FROM THE SOURCE
$IF Oy CHECK FOR END OF FILE
FGET THE QUTFUT JFN

T1sINJFN

MOVE

LOOF?

THE QUTFUT JFN
FMODES FOR OFENF C7-BIT
sOFEN THE FILE
§1F ERRORy GIVE MESSAGE AND

SOET

T1»0UTJFN

+OF ZWR
MOUX T2yFLLUCZyOFARSZ)

FILEy

END OF

FOR

TEST

FINISH

BUCCESS

ON A O

RBYTE

LOOF+2)

Kokk

NONE ¢

GTSTSZ
TXNN T2yG8XZEQF
JRST 1L.OOF

sOET THE STATUS OF INFUT FILE
AT END OF FILE®
iNOy FLUSH NULL ANI' CONTINUE COFY

CLOSIF:

MOVE T1,yINJFN
CLOSFZ%
ERJMFS FATAL

5 CLOSE

CLLOSOF:

MOVE T1iyQUTUJFN
CL.OSFX%
ERJMFS FATAL
TMSG

JRET

ZAF

ERROR

FATAL?

HANDLING

GIVE MESSAGE AND STOF

5TF ERROR>

DONE

*kxX

FyERROR

JRET

ZAF

TMGEG

FFATAL ERRORS FRINT 7 FIRST
FTHEN FRINT ERROR MESSAGE
STOF

FANDL

FWARNINGS

[

SAND FALL

Tiy

MOVETL
MOVE

GETZ

JECL

JFCL

FOFS

HAL.TFZ
JRBT
END

FRIOU

v -1
L FHELFy

ERSTRZ

LAk

SRETRIEVE OUTFUT JFN
SCLOSE QUTRFUT FILE

TMEG

FUSHJ

ERROR:

STOF

$GTOF

WARN

5IF

5 SUCCESSFULLY

D
COONE

XXX

RETRIEVE INFUT JEN
INFUT FILE
ERRORy GTVE MESSAGE AND

PYESy

START
BTART

FRINT

THRU

FIRST

“ERROR‘

BACK

TO CALLER

s NECLARE FRINCIFAL OUTFUT DEVICE
FFOR ERROR MESSAGE
FOURRENT FORKs» LAST ERROR

NG LIMITs» FULL MESSAGE
SPRINT THE MESSAGE

FIGNORE UNDEFINED ERROR NUMEBER
P IGNORE ERROR DURING EXE OF ERSTR
FRETURN

CallER

FSTOF
sWE

OARE

FTELL

RESTORTARLE

LINKING

3-L6

LOADRER START

AINMRESS

USING

Example
then

- This

outputs

program accepts

the data

the

FILES

input

line

from a

user

printer.

Refer

the

terminal

to Section

and

2.9

for

explanation of the RDTTY% call.

——— WAS——

—

——

TITLE
SEARCH

MAGCHYM

JRECQUTRE

FHEARCH

SYSTEM

$TEFINE

STANDARD

TERMINAL

JSYS-SYMEBOL

INFUT

PRINTER

LIBRARY

SYSIMACREL

STHACG .

—
—
——
———
—

sPROGRAM

MONSYM

ACs

PHLENwmfid
COUNT:

RLOCK

LETJFNG

BLOCK

BUFFERS

RILOCK

RUFS1Z

I, ¢

BLOGK

PRLEN

STARTS

REGETX

——- A

—

——

LFTRNT

CENTER

———
——

TEXT

T1yRUFFER
T3

——

FTNFUT

—
r———
D

SCOMPUTE

T1,T2

808

SOONT

THE

FRINTER

T2y LAGCTZ

——
A——

ERJMPS
MOUX

AND

JFNERR

THE

HRROT
MOUN

TEXT

THAT

WAS

T2y RUFFER

HOUTH

TMSG

BATERR

READ

BUFFER

CHARS

READ

BUFFERGIZE

REMAINING

TM2
INFUT

FILE,

FOINTER

PGET

JFN

SHORT
TO

FOR

FRINT

THE

BYTESy

FRINTER

MESSAGE

JFN
WRITE

FOR

ERROR

THE

TERMINAL

FROM

sGET

POINTER

sGET

NUMBER

TO
OF

FILE

FRINTER

ERROR

FRINTER

3 7-BIT

CaAlL

NAME

TEXT
CHARS

sOUTEUT

STRING

FERRORy

FRINT

ERROR

ACCESS

WANTED

OQUTPUT

MESGAGE

(FRINTER
TO

CHARS

JFN

STILL

OQUTFUT
TO

THE

FRINTER

MESSAGE

BEEN

SENT

THE

FRINTER...
SOUTFUT

MOVE

CHARS

TERMINAL

CHARS

SGET

INFUT

FRINTER

PERRORs

T3y COUNT

ERJIMFS

THE

sOFEN

REMAINING

NUMBER

sREMEMBER

OFNERR

FROM

INCLUDE
&

sOUTFUT

T2y FLICZy
QF ARSI FOFZWR

MAX

BUFFER

CHARS

PERRORy

T1sLPTJUFN

ERJMES

HAS

OFEN

ZLPTIZ0

OFENFZ%

OQUTFUT

MINUS

sGAVE

T1yGJREHTIGIAFOU

MOVEM

——

CHARS

SUE

FOR

"Z)
¢

STOF

SOET

T1yCOUNT

AND

TEXYT

v RO

GTJFNZ

S———- —

FLAG

JFN

WITH

RE-TYPE

Ti1yBUFSTZRS

HRROT

QUTFUT

SGET

PNO

MOVET

MOVX

NOW

(END

HRIRZSG

MOVEM

ETC,

STACK

FOUTFUT FROMPFTING TEXT
FGET FOINTER TO BUFFER

EJSHLT

1700

PRINTED

ROTTYZ

FGET

PILENPDL]

T3y TROZBRICHRBUFSTZEE]

BETIM

——

————

TMSEG

MOVE

—— ———

——

P CIOWD

HRROT

—
S —— S———
——
—
——

5 [

MOVE

TLeLFTUFN

sOGET

CONFIRMATION

FRINTER

MESSAGE

JFN

CLOSFZ

ERJMPS DATERR
HALTFZ
JRET START

5 LINEX
TED ERRORs FRINT ERROR MESSAGE
§FINTSHED
$IF CONTINUEDY GO BACK TO START

3-47

T1)

CHAPTER L
USING THE

L.1

SOFTWARE

INTERRUPT SYSTEM

OVERVIEW

Program

execution

instructions
must be

able

monitor,

wusually

occurs

are executed one after
to

receive

other

using

the software

that

will

cause

asynchronous

programs,

interrupt system,
his

program

sequential

another.

But

signals

manner,

sometimes

from

result of

where
program

terminals,

the

its own execution.

the user

can

specify

conditions

to deviate from

its

sequential

method of

execution,
An

interrupt

during
the

occurrence

conditions

that

dynamically

generating

and

special

after

because
the

When an
program

a break

prespecified

can cause an
responding
as

for

they occur,
not

sequence

interrupt.

it was

the

After
system

the

events

can

it does
have

interrupted,

and

control

specifying

error

the

the capability
conditions

and

not

the

have

program's

include

explicitly

execution
special

test

the condition.

system

routine

is caused by

Because the program can respond

transfers

previously-specified

the

flow

interrupt,

the program has

|In addition,

the program does

normal

condition.

services.

them.

interrupt occurs,

the

interrupt,

to external

requests for
test

The break,

possible occurrence of

interrupt,

point

execution.

conditions

repeatedly

faster

the

defined

program's

has

transfer

control

routine

completed

control

back

its
to

from

the

that will

main

process

processing of

the

and execution can continue.

program

See Figure L-1.

USING THE SOFTWARE

INTERRUPT SYSTEM

User

Program
|S
Executing

Interrupt

Condition
Occurs

Execute

Enabled for
Condition on This,
Channel?

Yes

Higher Priority
Being
Processed?

| User's
Interrupt
Routine

Wait Until
Higher Priority

Interrupt
Finishes

Perform System
Default Action
(e.g., stop job,
print message)

User Program
Continues if Job
Has Not Been
Terminated
MR-S-2027-82

Figure L-1:

Basic Operational

Sequence of

System

4-2

the Software

Interrupt

USING THE

L.2

SOFTWARE

INTERRUPT SYSTEM

INTERRUPT CONDITIONS

Conditions
system
1.

that

cause

enabled

Conditions

There

the

program

to be

interrupted when

the

interrupt

are:

generated when

are

particular

interrupt

terminal

specific

possible

character

terminal

codes;

each

initiated.

keys

one

condition

Refer

are
on

which

to Table 4-2

Invalid

instructions

mode)

privileged
Memory

(for

example,

privileged

|/0

monitor

instructions

calls

the

given

issued

by a non

user.

conditions,

Arithmetic
or

the

for

possible codes.

user

typed.

specifies

such

processor

illegal

conditions,

memory

such

references.

arithmetic

overflow

underflow.

Certain

file or

device

conditions,

such

Program-generated

software

interrupts.

Termination of

inferior

process.

System

end

file.

resource unavailability.

Interprocess

communication

interrupts.

b-3

(I1PCF)

and

Enqueue/Dequeue

USING THE

4.3

SOFTWARE

(for

INTERRUPT SYSTEM

INTERRUPT CHANNELS AND PRIORITIES

Each condition
channels.
channels;

SOFTWARE

associated

with

one

software

interrupt

Most
conditions
are
permanently
assigned
to
specific
however, the user's program can
associate
some
conditions

example,

conditions generated by specific terminal keys)

to any

one of the assignablie channels.
(Refer to Table L-1 for
the channel
assignments.) When the condition associated with a channel occurs, and
that channel has been activated, an interrupt is
generated.
Control
can
then
be
transferred
to
the routine responsible for processing
interrupts on

that channel.

The user program assigns each channel to one of three priority levels.
Priority levels allow the occurrence of some conditions to suspend the
processing of other conditions.
The levels are referred to
as
level
1, 2, or 3 with level 1 having the highest priority.
Level O is not a
legal priority level.!

level

interrupt
is

prepared

generated

the

system

to handle

the

in a

process

considers

interrupt.

that

where
the

The process

or terminated according to the setting of bit 17
capability word.

L-4

the

priority

process
then

not

suspended

(SCZFRZ)

its

USING THE

Table L-1:

SOFTWARE

Software

Interrupt Channel

Symbol

Meaning

Channel

0-5

Assignments

Assignable by

user

. ICAQV

Arithmetic overflow

.ICFOV

Arithmetic

program

floating

point

overfiow

Reserved for Digital

. 1CPOV

Pushdown

. |CEOF

End

. | CDAE

Data

error

file

.1CQTA

Disk

quota

exceeded

13-14

list

(PDL)

overflow!

file condition
condition!

Reserved for Digital

.ACILI

I1legal

instruction!

.1CIRD

I11egal

memory read!

.ACIWR

I1legal

memory write'!

Reserved for Digital

JACIFT

Inferior

. |CMSE

System

21
22

. |CNXP

process

resources

Reserved

for

Nonexistent

23-35

INTERRUPT SYSTEM

(called

deactivated.

terminates

process

the

panic

interrupt
if

exhausted!

Digital
page

Assignable by

These channels

termination

channels)

reference

user

program

cannot

generated on one of

the channel

not

completely

these channels

activated.

USING THE

The

software

channels

interrupt

only,

and

independently of

generate an
for

any

system

each

other

for

level

the

system

remembers

equal

higher

priority

level

interrupt.

interrupts

activated,
if

priority

request
can

the user

activated

be activated and deactivated

When

level

request

Thus,

<c¢an

associated priority

higher

interrupt

priority

level

processes

initiated only

same or

the

higher

its

INTERRUPT SYSTEM

channel

channels.

interrupt for

priority

progress

SOFTWARE

the

there are

levels.

and

Iinitiates

interrupts

finish.

suspend

routine

must

concerned with

channel

level.

can

interrupt

interrupts

there are,

the

all

after

This means
processing

that

lower

several

items

when he assigns his priority levels.
He must
consider
1)
when
one
interrupt
request
can
suspend the processing of another and 2) when
the

processing of

completion of

the

second

first.

interrupt

See

cannot

deferred

until

the

Figure L-2,.

Level 1

Channel 4
Interrupt
Routine

Level 2

Channel 6
Interrupt
Routine

—

Waiting

Channel 6 Interrupt
Routine Continues

Level 3

Waiting

Channel 35
Interrupt
Routine

Waiting

User Program
Execution

User Program
Continues

Interrupt on

that Has a

of 1

Channel 6

Priority Level

of 2

Figure L-2:

Channel 4

Interrupt on

Priority Level

Interrupt on

Channel 6

Channel 35

Channel 4

that Has a

Completes

of 3

Interrupt

Channel 35

Priority Level

Channels and Priority Levels

L-6

Interrupt

MF-5-2030-82

USING THE

L.h
To

SOFTWARE
process

special
then
up

the

interrupts,

these

the

The program must

the

these

part of
tables

software
of

then

specify

These

calls

are

SIR%Z

call

can be used

must

used

similar,

same

section

the

interrupt

processes

the

you should use

but

the

wuser

his

program,

using.

He must

system by
must

Finally,

also

setting
include

he must declare

system.

Interrupt Tables
system,
table

their

the

and

user's

the

their

program

priority

addresses with

differences

that

use more

than

level

either

are

one

in non-zero sections only

the code
must

of
be

must
table.

the SIR%

important.

The

in single-section programs, but the XSIR% call

programs

The SIR% call works

the

channel

XSIR% monitor calls.

program.

interrupt

the

part

he will

routines

his

channels

addition,

the Software

contents

includes,

for

table as

Specifying

Before using
set

table.

level

addresses

L.4.1

the user

routines

the addresses

channel

priority

INTERRUPT SYSTEM

INTERRUPT TABLES

service

specify

SOFTWARE

that makes

also

interrupt.

Because

the

call.

that
of

section

The

section,

the

memory.

the tables are
code

must

limitations

in the

that
the
the

causes

code
SIR%

that
call,

the XSIR% call.

The SIR% monitor call accepts two words of arguments:
the
identifier
for
the
program (or process) in ACl, and the table addresses in AC2.
Refer

The

Section

following

MOVEI

5.3

for

example

the description

shows

the

1, .FHSLF

XSIR¥

call

identifier

The

set;

argument

accepts
the

the

;identifier

MOVE 2, [LEVTAB,,CHNTAB]
SIR%
The

use

process
SIR%

;addresses of

the

process

for

AC2,

the

address

block

identifiers.

call.

current

process

the tables

following

arguments:

which

interrupt

the

three-word

the

argument

block

channel

ACI1,

the

tables

are

block.

that

has

the

following

format:

Length of

the argument block,

Address of

including

the channel

b-7

table

this word

USING THE

Control

always

following
table

returns

the

addresses

successful,

Any

made

changes

calls

have

SOFTWARE

the

SIR%

and

XSIR%

are

stored

illegal

been

wuser's

the

program

calls.
the

instruction

contents

executed

INTERRUPT SYSTEM

the

trap

The

Channel

channel

channel;

with

The

table,

one

CHNTAB

tables

after

effect

used

any

the

priority

that

and

indexed
use with

|If

the

channel

table

older

format,

for

single-section

program,

priority

(1,

the

address

channel.

The

user

desires;

can

call

the

not

SIR%

the

XSIRY

time of

2,
the

for

call

his

in
to

that

number

half

time

given

Table

L-1

for

the

through

each

35).

calls,

entry

can

The
be

contains

bits

0-5

(SI%LEV)

to which

the

each

entry

contain

the

process
is

not

SIR%

interrupts
used,

and

the

that

The
will

channel

practice

RIR%

each

channel.

priority

L-8

any

XRIR% monitor

half

routine

good

each

generated

corresponding

zero.

the

left

interrupt

however,

for

corresponds

channel.)

and

left

channel

use with

(Refer

each

entry

associated

(SI%¥ADR)

should

the

one-word
Each

channel

routine

particular

the

that

XSIR%

The

6-35

level

the

(1,

entry

the

Bits

of
a

channel

memory.

1level

entries.

condition.

address

associated with

assigned.

channel.

each

for

section

contains

has

interrupt

table

format,

starting

table

conditions

general

channel

CHNTAB, 2

the

channel,

only

interrupt

the

instruction

successful,

Table

thus,

particular

the

generated.

interrupt.

L.,4L.2

call

monitor.

will

|If

calls

word

right

contains

half

any

the

contains

handle

interrupts

table

any

call

CHNTAB.

name

USING THE

The

following example

CHNTAB:

SOFTWARE

for

INTERRUPT SYSTEM

use with

the XSIR% monitor

FLD(2,SI%LEV)+FLD (CHNOSV,SI%ADR)
FLD(2,S1%LEV)+FLD (CHN1SV,S|%ADR)
FLD (2,S1%LEV)+FLD (CHN2SV, S1%ADR)

;channel
;channel
schannel

FLD (2,SI%LEV)+FLD (CHN3SV,SI1%ADR)

;channel

s;channel

schannel

FLD(1,SIBLEV)+FLD (STKSRV, SI%ADR)

this
with

9
10

schannel

example,
the

channels

and

the

channel

remaining

Priority Level

priority
one-word

general
of

the

address when

The

for

each

word

with

routine at

interrupt

flags

are

stored

the

the XSIR%¥ and XRIR%¥

the

LEVTAB

user

however,

the

Channels

routine

three-word

three

n+l

can

call

APRSRV

This

monitor

calls,

priority

the

form of

level

to call

4-9

the

containing

levels.

the

word

The

block

space.

global

first

flags

and

occurs.

first word

practice

address

store

second.

his

good

table,

priority

address

process

section.

The

CHN2SV servicing

channel

the

level

channel

STKSRV servicing channel

30-bit

used

level

the

is
the

contains

block

n of

routine at

servicing
1,

priority

assigned.

LEVTAB,
3
each

address

with

table,

by word

the

servicing

Table

level

two-word

not

assigned

CHNOSV

level

the

are

entry

form,

addressed

and

are

CHN3S5V

priority

channels

3
at

channel

routine at

servicing

through

routine

CHNISV servicing
to

The

interrupt

assigned

L,4L.,3

schannel

are

All

;channel

schannel

channel
9

schannel

routine at
and

FLD(1,SI%LEV)+FLD (APRSRV, SI%ADR)

0
1

;channel 3

call.

and

block,

and

table must

can

table

PC
the

any

LEVTAB.

name

used

the

used

any

desires;

USING THE

The older

form of

the

interrupt

single-section program,
This

table

minus

address

right

the

also

SOFTWARE

INTERRUPT SYSTEM

level

contains

three words,

word

contains zero

Each

the word

in which

half.

table

and must be used with

This

store

address

can

indexed

the

left

half,

the

one-word

assumed

used

any

the SIR% and RIR% calls.
priority

and

level

the

18-bit

section-relative

to be

the

same program

section

that contained the SIR%¥ monitor call.
(For
more
information
Chapter 8.) The system must save the value of the program counter

see
so

that

once

the

can

return

interrupt

particular

control

routine

priority

the

level

The

following

table

LEVTAB:

level!

should

has

the

appropriate

completed

not

used,

point

processing

its

the

program

interrupt.

corresponding

entry

|If

zero.

sample of

level

table.

0,,PCLEV]

;Addresses

save

0,,PCLEV2

sjoccurring

priority

0,,0

tNo

priority

level

for

interrupts

levels

and

interrupts

are

addresses

defined

splanned

L.5

ENABLING THE

Once

the

SOFTWARE

interrupt

tables

the

XSIR%Z

monitor

interrupt

system.

When

with
that

occur

When

processes

interrupts

the

have been

call,

the

activated

routines.

INTERRUPT SYSTEM

interrupt

channels

are

interrupt
as

set

the

up and

their

user's

program must enable

system

enabled,

the

processed

system

channels

for

user's

disabled,
these

the

interrupts
interrupt

the

moni tor

interrupts were

not

activated.

The EIR%Z

monitor

argument:

the

MOVE!

call,

used

identifier

for

1, .FHSLF

to
the

enable

always

L.6

ACTIVATING

Once

the

ACI.

sidentifier

current

entry

can

the

interrupt
occur

assignments).
the

instruction

following

accepts

process

the

EIR

system

must

The channels

appropriate word

enabled,

activated

to be

the

(refer

the

process

call.

channels
to Table

activated

channel

have

ACl,

and

the

channels

L-10

on
L-1

which
for

the

nonzero

table.

The AIC% monitor call activates
one
or
more
of
the
36
channels.
This
call accepts two words of arguments - the
for

one

INTERRUPT CHANNELS

software

interrupts

channel

returns

system,

EIR%
Control

the

process

to be

activated

interrupt
identifier
AC2.

USING THE

The

channels

are

SOFTWARE

indicated

indicates

that channel

only

those

channels

which

MOVE!

1, .FHSLF

for

INTERRUPT SYSTEM

setting bits
bits

are

Some

;identifier

always returns to the

channels,

called

disabling the channel
L-1

for

these

conditions

one

the

these

channel

conditions

activated

process

terminated,

returns

the monitor.

the user's

L.7
A

process

the
the

current

process

cannot

deactivated

channels

not.

|[f

usually
the

routine

because

the

cannot

interrupt

the

completely

ignored

generated

whether

not

output

channel

for

channel.

that

occurrence
be

channel

a message

(Refer to Table

activated,

activated,
before

control

the

control
is

given

interrupt

enabled,

such

producing

condition

for

overflow,

arithmetic

which

using

|1C% monitor call.
This call can generate an interrupt on any
of
36
interrupt
channels
of
the
process
the
calling
process

specifies.

See Section 5.10 for

L.8

PROCESSING AN

When

software

monitor

indicated
with

the

routine
Since
occur,

the

user's

program

contents

interrupt.

can be

any

After
the

the

user

cannot

given

(refer
the

the

II1C% call.

(refer

determine
preserve

word

First,

accumulators

for

state

the
wuse

saved,

L.4.3).

routine

The

the

the address

The

associated

address

this

to Section L.L4.2).

when
the

level,

to Section

occurred.

table

are

priority

(PC)

interrupt

properly.

accumulators

interrupt.

interrupt

routine must

resumed

the

table

the channel

program

interrupt

control

on which

specified

the

level

transfers

channel

processes

occurs

current program counter

in the priority
then

a description of

INTERRUPT

interrupt

stores

monitor

the

[NTERRUPT

generates

interrupt channel

these

|If

interrupt

GENERATING

channels,

occurs,

and

sactivate channels 6 and 9

This

bit

activates

instruction following the AIC¥ call.

panic

channels.)

the monitor.

Setting

or the entire interrupt system.

associated with

AC2.

The AIC% call

set.

MOVE 2, [1B<.ICAOV>+1B<.|CPOV>]
AIC%
Control

is to be activated.

interrupt
of

the

routine
while

the

will

program

stores

processing

interrupt

the
the

routine

Occasionally,
main

section

stored

the

alter

returned

stored

important

that

care be used

because

any

changes

main

the

alter

the main

different

a value

when

will

example,

locations

routine may

location

may

For

return

to use

interrupt

during

that

1is

the

where

the

routines
control

inadvertently

the

the word

the

caused

writing

data

section

system attempted

from

remain when

change

program would

the value of

counter.

higher-priority
routine,

suspended.

indicated

program.

PC word,

program

routine

to alter

occurred.

the

need

example,

incorrect when

interrupt

For

execution

the

INTERRUPT SYSTEM

resume

routine may

the program.

data

interrupt

that

SOFTWARE

PC word

interrupt.

USING THE

The

for

the

value

the
this

its

counter

priority
new

occurs

execution
program

level

interrupt

table
is

the

for

the

execution

lower-priority
is

the

stored

new

completed,

the

an
is

location

interrupt.

the

routine
When

suspended

the

routine

resumes.

interrupt of

execution

higher
The
on

equal

the

level

system considers
an

activated

same

routine,

the user's

The

priority

The

program

monitor

interrupts

channel

Jlower

the

any

level
has

process

EIR% monitor call,

any of

these

panic

cases,

user's

program.

4L.8.1

Dismissing An

Once

the processing of

All

the

should

return

control

monitor

call.

The call

has

until

the
all

processed.
to

following

process

the

interrupt

true:

channel

its

interrupt

tables

executing

the

interrupt

system by

executing

on which the

interrupt

and the channel

channel.
interrupt

user

interrupts

call

interrupt

panic

are

accumulators
the

channel

terminates

the

ignored.

complete,

interrupted

restores

no arguments,

routine.

enabled

during

Interrupt

restore

interrupt

other

should

This

not

the

program unable
of

defined

The

occurs

interrupt

associated with

not

has

occurs.

holds

have been

an XSIR%¥ or SIR% monitor call.
3.

priority

the

and must

their
code

PC word

the

initial
by
and

1last

interrupt

routine

values.

Then

using
resumes

the
the

statement

DEBRK%
program.

the

USING THE

the

user's
the

was

interrupt-processing

program,

in just

interrupted

execution
|f

the

location.

the

PC word was
The

TERMINAL

The user's
through

not

the

interrupt

for

occurrence

1/0

interrupts;

the

occurred.

to complete,

for

complete

when

changed,
state of

the
the

program
program

occurrences

particular

an
refer

|[IPCF
to

resumes
is

associated

the

program

example,
it

the

resumes

execution

the

new

unchanged.

various

character

message.

Chapters

and

There are 36 codes used to specify
which

DEBRK% call.

typed

through 5 and
conditions,
at

the

This

section

other

for

interrupts

conditions,

can

are

terminal

initiated.

terminal

discusses
types

shown

characters

These

in Table L-2.

4-13

channels
such

codes,

as
or

2k
the
the

terminal

assignable

conditions

interrupts.

the same state

INTERRUPTS

with

changed

the program

program can associate channels O

receipt

has

restores

waiting

again be waiting

after

before

while

INTERRUPT SYSTEM

routine

the DEBRK% call

program was

program will

L.9

SOFTWARE

along with

their

USING THE SOFTWARE

Table L-2:

Terminal

INTERRUPT SYSTEM

Codes and Conditions

Code

Symbol

Character or Condition

.TICBK

CTRL/@

]

.TICCA

CTRL/A

.TICCB

CTRL/B

.TICCC

CTRL/C

.TICCD

CTRL/D

.TICCE

CTRL/E

.TICCF

CTRL/F

.TICCG

CTRL/G

.TICCH

CTRL/H

.TICCI

CTRL/

.TICCJ

CTRL/J

.TICCK

CTRL/K

.TICCL

CTRL/L

.TICCM

CTRL/M

.TICCN

CTRL/N

.TICCO

CTRL/0O

.TICCP

CTRL/P

.TICCQ

.TICCR

CTRL/R

.TICCS

CTRL/S

CTRL/Q

or break

USING THE

Table L-2:

Terminal

Codes

SOFTWARE

INTERRUPT

and Conditions

SYSTEM

(Cont.)

Code

Symbol

Character

.TICCT

CTRL/T

.TICCU

CTRL/U

.TICCV

CTRL/V

.TICCW

CTRL/W

.TICCX

CTRL/X

.TICCY

CTRL/Y

.TICCZ

CTRL/Z

.TICES

ESC

.TICRB

Delete

.TICSP

Space

. TICRF

Dataset

LTICTI

Typein

.TICTO

Typeout

.TITCE

Two-character

3L4-35

Condition

key

(or

Reserved

rubout)

carrier

key

off

escape

sequence

USING THE

cause

assign

terminal

the

interrupts

desired

word

the channel

the

always

current

the

controlling
they will

the

code

receipt

mode

terminal

character

causes

wuser

types

it).

In deferred mode,

receives
either

immediate

mode

terminal

character

causes

wuser

the

types

deferred mode,

the

sequence with

other

character
at

the

time

deferred

the

are

program

the

input

that

the

initiate

(that

system

the
In

typed.

system

read

the

example,

when characters are

not

the

are

STIWY

actually
passed

requests
to

the

handled

(Set Terminal
Calls

immediately

interrupt
in

soon

receives

the

input

two of

it).

stream

the

interrupt

same

occurs

character

enabled

interrupt

only

Deferred mode

actions

In
data.

either
The

unless

allows

time

mode,

the

assumes

program

call.

description

the

system

monitor

when

specified

typed ahead of

Interrupt Word)
Reference Manual for a

soon
system

the

other

them).

program

the

placed

unless

character.

(for

system

one

immediate mode,
an

to occur

program

interrupt

case,

only

sequence with

the

soon

placed

initiates

character

the

input,

this
|If

remembered;

initiate

soon

character

terminal

immediate mode,

character

mode.

(as

succession.
one

the terminal

characters

typed,

to TOPS-20 Monitor

call.)

are

interrupt

mode.

deferred

character

attempts

interrupts

issued

system

attached.

terminal

character

terminal

second

the

(there

assignments

actions

character

that

the

mode

interrupt

typed

following

terminal

deferred

the

terminal

immediate

the

accepts

|If

either
the

half

ATI% call.

terminal

This call
left

instruction

the

INTCH]

the job),

handles

;assign CTRL/E to channel

must

and

attached

effect when

program

half.

not

user's

the assignable channels.
AC1

right

code

The monitor

returns
job

the

to one of

terminal

MOVE 1, [.TICCE,,INTCH1]
ATI%
Control

code

is used to assign this code.

arguments:

number

INTERRUPT SYSTEM

to be generated,

terminal

The ATI% monitor call
one

SOFTWARE

has

(Refer
of

this

USING THE

L.10

ADDITIONAL SOFTWARE

Additional
to

check

Also,

the

monitor
and

there

clear

call

11C% call

L.10.1

calls

Testing for

After

are

available

various

useful

parts

for

call

tests

The

execution

the

call,

off,

and

system

that

allow

the

software

interprocess

user's

program

interrupt

system.

communication

(refer

to see

Enablement

enabled.

the

INTERRUPT SYSTEM

INTERRUPT MONITOR CALLS

in Section 5.10).

The SKPIR% monitor
it

SOFTWARE

call

the software

accepts

AC1

control

the

interrupt

the

returns

second

system

identifier
to

the

instruction

process.

instruction

the

system

on.

MOVE!l

1, .FHSLF

;identifier

SKPIR%

;jtest

return
return

4L.10.2

Obtaining

current

;system

off

;jsystem

Interrupt Table Addresses

addresses

for

process.

routines

L.10.2.1

The RIR% Monitor

any

section

addresses
code

call

table

process

that

addresses
The

one

those

half
the

accepts

contains

call,

AC2

Control
The

has

following

MOVE!I

RIR%

These

set

useful

same

the
of

SIR
the

The

the

process
half

priority

level

section-relative

not

set

table

level

several

call
of

can

can be used
obtaining

memory
only

obtain

the
table

address

addresses

ACl.

table,

the

with

AC2

returns

contains

and

channel
the

the

right

table.

SIR%

example

the

shows

instruction

the

use

the

sidentifier

following
RIR%

the

RIR%

call.

current

process

sreturn the table addresses

L-17

the
the

monitor

zero.

returns

table

call.

left

the

when

tables.

for

section

Furthermore,

identifier

address

only

the

and priority
useful

interrupt

- The RIR% monitor

AC2.

1, .FHSLF

the

are

Call
are

the

calls

but

contains

always

«call.

been

the

addresses

process

tables
the

have

section-relative

want

memory,

makes
that

process

interrupt system

The RIR% and XRIR% monitor calls obtain the channel
table

call.

INTERRUPT SYSTEM

USING THE SOFTWARE

L.,10.2.2 The XRIR% Monitor Call - This call obtains the addresses
of
the
interrupt tables defined for a process.
The tables can be in any
section of memory.
The code that makes the call can also be
in
any
section.
This
call
can only obtain addresses that have been set by
the XSIR% call.
The call accepts the identifier of the process in ACl, and the address
of the argument block in AC2.
The argument block is three words long,
word zero must contain the number 3.
The call returns
the
addresses
into words one and two.
The block has the following format:
| ======

Length of

the argument block,

Address of

===

the

Address of

——
.

including this word

interrupt

level

the channel

table

Control always returns to the instruction following
the
XRIR% call.
If
the process has not set the table addresses with the XSIR% monitor
call,

words one and

L.,10.3

two of

Disabling the

The DIR% monitor call
process.

MOVEI

accepts

the argument block contain zero.

Interrupt System

disables the software
the

identifier

1, .FHSLF

the

sidentifier

DIR%
Control

interrupt system
process

current

for

process

;disable system

always returns to the

interrupts

remembered

occur

while

until

the

instruction following the DIR% call.
interrupt

system

reenabled.

disabled,
At

that

they

are

time,

the

interrupts take effect unless an intervening CI1$% monitor call
to Section 4.10.6) has been issued.
Software

interrupts

disabled

and

the

call.

the

superior

In addition,
channel,

the

AC1.

assigned

process

the channel

the terminal

it causes an
However,

DIR% call.

the

assigned

notified

the

channels

are

not

has

CTRL/C

enabled

(.TICCC)

channel

.ICIFT.

is assigned to a

that cannot be disabled

interrupt
CTRL/C

completely

interrupts terminate the process,

code for

interrupt
CTRL/C

panic

These

(refer

the

DIR%

can be disabled by deactivating

terminal

code.

USING THE

L.10.4

and

INTERRUPT

accepts
the

is used to deactivate

two words

channels

indicates

arguments:

deactivated

that channel

MOVE!

Control

channel

ignored

returns
is

except

the

AC2.

interrupt

interrupts

Deassigning Terminal

The DTI% monitor
one

argument

MOVE!

call

word:

Control

terminal

1, .TICCE

been

always

monitor

requests

generated

defined

4L.10.6

returns

the

Clearing

This

interrupts.
returns

call
its

(refer

the

AC2

current

process

the

for

panic

DIC%

that

call.

channel

channels

(refer

are

the

code.

This

call

accepts

ACI.

CTRL/E

following

specified

the

terminal

DTI%
code

call.
has

not

job.

Interrupt System

call

clears
<clears

the

interrupt

interrupts

requires

instruction

following

to Section 2.6.1)

initializing

instruction

ignored

current

<call

This
the

The CIS% monitor call
process.

code

;deassign

call

ACI,

Codes

DTI%

This

following

deassigns a terminal

the

bit

The

;jdeactivate channels 6 and 9

Section 4.6).

L.10.5

channels.

identifier

Setting

sidentifier

instruction

deactivated,

for

process

to be deactivated.

1, .FHSLF

always

interrupt

the

MOVE 2, [1B<.|CAOV>+1B<.|CPOV>]
DIC%

When

SYSTEM

Deactivating a Channel

The DIC% monitor call
call

SOFTWARE

procedures.

system
in

arguments,
the

performs

CIS

for

progress
call.

and
The

and

the

current

all

waiting

control

always

RESET%

monitor

these same actions as

part

USING THE

L.11

SOFTWARE

INTERRUPT SYSTEM

SUMMARY

To use

the software

Supply

Set

interrupt

routines

up a

system,

that will

channel

table

the user's

process

the

containing

program must:

interrupts.
the

addresses

routines
(refer to Section L4.L4.2) and a priority level table
containing the addresses for storing the program counter (PC)
values (refer to Section L4.L.3).
3.

Specify the addresses of the tables with
call (refer to Section 4.4.3).

Enable the software interrupt system with
call (refer to Section L.5).

Activate the desired channels
(refer to Section 4.6).

L-20

with

the

AIC%¥

XSIR%

monitor

EIR%¥

monitor

USING THE

L.12
This

SOFTWARE
program

sof tware

copies

one

file

from

the

user.

The end of

and

CTRL/E

interrupt,

TITLE

SOFTWARE

MONGYM

MACSYM

+REQUIRE

INTERRUPT SYSTEM

INTERRUPT EXAMPLE

filenames

output

SOFTWARE

to another.

INTERRUFT

enabled

RESET

STANDARD

ACs

FRELEASE

FILESy

ETC.

Ti1sEOFINT

YGET

HLLZS

STSOLATE

CURRENT

FROCESS

SECTION

TORM

T1sCHNTAREFINTCHI

§OAND

TL1yCHNTARY
. ICEQF
T1y L EVTARYL

i
3

OUR

ROUTINES

FOR

MOVET

T1s

MOVET

T23

FNUMBER

MOVEM

T2y ARGRILK

SFUT

FHSLF

XMOVET

T25LEVTAR

MOVEM

T2sARGRLK+,

FCURRENT

$GLOBAL

T2yCHNTAR

FMOVE

T2y ARGRLK

WORDG
IN

TO
TO

ARGRLK

ADDRESS

WORD

ADDRESS

FGLOBAL

ARGBLKA42

SERVICE

ARGRLK

$GLORAL

ADNRESS

EITRZ

FENARLE

SYSTEM

MOVE

T2y DIBCINTCHLIE
TCEOF
HAIR
=1

XSIRZ

T1yL.TICCEs
y INTCHLT

$ASSIGN

FILES

ARG
LEVEL
WORI

CHANNEL
WORD

IINFUT

MOVE

T2y LFPRITNy
» « FRIOU

ARGUMENT

MOVEM
GETOF3

Ti1y INJFN

THSG

<OUTFUT

MOVX

TLyGJZFOUAGIZMSGHOJLCFMAGIAFNSHGILGHT

MOVE

T2y FRITNy
v «FRIQU

ERJMF

MOVEM

FILES

FOET

T1» INJFN

MOUX

T2y FLDCZ s OFZRSZ)Y
+OF ZR]
FOFEN

T1+0UTJFN

MOVX

T2»FLIC
v QFZREZ) +OF 7
LWR

OFENF X%
ERJMF

FILE

OQUTFUT

sREAD

INFUT

FILE

T1>INJFN
TLsOUTJFN

BROUTZ
LONE

INFUT

FOFEN
ERROR3

BRINZ
MOVE

SWRITE

JRET

CRYRYT

MOVE

T1yINJFN

CLOSFX

sLOOF

RBYTE

OQUTRUT
UNTIL

RYTE

EOF

FCLOSE

INFUT

sCLOSE

QUTPUT

JFCL

MOVE

FROM

ERRORE

MOVE

FILENAME

T120UTJFN

MOVE

ERJIMF

CRYRYT?

ERROR2

OFENF X

OFNOF¢

USER

ERRORL

GTUFNZL

OFNIF:

FILENAME FROM

FILE

T1,0UTJFN

CLOSFZ
JFCL
HALTF
X%

h-21

FILE

TARLE

TWO

CHANNEL

T1yGJZOLDHGIAMEGHGILCFMHGIAFNSHGIZASHT

SOET

TARLE
ONE

CTRLZE

TMEG

ERJMF

BLOCK

CHANNELS

MOVUX

GTJUFNX

ADDRESSES

ZERCD

ATTA

GETIF?

NUMBER

ROUTINE

SACTIVATE

ATCH

MOVE

and

by a

ONLY

FROCESS

NUMRER

SMOVE

SECTION

NUMBER

TORM
TORM

XMOVETL

input

detected

an escape character.

YREFINE

XHLLIT

T2y

EXAMPLE

INTCHL
=21

MOVEM

the

file

SYSIMACREL

STHAC.

XMOVET

accepts

USER

BLOCK

USING THE SOFTWARE
TO HANDLE

# ROUT ENE

MOVET

CTRLE?

CFORFZ

Ti»

- ARORTS (FERATION

FRIOU

TMSGE <ARORTEX
CIs%
JRET

JLEVEL

FCLEAR OUTFUT BUFFER

§INFORM USER
FCLEAR SYSTEM

8TART

TO HANDLE EQOF - COMPLETES OFERATION NORMALLY

$ROUTINE

MOVEM T1»INTACL
XMOVET T1yDONE
MOVEM 710241
MOVE T1yINTACL
NERRKZ

EOFINT?

INTERRUPT SYSTEM

FHAVE My
§ CHANGE FC
FTO NONE
FRESTORE ACs
FUIHMISS INTERRUFT

T ARLE

LEVTARS

O
FC2
0

RL.OCK 2
5 CHANNEL TARLE
CHNTARS 0

FO2
3

FLOCR2eSTALEWVY TFLOCCTRLE » STZADR)
REFEAT

I8y Ok

FLOC2 STALEWV IFLDCEQF INT» 8EZADR)D
REFEAT

DUTJFN?

RLOCK
ELOCK
RLOCK

INTACTS

RLOCK

ERRORL
¢

TMSG

ARGELK?
INJFN?

PINVALID

“N2% <0k

3
1
1
1
=

FILE

SPECIFICATION:

HALTFZ

ERROR2? TMSG
TINVALID FILE

SFECIFICATION

HALTF%

ERRORZS

THMEG

<«

FTCANNCT

OFEN

FLLE:

HALTE

LET

END

START

L-22

CHAPTER 5
PROCESS

stated

Chapter

have multiple

has

its

own

well-defined

the

term fork

processes

because

time

which

killed.

called

relationship

jobs.

that

program

The TOPS-20 operating
entire

the TOPS-20 operating

processes

environment

environment. is

TOPS-20,

any

has

space.

(PC)

other

the

definite

existence:

its

existence,

represented by

end
a

Job

process

the

and

job.

the
a
In

term process.

running

scheduled

each

Each

Associated with
the

processes

and

system allows

simultaneously.

address

schedules
can

created,
in

its

run

synonymous with

system

point

its
state, which
to Section 5.9).

can

counter

with

process

STRUCTURE

processes,

independent
its

the

process

status word

beginning

time

nhot
other

at which

the

can be described

and

PC word

is
by

(refer

PROCESS

The

STRUCTURE

relationships among processes

in a job are

shown

the

below.
Each
process
has one immediate superior process
the top-level process) and can have one or
more
inferior
Two
A

processes

process

superior

are parallel

can create

they

inferior

have the
process

same
but

diagram

(except for
processes.

immediate superior.
not

parallel

process,

Top—Level
Process

Process
1

Process
2

Process
3

Process

MR-8-2036-82

Process

superior

processes

Processes

process
same

the

superior

process
and

and

depth

the

respectively.

5.1

USES

any

time.

These

that

have more

One

process

and

parallel

because

created

process

the

inferior

structure

they

the

superior

the

not

have

could

not

the

same

but

process.

the same

above.

allows:

can

program

runnable

independent

loaded

separately.

separate

other,

them.

but

This

to wait

continues

its

processes

inferiors

although

not

they

the

process.
are

use

allows

Each

These

inferior

programs,

parallel

each

program

processes
the main

can

one
can
be

process

execution

the

programs.

completion

that

to each

created

has

process

are
have

than one

programs

debugged,

individual

because

shown

structure

placed

parallel

and
5

PROCESSES

job

One job

and

Processes 4 and 5,

Process

process

FOR MULTIPLE

then be

parallel
are

Process

process).

process.

compiled,

are

other

multiple-process

process 4,

Processes

structure,

same superior
created

process of

(the top-level

have

the

for

an event

1/0

computations.
such

computing

system.

This

overlap

|/0 with

that

can be

use

to occur

operation)

Communication
when

the event

notified via

allows

two

computations.

5-2

(for

while

the

example,

another
between

occurs,

the

software

processes

within

the

process
two

process

interrupt
a

job

PROCESS

One application of
situation:
various

a multiple-process Job

superior

terminals.

various

process

After

inferior

then

initiate other

data

that

was

STRUCTURE

receiving

processes

processes,

structure

responsible

as
for

for

the

this

input,

the

data.

These

inferior

example,

following

accepting

input

process

to write

from

sends

processes

can

reports

the

interface

the

process

the job

received.

Process that

TTY

Accepts Input

TTY

from Terminals

Processes that
Receive the
input as Data

Processes that
Write Reports
on the Data
MR-S-2035-82

Another

application

DECSYSTEM-20.
structure

the

On
the

terminal

MACRO,

inferior

process,

the

Command

terminal

5.2
A

and

key

PROCESS

process

system

can

FORTRAN),

places

Command

from

for

for
An

the

user

top-level
process

When

requested

user.

the

This

then wait

the

event

(CTRL/C,

for

input.

the

can

from

used

Language.

accepting

Language

program

completion,

that

DECSYSTEM-20,

Command

example,

The

the

Language

program
an

event
from

can

runs

the

it,

and

to occur,
the

the

example).

(for

creates

executes

it.

either

program

typing

user

program

process

event

user

services

user

can

from
be

its

certain

COMMUNICATION
communicate with

several

direct

software

interrupts

|PCF

ENQ/DEQ

memory

process

and

ways:

control

facilities

sharing

5-3

control

other

processes

the

PROCESS STRUCTURE

Direct Process Control

5.2.1

A process can create and control other processes inferior to it within
The superior process can cause the inferior
the job structure.

later resume
process to begin execution and then to suspend and
tasks, the
its
completed
has
process
inferior
After the
execution.
structure.
job
the
from
inferior
the
superior process can delete

Some of the

CFORK%,

monitor

create

for

used

calls

process

direct

control

are:

a process; SFORK%, to start a process; WFORKX, to

wait for a process to terminate; RFSTS%, to obtain the status of a
Refer to the TOPS-20
to delete a process.
and KFORK%,
process;
additional monitor
of
descriptions
for
Manual
Reference
Calls
Monitor
calls dealing with process control.

5.2.2

Software

Interrupts

receive
to
interrupt facility enables a process
The software
asynchronous signals from other processes, the system, or the terminal

user or to receive signals as a result
of
its
own
execution.
For
example, a superior process can enable the interrupt system so that it
receives an interrupt when
one of
its
inferiors
terminates.
In
addition,
processes
within
a job structure can explicitly generate
interrupts to each other for communication purposes.
Some of the monitor calls

used

when

communication

occurs

via

the

software interrupt system are:
SIR%, to specify the interrupt tables;
EIR%, to enable the interrupt system; AIC%, to activate the
interrupt

channels;

and

|I1C%,

initiate an

Chapter

L4 and Section 5.10 for more

5.2.3

IPCF

interrupt on a channel.

and ENQ/DEQ Facilities

The Inter-Process Communication Facility
jobs

Refer to

information.

(IPCF)

communicate by sending and receiving

enables processes
informational

and

messages.

The MSEND% call is used to send a message, the MRECV% call is used to
receive a message,
and
the MUTIL% call is used to perform utility
functions.

Refer

to Chapter

7 for descriptions of

The ENQ/DEQ facility allows cooperating processes

and facilitates dynamic resource allocation.

these calls.
to

The ENQ% call

resources

is used to

obtain a resource, the DEQ% call is used to release a
resource,
and
the
ENQC%
<call
is used to obtain status about a resource.
Refer to
Chapter 6 for descriptions of these calls.

5.2.4

page or

the

process

section
or

processes when
address

space.

use

same

the

that

page,

page

access

type

processes

read

system

the

makes

writing.
page.

Other
This

possible

the

order
an

for

processes

storage.

Even

when

can

remains

shared

soon

copy

as
of

continue

provides

allows

the

other

the

page

read

the

and

the

processes.

copy-on-write
as

all

the

page,

the

process

doing

the

long

the

sharing

<c¢hange

and

processes

page.

execute

capability

process

Refer

for

process'

have a different
that

process writes

the

can

write

among

identify

several

sharing

access

process

private
shared

than one

facilitates

its

original
as

much

data

monitor

call

to Section 5.6.2 for more

without
used when

information.

IDENTIFIERS
processes

communicate with

creates

inferior

inferior.

in more

two

read or

identifier,

process

represented

are

page.

is PMAP%.

either

each

this

processes

Pages

access

with

data

sharing memory

PROCESS

that

space

processes.

page,

private

still

that

same
such

access

but

changing

the

page

other

physical

identified

address

means

have

process'

same page

This

page

access.

shared with

access

have

STRUCTURE

Memory Sharing

Each

5.3

PROCESS

This

handle,

refer

process

any

then

other

inferior

sometimes

called

process

There

the

are

processes

this

other,

another

given

process

must

process.

When

handle

These

process
at

once.

the range 400001

handle when

structure,

the

to process

process

that

fork

For

uses

not

known

including

but

this

handles'

process

handles

that

specific meaning when

handles

other
These

monitor
by

calls

this

itself.

reason,

because

to 400777

that

handle

The

handle

would

describe

process

handles

are

relative

never

assigned

they

them.

standard

''relative

have

number

process

created

several

system but

structure.

with

that

process,

However,

in fact be known

process
the

specifies
B.

process

LOOO0O3 may

each

referencing

and
is meaningful only to the process to which it is given
(that
is,
to
the
superior
process).
For example, if process A creates process B,
process A is given a
handle
(for
example,
L400003)
on
process
B.
Process

handle

for

are

used

than

its

handles

when

process

immediate

any

needs

inferior

are described

5-5

are

used

in Table

process
to

the

communicate

with multiple
5-1.

PROCESS

Table 5-1:

Process

STRUCTURE

Handles

Number

Symbol

Meaning

400000

.FHSLF

The current process (or self).

LO0O00O+n

Process n,

relative

the

current

process.

200000

FHZEPN

Extended page number

PMAP%).
the

When used

above

indicates
numbers
not

are

.FHSUP

has

meaning

not

use

extended

The

immediate

forms,

this

bit

and/or

page

the

executing

PM¥EPN

addresses

interpreted

relative

program

-1

two
that

(see

in conjunction with

absolute,

section

the

JSYS.

for

programs

This

the
bit

that do

addressing.

superior

the

current

process.

-2

.FHTOP

The

top-level

process

the

job

structure.

-3

.FHSAI

The

current

process

and

all

inferiors

the

current

its

inferiors.

-4

FHINF

A1l

the

process.

-5

.FHJOB

A1l

processes

5-6

the job

structure.

PROCESS STRUCTURE

Consider

the job structure below.

l
D

l
G

H
MR-S-2031-82

The following
referenced

if process E gives the handle:
refers
refers
refers
refers
refers
refers

.FHSLF
.FHSUP
.FHTOP
.FHSAI
.FHINF
.FHJOB

have

The process must

capability

specific

the

indicates

word

to Section 5.5.1).

to
to
to
to
to
to

process

processes

being

process E
process D
process A
processes E, G, and H
processes G and H
processes A through H

the

appropriate

capability

enabled

its

to use the handles .FHSUP, .FHTOP, and .FHJOB (refer

Process E can reference one of its inferiors (for example, G) with the

handle

was

reference other

given

when

processes

created the inferior.

the

structure

(for

Process E can

example,

executing the GFRKS%¥ monitor call to obtain a handie on the desired
for a
Refer to the TOPS-20 Monitor Calls Reference Manual
process.
description of the GFRKS% call.

5-7

PROCESS

5.4L

OVERVIEW OF

MONITOR CALLS

STRUCTURE

FOR PROCESSES

Monitor calls
exist
for
creating,
1loading,
starting,
suspending,
resuming,
interrupting,
and
deleting
processes.
When a process is
created, its address space is assigned, and the process
1is
added
to
the
job
structure
of
the
creating
process.
The contents of its
address space can be specified at the time the process is
created
or
at
a
later
time.
The process can also be started at the time it is
created.
A
process
remains
potentially
runnable
wuntil
it
is
explicitly deleted

A process may be
1.

its

superior

suspended

The process
interrupt

one of

executes
to

occur,

deleted.

the

following conditions

instruction
and

that

not

causes

prepared

occurs:

software

process

the

interrupt.

The process executes

the HALTF% monitor call.

The

requests

The

superior

suspended,

5.5

process

all

its

suspension of

suspended.

inferior

processes

its

inferior.

When

are

also

process

CREATING

Process)

the

address
the

PROCESS

space,

inferior

The CFORK% call

AC2:

creates an inferior process by executing the CFORK®Z
(Create
monitor call.
This monitor call allows the caller to specify

for

AC1:

suspended.

A monitor call is trapped.
(Refer to TFORK%Z monitor call
the TOPS-20 Monitor Calls Reference Manual).

A process

The

process

capabilities,

process

accepts

and

initial
start

characteristics

for

inferior

the

address of

a 20

values

the

characteristics

for
for

the

{octal)

inferior
in

execution

two words of arguments

address

for

contents

the

the
of

in ACl

the

right

word

block

process

are

ACs,

the

and

inferior.

and AC2.

left

half,

and

containing

the

half.

inferior.
inferior

5-2.

5-8

described

Table

PROCESS

Table 5-2:

Bit

Inferior

Process

STRUCTURE

Characteristic

Symbol

Meaning

CREMAP

Set

the map of

same

the

process.

This

space.

Changes

seen

the

this

bit

desired,
PMAP

that

the

process

made

the

one

the

(creating)

means

superior

same

and

address
will

process.

not

map

will

creating

GET

process

the superior

will

other

the

inferior

map of

inferior

inferior's

Bits

add

the

call,

contain

all

zeros.

|If

process

can

then

use

pages

the

inferior's

map.

CR%CAP

Set

the

process

capability
to

the

superior

5.5.1

for

same

word
as

process.

the

inferior

capability

word

(Refer

Section

description

the

capability

word.)
If

this

bit

inferior

will

Reserved for

CR%ACS

Set

the

values
If

CR%ST

ACs

this

the

inferior

the

not

will

set

contents

AC2

ignored.

for

the

inferior

given

the

execution

this

half
not

bit

can

the

PC value

for

5-9

the

not

right

then

the

given

the

AC2.

call,

zero,

the

and

the

process

the

half

ACl

and

the
and

call,
the

desired,

use

SFORK¥
process.

process

the

right

inferior

the

created

inferior

inferior.

ignored,
If

newly

the

started.

process
start

ACl

«call,

process

address

the

capabilities.

(must be 0).

ACs

Set

bit

special

inferior's

start

CRZPCV

Digital

beginning

address

18-35

not

have

creating

XSFRK%

CR%ST

is on.

PROCESS

| f execution of

the

process

created

Section

| f

not

execution of
and

This

handle

with

its

superior

error

the CFORK%¥ call

its
is

process

then

used

inferior
process

CFORK%Z
call.
in bits 18-35

two

call

and

not
code

successful,
is

returned,

the
as

inferior

described

1.2.2.

created

Assume

CFORK%¥

STRUCTURE

that

the

successful,
returned

superior
The

the

process

execution
second

inferior

process

right

the

when

the

instruction

inferior begins execution at the

(CR%PCV)

process

parallel

process.

continues

The

handle

if CR%ST
executes

inferior

half

ACI.

communicating
program

following

the
the

location contained

is specified.
the

CFORK% monitor

processes.

This

call

twice

represented

to create

pictorially

below.

Process A
Creates Process B
by Executing a CFORK

Process B Is Created
and Its Handle Is
Given to Process A

Process A Executes
Another CFORK to
Create Process C

—

Process C Is Created
and Its Handle
Given to Process A

Process B

MR-S-2034-82

Note

that

one

for

giving

process
process

A
C.

has

the appropriate

handle of

-4

been

Process

given

two

refer

either

to both

its

can

handle or

(.FHINF).

5-10

handles,

one

for
of

process

its

inferiors

giving

and
by

PROCESS

5.5.1

Process

When

its

superior,

Capabilities

new process

created,

the

setting of

capabilities

for

and

the

second

process.

process

indicates
This

given

indicated by
first word

STRUCTURE

the
are

given

CR%CAP bit
indicated

the capability

word

indicates

second word

the

one

capabilities

process,

and

user

represented

particular

bit

protected

independently

TOPS-20

Monitor

the

Calls

the

set

thus

the

for

the

CR%¥CAP

bit

words

are

job,

corresponds

can be

The

process,

enabled

activated

and

Refer

the

capabilities.

for

The

capability

other

call.

the

capability

and

Reference Manual

CFORK%

capability

Each

capability words

the

This

two capability words.

being

the

capabilities.

capabilities

capabilities.

available

the CFORK% call.
Types

same

special

information

the

capability words.

5.6

SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A PROCESS

Once

process

specified.

mentioned

indicate

that

same

the

creating
pages

from

can

the

file

the

process.

creating

the

into

pages

GET% Monitor

process

the

from

the

can be
the

set

space

process

execute

not

address

files

call

can be

that

the

CFORKY call

process
In

addition,

inferior

process.

address

call

the

space

specify

the

contents

space will

filled with

gets a save file,

the

entry

updates

vector

copying or mapping
the monitor's

and

the

for

created

either

with

the

list

(See

sharable
SSAVE¥

or
or

data

the

it
base

the

zeros.

.POADD

save

the TOPS-20 Monitor Calls Reference Manual

regarding

the

PDVOP%,

SSAVE%,

5-11

function

call,

file must

any

the

data

nonsharable

be open by

for

SAVE% monitor

The

not

into the

program

respectively.

information

the

specified

job.

(Refer

the

to map

PMAP% monitor

the

to be

Call

executed

were

the

into

addresses (PDVAs) from the save file.
the PDVOP% monitor call.)

This

can

three ways.

call

the

space

process.

vector

GET% monitor

another

does

address
one

inferior

can

the

its
in

the creating

address

appropriate.

copying

process

space,

The GET% monitor call
process

space of

process

address

CR¥MAP

execute

<creating

inferior

inferior's

space

can

contents

accomplished

bit

address

the

Section 5.5,

specified

5.6.1

created,

process

Finally,
map

This

process

and SAVEX% monitor

the

user's

for more

calls.)

STRUCTURE

The GET% monitor call accepts two words of arguments in AC1
and
AC2,
The first word specifies the handle of the desired process, flag bits,
and the JFN of the desired file.
The second word specifies where
the
pages
from
the
file
are
to
be placed in the address space of the
process.

Thus,

AC1:

process

handle,,flag bits

and

a JFN

AC2:

lowest process page
number
in
left
half,
and
highest
process
page
number
in right half; or the address of an
argument block.
If this AC contains page
numbers,
those
page
numbers
control the parts of memory that are loaded

when GT%ADR
Table 5-3 describes

is on

the bits

in ACI.
that

can be

set

in ACI.

Table 5-3:

GET% Flag Bits

—

——

—

————"

——

— —————

—

———

——

—

——

—

——

S—— S o———

PROCESS

Bit

Symbol

Meaning

GT%ADR

Use the memory address
If

this

bit

the file

is off,

limits given
all

(according to

its

in AC2,

existing pages of

directory)

are

mapped.

GT%PRL

Preload the pages being
mapped
pages immediately.) If this bit

(move
is off,

the
the

pages

when

they

are

GTENOV

are

read

error.

pages will

2L-25

GT%ARG

GT%JFN

from

the disk

Do not overlay existing pages and do return
an

referenced.

this bit

this

bit

off,

existing

be overlaid.

is on,

argument

AC2 contains the address

block.

JFN of the save file.

5-12

PROCESS

The

format

Table 5-4:

the

argument

block

STRUCTURE

Symbol

.GFLAG

Flags

that

.GLOW

Number
into

by
.GHIGH

the

which

how

the

used.

lowest
a

file

page

rest

the

page

gets

the

section

the

process

loaded.

This

specified

.GBASE.

Number

into

which

be within

the

page must

.GBASE

indicate

block

page must

5-4,.

Meaning

argument

in Table

GET% Argument Block

Word

described

highest

page

file page gets

be within

the

process

loaded.

section

This

specified

.GBASE.

Number

pages

are

section

the

for

use

save

file

are

Jloaded

file.

into which
You

single-section

this

regardless

save

section

loaded.

word with

causes
of

error.

into

this

the

section

the

file

can

specify

save

files

the

only;

multiple-section
The

section

file

pages

memory

specified

the

PROCESS

Table 5-5 describes

Table 5-5:

the

flag bits

STRUCTURE

defined

Symbol

GT¥LOW

.GFLAG.

Meaning

.GLOW contains the
page within

GT%HGH

GT%BAS

the

number

process

the

process

use.

lowest

the

highest

the

section

use.

.GBASE contains the number of
to

the

to use.

.GHIGH contains the number of
page within

use

GET% Argument Block Flags

Bit

]

for

PROCESS

When

the

address

pages

space,

overwritten.

unchanged.

data

For

file

example,

sets

the

file are mapped

the

Any

are

the

full

pages

Any

portions

are

the
of

pages

process
process

the

process's

process

that

are

not

pages

for

which

pages

are

overwritten
there

pages

zeros.

executed

address

into

contents

filled with

GET% call

process'

STRUCTURE

for

space

file

shown

Process

that
in

contains

the

following

1/2

diagram.

File

Page1 | Data

Data

Page 1

Data

Page 2

Data

Page 3

GET
Call

Page 2 | Data

Page 3 | Data

ST T T

EOF

gggg 2'1_2

Unchanged
MR-§-2032-82

After

execution of

the

GET%

program

software

interrupt

software

interrupt

system.

the

instruction

call,

control

following

generated,

which

5-15

the

returns

call.

|If

program

can

the

error

user's

occurs,

process

via

the

PROCESS STRUCTURE

PMAP% Monitor Call

5.6.2

to the
The PMAP% monitor call is used to map pages from one process
transferred;
actually
not
is
Data
process.
second
a
of
space
address

only the contents of the page map of the second (that is, destination)
process

are changed.

The PMAP% monitor call accepts three words of arguments in ACl through
The first word contains the handle and page number of the first
AC3,

page to be mapped in the source process
pages are being mapped).

(that is,

the

whose

process

The second word contains the handle and page

number of the first page to be mapped in the destination process (that
is,
the process
into which the pages are being mapped). The third

word contains a
indicating
the
pages mapped.

AC1:

count
of
the
number
of
pages
to map
and
bits
access
that the destination process will have to the

Thus,

source process handle in the left half,
the process

and page number

AC2:

destination process handle
in
the
left
number in the process in the right half.

AC3:

count of number of pages to map and the access bits.

The count and access bits that can be specified
in Section 3.5.6.1.

Upon

successful

the right half,

execution

the

PMAP%

half,

in AC3

<call,

and

are

page

described

addresses

the

destination process actually refer to addresses in the source process.
The contents of the destination page previous to the execution of
the

call

have

granted

been

deleted.

it does

not

The access requested in the PMAP% call

conflict

with

the

current

access

the

destination
page
(that is, an AND operation is performed between the
specified access and the current access).
Control
returns
to
the

user's

program

the

instruction following the PMAP% call.

error occurs, an illegal instruction
program can process via the software
or

5.7

ERCAL

instruction.

STARTING

A program
As

|If an

trap
is
generated,
which
the
interrupt system or with an ERJMP

in an

mentioned

INFERIOR

inferior

PROCESS

process can be started

in Section 5.5,

the superior

in one

two

process can specify

ways.
in

the

CFORK% call the PC for the inferior process and start
its
execution.
Alternatively,
the
superior process, after executing the CFORK% call
to create an inferior process, can execute the SFORK% (Start
Process)
monitor

call

start

it.

PROCESS

The SFORK% monitor call
ACl:

STRUCTURE

accepts two words of arguments

flags,,process

in AC1

and AC2.

handie

Flags:

SF%CON (1B0)
- Used to
continue
a
process
that
previously
halted.
If
SFZCON
is
set,
address

in AC2

continues

AC2:

the PC of

There are two
Section

8.3.2)

from

ignored,
it was

the process being started.

the

and

the

process

halted.

The PC contains flags

left half and the process starting address

right half.
PC

from where

This call

obtains the section number

the entry vector

alternative
or

SFRKVZ

ways

(see

has
the

in the

the

XSFRK%

(see

the process.

start

processes:

the TOPS-20 Monitor Calls Reference

Manual)
.
The process handle given

than one process

already

been

in ACl

cannot refer to a superior process,

(for example,

.FHINF), or to a process that has

started.

After execution of the SFORK% call,

control

returns

the

wuser's

program
at the instruction following the call.
[If an error occurs, a
software interrupt is generated, which the program can process via the
software

5.8

interrupt

system.

INFERIOR PROCESS TERMINATION

The superior process has one of two ways
when
one
or
more
of
its
inferiors

in which it can
be
terminate execution:

notified
via the

software interrupt system or by executing the WFORKZ monitor call.
An
inferior
process will
terminate normally when it executes a HALTF%

monitor call.
Alternatively, the process
will
terminate
abnormally
when
it
executes an instruction that generates a software interrupt,
such
as
an
illegal
instruction,
and
it
has
not
activated
the
appropriate channel.

activating

channel

.ICIFT

(channel

19)

for

inferior

process

termination
and
enabling the software interrupt system, the superior
process
will
receive
an
interrupt
when
one
of
its
inferiors
terminates.
(Refer
to
Section
L4.6
for
information on activating
channel .ICIFT.)
The
interrupt
occurs
when
any
inferior
process
terminates.
Use
of
the
interrupt system allows the superior to do
other
processing
until
an
interrupt
occurs,
indicating
that
an
inferior

process

has

terminated.

5-17

PROCESS

some cases,

until

either

completed

however,
a

the

specific

execution.

execute

the WFORKZ

superior

until

one

|If

until

process.

all

superior

this

the

all

This

inferiors

cannot

process
is

(Wait Process)

The WFORK% monitor call
desired

STRUCTURE

its

additional

its

inferior

case,

the

superior

all

monitor

call.

inferiors

have

accepts one argument
handle

can be

terminate,

but

.FHINF

This

have

process

can

call

blocks

the

the handle of

the

terminated.

in ACl,
(-4)

cannot be a

processing

processes

to block

handle

the

superior

process.

After

execution of

user's

program

specified
error

process

5.9
The

process

occurs,

via

INFERIOR
superior

executing
returns

The

the

short

the
two

status

return

set

and

wuser's

RFSTS% call
process

and

Table 5-6.

inferior

software

obtain

the

<call,

when

processes

the

terminate.

which

the

program

can

system.

the

status

words

to more

flags,,

1-17
the

are

short

process.

accepts
This

handle

the

long

(must

form

the

is successful,

instruction

ACl!

contains

the

one

handle
The
in

and

the

RFYLNG

call

in ACIl,

refer

form

to a

accepts

address

(bit

zero).
call,

following

control
the

The

status

returns

call.

the status word of

word.

This

argument
cannot

long

AC1

form,

RFSTS%

contains

inferiors

inferior

unused
of

its

given

process.

process

AC2.

call.

call

one

monitor

process.

than

Status)

the

RFSTS% monitor

program

AC2

returns

the

interrupt,

Process

desired

block

bits

execution

the

words:

status

(Read

and

the

interrupt

can

the

process

argument

control

following

STATUS

RFSTS®

form of

AC1

all

PROCESS

call,

instruction

generates

the

After

process

handle

superior

the

software

the

the WFORK% monitor

word

|If

the
is

the

given

shown

PROCESS

Table 5-6:

STRUCTURE

Process Status Word

Bit

Symbol

Meaning

RFYFRZ

The process
If

this

is suspended

bit

not

(that

on,

the

is,

frozen).

process

not

suspended,

1-17

RFESTS

The status of

the process.

Value

Symbol

Meaning

.RFRUN

The

process

runnable.

]

.RFI0

The

process

waiting
2

«RFHLT

1/0

The

process

never

.RFFPT

halted

HFORK% or HALTF%

monitor

for

call

was

started.

The

process

the occurrence

halted
of

sof tware

interrupt

for

which

not

prepared

The

was
to

right

status

the

handle.

half

word

number

channel

the

contains

the

which

the

interrupt occurred.

-RFWAT

The

process

waiting
process

.RFSLP

The

for
to

process

for

time.

halted
another

terminate.

specified

halted
amount

PROCESS STRUCTURE

Table 5-6:

Process Status Word

Bit

Symbol

(Cont.)

Meaning

Value

Symbol

Meaning

.RFTRP

The

process

dismissed
was

because

intercepted by

it
its

superior.
7

.RFABK

The

process

dismissed

because

address

break

was

encountered.

18-35

RF%SIC

The channel

number on

occurred,

which

prepared to handle
.RFFPT above)
.

The RFSTS% call
handle

generates

returns with -1

assigned
an

but

illegal

(fullword)

refers

instruction

which

the

interrupt

process

was

not

(see process status code

AC3

deleted

interrupt

|if

the

process.
the

specified
The call
handie

is set

in AC1

and

return,

AC]

described

unassigned.

In the

long form of

AC2

contains

and

AC2

are

the
not

the RFSTS% monitor

address
modified.

a
The

call,

status-return
status-return

Table 5-7.

5-20

RF¥LNG
block.
block

the

PROCESS

|
I
I

Table 5-7:

STRUCTURE

RFSTS% Status-Return Block

Word

Symbol

Meaning

RFCNT

Count

of words

left

half,

words

to return

word).

The

specified
]

.RFPSW

status word.

.RFPPC

.RFSFL

valid,

and

Process

PC
in

Process

PC.

returned

then

words

are

These

This
in

this

This word
return

ACl,

flags.
AC2

the

number

(including

from

wunassigned,

other

returned

Status

but

specified

are

ACl1

half

block

maximum

this

word

user.

the

this

right

format
If

.RFPFL

right

count

Process

was

returned

and

a
is

this

has
a

the

same

short

call.

process

this

word

handle
contains

returned.
are

short
the

the

same

flags

call.
address;

word.

flag word.

Flags:

Bit

Symbol

Meaning

RFZEXO

Process

|f an error occurs during execution of
interrupt

interrupt

generated which

the

program

system.

5-21

is execute-only.

RFSTS%¥
can

call,

process

via

software

the

software

PROCESS STRUCTURE

5.10
A

PROCESS

superior

same

process

pages

(bit CR¥MAP)
either
same

COMMUNICATI!ION
can communicate with

memory.

sharing

or the PMAP% monitor call.

these

pages.

seen by

This

calls,

Changes

both

made

the other

the

processes

can

system.

The

superior

process

generated

Interrupt

Channel)

the

interrupt

inferior

|1C% monitor call
handle

half

representing
software

example,

can

process

pages

cause

call.

interrupt

process

ACI.
one

bit

AC2

of
5

AC2:

the
is

process

than one

For

this
must

receive

contains
36

software

program

generates

software

the

the
a

the

36-bit

the

interrupt

AC2,

handle

the

right

bit

cannot

the

|IC%

refer

call,

following

interrupt

which

system.

5-22

and

with

AC2.
in

the

bit
AC2,

channel.

initiated

to
its

each

For

channel

half

with bit n on to

given

(lnitiate

given

initiate a software

instruction

interrupt

in AC1

corresponding
is

interrupt

communication

word,
|f

the
will

interrupt
11C%¥

interrupt

channels.

software

executes
share

activated

to a

superior

process

process.

After execution of

the

CFORK%

process

software

type of

channel

handle

the

inferior

software

executing

channels

initiated

36-bit word,
on

sharing

with

either

the
a

Thus,
process

superior

the

accepts two words of arguments

the

interrupt

AC1:

The

shared

the

and

system enabled.

The

When

superior

communicate via

monitor

inferior's

The

right

inferiors

accomplished

process.

Alternatively,

occur,

its
is

control

interrupt

to more

the

wuser's

returns

error

occurs,

process

via

the

call.

the

program

can

PROCESS

5.11
A

DELETING

process

executes

deleted

the

deleted,

its

process

are

inferior

INFERIOR
from

KFORKZ
address

the

PROCESS
the job

(Kill

structure when

Process)

space,

released.

it,

STRUCTURE

its

handle,

the

inferiors

monitor

are

and

process

the

call.

any

JFNs

being

also deleted.

structure:

superior

When

process

acquired

deleted

For

a
has

is
the

processes

example,

the

Process A

Process B

Process C
MR-5-2028-82

process

also deleted.

deletes

process

executing

KFORK% call,

process

The KFORK% monitor call accepts one argument in the right half of
ACI1,
the
handle of the process to be deleted.
This handle cannot refer to
@

superior

the

monitor

process,

process

call

to more

than

executing

the

used

Section 2.6.1.
After

execution

the

KFORK%¥

software

interrupt

software

interrupt

system.

instruction

process

call

reinitialize

program

the

one

call,

the

which

5-23

the

(for

example,

.FHINF),

is,

.FHSLF).

The

current

control

following

generated,

(that

process;

returns

call.

|If

program

can

RESETY

refer

the

error

user's

occurs,

process

via

the

PROCESS

P ROCESS

5.12

Example

STRUCTURE

EXAMPLES

- This program creates an

inferior process

to provide timing

interrupts.
TITLE

TIMINT

MONSYM

[
SEARGCH

MACHEYM

REQUIRE

INFERIOR

RESETR
MOVE

P ET0WD

POLSTZyFOLT

MOWVX T CRZEMAF
CHFORKEY

sHERE

STFROCS

THE

T4y Fl.al

MOVE

T1 e HANDLE
T2

SLEER

SRET
¢

HERE

WH HEN

has

LOOF
LOWER

THMSH
Counter

INTERRUFTS

ETC.

STACK

PROCESS SHARE
NEW PRUF”:p
FATAL

PROCESE

THIS

FROCESSS

;'7

HANIILE

COUNTER

SHET

FROCESS

HANDLE

SOET

ADORESS

THE

NEW

AND

START

FLAG

FROCESS

FROGESS

SUNEXPECTED

FaTal.,

ERROR

S IMOCREMENT

COUNTER

LOOF

HERTFN

FILESy

SINITIALTZE

SHTART

F ROCESSTMNG

A0%E

sRELEASE

FINITIALLZE

EJGHLT

L O3

TIMING

PFROCESS

SFORRKY

§oMAIN

ACH

SEAVE

ITNFERIOR

SETLR
MOVET

STANDARD

FUNEXFECTED

T4y HANDLE

START

SHEFINE

FMAKE NEW
FOREATE A

ELSHLT

MOUVEM

PFROVIDING

SY53IMACREL

aTnac.
STARTY
¢

PROCESS

HAS

SHAS

TIME

SNCy

ELAFSED

YETT

FROCESSTRG

INTERRUPTED

<
reached

sOUTHFUT

FIRST

MOVK

Tl FRIOU

JOET

FRIMARY

MOVE

T24T4

SOET

VALUE

sUSE

DECTMAL

MOVET

TXe"N10

NOUTY

SOUTEFUY

EJSERR

FRRINT

FART

MESHAGE

DESTIGNATOR

COUMTER

RADITX

CURRENT
ERROR

QUTFUT

COUNTER

MESSAGE

AND

VALUE
CONTINUE

THM&GG
sMOVE
JERET

FROGEA M

SLEEF?

STHROC

FERFORMED

MOVX

INFERTOR

TLy D3R
000

DIGMEY

SCONTINUE

FROCESS

NEW

LEINE

COUNTING

WALT

FOR

§ ONE-HALF

MINUTE

sWATT

SPECTFIED

FOR

ONE-HALF

MINUTE

MILLISECONDS
TIME

SETOM FLAG

STELL JUIthun”““'fi HAS ELAFSED

HALTE Y

SETNTGHE

CONSTA NTSG

STORAGE

FRLST

FHIZE

BLUCK

FOLSTYE

PHTACK

HANTIL.E
¢

BLOCK

S INFERTOR

FROCESS

Fil.afke

BLOCK

PINTERRUFT

FLAG

END

THE

START

5-24

STACK
HANDILE

MEMORY

PROCESS STRUCTURE

Example
used

- This

counter.

timing
10

program

source of
has

second

seconds,

program

then

counter

since
TITLE

reports
the

last

TRMINT

MONSYM

MACHYM

how
10

FORK

§OBET

MOVUX

TLy

MOVE

T2y LLEVTARy yCHNTARY

FHSILF

T2y 1B, TCEFT

START

THE

TI1yHANDLE

SETZER

INFERIOR

THE

LOOF

T4y1.O00F

FROINT:

INTERRUPT

LOWER

CHANNEL

TERMINATION

FATAL

SYSTEM

FATAL

ERKOR

AND

START

TIMER

FUNEXPECTED

FATAL

ERROR

PROCESS

SLEER

HANDILE

WHICH

PRESUMARLY

JUST

HAVE

KEEFS

HAS

COUNTING.

$JUST

FROCESS

COUNTER

UBEFUL

KEEF

INTERRUFTED
S8TACK

sMARE

FOINTER

FOR

Py IALSHOX

sHAVE

REST

ACH

MOVE

FeTACSHF

NUMEBER

HOUX

Tle

EXCH

TA4yQLOTAS

$RESTORE

RIOU

SUR

T4»01L.0T4

MOUM

T2+7T4
T3=70010

NOUTZ
EJSERR

FROGRAM.)

INCREMENTING

PHAVE

THMEE

(REAL

MAIN

Py ITACSHF

FOINTER

REST

ACS

COLUNTSE

s GET

FRIMARY

s EAVE

NEW

o NI

NUMBER

IT
JEE

QUTRUT

COUNTER
QF

FEEGNATOR

VYall

COUNTE

SIMCE

OECTHMAL

RAOTX

FOUTEUT CURRENT COUNTER VALUE
sPRINT ERROR MESSAGE AND CONTINUE
SAOVE

MOVE

T1»HANDLE

MOVET

T2y SLEEF

GFORKZ
e IACS

DEBRRKY

NEW

LINE

SOLET

PROCESS

HAMDLE

SHET

ADDRESS

UTART

SJSHLT

LaST

FOSTTEVE

TMEG

BLT

BIT

CHANNEL

ERROR

INTERRUFT

FyIACSH

MOVAT

FORK

ALDRESSES

TERMINATION

MOVET

THIS

ERROR

FROCESS

MOVEM

RLT

FOR

TARLE

FATAL

PROCESS

s CLEAR

FROGRAM

WOULIDY

AQJA

$§85AVE

T4,0L.0T4

WHEN

ADDRESSES

THE

NEW

START

FECTED

FaTal

s GF

FOINTER

SAVED

ERROR

SAVED
aCH

ITNTERRURT

5-25

FROCESS

PROCESS
ACS

has

timed

The

main

incremented

COUNTER

FAFFLICATION

HERE

HANDLE

TARLE

sOREATE

THE

has

STACK

PROCESS

SGET

SUNEXFECTED

EJSHLT

ETC.

SENABLE

CFORKE

LOOF

FILES,

§INITIALLZE

FUNEXFECTEDR

ELdGHLT

FMAIN

SRELEASE

SACTIVATE

EJSHLT

STEROCSE

ACS

PGET

ETRX

FINITIALTZE

process

INTERRUFTS

FUNEXFECTED

ALCZ

MOVEM

a
of

program.
it

purpose

interrupt.

STANDARD

FHET

AND

times

FPREFINE

sGET

EJSHLT

CREATE

main

sole

may

increments

SYSTEM

SIRA

the

inferior

the

TERMINATTON

FRLETZePOLD

INTERRUPT

MOUX

the

for

process

program

SYSIMACKEL

FeDIOWD

THE

running

time

many

second

RESETX
MOVE

Each

inferior

The main

interrupts

STOAC .

STARTY

process

intervals.
and

how an

interrupts.

inferior

stops

JREQUIRE

illustrates

timer

TIME

the

——
—

FOLLOWENG

FTIMING.
SLEEF:

——
—
——

EXECUTED

SLEEFS

FOR

STRUCTURE

PROCESS

LOWER

SECONDS

AND

10 GECGONDS
§ GLEEF

HALTEZ

FOTOR

AND

FOLZE

BLOCK

PRTACK

CHNTARS

REFEAT

PILSYTZ
7U1L9Dy JEXF

Lo y FROINT

REFEAT

00O

MILLYISECONDS

INTERRUFT

“01L8
s EXE

#OCHANNELS
sLEVEL

THE

MAIN

PROGRAM

STACK

O-18

ARE

FROCESS

NOT

RETHC

PRETURN

STORED

s LEVEL

EVEL

NOT

HANIH.ES BLOCK

FINFERTOR

RETFCL:

BLOCK

RETURN

OLOT4:

RLOCK

FHOLDG

TIMER

LACS

BLOCK

PSTORAGE

USED

TERMINATION

CHANNELS

THE

SHEMATNING

ENDN

THE

STOFS.

STORAGE

FOLG Y Z el

LEVTAR:

THEN

MOUX T1e"DLOXTMILOOO
RISMEH

——
————
———
———

CONSTANTS

——

—————

—

———

$THE

PROCESS

ARE

NOT

RETFCL

CHANNEL

USED
FOR

LEVEL

[\
L

PROCESS

STORED

FOR

START

5-26

VALUE

ACS

HERE

La8T

BURING

INTERR

INTERRUFT

INTERRUFTS

PROCESS

Example
a

|
|
I
|
|
|
|
|
|
|
|
|
I
|
|
|
|
|

I
|

line

- This

has

been

TITLE

program creates
typed on

FRRIOC

the

inferior

process which waits

terminal.

INFERIOR

FROCESS

WAITS

UNTIL

LINE

until

TYPED

MONSYM

MACSYM
+REQUIRE SYSIMACREL

SThAC.
START?

FUOEFINE

FRELEASE FILESy ETC.
FOLSTZyFDLY SINITIALIZE STACK
MOUX Tl CREMAF
SMARE NEW FROCESS SHARE
CFORKY
SOREATE A NEW PROCESS

SETZR

T4»FLAG

MOVET

T2yGETCOM

FROCESSING

AlS

FLAG

LOOF

PHERE

WHEN

INFERIOR

Counter

has

reasched

THSG

FROCESS

HAS

FROCESS

FaTal

P INCREMENT

COUNTER

sHAS

TIME

NOy

INFUT

ERROR

ELAFSED

DO
A

LINE

FIRST

YET®

FROCESSING
TEXT

FART

MESSAGE

SUSE

SGET VALUE OF COUNTER

T3,"1[110

DECTMAL

SOUTFUT

FEOUTY

SGET

HAL TFY

FGTOR

JRST

FERFORMED

INFERIOR

CASE

PROCESS

FROGRAM

TiyBUFFER

FOET

MOVET

FOINTER

T2y BUFSTZXE

SOET

COUNT

GETZM

NGO

RETYPE

ROTTYX

HALTF X

FTELL

SUFERTOR

PG
T

STORAGE
L)

F1i. ¢

BLOCK
BUF ST

L=t

BUFFERS

BLOCK

FlL.ag:

BUFSITZ

BLOCK

PLRILSLZ

sOLZE

THE

STaCK

FGT
FRUFFER

SIT2E

FINTERRUPFT

START

5-27

TEXT

RUFFER

FLAG

THE

TIME

PFINTSHED

AND

CHARACTERS

BUFFER

A LINE FROM
FUNEXFECTED ERROR

FLAG

LINE

TEXT

MAX

FREAL

EJSERR

END

CONTINUED

INFUT

HRROI

vODONSTANTS

VALUE

SOUTFUT TEXT JUST ENTEREI

START

SETOM

COUNTER

FIRST FART OF MESSAGE
SOUTFUT
FOINTER TO BUFFER

| Feho Check:
HRROL 71y BUFFER

FROGRAM

RADIX

CURRENT

SFRINT ERROR MESSAGE AND CONTINUE

GETCOM?

FLAG

FROCESS

MOVET

THSG

NEW

START

FUNEXFECTED

POUTEUT

EJSERR

THE

ERROR

SHET FRIMARY OUTFUT DESIGNATOR

NOUT

ADDRESS

PROCESS’S

MOUX T1s.PRIOU
MOVE T2,T4

COUNTER

THIS

LOOP

SRKIFN

JRET

FATAL

FINLTIALYZE

POTART

EJSHLT

L.OOF 3

FUNEXPECTED
SGET

SFORKY

MAIN

ACS

FyDIOWD

ELJEHLT

STANDARD

RESETX

MOVE

|
|
|
I
|
I
|
|
|
|
|
|
|
I

STRUCTURE

TERMINAL

HAS

FLAFSED

MEMORY

CHAPTER 6
ENQUEUE/DEQUEUE

6.1

OVERVIEW

Many

times

users

with

other

users.

file,

file,
the

other
no

are

users

placed

Each

situations where

user wants

are

reading

the

are also writing,

they must

to be guaranteed
same

data

even

and

reading,

that while
while
the

files

reading

writing

same

portion of

file.

Consider
many
can

FACILITY

data

agents
all

access

portion

replace

accessed
access

file

are

used

by members

reading

individual

accounts

the

file
data.

individual

exclusively

accounts

simultaneously
However,

account,
by

that

are

insurance
from

because

when

that

company.

the data
one

agent

the

None

the

other

changed

When

file,

they

changing

any

desires

portion

agent.

being

to modify

should

file

agents

wants

until

after

the

changes

are

cooperating

users

can

insure

that

made.

using

the

resources

not

ENQ/DEQ

are

interfere with

controlled

this

(for example,

READ,
for

wused

correctly

another

can

facility,

shared

However,

by multiple users

The
the

ENQ/DEQ facility
processes

physical

processes

using

Use

Nor
it

its

does
an

user's

modifications

resources

files,

control

that

operations

and memory pages.
allocation,

most

This

computer

the

can
on

files

facility

networks,

simultaneous

and

updating

common application.

integrity among processes

their

processes

it.

insures data

cooperate

resource.

non-cooperating

enqueueing

records,

queueing.

one

are devices,

resource

monitor

that

Examples

dynamic

internal
files

user's.

facility

WRITE),

and

wuse

both

facility

from

accessing

the

facility

incorrect manner.

only

the

facility

does

not

protection

the

prevent

resource without

provide

when

and

first

from

ENQUEUE/DEQUEUE

resource

Because
each
of
the

defined

1is

resource
the

lock

resource.

the

are

However,

For

there

this

access

the

occurs

processes

among

the

duration

processes

queue

This

from

call.

This

the queue

process.

than

satisfied.

6.2

RESOURCE OWNERSHIP

Ownership

for

shared.

Exclusive

the

other

resource.

relinquishes

it.

plans

updating a
process

When

This

resource with
to

should

all

when
use

the

use

one

the queue

process

call.

the
the

DEQ%

request
waiting
have

exclusive

use

ownership,

until

the

owner

the

the process

occurs
share

the

given

shared

not

resource

when

use

shared

ownership

Access

sole

requested

will

process

Processes

requests

ownership

resource.

any

either

time;

the queue

example,

specifying

the

1long

(for

lock.

resource

that

When

also

the

exclusive

Shared

processes.

resource
the

removing

is
and

the owner

issues

process

should

specifying

the

ENQ% monitor

as
a

the

resource

requests

granted

ownership

the

processes

lock

requested

request

available

resource,

shared

resource

to Section 6.2).

ordering

resource

the

allowed

simultaneously

placing

until

the

relinquishes

releases

type of

other

system.

resource,

process

then

in a data file).

requests

allowed

the

process

on modifying

record

ownership,

a
be

that

the

access

owner

(refer

ownership occurs

will

made

for

process

resource can

process

the

that

is generated by

continues

been

the

queue

request

lock,

one owner

request

cycle

the

resource by

call

This
a

requesting

ownership

and makes

This

use of

process

until

When finished with the resource,
monitor

not

for

When

specific

resource.

and

queue.

the

shared

using

can be more

called

processes

resource.

between

O0ther

obtain

for

resource.

placed

competition

associated with

requests

granted,

there

FACILITY

are

resource

modifying

the

resource.

Two

conditions

determine when

lock

given

process:

The

position

the

process's

request

the

resource.

The

Because

each

for
the

both
same

which

type

the

requests

for

basis.

has

and

facility

the

facility

this

are

specified

one queue

first

the

associated with

ownership of
placed

receives

first one serviced

multiple

ENQ

only

shared

Requests

ENQ

the

ownership

resource

queue will
words,

exclusive
queue.

queue

for

the

resources;
processes
request

the

them,

refer

6-2

for

the

first

the

Section

shared

first

request.

it,

resource

queue

and

(except

requests
is

the

process's

are
the

requests
placed

order

request

case

6.4.1).
in,

ownership,

the

single
|In other

first
that

out

request

ENQUEUE/DEQUEUE

will

but

first

serviced
not

request

allowed

along with

including

wuse

for

the

all

the

following

first

exclusive
resource

FACILITY

shared

ownership

exclusive ownership

ownership,

until

the

first

other

process

requests

request.

processes
has

up
the

are

released

the

lock.

Consider

the following queue

for

particular

request

!
!

resource.

(shared)

request 5

(shared)

=
!

Request
the

request

the

will

queue.
2

serviced

However,

can

also

processes

Eventually

the

two

the

first

following

the

requests

lock

are

resource.

because

released

removed

from

the
is

first

for

cannot

request

shared

until

the lock on
processes,

The

ownership,

serviced

release
the two

the queue.

request 4

now first

the

and

queue

the
and

now has

entries:

Because

requests will

releases

request

Request

request

Request

because

this

serviced.

with

resource.

first

since

serviced.

lock,

they both

the

are

both
for

the

queue

request

Once

the

request

(shared)

and
for

given

exclusive

lock

ownership,

process

associated with

request 5

and

shared ownership.

6-3

can be

on
no

the
other

request

serviced

ENQUEUE/DEQUEUE

6.3

FACILITY

PREPARING FOR THE ENQ/DEQ FACILITY

Before using the ENQ/DEQ facility, the user must obtain an
ENQ
quota
from the system administrator and must obtain the name of the resource
desired, the
type
of
protection
required,
and
the
level
number
associated with
The

ENQ quota

outstanding
cause

the

indicates

for

the quota

use

the

The

resource

resource.

the

name
no

has

resource

system makes

association.

process

The

requests

user

must

and

between

the

The

Any

upon

resource

different

all
of

responsibility of

system merely uses

handles

The

can

that would

wuser

cannot

to zero.

identifier

the

that

request

in an error.

set

requests

the

resource.

The

name

and

the

user's

process

resource

name

requests

for

the

resource

wusers

the

names

the

physical

resources.

resource

JFN

name

the

(refer

time.

agreed

serves

association

make

different

results

a meaning

itself;

number

any given

the quota

and

resource
that

total

to be exceeded

ENQ facility

specific

the

wuser

has

file

initialize

to
is

either

string

uniquely

either

parts.
file

3.1).

pointer
byte

cases,

the

first

using

the

ENQ

Before

wusing

the

appropriate

The second part of
to

identifies

standard

|In most

accessed.

the

Section

which

two

being

string or

the

resource

all

users.

the

form

left-justified

the
the

calls

is a modifier,

wuser

pointer

part

monitor

the name

33-bit

facility,

The

code.

The

pointer

can

-1,,ADR
where

ADR

The

33-bit

item

such

considers

assigning

values.

file

is
it

When

same

name

are

-2

instead

the
-3

capability

the

and

prevent

same

desired

for

user

specifies

the

standard

resources

the

job.

different

JFN,

it means

system.

-2

that

this
JFN,

that

Quotas

are

The

ENQ
not

facility
check

careful

for
when

two different

JFN

type
it means

the

a job

of
the

process

user

type of
is

have

the

any

its
wuser

protection

reserved

specifies

accessed

protection.

checked when

This

accessed

resources

same

of
the

SC¥ENQ enabled

for

as
the

WHEEL

OPERATOR

given

instead

-3

'
6-4

can

this

system.

are
the

the

file,

instead

When

have bit

-1

requesting

resource

However,

of a JFN.

the desired

specifies

jobs

the

not

indicated

name can be one

resource.

the

is
the

protection of

user

Other

specified.

requires

enabled.

part

the

process must

specify

instead of

resource

defined within

must

This

access

When

users

string.

representing

does

the occurrence of

the

and

text

resource.

name.

case.

resource

strings

Thus,

that

given when

moni tor

number.

block

queued

capability word
specifies

logical

resource

that

processes

job

that

the

users.

typical

means

ASCIZ

identifies

number

modifiers

the

subject

the most

only

the

protection

part of

the

similarly

record

referring

type of

JFN,

among

four

these

modifiers

first

location

code

these modifiers

cooperation

The

the

user

ENQUEUE/DEQUEUE

FACILITY

in addition to specifying the resource name and

type

the

resource.

user

also

assigns

level

number

to each

protection,
The use of

level numbers prevents the occurrence of a deadly
embrace
situation:
the
situation
where
two
or
more processes are waiting for each to
complete, but none of the processes can obtain a lock on the
resource

it needs for completion.

This situation is represented by Figure 6-1.

Process A Is
Waiting for a
Resource Process
B Has.
i

Process B Is
Waiting for a
Resource Process
C Has.

Process C Is
Waiting for a
Resource Process
A Has.
MR-S-2029-82

Figure 6-1:

Deadly Embrace Situation

Each process
request
is

in the queue waiting for the resource it needs, but no
being
serviced
because
the
desired
resources
are

unavailable.

The use of level numbers forces cooperating processes to
order
their
use
of
resources by requiring that processes request resources in an
ascending numerical order and that all processes assign the same level
number
to
a
specific
resource.
This means that the order in which
resources are requested is the same for all processes
and
therefore,
requests
for
the first resource will always precede requests for the
second

one.

| f both of the above requirements are not met, the process
requesting
the resource receives an error, unless the appropriate flag bit is set
(refer to Section 6.4.1.2), and the
request
is
not
placed
in
the
gqueue.
Thus, instead of waiting for a resource it will never get, the
process is informed immediately that the resource is not available.

ENQUEUE/DEQUEUE

6.4

USING THE

There

are

ENQ/DEQ FACILITY

three monitor

calls

available

ENQ%,
to
request
use
of
a
resource; and ENQC%¥, to obtain
specify

6.4.1

access

for

issues

associated

the ENQ% monitor call

with

resource

the

name,

desired

level

to place a

resource.

number,

can

and

This

type

used

|In

fact,

when desiring multiple

request

them

all

guarantees

that

the

requested

because

the

resources

single

call

requesting

resource)

single

entire
not

are

second

one

never

the

any

all

number

the user
of

allocates
Because

resources

some

resources

the

should

resources

the

only

all

time,

queue
specify

required.

requesting

same

in the

used

request

none

call.

resources,

method

either

ENQ/DEQ facility

currently

for

multiple

single

calls

request

is
an

word

contains

not

rejected

specified.

return

first

This

gets

available

error

The ENQ% monitor call
The

call.

user

specified

must

call
of

resources

did

facility:

first

of
in

user

a
resource
(that is, the first user in the queue for the
may not be the first user obtaining it if other resources in

request

series

one

request

call

protection

resources.

the

ENQ/DEQ

these gueues.

A single ENQ% monitor call

the

resource; DEQ%, to release a lock on a
information about
the
queues
and
to

Requesting Use of a Resource

The user
the

FACILITY

ACl1:

function

AC2:

address

resources

resources.

those

if
a

will

error

series

not
is

address

functionally
In

returned

single

calls,

the

same

single

call,

the

for

one

the

each

request

that

be queued.

accepts two words of

contains
the

available.

the
of

code
the

arguments

the

desired

argument block.

in AC1

and

function,

AC2.

and

the

Thus,

code
of

argument

block

6.L.1.1
ENQ% Functions - The functions that can be requested
ENQ% call are described in Table 6-1.

6-6

ENQUEUE/DEQUEUE

Table 6-1:

FACILITY

ENQ% Functions

Code

Symbol

.ENQBL

Meaning

Queue

the

process

requests

until

acquired.

error
not

.ENQAA

This

code

the

locks

are

the

.ENQS!

all

error

I f

.ENQBL

resources

the

any

locks

code

the

software

all

resources

one
no
are

specified

not

all

are queued,
is

resources

process.

immediately

requests
interrupt

are

identical

function.

requested

the

for
all

function

are

available,

6-7

If
will

available,

this

the

resources

ACI1.

available,

given

not

requests

all

acquire

queued,

and

resources.

when

and

requested

Queue

process.

and

all

returned

the

returns

the ENQ% call

available.

the

are

the

are

available,

resources

acquired,

the

locks

specified.

are

requests

immediately

allocated

block

function

requests

only

resources
of

and

requested

only

correctly

Queue

all

generated
have

been

ENQUEUE/DEQUEUE FACILITY

Table 6-1:

ENQ% Functions (Cont.)

Code

Symbol

Meaning

.ENQMA

Change
the
ownership
access
of
a
previously-queued
request
(refer
to
bit EN¥SHR below).
The
access
for
each

lock

with

in this request is compared
for each lock
in
the

the access

request
already queued.
No action is
taken if
the
two
accesses
are
the
same,
If
the access in this request

shared

and

the

request

ownership access
access.

the

exclusive,

changed

Otherwise,

returned

access

the

shared

error

if:

The process
the

shared
is

tries

ownership

to exclusive.

desired,

change

access

the

from

|If

process

this
should

issue a DEQ%¥ monitor call
the

shared

issue
call

request

another
for

ENQ%

for
then

moni tor

exclusive ownership.

Any one of
does

and

the

not

specified

have

locks

pending

request.

Any one of

the specified

is a pooled resource
Section 6.4.1.2).
Each

lock

the

access

that

were

receiving

should
to

specified
is

correctly
an

6-8

error,

issue the ENQC%¥

determine

each

changed

lock

the

checked,
for

locks

(refer

and

all

locks

given.

the

process

monitor

current

call

state of

(refer to Section 6.4.3).

ENQUEUE/DEQUEUE

6.4.1.2

FACILITY

ENQ% Argument Block - The format of

described

the

argument

block

in Table 6-2.

Table 6-2:

ENQ% Argument Block

Word

Symbol

Meaning

.ENQLN

Number

locks

being

requested

the

half, and length of argument block
this word) in the right half.
1

LENQID

Number

software

left half,

LENQLV

interrupt

request

channel

the

half.

right

the

Flags and level number in the left half,
and
JFN,
-1,
-2 or -3 (refer to Section 6.3) in
the

and

left

(including

.ENQUC

right

Pointer

half.

to string

5B2+33-bit

wuser

code

the

left

(refer to Section 6.3).
L

.ENQRS

Number of
half,
the

.ENQM5

Words

.ENQLV,

each

lock

right

Address

.ENQUC,

being

and

resources

the pool

number

resources

requested

and

.ENQRS

requested.

half.
a

resource mask

block.

(words 2 through L)
These

three words

are repeated

are called

the

for
lock

specification.

Software
The

software

function
when

Interrupts

the

interrupt
specifies

interrupt

(refer
user

requests

to
the

system

used

to Section 6.4.1.1).
them,

the

be generated when

.ENQS!

the

software channel

on which
in

the

argument

block.

number

tfthe

6-9

the

.ENQSI

locks are not available

function

locks

channel

placing

conjunction with

|If all

software

become available.

causes

The user

receive

the

interrupt

left

half

word

.ENQID

by
the

ENQUEUE/DEQUEUE

When

the

user

will

desires

the

is waiting

receive an
to be

locks

the user

interrupt

each

lock

lock will

the

becomes

lock

become

available,

is available.

available,

|If

can

indicated by

assign

issuing multiple ENQ% calls.

then be

requests

the

system first or

.ENQSI
else

function,

The

the occurrence

must

interrupt will

not

initialize
be

the

generated when

(refer to Chapter L).

The 18-bit request

is currently not used

stored

for

the

process.

use as

identification

use

.DEQID function of
Flags

lock

last

channel.

the locks become available
Request

than one

separate channels by
each

interrupt on each

When

interrupt when

informed as

availability of
an

for

FACILITY

and

Level

for

the

Thus,

the

request.

the DEQ% monitor call

the

process

system,

can

supply

wuseful

but
an

This

(refer

to Section 6.4.2.1).

the

Numbers

Table 6-3 describes the flags that can be used in the
first word of each lock specification (.ENQLV).

left half of

the

ENQUEUE/DEQUEUE

Table 6-3:

FACILITY

Lock Specification Flags

Bit

Symbol

Meaning

ENZSHR

Ownership for this resource is
shared.

ownership

this

for

bit

this

resource

level

number

not

on,

exclusive.

]

ENZBLN

fgnore

the

with

this

set,

sequencing

numbers

resource.

are

successful

ACl1

contains

sequencing
a

error

sequencing

fatal,

did

the

error

occurred,

error

level
and

continues.

completion

either

bit

considered

the call

this

errors

not

execution of

associated

not

call,

code

zero

a
if

occur.

WARNING
A

deadly

occur
not

embrace

when
wused.

numbers

this

ENINST

numbers

Use

guarantees

situation
not

situation may

level

cannot

are

these

that

such

arise;

for

reason bit EN%BLN should
be

set.

Allow ownership of

this

lock

nested.

ENZLTL

Allow

long-term

lock

this

with

this

resource.

L-8

9-17

Reserved for Digital.

EN%LVL

Level

number

resource.,
the

user

wusers

eliminate

situation,
order.

number

and must

all

resources

associated

This

specified by

agreed

the

resource.

deadly

users
in

must

numerically

wupon
|In

order

embrace

request
increasing

ENQUEUE/DEQUEUE FACILITY

The request is not queued, and an error is given, if EN¥BLN is not set
and

The user requests a resource with a level number less than or
to the highest numbered resource he has requested so
equal

far.

The level number of this request does

not

match

allocate

the

number supplied in previous requests for this resource.

level

Pooled Resources

wWord .ENQRS of each lock specification is used

copies

from

pool

of identical resources.

multiple

Bit EN%SHR, indicating

shared ownership, is meaningless for pooled resources because each
resource in the pool can be owned by only one process at a time. A
process can own ohe or more resources in the pool; however, it cannot
own more than there are in the pool or more than there are unowned in
the pool.

resources
number of
The left half of word .ENQRS contains the total
in the pool. This number is previously agreed upon by all
existing
the
The first user who requests
users of the pooled resource.
resource sets this number, and all subsequent requests must specify
the same number or an error

is given.

resources being
The right half of word .ENQRS contains the number of
than zero if a
greater
requested by this process. This number must be
the
in
number
the
than
pool of resources exists and cannot be greater
user
the
exists,
resources
This means that if a pool of
half.
left
must request at least one resource,
in

the

than

are

resources

are

but cannot request more

pool.

Once the number of pooled resources

allocated until

the pool

is determined,

is depleted or until

the

a request specifies more

resources than are currently available.
In the latter case, the
user
making the request is not given any resources until his entire request
can be satisfied.

Subsequent

requests

from

other

users

are

not

granted
wuntil
this
request
is
satisfied
even though there may be
enough resources to
satisfy
these
subsequent
requests.
As
users
release their resources, the resources are returned to the pool.
When
all resources have been returned, they cease to exist,
and
the
next
request completely redefines the number of resources in the new pool.

ENQUEUE/DEQUEUE

The

system assumes

word

L.ENQRS

should

set

the

type exists.
a

number

for

left

|If

the

This

access

access
to

case,

group of

that when

only

set

one

who

the

pool
is

the

resource

right

can

half

left

half

Thus

the

this

simultaneously
is

the

The use of

processes

nonzero.

resource

users

resource.
a

then

users

only other
to

specification

the

resource

to zero

means

shared ownership,

allowed

the
lock

half

this

defining

resource,

that
the

FACILITY

specific

group

sharer

groups

smaller

than

word

the

to a

user

will

allocated

same

of
user

restricts

the

set

for

shared ownership (which is sharer group 0) but larger than the set for
exclusive ownership.
(Refer to Section 6.5 for
more
information
on
sharer groups)
.

6.4.2

Releasing a Resource

The user
queue
not

issues the DEQ% monitor call

associated

the

user

with

actually

queue

for

the

resource.

owns

lock

to remove

resource or

can be used to remove
If

that

could

call
Thus,

user

as
the

error

code

be dequeued.

many
lock

attempts

the

until
then

any

requests

all

lock

returned

The process

allocated,

resources

specifications
to

dequeue

error

the
or

only

waiting

requests

removed,

specifications

for

can

number
cannot
the

then

last

request

execute

code

can,

the

even

pooled

returned

argument
and

error

block.

resources

none

found

the

ENQC%

the

lock.
will

returned

However,

than

the

have been

(refer
to
Section 6.4.3) to determine the status of each
unlike the operation of
the
ENQ%¥
call,
the
DEQ¥
call

dequeue
one

one

procedure continues

not

from

resource.

queues.

processed.

removed whether

the

from

dequeueing

request

The DEQ% monitor call
the

The

for

when

originally

resources

are

dequeued.

The DEQ% monitor call
The

first

second word

word

accepts two words of arguments

contains

ACl:

function

AC2:

address

the

code

address

code
of

argument

block

for
the

the desired
argument

in AC1

and

function,

block.

Thus,

and

AC2.
the

ENQUEUE/DEQUEUE

6.4.2.1
6-4

DEQ¥ Functions - The DEQ¥ functions are

Table 6-4:

Symbol

.DEQDR

Table

Meaning

Remove

This

the

.DEQDA

Remove all

requests

from

the queues.

the only one

that

requires an

requests
This

monitor
this

block.

queues.

.DEQID

specified

function

argument

described

DEQ% Functions

Code

FACILITY

call.

for

this

action

An error

process

has

not

process
taken

code

if this process has

Remove all

requests

specified

request

function

18-bit
This

that

specified,

of
lock

should be

1locks
in

the

locks

For

example,
the

that were

issued

the

When

must

user

this

place

the

release

without

block.

with

this

function

to be

the

same as

function

one

itemizing

The
in

enqueued

in
the ENQ% call and
that file at once.

AC2 on the DEQ%¥ call.

in one call
argument

the
RESET

resources

correspond

used when dequeueing

same

specify

not

the user

returned
any

identifier.

function aliows

class
each

request

requested

(that is,
ENQX)
.

from

call

one

the

call.

the user
the

thus remove all

JFN

can
used

locks to
|

ENQUEUE/DEQUEUE

6.4.2.2

DEQ¥ Argument Block - The format of the

|
{

function

Table 6-5:

|
|
|

FACILITY

.DEQDR

described

block

for

DEQ% Argument Block

Word

Symbol

Meaning

.ENQLN

Number

half,

locks

and

being

requested

length

(including this word)
]

argument

in Table 6-5.

.ENQID

Number
left

software

half,

and

the

argument

left
block

in the right half.

interrupt
request

channel

1ID

the

right

half.
2

.ENQLV

Flags

.ENQUC

and

level

number

the

left

and

JFN,

-1,

-2

6.3)

-3

(refer

in the right half.

Pointer

string

5B2+33-bit

(refer to Section 6.3).
L

.ENQRS

Number of
half,

the
5

.ENQMS

and

right

Address

Words

.ENQLV,

.ENQUC,

and

each

request

being

dequeued.

.ENQRS

half,
Section

user

code

left

resources

in the pool

in the

number

resources

requested

half.
a

resource mask

(words

These

specification.

6-15

through

three words

block.

are

repeated

called

the

for

lock

ENQUEUE/DEQUEUE FACILITY

6.4.3

Obtaining

Information About Resources

The user issues the ENQC% monitor call to obtain information about the
current status of the given resources. This call can also be used by
privileged users to perform various utility functions on the queue
structure.
The format of the ENQC% call is different for these two
uses.
(Refer to the TOPS-20 Monitor Calls Reference "Manual
for
the

~explanation of the privileged use of the ENQC%¥ call.)

The ENQCZ% monitor call accepts three words of arguments in ACl

through

AC3:

AC1:

function code

(.ENQCS)

AC2:

address of argument block

AC3:

address of area to receive status

information

The format of the argument block is identical to
the
format
of
the
ENQ¥
and DEQ% argument blocks.
The area in which the status is to be
returned should be
three
times
as
long
as
the
number
of
locks
specified

the argument block.

On successful execution of the ENQC% call,
lock

specified

entry has

returned

the following

the current status of

as a three-word entry.

each

This three-word

format.

Flag bits

indicating status of

Reserved

lock

Request

ENQUEUE/DEQUEUE

FACILITY

Table 6-6 describes the flag bits that can be used

Table 6-6:

in a ENQC% call.

ENQC% Flag Bits

Bit

Symbol

Meaning

EN%QCE

error

has

corresponding

occurred
lock

18-35 contain

the

request.

Bits

appropriate

error

code.

]

EN%QCO

EN%QCQ

The process

issuing the ENQC% call

the owner

this

The process
in

the

issuing the ENQC% call
queue

resource.

lock.

This

waiting
bit will

for

this

when

EN%QCO is on because a request remains
in the queue
wuntil
a
DEQ¥
call
s
given.

EN%QCX

The

lock

has

been

allocated

exclusive ownership.

EN%QCB

off,

there

the

number

sharers

The process
in

the

way

of
of

this

for
bit

be off

waiting

the

determining
the

resource.

issuing the ENQC% call

queue

ownership

will
5-8

When

for

resource.

exclusive
This

bit

if EN%QCQ is off.

Reserved for Digital.

9-17

EN¥LVL

The level

18-35

EN%JOB

The number of the job
lock.

For

ownership,
number

this

the

is on,

this
is

lock

the

shared
the

job

However,

current

current job

job's

is one of
is

not

-1.

this

the appropriate error

6-17

the owners.

the

the value

| f EN%QCE

owns

with

this value will
one

owners.

owned,

that

locks

value will

number
the

number of the resource.

field
code.

contains

ENQUEUE/DEQUEUE

FACILITY

The 36-bit time stamp indicates the last time
The

resource.

currently

The

request

the
or

has

6.5

request
the

time

lock

the

returned

request

of
ID

the
of

the universal

resource,

the

right

current

this word

half

process

the owner

the

process

date-time

the

that

locked

standard.

|If

the

no one

zero.

third word

process

either

the queue

lock.

SHARER GROUPS

Processes

can

numbers

(refer

restricts

the ownership for

than

the

specify

set

the

sharing of

Section

for

resources

6.4.1.2).
a

shared

The

resource

to a

ownership

but

using

use

set of
larger

sharer

group

sharer

processes
than

the

groups
smaller
set

for

exclusive ownership.

Sharer

group number

processes

specified

group

number

Consider
on

the

file.

the

used

resource.

in the ENQ% call.
other

than

indicate

This

O must

group

are

four

To restrict use
be

following example.
There

the group of

number

types

explicitly

The
of

all

cooperating

assumed when

the

specified

the

operation
resource is the
WRITE
of this resource as shown in

uses

Process’ Own Use of
the Resource
Not Aliowed

Write

to Write

3
Exclusive

4
Shared, Group 1

Other
Process’ Use
of the Resource

rite

Shared, Group 0

Not Allowed
to Write

Efig/%?oto Use

MR-S-2038-82

Figure 6-2:

Use of Sharer

Groups

call.

Figure 6-2.

Writ

group

resource,

ENQUEUE/DEQUEUE

In block
all

the

figure,

cooperating

perform the WRITE
process

locking
Thus,
In

|In

the

there

block

the

block

need

the

exclusively and does
process

obtains

the

figure,

the

but

also

does

request

plans
one
long

not
a

desire

this

because

this

same

example,

sharer

resource

different

type of

group O

facility.
where a

6.6

the

other
the

desires

processes
for

the

lock

processes

ENQ/DEQ
lock

lock

it.

the

use,

exclusive ownership
releases

is,

1lock.
the

its

own

lock.

defined

include

all

not

another

user

processes

sufficient,

process with

Thus,

processes
the

subset

the

resource,

sufficient

groups

for

should only

cooperating

most

uses

needed

with

the

lock

the

lock

resource

processes

must

have

the

those
a

this

it).
for

use.

should

soon
be

processes

obtaining

the only
would

processes who do not want to

also do not want other

others

other

another

the
4

immediately

lock,

obtain

resource

because

it.

|In block

ownership

However,

the

lock

Thus,

process were

exclusive

plan

facility.

the

resource

lock

the

cooperating

not

resource.

all

allow
is,

call,

processes

owned

problem of

Additional

ENQ/DEQ

situations

specific

use

the above example.

AVOIDING DEADLY EMBRACES

Processes

can

communication

interact

shared.

occurrence

each

other

but

for

completion.

consider

the

following

embrace:

neither

This

should

them.

possible,

time and

processes
one

undesirable

when

one

ways

two

can

situation

improper

situation

processes

gain

can

resources

are

the

are waiting

for

access
to the

resource

avoided when

processes

guidelines.

Processes
|If

undesirable

the

example of

deadly

complete

many

among

needs

occurs

incorrectly

to use

process

use,

by
does

unavailable

immediately but

elimates

Sharer

(that

locked
process

resource.

could

group

same type of use

the

process

use

(that

ENQ¥

resource would be

type of

the

process
the

not want

type

not care

other

the

one

different

This

want

process

once

the

does

lock

because

the

does

not want other

process

resource

the

exclusive ownership

requesting

sufficient,

for

lock wishes

the

can

figure,

the

lock

Therefore,

the

and

owning

also

resource
of

resource

operation).

specifies

processes.

the process

processes

FACILITY

request

resources

processes

release each

should

the

request

resource before

time

they

resources

requesting

the

need
one

one.

Processes

should

However,

the

plans

request

process

on modifying

shared

should

the

ownership whenever

not request
resource.

6-19

possible.

shared ownership

ENQUEUE/DEQUEUE FACILITY

it should
When a process needs more than one resource,
muitiple
of
instead
request these resources in one ENQX¥ call
the
release
also
calls for each resource. The process should

entire set of resources at once with a single DEQ¥ call.

When the use of one resource depends on the use of a second
the process should define the two resources as one in
one,
However, there is no protection of
the ENQ% and DEQ% calls.
the resources if they are also requested separately.

Occasionally processes use a set of resources and

require

the second resource while retaining the lock on the
lock on
are
locks
the
in which
the order
In this case,
first.
of
set
the
of
all users
the same for
obtained should be
the
by
accomplished
The same ordering of locks is
resources.
The
to each resource.
numbers
level
processes assigning
ascending
in
resources
requirements that processes request
numerical
order
and
that
all processes use the same level
embrace
number for a specific resource ensure that a deadly
situation will

not occur.

6-20

CHAPTER 7

INTER-PROCESS COMMUNICATION

7.1

FACILITY

OVERVIEW

The Inter-Process Communication Facility

(IPCF)

allows

communication

among
jobs
and
system
processes.
This
communication occurs when
processes send and receive information in the form of
packets.
Each

sender

and

receiver

has

Process

(PID)

assigned

to it for

identification purposes.

When the sender sends a packet of information to another process,
the
packet
is placed into the receiver's input queue.
The packet remains
in the queue until the receiver checks the
queue
and
retrieves
the
packet.
Instead
of
periodically
checking
its
input
gqueue,
the

receiver can enable the software interrupt system (refer to Chapter 4)
to generate an

interrupt when a packet

is placed

its

input queue.

The
<SYSTEM>INFO
process
is
the
information
center
for
the
Inter-Process
Communication
Facility.
This process performs system
functions related to PIDs and names, and any process can request these
functions by

7.2

sending <SYSTEM>INFO a packet.

QUOTAS

Before using IPCF, the user must
acquire
the
ability
to
use
IPCF
privileges
from
the system administrator:
a send packet quota and a
receive packet quota.
These quotas designate, on a per process basis,
the
number
of
sends and receives that can be outstanding at any one
time.
For example, if the process has a send quota of two and it
has
sent
two
packets,
it cannot send any more until at least one packet
has been retrieved by its receiver.
A send packet quota of two and
a
receive
packet
quota of five are assumed as the standard quotas.
|If
these quotas are zero,

the process cannot use

IPCF.

INTER-PROCESS

7.3

FACILITY

PACKETS

Information

divided

into

words

COMMUNICATION

and

transferred

packet

the packet

data

the

block

shown

Packet Descriptor

IPCFL

two portions:

form of

packet

the

Figure

packets.

descriptor

length

the

Each

block

message.

packet

The

format

7-1.

Block

flags
!
e
it T T T Ty !
!
PID of sender
!
e
e
ee !
|
‘
PID of receiver
!
et LT
O!
|
length of message
!
address of message
!
!
n
!
ADR
!

.IPCFS

.IPCFR
JAPCFP

e e

.IPCFD

!
f
.IPCFC

sender's

. |PCAS

f o
e

.IPCLL

ADR

logged

enabled

capabilities

connected

sender

e e e

string of

sender

logical

location of

message word

o
message word

IPCF

e ee !
account

e e

directory

Figure 7-1:

sender's

!
directory
!
ee !

directory

.IPCSD

connected

Packet

7-2

sender

four

!
]

six

INTER-PROCESS

7.3.1

FACILITY

Flags

There are
- packet

two

types

descriptor

instructions

right

are

"right

COMMUNICATION

half

Section

flags

block.

IPCF

for

The

can be

flags

set

the

left

packet communication,

descriptions

are returned as

7.4.2).

that
The

word

.IPCFL

half

and

the

the data message.

part of

the

the word

flags

The flags

the associated variable

are

the

(refer

packet descriptor block flags are described

Table 7-1.

Table 7-1:

Packet Descriptor

Bit

Symbol

IP¥CFB

Block

Flags

Meaning

not

block

messages

process

the

process

the queue.

receives

|[f

this

error

there

are

bit

on,

the

are

there

messages.

]

IP%CFS

Use the PID obtained from the
.IPCFS

sender's

IP¥CFR

the

packet

block

word
as

the

PID.

Use the PID obtained from the
.IPCFR

address

descriptor

the

receiver's

PID.

packet

address

descriptor

block

word
as

the

| PECFO

Allow the process one send above the send quota.
(The standard send quota is two.)

| PETTL

Truncate the message
area

reserved

this

error

| P%CPD

| PEJWP

not

on,

the

the message

is
the

too

longer
packet

process

Create a PID to use as the

sender's
in word

created

descriptor

returned

than
data

the

block.

receives

PID.

The

long.

PID

packet

bit

for

.IPCFS

the

block.

Make the PID created be permanent until the
job
logs
out
(if
both
bits IP¥CPD and IP%JWP are
on). Make the PID created
be
temporary
until
the
process
executes a RESET% monitor call (if
bit IP¥CPD is on and bit IP¥JWP is not on).
| f
bit IP¥CPD is not on, bit IP¥JWP is ignored.

7-3

INTER-PROCESS

Table 7-1:

Packet Descriptor Block Flags

Bit

Symbol

| PENOA

8-17
18

FACILITY

(Cont.)

Meaning

Do not allow other

processes

created when bit IP%CPD is on.
not on, bit IPENOA is ignored.

usé

|If bit

the

PID

set

IP¥CPD

Reserved for Digital.
| P%CFP

The packet
only

Refer
Manual

COMMUNICATION

IP%CFV

is privileged.

This bit can

process with WHEEL

the

TOPS-20

capability

Monitor

Calls

for

a description of

this

The packet

is a page of 512

(decimal)

enabled.

Reference

bit.

words

data.

IPECFZ

Reserved

| PXEPN

24-29

A zero-length message was sent.
Digital.

Page
number
in
descriptor block
Reserved

IP%CFE

for

Field for

for

word
.IPCFP
of
is 18 bits long

the

packet

Digital.

error

code

returned

from

INFO.

Code

Symbol

Meaning

.IPCPI

insufficient

.IPCUF

invalid function

.IPCKM

PID has been deleted

.IPCSN

<SYSTEM>INFO needs name

.IPCFF

<SYSTEM>INFO

.IPCBP

PID has no name or

.IPCDN

duplicate

been

. IPCNN

unknown name has been specified

.IPCEN

invalid

privileges

free

name

space exhausted

has

been

invalid
specified

specified

INTER-PROCESS

Table 7-1:

Packet Descriptor Block Flags

Bit

Symbol

30-32

{PSCFC

(Cont.)

System and sender code.
but

|PECFM

FACILITY

Meaning

only by

33-35

COMMUNICATION

This code

a process with WHEEL

the

monitor

will

can

capability

return

the

set

enabled,

code

nonprivileged

process can examine

Code

Symbol

Meaning

]

.IPCCC

Sent

.IPCCF

Sent by system-wide <SYSTEM>INFO

.IPCCP

Sent by

.IPCCG

Sent by monitor for QUEUE% JSYS

by <SYSTEM>IPCF

receiver's <SYSTEM>INFO

Field for special

messages.

set

process

only

enabled,
that

by
but

Symbol

.IPCFN

This

can

process

return

the code

can examine

it.

Meaning

Process'
packet
to

7-5

code

with WHEEL capability

the monitor will

nonprivileged

Code

it.

input

that

intended

queue

could
PID.

not

contains

be delivered

INTER-PROCESS

7-3.2
Any

that wants

process

requesting
symbolic
The

can

that

name

symbolic

any

FACILITY

PlDs

process

The

COMMUNICATION

PID

that

name

characters

send

PID

obtain

be mutual

understanding

names

wused

order

defined,
character

Before

symbolic
sender

since

any
for

packet

must

packet

obtain

PID.

to <SYSTEM>INFO

process must
also
include
the assigned PID.

terminated

among

processes

initiate

referring

characters

and
can
contain
zero word.
There

communication.

that

name must

the

Once

specify

symbolic

the

name

exactly

character.

process
name

must

all

process

The

a maximum of

long

sending

associated with

should

assigned.

to be

can
as

receive

can
or

ask

send
PIiD.

packet,

only

<SYSTEM>INFO

communication

The association between

for

via
PID

the

and

On a RESET% monitor call.

When

the

When

request

must

know

receiver's

PID

the

name

associated

receiver's

known,

with

the

name,

PIDs.

process

it
the

name

killed

broken:

the job

to disassociate

the

logs

PID

off

from

the

system.

name

made

PID

to be

to <SYSTEM>INFO.
<SYSTEM>INFO will
assigned

will

again

not

<SYSTEM>INFO

protects

allow a

unless

assign

against

name

the owner

PID

messages

already
of

once

the

being

associated with
name makes

has

sent

been
to

the

used.

the

request.

This

wrong

Nor

action

receiver

accident.
The

PIDs

and

.IPCFR,

7.3.3
Word

the

Length
.IPCFP

beginning
types,

the

sender

And

Address

the

packet

address

depending

message

the

the message.

1000

address

the

sent,
is

placed

is
in

(octal)

specified

type

this

Packet

type

are

packet

|If

block

from

(refer

this

contains

the

length

specified

message

(refer

is,

the

length

7-6

long-form

and

the

one of

two

7.3.5).

I f

actual

word

message,

the

one page.

address

address.

Section

page

to Section 7.3.5).

address.

.IPCFS

Block

length

that

either

by words
block.

The

the message

words,

indicated

descriptor

Data

descriptor

of message

taken

receiver

the

short-form message,

length

the
of

the message.

length

The

and

respectively,

When

a message

number,

depending

When a message

received,

INTER-PROCESS

7.3.4

Directories and

Words

.IPCFD

was

sent

These

and

the

used

packet

message
for

.IPCFC

are

describe

not

the

supplies
if

words

the

packet

interested

does

knowing

The packet

data

The message

block

short-form message

half

right

block
and

it.

sender

space

block,

the

system supplies

the

reserve

packet.
these

directories

The

receiver

words

and

one

to n words

sent or

iif

not

capabilities.

being

long,

assumed

received,

the

process

the message

short-form message

actual
the

uses

the

.IPCFP

length of
of

received.

long-form message.

where

word

sent

first word

always

is one page

message

sent

1000
in

the

message

long-form message,

19)

set

error

defined by

When a

packet

the

the message

the

message

short

the

words.)

the

form when

the

sending

length

(1000 octal

received,

(octal)
the

in the

right

and

words).

.IPCFP

left half and

half.

send

the

and

receiver must have

When

the packet

page

receive

|P%CFV

in the first word of the packet descriptor block,

or else

the sender

word

bit

code

both

number

returned.

SENDING AND RECEIVING MESSAGES
send

words

a message,

the

packet

MSEND% monitor call.
to

the

receive

four

intended

the

and

system will

fill

the

packet

the

from

the

must

block.

receiving

first-message-in,

the

first

four

then

executes

the

this call,

the packet

the

process must

also

block.

The

last

sender

can be

After execution of

receiver's

process

is sent

queue.

descriptor

set

The

appropriate values.

the MRECV% monitor call.
retrieved

input

capabilities
in

process

After execution of

a message,

words

sending

descriptor

receiver's

directories

the

packet descriptor

ignored.

when a

descriptor block contains

and

reserved

sender

are

sent,

However,

contains

long-form message

7.4

message

sent

to <SYSTEM>INFO.

long-form

(bit

the

has

contains

the address

half.

messages

time

packet

sender's

(Usually,

short-form message
descriptor

the

can be either

installation.

left

they

receiver

have

the

to validate messages

Packet Data Block

7.3.5

not

sender

a message

them,

the

the appropriate values of
the

the

receiver

used when

received,

these

FACILITY

Capabilities

and

two words

COMMUNICATION

input queue.

first-message-out

71-17

set

the

two words

supplied,

and

The process

then

this call,

The

basis.

input queue

first

for

the

executes

packet
is

the

emptied

INTER-PROCESS COMMUNICATION FACILITY

7.b.1

Sending a Packet

The MSEND% monitor call is used to send a message via |PCF.
Messages
are
in
the
form
of
packets
of
information
and can be sent to a
specified PID or to the system process <SYSTEM>INFO.
Refer to Section
7.5 for information on sending messages to <SYSTEM>INFO.
The MSEND% call

accepts two words of arguments.

The

length

the

packet
descriptor block is given in ACl, and the beginning address of
the packet descriptor block is given in AC2.
Thus,
ACl:

length

less
AC2:
The

address

packet

packet descriptor

descriptor

packet
block

descriptor
consists

.IPCFL

Flags

. IPCFS

Sender's

. IPCFR

Receiver's

PID

. IPCFP

Pointer

packet

The

Section

data

flags

Table

7-2.

The

length

cannot

7.3

for

block

the

following

four words:

PID
to

message being

Refer

block.

than 4.

data

block

containing

the

sent.

the details

the

sending

packet

descriptor

and

blocks.

that

are meaningful

Refer

to Table

7-1

when
for

the

7-8

packet

complete

list

are
of

described
flag

bits.

INTER-PROCESS COMMUNICATION

Table 7-2:

Flags Meaningful

FACILITY

on a MSEND% Call

Bit

Symbol

Meaning

| P%CFB

Do not block process if no messages in
if

]

| PZCFS

| P%CFR

| PECFO

error

set,

return

queue;

no messages.

.IPCFS

is given in word .IPCFR

The sender's PID is given in

word

the packet descriptor block.

The receiver's PID

the packet descriptor block.

Allow the sender to send one message above its
send

IPETTL

quota.

Truncate

than

larger

message

space

reserved.

)

IP%CPD

| PZJWP

Create a PID for the sender and return

the packet descriptor block.
of
.IPCFS
word
The PID created is to be permanent and useable
by other processes according to the setting of
bits IP¥JWP and |P3NOA.

The
PID
created
is
to
be
job
permanent until the job logs out.
is not on,

until

the

the PID created

is to be

wide
and
|[f this bit
temporary

process executes the RESET monitor

call.

| PENOA

The PID created is not to

used

other

processes.

IP%ZCFP

The message being sent is privileged (refer to
the TOPS-20 Monitor Calls Reference Manual).

| P%CFV

The message being sent is a long-form message
The page the message is
page).
a
is,
(that
being sent to cannot be a shared page; it must
be a private page.

| PXEPN

Page number

word

.IPCFP

descriptor block is 18 bits long.

the

packet

INTER-PROCESS

When bit
word

IPECFS

L.IPCFS

IPZCPD
for

is on

the

is on

COMMUNICATION

in the flag word,

the packet

descriptor

in the flag word,

sender.

this

FACILITY

the sender's PID

block.

This word

indicating that a PID

case,

the

PID

created

IPZCFR

from

word

then

the

7.5
On

for

receiver

the

block

in the flag word,

the

input

updated with
continues

Word

sender's

the

execution of

the MSEND% call

error

returned

sent,

and

user's

program continues

7.4.2

Receiving a Packet

code

the

process'

input

Before

must

know

packet

queue.

the message

descriptor

packet

the

descriptor

1length

less
AC2:

taken
is

ACl.

retrieve

process

can

sent

descriptor

the

wuser's

the

MSEND%

call.

the message
The

execution

following

long-form message

block

packet

given

packet

ACl1,

and

AC2.

descriptor

block.

descriptor

block

7-10

Section

packet

after

successful,

than L.

address

the

not

the

the MSEND% call.

message

from

the

retrieve a message,

and

also must

accepts two words of arguments.

block

packet descriptor

AC1:

to
a

set

block.

The MRECVX monitor call
the

not

used

Execution

instruction

The MRECV%Z monitor call

call,

.IPCFS

location

(MSEND%)

in word

this word

Refer

bit

to <SYSTEM>INFO.

PID.

second

PID

|I|f

<SYSTEM>INFO.

the MSEND% monitor
queue.

the

block.

created

returned

the receiver's

descriptor

sending messages

execution of

receiver's

program

packet

the message

information on

successful

is on

.IPCFR of

zero

is to be

. |PCFS.

When bit

is taken from
is

the

The

length of

beginning

address

Thus,

The

length

cannot

INTER-PROCESS

The packet descriptor
The

last

values

five words

the

block

COMMUNICATION

can consist of

are optional,

sender will

and

filled

.IPCFL

Flags

. IPCFS

Sender's

. IPCFR

Receiver's

.IPCFP

Pointer

FACILITY

the

following

supplied by

in by

the

nine

words.

receiver,

the

the message

system.

PID
PID

to packet data

block

where

to be placed.

.IPCFD

Connected

. IPCFC

Enabled

. IPCSD

Number

. IPCAS

Account

. IPCLL

Byte pointer

Refer
packet

The

to Section 7.3
data

flags

Table

7-3.

for

and

logged-in directories

capabilities

sender's

string of

the

sender.

connected directory.
sender.

for destination of

the details

sender.

.the

sender's

packet

node.

descriptor

and

blocks..

that are meaningful

Refer

to Table 7-1

when

for

receiving a packet are described

the complete

7-11

list of

flag bits.

INTER-PROCESS

Table 7-3:

Flags Meaningful

Bit

Symbol

| P%CFB

COMMUNICATION

FACILITY

on a MRECV%Z Call

Meaning

there are

input

queue,

return

this

packet

error

bit

packets

not

code
not

arrives,

on,
if

the

block
the
the

receiver's

the process and
queue

process

the queue

empty.

waits

until

empty.

| PECFS

Use PID referenced

in word

.IPCFS as

| P%CFR

The receiver's PID

is given

in word

the

packet

descriptor

IP%CFO

Allow one send request above quota.
send quota is 2.)

IPYTTL

Truncate the message
block.

too

message

| PXCPD

reserved

|If

this

large,
is

for

bit

.IPCFR

block.

space

sender's

not

error

code

(Default

larger
the

and

than

the

packet

data

the

message

returned

and

received.

Create PID

for

sender

and

job

wide

return

word

. IPCFS.

| PZJWP

Make created
IP¥CPD set).

I PZNOA

Do not allow other processes
to
PID (ignored unless IP¥CPD set).

| PECFP

Packet is privileged
enabled)
.

| PXCFV

The message

message

| PXEPN

PID

(that

(requires

expected

1is,

being

stored

shared

page;

Page number

must

word
is

wunless

use

created

IPCF capability

page).

message

descriptor block

(ignored

long-form

The

page the

into

cannot

private

page.

.IPCFP

18 bits

long.

the

packet

INTER-PROCESS

The

information

the MRECVZ
sender

Word

the

.IPCFR

flag word,

in word

call

.IPCFS

the

supplied by
the

PID

packet

PID

then word

belonging

received
PID

are

values

The

any

-1

except

the

sender's

and

the

placed
packet

packet

monitor
data

descriptor

block.

ACl1

queue

the

left

packet

in the right half

(see below).

called

the

variable of

the

packet

the

there

1is

Execution

after
The

not
of

another
the

wuser's

for

flag

for

any

packets

PID

are

not

specific

sent.

not

Any

supplied

the

other

retrieved.

the

receiver,

the

left

half,

sender.

packet

associated

also

right

the

half

Word

These words

the
Word
and

.IPCFC
describe

sent.

the MRECV%

into

the

.|PCFR

returned.

packet

the

from

they were

the

the message was

execution of

and

when

packet

specified by

the

given,

connected directory

capabilities

time

.IPCFC

is on

from word

is not on

packets

to be

have been

IP¥CFR

receive
is

that

in which

logged-in directory

-2

code

.IPCFD

receiver

in the PID of the

taken

receive a

error

information when

the

order

the enablied

two words

On successful
. IPCFP

IP%¥CFR
-1,

-2,

these

contains

retrieved

order

the

in words

|If bit

packet

either

When

particular
in

sender

job.

cause

sender's

contains

process,

this word

fills

.IPCFD

the

this

information

system

this

the

retrieved.

|If bit

contains

received

receiver.

the

.IPCFR

the

system fills

the receiver.

receiving

FACILITY

supplied

The

the packet descriptor block.

word,

not

executed.

packet when

then

COMMUNICATION

call,

block

contains

half

and

the
the

packet

queue,

program continues

ACl1
the

by word

length

flags

the

from

the

ACl1

the queue.

This word returned
next

packet

indicated

contains

second

zero.

instruction

the MRECV% call.

flags

returned

the

the MRECVZ monitor call

right

half

are described

7-13

AC1

successful

in Table 7-4.

execution

INTER-PROCESS

Table 7-4:

COMMUNICATION

FACILITY

MRECV% Return Bits

Bit

Symbol

30-32

| P%CFC

Meaning

System and

sender

code,

privileged

process.

The

<SYSTEM>IPCF

packet

was

<SYSTEM>INFO
packet

IP%CFM

Field for
the

process'
to

the code
sent

the code

1(.IPCCC).

the

2(.IPCCF).
the

1(.IPCFN),

input queue contains
another

sender

PID,

because

but

The

receiver's

messages.

The

system-wide

return of special
contains

sent by

3(.IPCCP).

sent

the

only

field

was

code

was

<SYSTEM>INFO

33-35

the

sent

set

packet was

| f

then

the

packet

that

was

returned

could

not

delivered.

execution'of the MRECVX call is not successful,

retrieved,

user's

7.5

and

an error

program continues

SENDING

MESSAGES

The

<SYSTEM>INFO

performs

process

functions

assigning

can

process

PID

code

the

in
instruction

packet

not

ACl.
The execution of the
following the MRECV% call.

<SYSTEM>INFO

the central

associated

name or

request

returned

returning

functions

information

with

names
name

utility

and

for

PiDs,

associated with

performed

|PCF.

such
a

as,

PID.

<SYSTEM>INFO

executing
the
MSEND%
monitor
call
(refer
to Section 7.4.1).
The
message portion of the packet (that is, the packet data block) sent to
<SYSTEM>INFO

contains

total

to <SYSTEM>INFO

request

descriptor

block

and

the
packet

request
is

data

being made.
packet

block

7-1k

In other words,

consisting

containing

the

request.

the

packet

INTER-PROCESS

Packet

Descriptor

COMMUNICATION

Block

flag word

Packet

FACILITY

pointer

Data

to request

Block

code

function

Refer

function argument

to Section 7.4.1

descriptor
a

packet

7.5.1

block.

for

the descriptions of

The receiver's PID

(word

the words

.IPCFR)

in the packet

is O when sending

to <SYSTEM>INFO.

Format of

<SYSTEM>INFO Requests

As mentioned previously, the packet data block (that is,
the
portion) of the packet contains the request to <SYSTEM>INFO.
The first word

(word

half

function

and

the

.IPCIO)

contains a user-defined code

being

requested

user-defined code

is used

to associate the

with

request.

The functions

the

correct

<SYSTEM>INFO are described

in Table

7-15

the

right

response from
that

7-5.

the

process

message

in the

left

half.

The

<SYSTEM>INFO
can

request

INTER-PROCESS COMMUNICATION FACILITY

The second word

(word

.IPCI1)

contains a PID associated with a process

that
is to receive a duplicate of any response from <SYSTEM>INFO.,
this word is zero, the response from <SYSTEM>INFO is sent only to
process making

the

The third word

(word

specified
functions

Table

7-5:

request.

.IPCI2)

in the right half

depending on

|If
the

contains the argument
of word

the function being

are described

<SYSTEM>INFO

.IPCI0O.

for

the

The argument

requested.

The

function

is different

arguments

for

the

in Table 7-5.

Functions

and

Function

Argument

Meaning

+IPCIW

name

Return

Arguments

the

PID

associated

with

the

given name (refer to Section 7.3.2 for
the description of the name).
.APCIG

LAPCII

PID

name

Return

ASCIZ

the name

given

PID.

Assignh

the

associated

given

name

with

the

PID

associated with

the process making

request.

PID

The

the

permanent

the
if

IPXJWP was set in the flag
word
when
the
PID was originally created (refer
to Table 7-1).
JAPCHJ

name

Identical

ASCiZ

7-16

.IPClI

function.

INTER-PROCESS

7.5.2

Format

Responses
process
PID

from <SYSTEM>INFO
in word

the

are

the

request.

copy of

.IPCI1,

The message portion
contains

FACILITY

<SYSTEM>INFO Responses

that made

given

COMMUNICATION

(that

response

form of
the

a packet

sent

response

the

sent

the

packet

any.

is,

the packet data

from <SYSTEM>INFO.

block)

The

format of

this

response

code

]

S S T S S me e e v g

The first word
half

(word

and

These values

are

.IPCI0)

the

from

different

the

copied

from

function

depending

functions are described

Table 7-6:

Function

contains the

function

The second and third words
response

response

left

function

the

that

was

the values

(words

user-defined
requested

given

.IPCI1

requested

function

the

and

code
the

.IPCI2)
The

right

the
half.

request.

<SYSTEM>INFO.

requested.

contain

The

the

response

responses

from

the

in Table 7-6.

<SYSTEM>INFO Responses

Requested

.APCIW

JAPCIG

JAPCHI

Response

The

PID

the

request

associated with

The

name

the

request

returned

response

returned.

returned

associated

with

the

name

in word
the
in

PID

word

given

.IPCI1.
given
.IPCIl1.

INTER-PROCESS

7.6
A

PERFORMING

process

the

can

MUTIL%

request various

monitor

functions.

call.

creating and

the

functions

Some of

functions

deleting

PIDs,

These are described

The MUTIL% monitor call
argument

argument

block

can

for

are

in ACl1,

and

Calls Reference

the beginning

length

the

argument

describes

functions,

the

and

of
the

AC2.

following

different,

values

quotas.

privileged

address

the

are

Any

7-7

the

returning

the TOPS-20 Monitor

argument

arguments

Table

and

requested

format:

function code

requested.

returned

executing

The

has

The

accepts two words of argument.
in

performed

given

The argument block

to be

these functions are enabling and

that

Manual.

the

FACILITY

IPCF UTILITY FUNCTIONS

disabling PIDs,

Several

COMMUNICATION

for

block,

function

depending

resulting

from

starting

functions

the values

that

the

function

the

can be

returned

are

second word.

requested,

from

being

requested

the

the arguments

functions.

INTER-PROCESS

Table 7-7:

COMMUNICATION

FACILITY

MUTIL% Functions

Function

Meaning

.MUENB

Allow

the

PID

given

process

executing

the

PID,

receive

the

call

process

must

packets.
not

|If

the

the owner

privileged.

Argument

PID
Value

Returned

None
.MUDIS

Disable
If

the

owner

PID

given

process
of

the

from

executing
PID,

the

receiving

packets.

the call

process

must

not

the
be

privileged.
Argument

PID
Value

Returned

None
+MUGTI

Return

the

PID

associated with <SYSTEM>INFO.

job

number

Argument

PID
Value

Returned

PID
.MUCP|

Create a

<SYSTEM>INFO

private

specified
capability

copy

job.

The

<SYSTEM>INFO

<caller

must

for

have

the

|IPCF

enabled.

Argument

PID

to be assigned

PID

number

7-19

to <SYSTEM>INFO

job creating

private

copy

INTER-PROCESS

Table 7-7:

Function

+MUDES

MUTIL% Functions

COMMUNICATION

FACILITY

(Cont.)

Meaning

Delete
call

the

must

PID
own

given.
the

The process

PID

being

executing

the

deleted.

Argument
PID
Value

to be deleted

Returned

None

-MUCRE

Create a

PID

the

number

given

the

call,

the

flag

bits

job

executing

for

privileged.

the

The

process

are IP%JWP and IPYNOA
their descriptions).

not

job

that of

given.

the

process
that

(refer

must

can be

I f

process
be

specified

Table

7-1

for

Argument
flag

bits

handle

in
job

the

left

number

half,

the

and

right

process

half

Value Returned
PID

+MUSSQ

Set

that was

send

PID.

and

The

enabled.

18-26,
bits

receive quotas
caller

The

new

and

the

27-35.

The

specified
job

created

PID,

to which

for

have

the

send

quota

receive quota

the
PID

specified

|IPCF

new

receive quota

but

that

must

capability

given

applies

send quota

bits

is given

applies

in
the

the

associated with

the

belongs.

Argumemts

PID
new

.MUFOJ

Return
PID

quotas

the

number

the job

given.

Argument

PiD
Value Returned
Job

number

associated with

7-20

PID

given

INTER-PROCESS COMMUNICATION rne..

Table 7-7:

MUTIL% Functions

(Cont.)

Function

Meaning

MUFJP

Return all

PIDs associated with

the job given.

Argument

job number
Values

PID

belonging

to the job

Returned

Two-word

entries

the job.

for

each

PID

The first word of

belonging

the entry

the

PiID, and the second word has bits IP%JWP and
[PENOA
set
if
appropriate (refer to Table
7-1 for the
descriptions
of
these
bits).
The
by

.MUFSQ

1list

Return
the

entries

returned

terminated

a zero word.

PID

the send quota and

the receive quota

for

given.

Argument

PID

Values

Returned

Send quota in bits
in

MUFFP

bits

Return all
the

PID

18-26 and

receive

quota

27-35.

PIDs

associated with

the

process

belonging

given.

Argument

PID

Values

Returned

Two-word entries
the process.

for each PID

The first word of

the entry

the PID, and the second word has bits |PZJWP
and
|IPZNOA
set
if
appropriate
(refer to
Table 7-1

bits).

for

The

the

1list

descriptions

entries

these

returned

terminated by a zero word.
+MUSPQ

Set

the maximum number

specified

job.

The

capability enabled.
Argument

job number

PID quota
7-21

PID

PIDs

caller

allowed

must

for

have

the

|PCF

INTER-PROCESS

Table

7-7:

Function

-MUPIC

MUTIL% Functions

COMMUNICATION

FACILITY

(Cont.)

Meaning

Place

the

specified

channel.
1.

PID

software

interrupt

then generated when:

The MUPIC

function

issued while

has

messages

one

the

its

PID

receive

queue.

The PID's
from

receive queue

empty

Subsequent
empty

the

from

The

calling

the

specified

to a queue

cause

number

its

and

its
a

state

message.

that

not

interrupt.

given

current

process

changes

containing

entries

not

channel

removed

-1,

the

PID

channel.

the

process

PID must belong

the

that

owns

same job.

Arguments
PID

-MUDF|

channel

number

Set

the PID

<SYSTEM>INFO

must

have

|PCF

<SYSTEM>INFO.
already

capability

has

error
PID.

given

The caller

enabled.

Arguments

PID

.MURSP

Return

of
a

<SYSTEM>INFO

PID

returned

The

system

from

the

system

PID

table.

word

the

argument

PID

table

currently

has

entries:
0

.SPIPC

Reserved

.SPINF

PID

<SYSTEM>INFO

for

Digital

J.SPQSR

PID

QUASAR

.SPMDA

PiD

QSRMDA

.SPOPR

PID of ORION

Argument

index

into system PID

7-23

table

the

The

PID

block.

following

INTER-PROCESS COMMUNICATION FACILITY

Table 7-7:

MUTIL% Functions

(Cont.)

Function

Meaning

MUMPS

Return the

PID

the

for

size

packet

maximum

given.
Argument

PID

Value Returned

PID

Maximum packet size for

. MUSKP

Set PID to receive deleted PID messages.
Allows
a
controller
task to be notified if one of its
subordinate tasks crashes.
After this
function
is
performed,
if
the
subordinate PID is ever
deleted
(via
RESET
or
the
.MUDES
MUTIL
function), the monitor will send an IPCF message
to the controlling PID
notifying
it
that
the
subordinate
PID has been deleted.
This message
contains
word

.IPCKP

in word O and the deleted PID

Argument

Source
Object
. MURKP

(subordinate) PID
(controller) PID

Return controlling PID for

this subordinate PID.

Argument

Source
Object

On successful

completion of the

requested

performed,

block.

Execution of

and

the

(subordinate) PID
(controller) PID (returned)

MUTIL%¥

any value

wuser's

monitor
is

call,

the

returned are

continues

program

function

the argument
the

second

location following the MUTIL% call.

If execution
requested

the

function

Execution of

the user's

MUTIL%¥

monitor

performed and

call

error

code

the

location

program continues

the MUTIL% call.

7-24

not

successful,
returned

no
ACI.

following

CHAPTER 8
USING

EXTENDED

ADDRESSING

The term "extended addressing''

that

TOPS-20 uses on

refers to the
size
of
the
addresses
the DECSYSTEM-20 Extended KL10 processor.
Older

versions of TOPS-20 (Release L.l and before)
used
18-bit
newer versions (Release 5 and after) use 30-bit addresses.
This

chapter

discusses

TOPS-20 monitor
1.

two main activities associated
extended

Writing new programs
other

than

section

other

than

also contains

for

this

sections

memory

that

they can be executed

description

the

processor

way

individual

depends

Processor
of

uses

machine

the

information on

chapter

algorithm

8.1

hardware

to MACRO programmers who use extended

DECsystem-10/DECSYSTEM-20

that

execution

programs

useful

wusing

section O

sections

The discussion
manual

for

with

addressing:

Converting existing

This chapter
macros

the

calls with

addresses;

heavily on

instructions

the material

Reference Manual.

format

30-bit

to calculate effective

and

addressing.
in

the

that

addresses,

the

Refer

addresses,

and

the

instructions work.

OVERVIEW

The TOPS-20 extended address space
contains
32
(decimal)
sections.
Each
section
contains
512 pages of 512 words each (256K words).
An
18-bit address, called a local address, can reference any
word
in
a
given
any

section.

section of

30-bit,

memory.

global,

address

can

reference any word

USING

In contrast,
address
each

TOPS-20 VL.l

space.

The

EXTENDED

ADDRESSING

and earlier

provided

Program Counter

instruction executed,

(PC)

18-bit,

the first action

taken was

256K-word

18 bits.

the

For

computation

of
an
18-bit
effective
address.
The algorithm for calculating the
effective address (including indexing and indirecting rules)
was
the
same

for

Because
and
are

all

instructions.

the TOPS-20 virtual

section

numbers

effectively

view this
From

the

address

longer

limited

32-section address

space

than 5

bits

are

bits.

When

space as one

point

view

program

divided

into

discrete

sections.

than one

section of memory,

limited

sections,

legal

addresses

addressing

data,

large memory

area.

execution,

illegal,

however,

you

can

memory

program can have code

in more

and it can execute that code (assuming the
discussed below), but it must change sections explicitly,
as discussed below.

constraints

Compatibility
program

for

running

system

instructions
specific

existing
in

section

without

such

programs
0

extended

XJRSTF.

instructions,

see

provided

though

were

behaves

addressing,

For more

the

section
for

certain

the actions of

DECsystem-10/DECSYSTEM-20

Processor

Reference Manual.

8.2

ADDRESSING MEMORY AND ACS

The

extended

format

word-within-section
word

field

word

executed,

field
and

fetched

change

incremented.

section O

the

Column

not

jump

explicitly,

and

contains

only

to another

When

section

from word O of

sections

instruction,

field.

section

|If

the

instruction,

only

the

never

carried

then

the same section.
of

XJRST or

XJRSTF

8-2

and

executed,

last word

by means

section.

field

instruction

overflow

field.

executed

except

information on

being

the

Thus

PUSHJ,

JRST,

can

from

the

section

instruction

program can only
XJRST or

change

XJRSTF

control

from

USING

Because

a whole word

flags,

the

cannot

and

flags

first word,

and

the

Figure 8-1

EXTENDED ADDRESSING

contain

30-bit

address

are a

two-word

entity.

figure

below

represents

and

The

the

program

flag bits

the

are

second

shows the format of the address fields of the PC.

un-

section

word-within-

used

number

section

Figure 8-1:

word.

Program Counter Address Fields

The word (word-within-section) field consists
of
18
bits
and
thus
represents
a
256K-word
address
space similar to the single-section
address
12

space of

bits,

section
of

numbers

the

only

releases.

determine

the

The

the

Most

field

section

running

calculated

section.

Monitor
The

this

Calls

program

unless

The

zero.

each

section
the

not

available

cannot

global

local

Chapter

Reference

Manual

for

from

section
call

monitor

0O
or

running

section

program
when

(18 bits).

memory

pointers
1

in.

addresses),

address

byte

Refer

monitor

running

(including

section

just

the

program

are

(One-word

bits

room

section.

rule.

uses

because

seven

provides

allow

to be

cannot jump

field

nonzero

leftmost
This

considered

number
be

512 words,

facilities

quantities

are

can

256K words.

features

program executing

exception

zero,

A1l
0,

protection

addressing

section

illegal.

into pages

paging

and

section

other

divided

The

five bits

must

each

contains

section
from

are

determines what

field

extended

field

The

existence

section

earlier.

right-hand

sections,

further

earlier

and

than

number

separate

section

the

greater

section

address

Each

release

which

the

any

are

TOPS-20

information.)
to
the

another
XJRST

section
or

XJRSTF

instruction.
3.

The

program

extended

the

section

inclusive,

runs

field

the

contains

program

other

than section 0).

bits,

and

the

exactly

it would

run on

a machine without

addressing.

number

executing

The hardware

program can

use extended

8-3

from

nonzero

considers
addressing

section

addresses
features.

(decimal)

section

USING EXTENDED ADDRESSING

A local address is defined as an 18-bit address in the same section as
of the instruction.
(PC)
the program counter
is
relative to the PC section. - A global address

which therefore supplies

its own section number.

The following paragraphs

explain

calculated

the

way

Local addresses are
a 30-bit address,
addresses

effective

are

In addition, see the description in

nonzero sections.

the DECsystem-10/DECSYSTEM-20 Processor Reference Manual.

8.2.1

Instruction Format

The format of a machine instruction
The effective address
machine.
field (Y, 18 bits), the index field
Figure 8-2 shows
field (I, 1 bit).
0

and

indirection,

13 14

17 18

Instruction Word Address Fields

Figure 8-2:

is the same as on an unextended
calculation depends on the address
and the indirect
4 bits),
(X,
these fields.

are

the

instruction

uses

neither

address is Y (18 bits).

effective

indexing

nor

The section

the
from
taken
number, since it is not specified in the address, is
section field of the PC.
The PC section field contains the number of

the section from which the instruction was fetched.

address

is called a

local

Such

18-bit

X and Y

fields

address.

The following is an example of an instruction whose |,
evaluate to an 18-bit effective address.

3,,L400/

MOVEM T, 1000

The effective address is
word
1000
of
the
current
section.
The
section
from which
the
instruction is fetched is section 3, so the
instruction moves the contents of register T into memory word 3,,1000.

8-4

USING

8.2.2
The

ADDRESSING

Indexing

first

the

EXTENDED

step

field

the effective address

1is

nonzero,

effective address
register.
e

then depends on

Indexing may be
|f

the

indexing

left

half

local
of

used.

global

index

indexing.

the

specified

address.

This

formats

section

index

the

not

the

half

the

to yield

index

contains

negative

that

addresses

field

the

than

field

contains

word

index

refers

contain

Note,

global

less

indirect

and

unextended

usual

AOBJN

stacks

that

however,
a

machine.

pointer

are

that

positive

and

stack

the

same

the

left

half

number,

contains

the

results

positive

address.

instructions can
means

can

Indirection

the

contains

30-bit

instruction

8.2.3

done on

index

reference
register.

the address

positive

30-bit

(global)

|If

field

The

the Y

contained

negative

offset

2A17.

the

fetched

from

instruction

specifies

the

determined by Y

address

indirection.

and X.

types of indirect word exist, Instruction Format Indirect Word
and
Extended
Format Indirect Word (EFIW).
They are described
following

18-35)
18-bit

contents of bits 6-35 of the register are added

This means
the

is
use

tables

left

program.

same.

magnitude

the

for

the

number,
to Y

indexing

program

pointer

are

the way

allows

the

follows:

number
or
zero, the contents of the right half (bits
are added to Y (from the instruction word) to yield an
local

| f

The calculation of

the contents of
or

the

calculation

section.

8-5

Two

(IFIW)
in the

USING

8.2.3.1
Y,

EXTENDED

Instruction Format
and

fields

instructions

(in bits

bits

not

2-12

are

the

13-35).

(IFIW)

same size and

Bit O must be

instruction format

012

(not used)

Figure 8-3:

Indirect Word

Note

that

this

and

the default

fetched.

This

course of

default
was

section

word

Indirect Word

original

means

that

effective

section

for

the

always

any

with

the

instruction.

local

section

the default

address

the

!
!

Indexing

local or global depending on the
indirection can also be specified.

indirect

quantities

can be

Further

O0;

for

the

Instruction Format

addresses

from which

section

calculation

section

left

can

that

the

contains

shows

Extended
Y,

Format

and

extended

Figure 8-L:

Indirect

fields,

format

o1t

but

Word
in

(EFIW)
different

itself

Extended Format

Indirect Word

8-6

from
was

the
The

last

format.

address word

word
Figure

(word)

the

indirection.

indirect word.

(section)

during

- This

<mmmmmmemmmee- R

can be

produced

change

uses

from which

half

the word

fetched.

8.2.3.2

must

calculation continues

index.

this

specified

and bit

just

contains

the same position as

indirect word.

The effective address
word

- This word

used.

Figure 8-3 shows an

11101

ADDRESSING

!
!

also
8-4

USING

indexing

contents
produce

local
on

of
a

specified
the

global

extended

space.

|If

further
is

indirect word

and

its

indirect word
register
type

address
register

space,

just

indirection

fetched

ADDRESSING

are

(bits
added

2-5 nonzero),
to

the

can

from Y

never

calculation used

does

specified

done

specified

the

(bit

as modified by

instruction

interpretation does

30-bit

indirect word

can be used as an address or an

address

indirect word

index

Hence either Y or Y(X)
the

This

type

the

this
index

address.

The

the contents

entire

address.

EXTENDED

1
or

the

produces

not

depend

field.

offset

within

18-bit

address

set),

indexing

format

not depend on

the

the
Y

(if

the

any).

The

extended

format of

format,

the

indirect word.

8.2.3.3

Macros for

Indirection - The system file MACSYM.MAC

several

convenient

macros

for

constructing

LFIWM generates

local

macros

GFIWM may be used

EP.

and

(instruction format)

contains

indirect words.

Macro

Both

to generate global

(extended

(octal)

the hardware

the

format)

indirect words.

8.2.4

AC References

local

memory.

address

global

refers
refers
1.

This

address
to

the

the range 0-17

true

section

hardware

to memory.

This

Addresses

every

the

ACs.

means

the

range

global

that

range

references

section of

the

0-17

ACs

memory.

1,,0

address

following

reference

1,,17
in

(octal)

any

other

behavior

ACs

also

section

occurs.

expected.

The

instruction

MOVE
fetches

what
2.

the

section

To make

contain a
3.

Arrays

hardware

instruction executes
reference

AC,

section

number

can

cross

any

never

incrementing
address

the

global

specifying
memory,

contents

2,3

section

section
to

the

7,,000000,

the

regardless

global

address

the

boundaries.

Global

always

hardware

ACs.

For

this

reason,

example,

yields

address

6,,777777,
a

memory

for

local

ACs from any section.

any

section will

yields
cause

to any section;

local

effective

code

executed

8-7

refer

location.

(0-17)

instruction which

addresses

section

which

the

must

except

The ACs are regarded as

references

in.

local

Hence,

address
from

address

a jump
0-17

the ACs.

USING

EXTENDED ADDRESSING

8.2.5

Extended Addressing Examples

These

instructions

make

local

references

within

the

current

section:

3,,400/
The

following

MOVE T,1000

; fetches from 3,,1000

JRST 2000

instructions

scan

s
table TABL,

jumps

which

to 3,,2000
in

the

current

section:
MOVSI

LP:

The
by

following
using

JRST

FOUND

AOBJN

X,LP

instructions

global

CAIGE

LP:

table TABL,

which

EP.

in current section

section

TSEC,

X,0

CAMN T,@[GFIWM TSEC,TABL(X)]
JRST

the

scan

: TABL

address:

MOVE!

LP:

Similarly,

X,-SiZ

CAMN T,TABL
(X)

;

X,SI1Z-1

AOJA

X,LP

macro

can

MOVE!

X,0

used

for

the

same

CAMN T,@[EP.<TSEC>B17!TABL
(X)]
JRST
CAIGE

AOJA

extended format

FOUND

FOUND
X,S1Z-1

X,LP

8-8

purpose:

USING

EXTENDED ADDRESSING

The following examples illustrate
various
aspects
indirection in effective address calculation:

indexing

and

L/100
6,, 1000/MOVE 1,82000
6,,2000/LFIWM @4000
6,,4000/LF
IWM 200 (4)

Effective address = 300 in section 6

6,,5SUB/

MOVE

1,@[LFIWM @2ZZ]

6,,ZZZ:
XXX

LFIWM @XXX
LF IWM ARRAY (4)

Effective address = ARRAY+100 in section 6

6/14,,ADDRX

11, ,ROU/MOVE
14, ,ADDRX:

1,@[LFIWM

LFIWM

(6)]

100

Effective address = 14,,100

8.2.6

Immediate

Instructions

Each effective address calculation yields a 30-bit address, defaulting
the
section
if
necessary.
Immediate
instructions
use
only
the
low-order 18 bits of this as
their
operand,
however,
and
set
the

high-order
produce

bits

identical

results

Hence instructions such as MOVElI

regardless of

the section

and CAl

in which they

are

executed.

Two

immediate

addresses.

instructions retain the section field of

their effective

These are:

XMOVE!

(opcode 415)

Extended Move

XHLL!

(opcode 501)

Extended Half Word Left to Left

8-9

Immediate

USING

8.2.6.1

XMOVE!

address

into

- The XMOVEI|
the

AC,

indirection

the

the AC.

address
The

used,

sets

number

This

bits

0-5

the

the current

instruction can

30-bit

to 0.

section

no
is

replace MOVEI

effective
indexing or

copied

from

when a global

needed.

subroutine

instruction loads

and

the

following example

list

EXTENDED ADDRESSING

<call.

the

shows

The

the use of

subroutine

same section as
XMOVE|

the

XMOVElI

section

the calling

instruction

XSEC,

but

the

argument

program.

AP,ARGLIST

PUSHJ P,@[GFIWM XSEC,SUBR]
The

subroutine

can

reference

the

arguments

with

the

following

instruction,

MOVE T,@1 (AP)
To construct
following

the

addresses of

arguments,

the

subroutine

can

use

the

contains

the

instruction.

XMOVE| T,@2 (AP)
The

last

argument

the

two

instructions

assume

list

pointer.

the

IFIW,

<calling

EFIW,

argument

placed

section

program.

the

block

the

|If

section
is

list would be
address

global

determined by
|IFiW

used.

8.2.6.2

the
used

XHLL!

accumulator

right

the calling

the

effective

the address

the

effective

section

number

the

calling

placed

address is that
of
program placed in AP

number

program

address

the

calling

the

program

AP.

the

EFIW

number

determined

The argument

that

address

half

The

caller,

and

the

arglist

addresses.

8.2.7

Other

This

the

caller's

section

implicitly
pointer,

the

section

the

because

effective

same

address

the caller

explicitly

given

instruction replaces the left half

section

the AC.

global

AP.

- The XHLL!

with

found

number

the

instruction

PC,

and

wuseful

places

for

zero

of
is

if
an

the

constructing

Instructions

The

instructions discussed here are affected by
extended
addressing,
not
necessarily
in
the
way that their effective addresses are
calculated.
In addition to
the
material
presented
here,
see
the

but

DECsystem-10/DECSYSTEM-20
following

instructions:

Processor
LUUOs,

BLT,

SFM.

8-10

Reference
XBLT,

XCT,

Manual
XJRSTF,

regarding
XJEN,

the

XPCW,

USING

8.2.7.1

Instructions that

PUSHJ,

POPJ,

flags.

POPJ

EXTENDED

JRST.

sets

restores

bits

0-5

30-bit

PC - These

30-bit

the destination word

address

from

stack,

but does

JSA and

JRA

instructions

can be used only within

the

JSP and

instructions

transfer

out of

store

flags,,PC

section

nonzero

the destination word

(if

8.2.7.2

Instructions - PUSHJ,

Stack

instructions

according
address

the contents

govern

local

indexing

8.2.2.)

stacks.

when

or
in

with

address

use

local

the

local

address

current

decremented

the

left

half

and

the

the
in

instructions

can

transfer

any

into

indexing

POP,

address

and
for

ADJSP.

the

stack

Whether

the

rules

those

(See

stack
that

section

instruction when working

section and will

indicate

occurs.

stack
its

stack.

adding

restore

calculation.

any

not
to O.

then

with

same

pointer

decrementing),

the address

in
by

section.

can

pointer.
on

PUSH,

global

address

instruction works

incrementing

item

POPJ,

are

stores

flags,,PC but

JSR

then

always best to use the ADJSP

This

(prior

and

stack

effective

store

specified

depends

pushdown overflow error

In brief,

global

can

The JSP

sections

other
section
indirection)
.

These

the

The

JSR

0-5

but

to O.

cannot

bits

instructions

address,

flags.

sets

the

stores

the

section

also

Affect

PUSHJ

ADDRESSING

right

The

half

stack

subtracting

zero

negative

the pointer references a
is

the address

pointer
one

the

incremented or

from

both

sides,

respectively.
If

the

taken

left
as

and

stack

that

routines

protect
after

global

the

must

Both

global

calls

from

one-word

further

global
The

stack

pointer

The

stack

positive,

pointer

addresses

global

can be

stack,

used

however,

overflow and

inaccessible.
room

for

underflow,

This

and

either

local

nonzero

global

count

one-word,

byte pointers

sections

byte

information.

can

make

method must
the

left

half

Instructions - To reference a byte

use

the

entire word

incremented

the

same

contain

adding

but

pointers

are

there are

from

two-word,

the
be

pages

before

used

because

the

pointer.

another

global

section,

byte

pointer.

monitor

legal

arguments

some

restrictions

section 0.

way

pointers

sections.

stack

has

stack

subtracting
1.

used.

against

Byte

you

in other

stack

8.2.7.3

the

address.

contains

stack

decremented

local

and

half
global

the use

See Section 8.3

for

USING EXTENDED ADDRESSING

Chapter 1 of the TOPS-20
ohe-word
global
byte

Monitor
Calls Reference Manual
describes
pointers.
The DECsystem-10/DECSYSTEM-20
Processor Reference Manual describes two-word global byte pointers.

8.3

USING MONITOR CALLS

|f a program runs
section
0,
section 0.
current

section

The GTFDB% call,
the

in a single section,

block

for example,
which

section

the monitor

address

process

that makes

same

local,

is
is

number

from

arguments

that section

not

call

it obtains

18-bit

address

from.

the

When

from the file data

regardless

the monitor

section number

from

sees

what

that

the

|If

9-bit

the call.

true of

calls
as

the

the data

is made

passed

are

requires that AC3 contain the address of

to store

This address can be

number

though

the default.

block.

The

even

most
monitor
calls
execute
exactly the way they do in
This is because when no section number is
specified,
the

that

an
the

page

argument,
process

discussed

numbers.

the monitor

that made

Chapter

the

obtains

call.

the

page

section

Monitor

calls

the TOPS-20 Monitor

Calls

Reference Manual.

sometimes

desirable

specify

addresses

section

when

executing
a
JSYS
from a nonzero section.
The bit PMY¥EPN for PMAPX,
and FH¥EPN for JSYSs that accept fork
handles,
prevent
the
current
section
(the
section
in
which a program is running) from being the
target

section

Another

other

which have
Universal
have

the

Thus monitor
pointer

byte

same

format.

calls

that

called

any

calls

arguments.

passed

to monitor

concerns

universal

B5XXXXX,,XXXXXX
are not

existence of

other

either

byte

O do not

can

either

not

one-word

universal

(.DVDES).
This

pointers,

which

universal

byte

used

byte
device

such

Conversely,

device

global

section 0.

device designators,

in any section.

that

pointers

executed

bXXXXX,,XXxxxx
except

global

Other

wused

calls

device designators,

a device designator

section

section.

can

legal

one-word

accept
from

(0,,hkxxxxx),

monitor

call's

section 0

format

the

when

designators

.TTDES

than

device designators

because of

can

the monitor

restriction on arguments

sections

for

designators

pointers

these
or

section

The calls SIR% and RIR% should not be
section

These

associated with
that makes

these

the call.

calls work
calls

in other

exists

the

sections

sections
same

only

section

other
all
as

the
the

than
code
code

USING

For example,
correctly

EXTENDED

if an SIR% call

and

only

interrupt-processing

ADDRESSING

is executed

the code

routines,

and

section

that

generates

all

associated

L4,

the

executes

interrupts,

tables

are

the
also

located
in section 4.
Thus, in programs intended to run in a section
other than section 0, the XSIR% and XRIR% calls, described in
Chapter
L,
should
be
used
in
place
of
SIR% and RIR¥.
|In general, it is
recommended

that

form works

8.3.1

the

any

extended

section,

form of

including

monitor

calls

used

since

this

section 0.

Mapping Memory

The PMAP% monitor call accepts an 18-bit page number, half of which is
a
section
number.
Thus
PMAP%
can
be used to map a page from one
section

to another.

section will

|If

The SMAP% monitor call
like

the

the destination

PMAP

but

the

sections

algorithm

that determines

section

process

the

access

equal

not

exist,

maps one or more sections of memory.

call,

maps

sections

destination section does not exist,
Access

section does

that

be created.

page

privileges

are

page

gains

the ANDed

For example,

SMAP¥ creates

process map

access

the

and

to a
that

determined

given

has

works
|If

the

The

|If

accesses,

process

access

same

section.

have different

together.

only

pages.

the section.

page within
section

ANDed

access

instead of

requesting

rights

least

protections.

if a process has read access toa section and maps a page

into

that

section

page

is mapped,

for which

but

the

process

gets

has

only

read

and write access,

access

the

mapped

page.

The following sections describe the SMAP% functions.

8.3.1.1

Mapping File Sections to a Process - This function

sections

source

sections

mapped

pages

a file

are mapped
is

call
pages.

files

views
Each

multiple of

determined

and the access specified
Although

not

actually

having

section

process.

All

the destination
by

ANDing

the

pages

that

sections.

access

maps

exist

Access

allowed

the

one
the

the
file

in the SMAP% call.

them
file

have

section boundaries,

sections

starts with

512.

8-13

this

that

consist

512

page

number

that

monitor

contiguous
an

integer

USING

This

call

cannot map a

process

section

section
This

EXTENDED

ADDRESSING

process memory
a

file,

use

section
the

function of

the SMAP% call

AC1:

source

AC2:

destination

AC3:

flags,,count

The

flags

the number

identifier:

determine

between 0

requires

and

of
37

8.3.1.2

access

contiguous
(octal).

maps
you

same

three words

means

exist

Allow execute access

B18-35

The number of

that

the

occur

and

SMAP%

call

pages

into a

section,

the

SMAP%

the

source

and

section

section map.

If SMZIND

is not set,
After

map.

This

(octal).

SMAP%

monitor
In

process

another

section

maps
in

all

the

pages

cause

the

SMAP% creates

the new

the destination

the

with

indirect
all

SM¥IND

pointer.

pages

that

the destination

pages

pages.

same

that

the

exist

section.

section

contain

ensures

contain

that

destination

source

section

SMAP% maps

count

process.

the destination

This

the

another

the

map

and

number

the contents

has mapped

section

Process - The

destination

arguments,

process

section will

and

contents

destination

pointer.

source

section

destination

after

the

one

the

The count must be

sections
1

the destination section using an

the

the destination

the

between

from

section

source

identical

section

map

follows.

BL (SMY¥EX)

The

source

Furthermore,
that

are as

Allow write access

corresponding

SMAPX creates

section,

to be mapped.

B3 (SM¥WR)

must

map

number

Allow read access

process.

This
will

flags

call

handle, ,process

the destination

sections

The

sections

section

B2 (SM¥RD)

can map one

section

you map

set,

fork

Mapping Process Sections to

also

addition,
the

JFN,,file

identifier:

number

source

file.

monitor

page-by-page.

follows:

call

to a

PMAPY

same

section,
to

be made

both

the

source

shared

that

occur

data.

section
section,

changes

using
changes

section's map do not cause any change in
section's
map.
Thus
after
a short time the source
sections might contain different data.

the destination
and

destination

USING

you

request

section,

shared

what

the

the
2.

|If

source

the

(SMZIND

not

contents

the

The outcome

section

source

co-owner

ADDRESSING

does

not

set)

to
of

the
the

is one of

exist,

the

destination

source

section

the following.

SMAPY

call

creates

the

private

section.

the

private

the

private

section

is mapped

pointer,

section

found
a

contains

file

the destination

to be

destination

process

ACl:

Source

is made by

means

that

nonexistent,

section,

the

pointer
a

until

private

three words of arguments

AC2:

Destination

AC3:

access

identifier:

number

fork

handle,,section

identifier:

flags,,the

source

indirect
the source

section,

The

flags

determine

The

flags

are

must

access

B3 (SMZWR)

Allow write access

BL (SMYEX)

Allow execute access

B6 (SM¥ IND)

Map the
is
the

destination
pointer.

created,

the

Once

the

through

number
number

sections

number

and

to map.

the

right

37.

the

destination

same way

section
the

indirect

destination

Count of

Allow read access

section

AC1

section.

follows:

B2 (SM%RD)

the

contiguous

be between

handle,,section

sections mapped,

AC3,

fork

number

half

section.

file.

AC3.

B18-35

a mapping

the

SMAP% follows

This SMAP%¥ function requires

The

and

section.

the source section map

section

section of

section,

established,

source

section

depends

executes.

section

pointer

happens

when the SMAP% call

EXTENDED

that

section
the

using

destination

section
map

source

indirect

section map

pointer
change

section

map

changes.

the number of contiguous sections

mapped.

8-15

causes
exactly

USING

EXTENDED

ADDRESSING

8.3.1.3

Creating Sections - Before you can use a nonzero

memory,

you

must

create

it.

not

exist

section of memory that does
instruction

that makes

the

reference

your

program

(that

not

AC2:

destination

AC3:

flags,,count

The

flags

the

The

determine

number

must

flags

access

left

and

half

the

through

fork

handle,,section

the destination

private

section,

sections

number

and

the

count

to be created.

This

37.

AC3

are

follows:

Allow write access

BL (SMZEX)

Allow execute access

B6 (SMZIND)

Create the section using an indirect pointer

B18-35

The number of sections
be

between

and

create.

37.

All

This

wunmap
of

the

section

cause

the

one

sections

SMAP%

monitor

contiguous.

section

contains

means of

more
are

the PMAP% call.

sections

memory

process.

The

lost.

pages mapped

unmapped

they were mapped.

number

created

Unmapping a Process Section - You can use the

contents

which

AC]

B3 (SMEWR)

the

Allow read access

8.3.1.4

mapped),

B2 (SM%RD)

are

not

contiguous

between

the

identifier:

must

call

nonzero

follows:

AC1:

count

fails.

This SMAP%Z function requires three words of arguments
AC3,

section

references

sections

Such

from a

file,

be written

pages must

this
back

mapped

function
to

the

file

does
from

USING

This

function

requires

EXTENDED ADDRESSING

three words

arguments

AC1

through

AC3,

follows.
AC1:

-1

AC2:

Destination

AC3:

8.3.2
You

identifier:

can

handle,,section

number

0,,count
The count

unmapped.

This

the

Starting A Process
use most of

programs

fork

that

exception,

run

the

and will

number
number

must

contiguous
be

sections
and

37.

In Any Section
calls

described

nonzero section.

not

between

start

Chapter

The SFORK® monitor

program

nonzero

control

call

section.

The XSFRK%¥ monitor call starts a process in any section of memory.
If
the
process
is
frozen (by means of the FFORK% call), XSFRK%¥ changes
the double-word

resume

PC,

but

the execution of

The XSFRK® call
ACl:

does

not

any

frozen

resume

execution

fork,

use

requires three words of arguments

flags,,process

the

the RFORK%

process.

call.

in ACI

through AC3.

handle

Flags:

SF%CON (1BO)

continue a process
If
SF%CON
is set,

that
has
halted.
the address in AC3

process

ignored

and

from where
AC2:

AC3:

address

half

section
Most

other

calls

local

AC3

set

address

the

to which

this

call

also starts a process
AC3

at which

continues

halted.

flags,,0

The XSFRK% call
left

the

it was

to zero and
you want

consider

address.
PC.

the

PC with

half
to

address with

The XSFRK% call,
zero

section O.

8-17

set

the

in section 0.

right

the process

To do so,

AC3

the

set the

the address

left

start.
a

zero

however,
the

1left

uses
half

half

the contents of
indicates

USING

8.3.3

EXTENDED

Setting the Entry Vector

In Any Section

The SEVEC% monitor call

has room

half-word

address,

address

hand,

wuses

for

the

any

section of

length

for

length

AC3:

address
of

The

set

XSVEC%¥

ACs

call,

can

specify

only

entry vector

the

and

another

entry vector

the entry vector,

and

for

process

requires three words of arguments

AC2:

section.

the address

argument
to

other

memory.

process

length

its
used

the entry vector,

AC1:

words.

cannot be

nonzero

The XSVEC% call

The

ADDRESSING

the
AC2

in AC1

through AC3.

handle

the

entry vector,

the beginning of

the

entry vector

specified

contains

TOPS-20

entry vector
AC2 must

assumes

less

default

than

length

1000
two

words.

8.3.4

Obtaining

Although
of
the

the monitor

memory,

section

Information About a Process
calls

several

in which

monitor

they

calls

described

them

are

executed.

you

can

use

can

Chapter

5 work

only

return

The

following

to obtain

any

information

section
about

paragraphs

information

about

any

memory.

8.3.4.1
about

Memory
memory

Access

are

Information - Several

important.

Among

kinds

them are whether

of
a

the

describe
section

information

page or

section

exists (is mapped), and, if so, what the access to a page
is.
The RSMAP¥ and XRMAP% calls provide this information.

The RSMAP% monitor call

reads a section map,

about

information

one

the

mapping

section

RSMAPZ requires one word of arguments
left
access

half,

and

information

section
in

AC2.

number

the

in ACl:
the

and provides

address

space

a fork

right

half.

handle
It

section

process.

returns

the
the

USING

The map

information
-1

EXTENDED

ADDRESSING

that RSMAPZ returns
nNo

current

in ACl

mapping

present

exist)
the mapping
where

n,,m

is
a

private

fork

section

handle

the mapping

JFN,

The access

information bits

returned

B2 (SM%RD)

Read

B3 (SM%WR)

Write

Bl (SMXEX)

Execute access

B5 (PAZPEX)

The

section exists

B6 (SMXIND)

The

section was

Although
pages,

from

access

data

the XRMAP% monitor

does

it does

section

does

not

|If

JFN,
n

and
a

the

mapping

file

section.

handle,

shared

indirect
fork's

fork

section.

shared

in AC2 are the following:

is allowed

access

the RSMAP% call
the

(the

to another

mapping

the following:

section

number.

mapping

can be

allowed
is

allowed

created
not

return

using an

return

useful

call.

8-19

indirect

pointer.

information
on
individual
in preventing error returns

USING

The XRMAP% call

EXTENDED ADDRESSING

returns access

information on a page or group of pages

in any section of memory.
Although the RMAP% call returns access data
about a page in the current section, and you can use the RSMAP¥ call
in any section of memory,
you must use the XRMAP% call to obtain
information about pages

The XRMAP% call

process

AC2:

address of

The argument block

The

number

groups

number

pages

the

the monitor
Note

that

section of

will

addressed by AC2

fail

the

which

this group on which

first

return

that

you want

data,

page

the access

to which
already

illegal

argument block

three arguments:

address

memory

with

for

the

the following format:

======s=====ssscsszsss==s==s===s===
including

words

has

the argument block,

pages

requires

number

and AC2.

the argument block

pages

in AC1

handie,,0

Length of

than the current section.

requires_two words of arguments

AC1:

|
!

in any section other

access

the
the

three

number
group,

this word

!
!

return data

times

plus

of
and

pages
the

number
Each

the

address

group

group,
at which

data.

the monitor

returns

data

exists.

not

memory

the

one.

|If

reference.

8-20

does

should
exist,

the

call

USING

The access
the

information

argument block

B2 (RM%RD)
B3 (RM¥WR)
BL (RM¥EX)
B5 (RM¥PEX)
B9 (RM%CPY)
For

EXTENDED

returned for
the

ADDRESSING

each

group of

pages

specified

following:

read access allowed
write access allowed
execute access allowed
page exists
copy-on-write access

each page specified

the argument block

that

does

not

exist,

XRMAP%
returns
a -1.
It also returns a zero flag word for each such
page.
The data block to which XRMAP% returns the
access
information
should
of

therefore

pages

contain

about which

twice

you want

as many words

the

number

groups

information.

If you execute an XRMAP% call to obtain information about a page in
a
nonexistent
section,
the
XRMAP%
call
fails with an illegal memory
reference.
For this reason it is recommended
to execute an
RSMAPY
call
to determine
that
the section exists before you use XRMAP% to
obtain

information about any page within

8.3.4.2
process
returns

the

length
in

The XGVEC% call
fork

8.3.4.3

for

the entry vector

and

that

the

you want

the

allows

program

program has

program

can

continue

and

XGTRP% call

the

a program

the

base,

the

address

the

Reference

to determine

instruction

to correct
corrected

the handle

the

cause

that caused

the

described

Manual,

cause

the cause of

the

the
the

in the

contains
of

page

trap.

This

page-fail

trap,

monitor's

data

execution,

obtains the page-fail

returns

in ACl1,

the entry vector.

Processor

Once

The XGTPWX call

and

Information - A page-fail word,

address of

information allows
trap.

AC2

requires one word of argument:

which

Page-Failure

information

AC3.

DECsystem-10/DECSYSTEM-20
trap

section.

Entry Vector Information - To obtain the entry
vector
of
a
in
any
section
of
memory, use the XGVEC¥ call.
This call

entry vector

the

that

word

the calling

from

program's

requires two words of arguments

AC1:

process

handle

AC2:

address

the block

in which

8-21

in AC1

the

address

and AC2.

return data

space.

The

USING

8.3.5

EXTENDED

Program Data Vectors

Program Data Vectors
known

(PDVs)

the monitor

are data structures

name

and

location.

about

the program segments within a

data

that

LINK writes

The PDV resides

program

data

in memory as

vector

to obtain

information

into

process.

PDVs

monitor call.
a

(Refer

complete

monitor

call

part of

address
and

the

about

program,

PDVs

other

description

the

to obtain

and

programs

Calls

PDVOP% monitor

block
of
program.

to allow user

that

are

information

starts

are used

are manipulated

to the TOPS-20 Monitor

can be used

contain

The PDV is
a
loading and linking

(PDVA).

PDVAs

in a process that

They

process.

into memory when

programs

for

ADDRESSING

can

using

be mapped

the

PDVOP%

Reference

Manual

call.)

PDVOP%

information about

The

execute-only

process.

Certain words

information.

These

the PDV

Sections 8.2.3.1
and

any

pointed

chain

This

example,
are

and 8.2.3.2)

indirect

accumulator.

(for

words

PDV word

point

|IFIW or

except that they

pointed

allows

.PVNAM)
either

cannot

to by

the word

the

program

find

simply using

use

cannot

of
(see

indexing,

address

XMOVE!

blocks

EFIW format

through

block

instruction.

For

example,

XMOVEI
puts

into AC1

the

global

AC1,@.PVNAM(AC2)

address

the

name of

the

PDV whose

PDVA

specified

in AC2.

8.3.5.1
word

Manipulating PDV Addresses - For

.POPHD

monitor
in

call

words

Reference

The

any

.POADD

for

given

the

process.

.POREM function of
the

the

the
the

ones within

process

function of the PDVOP%
range of addresses specified

argument

in the
the

.POADE

the

PDVOP¥

block

PDVAs must be

block.

TOPS-20

argument

(See

Monitor

block.)

The

determines which

monitor

range

for

the

Calls
address

PDVAs

8-22

adds

system's

data

ascending

order

the
base

are

call

removes

a set of

process.

Those

by words

.POADR

PDVAs
for

within

specified

block.

call

the

the PDVOP% monitor

system's data base

the argument

and

the
.POGET

call.

The

The
are

format

.POADR

block.

the

data

from

the

PDVAs within
.POADE

by words

function

specified
specified

all
and

block,

the PDVOP% monitor call

Manual

supplied

affected

argument

returns
.POADR

description of
range

the

and

the
the

PDVAs
removed

.POADE

—

PDV Names - The

returns

the

argument block must contain a valid

The

name

returned

The string

For

ASCIZ

.PONAM function of the

name

returned by

PDV

PDVA

.PONAM

the

placed

PDVOP¥

memory.
for

the one to which word

the specified process,

block all the PDVAs of
in AC3 points to
the
.POADR/.POADE words.

ADDRESSING

monitor

Word

the

specified

.PVNAM of

call

.POADR of

the

process.

the PDV points.

into the data block.

.POLOC function

returns

PDVs with the specified name.
PDV
name.
Function
.POLOC

the

data

The byte pointer
is
affected
by

The following rules apply to the assignment of PDV
names.
rules
are
followed, it is quite unlikely that two packages

to run

in the same process will

discover

a conflict

these

that want

in PDV names.

PDV names assigned by DIGITAL will contain the character "%"
at
the end
(or eisewhere).
No PDV names assigned by users
should contain the "%" character.

All

—

——

T S————

—

——

—— ——

———

——— —— O

St—

8.3.5.2

——

EXTENDED

—

USING

PDV names containing the character
for

"."

are

reserved

future use.

EE—

DIGITAL

The character "$" is reserved for a special use:
PDV names
of
the form stringlSstring2
are reserved for the special
class of use named by stringl.
this

Rules

and 2 still

apply

case.

As a general principle, avoid using PDV names that are
insufficiently
specific; use of such names invites conflicts with other packages.

8.3.5.3

Version Number - The .POVER function of

the

PDVOP%

monitor

call
returns
in
the
data block the version of a program in memory.
Word .POADR must contain a valid PDVA for the specified process.
The
version returned is the one that word .PVVER of the PDV contains.

—

. S

S—— A

S—

. — ——

——

A} Sii——_) S

—

For more information on program data vectors,

including

explanations

of
the static memory map (pointed to by word .PVMEM) and the symbol
table vector (pointed to by word .PVSYM), refer to
the TOPS-20
LINK
Reference Manual.

8.4

MODIFYING EXISTING PROGRAMS

Existing programs can be modified to run in
any
section
of
memory,
including
both
section
O and all other sections.
The sections that
follow discuss the changes that must be made to an existing program so
that

it runs

in a single nonzero section.

8-23

USING EXTENDED ADDRESSING

8.4.1

Data Structures

Stacks, tables, and other data structures used
contained words with an address in the right
left half.
The count
could be positive or
programs
ran only in section 0, and when the
evaluated for Effective Address calculation or
0,

in the past have often
half and a count in the
negative because all
contents of a word were
address use in section

only the right half was considered.

in all other sections, the entire word is considered to be an address.
If
the
left
half
of the word is negative, the left half is ignored
when the address is evaluated, and the address is local.
Thus
for
a
word
to
contain an address in the right half and a count in the left
half,

the count must be negative.

8.4.1.1
|Index Words - Be sure the left halves of index words
contain
a
nonpositive quantity.
To use the left half of an index register to
hold a count, the count must be negative.
|f the left half is unused,
it
must be zero so that the effective address is a local address.
|If
the left half contains a positive number, the indexed address will
be
global.

8.4.1.2
Indirect Words - To be
sure
that
an
indirect
word
in
a
nonzero
section
is evaluated as a local address, always set bit 0 of
the indirect word.
Argument lists that
produce
local
addresses
in
section 0, for example, will produce local addresses in any section if
bit

set.

8.4.1.3

Stack Pointers - As mentioned above,

pointers

must

contain

addresses.

count.

positive

section

8.5

2zero

negative number

number

in the

the left halves of stack

negative number
left half

the

to produce

is considered

1left half

is considered

local
be

a
to be a

number.

WRITING MULTISECTION PROGRAMS

Multisection programs,

programs

memory,

are

similar

sections.

They allow

interrupts

in any section of memory

arrays,

you

that use

than

single-section programs
to

and to write modules of

place

tables

needed

(See Chapter L4),

code that can

into a section of memory and executed.

8-24

one

that

run
for

section

in nonzero
processing

to use very

dynamically

large
mapped

USING

EXTENDED

ADDRESSING

In a single-section program, local addresses
and
byte
pointers
are
sufficient to specify any word or byte in the program's address space.
in a multisection program, local addresses and
byte
pointers
cannot
specify any word or byte in the program's address space.
Most monitor
calls use only one AC per argument, so passing
two-word
global
byte
pointers is not possible.
Thus, it is necessary to:
o

keep monitor

call

the code making
e

use global

use the global

arguments

the call,

arguments,

the same section of memory

form of

the monitor

call.

In many multisection programs it is not
necessary
to
keep
all
the
arguments
required
by
a
<call
in the same section as the code that
makes the call.
Global arguments are required, and they take
several
forms.
Chapter 1 of the TOPS-20 Monitor Calls Reference Manual gives
details

the use of

these

arguments.

The following program computes a file checksum by XORing the words
in
all
file pages.
The program is loaded into section O and maps itself
into section 1.
|t then jumps into section 1 to access the file
data
loaded

into section

15,

TITLE

COMPUTE

CHKSUM

SEARCH
SEARCH

MONSYM
MACEYM

JREQUIRE

SY&SIMACREL

sSTHAC .
i

FROGRAM

FILE

CHECKSUM

SHETANDARD
FOET

FILES

SUFFORT

ROUTINES

JSERR

s HEF INE

STANDARD

ACSH

CONSTANTS

FOIZE

STACK

§ !
TION
FHECTION

CHKRSUME

UNIVERSAHL

RESETX

TO
TO

Mafk
MAP

SFAGE

WITHIN

SHIZE

FRESET

CODE
FILE

DATSEC

INTO
DATA
FOR

INTO

FILE

DATA

PAGE

THE

WORLD

MOVE

P LTOWD

FRLSTZyFDRL

MOUVE
MOVED
MOVX

TL1y Do FHELFy
90O
sMar THIS FORKS SECTION O
T2 Do FHSLF
» » CODSECT
570 EXTENDED CODRE SECTION
TEySMZEDEMAWRI
SMAEX TEMAINDE L FINDIRECT POINTER

RDyWRyEX

SECTION

HSMOF7

EJEHLT
GETFILE

SETIM
TMEHG

ENTER

FUNEXFECTED

FILJFN

HAY

FATAL

FILE

FILE SPEC TO CHECKSUM: >
FPROMFT USER FOR
MOUX TLyGIRSHTIGIZOLD
T GUAFNG s0LD FILE
MOVE T2y PRIINy
» dFRIQUT SREAD FILE SF SO
GT JFN

FOET

EFRJIMPR
MOVEM

ERROR

HEEN

BALF T

T1yFILJFN

FILE

PUANNOT
FOAVE

FILE
FROM

TERMINAL

TELL

UBER

SFE

GET

FILE

FILE
JFN

MOUX T2y FLOCT N3G OFZREZIVOFZRD FREQUEST READ ACCESS
CHFENF %
FOFEN THE FILE
ERJMER BADF
L.
§CANNOT OFEN FILE TELL USER

AND

XJRET

LCOUSECy
y DOCHKED

FENTER

EXTENDED

8-25

SECTION

aAND

346

RIT

CHECKSUM

BYTES

USING
BRANFTL:

JSERR
T1«FILJFN

RLFNZ

THE

STORED

DNOCHKS:

MOVE
HRL

PAND

COIE

RUNS

Q1,02
T1,Q2

T1»FILJFN

FFUFF%

ERJMFR
HRRZ

TRY

NONZER(D

NOFAGE

Q2»T1

HOLDS
1S

ANY

GET

FILE

THE

AND

AGAIN

DOES

JGET

FILE

FAGE

FILE

JFN

CHECKSUM

FIRST

ANALYZE

ERROR

PREMEMBER

CURRENT

FAGE

sREAD

THIS

sMAF

THE

FILE

T1sDATSEC

FTL

HRRI

T1sDATFAGXFAGSITZ

sANDY

PAGE

FT2

COUNTS

DOES

THE

FAGE

NUMBER

NEXT
DATA

TIME THROUGH
SECTION

Q1s<T1D

s CHECKRSUM

AlDS

FSTEF

S0JG

T2 XORL.OF

SETO

T1»

sUNMAF

MOVE

T2y L<DATSECHR26FDATFAGT

HRLI

T2y ,FHSLF
TIEsFMZRI

ERROR

INTO

DATA

THE

FAGE.

SETUF

SECTION

ADDRESS
THE

FOR

XOR

EJSHLT
JRET

WORDS

THIS

FAGE

WORID
WORD

WHOLE

FAGE

THE

FAGE

FILE

$T0

DATA

THIS

FORK

WHEN

NOFAGE:

SUNEXFECTED

CHKLOF

FFUFFZ

CATE

iLOOF

FAGE

DATA

SECTION

THE

T1,FFUFX3

FILE

USED

sNO.

CHECKSUM

TMSEG

THE

FOR

FATAL

ERROR

FAGES

FATLS

JSHLLT
ANU

FAGE

FOUND?

UNEXFECTED

FATAL

ERROR

QUIT

CHECKSUM

I&t

MOUX
MOVE

Tiy.FRIOU
T2,Q1

MOUX

fFPRINT IT ON THE TERMINAL
FOGET THE CHECKSUM

T3y NOZMAG!FLDCTM
DOy NOZRIIX)

SUNSIGNED

QUTAL

NUMRER

NOUTZ
EJSHLT
MOVE

T1yFILLJFN

CLOSFZ

HALTFZ
LCHRSUMI

FATAL

PSTOF

FROGRAM

s JUME

RACK

USER

PIL:

EBLOCK

FDLSIZ

FHTACK

FILJFN:

ELOCK

SFILE

ERROR

AGAIN

JFN

CHRKEUM

8-26

ERROR

SECTION

CONTINUES

STORAGE

ENII

FATAL

FUNEXFECTED

FIF
¥

FILE

sCLOSE

EJSHLT

XJRST

SUNEXFECTEDR
FOET

LOOF

FAGE

FATAL

INLEX

CHECKSUM

sOF

ZEROD

FMAFZ

HERE

FILE

NUMRER

FORK

FUNEXFECTED

LOOF

INITIALLY
PAGE

ACCESS

HRLI

FOLLOWING

USEN

NEXT HIGHER FAGE
$TO DATA FAGE IN

sOF

MOUX

THE

NUMBER

sCAN'T

T3»FMXRD

T2sFAGSIZ

FILE

sFIND

T2y .FHSLF

MOVEI

CHECKSUM.

CURRENT

FAND

MOVX

EJSHLT

XORLOF?

IT
TF

SECTION

HRLI

FMaFr%

THE

Q1L

A0S QA2
sUSE
MOVE T2yL<DATSECHEBLG6+DATFAGT

ERROR

FILJFN

SETZR

CHRKLOF:

PEFRINT

GETFIL

FOLLOWING
IN

ERROR MESSAGE
THERE A JFN

FYES. RELEASE

EJSERR

ADDRESSING

SFRINT

SKIFE

JRET

EXTENDED

AND

START

OVER

INDEX

AC,

Arguments

1-2

global reference,
references, 8-7

(Cont.)
GTJFN% short form,
11C%, 5-22
JFNS%, 3-36

8-7

Access

copy-on-write,
file,

file
file
file
file
file
file
file

3-2,

5-5

JSYS,

3-17

append, 3~-18
frozen, 3-18
read, 3-18
restricted, 3-18
thawed, 3-18
unrestricted, 3-18
write, 3-18
bits

OPENF%, 3-19
PMAP%, 3-28
Accumulator (AC),
Accumulators,

1-2

1-3

global reference,
hardware, 8-7
references, 8-7

8-7

Acddress

global, 8-1, 8-7
local, 8-L4, 8-7
Address space, 8-1, 8-3
process, 1~6, 5-1, 5-1]

1-3

cails,

ASCIH!

strings,

ASCIZ

strings,

ATI% JSYS,

L-16

extended, 8-1
Addressing ACs, 8-2
Addressing memory, 8-2
ADJSP instruction, 2-2, 8-11
AIC% JSYS, 4-10, L-20, 5-4
AOBJUN pointer, 8-5

BIN% JSYS,
example,

1-6,
1-6

8-15,

8-16

3-23

1-6

2-1,

3-23

packet

data,

packet

descriptor,

7-2

BLT instruction, 8-10
BOUT% JSYS, 3-23
Byte,

3-14

2-1,

reading

3-1

2-9

transferring,

Arguments

CFORK%, 5-8
DEQ%, 6-13
DIC%, L-19
ENQ% JSYS, 6-6
ENQC%, 6-16
GET%, 5-12
GTJFN% long form,

5-16

Block

block

DEQ%, 6-15
ENQ%, 6-9
ENQC%, 6-16
GTJFN% long form,

2-1,

ASCIZ pseudo-op,

Addressing

Argument

1-3

MRECV%, 7-10
MSEND%, 7-8
MUTIL%, 7-18
OPENF%, 3-18
PMAP%, 3-28, 3-30,
PMAP% JSYS, 8-16
RDTTY%, 2-10
SFORK%, 5-16
SIN%’ 3—2h
SIR%, L-7
SMAP%, 3-32, 8-14,
SOUT%, 3-25
XGTPW%, 8-21
XRIR%, L-18
XRMAP% JSYS, 8-20
XSFRK%, 8-17
XSiR%, L-7
XSVEC% JSYS, 8-18

page, 5-5

Access

1-2,

monitor

3-5

writing

Byte

3-24

2-9

instructions,

Byte manipulation
2-2

ADJSP,
IBP,

3-14

ILDB,

Index-1

2-2

8-11
instructions,

DEQ% JSYS, 6-2, 6-6, 6-13

Byte pointer, 8-11

argument block, 6-15
arguments, 6-13
functions, 6-14

global, 8-11
local, 8-11

one-word global, 2-2, 8-11

Descriptor block

system standard for JSYS, 2-2

two-word global, 2-2, 8-11

Calling

packet,

destination, 3-22
primary input, 2-3,

sequence

1-3

monitor calls,

Capability words, 5-11

CFORK% JSYS, 5-4, 5-8, 5-16, 5-22
arguments, 5-8

deactivating, 4-19
panic, 4=5, L-11, L4-12

arguments,

assignhments

DTi% JSYS,

Editing functions,

CLOSF% JSYS, 3-33
example, 3-34
execution, 3-34
Closing a file,
Communication

Effective address calculation,

8-35 8-9

example, 8-9
indexing, 8-9
indirection, 8-9
extended, 8-4

3-33

1-6

Communication facility
inter-process, 7-1

immediate instructions, 8-9

indexing, 8-6
indirection, 8-6
nonzero sections,
EFIW, 8-6, 8-22

bits

2-11

Control process, 1-7
Copy-on-write access,

5-5

EJSERR macro,
EJSHLT macro,

8-1

Creating sections, 8-16
Data

Data
Data

ENQ% JSYS, 5-L4, 6-2, 6-6, 6-18

7-2

transfer, 2-1
transfers, 3-21

Deactivating a channel, 4-19
Deadly embrace, 6-5, 6-19
Deassigning terminal codes, 4-19
DEBRK% JSYS, L-12, L4-13
Deferred

mode

terminal
Deleting

1-5
1-5

ENQ quota, 6-4

block

packet,

8-4

EIR% JSYS, L-10, L-12, 4-20, 5-L

Counter

program,

2-10

Effective address, 8-1

3-33

flag bits,

RDTTY%,

L-19

Clearing interrupt system, L-19

Control

kL-19

Disabling interrupt system, L-18

Channe! table (CHNTAB), L-8

process,

3-22

DIR% JSYS, L-18
Direct process control, 5-L

sof tware interrupt, L-5

CI1S% JSYS,

3-22

universal, 8-12
DIC% JSYS, L-19

Channel

CHNTAB, L-8

source,

universal device, 8-12

Device designator

Changing sections, 8-2

Channel

primary output,

3-22
2-3, 3-22

Destination designator,

5-10

execution,

7-2

Designator

interrupt,

inferior

4-16

process,

5-23

argument block, 6-9
arguments, 6-6
functions, 6-7
ENQC% JSYS, 5-4, 6-6, 6-16
argument block, 6-16
arguments, 6-16
flag bits, 6-17
ENQUEUE /DEQUEUE (ENQ/DEQ)
facility, 5-L, 6-1
use of, 6-6

| ndex-2

Entry vector, 8-18
information, 8-21
EP. macro, 8-7, 8-8
ERCAL symbol, 1-4, 5-16
ERCALR symbol,

1-4

ERJMPS symbol,

1-k

Flag bits

CLOSF%, 3-33
ENQC%, 6-17

GTJFN% long form, 3-16

ERCALS symbol, 1-4, 1-6
ERJMP symbol, 1-4, 5-16
ERJMPR symbol, 1-L4, 2-1kL
Error

Flags

packet descriptor block,

returns

monitor calls, 1-h
ERSTR% JSYS, 1-5

examples, 8-8

using monitor calls with, 8-12
indirect word

(EFiIwW), 8-6
Extended instruction format, 8-4
Extended page number, 8-12
8-12

FHY¥EPN,
File

closing a,

examples,

3-33

3-45

pointer,
reading

3-hk
3-3

referencing,
writing

3-L4Li

File access,

3-2,

DEQ%, 6-14
ENQ%, 6-7
MUTIL%, 7-19
PDVOP%, 8-22
RDTTY%, 2-10

3-2

identifier,
pointer,

bits

3-22

3-18

flag

Files,

3-10,

3-16

bits

long form,

3-16

form,

3-5

long form, 3-L, 3-14
argument block, 3-14
short form, 3-L4, 3-5

3-3

File thawed access, 3-18
File unrestricted access,
File write access, 3-18

3-11

returned,

short

8-13

3-5

form,

execution,

File section mapping, 3-31
File specification, 3-3
standard,

3-14

long form,
short

section

mapping,

1-5
8-7
5-7

arguments

3-3

File read access, 3-18
File restricted access,
File

5-12

3-18
3-18

File page mapping, 3-28
File

5-15

5-11,

GNJFN% JSYS, 3-10, 3-40O
bits returned, 3-40

3-17

File append access,
File frozen access,
File

Functions

Global address, 8-1, 8-5, 8-7
Global byte pointer, 8-11
Global stack, 8-11

3-2, 6-1

summary,
codes,

3-38
2-7

JFNS%,
NOUT%,

GETER% JSYS,
GF IWM macro,
GFRKS% JSYS,

from

sharing,

|PCF packet, 7-2
<SYSTEM>INFO requests, 7-15
<SYSTEM>INFO responses, 7-17
Format options

arguments,

3-22

summary,

extended instruction, 8-k

GET% JSYS,

3-17

opening a,

7-3

Format

Execute-only process, 8-22
Extended addressing, 8-1, 8-3
Extended format

3-5

GTJFN% short form,
MRECV%, 7-12
MSEND%’ 7_9
SMAP%, 3-32

examples,

3-18

summary,

GTSTS% JSYS,
bits

3-1

I ndex-3

3-12

3-17

3-34

returned,

3-35

HALTF% JSYS, 2-9, 5-19
example, 2-8
Handle section, 8-19
HFORK% JSYS, 5-19

Instructions (Cont.)
stack, 8-11
Inter-process

communication

facility
receive quota,

{/0 monitor
IBP

calls,

instruction,

2-2

send

file,

Inter-process

facility

3-3

8-22
4-11,

arguments,

ILDB

5-4, 5-22

instruction,

2-2

Interrupt

format

(IFIW),

Interrupt

characteristics,

5-2

Interrupt

service

interrupt

system

5-8

deleting,

5-23

parallel,

5-10

L4-7

terminal, L4-13
|PCF, 1-6, 5-L, 7-1
packet

starting, 5-16
status, 5-18
termination,

5-17

packet

about process, §-18
entry vector, 8-21
page-failure, 8-21

block,

7-2,

descriptor

block,

7-15
flags,

7-3

receive quota,

Initialization

send

quota,

7-1

utility functions,

2-9

Input

terminal,

data

IPCF

packet

JFN,

3-1,

format,

7-18
7-2

2-1

designator

extended,
Instruction

- (IFIW),
Instructions

format

8-4
format

8-5

3-2,

3-3

JFNS% JSYS, 3-36
arguments, 3-36
format options, 3-38

2-3

Instruction

7-7,

7-15
address, 7-6
length, 7-6

Information

byte,

routines,

Interrupts

5-8,

primary,

L-6

clearing, L4-19
disabling, 4-18

superior,

5-10

creating,

Input

4-12

immediate mode

terminal, L-16
interrupt priority levels,
Interrupt processing, 4-11

8-5

communicating with

4-3

deferred mode

terminal, L-16
Interrupt dismissing,

indirect

1-7,

channels

Interrupt

indirect word

process,

5-L,

assignments,

activating, 4-10
Interrupt conditions,

(EFIW), 8-6
format

channel

Interrupt

terminal interrupt, L-16
Indexing, 8-5, 8-22
example, 8-9
Indirection, 8-5, 8-22
example, 8-9

word

1-6,

L-5

Immediate mode

Inferior

(IPCF),

Interrupt, L-1
generating, b4-11

5-22

instruction

7-18

communication

7-1

i1legal instruction trap, 1-4
Immediate instructions, 8-9

extended

7-1

utility functions,

2-2

Identifier

IFIW, 8-5,
}1C% JSYS,

quota,

indirect word

Jobh,

1-7

Job

file

number,

Job structure,

8-11

exapmle,

I ndex-4

1-7

3-1,

1-6

3-3

7-2,

JRA instruction, 8-11
JRST instruction, 8-2,
JSA instruction, 8-11
JSP instruction, 8-11
JSR instruction, 8-11
JSYS,

JSYS (Cont.)
RESET%, 2-9, 5-23, 7-6
RFSTS%, 5-4, 5-18
RFSTS% long form, 5-18, 5-20
RFSTS% short form, 5-18
RIN%, 3-26
RIR%, L-17, 8-12
ROUT%, 3-26
RSMAP%, 8-18
SAVE%, 5-11
SEVEC%, 8-18
SFORK%, 5-4, 5-16
SFRKV%, 5-17
SIN%, 3-24, 3-25
SIR%, L-7, L-12, 5-4, 8-12
SKPIR%, L-17
SMAP%, 3-31, 8-13
SOUT%, 3-24, 3-25
SPJFN%, 2-3
SSAVE%, 5-11
STIW%, L-16
WFORK%, 5-k4, 5-17, 5-18
XGTPW%, 8-21
XGVEC%, 8-21
XRIR%, L-18, 8-13
XRMAP%, 8-20
XSFRK%, 5-17, 8-17

B-11

1-2

AtC%,

L-10,

arguments,

4-20, 5-4
1-2,

1-3

ATI1%, L-16
BIN%, 1-6, 3-23
BOUT%, 3-23
CFORK%, 5-4, 5-8, 5-10, 5-16,
5-22

CLOSF%,
DEBRK%,

3-33
L-12,

4-13

DEQ%, 6-2, 6-6, 6-13
DIC%,
DIR%,
DT1%,
EIR%,

L-19
L-18
L-19
L-10,

L-12, 4-20, 5-L

ENQ%, 5-L, 6-2, 6-6, 6-18

ENQC%, 5-4, 6-6, 6-16
error returns, 1-4
ERSTR%, 1-5
GET%, 5-11, 5-15
GETER%, 1-5
GFRKS%, 5-7
GNJFN%, 3-10, 3-40
GTJFN%, 3-3, 3-4, 3-5,
GTSTS%,
HALTF%,
HFORK%,
| /0,

XSIR%, L-7, L4-12, 4-20,
XSVEC%, 8-18
JUMP instruction symbols,
ERCAL, 1-4, 5-16

3-10

3-34
2-9, 5-19
5-19

2-2

Level

PBIN%, 2-9, 2-16
PBOUT%, 2-9, 2-16
PDVOP%, 5-11, 8-22
PMAP%, 3-27, 3-28, 3-30, 3-31,
5-11, 5-16, 5-22, B8-13,
8-16
PSOUT%, 2-3, 2-16

RDTTY%, 2-5, 2-10, 2-1k4, 2-16

1-4

ERCALR, 1-h
ERCALS, 1-4, 1-6
ERJMP, 1-L, 5-16
ERJMPR, 1-L, 2-14
ERJMPS, 1-4
JUMP instructions, 1-4

l1¢c%, L-11, 5-4, 5-22
JFNS%, 3-36
KFORK%, 5-L, 5-23
MRECV%, 5-4, 7-7, 7-10

MSEND%, 5-4, 7-7, 7-8, 7-14
MUTIL%, 5-4, 7-18
NIN%, 2-L4, 2-5, 2-1k4, 2-16
NOUT%, 2-6, 2-16
OPENF%, 3-2, 3-18

8-13

number

resource, 6-5
LEVTAB, L-9
LF IWM macro, 8-7
LINK, 8-22
Literals,
Local

2-2

byte pointer, 8-11
Local address, 8-4, 8-5, 8-7
Local byte pointer, 8-11

index-5

MUTIL% JSYS

Lock

execution,

resource, 6-2
Long form GTJFN%,

functions,

3-14
8-10
ons,
instructi
LUUO

example, 2-8

TMSG, 2-4
Mapping, 8-13

Number

OPENF% JSYS, 3-2, 3-18, 3-30

sections

to a

arguments, 3-18

examples, 3-21
Opening a file, 3-17

process,

Operation code

monitor

page, 3-27, 5-15

Ownership, 6-2, 6-18
exclusive, 6-2, 6-18
shared, 6-2, 6-18

receiving process, /-7
sending process, 7-7

calling

sequence,

error returns,
for processes,
I /0,

code,

1-2,

2-3

MRECV% JSYS,

5-L,

arguments,

7/-10

execution,
flagbits,

flags

5-L,
7-8

execution,

7-10

flag

7-9

bits,

7-2,

7-7,

7-15

address, 7-6
length, 7-6

Packet descriptor block,

1-2

7-2,

7-15

7-7,

flags,

7-10

|PCF,
Page,

Multiple processes,

7-2

3-1

Page access,

7-13

7-7,

7-3

format

Packet

7-13

returned,

7-10

7-8

Packet data block,

1-4
5-8

7-12

MSEND% JSYS,
arguments,

sending a,

1-3

2-2

operation
MONSYM,

receiving

1-3

7-2

7-1,

Packet,

1-2

1-2,

2-1

Output designator
primary, 2-3

Messages

calls,

1-2

terminal,

8-1k

5-5

sharing,

calls,

Qutput

3-30

page,

process section,
sections, 8-13
Memory, 8-2

arguments,

3-19

access bits,

3-28

8-13
memory, 8-13

Monitor

2-2,

byte pointer,

One-word global
8-11, 8-12

3-31

Memory

2-L
2-6

reading a,
writing a,

file section,

process

2-7

format options,

EP., 8-8
indirection, 8-7
EP., 8-7
GF IWM, 8-7
LFIWM, 8-7

file

7-19

NOUT% JSYS, 2-6, 2-16

1-2

MACSYM macros,
EJSERR, 1-5
EJSHLT, 1-5

file page,

7-24

NIN% JSYS, 2-L, 2-5, 2-1k4, 2-16

1-2

MACSYM,

(Cont.)

7-8, 7-14

Page mapping,
file,

Page

5-5
5-15

3-27

sharing,

5-5

Page-failure information, 8-21
5-2

Multisection programs, 8-24
MUTIL% JSYS, 5-4, 7-18
arguments, 7-18

Panic channel,
Parallel

L4-5,

inferior

L-11,

PBIN% JSYS, 2-9, 2-16
PBOUT% JSYS, 2-9, 2-16

Index-6

L-12

processes,

5-10

Process

PC, 5-1, 8-1, 8-2, B-1
address, 8-11

PDV, 8-22
:
names, 8-23
rules, 8-23
PDVA, 8-22
manipulating, 8-22
PDVOP% JSYS, 5-11, 8-22
functions, 8-22
PID, 7-1, 7-6, 7-13
PMSEPN, 8-12
PMAP% JSYS, 3-27, 3-30, 3-31,

structure,

5-5, 5-22.

5-22

sharing pages,

sof tware interrupt, 5-4, 5-22
Process control, 5-4
Process handle, 5-5, 5-6
Process ID (PiID), 7-1, 7-6, 7-13
Process
Process

2-1

identifiers,

5-5

initialization,

Process mapping,

2-9

3-30

Process messages

3-22

PRIIN symbol,

receiving,

sending,

2-3, 2-10, 2-16,

input designator

(.PRIIN),

3-22

Primary output

(.PRIOU),
Printing

Priority

level

designator

2-3,

string,

3-22
2-3

interrupt, 4-12
software interrupt, L-4

Priority level
4-9
.PRIOU symbol,

table

(LEVTAB),

2-3,

2-10, 2-16,

3-22

Process, 1-6, 1-7
address space, 1-6,
capabilities,

5-11

inferior,

identifiers,

multiple,

5-2

section,

Process

5-2

3-31

8-16

status word,

5-19

Process structure,

1-6, 5-1

Process

3-31

unmapping,

Program counter, 8-2
address fields, 8-2
Program counter (PC), 5-1, 8-1,
8-11
address, 8-11
Program data vector (PDV), 8-22
address (PDVA), 8-22
manipulating PDVAs, 8-22
names, 8-23
rules, 8-23
program version number, 8-23

multisection,

8-24

Protection

resource,

5-23

5-5

1-7,

relationships,

Process

5-3, 5-22

examples, 5-2L4
execute-only, 8-22
handle, 5-5, 5-6, 5-10
inferior,

Process

Programs

5-11

communication, 1-6,
control, 1-7, 5-k

/-7

7-7

unmapping,

3-22

deleting

5-17

use of resources, 6-5
Process communication, 1-6, 5-3,

Pooled resources, 6-12
POP instruction, 8-11
POPJ instruction, 8-11

2-3,

5-2

inferior,

terminating

Pointer

Primary

1-6, 5-1
1-7,

superior,

5-11, 5-16, 5-22, B-13, 8-16

file,

5-19

status word,

access bits, 3-28
arguments, 3-28, 3-30, 5-16,
8-16
pseudo-op,

5-2

starting in any section, 8-17
starting inferior, 5-16

address fields, B8-2

POINT

(Cont.)

parallel,

information about, 8-18
JSYSs for, 5-8

6-4

Pseudo-ops

ASCIZ,

1-6

POINT,

2-1

PSOUT% JSYS, 2-3, 2-16
example, 2-8
PUSH instruction, 8-11
PUSHJ instruction, 8-2,

I ndex-7

8-11

Queue,

6-2

Quota,

7-1

receive,
send,

7-1

/-1

RDTTY% JSYS,
2-16

2-5,

arguments,

2-10

2-10,

file,

control

bits,

editing

functions,

example,
Reading

2-10

2-1k

Send quota,

a byte,

2-9

2-4

Reading a

2-10

string,

from a file

3-4b

summary,

Receive quota,

7-1

Receiving a packet,

7-10

Referencing a

3-3

file,

Releasing a resource, 6-13
RESET% JSYS, 2-9, 5-23, 7-6
example, 2-8
Resource, 6-2
level number, 6-5
obtaining

information

about,

6-16

ownership, 6-2,
pooled, 6-12

6-18

protection, 6-4
releasing a, 6-13
requesting use of, 6-6
sharing, 6-1, 6-18
use by process, 6-5
Resource lock, 6-2
Resource name, 6-4
Resource ownership, 6-2
RFSTS% JSYS, 5-4, 5-18
long form, 5-18, 5-20
status-return block,
process

status word,

short form, 5-18
RIN% JSYS, 3-26
RIR% JSYS, 4-17, 8-12
example, L4-17
ROUT% JSYS, 3-26
RSMAP% JSYS, 8-18
information returned,

SAVE% JSYS,

5-11

Section

changing,

8-2

3-31

file to process,
process, 8-14
Sections, 8-2

2-11

Reading a number,
Reading

2-14&,

Section (Cont.)
creating, 8-16
nonzero, 8-16, 8-17
zero, 8-3, 8-12
Section handle, 8-19
Section mapping, 8-13
8-13

7-1

Sending a packet, 7-8
SEVEC% JSYS, 8-18
SFM instruction, 8-10
SFORK% JSYS, 5-4, 5-16
arguments, 5-16
SFRKV% JSYS, 5-17
Sharer groups, 6-18
use of, 6-18
Sharing files, 3-2, 6-1
Sharing

pages,

5-22

Sharing resources,
Short form GTJFN%,
examples,

6-1,
3-5

6-18

3-12

SIN% JSYS, 3-24, 3-25
arguments, 3-24
SIR% JSYS, 4-7, L-12, 5-4, 8-12
arguments, L-7
SKPIR% JSYS, L-17
SMAP% JSYS, 3-31, 8-13
arguments, 3-32, 8-14, 8-15,
8-16
flag bits,

Software

3-32

interrupt,

1-6,

L4-11,

£-22

channel assignments, L-5
channels and priorities, L4-L,
L-6
disabling, 4-18
dismissing, L4-12
example, L-21
panic channel, L4-5, L4-11, L4-12
priority level, L-12
priority levels, L-4
process communication, 5-4
processing, L4-11

5-20

5-19

8-19

service routines, L-7
tables, L-7
Software interrupt system,
L-1, 5-17
enabling, L4-10

| ndex-8

1-6,

Software interrupt system
operational sequence,
summary, L-20
Source designator,

- SQUT% JSYS,

3-24,

(Cont.)

Table

(Cont.)

software

4-2

interrupt,

L-7

Terminal
input,

3-22

3-25

2-1

output,

2-1

arguments,

3-25

Terminal

SPJFN% JSYS,
SSAVEZ JSYS,

2-3
5-11

deassigning, 4-19
Terminal interrupts, 4-13
codes, L4-1b4
deferred mode, 4-16

Stack

address, 8-11
global, 8-11
pointer, 8-11
register, 8-11
Stack instructions,
ADJSP, 8-11
POP, 8-11
POPJ, 8-11
PUSH, 8-11
PUSHJ, 8-11
Standard

file

generating, L-16
immediate mode, L-16
Terminating

8-11
Text

strings,

specification,

3-3

illegal

STIW% JSYS,

instruction,
global

2-3

Unmapping

2-10

process

a,
a,

ASClZ,
text,

device designator,
page,

3-31

process section,

Strings
ASCIHt,

1-4

pointer,

2-1,

3-23

2-1,

3-23

8-16

Vector

2-1

transferring, 3-2h4
example, 3-26

entry, 8-18
Virtual address space,
Virtual space, 1-6

8-1

WFORK% JSYS,

5-18

Structure

process,
Superior

2-2,

L-16
Universal

reading

byte

8-11

5-20

String
printing

3-24

3-26

Trap
Two-word

block,

3-24
3-21

Transferring strings,

example,

5-19

Status-return

process,

2-1

Transferring data,

Status word

process,

inferior

5-17

TMSG macro, 2-k
example, 2-8
Transferring bytes,

Starting a process, 8-17
Starting inferior process, 5-16
"

codes

1-6

process,

1-7,

communicating with

Writing

5-2

<$YSTEM>INFO, 7-1, 7-6, 7-7, 7-8,
7-10, 7-14
~functions and arguments, 7-16
7-1b4

format,

7-15

responses,

<SYSTEM>INFO

7-17

responses,

7-17

Table

channel (CHNTAB), L4-8
priority level (LEVTAB),

L-9

5-L,

byte,

5-17,

2-9

Writing a number, 2-6
Writing to a file

inferior,

5-10

requests,

summary,

3-Li

XBLT instruction, 8-10
XCT instruction, 8-10
XGTPW% JSYS, 8-21
arguments, 8-21
XGVEC% JSYS, 8-21
XHLL! instruction, 8-9, 8-10
XJEN instruction, 8-10
XJRST instruction, 8-2
XJRSTF instruction, 8-2, 8-10

Index-9

8-12

XMOVE| instruction, 8-9, 8-22
XPCW instruction, 8-10
XRIR% JSYS, 4-18, 8-13

XSFRK% JSYS, 5-17, 8-17
arguments, 8-17
XSIR% JSYS, 4-7, L-12, 4-20, 8-13

XRMAP% JSYS, 8-20
arguments, 8-20

XSVEC% JSYS, 8-18
arguments, 8-18

arguments, 4-18

arguments, L-7

Index-10

TOPS-20
Monitor Calls User’'s Guide
AA-D859C-TM

READER’S COMMENTS

NOTE:

This form is for document comments only. DIGITAL will use comments submitted on

this form at the company'’s discretion. If you require a written reply and are eligible to
receive one under Software Performance Report (SPR) service, submit your com-

ments on an SPR form.

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

Did you find errors in this manual? if so, specify the error and the page number.

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

[l Assembly language programmer
[ Higher-level language programmer
[L] Occasional programmer (experienced)
[ _1 User with little programming experience
[ Student programmer
[] Other (please specify)
Name

Date

Organization

Telephone

Street

City

State —______ Zip Code
or Country

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.

POSTAGE WILL BE PAID BY ADDRESSEE

200 FOREST STREET

MRO1-2/L12

MARLBOROUGH, MA

01752

Cut Along Dotted Line

SOFTWARE PUBLICATIONS