Digital PDFs

AA-0974G-TB

April 1988

348 pages

Original

15MB

Document:	TOPS-10 Monitor Calls Manual Volume 1 Oct88
Order Number:	AA-0974G-TB
Revision:	0
Pages:	348
Original Filename:	AA-0974G-TB_TOPS-10_Monitor_Calls_Manual_Volume_1_Oct88.pdf

OCR Text

TOPS-10
Monitor Calls Manual
Volume 1
AA-097 4G-TB

October 1988

This manual describes the functions that the monitor performs
to service monitor calls from assembly language programs.
The TOPS-10 Monitor Calls Manual Is divided Into two volumes:
Volume 1 covers the facilities and functions of the monitor;
Volume 2 describes the- monitor calls, calling sequences,
symbols, and GETTAB tables.
This manual supe-rsedes the previous manual of the same
name, SOC order number AA-0974F-TB.

Operating System:

. TOPS-10 Version 7.04

Software:

GALAXY Version 5.1

digital equipment corporation
maynard, massachusetts

First Printing, November 1975
Revised, May 1977
Revised, January 1978
Revised, August 1980
Revised, February 1984
Revised, April 1986
Revised, October 1988
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 be
used or copied only 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 Equipment Corporation or its affiliated companies.
Copyright © 1975, 1984, 1988 Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The Reader's Comments form on the last page of this document requests the
user's critical evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

CI
DDCMP
DEC
DECmail
DECnet
DECnet-VAX
DECserver
DECserver 100
DECserver 200
DECsystem-10
DECSYSTEM-20

DECtape
DECUS
DECwriter
DELNI
DELUA
HSC
HSC-50
KA10
KI
KL10
KS10

LA50
LN01
LN03
MASSBUS
PDP
PDP-11/24
PrintServer
PrintServer 40
Q-bus
AeGIS
RSX

SITGO-10
TOPS-10
TOPS-20
TOPS-20AN
UNIBUS
UETP
VAX
VAXNMS
VT50

~BmBDmDTM

CONTENTS
PREFACE
CHAPTER 1
1.1
1.2
1.2.1
1.2.2
1.2.3
CHAPTER 2
2.1
2.2
2.3
2.4
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.4.6
2.5
2.5.1
2.5.2
2.6
2.6.1
2.6.2
2.6.3
2.7
CHAPTER 3
3.1
3.1.1
3.1.2
3.1.3
3.2
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
CHAPTER 4
4.1
4.2
CHAPTER 5

INTRODUCTION TO MONITOR CALLS
MONITOR CALL SYMBOLS .
PROCESSING MODES .
User Mode
. .
Executive Mode . . . . .
User I/O Mode
. . . . .

. .
. . ..
. . . . .

· ..
· .
. . . . · .
....
. .

1-2
1-3
1-3
1-3
1-4

MEMORY
. . 2-1
MEMORY ALLOCATION . . . . . . . . . . .
USER-MODE EXTENDED ADDRESSING
. . . . . 2-3
USER MEMORY
. . . . . .
. . ..
. 2-4
CONTROLLING PROG~ SEGMENTS . .
. . . . . . 2-4
Adjusting the Size of Segments . .
. . 2-5
Merging Low Segments . . . . .
. . . . . . . 2-5
Writing Into High Segments . . . . . . . . . . . 2-5
Testing for a Sharable High Segment
. . . . . . 2-6
Finding the Origin of a High Segment .
2-6
Modifying a High Segment and Meddling . . . . . 2-6
RUNNING A PROGRAM . . . . . .
. 2-8
Functions of RUN and GETSEG
. . . . . . . 2-9
Reading Command Files
. . ..
....
2-11
CONTROLLING PAGES
. . . . . . .
2-12
Handling Page Faults . . . . .
2-12
The System's Page Fault Handler
2-12
Building Your Own Page Fault Handler .
2-12
LOCKING AND UNLOCKING A JOB IN MEMORY
2-13
JOB CONTROL
EXECUTING A PROGRAM
Starting a Program
Stopping a Program .
..... .
Suspending a Program .
... .
CONTROLLING MULTIPLE JOB CONTEXTS
RUNTIMES, TIMES, AND DATES . . . . .
Runtimes . . . . .
. ...... .
The System Date
. . . ..
... .
The Universal Date . . . .
. .
The System Time
. . . . .
Date-Time Elements from GETTAB Tables

·
·

·
.
.
·
·

· .
· ..

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

THE JOB DATA AREA
JOB DATA IN THE LOW ·SEGMENT
JOB DATA IN THE HIGH SEGMENT .

. 4-1
· 4-5

NETWORKS

ANF-10 NETWORK MONITOR CALLS . .
5.1
ANF-10 INTERTASK COMMUNICATION . .
5.2
Initiating a Connection
5.2.1
Using the LOOKUP/ENTER UUOs
5.2.1.1
iii

· . 5-2
· . . 5-3
· . 5-4
5-5

Using the TSK. UUO . .
. . . . . . . . . . . 5-6
5.2.1.2
Sending and Receiving Between Tasks
. . . . . . 5-7
5.2.2
Breaking the Intertask Communication . . . . . . 5-8
5.2.3
TASK TO TASK PROGRAMMING WITH DECnet-10
. . . . . 5-8
5.3
Specifying a Destination Task
5-10
5.3.1
Specifying a Source Task . . . . . .
5-13
5.3.2
Reading the Connect Information
. . . . 5-15
5.3.3
5.3.4
Accepting the Connection . . . . .
. . . . 5-16
Rejecting the Connection. . . . .
5-17
5.3.5
Reading the Connect Confirm Data .
5-18
5.3.6
5.3.7
Reading the Status of the Link
5-18
Using the PSI System . . . .
. . . . . . 5-21
5.3.8
Setting the PSI Reason Mask
. . . . . . . 5-21
5.3.9
5.3.10
Enabling the PSI Interface . .
. . . . . 5-22
5.3.11
Reading and Setting the Link Quota and Goal
5-23
Transferring Information Over the Network
5-24
5.3.12
5.3.13
Sending Normal Data . . . .
. . . . 5-24
5.3.14
Receiving Normal Data . . . . . . . . . . . . 5-25
5.3.15
Sending Interrupt Data . . . . . . . . . .
5-27
5.3.16
Receiving Interrupt Data . . . . . .
5-27
5.3.17
Closing a Network Connection
5-28
Releasing a Channel
. . . . . ..
5-29
5.3.18
Aborting a Connection
5-29
5.3.19
5.3.20
Reading the Disconnect Data
. . . . . . . . . 5-30
5.4
OBTAINING INFORMATION ABOUT DECNET-10
5-31
ETHERNET NETWORKS
.......
5-36
5.5
5.5.1
Transmitting and Receiving.Information . .
5-37
5.5.2
Returned Channel Information .
5-38
5.5.3
Returned Portal Information
.....
5-40
5.5.4
Returned Controller Information
. . . . . . . 5-40
CHAPTER 6
6.1
6.2
6.2.1
6.2.2
6.3
6.3.1
6.3.2
6.3.3
6.3.4
CHAPTER 7
7.1
7.2
7.2.1
7.2.2
7.2.3
7.2.4
7.2.5
7.3
7.4
7.5
7.6
7.7
7.8
7.8.1
7.8.2

TRAPPING, INTERCEPTING, AND INTERRUPTING
TRAPPING ERRORS AND CONDITIONS . . . . . . . . . . 6-1
. . . . .
INTERCEPTING ERRORS
. . . . . . . 6-3
Using the .JBINT Intercept Block
. . . . . . . 6-4
Examples of Error Intercepts . .
. . . 6-6
USING PROGRAMMED SOFTWARE INTERRUPTS .
. 6-7
PSI Monitor Calls
. . . . .
. 6-9
Interrupt Control Block . . . . .
6-10
Interrupt Conditions . . . . . . .
6-12
Example Using Programmed Interrupts
6-16
COMMUNICATING BETWEEN PROCESSES USING IPCF
PACKETS
. . . . .
. . . . . . 7-1
FORMAT OF THE PHB
. . . . . . . ..
. . . . . . 7-2
IPCF Instruction Flags . . . . . .
. . . . 7-3
IPCF Packet Descriptor Flags . .
....
. 7-4
Process Identifiers
. . . . . . . . . . . . 7-6
Symbolic Names . . .
.........
. 7-6
IPCF Capability Word .
. 7-7
LONG-FORM MESSAGES . . .
....
7-7
QUOTAS . .
.....
. . . . . . 7-8
SENDING AN IPCF PACKET USING IPCFS. UUO
. . 7-8
RETRIEVING AN IPCF PACKET USING IPCFR. UUO . . . . 7-9
QUERYING THE NEXT IPCF PACKET USING IPCFQ. UUO.
7-10
SYSTEM PROCESSES . . . . .
. . . . . . 7-10
[SYSTEM] INFO .
. . . .
. . . .
7-11
[SYSTEM] IPCC . .
....
. . . . . . . 7-15

CHAPTER 8
8.1
8.1.1
8.1.1.1
8.1.1.2
8.1.2
8.1.2.1
8.1.2.2
8.1.3
8.1.3.1
8.1.3.2
8.1.3.3
8.2
8.3
8.4
8.5
8.6
8.6.1
8.6.2
8.6.3
8.6.4
8.7
8.7.1
8.7.2
8.7.3
8.8
8.8.1
8.8.2
8.8.3
8.8.4
8.9
8.10
CHAPTER 9
9.1
9.1.1
9.1.2
9.1.3
9.1.4
9.1.5
9.2
9.3
9.4
9.5
9.6
CHAPTER 10

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
REQUESTING A RESOURCE
. . . . . . . . . . . . . . 8-2
Sharable Resources .
.....
. . . . . 8-3
Resource Pools . .
. . . . .
. 8-3
Partitioned Resources
. . . . .
. 8-4
Multiple-Lock Request.s . . . . . .
. 8-5
ENQ. Quotas
. . . . . . . . . .
. . . 8-5
Request Levels . . . . . . . . .
. 8-5
Granting Loc~s . . . . . . . . . . . . . .
. 8-6
ENQ. Software Interruption
. . . . . 8-6
Time Limits
. . . . ..
....
. 8-6
Deadlock Detection . . .
. . . . . . 8-7
RELEASING RESOURCES
. . . . . . . . .
. 8-7
PASSING DATA TO OTHER JOBS . . . . . . . . . . . . 8-8
ENQ/DEQ MONITOR CALLS
. . . . . . . . . . . 8-9
BUILDING REQUESTS
. . . .
. . . . . . . . . 8-9
QUEUEING REQUESTS: ENQ. UUO
. . . . . . . . . .
8-12
Requesting and Waiting for Locks .
....
8-13
Requesting Locks Only if Available . . . . . .
8-13
Requesting and Interrupting when Locked
8-13
Modifying a Previous Request . . . . . . . . .
8-14
DEQUEUEING REQUESTS: DEQ. UUO
. . . . . .
8-14
Cancelling a Specific Request
. . . . . .
8-14
Cancelling All Requests for a Job
. . . .
8-15
Cancelling Requests Based on Request-id
8-15
CONTROLLING ENQ/DEQ: ENQC. UUO . . . . . . . . .
8-15
Obtaining the Status of a Request
. . . .
8-16
Obtaining the Quota for a Job
8-17
Setting the Quota for a Job
. . . .
8-18
Dumping the ENQ. Database
. . . . .
8-18
ENQ. ERRORS
. . . . . . . . . .
8-21
EXAMPLE USING THE ENQ. FACILITY
8-22
PROGRAMMING FOR REALTIME EXECUTION
. . . . . . . . 9-1
CONNECTING REALTIME DEVICES
Normal Block Mode
. . . .
. . 9-6
Fast Block Mode
. . . . . .
. 9-8
Single Mode
. . . .
9-10
EPT Mode . . . . . .
9-12
9-12
Exec-Mode Trapping .
USING RTTRP AT THE INTERRUPT LEVEL . . . . .
9-14
RELEASING REALTIME" DEVICES . .
9-14
DISMISSING REALTIME INTERRUPTS . . . . . . . . .
9-15
ASSIGNING RUN QUEUES . . .
....
9-15
SUSPENDING OTHER JOBS
9-15
ANALYZING SYSTEM PERFORMANCE

THE PERFORMANCE FACILITY: PERF.
10.1
Performance Modes
. . . . . . .
. . . .
10.1.1
Performance Enable Flags . . .
... .
10.1.2
PERF. Functions
. . . . . . . ..
. .. .
10.1.3
Initializing the Performance Meter . .
10.1.3.1
Starting the Performance Meter . . . . . . .
10.1.3.2
Reading the Performance Meter
. . . . .
10.1.3.3
Stopping the Performance Meter . . . . . . .
10.1.3.4
Releasing the Performance Meter
. . . . . .
10.1.3.5
Background PERF. Functions . .
10.1.4
10.1.5
PERF. Errors . .". . . .
THE SNOOP FACILITY: SNOOP.
10.2
v

10-1
10-1
10-1
10-2
10-3
10-5
10-5
10-6
10-6
10-6
10-6
10-7

10.2.1
10.2.2
10.2.3
10.2.4
10.2.5
CHAPTER 11

Defining Breakpoints . . . . . . .
Inserting Breakpoints
. . . .
Removing Breakpoints . .
....
Deleting Breakpoint Definitions
SNOOP. Error Codes . . .

10-8
10-9
. . 10-10
10-10
. . . . 10-10

PROGRAM INPUT AND OUTPUT

OVERVIEW OF THE I/O PROCESS
. . ..
11.1
INITIALIZING A PROGRAM . . . . . . .
11.2
INITIALIZING A DEVICE
.....
11.3
TOPS-10 Devices
. . . . .
11.3.1
11.3.2
Device Names . . . . .
....
....
11.3.2.1
Generic Device Names
........
Physical Device Names
. . . .
11.3.2.2
Logical Device Names . .
11.3.2.3
11.3.2.4
Ersatz Device Names
11.3.2.5
Pathological Device Names
. . . ..
11.3.3
Universal Device Indexes
. . . .
11.3.4
MPX-Controlled Devices .
11.3.5
Spooled Devices
. . . .
11.3.6
Restricted Access Devices
11.4
MODES
.
DEFINING A COMMAND LIST
.
11.5
11.6
SELECTING A FILE . .
.
11.7
TRANSMITTING DATA
. . . . .
. .
11.7.1
Output (Writing a File)
.
11.7.2
Input (Reading a File)
Writing a File Using FILOP.
11.7.3
11.7.4
Modifying Files (Update Mode)
.
11.7.5
Block Pointer Positioning
11.7.6
Super USETI/USETO
....
.
RECOVERING FROM ERRORS .
. .
11.8
11.9
USING BUFFERED I/O . .
.
11.9.1
The INBUF and OUTBUF Monitor Calls .
11.9.2
The Buffer Control Block .
. . . .
11.9.3
The Buffer Header Block
. . . .
. .
11.9.4
Using Buffered Input .
. . . .
11.9.4.1
Normal Buffered Input
11.9.4.2
Synchronous Buffered Input
. .
11.9.4.3
Nonblocking Buffered Input . .
. .
11.9.5
Using Buffered Output
. . . .
11.9.5.1
Normal Buffered Output .
. . . . . .
11.9.5.2
Synchronous Buffered Output
11.9.5.3
Nonblocking Buffered Output
.. . . .
11.9.6
Buffered I/O for MPX-Controlled Devices
.
11.9.7
Generating Your Own Buffers
. . . .
11.10
CLOSING A FILE . .
.
11.10.1
Maintaining File Integrity .
.
11.11
RELEASING A DEVICE .
.
11.12
STOPPING A PROGRAM . . . . . . . . . .
.
11.13
THE LOOKUP/ENTER/RENAME ARGUMENT BLOCKS
11.13.1
The Short Form of the Argument List
.
11.13.2
The Extended Argument List
.
11.14
ERROR CODES
. . . .
. . . . .
CHAPTER 12
12.1
12.1.1
12.1.2
12.1.3

DISKS

11-1
11-2
11-2
11-2
11-3
11-5
11-6
11-6
11-7
11-8
11-8
11-9
11-9
11-10
11-11
11-12
11-14
11-15
11-15
11-19
11-20
11-21
11-22
11-23
11-24
11-25
11-28
11-28
11-29
11-30
11-32
11-32
11-33
11-33
11-35
11-35
11-36
11-36
11-40
11-44
11-45
11-45
11-46
11-46
11-46
11-48
11-59

(DSK)

DISK NAMES
. . . . . .
Logical Unit Names
. . . . . .
Physical Controller and Disk Unit Names
Abbreviations
. . . . . . . . . . . . .
vi

12-1
12-2
12-2
12-3

12.2
DISK FILE NAMES
. . . . .
. . . . . . .
12.3
DISK FILE PROTECTIONS
12.4
THE FILE DAEMON (FILDAE) . . . . . . . . .
12.5
DISK FILE FORMATS
. . . . .
. . . .
12.6
DISK DIRECTORIES. . . . . .
. . . .
12.6.1
The Master File Directory (MFD)
. . . .
12.6.2
User File Directories (UFDs)
.
12.6.3
Subfile Directories (SFDs)
...
12.6.4
Directory Paths . . . . . . . . . . . . . . .
12.6.5
Pathological Device Names
..
12.7
DISK DIRECTORY PROTECTIONS
. . . .
.
12.8
JOB SEARCH LISTS.
. . . . . . .
.
12.9
DISK PRIORITIES
.
12.10
DISK I/O . . . . . . .
. . . .
.
12.11
DISK I/O PROCESSING
. . . .
12.12
DUAL-PORT HANDLING. . . . . .
. .
12.13
ERRORS........
. . . ..
.
12.13.1
DATA TRANSFER ERRORS.
. . ..
..
12.13.1.1
ECC Correctable Error
. . . . . .
.
12.13.1.2
Non-data Error . . .
....
. . .
12.13.1.3
Data Error. . . . . .
. ...
12.13.2
SEEK AND STATUS ERRORS .
.
12.13.2.1
Drive Powered Down. . . . . . . . .
..
12.13.2.2
Drive Powered Up .
. . . ..
..
12.13.2.3
Seek Incomplete
.....
12.13.2.4
Hung Device
.....
12.13.2.5
Rib Errors
. . ..
..
12.13.2.6
RAE Errors . . . . . . . . . . . . . . . . .
12.14
BAT BLOCKS. . . .
. ..
12.15
DSKRAT
......
. ..
12.16
DISK DATA MODES
. . . . .
.
12.17
DETERMINING THE PHYSICAL ADDRESS OF A BLOCK
WITHIN A DISK FILE . . . . . . . . . . .
·
Buffered Modes
12.17.1
. . .
Dump Modes . . .
12.17.2
DISK I/O STATUS
12.18
·
CHAPTER 13

12-3
12-3
12-7
12-8
12-8
12-9
12-10
12-10
12-11
12-12
12-21
12-23
12-24
12-25
12-26
12-28
12-28
12-28
12-28
12-28
12-29
12-30
12-30
12-30
12-30
12-30
12-30
12-30
12-31
12-31
12-31
12-31
12-35
12-35
12-36

DECTAPES (DTA)

. . . .
DECTAPE DEVICE NAMES . .
DECTAPE DATA MODES . . . . .
. . . . . . . . .
13.2.1
Buffered Data Modes
13.2.2
Unbuffered Qata Modes
13.2.3
Nonstandard Data Mode
13.2.4
Semistandard Data Mode
....... .
13.3
DECTAPE I/O
. . . . . . . . .
. . . .
13.3.1
Monitor Calls for DECtape I/O . . . . . .
13.3.2
Special Argument Lists . . . . . . . . . . . .
13.3.2.1
Using LOOKUP with DECtapes . . . . . . .
13.3.2.2
Using ENTER with DECtapes . . . . . .
13.3.2.3
Using RENAME with DECtapes .
13.4
DECTAPE FORMATS . . . . . . . .
13.4.1
Directory Format . . . . . .
13.4.1.1
Summary of DECtape Directory Block.
·
13.4.1.2
Block-to-File Index
.... .
·
13.4.1.3
List of File Names . . . . . . . . . . . . ·
13.4.1.4
List of File-Extensions . . . .
·
13.4.1.5
File Creation Dates
.... .
·
13.4.1.6
DECtape Label . . . . .
·
13.4.2
Data Block Format . .
·
. ....
13.5
DECTAPE I/O STATUS . . . .
13.1
13~2

vii

13-1
13-1
13-1
13-2
13-3
13-3
13-3
13-4
13-6
13-6
13-7
13-8
13-9
13-9
13-10
13-12
13-13
13-13
13-14
13-15
13-15
13-16

CHAPTER 14
14.1
14.2
14.3
14.4
14.5
14.6
14.7
CHAPTER 15

MAGTAPES (MTA)
MAGTAPE DEVICE NAMES . .
MAGTAPE DATA MODES
MAGTAPE I/O
. . . . .
MAGTAPE I/O STATUS . .
. .
MODES SET BY .TFMOD
READ BACKWARDS (TX01, TM02, AND TX02 ONLY)
PROGRAMMING I/O TO LABELLED MAGTAPES
TERMINALS

16.1
16.1.1
16.1.2
16.2
16.3
16.4
CHAPTER 17
17.1
17.2
17.3
17.4
17.5
CHAPTER 18
18.1
18.2
18.3
18.4
18.5

·
·
.

(TTY) AND PSEUDO-TERMINALS (PTY)

15.1
TERMINAL DEVICE NAMES
. . . . . . . . . .
TERMINAL DATA MODES
15.2
. . . . . . . .
TERMINAL CHARACTER HANDLING
15.3
15.4
BREAK CHARACTER SET
. . . .
15.5
LAT TERMINALS
. . . . . . ..
....
15.6
TERMINAL CLASSES, TYPES, AND ATTRIBUTES
.
15.6.1
Reading and Setting Terminal Class . . .
15.6.2
Reading and Setting Terminal Type
.
15.6.3
Reading and Setting Terminal Attributes
15.6.4
Terminal Characteristics Definitions
15.7
TERMINAL I/O . . . . . . . .
15.8
NON-BLOCKING TERMINAL I/O
. . . .
15.9
TERMINAL PAPERTAPE I/O . '.
15.9.1
Using Terminal Papertape Input .
15.9.2
Using Terminal Papertape Output
15.10
TERMINAL I/O STATUS
15.11
PSEUDO-TERMINALS . . . .
15.11.1
Pseudo-Terminal Names
. . . .
15.11.2
Pseudo-Terminal I/O
15.12
PSEUDO-TERMINAL DATA MODES .
15.13
PSEUDO-TERMINAL I/O STATUS
CHAPTER 16

14-2
14-2
14-4
.
14-4
14-6
· 14-10
14-10

·
·
·
·

15-1
15-1
15-2
15-7
15-8
15-8
15-8
15-8
15-9
15-10
15-11
15-12
15-12
15-13
15-13
15-13
15-14
15-15
15-15
15-17
15-17

LINE PRINTERS (LPT)
LINE PRINTER NAMES .
Controller Names
Unit Names
LINE PRINTER DATA MODES
LINE PRINTER I/O . . . .
LINE PRINTER I/O STATUS
CARD READERS

16-1
16-1
16-1
16-1
16-2
16-2

(CDR) AND CARD PUNCHES

(COP)

CARD DEVICE NAMES
CARD READER DATA MODES .
CARD PUNCH DATA MODES
CARD DEVICE I/O
CARD DEVICE I/O STATUS .
PAPERTAPE READERS

17-1
17-2
17-2
17-3
17-4

(PTR) AND PUNCHES

PAPERTAPE DEVICE NAMES . . . .
PAPERTAPE READER DATA MODES
PAPERTAPE PUNCH DATA MODES
PAPERTAPE I/O
. . . . .
PAPERTAPE I/O STATUS . . . . .

viii

(PTP)

18-1
18-1
18-2
18-2
18-3

CHAPTER 19
19.1
19.1.1
19.1.2
19.2
19.3
19.4
CHAPTER 20
20.1
20.1.1
20.2
20.3
20.4
CHAPTER 21

PLOTTERS (PLT)
PLOTTER DEVICE NAMES
Controller Names
unit Names
PLOTTER DATA MODES
PLOTTER I/O
PLOTTER I/O STATUS

19-1
19-1
19-1
19-1
19-2
19-2

DISPLAY LIGHT PENS (DIS)
DISPLAY LIGHT PEN NAMES
Unit Names
DISPLAY LIGHT PEN DATA MODES
DISPLAY LIGHT PEN I/O
DISPLAY I/O STATUS

20-1
20-1
20-1
20-1
20-3

REMOTE DATA TERMINALS (RDA)

21.1
21.2
21.3
21.4

REMOTE DATA TERMINAL NAMES
REMOTE DATA TERMINAL I/O
REMOTE DATA TERMINAL DATA MODES
REMOTE DATA TERMINAL I/O STATUS

21-1
21-1
21-2
21-2

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

The Software Interrupt Process .
Interrupt Control Block
Packet Header Block
. . . .
·
ENQ/DEQ Request Block
. . . .
Flow Diagram -- I/O Sequence . . . . . . . . . .
The Buffer Structure .
. . . .
.
Flowchart for Buffered Input
. .....
Flowchart for Buffered Output
·
One Buffer in Each of Two Device Chains
. .
Multiple Buffers in Multiple Device Chains
·
One Buffer Moved Back to Free Chain
. . . . . ·
Disk Chain . . . . . . . . . . . . . . . . . .
General Disk File Organization for a File
Structure . . . . . . . . . . . . . . . .
Directory Paths on a Single File Structure
·
Directory Paths on Multiple File structures
LOOKUP on DSK with No Matches
·
LOOKUP on DSK for FILE2
·
ENTER on DSKA for FILE1
. . . . .
·
ENTER on DSK for FILE6 . .
·
ENTER on DSK for FILE2 . . . . . . .
·
ENTER on DSK for FILE7 . .
·
DECtape Buffer . . . . . .
DECtape Format . . . . . . . . . .
DECtape Directory Block
. . . . .
·
Directory Block for FILE.MAC
....
·
First 83 Words on the DECtape of the Directory
Block . . . . . . . . . . . . .
·
Words 83 through 104 of DECtape Directory . . .
Words 105 to 126 of the Directory Block
·
High-Order Three Bits of Creation Date . .
·
Data Block Format
. . . . . . . . . . . .
·

. 6-7
6-10
. 7-2
8-12
11-17
11-26
11-31
11-34
11-38
11-39
11-40
12-8

INDEX
FIGURES

12-3
12-4
12-5
12-6
12-7
12-8
12-9
12-10
13-1
13-2
13-3
13-4
13-5
13-6
13-7
13-8
13-9

12-9
12-13
12-14
12-15
12-16
12-17
12-18
12-19
12-20
13-2
13-9
13-10
13-11
13-12
13-13
13-13
13-14
13-15

15-1

PTY I/O

5-1
5-2
5-3
5-4
6-1
6-2
6-3
6-4
11-1
11-2
12-1
12-2
13-1
14-1
14-2
14-3
14-4
14-5
15-1
15-2

5-10
NSP. UUO Functions. . . . .
. ...
Allowable Combinations of Task Descriptor Values 5-12
5-18
Fields in .NSACH (status variables)
5-19
NSP. Connection States.
Format of .JBINT Intercept Block.
· . 6-5
6-11
Control Flags
...... .
6-12
I/O Interrupt Conditions . . . .
6-12
Non-I/O Interrupt Conditions . .
11-7
Ersatz Devices .
11-11
Data Modes (Bits 32-35 of the file status word)
File Access Protection -- Owner Field
12-5
File Access Protection -- Second and Third Digits 12-6
LOOKUP/ENTER/RENAME Argument Block for DECtape
13-7
14-6
9-Track DEC Dump Mode
14-7
7-Track Dump Mode
. . . . . . .
9-Track Industry-Compatible Dump Mode
14-8
9-Track SIXBIT Mode
14-9
14-9
ANSI ASCII Mode
Terminal Handling of ASCII Characters
15-3
Terminal Characteristics .
· 15-10

· 15-15

TABLES

PREFACE

The TOPS-IO Monitor Calls Manual is a complete reference set for using
the TOPS-IO monitor calls.
The set consists of two volumes:
Volume 1 contains descriptions of the facilities available to the
assembly language programmer through the use of calls to the
monitor.
It details the requirements for performing various
types of I/O,
computation,
and information processing using
monitor-defined symbols and data.
Specific monitor facilities,
such as inter-process communication, programmed interrupts, and
device I/O are ~ach described in relation to the monitor calls
needed to use those facilities.
Volume 2 lists the monitor calls themselves,
in alphabetical
order, including coding sequences for calling the monitor and for
reading data returned by the monitor.
The data may be returned
on a successful completion of the call, or data on the error will
be returned when an error occurs in the attempt to execute the
monitor call.
Volume 2 also contains a list of the GETTAB
Tables, which contain data about the monitor and user jobs.
The
data
stored in these tables is extensive and yet easily
accessible through the GETTAB monitor call.
Finally, Volume 2
contains a glossary of the terms used in both volumes, a detailed
description of the format of an executable file,
and
a
description
of
the
File
Daemon program,
which provides
user-definable file security measures.
Before you attempt to use the TOPS-IO Monitor Calls Manual, you should
have a basic familiarity with the structure, paging mechanisms, and
hardware of the DECsystem-lO.
The TOPS-IO Monitor Calls Manual does
not attempt to describe the monitor on a general level.
You should
also be familiar with the MACRO programming language before you read
this manual.
Specifically, it is recommended that you become familiar
with the following manuals and topics before attempting to use the
TOPS-IO Monitor Calls Manual:
o

The DECsystem-lO MACRO Assembler Reference Manual is very
important to an understanding of the methods for programming
in assembly language on TOPS-IO.
The TOPS-IO monitor calls
are written to facilitate the task of programming in MACRO,
but the bulk of assembly language programming involves the
operations described in the MACRO Reference Manual.

Restrictions and capabilities of higher-level programming
languages on TOPS-IO are not described in the TOPS-IO Monitor
Calls Manual.
If you are programming in a higher-level
language
(FORTRAN, COBOL, and so forth), you should obtain a
copy of the programming language's specific reference manual
written for TOPS-IO.
xi

Facilities and capabilities of software products that run on
TOPS-10 but are distributed as a separate product are not
included in the TOPS-10 Monitor
Calls
Manual.
Many
references to such products (DECnet-10, IBM communication,
and so forth) are made in the TOPS-10 Monitor Calls Manual,
but you need the appropriate product-specific documentation
to use the monitor facilities provided for these products.

The TOPS-10 Monitor Calls Manual is divided into two volumes only
because there is a great amount of information that must be included
in the manual.
Therefore, neither volume can be used without the
other.
Volume 1 describes the facilities your program can access through
requests to the monitor; and contains specific references to calls,
and calling functions; but only in Volume 2 can you find the detailed
lists of functions available through each call, the specific kinds of
data available after the execution of each call, and the restrictions
and requirements for each.
Volume 2 contains detailed documentation of each monitor call,
flag,
argument
block,
and
returned
information,
with
programming
requirements for each call, in a manner similar to the monitor source
file UUOSYM.MAC.
However,
this information is useless without the
knowledge available in Volume 1: the order in which calls must be
made to the monitor,
methods for handling errors, and the types of
information you can use to make your programs interact smoothly with
the monitor.
The TOPS-10 Monitor Calls Manual is intended to be the primary source
of reference information for the interface between user programs and
the monitor.
If you find any errors in the manual, or have difficulty
using the manual for any reason, please detail the problem on the
Reader's Comment Card provided at the end of each volume and mail it
to Digital Equipment Corporation. This important form of feedback is
vital to the accuracy and usefulness of the documentation,
and
complete information about the problem would be greatly appreciated.

xii

CHAPTER 1
INTRODUCTION TO MONITOR CALLS

A program written in MACRO-IO assembly
statements:

language

has

four

types

Pseudo-op statements, such as BLOCK, TITLE,
and RADIX,
are
instructions to the MACRO assembler and do not generate code.

Direct-assignment statements, such as Tl=l and P=17,
resolve
definitions of symbols.
Pseudo-ops and direct-assignment
statements are described in the DECsystem-10 MACRO Assembler
Reference Manual.

Machine instructions, such as ADD, MOVEM,
and JRST,
are
direct hardware instructions. Machine instructions and their
symbols are discussed in
the
DECsystem-l0/DECSYSTEM-20
Processor Reference Manual.

Monitor calls,
such as INPUT,
CLOSE,
and GETSTS,
are
directions to the monitor to perform special services for the
program. Monitor calls, also called UUOs (Unimplemented User
Operations), are described in this manual.

An operation code (opcode) and a symbol representing the name of the
monitor call designates each monitor call.
Use operation codes
(opcodes) to direct the TOPS-I0 monitor to perform I/O and other
services for your program. Opcodes can be divided into the following
groups:
o

Opcode 0 always returns your job to monitor command level,
because opcode 0 is an illegal UUO.
The monitor displays the
following error message, followed by the monitor prompt.
?Illegal UUO at user PC addr

Opcodes 1 through 37 cause the hardware to store the
instruction code and the effective address in location 40,
and to execute the instruction at location 41 in the user's
address space.
The original contents of location 40 are
lost.
This trap allows your program to gain control when
using these opcodes.
These opcodes can be defined by the
system programmer as Local UUOs
(LUUOs).
If your program
executes one of these opcodes accidentally,
the monitor
displays the message:
?HALT at user PC addr

1-1

INTRODUCTION TO MONITOR CALLS

The monitor displays this message because relative location
41 contains a HALT instruction,
unless the contents of
location 41 were changed inadvertently.
The LINK program
provides
the
HALT instruction.
To set or read trap
instructions for an LUUO in a non-zero section, you must use
the UTRP. monitor call. Refer to Volume 2 for a description
of the UTRP. UUO.
o

Opcodes 40 through 100 are the opcodes for monitor calls.
The TOPS-10 monitor defines these opcodes.
They are called
Monitor UUOs (MUUOs).
This manual describes all monitor
calls for TOPS-10. A monitor call is stored at location 424,
the new PC is loaded from location 436 of the user's process
table,
and the processor operates in executive mode.
The
monitor interprets the opcode; then the monitor performs I/O
and other control functions for your program.

Opcodes 101 and 104 cause the monitor to
and display the following message:

stop

your

program

?Illegal instruction at user PC addr
o

Opcodes 102, 103, 106, and 107 are legal only on the KL
processor.
On any other type of DECsystem-10 processor, the
monitor will stop the program and display the following
message if it receives one of these opcodes:
?KL10 only instruction at user PC addr

1.1

MONITOR CALL SYMBOLS

Opcodes 40 through 100 provide the basic set of monitor calls.
The
opcodes and names of these calls are listed in Chapter 22, Volume 2.
Three of these calls (CALLI, MTAPE, and TTCALL) offer extended calls
by using values in addition to the opcode value.
(CALLIs and MTAPEs
use the address field;
TTCALL uses the accumulator field.)
Each
extended call has a symbol that defines its opcode and its value.
These symbols and their full values are also listed in Chapter 22,
Volume 2.
Most monitor calls accept arguments, return values, or both.
Almost
all these arguments and values have symbols defined in the monitor
symbol file for UUOs,
UUOSYM.MAC.
Error codes,
flag bits,
and
interrupt conditions all have symbols defined in UUOSYM.MAC.
The file
MACTEN.MAC contains definitions relating to the hardware, such as the
PC flag bits.
The file JOBDAT.MAC defines the job data locations.
User programs should be written to reference all system values
symbolically by these three universal files.
That is, a SEARCH
statement should appear near the beginning of the program to search
UUOSYM,
MACTEN,
or JOBDAT.
Refer to the TOPS-10 MACRO Assembler
Reference Manual for a description of universal files and the SEARCH
pseudo-op.
Some of the symbols represent codes that tell the monitor what is
being specified; others are masks that you can use to isolate or test
a returned value.
For example,
the symbol IO.ERR is defined as
follows:
IO.ERR==17B21
This defines a 4-bit field in the I/O status word,
allowing you to
logically AND the returned file status word with the value IO.ERR to
mask out all other bits of the word.
1-2

INTRODUCTION TO MONITOR CALLS
1.2

PROCESSING MODES

The DECsystem-l0 hardware defines three processing modes: user mode,
executive mode,
and user I/O mode. Normally, programs run in user
mode, which allows the processor to protect and map data in core
successfully.
The processor will switch from user mode to executive
mode when a monitor call is issued.
The monitor controls execution
from that point until the monitor call finishes.
User I/O mode, a
privileged alternative to user mode, provides the program with direct
access to I/O devices.
This allows real-time device drivers to run
under TOPS-I0 in user mode.

1.2.1

User Mode

The majority of user programs execute in user mode.
prrgram, the processor:

For

user-mode

Performs automatic memory protection and mapping.

Passes control to the monitor if a monitor call or an illegal
instruction
(including HALT)
executes.
In this case, the
processor enters executive mode.

The hardware traps to location 40 in the job data area
less than 40 (but not 0) executes (see Chapter 3) .
User mode requires an assigned area
instructions are:

memory.

Illegal

opcode

user

mode

I/O instructions
(opcodes 700 through 777)
except those
giving a device code greater than 734. KSI0 I/O instructions
are all illegal.

All unimplemented opcodes
(those
instructions or monitor calls) .

Any JRST instruction with an accumulator greater
except JRST 5 (XJRSTF) and JRST 15 (XJRST).

not

defined

If your program executes an illegal instruction, one of the
messages prints (and your program stops) :

machine
than

following

?HALT at user PC addr
?Illegal instruction at user PC addr
Where:

addr is the memory location of the illegal instruction.

For the HALT message above, you can continue the execution of your
program at the target address of the JRST 4, (HALT) by giving the
CONTINUE or CCONTINUE monitor command
(see the TOPS-I0 Operating
System Commands Manual). For the "illegal instruction" message, you
must correct your program and begin execution again.

1.2.2

Executive Mode

A user program switches to executive mode to perform a monitor call
when it encounters an illegal instruction, or on a HALT instruction.
The monitor always executes in executive mode,
giving it special
memory protection and mapping.

1-3

INTRODUCTION TO MONITOR CALLS

1.2.3

User I/O Mode

A program executes in user I/O mode if bits PC.USR and PC.UIO (bits 5
and 6)
in the program counter
(PC) word are set.
These bits are
defined in the MACTEN.MAC symbol file.
I/O mode is the same as user
mode,
except that the hardware allows any opcodes or instructions to
be executed except a HALT (JRST 4) .
User I/O mode provides some protection against partially debugged
monitor routines, and allows device service routines to be executed as
user jobs. Realtime programs execute in user I/O mode, allowing them
to
gain
direct
control
of
devices.
Refer
to
the
DECsystem-10/DECSYSTEM-20 Processor Reference Manual for information
about processing modes, or to Chapter 9 of this manual for information
about programming real-time devices.
To execute in user I/O mode, your job must have the JP.TRP
(trap)
or
JP.RTT (realtime) privilege set, and you must successfully execute one
of the realtime monitor calls TRPSET or RTTRP.
When your program
issues a RESET monitor call or clears it with a JRSTF, user I/O mode
ends.

1-4

CHAPTER 2
MEMORY

Two distinct conventions allow you to reference DECsystem-10 memory:
physical memory addressing and virtual addressing. Physical memory
defines the physical limits of the CPU addressing space,
and a
physical address refers to an exact physical location within the
memory unit of the processor.
However,
TOPS-10 is a timesharing
system,
characterized by the capability of serving multiple user
programs simultaneously. A single program can be loaded into several
different parts of memory that need not be contiguous.
Therefore,
user programs do not normally reference actual physical locations in
memory.
Programs reference a self-contained set of "virtual" addresses. While
the program is running,
the virtual addresses are translated into
physical locations that can be referenced by the hardware.
TOPS-10 provides each user with 512 pages of addressable virtual
memory on the KS processor, and 16384 pages of addressable virtual
memory on the KL processor. Although the conventional usage of the
term "core" on TOPS-10 often is used to mean any type of memory,
throughout this chapter, references to "memory" are to virtual memory
and references to "core" are to physical memory.
The processor protects the memory
needed
for
monitor-related
functions,
and the memory assigned to each job.
It manages the
assignment of memory space to each user, and controls the swapping of
jobs into -and out of core.

2.1

MEMORY ALLOCATION

Core memory is a physical and therefore finite space measured in
36-bit words,
512-word pages,
or 1024-word K. Virtual memory uses
these three measurements, and also 512-page sections.
There are 32
(decimal)
sections on the KL.
They are referred to as sections 0-37
(octal). A user's maximum virtual address space is 512P
(pages)
on
the KS, and 16384P on the KL.
To accommodate all the users in the timesharing environment,
TOPS-10
removes each job from core memory and places it in a special disk area
temporarily to make room for another job.
This function is called
"swapping." You can prevent a program or program segment from being
swapped out by using the LOCK monitor call to lock your job in memory.
(This requires that the LOCK privilege be set in the privilege word in
GETTAB Table .GTPRV.) To use realtime devices, you need to LOCK your
job in memory.

2-1

MEMORY

A user job need not be entirely in memory or on disk all at once.
Your program can explicitly transfer individual pages of its virtual
address space from core memory into and out of the working set.
The
working set is the collection of pages in core that are immediately
accessible to a job, and those in core with the access-allowed bit
off. Alternatively, if your program exceeds the current physical page
limit for your job, it will be subject to paging by the monitor.
Memory limits and paging are discussed later in this chapter.
The
TOPS-I0 monitor itself always remains in memory.
On the KS, if you need to exceed the virtual memory limit of 5I2P, you
must use an overlay structure.
On the KL processor, if your program
requires more than the virtual memory limit of I6384P, or you do not
want to use extended addressing for a program greater than one
section, you can construct your program using an overlay structure.
Using overlays, your program can restrict its current virtual space to
only a portion of the entire amount of references it may require.
For
information about using overlays, refer to the TOPS-I0 Link Reference
Manual.
--The monitor enforces the following limits on memory space:
Symbol

Application

GPPL

(Global Physical Page Limit)
core available to any user.

GVPL

(Global Virtual Page Limit) is the maximum amount of
virtual memory available to any user.
GVPL is 5I2P on
the KS and I6384P on the KL.
You may change this limit
using the privileged SETUUO function .STMVM.

MPPL

(Maximum Physical Page Limit) is the maximum amount
core available to a given user.

MVPL

(Maximum Virtual Page Limit) is the maximum
virtual memory available to a given user.

CPPL

(Current Physical Page Limit) is the current amount of
core that is available to the user, a value that must
not exceed the user's MPPL.

CVPL

(Current Virtual Page Limit) is the current amount of
virtual memory available to the user, a value that must
not exceed the user's MVPL.

is the maximum

amount

The monitor also maintains values to measure the amount of space
currently being used and currently available to your job.
Those are:
CPPC

(Current Physical Page Count) is the number of physical
pages in core that are being used by your job.

CVPC

(Current Virtual Page Count) refers to the number
virtual pages that are being used by your job.

The monitor itself has a virtual address space greater than 256K
because it uses KL-paging, the default paging method for monitors on
KL and KS systems.
Under KL-paging, multiple sets of 256K words each
can be used by the monitor.
Each set is called a "section." The KL
processor supports up to 32 sections. Most of the monitor executes in
Section o.
KL-paging allows the monitor to refer to code and data in
non-zero sections.
Refer to the DECsystem-I0/DECSYSTEM-20 Processor
Reference Manual for more information about KL-paging.

2-2

MEMORY
The user core allocation cannot exceed MPPL, but you can adjust your
program's limits from 0 to MPPL by using various functions of the
SETUUO.
You can set the size of CPPL to limit the physical size of
your job. The sign bit of CPPL is symbolized as ST.VSG.
If this bit
is off, the limit is interpreted as a guideline by the page fault
handler; if the bit is on, the value is interpreted as a strict limit.
Use the CPPL word to control paging for your job.
If your job exceeds
CPPL,
the monitor will initiate paging for your job by using the
virtual memory software.

2.2

USER-MODE EXTENDED ADDRESSING

User-mode extended addressing gives you access to all 32 sections of
virtual memory on the KL processor.
30-bit addressing allows you to
reference any address in the 32 sections. Use extended addressing in
situations where your program or data requires more than one section
of virtual memory.
Your program may reference any section from any non-zero section.
However,
you may not reference a non-zero section from Section 0,
unless the section has been mapped together with
Section
O.
Generally, however, if your program requires inter-section references,
do not execute it in Section O.
When using user-mode extended addressing, make certain that the UUO
argument list does not cross a section boundary.
If it does, the
argument list will wrap around to the beginning of the same section,
overwriting the previous contents of those addresses, instead of
continuing into the next section.
To help you identify section and
address within the section more easily, use the following format when
writing the address:
section"address
There are four ways to run
Section O.
They are:

your

program

section

other

than

Using the XJRST or XJRSTF instruction to place your program
in an extended section.
See the DECsystem-lO/DECSYSTEM-20
Processor Reference Manual for information about
these
instructions.
The addresses in the program become thirty
bits in the form:
section,,18-bit addr.

Placing a section number before a page number in any UUO that
accepts page numbers as arguments.
These UUOs include PAGE.
and IPCFR ..

Supplying a 30-bit argument to a UUO which allows extended
addressing.
UUOs that accept thirty-bit addresses include
CTX., NSP., and ETHNT .. Note that the value in the AC is
always interpreted as a global address for these UUOs,
regardless of the section in which the UUO is executed.

Formatting the core argument word to the GETSEG, MERGE,
or SAVE UUO to include a section number.

2-3

RUN,

MEMORY
2.3

USER MEMORY

You can exert considerable control over the functions of the monitor
as it services your program and memory space.
However, it is first
necessary for you to understand the interaction of the monitor and
your program.
Before the monitor can run a program, it must be
compiled or assembled, and loaded into core.
This is discussed in
more detail in Chapter 3.
The LINK program loads compiled programs (.REL files) into memory.
If
you save the core image of the loaded program, it is written to disk
as an executable (.EXE) file, and need not be processed again by LINK.
You can place an .EXE file into core (ready for execution) by using
the GET or RUN monitor command.
(See Chapter 3.)

2.4

CONTROLLING PROGRAM SEGMENTS

Programs that are loaded into memory can be divided into high and low
segments.
Every executable program has a low segment (lowseg). A low
segment is private. A program can always modify its own low segment.
A program can also have one or more high segments
(hisegs).o
By
default,
high segments start at virtual location 400000, and are
either private or sharable.
Sharable high segments can be used by
more than one job.
By default,
the monitor write-protects high
segments so that no users can modify them.
However, the owner of the
file can clear the write-protect bit, allowing the program to modify
the hiseg.
Programs written in a high-level language such as FORTRAN commonly use
a sharable high segment. As an example of a program using a single
sharable high segment, suppose several users are executing FORTRAN
programs.
Each user has a low segment, containing most of his FORTRAN
program.
However, all FORTRAN users share the same high segment that
contains the FORTRAN object-time system FOROTS.
As an example of a program using multiple sharable high segments,
these same FORTRAN users might also share a second high segment
containing FSORT,
the FOROTS-callable version
of
SORT,
which
implements the SORT built-in for FORTRAN-IO.
Using sharable high
segments conserves memory space used by programs that will not be
modified.
If your program uses multiple high segments,
you must use the
SEGOP. UUO to create and control these segments.
The SEGOP. monitor
call provides the same functions for multiple high segments as the
separate CORE,
SETUWP,
GETSEG,
~nd REMAP monitor calls provide for
controlling s~ngle high segments. You may also use the SEGOP. UUO to
control single high segments,
or you may use the separate calls
described in the following sections.
The SEGOP. UUO functions, the monitor calls to which they correspond,
and a brief description of the action they perform, are listed below.
Monitor Call

Action

SEGOP. UUO Function

CORE

Dynamically changes CORE
allocation of a low or high
segment.

.SGCOR

GETSEG

Create a high segment.
Replace a high segment.

.SGGET
.SGREL plus .SGGET

2-4

MEMORY
SETUWP

Sets or clears the high
segment's write-protect bit.

.SGSWP

REMAP

Create a high segment from
already-existing memory in a
program's low segment.

.SGRMP

The following sections describe the monitor calls that allow you to
control
the allocation,
accessibility,
and contents of program
segments.
Remember that you must use the SEGOP. UUO to manipulate
multiple high segments.

2.4.1

Adjusting the Size of Segments

The CORE monitor call allows you to dynamically change the core
allocation of your program's low segment and a single high segment.
You cannot change the core allocation of segments or programs that are
locked in core.
You should use separate CORE calls to change the sizes of the low and
high segments to ensure that your program does not exceed its core
limits. Memory that is allocated by CORE will be cleared before it is
made available,
to ensure privacy of user data. A CORE UUO function
that does not alter the size of the program, or which decreases the
program size,
will clear any non-contiguous pages.
You can use the
CORE monitor call to eliminate a single high segment,
thus allowing
you to create a new high segment.

2.4.2

Merging Low Segments

You can merge portions of an .EXE file with the low segment
program that is currently in memory by using the MERGE. UUO.

2.4.3

the

Writing Into High Segments

You can set or clear the high segment write-protect bit for your
program's high segment by using the SETUWP monitor call. After the
bit is cleared, you can modify your job's high segment.
You can
replace or create a high segment for your job using the GETSEG call to
read a hiseg from an
.EXE file or the REMAP call to convert a
contiguous portion of the low segment into the high segment.
The GETSEG monitor call replaces the current program's high segment
with a new high segment from another .EXE file.
The low segment of
the .EXE file, if any, is not changed.
This high-segment replacement
is useful for sharing data,
overlays,
and runtime routines.
The
GETSEG monitor call accomplishes this in a manner similar to that used
by the RUN monitor call (refer to Section 2.4.1.).
You can create a high segment from already-existing memory in your
program's low segment by using the REMAP monitor call.
Use REMAP to
specify the virtual address where you want the hiseg to start.
This
allows you to define a contiguous portion of the low segment as the
high segment.
The specified portion of the low segment is removed and
placed at the address in the REMAP call, which is the new hiseg origin
address.

2-5

MEMORY

If your job uses multiple high segments, use the
.SGGET function of
the SEGOP. monitor call to create an additional high segment for your
job.
.SGGET creates a new high segment without discarding any
previous high segments.
In order to replace one high segment with
another, you must first create a new one using .SGGET and then release
the old one using the function
.SGREL.
To convert a contiguous
portion of the low segment into a
specified high segment,
use the
.SGRMP function of the SEGOP. UUO.
.SGRMP will create a new high
segment without discarding any previous segments.

2.4.4

Testing for a Sharable High Segment

The bit SN%SHR in GETTAB Table .GTSGN is set for each job that has one
or more sharable high segments.
The following code sequence shows how
to use this bit to determine whether your own job's high segment is
sharable.
Note that
-1 is used here for the job number to refer to
your own job.
MOVE
GETTAB
JRST
TLNN
JRST
JRST

2.4.5

ACl, [XWD -1, .GTSGN]
ACl,
ERROR
ACl, (SN%SHR)
NOTSHR
SHAR

;Set up GETTAB
;Get hiseg parameters
;GETTAB failed
;Is it sharable?
;No
;Yes

Finding the Origin of a High Segment

The usual origin for a program high segment is location 400000;
however,
the origin can be at a different location.
If you need to
find the origin for a program's high segment (for example,
to access
the vestigial job data area), you can get the address from the GETTAB
Table .GTUPM.
The following example shows how to obtain the high segment origin.
Note that
-2
is used here for the segment number to refer to the
program's own high segment.
MOVE
GETTAB
JRST
HLRZ
JUMPE
MOVEM

2.4.6

AC, [XWD -2, .GTUPM]
AC,
NOHIGH
AC,AC
AC,NOHIGH
AC,HIORGN

;Set up GETTAB
;Get origin
;GETTAB failed
;Set up origin
;If 0, no high ~e~ment
;Store hiseg or~g~n
;Code for no hiseg

Modifying a High Segment and Meddling

The monitor sets the write-protect bit for each new high segment.
You
can clear this bit using the SETUWP monitor call if your program uses
a single high segment.
If your program uses multiple high segments,
use the .SGUWP function of the SEGOP. monitor call.
You can increase
or decrease the shared core using either the CORE monitor call if your
program uses a
single high segment, or the .SGCOR function of the
SEGOP. monitor call if your program uses multiple high segments.

2-6

MEMORY

These calls are legal from either the
following is true:

low

high

segment

the

high

You have write privileges for the file from
segment was loaded.

The segment has not been "meddled." Meddling occurs when a
program attempts to modify a sharable hiseg, because such
modifications might interfere with the other jobs using the
hiseg.

A sharable high segment is considered to be
following is true:

meddled

which

any

the

The program was started with a RUN monitor call that
specified an offset start address other than 0 or 1, or with
a START or CSTART command that supplied an address.

The D (deposit) monitor command was used.

The high segment was obtained with a GETSEG monitor call,
the .SGGET function of the SEGOP. monitor call.

It is not considered meddling if you perform any of the above commands
or calls with a nonsharable high segment.
If you have privileges to write to the file from which the sharable
high segment carne,
you can use the D monitor command and the SETUWP
and CORE calls for that high segment without meddling.
For a program
that uses multiple high segments, you can use the .SGSWP and .SGCOR
functions of the SEGOP. monitor call.
You can write a program that
accesses a sharable high segment using the GETSEG monitor call, and
then turn off the write-protect bit with the SETUWP call.
For a
program that uses multiple high segments, use the .SGGET function of
the SEGOP. monitor call to access a specified high segment, then turn
off the write-protect bit of the specified segment with the .SGSWP
function.
When a sharable program has been meddled, the monitor sets the meddle
bit for the meddling user.
If the user attempts to clear the
write-protect bit with a SETUWP (or .SGSWP when there is more than one
high segment)
monitor call,
or to change the high-segment core
assignment with a CORE monitor call (or .SGCOR when there is more than
one high segment), without removing the hiseg completely, the monitor
takes the error return.
If the meddling user attempts to modify the
high segment with a D monitor command,
the monitor prints the
following message:
?Out of bounds
Whenever the hiseg has been meddled, the monitor resets the
write-protect bit to protect the high segment.

user-mode

If you are suitably privileged, you can supersede a sharable high
segment.
When you use a CLOSE, OUTPUT, or RENAME monitor call, or
some of the functions of the FILOP. UUO, on the file from which the
sharable high segment was initialized,
the monitor zeros the word
containing the segment name in the GETTAB Table
.GTPRG.
Jobs
currently using that high segment can continue to do so, but after
those jobs are completed (that is, when the segment becomes dormant),
the monitor deletes that segment. Meanwhile, new users are able to
share the new (superseding) segment.

2-7

MEMORY

If your program modifies a sharable hiseg,
you are responsible for
coordinating the changes with other users of the hiseg.
Remember thdt
your program can be interrupted within the execution of instructions
that
require multiple services,
such as monitor calls,
and a
concurrent user program can be started at that time.
On
a
multiple-CPU system,
your program can be running simultaneously with
another user program.
Generally, when modifying a shared hiseg,
you
should refer to shared data with non-interruptable instructions, or
under the protection of an interlock such as that provided by the
ENQ/DEQ facility (see Chapter 8) .
Because a sharable hiseg can exist on the swapping space after all
users have released it,
your program must be prepared to handle
inconsistencies in data or "stale" interlocks left by previous user
programs that ended prematurely.

2.5

RUNNING A PROGRAM

The RUN monitor call transfers control to another program by replacing
both segments of the current program with the specified program, and
starting execution of that program at its normal start address or at a
specified offset from the start address.
The new program completely
replaces the calling program, so that there is no return to the
calling program (unless you RUN it later).
When the RUN monitor call is executed, the monitor clears all of your
job's memory.
Your programs,
however, should not assume that this
action will occur.
You must initialize memory to the desired values
to allow your programs to be restarted by the CTRL/C and START
sequence.
If you want to call a program from a system library,
your program
should call it by using device SYS, and a zero project-programmer
number.
The extension you specify for these programs should also be
zero.
The RUN UUO executes a RESET monitor call,
functions) releases all user I/O channels.

which

(among

other

The RUN call uses the following information in its ac:
start-addr-offset"addr
Where:

start-addr-offset is the offset to the starting address of the
program that is being called.
addr is the address of the first word in the RUN UUO
block.

argument

Before the monitor transfers control to the program you call, it adds
the program's starting address to the left half of the value in the ac
and starts the program at this address.
If you set the starting
address offset to be anything other than 0 or 1, you are considered to
be meddling with the program, unless the program being executed is an
execute-only program for your job. For execute-only programs, the
monitor ignores any value other than 0 or 1.

2-8

MEMORY
2.5.1

Functions of RUN and GETSEG

To successfully program the RUN monitor calIon systems of all sizes
and for programs whose size' is not known at the time of the RUN
monitor call's execution you must understand the
sequence
of
operations initiated by the RUN monitor call. Note that the RUN
monitor call can be executed from either the high or the low segment.
Before calling a new program with the RUN monitor call,
you should
change your low segment core allocation to one page, and delete your
high segments (if any) .
The GETSEG and RUN monitor calls perform the following functions:
1.

Using the file name you specify in the argument block,
the
monitor searches for a sharable high segment that is already
in core that has the same name as the program you specified.
If a sharable high segment already exists, it is attached to
your job.
If there is no existing sharable high segment,
the monitor
looks up the program on disk, searching for the same file
name with the extensions .EXE, .SHR, and .HGH, in that order.
If it finds a file with one of these extensions, the monitor
loads the high segment of the file into memory, starting at
the high end of your current low segment.
If it does not
find a file, it goes to Step 5.
It then remaps the hiseg, placing the
.JBHGH location.

hiseg

origin

the

However, if the current low segment contains any pages that
would conflict with the new high segment, the monitor call
takes the error return, with error code 31 in the AC.
2.

Then the monitor adjusts its internal data base to include
the new information.
Either a new user for the sharable high
segment or a new high segment must be added.
(If the UUO was
a GETSEG, the monitor returns control to the user program at
this point.)

Information from the vestigial job data area is copied into
the low segment's job data area.
The vestigial job data is
always loaded into the high segment (see Chapter 4) .

Part of the job data area is the .JBCOR word.
If the left
half of .JBCOR is less than or equal to 137, the monitor does
not have to read data into the low segment because it is a
null low segment.
Then the monitor reads the right half of
.JBCOR to determine how much space to allocate for the low
segment.
For a null low segment, control is passed to the
user program at this point.

2-9

MEMORY

If the left half of .JBCOR is greater than 137,
the monitor
loads the program's low segment, using one of the following
procedures:
o

If the original file contained both segments, the monitor
continues reading the currently open file, loading the
data from its low segment into memory starting at
location 140.
The user program is started.

If the original file contained only the high segment, the
monitor looks up the file using the same file name and
one of the extensions .EXE, .SAV, .LOW, or the extension
specified in the argument block, in that order.
If found,
the file is opened and read into memory
starting at location 140.
The user program is started.
If a low segment file is not found, the monitor returns
control to the user, giving an error return.
The monitor
handles the error in either of the following ways:
a.

If the call came from the high segment, or if there
is a HALT in the error return after the UUO, the
monitor prints one of the following error messages:
?Not a save file
?filename.SAV not found
?Transmission error
?LOOKUP failure n
?nP of core needed
?No start adr

If the call came from the low segment and there is no
HALT in the error return, the monitor puts the LOOKUP
error code into the ac and passes control to the user
program.

The GETSEG monitor call works like the RUN monitor
the following differences:

call,

except

for

No attempt is made to read the low segment of the file.
If
an
.EXE file is found, only the pages representing the high
segment will be merged into the user's address space.

The only changes made to the Job Data Area are:
1.

the left half of .JBHRL is set to zero.

the right half of .JBHRL is set to the highest legal high
segment address.

.JBSA and .JBREN in the Job Data Area are set to zero by
the monitor if they point to a high segment that is being
removed.
If this should occur, the following message is
printed on your terminal when the START or REENTER
command is issued:
?No start adr

If an error occurs, control is returned to the error return
location, -unless the left half of the error return location
contains a HALT instruction;
in this case,
the monitor
displays an error message and the program is HALTed.

2-10

MEMORY

2.5.2

The call should be made from the low segment unless the
normal return coincides with the starting address of the new
high segment.

User channels are not released.
Channel 0,
however,
released because it was used by the GETSEG monitor call.

The contents of the job's
Therefpre,
any AC used
invalid.

accumulators
as a stack

are not preserved.
pointer will become

Reading Command Fi1es

Programs that accept commands can input those commands from a terminal
or a file, depending on how the program is started.
If a program is
started at the normal starting address (.JBSA), it should display a
prompt, such as an asterisk, and read commands from the terminal input
buffer. with a CCL entry, commands are read from a file on disk or
from a list of commands stored in memory.
CCL entry is determined b¥ the argument to the RUN monitor call.
If
the RUN UUO has a 0 ~n the left half of the ac, the normal start
address will be used.
If the RUN UUO has a 1 in the left half of the
ac,
the CCL entry will be used; the program is started at the address
found in .JBSA+1, and should read commands from TMPCOR or from an
indirect command file on disk.
TMPCOR is the name for the section of
memory that is searched first.
The format of a command file is
defined by the program that must read it.
The TMPCOR area is limited in size; therefore,
programs should also
search for the command file on disk.
If TMPCOR does not contain the
command list, it should contain a file specification for an indirect
command file.
The file specification is usually preceded by @ to
indicate indirection. Note that the PIP program expects the @ to
follow the file specification. By convention, the file name on disk
is of the form:
nnnabc.TMP
Where:

nnn is your job number in decimal,
including leading zeros.
The job number is included to allow users to run more than one
job under the same PPN.
abc is usually the name looked for in TMPCOR.

For example:
009PIP.TMP
039MAC.TMP

;Job 9 commands to PIP
;Job 39 commands to MACRO

These files are temporary and will be deleted by the LOGOUT program.
If a command file does not exist, or the program does not support CCL
entry, the program should display a command prompt and accept commands
from the terminal.

2-11

MEMORY
2.6

CONTROLLING PAGES

By using the PAGE. monitor call, you can manipulate pages in your
program's virtual address space and manipulate or obtain data about
those pages.

2.6.1

Handling Page Faults

When your program refers to a page of memory that is either not in
physical memory or has the access-allowed bit turned off, a page fault
occurs. Program control then passes to a page fault handler.
The
page fault handler can be either the system's internal page fault
handler or your program's page fault handler, if you have defined one
by setting .JBPFH in JOBDAT.
(See Chapter 4 for more information on
.JBPFH.)
Refer to Section 2.6.3 for information on building your own
page fault handler.

2.6.2

The System's Page Fault Handler

Unless your program has its own page fault handler, the monitor
its internal page fault handler when a page fault occurs.
default page handler selects the page to swap out of memory to
room for a needed page that is not in memory.

uses
This
make

Each page has an access-allowed bit associated with it.
Periodically
the page fault handler clears every page's access-allowed bit. When
the page fault handler clears the access-allowed bit,
a page fault
occurs the next time your program references that page. After the
reference is made,
the monitor sets the access-allowed bit and
execution of the program continues.
The system's page fault handler selects the page that has been in core
the longest since the last reference to it.
This selection method
assures that frequently-referenced pages are likely to remain in
memory,
while seldom-referenced pages are likely to be paged out
sooner.
By using an age-ordered list and a periodic check of the
access-allowed bit,
the page fault handler pages on a modified
first-in/first-out basis.

2.6.3

Building Your Own Page Fault Handler

You can override the system's page fault handler by setting the
location
.JBPFH to point to your program's page fault handler (left
half = end address and right half = start address).
Setting .JBPFH to
zero returns your program to using the system's page fault handler.
If the area of core containing your own page fault handler is
destroyed,
a reference to the page fault handler will result in an
illegal memory reference error.
NOTE
Use the system's page fault handler if your program
will
execute
in a non-zero section or contain
thirty-bit addresses.
The format given below for your
own page fault handler can accept only eighteen-bit
addresses, and is restricted to programs executing in
Section O.

2-12

MEMORY
The format of your page fault handler must be:
Word

Symbol

Contents

o
1

.PFHJS
.PFHOP

.PFHFC

.PFHVT
.PFHPR
.PFHPV

The instruction "JRST .+.PFHST".
Old PC and flags.
That is, the flag/PC word used for
JRSTF, same as .JBTPC, .JBOPC, and so on.
Fault word, filled in by the monitor on each page
fault.
The fault word is described below.
virtual time.
Paging rate.
Highest PSI vector in use (in left half); address of
PSI vector (in right half) .
Version number of the page fault handler.
Reserved for runtime statistics.
Origin of the page fault handler (first instruction)

.PFHUR

6
7-11
12

.PFHST

The fault word (.PFHFC) contains the following information:
Bits

Symbol

Contents

PF.HCB

1
2-8
9-17
18-35

PF.HBS

Working set was changed by a routine other than
page fault handler.
Working set has been scrambled.
Reserved for use by DIGITAL.
Page number of the page causing the fault.
Fault code, described below.

PF.HPN
PF.HFC

this

The fault code (PF.HFC) is one of the following:
Code

Symbol

Meaning

.PFHNA

.PFHNI
.PFHUU

.PFHTI

.PFHZI

.PFHZU

Page is inaccessible (access-allowed bit is cleared)
but in core.
Page has been paged out and is not in memory.
A page containing a monitor call argument has been
paged out.
This is a monitor-detected fault.
A virtual timer trap has occurred.
The monitor will
cause this kind of trap every n units of time, if
requested by the
.STTVM function of the SETUUO
monitor call.
The page has been allocated,
but is a
zero page,
occurring after a user instruction.
The page has been allocated,
but is zero after a,
monitor call is executed.

2.7

LOCKING AND UNLOCKING A JOB IN MEMORY

When a job is "locked" in memory, it is not available for swapping.
You can lock a job in user memory by using the LOCK monitor call.
You
may want to lock a job for any of the following reasons:
o

The job is a realtime job that should respond
promptly, without the delay of swapping.

The job uses a display device that must refresh
from a buffer without flickering.

the

display

The job analyzes system
quickly.

invoked

The job uses the SNOOP. UUO.

performance,

2-13

and

must

interrupts

MEMORY
You must have the lock privilege to use the LOCK UUO.
the JP.LCK bit in GETTAB Table .GTPRV.

This is set

Using the LOCK call, you can lock either or both program segments into
memory,
and you can specify whether the memory must be physically
contiguous.
A job can be unlocked (made available for swapping) using either the
RESET or UNLOK. monitor call.
Execution of a RESET monitor call
automatically performs several other functions.
You may want to
unlock the job without resetting everything.
You can do this by using
the UNLOK. monitor call.
The UNLOK. call allows you to unlock either or both segments of your
job.
Note,
however,
that a
locked high segment that is shared by
several jobs will not be unlocked until the SN%LOK bit in the GETTAB
Table
.GTSGN is off for all those jobs.
The shared high segment will
not be unlocked until every job sharing the segment has issued either
a RESET or UNLOK. monitor call for that segment.

2-14

CHAPTER 3
JOB CONTROL

This chapter discusses
initializing,
starting,
suspending
programs,
timing considerations,
and
pertaining to jobs.

3.1

stopping,
and
other functions

EXECUTING A PROGRAM

After you write a program, it must be compiled and loaded before it
can be executed.
The compilation process depends on the programming
language used in the source program, but the COMPILE monitor command
will initiate compilation of any program in a supported language.
Refer to the TOPS-10 Operpting System Commands Manual for information
about the COMPILE command and all monitor commands.
The compiled program exists on disk in relocatable format; this stage
of program preparation is known as the .REL file.
The LINK program
(the linking loader) processes the
.REL file by resolving symbol
definitions and by loading the program into user core memory. After
it has been loaded successfully, the program is ready to be executed
or saved in its executable format.
LINK offers switches to initiate
execution or saving.
LINK is described in detail in the TOPS-10 LINK
Reference Manual.
Each time the source program is changed, it
reloaded before it can be executed.

must

recompiled

and

Once the program is loaded into memory,
execution
can
start
immediately,
but it is more common to write the core image of the
program to disk, thus saving it in executable format as an .EXE file.
This
.EXE file can be loaded from disk and executed using the RUN
monitor command.
Programs can be called from within another program
monitor command level.

well

from

any

the

RUN loads an .EXE file from disk and starts execution at
address given by .JBSA in the job data area.

the

EXECUTE starts execution of a specified program at its normal
start address.
This command loads the program from its .REL
file.
If no .REL file exists, EXECUTE compiles the source
file and then loads the .REL file.

3.1.1

Starting a Program

You can start a program from the monitor level by
following monitor commands:

3-1

using

JOB CONTROL
o

START starts (or restarts)
execution
program at its normal start address.

already-loaded

CSTART starts execution of an already-loaded program at its
normal start address,
but leaves the terminal at monitor
level.

DDT starts execution of the debugging program specified by
the
right
half of
.JBDDT.
(Refer to Chapter 4 for
information about JOBDAT locations.)

You can continue execution of an already-loaded program from
level by using either of the following monitor commands:

monitor

CONTINUE continues execution of an already-loaded program
the place where the program was interrupted.

CCONTINUE functions like the CONTINUE command, except that it
leaves your terminal at monitor level.

You can start a program from within another program with
following monitor calls:

any

the

RUN transfers execution control to the specified program.
The calling program is overwritten in core, and control is
passed to the new program.
The RUN call allows you to
specify an offset to the normal starting address.

GETSEG replaces the high segment of the calling program
a specified high segment.

MERGE. merges specified pages of an .EXE file
segment of the current program.

into

the

with
low

The RUN and GET monitor commands are often used in the same session.
Therefore,
for these commands, the monitor saves the argument to the
command (that is, the program name) in a GETTABable form.
If you use
one of these commands without an argument, the saved argument is
assumed by the monitor.
To read the argument that is currently being
stored, see GETTAB Tables 135-137 and 145-151.

3.1.2

Stopping a Program

You can stop execution of your program by using any of
commands or monitor calls:

the

following

CTRL/C, if your program is waiting for terminal input, or if
your program is running but your terminal is at monitor
level.

Two CTRL/Cs, if your program is not waiting
input, but is attached to your terminal.

The HALT monitor command.

The EXIT monitor call in your program code.

The LOGOUT monitor call in your program code.

The FRCUUO monitor call in your program code.

If a fatal error occurs
program.

for

terminal

(including a HALT), the monitor will stop your
3-2

JOB CONTROL
3.1.3

Suspending a Program

You can suspend execution of a program until some event occurs,
or
until some time has elapsed, by using the following monitor calls in
your program:
o

The HIBER monitor call suspends execution of your program
until some specified event occurs or until a specified amount
of time has elapsed.
The program will be continued by the
monitor.

The SLEEP monitor call suspends execution
until a specified time has elapsed.

You can also use the PSI system, which can interrupt
particular event occurs.
(Refer to Chapter 6.)

3.2

your
a

job

program
when

CONTROLLING MULTIPLE JOB CONTEXTS

The core image of a job, some system resources such as ENQ/DEQ locks,
some terminal parameters, and monitor overhead data constitute a job's
context.
The CTX. UUO allows you to save and retrieve information
about contexts, and manipulate them in ways that give you control over
multiple jobs. For instance, using contexts, you can halt and save a
running program to perform some other task, and later restore the
context and continue the program.
For jobs that have set a program to
run automatically at login, you must use the RUN. UUO from within the
captive program to transfer execution control to another program.
Using CTX., you can create two kinds of contexts:
inferior and
parallel. Creating either an inferior or a parallel context halts the
current job and saves the current context. However, when you work in
an inferior context,
returning to the original (superior) context
causes the system to automatically delete the inferior context.
When
you create a parallel context, it co-exists with the original context
until you explicitly delete it.
You may switch between parallel
contexts without deleting any of them.
Under the system default, you
may work with a maximum of four parallel and/or inferior contexts at
anyone time.
This value may be changed in the user's accounting file
entry.
Once the system has swapped a
job's core image out to disk,
context is considered idle.
The items saved in a context are:
o

Program run; from physical SYS bit (JB.LSY from JBTLIM(J»

Monitor mode bit:

SAVCTX word in the PDB:

Break mask words:

PSI data base address:

All IPCF-related words in the PDB

Enqueue block chain address:

Selected words in the TTY DDB

LDLCOM from LDBDCH(U)
.PDSCX(W)

LDBBKM(U), LDBBKB(U), and LDBCSB(U)
JBTPIA(J)

3-3

.PDEQJ(W)

the

JOB CONTROL

Job status word:

JBTSTS(J)

Swapped out disk address:

Swapped in image size:

JBTIMI(J)

Swapped out image size:

JBTIMO(J)

High segment number:

Funny space (per-process space) page count:

Swapped out checksum:

Program name:

User pc:

I/O wait DDB:

Program run data:

. PDNAM (W),

Time of last reset:

PDSTM(W)

Address of user-defined commands:

Address of UNQTAB for user-defined commands:

Address of DECnet session control block:

JBTSWP (J)

JBTSGN(J)
JBTPDB (J)

JBTCHK (J)

JBTNAM (J)

JBTPC(J)
JBTDDB (J)
. PDSTR (W),

. PDDIR (W),

. PDSFD (W)

PDCMN(W)
PDUNQ(W)

PDSJB(W)

The ENQ/DEQ, IPCF, and PSI facilities can all work in conjunction with
multiple contexts.
The Job/Context Handle (JCH) allows a facility to
uniquely identify a job and one of its contexts.
JCH storage requires
18 bits.
ENQ/DEQ,
IPCF,
and PSI have 18 bits reserved for this
purpose.
If you have not enabled the context facility, the JCH equals
the
job number.
If the JCH has a zero context component, the system
translates it into the JCH for the job's current context.
A non-zero
context component allows a program to target a job at a particular
context.
Refer to Chapter 22, Volume 2 for a description of the
CTX. monitor call.

3.3

RUNTIMES, TIMES, AND DATES

The TOPS-I0 monitor calculates runtimes, the time of day,
and the
date.
You can obtain any of these either from your terminal or for
use in your programs.

3.3.1

Runtimes

The TOPS-I0 monitor has several ways of monitoring runtimes.
The
runtimes available to you depend on the type ·of processor your system
uses, and on system parameters.
The KS and KL processors simulate a clock, called the APR clock, which
is based on the frequency of the system power source (either 50 or 60
Hz).
The APR clock may be used to keep the system time of day,
because it is accurate over long periods of time.
The APR clock may
also be used for job accounting.
However, it may not be completely
accurate, as its tick may be longer than the runtime period for a job.
The KS and KL processors simulate the APR clock by setting up internal
timers to simulate the jiffy clock.
3-4

JOB CONTROL

The OKlO clock has higher resolution than the APR clock,
and is
therefore more reliable for job accounting. High-precision runtime
simulates the OKlO clock time.
EBOX/MBOX runtime is computed from KL10 accounting meters
(to the
nearest 10 microseconds).
This runtime is not related to any other
runtime, and it is not directly related to real time.
Runtimes returned by the monitor
(by the RUNTIM call; the TIME,
USESTAT,
or CTRL/T monitor commands; or the .GTTIM GETTAB Table) are
all either high-precision runtime or EBOX/MBOX runtime
(selectable
with MONGEN).
The type of runtime reported depends on the value of
the ST%ERT bit in item %CNST2 of the .GTCNF GETTAB Table.
(The value
1 selects EBOX/MBOX runtime; 0 selects high-precision runtime.) The
RUNTIM call reads RN.PCN in its accumulator to initiate high-precision
runtime.
A
program that uses high-precision runtime can run
successfully even though the ST%ERT bit is on.
The time returned will
be approximated to simulate high-precision, but the low-order bits of
the high-precision word will be zero.
Monitor overhead can optionally
depending on MONGEN parameters.

3.3.2

included

these

runtimes,

The System Date

The DATE monitor call returns the system date as a IS-bit integer that
must be decoded to obtain a calendar date.
(See the DATE call in
Volume 2 of this manual for an example showing how to decode the
date.)
This 15-bit date is in multiple-radix form,
so that the
difference between two dates is usually not the number of days between
them.
The format of the code is:
(day of month - 1) + 31 * [(month - 1) + 12 * (year - 1964)]

3.3.3

The Universal Date

The monitor also keeps the date in an alternate format, the
date standard.
This fullword value is in the form:

universal

day"fraction
Where:

day is the number of days since November 17,
1858
November 17th is day 0, the 18th is day 1, and so on) .

(where

fraction represents the fractional part of the day elapsed
since midnight,
to approximately 1/3 of a second.
The
fraction is the numerator of a fraction whose denominator is
2**18,
so that the following expression gives the portion of
the day elapsed since midnight:
fraction/(2**18)
The arithmetic difference between two universal dates gives the number
of days and the portion of a day between the dates.
The universal date is stored in item %CNDTM in GETTAB Table .GTCNF and
is taken from the Smithsonian Universal Date/Time Standard (UDT).

3-5

JOB CONTROL
To obtain the local time (at your time zone), add the contents of item
%CNGMT in the same GETTAB Table (.GTCNF) to UDT.
You can derive the day of the week from the UDT by dividing the left
half by 7, and using the remainder to determine the day of the week.
Where:

a = Wednesday, 1 = Thursday, 2 = Friday, ... 6 = Tuesday

3.3.4

The System Time

You can obtain the system time in jiffies (one jiffy = 1/60 second) by
using the TIMER monitor call.
(For 50 Hz power supplies, 1 jiffy
1/50 second.)
You can also obtain the system time in milliseconds (one millisecond =
.001 seconds, to the nearest jiffy) by using the MSTIME monitor call.
This call is preferable to the TIMER call, because the returned time
is the same, regardless of the type of power supply (50 or 60 Hz) .

3.3.5

Date-Time Elements from GETTAB Tables

The GETTAB Table .GTCNF contains the
These items are:
Symbol

Contents

%CNYER
%CNMON
%CNDAY
%CNHOR
%CNMIN
%CNSEC

Local
Local
Local
Local
Local
Local

parts

the

date

and

time.

year.
month.
day of the month.
hour.
minute.
second.

The cautious programmer should assume that individual items can change
between successive GETTABs.
If a date and time must be guaranteed to
be consistent, your program should test values returned from the items
above until it obtains two consecutive, identical readings, or you
should derive the date and time from the UDT (available with a single
GETTAB) .

3-6

CHAPTER 4
THE JOB DATA AREA

Memory locations 20 through 137 (octal) and the high segment origin to
hiseg origin + 7 (normally locations 400000-400007) are allocated for
specific monitor and program uses.
This area is called the job data
area.
Your program sets some locations in the job data area for the
monitor's use; the monitor sets other locations for your program's
use.
During a program load, LINK loads the job data area symbols if they
are required to satisfy global references.
In your program, refer to
job data area locations by their symbol names (of the form
.JBxxx).
These symbols are defined as external symbols in UUOSYM.MAC, and are
given values in JOBDAT.MAC.
Section 4.1 lists important JOBDAT locations.
The JOBDAT locations
that are not listed in this table are either unused or used only by
the monitor.
Your program should be written to reference only the job
data area locations described in Section 4.1.

4.1

JOB DATA IN THE LOW SEGMENT

The low-segment job data area is in locations 20 through 137
Locations relevant to your job are:

(octal) .

Word

Symbol

Contents

.JBUUO

Used by hardware for processing local UUOs (opcodes
o through 37); the hardware stores the opcode and
the effective address in this location.

.JB41

Executed to start the user-programmed monitor call
(LUUO)
stored in
.JBUUO; this location usually
contains a JSR or PUSHJ instruction.
LINK puts a
HALT here if the user does not explicitly load
anything else.

.JBERR

System program error count.
The left half is
reserved; the right half is the number of errors in
the previous compilation.

.JBREL

The left half is reserved; the right half is the
highest physical memory location available to the
user program (low segment) .

.JBBLT

First location of three words used by LINK to move
the program before calling the exit routine.
This
location is used by the PA10S0 program to store the
return address for the user program.
4-1

THE JOB DATA AREA

.JBDDT

The left half is the first address after DDT,
if
DDT is loaded.
If any other debugging program is
loaded, this halfword is zero.
The right half is
the start address of the debugging program.
.JBDDT
can be set only with the SETDDT monitor call.
If
.JBDDT is zero,
DDT has not been loaded and the
monitor will attempt to read SYS:VMDDT.EXE when you
execute a DDT command.
If successful, VMDDT.EXE is
brought into the program's virtual address space.
The left and right halves of .JBDDT will be set
appropriately.

.JBPFI

The highest location that is protected from user
access.
User programs cannot write into locations
up to . JBPFI.

.JBHSO

Reserved for use by DIGITAL.,

.JBBPT

The unsolicited breakpoint address.
Use
the
instruction JSR @.JBBPT to invoke this facility
from a program.
It is necessary to explicitly
search JOBDAT to define this symbol.

112

.JBEDV

The Exec Data Vector, which the monitor uses as a
pointer to EDDT.
This location is valid only in
exec mode.

115

.JBHRL

High-segment addresses.
segment.

If zero, there is no

high

The left half is the first
free location in the
high segment, relative to the high-segment origin.
This value is the same as the high segment length.
This address is initially set by LINK and then set
by the monitor on subsequent GETs,
regardless of
whether there is a
file to initialize the low
segment.
The address is a relative quantity so
that
.JBHGH can be changed.
The SAVE monitor
command uses this value to determine how much to
write from the high segment.
The right half is the highest legal address in the
high segment.
This value is set by the monitor
each time a user program begins execution or
executes a CORE or REMAP monitor call.
116

.JBSYM

Pointer to the program symbol table created by
LINK.
The left half is the negative length of the
symbol table, and the right half is the starting
address of the symbol table.
If 0, this table does
not exist.
If this word is a positive number,
it
contains a pointer to the extended symbol table for
LINK.

117

.JBUSY

Pointer to the table of undefined symbols created
by LINK.
The left half is the negative length of
the symbol table,
and the right half is the
starting address of the symbol table.
If .JBUSY is
0, .JBSYM contains a pointer to an extended symbol
table for LINK.

4-2

THE JOB DATA AREA

120

.JBSA

First free low-segment address and program starting
address:
the left half is the first free location
in the program low segment, as set by LINK.
The
right half is the starting address of the user
program, unless an entry vector is in use.
(Refer
to the ENTVC.
monitor call in Volume 2.)

121

.JBFF

The first free address in the program's
low
segment.
The left half is zero.
The right half is
the address of the first free location after the
program data in the low segment.
On a RESET
monitor call, the value of the left half of
.JBSA
is moved to this location.
When the monitor builds a buffer, it allocates the
buffer at the address given by .JBFF, and then
changes .JBFF to the address at the end of the
buffer.
Note that .JBFF may point to a non-legal
user address if your program
occupies
every
location in the last page of your low segment.

123

.JBPFH

Pointer to page fault handler.
The left half is
the last address of the page fault handler.
The
right half is the address of the start of the page
fault handler.
If this address is 0, the user
program has no page fault handler; on a page fault,
the monitor calls its internal page fault handler.
This location remains zero when virtual under the
above circumstances.

124

.JBREN

The left half is zero.
The right half is the start
address for the REENTER monitor command, unless an
entry vector is in use.
(Refer to the ENTVC.
monitor call in Volume 2.) This value is set either
by the user program or by LINK.

125

.JBAPR

The left half is zero.
The right half is
address of a trap routine to handle APR traps.
the APRENB monitor call.

126

.JBCNI

The state of the APR as stored
instruction from a user trap.

127

.JBTPC

The PC of the next instruction to be executed after
a user-enabled trap occurs.
This value is set by
the monitor.
Use the JRSTF @.JBTPC instruction to
continue execution.

130

. JBOPC

The last user-mode program counter for the
job .
The monitor sets this value on each DDT, REENTER,
START, or CSTART monitor command.
Location
.JBOPC
contains
the
effective
address of the HALT
instruction, when the user program contains a HALT
instruction followed by the execution of a START,
DDT, CSTART, or REENTER command.
After an error
has occurred during execution of a monitor call
followed by a START,
DDT,
CSTART,
or REENTER
command,
.JBOPC will point to the address of the
monitor call.
To resume execution,
type
the
following command to DDT:
@130$G

4-3

the

the
See

monitor

THE JOB DATA AREA

131

.JBOVL

The left half is the negative number (count) of the
root segment overlays.
The right half is the
pointer to the header block for the root link of an
overlay structure.
You may also reference .JBOVL
as .JBCHN.

133

.JBCOR

LINK-written low segment break and monitor-written
SAVE or GET argument.
The left half is the highest
non-zero address in the program low
segment,
supplied by LINK.
If this address is less than 140
octal, no low segment will be written by a SAVE or
SSAVE monitor command.
The right half is the
user-specified argument for the last executed SAVE
or GET command.
The value in the right half is set
by the monitor.

134

.JBINT

The left half is reserved.
The right half is the
address of the error-intercepting block.
For a
description of the format of the block, see Chapter
6.

135

.JBOPS

Reserved for object-time systems.

136

. JBCST

Reserved for customers .

137

. JBVER

Program version number (in octal) and flags, in the
format
shown below.
The vt~rsion number of any
program can be obtained using t:he VERSION monitor
command.
Bits
0-2

Meaning
Modifier flag:
Meaning

Flag

DIGITAL development group
last
modified the program.
Other
DIGITAL
employees
last
modified the program.
A customer last
modified
the
program.
A customer's user last modified
the program.

2-4
5-7
3-11
12-17
18-35

140

. JBDA

DIGITAL's latest major revision
number,
usually incremented by 1 for each release.
DIGITAL's minor revision number,
which is
usually 0,
unless the program has been
modified since the last release.
The edit number, increased by 1 after each
edit to the program.
This value is never
reset.

First location available for user program .

4-4

THE JOB DATA AREA
4.2

JOB DATA IN THE HIGH SEGMENT

Some job data area locations are in your program's high segment.
These are loaded at the high-segment o:i~in (usually 400000), so that
(usually 400010).
your program actually begins at the or~g~n + 10
Refer to Section 2.4 for information about accessing the information
in the high segment.
In the following description of the format of this area,
all
are from the high-segment origin, usually .JBHGH (400000).

offsets

The format of the vestigial job data area is:
Word

S~rnbol

Contents

0
1
2
3

.JBHSA
. JBH41
.JBHCR
.JBHRN

4
5
6

.JBHVR
.JBHNM
.JBHSM

. JBHGA
.JBHDA

Copy of .JBSA in the job data area.
Copy of .JB41 in the job data area .
Copy of .JBCOR in the job data area.
LH:
used to set LH of .JBHRL
RH:
used to set RH of .JBREN
Copy of .JBVER in the job data area.
High segment name set on execution of SAVE command.
Pointer to high segment symbol table, if any.
In
the left half is the length of the symbol table.
In the right half is the address of the first word
in the symbol table.
If 0, there is no symbol
table.
GET address page number (bits 9-17) .
First word in high segment that is available to the
user program.

4-5

CHAPTER 5
NETWORKS

TOPS-IO supports four types of data networks:
o

ANF-lO, the TOPS-IO native communications software,
supports
communication
among
DECsystem-lOs
and
certain remote
stations. ANF-IO provides terminal concentration, remote job
entry, and front-end services for the monitor.
Using ANF-lO,
you can perform data transfers between jobs running on
different
systems,
and the same facility allows data
transfers among jobs running on the same system.
The ANF-IO
software is bundled with the TOPS-IO monitor.
This chapter
discusses the monitor calls and facilities available in the
ANF-IO communications environment.

DECnet-lO allows data communication among many of DIGITAL's
operating systems, for the purpose of file transfer, network
virtual terminal capability,
and intertask communication.
(DECnet-lO
must be purchased separately.)
DECnet-lO is
TOPS-lO's implementation of the Digital Equipment Corporation
Network Architecture.
DECnet-lO Version 4 supports the
standards defined in the DECnet Phase IV
Architecture
Specification, for Levell routing.
Three monitor calls deal
directly with DECnet-lO:

The NTMAN. call is
Management Layer.

used

only

the

DECnet

Network

The NSP. call
is
used
for
task-to-task
program
communication over DECnet network links.
Section 5.3
discusses the NSP. monitor call.

The DNET. call is
used
to
access
monitor-stored
information about DECnet nodes,
links,
and networks.
Section 5.4 discusses the DNET. call.

IBM Emulation/Termination facility provides communication
with IBM systems using batch job submission.
IBM E/T, a
separately purchased product,
interacts with the GALAXY
~pooling
and batch subsystem
(Versions 4.1 and later),
allowing users to submit TOPS-IO batch jobs from IBM remote
stations,
or to submit IBM-style batch jobs from the TOPS-IO
host.
This facility runs on a DN60 front end.
IBM
communication
is
described
in
the
TOPS-IO
IBM
Emulation/Termination manual.

5-1

NETWORKS
o

Ethernet, which allows you to implement foreign Ethernet
protocols using the ETHNT. monitor call.
For example, if you
wish to communicate with a printer that is on the Ethernet,
but is unreachable with ANF-10 or DECnet, you could use
ETHNT. to develop software that would communicate with the
printer
over the Ethernet.
ANF-10 and DECnet-10 also
function on the Ethernet hardware.
Section 5.5 discusses the
ETHNT. monitor call.
See Volume 2 for a full description of
ETHNT. functions.
Refer to The Ethernet:
Data Link Layer
and Physical Link Layer Specifications for a description of
the Ethernet hardware.

Each computer processor in a network is called a node.
A node is
either a host or a remote station. A host node is capable of running
user programs. A remote station, also known---a8a server,
is a node
with more limited capabilities.
It contains software that controls
specific I/O functions, such as terminal concentration,
remote batch
job entry, network communications links, and more.
A TOPS-10 system operates as a host node in any network.
A KL-based
DECsystem-10 can operate as a host node in any of the network
environments described above.
The RSX-20F front end is not a separate
node
in
the network.
IBM E/T is not supported on KS-based
DECsystem-10s.
Each node in the network has a node name of six characters or less,
and a node number, sometimes known as the node address.
For ANF-10,
the node number is octal.
You can use either the node name or node
number in most cases when referring to an ANF-10 node.
You must refer
to a DECnet node by its node name.
The terms local node and remote node distinguish the host system that
is interpreting your commands (the local node) from the other nodes in
the network
(the remote nodes).
Your terminal is automatically
connected to the host system by the remote station or front end to
which your terminal is physically connected.

5.1

ANF-10 NETWORK MONITOR CALLS

A MACRO program can include the following monitor calls to
intertask communication in the ANF-10 network environment.

accomplish

GTNTN. UUO returns the line and remote station
terminal.

number

GTXTN. UUO returns a terminal name for a
line number.

physical

node

and

LOCATE UUO allows your job to send direct spooled
the device at the node you specify.

output

NODE. UUO can perform several network functions.
are:

Among

them

Assign a logical name to a device and assign the device
to your
job.
The device may be connected to a remote
system.
Return a node number for a node name, or
node number.

5-2

node

name

for

NETWORKS

Send station control messages.
Receive boot request messages.
Return system configuration information (similar
NODE command) .
Connect or disconnect a terminal
system.

from

to
a

the

remote

List the known nodes.
Return node data block information.
Return and clear the ungreeted node flag.
o

TSK. UUO allows you to use intertask communication, which may
include tasks on the same system or on different systems.

WHERE UUO returns the name of the node to which a terminal or
other peripheral device is connected.

You perform I/O in the ANF-10 environment using UUOs such as IN,
INBUF, OUTBUF, FILOP., and OPEN.
The following sections discuss the use of monitor calls to
intertask communication between nodes on an ANF-10 network.

5.2

OUT,

establish

ANF-IO INTERTASK COMMUNICATION

Two tasks running in the same ANF-10 network can communicate with one
another. For example, one task may wish to transfer a file to another
task at another node.
This communication between tasks is called
intertask communication.
Intertask communication can be used between
jobs on the same system or between jobs on on different systems in the
network.
In this discussion,
the term task is used to refer to a
program.
Initially, both program~ must open a channel for I/O for intertask
communication.
This 1S accomplished using the OPEN UUO with SIXBIT
/TSKnn/ in the argument block (Word 1), for the device name, where nn
is the node number of the node where the other task is running.
The appropriate calling sequence for opening a channel
communication is:
OPEN
channo,argblk
error return
normal return
argblk:

EXP
SIXBIT
XWD

mode
/TSKnn/
outblk,inblk

5-3

for

intertask

NETWORKS

In this example, channo is the channel number, argblk is the address
of the argument block.
The first word of the argument block allows
you to define the data mode.
The I/O modes used for data transfer
between tasks are:
o

ASCII and ASCII line modes, in 7-bit ASCII

Byte mode, in 8-bit bytes

Image and image binary modes, in 36-bit words

Refer to Section 11.4 for information about I/O modes.
The second word specifies the device and node number of the other task
(TSKnn) .
The third word of the argument block specifies the addresses
output (outblk) and input (inblk) buffer control blocks.

the

After opening the I/O channels for communicating data, the tasks must
initiate the connection.
The passive task describes the desired
connection, and then waits for I/O to start.
The active task
initiates a connection and may start I/O.
Since interactive task-to-task communication is always buffered,
you
should use one buffer for each data request when sending data.
When
receiving data, use multiple buffers,
so that all incoming data
requests can be accommodated.

5.2.1

Initiating a Connection

The intertask connection can be initiated by either of
methods:

the

following

The passive task uses the LOOKUP UUO to specify the task
name,
and then performs an IN or INPUT.
The passive task
then waits for the active task to initiate I/O.
The active
task uses the ENTER UUO to initiate the connection, and then
performs OUT or OUTPUT calls to start data transfer.
This
procedure
is
described
in
the
following
section.
LOOKUP/ENTER blocks are described in more detail in Chapter
11.
Either the short argument block (shown here) or the
extended argument block may be used to initialize intertask
communication.

The passive task uses the TSK. UUO with the
.TKFEP function
code.
The active task uses the TSK.
function .TKFEA.
Both
tasks must provide Network Process Descriptor
(NPD)
blocks.
This method of intertask communication is described in
Section 5.3.1.2.

5-4

NETWORKS

5.2.1.1 Using the LOOKUP/ENTER UUOs - After OPENing the I/O channel,
the passive task must declare the task name in the LOOKUP monitor
call.
By specifying the task name in the argument block, the passive
task ensures that only the appropriate active task can initiate I/O.
The task names specified by the passive and active tasks are compared
and must be equivalent before I/O can begin.

The LOOKUP calling sequence is:
LOOKUP
channo,argblk
error return
normal return
argblk:

SIXBIT

o
o

/tsknam/

ppn
In this sequence, channo is the same channel number used in the OPEN
UUO,
and argblk is the address of the argument block.
In Word 0 of
the argument block, tsknam specifies the task name in SIXBIT. Words 1
and 2 are unused.
Word 3 contains the ~ of the active task, if
different from that of the passive task.
(You must have privileges to
specify a PPN.)
A PPN of 777777,777777 indicates full wildcard
acceptance of a connection from any PPN.
The passive task can then issue an IN or INPUT monitor call for the
given channel to initiate a wait state until connection is made from
an active task, or, if the program has the PSI system enabled, it can
act on an appropriate interrupt condition (refer to Chapter 6) .
The active task uses an ENTER UUO to specify the task name for which
to establish a connection.
The following calling sequence is used:
ENTER
channo,argblk
error return
normal return
argblk:

SIXBIT

o
o

/tsknam/

ppn
Where:

channo is the channel number used in the OPEN call.
argblk is the address of the argument block.
tsknam is the name of the task (same used
passive task) .

LOOKUP

the

is the project-programmer number of the active task, which
you should include only if it is different from that of the
passive task.
You must have privileges to specify the PPN.
If you specify 0 for the PPN, it defaults to the task's own
PPN.

5-5

NETWORKS

5.2.1.2 Using the TSK. UUO - Both the passive and actiV"e tasks can
use the TSK. UUO to initiate the connection.
First you must OPEN an
I/O channel for task-to-task communication,
just as
with
the
LOOKUP/ENTER method.
However,
the TSK. call gives your program
greater control over the communication,
and allows many functions
useful in performing task-to-task communication.

TSK. UUO operates by reading a Network Process Descriptor block
(NPD)
for each task.
In this description, the word "process" is equivalent
to "task." Both tasks must specify an NPD for both the passive and
active tasks.
The NPD that each task specifies for the remote task
must match the other task's local NPD.
The format of the NPD is:
Word

Symbol

Contents

0
2

.TKNND
.TKLNL
.TKNPN

Node number of the task
Length of task name
First word of task name

.TKLNL+n

Last word of task name

An NPD describes a task

(process).
The first word
(.TKNND)
contains
the node number of the node on which the task is running, and could be
-1 to indicate any node (-1 is not valid when connecting to a
remote
passive task) .
The second word specifies the length (in characters) of the task name.
The maximum length of the task name is 100 (decimal) characters; this
maximum is defined as .TKMNL in UUOSYM.MAC.
The third word contains the first word (in ASCII) of the task name.
The length of the NPD,
therefore, is the result of adding 2 + the
contents of .TKLNL ("the number of characters divided by 5 and rounded
up) .
The wildcard characters listed here can be used in the task
name:
Character

Meaning

Matches 0 or more characters.

Matches anyone character.

Quote next character,
allowing you
to
asterisks
and
question
marks
(for
characters) in the task name.

specify
wildcard

The TSK. call is invoked as shown in the following calling sequence:

argblk:

MOVE
ac, [XWD length,argblk]
TSK.
ac,
error return
normal return
EXP
function-code
EXP
channo
EXP
locnpd
EXP
remnpd

In the TSK.
calling sequence, the ac is first loaded with a word
consisting of the length of the argument block (in this case, 4) and
the address of the first word in the argument block
(argblk).
The
argument block contains the following words.

5-6

NETWORKS

In Word 0, the function code is indicated by function-code.
For the
passive task,
(similar to LOOKUP,
above) this is .TKFEP. For the
active task, (similar to ENTER, above) the function code is
.TKFEA.
Although a monitor call must be issued by each task, both tasks need
not use the same calling procedure.
That is, one task may initiate
the connection using a LOOKUP or ENTER call, and the other task may
use the appropriate TSK. function.
In Word 1, the channel number is indicated by channo.
identical to the channel number used in the OPEN UUO.

This

In Word 2, the address of the local ~etwork Process
indicated here by locnpd.
This is the task's own NPD.

Descriptor,

In Word 3, the address of the remote Network Process Descriptor,
indicated here by remnpd.
For the passive task, this is the NPD of
the task from which it will accept a connection. For the active task,
this is the NPD of the task with which to attempt a connection.
After using the TSK. UUO with the .TKFEP function,
can wait for input from the active task.

the

passive

task

After using the TSK. UUO with the .TKFEA function, the active task can
begin data transfer.

5.2.2

Sending and Receiving Between Tasks

When task-to-task communication is established with LOOKUP/ENTER
calls,
the monitor generates NPDs for the tasks.
Thus, the programs
can use TSK. call functions even though communication was
not
initiated with the TSK. monitor call.
The monitor generates a local
NPD and a remote NPD for each program.
The local NPD of each task consists of the node number of the local
node
(the node on which it is running), and the task name consists of
the program name (obtained from .GTNAM) and the task's [PPN].
The remote NPD for each task consists of
from the OPEN call
Where:

the

node

number

generated

TSKnn would contain the node number as nn, or -1 if only TSK
was specified (implying that connectionS-from any node will be
accepted).
The task name would be generated by the file
specification in the LOOKUP/ENTER block.

Because of this facility, two tasks can communicate using different
calling procedures.
One task can use the appropriate LOOKUP or ENTER
call, and the other task can use the complementary TSK. function.
Note,
however,
that the TSK.
call must include references to NPDs
that are equivalent to those generated by TSKSER for LOOKUP/ENTER
sequences.
The LOOKUP/ENTER NPD contains a file specification for the
task name.
This must be matched exactly by the program issuing the
TSK.
call.
When the intertask communication is established,
the two tasks can
send and receive data using the normal I/O monitor calls (IN, INPUT,
OUT, and OUTPUT) for the open channel.
Your program should require the communicating tasks to verify the
intertask communication by sending and receiving identifying codes;
these codes should be unique among tasks on the network so that no
mistaken communication occurs.
5-7

NETWORKS

The TSK. call offers several functions useful for performing I/O as
well as establishing the task-to-task link.
The TSK. functions are:
Symbol

Meaning

.TKFRS

Returns the state of the communications
link specified in the argument block.
The
link can be idle, waiting for a connection,
waiting for a connect confirmation, active,
or waiting for a disconnect confirmat{on.

.TKFEP

Creates a passive link.

.TKFEA

Creates an active link.

.TKFEI

Enters idle state.
This allows the monitor
to CLOSE the connection.

.TKFWT

Enters wait state.

.TKFOT

Outputs messages with
disassembly.

control

message

.TKFIN

Inputs messages
reassembly.

control

message

.TKFRX

Returns the state of the
maximum data message size.

Fcn-code

5.2.3

with

link

and

the

Breaking the Intertask Communication

Either the active task or the passive task can break the intertask
communication.
When one task issues a CLOSE monitor call for the
communication channel, the other task receives an end-of-file on its
channel.
When the task issues a RELEAS monitor call for the channel,
the communication is completely broken.
Both tasks should close and
release their channels.

5.3

TASK TO TASK PROGRAMMING WITH DECnet-lO

You can write MACRO programs to communicate with tasks on
DECnet node.
When doing so,
you use the NSP. monitor
interface to DECnet-lO.
This section describes the functions
NSP. monitor call.
These functions allow you to:

another
call to
of the

Declare a network task as willing to accept connections.

Initiate a request for a connection to another network task.

Accept or reject a request
network task.

Transmit data to and receive data from another network task.

Request the status of a logical link.

Read the connect attributes of a network task.

Exchange interrupt messages with.other network tasks.

5-8

for

connection

from

another

NETWORKS

Set buffer quotas for the link.

Set a reason mask for PSI interrupts.

Disconnect a network connection.

The basic form of the NSP. monitor call is:
MOVE I
AC, ADDR
NSP.
AC,
Error return
Normal return

iAr9 block pointer
iDo the UUO
iAC contains error code
iUUO succeeded, AC unchanged

The AC always points to a data block that has the general form:
Symbol

Word

Contents

17 18

. NSAFN

Flags+Fcn

Length

. NSACH

Status

Channel #

. NSAAI

First Argument

. NSAA2

Second Argument

. NSAA3

Third Argument

On an error (non-skip) return, AC always contains an error code.
The
error codes and their meanings are listed in Volume 2, in the
description of the NSP. UUO.
On a normal (skip)
return,
the AC is
unchanged.
You may set two flags in the NSP. monitor call.
o

NS.WAI (bit 0 of . NSAFN) indicates whether the program should
wait for the function to be completed before returning from
the monitor call.
If the bit is set, the monitor waits.

NS.EOM (bit 1 of . NSAFN) indicates whether an end of message
is to be sent with a message.
DECnet-l0 returns the NS.EOM
flag as appropriate on a data read.
If the program sets
NS.EOM on a normal data read call, DECnet-IO truncates data
that overflows the program's buffer.

The NSP. UUO has the functions listed below.
The function code must
be in Bits 9 through 17 of the first word of the argument block
(.NSAFN).
The NSP. status variable and channel number are always the
second word (.NSACH). All functions return the after-function status
of the link in the left half of
.NSACH.
All functions ignore the
status in
.NSACH when reading arguments, so the program can pass an
old status along with a channel number if that is convenient.
The
interpretation of the argument words varies with the function.

5-9

NETWORKS

Table 5-1:

NSP. UUO Functions

Fen-code

Symbol

Meaning

.NSFEA
.NSFEP
.NSFRI
. NSFAC
.NSFRJ
. NSFRC
.NSFSD
. NSFAB
. NSFRD
.NSFRL
.NSFRS
.NSFIS
.NSFIR
.NSFDS
.NSFDR
.NSFSQ
.NSFRQ
.NSFJS
.NSFJR
.NSFPI

Enter Active State
Enter Passive state
Read Connect Information
Accept Connect
Reject the Connect
Read Confirm Information
Synchronous Disconnect
Abort and Release
Read Disconnect Data
Release Channel
Read Channel Status
Send Interrupt Data
Receive Interrupt Data
Send Normal Data
Receive Normal Data
Set Quotas
Read Quotas
Set Job Quotas
Read Job Quotas
Set PSI Conditions

2
3
'4

5
6
7

10
11

12
13
14
15
16
17
20
21
22
23
24

5.3.1

Specifying a Destination Task

A task declares that it is ready to accept a connection by executing
the Enter Passive function (.NSFEP).
The .NSFEP argument list has the
format:
. NSAFN
. NSACH
. NSAAI

Flags+XWD .NSFEP,3
XWD Status, Channel number (assigned by this call)
Connect block pointer

The link is put into Connect wait state (.NSSCW) and remains in this
state until a connect initiate message is received that matches the
connect block, or until the link is released.
DECnet-l0 uses the connect block specified by the connect block
pointer
(.NSAAl) as a pattern for incoming connect initiate messages.
The connect block has fields for pointers to source and destination
task descriptor blocks,
and pointers to string blocks for the node
name, user-id, password, account, and user data.
Fields that are zero
in the connect block are considered wildcards and match anything.
The
only field that must be specified is the pointer to the destination
task descriptor.

5-10

NETWORKS

The connect block has the following format:
Word

Symbol

Field

. NSCNL

. NSCND

Node name

pointer to string block (max 6 bytes)

.NSCSD

Source

pointer to task descriptor block

.NSCDD

Destination

pointer to task descriptor block

.NSCUS

User-id

pointer to string block (max 39 bytes)

.NSCPW

Password

pointer to string block (max 39 bytes)

. NSCAC

Account

pointer to string block (max 39 byt~s)

.NSCUD

User Data

pointer to string block (max 16 bytes)

, Length

length of this argument block

The connect block contains pointers to other blocks,
such as thos@
containing· the node name or accounting information,
and tbose
containing information describing the source and destination tasks.
The blocks for the node name, user-id, password, account, and data are
called string blocks. A string block has the following format:
Word

Symbol

Field

.NSASL

NS .ASC, NS. ASL

LH: byte count;
length in words

.NSAST

c1,c2,c3,c4,0

8-bit bytes of data

NS.ASL-1

cn-1,cn,0

RH:

block

The user-id, passwqrd, account, and user data are optional. They can
be used by the destination task to validate a network connection or to
perform any other handshaking functions agreed to by both tasks.
Except for the data
(which can be up to 16 characters long), these
strings can be up to 39 characters long.
They must consist of
alphanumeric ASCII characters (including the hyphen, dollar sign, and
underscore) .
The task descriptor block identifies the source or
Its format is shown below:
Word

Symbol

Field

.NSDFL

.NSDFM

Format type

0, 1 or 2

.NSDOB

Object type

integer

.NSDPP

PPN

.NSDPN

task name

, Length

destination

task.

length of the argument block

2 half words (16 bits, 16 bits)
pointer to string block (max 16 bytes)

By including the proper combination of values in the task descriptor
block,
you identify the task and specify whether it is a system
program or a user program. Table 5-2 shows the information you must
supply for each type of program.

5-11

NETWORKS

Table 5-2:

Allowable Combinations of Task Descriptor Values

Kind of Program

Format Type

Object Type

PPN

Task Name

DECnet system
Customer system
User, name only
User, with PPN

a
a

1-127
128-255

a
a
a

a
a

1
2

a
a

n,n

string pointer
string pointer

Use format type a only with a non-zero object type to specify a system
program.
Object types 1 through 127 identify DECnet utilities or
control programs.
Only a privileged program can have an object type
of 1 through 127.
Object types 128 through 255 identify customer
system programs and are assigned by the system manager.
A program
need not be privileged to have an object type of 128 through 255.
Refer to UUOSYM.MAC for a list of the currently-defined object types.
Use Format types 1 and 2 to specify user programs. with Format types
1 and 2,
you must specify an object type of a and a pointer to the
task name. with Format type 1, you specify a task name of up to 16
characters, but not a project-programmer number.
Format type 2 allows
you to specify both a task name and a project-programmer number,
but
there are restrictions on each.
The task name can only ~e up to 12
characters long because DECnet-l0 adds the project-programmer number
to it. Also, your project-programmer number must fit into 16 bits, or
your program must be privileged
(so it does not require a PPN)
Otherwise, your program must identify itself using format type 1.
When DECnet-10 receives a connect initiate message,
it matches the
message against the connect blocks of successive destination tasks
until it finds a match. When a match succeeds,
DECnet-l0 puts the
link in the Connect Received (.NSSCR) state, and passes control to the
destination program. At this point the program can re~d the connect
data and accept or reject the connection.
Example of Specifying ~ Destination Task
This example shows use of the NSP. UUO to declare that a program is a
destination task.
It also shows the connect, task descriptor, and
string blocks for the Enter Passive function.
; Begin by using the NSP. Enter Passive function to wait
; for a program on some other host to send a message.
ENTPAS:
T1,EPBLK
; Pointer to Enter Passive arg block
MOVE I
Tl,
; Enter Passive
NSP.
JRST
[OUTSTR [ASCIZ /?Can't Enter Passive I]; Error
JRST
EREXIT]; return
; Argument block for Enter Passive
EPBLK: NS.WAI+XWD
.NSFEP,3
Wait bit, function, block length
XWD
0,0
No status or channel number yet
XWD
CONBLK
Pointer to Connect Block
Connect block
CONBLK: EXP
EXP
EXP
EXP

for Enter Passive
4
Length of block in words
a
Accept connects from any host
a
Accept connections from any source
TDBIB
Destination task descriptor block
5-12

NETWORKS

; Destination task descriptor block
TDB1B:
EXP
5
Length of TDB
EXP
2
Format type 2
EXP
o
Object type 0
XWD
20,7200
Project-programmer number
EXP
STRB1C
String block for destination name
String block for destination name
STRB1C: XWD
4,2
; Number of bytes, number of words
BYTE
(8) "P", "G", "M", "B"

5.3.2

Specifying a Source Task

A task declares that it is a source program by executing the Enter
Active function (.NSFEA).
The .NSFEA argument list has the format:
. NSAFN
. NSACH
. NSAA1
. NSAA2
. NSAA3

Flags+XWD .NSFEA,length (length = 3 to 5)
XWD Status, Channel number (assigned by this call)
Connect block pointer
Segment size (optional; default: maximum allowed)
Flow control (optional, privileged; default: segment)

DECnet-10 sends a connect initiate message using the information in
the connect block pointed to by
.NSAA1,
and the link enters the
Connect Sent state (.NSSCS).
The source connect block has the same
format as that used for a destination task.
When DECnet-10 is transmitting data across a physical link,
the data
is in the form of segments whose maximum size is set during network
generation.
The actual segment size used for a particular logical
link is negotiated by the two hosts when the link is being set up.
So, when transmitting a message, DECnet-10 will try to fit it into a
segment,
breaking it if the message is larger than a segment, or
sending a partial segment if the message is smaller than a segment.
To enhance performance, you may wish to find out the segment size and
set the program's buffers to that size.
Then each segment transmitted
would contain a complete message.
The program can find the segment
size of a logical link by executing the Read Channel Status function.
Flow control is necessary because it may take some time for a message
segment to travel through the network from the source node to the
destination node.
Therefore, it is desirable for a node to be able to
transmit a number of segments, one after another, without waiting for
an acknowledgement of one segment before transmitting another.
DECnet
recognizes three types of flow control:
o

Segment flow control (.NSFCS) - The receiving node sends a
request for data that includes the maximum number of message
segments it can accept at one time.
This is the default for
DECnet-10.

Message flow control (.NSFCM) - The sending node transmits
all the segments necessary to form a complete message.
DECnet-10 supports this type of flow control for sending
messages.

5-13

NETWORKS

No flow control (.NSFCO) - A node sends segments without
waiting for a data request from the receiving node.
When the
receiving node fills its buffers and cannot handle any more
segments, it sends an OFF link service message to the sending
node to stop the flow.
The sending node stops sending and
will not send any more segments until the receiving node
signifies that it can again accept segments by sending an ON.

If the connection attempt succeeds, DECnet-l0 sets the link state to
Running
(.NSSRN); if the attempt fails, DECnet-l0 sets the link state
to Connect Rejected (. NSSRJ) .
Example of Specifying ~ Source Task
Begin by using the Enter Active function to attempt to establish
a logical link with PGMB on system HOSTB.
MOVE I
T 1 , EABLK
; Point to Enter Active arg block
NSP
Tl,
; Enter Active
JRST
[OUTSTR [ASCIZ /?Can't Enter Active I]; Error
JRST
EREXIT]
return
; Argument block for Enter Active
EABLK:

NS.WAI+XWD .NSFEA,3
XWD
0,0
XWD
CONBLK

Connect block
CONBLK: EXP
EXP
EXP
EXP

wait bit, function, block length
No status or channel number yet
Pointer to connect block

for Enter Active
Length of block in words
Pointer to string block of node name
Source task descriptor block
Destination task descriptor block

STRBIA
TDBIA
TDBIB

String block for node name
STRBIA: XWD
5,3
BYTE
(8) "H", "0",

; Number of bytes, number of words
"S", "T", "B" ; Name of destination node

Source task descriptor block
TDBIA:
EXP
5
EXP
2
EXP
o
XWD
20,7100
EXP
STRBIB

Length of TDB
Format type 2
Object type 0
Project-programmer number on HOSTA
String block for source name

String block for source name
STRBIB: XWD
4,2
; Number of bytes, number of words
BYTE
(8) "P", "G", "M", "A"
Destination task descriptor block
TDBIB:
EXP
5
Length of TDB
EXP
2
Format type 2
EXP
o
Object type 0
XWD
20,7200
Project-programmer number on HOSTB
EXP
STRBIC
String block for destination name
String block for destination name
STRBIC: XWD
BYTE

4,2
(8)

; Number of bytes, number of words
"P",

"G",

"M",

"B"

5-14

NETWORKS

5.3.3

Reading the Connect Information

After DECnet-10 has matched the source and destination tasks, it puts
the link into Connect Received state.' The destination task can accept
or reject the connection at this point, or it can execute the Read
Connect Information function
(.NS~RI}
to move the connect initiate
data into the connect block supplied in the call.
The program can
then examine the data to decide whether to accept or reject the
connection.
The .NSFRI argument list has the format:
. NSAFN
. NSACH
. NSAA1
. NSAA2
. NSAA3

Flags+XWD .NSFRI,length (length = 3 to 5)
XWD Status, Channel number
Connect block pointer
Segment size (optional)
Flow control (optional)

The program must specify a pointer to each block.
However,
it can
specify the length of the block as zero, and DECnet-10 ignores the
data.
If the program uses 0 instead of a pointer,
DECnet-10 accepts
it as the pointer to AC 0 and stores the data starting at AC O.
If the Jestination program has included fields for segment size
flow control, DECnet-10 stores those values for the source node.

and

The UUO takes the error return if the
following states:

the

.NSSCR
.NSSCW
. NSSRN

link

not

one

Connect Received
Connect Wait
Running

If the link is in Running state and the program has issued neither
read nor write functions, DECnet-10 passes the connect initiate data
to the program.
Example of Reading the Connect Information
When control reaches this point, a program is attempting to initiate
a connection with this program. The Read Connect Info function
determines information about the job trying to establish contact.
EVALCN:
HRRM
CHAN,RIBLK+.NSACH; Store channel number into arg block
MOVE I
T1,RIBLK
; Point to Read Connect Info arg block
NSP.
T1,
; Read Connect Info
JRST
[OUTSTR [ASCIZ I?Can't Read Connect Info I]; Error
JRST
EREXIT]; return
Here the program checks to make sure that the source PPN is [20,*].
HLRZ
CAIE
JRST
JRST

T1,SRCPDB+.NSDPP;
T1,20
REJCON
ACCCON

Get left half of source PPN field
Test for project number 20
Reject connection if not
Accept connection if so

Argument block for Read Connect Info
RIBLK: NS.WAI+XWD
.NSFRI,3
wait bit, function, block length
XWD
0,0
Code supplies channel number
XWD
SRCCNB
Pointer to source connect block

5-15

NETWORKS

; Connect Block
SRCCNB: EXP
EXP
EXP
EXP
EXP
EXP
EXP
EXP

for Read Connect Info
"DS
Length of block in words
String block for ,node name
STNODE
Source task descriptor block
SRCTDB
Destination task descriptor block
DSTTDB
String block for user id
STUSID
String block for password
STPSWD
String block for account
STACCT
String block for user data
STDATA

string block for node name
STNODE: XWD
0,3
BLOCK
2

Number of words -- max 6 bytes

Source task descriptor block
SRCTDB: XWD
0,5
EXP
0,0,0
EXP
STNAME

Number of words
Format type, Object type, PPN
String block for task name

;Destination task descriptor block
DSTTDB: XWD
0,0
;Block is zero-length; no info wanted
; String block for user id
STUSID: XWD
O,"Dll
BLOCK
"DI0

Number of words -- max 39 bytes

string block for password
STPSWD: XWD
O,"Dll
BLOCK
"DI0

Number of words -- max 39 bytes

String block for account
STACCT: XWD
O,"Dll
BLOCK
"DI0

Number of words -- max 39 bytes

String block for data
STDATA: XWD
0,5
BLOCK
4

Number of words -- max 16 bytes

String block for source name
STNAME: XWD
0,5
BLOCK
4

Number of words -- max 16 bytes

5.3.4

Accepting the Connection

Once the link is in Connect Received state, the destination task can
accept or reject the connection, whether or not it reads the connect
initiate information.
By executing the Accept Connect function
(.NSFAC),
the destination task declares that it will exchange data
with the source task.
The .NSFAC argument list has the format:
. NSAFN
. NSACH
. NSAAI
. NSAA2
. NSAA3

XKD .NSFAC,length (length = 2 to 5)
XWD status, Channel number
Pointer to user data (string block pointer, optional)
Segment size (optional; default: maximum allowed)
Flow-control (optional, privileged; default: segment)

If execution of the Accept Connect function succeeds, DECnet-l0 sends
a connect confirm message to the source task and puts the link in
Running state (.NSSRN).
The connect confirm message contains the
optional data supplied by the destination task, the segment size
agreed to by both nodes, and the flow control to be used by the
destination node.
5-16

NETWORKS

If the link is not in Connect Received state when the
function executes, the UUO takes the error return.

Connect

Example of the Accept Connection Function
; The program comes here to accept the requested connection
ACCCON:
CHAN,ACBLK+.NSACH; store channel number into arg block
HRRM
MOVE I
TI,ACBLK
; Point to Accept Connection arg block
TI,
; Accept Connection
NSP.
JRST
[OUTSTR [ASCIZ /?Can't Accept Connection I]; Error
JRST
EREXIT]; return
; Argument block for Accept Connection
ACBLK: NS.WAI+XWD
.NSFAC,2
; wait bit, function, block length
XWD
0,0
; Code supplies channel number

5.3.5

Rejecting the Connection

Once the link is in Connect Received state, the destination task can
accept or reject the connection, whether or not it reads the connect
initiate information.
By executing the Reject Connect function
(.NSFRJ), the destination task declares that it will not exchange data
with the source task.
The .NSFRJ argument list has the format:
. NSAFN
. NSACH
. NSAAI

XWD ;NSFRJ,length (length = 2 or 3)
XWD status, Channel number
String block pointer to user data (optional)

If the link is not in Connect Received state upon execution
Reject Connect function, the UUO takes the error return.

the

Example of the Reject Connection Function
; The program comes here to reject the requested connection
REJCON:
CHAN,RJBLK+.NSACH; store channel number into arg block
HRRM
TI,RJBLK
; Point to Reject Connection arg block
MOVE I
TI,
; Reject Connection
NSP.
[OUTSTR [ASCIZ /?Can't Reject Connection I]; Error
JRST
JRST
EREXIT]; return
After it has rejected the connection, the program goes back and
executes the Enter Passive function again
JRST
ENTPAS
Argument block for Reject Connection
RJBLK:
NS.WAI+XWD
.NSFRJ,2
; wait bit, function, block length
XWD
0,0
; Code supplies channel number

5-17

NETWORKS

5.3.6

Reading the Connect Confirm Data

If the destination task accepts the connection, the DECnet software at
the destination node sends a connect confirm message to the DECnet
software at the source node.
The source task can
(optionally)
read
the data in the connect confirm message by executing the Read Connect
Confirm Data function (.NSFRC).
The
. NSFRC argument list has the
format:
Flags+XWD .NSFRC,length (length = 2 to 5)
XWD status, Channel number
String block pointer to user data (optional)
Segment size (optional)
Transmit flow control mode (optional)

. NSAFN
. NSACH
. NSAAI
. NSAA2
. NSAA3

If the link is in Running (.NSSRN)
state but the program has not
executed any read or write functions on this link, the UUO returns the
connect confirm data.
However, if the program has executed a read or
write function on this link, DECnet-lO discards the connect confirm
data, and the UUO takes the error return.
If the link is in any state
other than Connect Sent
(.NSSCS) or Running (.NSSRN), the UUO also
takes the error return.

5.3.7

Reading the Status of the Link

The program can check the status of an assigned channel
the link) by executing the Read Channel Status function
.NSFRS argument list has the format:

XWD .NSFRS,length (length = 2 to 4)
XWD Status, Channel number
Segment size for this link (optional)
XWD Remote flow control, local flow control

. NSAFN
. NSACH
. NSAA1
. NSAA2

The left half of the second argument
(.NSACH)
variable, which contains the following fields:
Table 5-3:

Bits

o
1
2

12-17

(and therefore
(.NSFRS).
The

contains

(optional)
the

status

Fields in .NSACH (status variables)

Symbol

Meaning

NS. IDA
NS. IDR
NS.NDA
NS.NDR
NS. STA

Single bit.
If set, interrupt data can be read.
Single bit.
If set, interrupt data can be sent.
Single bit.
If set, normal data can be read.
Single bit.
If set, normal data can be sent.
6-bit field that contains the state of the
connection.
State values are listed in Table
5-4 ..

The four data flags are set only if the
state for the indicated functions.
connection states.

5-18

link is in an appropriate
Table 5-4 lists the NSP. UUO

NETWORKS

Tab1e 5-4:

NSP. Connection States

Code

Symbo1

Meaning

.NSSCW

Connect wait:
The task has executed the Enter Passive function
and
is awaiting the receipt of a connect
initiate message.

.NSSCR

Connect Received:
The task has executed the Enter Passive function
and has received a connect initiate message; it
may now read the connect data and must either
accept or reject the message.

.NSSCS

Connect Sent:
The task has performed an Enter Active function
which sent a connect initiate message, and is
now awaiting either a connect confirm (and entry
into the Running state) or a connect reject (and
eatry into the Reject state) .

.NSSRJ

Reject:
The remote node has rejected this node's connect
initiate attempt.
The task should read the
disconnect data and release the channel.

.NSSRN

Running:
The link is up and may be used for the
of data.

transfer

.NSSDR

Disconnect Received:
The task has received a disconnect initiate
message.
The task should read the disconnect
data and release the channel.

.NSSDS

Disconnect Sent:
The task has performed a Synchronous Disconnect
function and is awaiting a disconnect confirm.
During this time, the task should be prepared to
read data from the link (the other end having
not yet received the disconnect),
but may not
use the link for the transmission of new data.

.NSSDC

Disconnect Confirmed:
This state is entered from the Disconnect Sent
state when the disconnect is finally confirmed.
At this point,
the only legal functions are
Release
and Read Status.
The task should
release the channel.

.NSSCF

Confidence:
DECnet has no confidence in this logical link
because the remote node is not acknowledging
messages.
The local node has retransmitted a
message more than the retransmit factor number
of times without receiving an acknowledgment.
The retransmit factor is a system parameter set
by the system manager.
The task should release
a channel in this state.
NO

5-19

NETWORKS

.NSSLK

No Link:
There is no link because the remote node no
longer recognizes this logical link.
This can
happen if the remote node is reloaded quickly,
or if the remote task is aborted without sending
a disconnect initiate message for some reason.
The task should release a channel in this state.

.NSSCM

No Communication:
There is no communication between this node and
the remote node.
A connect initiate cannot
succeed because there is no communication with
the requested node.
This state can only be
entered from Connect Sent state.
The task
should release a channel in this state.

.NSSNR

No Resources:
This state is entered from Connect Sent state
when a No Resources message is received from the
destination
node,
which
had
insufficient
resources to make the requested connection.
The
task should release a channel in this state.

Other functions can provide the same information as .NSFRS.
However,
a program could use the Read Channel Status function if it were a
destination node that required the segment size.
It could also use
this function if it became uncertain of the link status (perhaps
because it had not recently received data) .
Example of Read Link Status
; If there's a channel number, read the status of the channel and
; analyze it
REDSTS:
HRRM
T2,RSBLK+.NSACH
Store channel number into arg block
MOVE I
Tl,RSBLK
Point to Read Status arg block
NSP.
Tl,
; Read Status
JRST
[OUTSTR [ASCIZ /?Can't Read Status /); Error
JRST
TYPRET)
; return
; Argument block for Read Status
RSBLK:
XWD
«NS.WAI»+.NSFRS,2 ; wait bit, function, block length
XWD
0,0
; Code supplies channel number

5-20

NETWORKS

5.3.8

Using the PSI System

A task source or destination task can be programmed to perform
intertask I/O synchronously or asynchronously.
With synchronous
programming, the task sets a bit, called the wait flag
(NS.WAI),
so
that each time the task executes the NSP. UUO it waits (blocks) until
the I/O has been entirely completed~
with asynchronous programming,
the task does not set the wait bit so that the task can continue
executing even if the NSP. function has not completed.
The task must
check the status variable to determine when the requested function is
completed, or use the PSI (Programmed Software Interrupt)
system so
that it will be interrupted when the status changes, indicating that
the NSP. function is completed.
However, the program must enable the
PSI system and set a PSI reason mask before DECnet-lO can cause an
interrupt.

5.3.9

Setting the PSI Reason Mask

The PSI reason mask is an IS-bit value that contains
fieids
corresponding to the fields
in the DECnet-lO status variable.
A
program can set' this mask by executing the Set PSI Reason Mask
function (.NSFPI).
The .NSFPI argument list has the format:
. NSAFN
. NSACH
. NSAAI

Flags+XWD .NSFPI,3
XWD Status, Channel number
XWD O,reason mask

In the right half of the third argument, the program sets to 1 those
bits that correspond to the status or states that will cause an
interrupt.
All DECnet programmed interrupts come through a single PSI
interrupt condition.
You cannot assign a different interrupt to each
DECnet channel, as you can for normal TOPS-IO I/O.
When a program executes the Set PSI Reason Mask function,
DECnet-lO
simulates a status change from zero to the current status for the
affected link.
Thus, if the program has enabled the PSI system and
set that DECnet-lO condition in the reason mask, when the program
executes the .NSFPI function, DECnet-lO causes a PSI interrupt.
This
"free"
interrupt enables a PSI-driven program to do all its DECnet
checking in the PSI routine.
For any bit set in the reason mask corresponding to a status
(a
single-bit
field),
only changes from false to true cause PSI
interrupts.
For example, Normal Data Available changing from false to
true causes an interrupt, but not vice versa.
For the bit fields set
in the reason mask corresponding to a state (more than one bit in the
field),
all changes cause PSI interrupts.
For example, changing the
state from .NSCCS (Connect Sent) to
.NSCRN
(Running)
means that a
connect confirm message has arrived.

5-21

NETWORKS

5.3.10

Enabling the PSI Interface

The program can enable the PSI system for
doing the following:
MOVE I
PIINI.

AC,IVB
AC,
error return
normal return

any

DECnet-10

channel

;address of Interrupt Vector Block
;initiate PSI system

MOVE
PISYS.

AC, [PS.FON~PS.FAC,PSIARG]
AC,
; enable PSI
error return
normal return

MOVE I
NSP.

AC,NSPARG
AC,
error return
normal return

;NSP. argument list
ito specify reason for interrupt

EXP HANDLER

;interrupt vector: allow one
;4-word control block per channel
;interrupt control block
;specifies address of code
ito handle interrupt

IVB:
ICB:

°
°°
PSIARG: EXP .PCNSP
XWD <ICB-IVB>,O
XWD priority,

;NSP.-type interrupt
;offset in IVB to ICB
;priority of NSP. interrupts

NSPARG: XWD .NSFPI,3
XWD O,channel
XWD O,reason mask

;function code length
;status word (status, channel number)
;reason word

HANDLER:

;code to handle NSP. interrupt

When DECnet-lO interrupts the program,
interrupt control block contains:

the

status

word

the

XWD status, channel
Note that the PISYS. status word has the same format as the
argument (.NSACH word) of the NSP. function argument block.

second

,A program that has several links open at one time can include tables
indexed by the channel numbers of the links.
DECnet-lO assigns
consecutive channel numbers starting with the lowest number available.
Note,
however,
that DECnet-lO also reassigns channel numbers if the
program releases channels; therefore, the channel numbers may not be
sequential according to the order that the program first opened the
channels.
If the status word for a DECnet-lO PSI interrupt is zero, the
should ignore the interrupt.

5-22

program

NETWORKS

5.3.11

Reading and Setting the Link Quota and Goal

The DECnet-10 administrator allocates monitor buffers that DECnet-10
uses to hold message segments being sent or received, and also sets a
default number of buffers to use for each logical link.
The Set Quota
function allocates a portion of those buffers to a particular link.
The Set Quota function also allows the program to set the percentage
of buffers allocated to a link for input (receiving).
If the program has privileges, it can also use the Set Quota function
to establish the data request input goal.
DECnet-10 uses segment flow
control, in which the receiving node must request data before the
sending node can send it,.
To keep message segments flowing smoothly,
DECnet-lO can be asked to send data ,requests before the receiving
program issues a re,ad request.
DECnet-10 queues message segments that
arrive before the receiving program issues a read fun~tion for them.
The input goal controls the number of data requests that DECnet-10
will try to keep outstanding at the remote node. Whenever DECnet-10
receives, a message segment, it will send enough data requests to the
remote node to bring the total outstanding data requests to the goal.
If the input goal is larger than the link quota, this creates a pool
of "cached" messages that have been received but not yet acknowledged
("committed").
D~8net-10 allows cached messages to
be discarded at
any time because the source node ,will resend them after a timeout.
To change the link quota,
percent input,
or input
goal
(if
privileged) ,
the; program can execute the Set Quota function (. NSFSQ) .
The .NSFSQ argument list has the format:
. NSAFN
. NSACH
. NSAA1
. NSAA2
. NSAA3

Flags+XWD .NSFSQ,length (length = 3 to 5)
XWD status, channel number
Link quota
Percent of input (optional)
Input goal (privileged optional)

The prog~am can set the link quota for each link to any value up to
the maXl.mum number of buffers in the pool. DECnet-10 will allocate
that number of buffers but will not necessarily use them all for that
link.
The percent input can optionally be set to any number
100; the default is 50.

between

and

To find out the number of buffers allocated to the link,
the
percentage of those buffers allocated for input, and the input goal,
the program can execute the Read Quota function (.NSFRQ).
The
. NSFRQ
argument list has the format:
. NSAFN
. NSACH
. NSAA1
. NSAA2
. NSAA3

Flags+XWD .NSFRQ,length (length
3 to 5)
XWD status, channel number
Link quota
Percent of input (optional)
Input goal (privileged, optional)

If the argument block contains five words,
all
percent input, and input goal) will be returned.

5-23

the

values

(quota,

NETWORKS

5.3.12

Transferring Information Over the Network

Once a network connection has been established, the task at either end
of the logical link can send information to the task at the other end.
DECnet-10 provides functions for data messages and interrupt messages.
Data messages are primarily used by network tasks to move blocks of
data.
Interrupt messages are used by network tasks to exchange small
amounts of data (16 bytes or less) that are not sequentially related
to the main data flow.
Data transfers over a
logical link involve the segmenting and
reassembling of data at both the logical and physical link levels.
The network software accepts data from the user program,
segments it
to conform to the maximum segment size allowable on that logical link,
precedes each segment with a header, and passes these segments to the
physical link management
layer.
This layer segments the data to
conform to the maximum segment size allowable on the physical link and
proceeds each segment with a header to form a packet.
These packets
are then sent over the physical line to the destination node.
At the
destinat~on
node the reverse procedure takes place:
headers are
stripped and segments reassembled.
Occasionally, errors or status changes in a task require bypassing the
normal
flow of data so the message is delivered promptly.
DECnet-10
allows for the transmission and reception of short messages called
interrupt messages.
An interrupt message is sent and accounted for
independently of any buffered data messages and its delivery is
usually prompt.
Interrupt 'messages are limited in length to 16 bytes.
They are most effectively used as event indicators and usually require
the
subsequent exchange of data by the two processes owning the
logical link.

5.3.13

Sending Normal Data

To send a data message to another task, the program executes the Send
Normal Data function
(.NSFDS).
The
.NSFDS argument list has the
format:
. NSAFN
. NSACH
. NSAA1
. NSAA2

FLAGS+XWD .NSFDS,4
XWD status, channel number
EXP byte count
Byte-pointer to data

The program must include a count of the number of bytes in the message
and a byte pointer
(.NSAA2)
to the data in a program buffer.
As
DECnet-10 moves the data from the program buffer to the monitor
buffers,
it decrements the byte count and advances the byte pointer.
DECnet-lO then sends the data to the remote node,
segmenting it as
necessary to comply with the segment size.
If the program sets the NS.EOM flag, the program buffer represents a
message or the final portion of a message.
This can force DECnet-lO
to send the data even if it does not fill a segment.
Note that the
program must set the NS.EOM flag before executing the Synchronous
Disconnect function or the disconnect function fails.
If the program sets the NS.WAI flag, it waits until the UUO returns.
The UUO returns when DECnet-lO transmits the entire buffer of data.
If the program does not set the NS.WAI flag, the UUO returns when the
program's quota of monitor buffers is exhausted.
If the entire buffer
of data has not been sent, the byte count is non-zero.
The program
must check the byte count to determine whether all the data was sent,
and execute the Send Normal Data function again if necessary.
5-24

NETWORKS

If the link is in a state other than running (.NSSRN) or Connect Sent
(.NSSCS),
the UUO takes the error return.
If the link is in Connect
Sent state, the NS.WAI flag must be set so that the program can wait
for the state to change to Running, otherwise the UUO takes the error
return.
Example of Send Normal Data Function
SNDMSG.
HRRM

MOVE 1
NSP.
JRST

CHAN,DSBLK+.NSACH;Store channel number into arg block
TI,DSBLK
; Point to Send Normal Data arg block
TI,
; Send Normal Data
[OUTSTR [ASCIZ /?Can't Send Normal Data I]; Error
JRST
EREXIT]; Return

; Argument block for Send Normal Data
DSBLK:
NS.WAI+ NS.EOM+XWD .NSFDS,4
;Wait and end-of-message bits
Function, block length
XWD
0,0
Code supplies channel number
EXP
33
Number of bytes in message
POINT
7,MESSAG
Byte pointer to message to be sent
Message to be transmitted
MESSAG: ASCII/HI! THIS IS HOSTA SPEAKING!/

5.3.14

Receiving Normal Data

To receive a data message from another task, the program executes the
Receive Normal Data function (.NSFDR).
The .NSFDR argument list has
the format:
. NSAFN
. NSACH
. NSAAI
. NSAA2

Flags+XWD
.NSFDR,4
XWD status, channel number
EXP byte count
Byte pointer to data buffer

The program must include a count of the number of bytes expected and a
byte pointer to the buffer that will hold the incoming data.
As DECnet-IO moves data from the monitor buffers to the program
buffer,
it decrements the byte count and advances the byte pointer.
To determine the number of bytes received, the program must subtract
the value of the byte count after execution from the value specified
in the call.
The program will never receive data from more than one message in a
single execution of this function.
If the program does not set the
NS.EOM flag, (or clears it from a previous call), DECnet-10 returns as
much of the message as will fit into the buffer.
If the program sets
the NS.EOM flag, DECnet-IO returns as much of the message as will fill
the buffer and discards the excess data.
If DECnet-10 discards any
data, it sets the byte count to the negative of the number of bytes
discarded.
Thus,
a byte count of zero or greater means that the
message fit into the buffer.
If the program sets NS.EOM and does not
set NS.WAI as well, the .NSFDR function will fail.

5-25

NETWORKS

If the program sets the NS.WAI flag, the program waits until DECnet-10
transfers an entire message into the buffer or the buffer is full.
If
the program does not set the NS.WAI flag, the UUO returns inunediately
unless there is data waiting.
If so, DECnet-10 returns either an
entire message or as much of a message as will fill the buffer.
The
UUO takes the error return if the NS.EOM flag is set and the NS.WAI
flag is not.
This is to avoid the deadlock possible if the remote
task were to send a message larger than the local task's monitor
buffer quota.
'
If the link is in a state other than Running (.NSSRN) or Connect Sent
(.NSSCS),
the UUO takes the error return.
If the link is in Connect
Sent state, the NS.WAI flag must be set so that the program can wait
for the state to change to Running, otherwise, the UUO takes the error
return.
Example of the Receive Normal Data Function
READMS:
HRRZM
MOVE I
MOVEM
MOVE
MOVEM
MOVE I
NSP.
JRST

CHAN,DRBLK+.NSACH;Store channel number into arg block
T1,500
; Maximum number of bytes
T1,DRBLK+.NSAA1 ; Store into argument block
T1, [POINT 7,MESSAG]; Same with message byte pointer
T1,DRBLK+.NSAA2
Point to Receive Normal Data arg block
T1,DRBLK
T1,
; Receive Normal Data
REDERR
; Error in Receive Normal Data

When control comes here, there's a message
MOVE
T1, [POINT 7,MESSAG]; Get byte pointer to message
MOVE I
T2,500
Get size of buffer in bytes
SUB
T2,DRBLK+.NSAA1
Subtract number of bytes in buffer
to get number of bytes in message
JUMPLE T2,READM1
Skip output if no characters
Output loop
ILDB
T3,T1
Get first/next character
OUTCHR T3
Type out character
T2.-2
SOJG
Count characters and loop
; If end-of-message bit is on, type <End of message> on terminal.
READM1: MOVE
T1,DRBLK+.NSAFN; Get flag/function, length word
TLZE
T1, (NS.EOM)
; Test for EOM and turn off EOM Bit
OUTSTR [ASCIZ /
<End of message>/]
MOVEM

T1,DRBLK+.NSAFN

JRST

READMS

Turn off EOM bit in arg block for
next call
Go read another message

Argument block for Receive Normal Data
DBRLK: NS.WAI+XWD
.NSFLR,4
Wait bit, function, block length
XWD
0,0
Code supplies channel number
EXP
500
Maximum number of bytes in message
POINT
7,MESSAG
Byte pointer to message
Message to be received
MESSAG: BLOCK
100

Space for 500 character message

5-26

NETWORKS

5.3.15

Sending Interrupt Data

To send an interrupt message to another task, the program executes the
Send Interrupt Data function (.NSFIS).
The .NSFIS argument list has
the format:
. NSAFN
. NSACH
. NSAA1

Flags+XWD .NSFIS,3
XWD Status, Channel number
Pointer to string block containing the data

The pointer in .NSAA1 points to a string block
The data cannot be longer than 16 bytes.

containing

the

data.

The program must set the byte count and block length in the string
block. However, DECnet-10 ignores any bytes beyond the maximum of 16.
DECnet-10 does not segment interrupt messages, even if the NS.WAI flag
is not set.
If there are outstanding interrupt data requests from the
remote node, the Send Interrupt Data function causes DECnet-10 to send
the interrupt data.
The UUO takes the error return under any of the following conditions:

5.3.16

There are no outstanding interrupt data requests

There is already an interrupt message for transmission

The link is not in Running or Connect Sent state

The NS.WAI flag is not set while the link is in
Sent state

the

Connect

Receiving Interrupt Data

To receive an interrupt message from another task,
the program
The .NSFIR
executes the Receive Interrupt Data function (.NSFIR).
argument list has the format:
. NSAFN
. NSACH
. NSAA1

Flags+XWD .NSFIR,3
XWD Status, Channel number
Pointer to a string block to receive data

.NSAA1 contains a pointer to a string block that will contain the
data.
The maximum, block size is 16 bytes.
Interrupt messages cannot
DECnet-10
exceed that size.
If the string block is too small,
truncates the message.
The program must set the byte count and block length in the string
block,
but DECnet-10 ignores any space not necessary to hold data.
DECnet-10 either receives the whole message or none of it.
The interrupt message does not, of itself, cause an interrupt.
It can
bypass queued normal data messages.
The program must enable the PSI
system and set the PSI reason mask appropriately to cause an
interrupt.
If the link is in a state other than Running (.NSSRN) or Connect Sent
(.NSSCS)
the UUO takes the error return.
If the link is in Connect
Sent state, the NS.WAI flag must be set so that the program can wait
for the state to change to Running.
Otherwise, the UUO takes the
error return.

5-27

NETWORKS

5.3.17

Closing a Network Connection

Either of the two connected tasks can close a network connection.
A
connection can be closed normally, thereby preserving the integrity of
any data in transit, or a connection can be aborted without regard to
any undelivered data.
To close a connection normally, the program executes the Synchronous
Disconnection function (.NSFSD).
(The Synchronous Disconnect function
may be used by synchronously and asynchronously running programs.) The
.NSFSD argument list has the format:
. NSAFN
. NSACH
. NSAAI

XWD .NSFSD, length (length = 2 or 3)
XWD Status, Channel number
String block pointer to disconnect data (optional)

.NSAAI contains a pointer to an optional string block containing
disconnect data.
This data cannot be longer than 16 bytes.
If the Synchronous Disconnect function is executed successfully,
DECnet-l0 sends a disconnect initiate message to the remote task and
puts the link into Disconnect Sent state (.NSSDS).
While the link is
in this state,
the program cannot send any data, but should be
prepared to read any data sent by the other task before it received
the disconnect.
When the remote task confirms the disconnect,
DECnet-l0 places the link in Disconnect Confirmed state (.NSSDC).
The
program can then release the channel.
If the program releases the
channel
(using
.NSFRL,
RESET. or EXIT)
without waiting for the
disconnect message, unacknowledged messages from the remote task, could
be lost.
To insure that messages are not lost, the program should not set the
NS.WAI flag and should be prepared to read any further messages.
If
the PSI system is enabled and the reason mask is set for data
available, an interrupt occurs when a message arrives.
If the program
has also set the reason mask for disconnect confirm, the arrival of a
disconnect confirm message also causes an interrupt.
If not enabled
for interrupts,
the program can read any left-over messages by
executing one of the Receive Data functions (see the .NSFDR and .NSFIR
functions) with the NS.WAI flag set. By doing so,
the program also
determines the arrival of the disconnect confirm message because
either function takes the error return for a disconnect confirm
message.
If the link is in any state other than Running (.NSSRN) or if the last
message sent did not have the end-of-message (NS.EOM) flag set, the
UUO takes the error return.
Example of the Synchronous Disconnect Function
SYNDSC:
HRRM

MOVE I
NSP.
JRST

CHAN,SDBLK+.NSACH; Store channel number into arg block
Tl,SDBLK
Point to Sync Disconnect arg block
Tl,
; Synchronous Disconnect
[OUTSTR [ASCIZ /?Can't Sync Disconnect I]; Error
JRST
EREXIT]
; Return

; Argument block for Synchronous Disconnect
SDBLK: NS.WAI+XWD .NSFSD,2
; Wait bit, function, block length
XWD
0,0
; Code supplies channel number

5-28

NETWORKS

5.3.18

Releasing a Channel

After receiving a disconnect received or disconnect confirm message,
the task can execute the Release Channel function (.NSFRL) to release
the channel.
The .NSFRL argument list has tpe format:
. NSAFN
. NSACH

XWD .NSFRL,2
XWD status, channel number

The UUO returns immediately, even if the NS.WAI flag is set.
When a program receives a disconnect initiate message (.NSSDR state),
it executes the Release Channel function to confirm the disconnect,
release the link~ and return all buffers for that link.
DECnet-l0
sends a message to the other task confirming the disconnect.
When a program receives a disconnect confirm message, it executes the
Release Channel function to release the link and return all buffers
used for that link.
A program that has executed the Enter Passive function and is waiting
for a connection
(.NSSCW state)
can execute the Release Channel
function to release the link and any buffers allocated for the link.
Since no connection has yet been made, DECnet-l0 does not send a
disconnect confirm message.
If the link is in any state other than Connect Wait
(.NSSCW),
Disconnect Received
(.NSSDR),
or Disconnect Confirmed (.NSSDC), the
link is immediately released without any disconnect message sent to
the other task.
This is an abrupt aborting of the link.
Example of the Release Channel Function
RELCHN:
HRRM

MOVE I
NSP.
JRST

CHAN,RLBLK+.NSACH; Store channel number into arg block
Tl,RLBLK
; Point to Release Channel arg block
Tl,
; Release Channel
[OUTSTR [ASCIZ /?Can't Release Channel I]; Error
JRST
EREXIT]; Return

; Argument block for Release Channel
RLBLK:
NS.WAI+XWD .NSFRL,2
; wait bit, function, block length
XWD
0,.0
; Code supplies channel number

5.3.19

Aborting a Connection

To abort the connection, release the link, and send an abort message,
the program executes the Abort and Release function (.NSFAB).
The
.NSFAB argument list has the format:
. NSAFN
. NSACH
. NSAAI

XWD .NSFAB,length (length = 2 or 3)
XWD status, channel number
Pointer to disconnect data (optional)

.NSAAI can contain a pointer to an optional string block containing
disconnect data.
This data cannot,be longer than 16 bytes.
If the link is in Running state (.NSSRN) and the Abort and Release
function is executed successfully, DECnet-l0 sends an abort message to
the other task and immediately releases the link and all buffers
allocated to that link.
The other task should release the link on its
end to complete the disconnect.
If the link is in a state other than
Running, the UUo takes the error return.
5-29

NETWORKS
5.3~20

Reading the Disconnect Data

As a result of a Synchronous Disconnect, an Abort· and Release,
or a
Reject Connect function, DECnet-10 sends a disconnect message to the
other task.
To read the data from the disconnect message, the program
executes the Read Disconnect Data function
(.NSFRD).
The .NSFRD
argument list has the format:
. NSAFN
. NSACH
. NSAA1
. NSAA2

XWD .NSFRD,length (length = 3 or 4)
XWD status, channel number
Pointer to string block to receive the data
Reason code (optional)

.NSAA1 contains a pointer to a string block that will receive any data
that the other task included with its disconnect function.
If there
is no data, DECnet-10 leaves the string block empty. The data cannot
be longer than 16 bytes.
DECnet-10 sets .NSAA2 to a reason code that specifies the reason for
the disconnect.
These reason codes are not from the other task, but
from DECnet-10 and are universal to all DECnet implementations.
The
possible reason codes and their meanings are:

o - Rejected or disconnected by object (task)
1
2
3
4
5

6
8
9
10
11
34
38
39
41
42
43
44

No Resources
Unrecognized node name
Remote node shut down
Unrecognized object
- Invalid object name format
- Object too busy
.. Abort by network management
- Abort by object
- Invalid node name format
- Local node shut down
- Access control rejection
- No response from object'
- Node unreachable
- No link or logical link has been lost
- Discontlect complete
.. Image field too long (rqstrid, password, account, usrdata, etc.)
- Unspecified reject reason

Note that some of these reasons apply to a task that has rejected a
connection. DECnet-10 sends a disconnect initiate message when a task
rejects a connection as well as when the task disconnects the link.
If the link is in Disconnect Received state, (.NSSDR) the function is
executed successfully and the link remains in that state.
If the link
is in any state other than Disconnect Received,
the UUO takes the
error return.

5-30

NETWORKS

5.4

OBTAINING INFORMATION ABOUT DECNET-IO

For monitors that support DECnet-10 Version 3 and Version 4 networks,
the DNET. monitor call allows you to obtain data about the nodes in
the DECnet area you are in, and the DECnet links used for intertask
communication.
The DNET. call has three functions:
Symbol

Meaning

.DNLNN

Lists the
network.

.DNNDI

Returns information about each node in the
network as it relates to the EXECUTOR node
(that is, the node at which your program is
running) .

.DNSLS

Returns information about each logical link
established from your node. A logical link
is the path of communication used for
DECnet intertask communication.

Fcn-code

names

the

nodes

the

Function 1 for DNET. is .DNLNN, to list the node names of the nodes in
the DECnet area.
The calling sequence and argument block that you
must supply for .DNLNN is:
MOVE I
ac,addr
DNET.
ac,
error return
normal return
addr:
Where:

flags+.DNLNN"length+1
BLOCK length

addr points to the argument list.
length specifies the number of words to reserve in the
argument block for the returned list of node names.
The
maximum number of nodes in a DECnet-10 area is 1024,
so the
value of length should not exceed this.
The symbol .DNLLN is
defined to have this value.
If the length is too short for
the list of returned node names, the list will be truncated to
the number of words reserved.

You must set one of the following flags for .DNLNN:
Bits

Symbol

Meaning

DN.FLK

List only "known" nodes.
That is, the list of
node names returned will be all the nodes that
are defined with node names plus all nodes
that are reachable.
If the system is running
as an Ethernet end node,
the only node it
knows is itself.
The ST%END entry in the
%CNST2 GETTAB Table indicates whether the
DECnet is running as an Ethernet endnode.

DN.FLR

List only
reachable
nodes.
This
flag
restricts the returned list to only those
nodes that are currently in the network.

DN.FLE

List only the EXECUTOR node.
This is the node
at which the program is running.

5-31

NETWORKS

When the information is returned at addr+l, the form of
block is:
addr:

Where:

the

returned

you

place

flags+rDNLNN"length
count
first node name
second node name

Word 0 (.DNFFL)
this word.
Word I

contains the same

information

(.DNCNT) contains the number of node names returned.

Words 2 and following
name.

(.DNNMS)

each

contain

SIXBIT

node

Example
The following is an example of the use of .DNLNN:
MOVE

TI, [<.DNLNN>BI7!DN.FLK! .DNLLN]

( . DNLLN)
MOVEM
TI,DNARG
MOVE I
T I , DNARG
DNET.
TI,
HALT

;Function word to return
; known nodes up to the
; maximum length arg block
;Save word in arg block
;Point to arg block
;Ask for information
;Shouldn't happen

At this point, the argument block should be:
DNARG:

DN.FLK!<.DNLNN>BI7! .DNLLN
20
SIXBIT/ONE/
SIXBIT/TWO/
SIXBIT/THREE/
SIXBIT/KLI026/
SIXBIT/JINX/
SIXBIT/GNOME/

;20 nodes
;First node
;Second node

Function 2 of DNET. is
. DNNDI ,
which returns information about a
specific node in the network or about all the nodes in the network.
There are two methods of using this function:
step control and
non-step control.
In step mode, the informat£on is returned for each
node in the network, arranged by node address.
Under step mode,
you
must clear addr+l on the first call, so that the information returned
will begin with the first node in the node list.
If you do not set
the step mode flag, information is returned only for the node whose
name you specify in addr+l.
The control method is set by flag DN.FLS.
Specifically, the calling sequence and argument block for .DNNDI is:
MOVE
ac,addr
DNET.
ac,
error return
normal return
addr:

flags+.DNNDI, ,length
node name
BLOCK n
5-32

NETWORKS

Where the flags are:
Bits

Symbol

Meaning

DN.FLS

Set step mode
for
controlling
returned
information about every node in the OECnet
network.

ON.FLK

List information about known nodes.
Set
flag only if you set step mode (ON .FLS) .

ON.FLR

List reachable nodes.
Set this flag
you set step mode (ON .FLS) .

ON.FLE

List EXECUTOR node.

this

only

If you do not set ON.FLS, you can return information only about the
node whose name you specify, in SIXBIT, in addr+1.
The information is
returned in the argument block as follows:
addr:

flags+.ONNOI, ,length
node-name·
router information
link information
node address
circuit name

Where each word at addr is returned as follows:
Word

Symbol

Contents

.ONFFL

Flag word that you specified.

. ONNAM

The node name of the currently listed node .

.ONRTR

Router information. Bit 0
(ON.RCH)
of this
word is set if the node is reachable.
If bit
o equals 0, the node is not reachable.
The
remainder of the left half of this word
(ON.HOP)
contains
the
number
of
hops
(node-to-node paths) over which a signal must
pass to get from the EXECUTOR node to the node
in addr+1.
The right half of this word
(ON.CST) contains the relative cost of the
path to the specified node.

.ONLLI

Link information. Bit 0 (ON.VLO)
is set if
the
rest
of
this
word contains valid
information.
In this case, the left half of
the word indicates the number of logical links
currently established between the local and
remote
nodes.
If
bit
0 is ·off,
the
information in this word is
not
valid,
indicating that no attempt has been made to
communicate with the remote node.

.ONADR

Node address.

5-10

.ONCKT

Circuit
information.
This
information
describes the controller of the line that is
the first hop in the path to the remote node.
The circuit name is up to 4 ASCIZ words.

5-33

NETWORKS

Example
The following example shows how the DNET. function
.DNNDI
used in step mode to show information about known nodes:
MOVE

MOVEM
SETZM
MOVE I
DNET.
HALT

might

Tl, [<.DNNDI>B17!DN.FLK!DN.FLS!.DNNLN] ;Show link status
; up to the maximum
; length of the
; argument block (.DNNLN)
;Save in arg block
Tl,DNARG
DNARG+ . DNNAM
;Clear arg+l to start at
; First node name
;Point to arg block
,Tl, DNARG
Tl,
;Ask for information
;Shouldn't happen

The argument block returned may be:
DNARG:

DN.FLK!DN.FLS!<.DNNDI>B17!.DNNLN ;Flag word
SIXBIT/ONE/
;Node name
IBO!3B17!4B35
;Reachable,3 hops, cost=4
o
;No active links
1
;Node address=l
ASCII/DTE-O/
;Circuit-id
ASCII/-l/
;Continuation of
Circuit-id

Function 3 of DNET., .DNSLS, lists information about DECnet logical
links.
Every intertask communication through DECnet is performed over
a logical link (also known as a DECnet channel). Refer to Section 5.3
for information about establishing DECnet links.
The calling sequence
and argument list for .DNSLS is:
MOVE
ac,addr
DNET.
ac,
error return
normal return
addr:

Where:

DN.FLS+<.DNSLS"length>
jobno"channo
BLOCK n

Bit 0 (DN.FLS) of the word at addr is optional.
If set,
DN.FLS sets step control for the information returned.
Under
.DNSLS, step mode returns information about each link that is
open from the EXECUTOR node,
in the order of job number,
starting with job 1, and by link number within the job. After
all the jobs are listed, then job number -1 is listed. Under
step mode, you should clear addr+l (.DNJCN) the first time the
call is issued.
If DN.FLS is not set, non-step mode is the control method, and
addr+l
(.DNJCN)
should contain the job number and DECnet
channel number of the link for which you want the following
information.

5-34

NETWORKS

The link information is returned to you in the following form:
Word

Symbol

Contents

.DNFFL

The flag word you specified
block.

.DNJCN

The job number and channel number for which
the following information is appropriate.

.DNNOD

The node name (in SIXBIT) of the node to which
the link is made.

.DNOBJ

The object types of the communicating jobs.
The
standard object types are listed in
UUOSYM.MAC.
The left half of this
word
(DN.DOB)
contains the object type of the
destination process,
and the
right
half
(DN.SOB)
contains the object type for the
source process.
If a non-zero format type is
used for transmission, this entire word is o.

.DNSTA

Contains the status of the link.
The left
half
(DN.LSW)
contains
the
binary
representation of the link status
(refer to
Volume 2).
The right half (DN.STA) contains
the two-letter status of the link, in SIXBIT.
These status symbols are:

the

Symbol

Meaning

CF
CM
CR
CS
CW
DC
DR
DS
LK
NR
RJ

No confidence
No communication
Connect received
Connect sent
Connect wait
Disconnect confirmed
Disconnect received
Disconnect sent
No link
No resources
Remote node rejected
connect initiate message
Link is running

argument

.DNQUO

Quota word,
where
contains the input
(DN.QUO)
contains
outstanding messages

.DNSEG

Contains the segment size.

.DNFLO

Contains the flow control option,
where the
left half
(DN.XMF)
is the flow control for
transmission, and the right half
(DN.RCF)
is
the flow control for reception of messages.

.DNMSG

Contains the message count,
where the left
half
(DN.MRC) contains the number of messages
received, and the right half (DN.MXM) contains
the number of messages sent over the link.

5-35

the left half
(DN.QUI)
quota, and the right half
the
output
quota
of
allowed on the link.

NETWORKS

.DNMPR

Contains the monitor process or the terminal
number of the job associated with the channel
number in .DNJCN.
If the job number is -1,
this
words
contains
the
TTY
number
corresponding to the monitor pro?ess NRTSER's
link.

Example
The following example shows how the .DNSLS function might be used to
obtain information about the first link for job 1, under step control .
. DNSLN is the maximum block length for the function.
MOVE

T1, [<.DNSLS>B17!DN.FLS! .DNSLN]

MOVEM
SETZM
MOVE I
DNET.
HALT

T1,DNARG
DNARG+.DNJCN
T1,DNARG
T1,

;Link status, step
; control
;Save in arg block
iStart at first link
iPoint to arg block
iAsk for information
iShouldn't happen

At this point, the argument block should look like:
DNARG:

DN.FLS!, .DNSLS>B17! .DNSLN
-1, , 1

SIXBIT/THREE/
27,,27
240005,,'RN'
10,,10
100
2, , 1

2073,,1241
110

5.5

iFlag word
iNRTSER pseudo-job,
i channel 1
iConnected to node THREE
;NRT object type on both
i sides of the link
iBinary status, running
i link
;10 credits either
i direction
iSegment size
iSegment flow control"no
i flow control
;Messages sent and
i received
iLink is NRT TTY110

ETHERNET NETWORKS

The ETHNT. monitor call allows you to develop custom protocols for the
Ethernet
hardware.
Writing software using the function codes
described in Volume 2 gives you access to any device or system that is
connected to the Ethernet.
Once your program accesses the device or
system, data may be transmitted and received between the devices or
systems.
ETHNT. uses buffers called datagrams for information exchange over the
Ethernet. Datagrams are transmitted on logical communication channels
called portals. Portals uniquely identify particular Ethernet users,
by the portal ID.
Executing the Open User Portal function generates a
portal ID,
which is a 27-bit long,
randomly assigned
number.
Information associated with each portal includes a protocol type and
(optionally) one or more multicast addresses. A multicast address is
an address meant for multiple destinations on the same Ethernet.

5-36

NETWORKS

A protocol type indicates to the Ethernet the type of network
communications associated with the portal. Decimal values from 0 to
65535 are interpreted as protocol types.
Each protocol type must not
be associated with any other existing portals in the system.
If the
type contains -1, then the portal has no protocol type associated with
it.
If the type contains -2, promiscuous mode is enabled.
If the
protocol type contains -3, the Ethernet assigns the value "Unknown
Protocol Type Queue" to the portal.
This queue receives messages that
do not match any enabled protocol type.
Types -2 and -3 are not
implemented.

5.5.1

Transmitting and Receiving Information

When you queue a receive or transmit buffer
(ETHNT. functions
.ETQRB
and .ETQXB,
respectively), you must include a user buffer descriptor
list (also called a descriptor block) that contains information about
the buffer.
The
.ETUBL argument for these functions contains the
address of this buffer descriptor list. When you read the transmit or
receive queues (ETHNT. functions .ETRRQ and .ETRXQ, respectively), you
must also include the address of the buffer descriptor list.
Each of these descriptor blocks contains a status word, .UBSTS.
This
word indicates when a buffer has been transmitted or received
successfully.
If a failure occurred, the word indicates the nature of
the failure.
You should examine this word upon the completion of a
transmit or receive.
The format of the User Buffer Descriptor Block is:
Word

Symbol

Contents

.UBNXT

Address of the next user buffer descriptor.

.UBBID

User buffer ID.

.UBSTS

User buffer status.
This may return with the
flag UB.ERR, indicating an error occurred in
transmitting or receiving the buffer.
UB.ECD
in this word contains the error code if the
error flag is set.

.UBBSZ

Length of the datagram (in bytes) .

.UBBFA

A byte pointer to the datagram.

. UBPTY

Protocol type .

.UBDEA

A two-word Ethernet destination address.

.UBSEA

A two-word Ethernet source address.

The User Buffer descriptor block has a length of
symbol for block length.

5-37

13;

.UBLEN

the

NETWORKS

An example of the ETHNT.
This function includes
function.

queue receive buffers function follows.
returns from .ETRRQ, the Read Receive Queue

XMOVEI
ac,addr
ETHNT.
ac
error return
normal return
addr:

.ETQRB,,3
portal IO
UBL

;Function"block length
;Portal IO
;Address of buffer
; descriptor list

UBL:

;Address of next buffer
; descriptor list
;Returned on .ETRRQ
; function
; Status, returned on
; .ETRRQ
;Oatagram length in bytes
;Byte pointer

buffer IO
0
1000
POINT 8,OGM
0
0

OGM:

5.5.2

0
0
0
0

;Protocol type, returned
; on .ETRRQ
;Oestination Ethernet
; addr,returned on .ETRRQ
;Source Ethernet addr,
; returned on .ETRRQ

BLOCK <1000+3>/4

;Space for datagram

Returned Channel Information

When you request the Read Channel Information function (.ETRCI) or the
Read Channel Counters function (.ETRCC), ETHNT.
returns a buffer that
contains the requested information. The buffers are different for
each function.
The returned information will be at the address you
specified in the .ETBFA word of the function.
You specify the buffer
length
(in words)
in the
.ETBFL word of the function.
(Refer to
Volume 2 for a description of these words.)
The form of the return buffer for .ETRCI is:
Word

Symbol

Contents

. EICNM

The Ethernet channel number .

.EICEA

The current (two-word) Ethernet address.

5-38

NETWORKS

The form of the return buffer for .ETRCC is:
Word

Symbol

Contents

.ECCSZ

Seconds since the counters were last zeroed.

. ECCBR

Number of bytes received .

. ECCBX

Number of bytes transmitted .

. ECCDR

Datagrams received.

. ECCDX

Datagrams transmitted.

. ECCMB

Multicast bytes received.

. ECCMD

Multicast datagrams received.

. ECCXD

Datagrams
deferred.

. ECCX1

Datagrams transmitted, single collision.
A
collision
occurs
when
two
station's
transmissions overlap.

. ECCXM

Datagrams transmitted, multiple collisions.

. ECCXF

Transmit failures.

. ECCXX

The transmit failures
are:

transmitted,

bit

but

initially

mask.

The

bits

Bit

Symbol

Meaning

28
29
30
31
32
33
34

EC.XCL
EC.XBP
EC.XFD
EC.XFL
EC.XOC
EC.XSC
EC.XCC

EC.XEC

Carrier was lost.
Transmit buffer parity error.
Remote failure to defer.
Transmitted frame too long.
Open circuit.
Short circuit.
Collision
detect
check
failed.
Excessive collisions.

. ECCRF

Receive failures .

. ECCRX

The receive failures bit mask.

The bits are:

Bit

Symbol

Meaning

31
32
33
34
35

EC.RFP
EC.RNB
EC.RFL
EC.RFE
EC.RBC

Free list parity error.
No free buffers.
Frame too long.
Framing error.
Block check error.

. ECCUD

Unrecognized frame destination.

. ECCDO

Data overrun .

. ECCSU

System buffer unavailable .

. ECCUU

User datagram buffer unavailable.

5-39

NETWORKS

5.5.3

Returned Portal Information

When you request the Read Portal Information function (.ETRPI) or the
Read Portal Counters function
(.ETRPC),
ETHNT.
returns a buffer
containing the information.
The buffers are different for each
function.
The returned information will be at the address you
specified in the .ETBFA word of the function you requested.
You
specify the buffer length
(in words)
in the .ETBFL word of that
function as well.
The format of the returned Read Portal Information buffer is:
Word

Symbol

Meaning

.EIPCJ

Job Context Handle (JCH) of the portal owner.

.EIPPI

Protocol identification word.

.EIPCS

Channel status word.

.EIPKC

Controller status word.

The returned buffer for a Read Portal Counters has the format:

5.5.4

Word

Symbol

Meaning

.ECPSZ

Seconds since the counters were last zeroed.

. ECPBR

Bytes received.

.ECPDR

Datagrams received.

. ECPBX

Bytes transmitted.

. ECPDX

Datagrams transmitted.

. ECPUU

User datagram buffer unavailable.

Returned Controller Information

When you request the Read Controller Information function (.ETRKI)
or
the Read Controller Counters function
(.ETRKC), ETHNT.
returns a
buffer that contains the requested information.
The buffers are·
different for each function.
The returned information will be at the
address you specified in the .ETBFA word of the function.
You specify
the buffer length (in words) in the .ETBFL word of the function.
The buffer returned for a Read Controller Information request is:
Word

Symbol

Meaning

. EIKCS

Channel status word .

. EIKCP

CPU number of controller .

.EIKTY

Controller type. A value of 1
returned for an NIA20 interface.

. EIKNO

Controller number .

.EIKHA

A two-word Ethernet hardware address.

5-40

(EI. KNI)

NETWORKS

The buffer returned for a Read Controller Counters request is:
Word

Symbol

Contents

.ECKSZ

Seconds since the counters were last zeroed.

. ECKBR

Number of bytes received .

. ECKBX

Number of bytes transmitted.

. ECKDR

Datagrams received.

. ECKDX

Datagrams transmitted .

. ECKMB

Multicast bytes received.

. ECKMD

Multicast datagrams received.

. ECKXD

Datagrams
deferred.

. ECKX1

Datagrams transmitted, single collision .

. ECKXM

Datagrams transmitted, multiple collisions.

. ECKXF

Transmit failures.

. ECKXX

The transmit failures bit mask.
listed in Section 5.5.2

. ECKRF

Receive failures .

. ECKRX

The receive failures bit mask.
listed in Section 5.5.2

. ECKUD

Unrecognized frame destination.

. ECKDO

Data overrun .

. ECKSU

System buffer unavailable.

. ECKUU

User datagram buffer unavailable.

5-41

transmitted,

but

initially

The bits are

The bits

are

CHAPTER 6
TRAPPING, INTERCEPTING, AND INTERRUPTING

Assembly language programs can handle errors and interrupt execution
when specific conditions occur, using the following methods:
o

Trapping an error and jumping to a trap-service routine.
Traps can be set for several kinds of errors, including
illegal memory references, pushdown list overflows,
and
arithmetic overflows (generally CPU conditions) .

Intercepting specific kinds of errors.
The monitor then
transfers control to a predefined address for error handling
(generally I/O conditions) .

Using the software interrupt facility.
The program can
define any or all of a wide variety of interrupt conditions;
when one of these conditions occurs,
the monitor transfers
control.to a predefined address for interrupt handling.

Traps are synchronous events that often occur in the normal execution
of a program (for example, a context switch). After a trap, the PC is
predictable. A UUO, for example,
causes a trap to the monitor.
Interrupts, however,
are asynchronous conditions caused by external
events, inte~rupting program execution because of a specific change in
a condition or word.
After an interrupt, the PC is usually not
predictable. For example, if the interrupt occurs during I/O that
takes multiple instructions, the program can only detect the interrupt
after I/O is completed.
This chapter describes methods for handling halts,
errors,
and
software
conditions
in
a
TOPS-IO assembly language program.
Throughout this chapter, the term "interrupt" refers to a condition
produced by the software interrupt facility as opposed to the CPU's
hardware interrupt system. Using the software interrupt system is
more versatile than trapping and intercepting errors.
NOTE
APRENB traps and the
.JBINT .intercept block are
supported for Section 0 programs only. Programs that
require error handling and interrupting in non-zero
sections must use the Programmed Software Interrupt
(PSI) system.

6.1

TRAPPING ERRORS AND CONDITIONS

Your program can trap errors by using the APRENB monitor call to
enable certain kinds of traps .and then handle the traps that occur
with special trap-servicing routines.
6-1

TRAPPING, INTERCEPTING, AND INTERRUPTING

To set an APRENB trap, your program must:
1.

Place the address of the trap-service
.JBAPR in the job data area.

Enable one or more conditions
APRENB monitor call.

Include a trap service routine at the address given in
.JBAPR.
This routine should test to see which condition
occurred, and (if the program is to regain control)
should
end with the following instruction:

for

routine

trapping

location

issuing

JRSTF @.JBTPC
This instruction clears the bits that indicated the trap
condition, restores the state of the processor, and continues
the program.
APRENB traps can be set to handle the following conditions.
address specified in the error messages is your current pc.
a

The

Pushdown list overflows.
If your program does not trap these
overflo~s, the monitor stops the job and prints:
?Pushdown list overflow at user pc address

Illegal memory references.
If your program does not trap
these violations, the mon~tor stops your job and prints:
?Illegal memory reference at user PC address
Or, if the reference is from your program's pc:
?PC out of bounds at user PC address

References to nonexistent memory.
If your program does not
trap these references, the monitor stops your job and prints
?Non-existent memory at user PC address

Memory parity errors.
If your program does not
errors, the monitor stops the job and prints:

trap

these

?Memory parity error at user PC address
o

Clock ticks while the program is running.
These conditions
are not errors, and the monitor does not expect your program
to trap them.

Floating-point and arithmetic overflows.
If your program
does not trap these overflows,
the monitor ignores the
condition and continues your job. A condition such as this
can cause a hazardous situation for your program that could
result in fatal errors later in execution.
If you are using APRENB to trap for floating point or
arithmetic overflows, and the condition occurs in a non-zero
section, the monitor stops the job and prints:
?Arithmetic overflow at extended user PC address
The UTRP. call is the
arithmetic overflows.

preferred

6-2

method

for

handling

TRAPPING, INTERCEPTING, AND INTERRUPTING
When an enabled trap
following functions:

condition

occurs,

the

monitor

performs

the

Leaves a bit mask of conditions in .JBCNI in the job data
area.
The bit mask is the same as the APRENB bits AP.xxx.

Moves the current program counter (PC) to the location .JBTPC
in the job data area,
clearing the floating point and
arithmetic overflow flags.
Note that the PC at this time is
pointing to the next instruction to be executed and not the
instruction that caused the trap.
If this PC points to the
first or second instruction in the trap service routine, the
monitor stops your job.

Transfers control to the address given in location .JBAPR in
the job data area.
This is the address you have set as the
beginning of the trap service routine.

In general, each time a trap occurs the monitor clears the trap
conditions that your program set.
To enable repetitive trapping, you
must set the AP.REN bit when executing the APRENB monitor call.
This
repetitive-enable
does
not
affect clock-tick traps.
To trap
consecutive clock ticks, your program must explicitly re-enable the
trap condition.

6.2

INTERCEPTING ERRORS

For specific kinds of errors, the monitor intercepts control of your
program automatically.
Your program can allow the monitor to take
some default action for these intercepts,
or it can handle the
intercepts with a special intercept block.
This block allows you to
accept or suppress the monitor's error message for the encountered
error condition.
The errors that the monitor intercepts in this way are:
o

Fatal errors in your job's execution.
If these errors are
not intercepted,
they abort your job; the job cannot be
continued.
The possible error messages are:
?Illegal UUO at user PC address
?Address check at user PC address
?PC out of bounds at user PC address
You can add APRENB error traps to your program or enable the
software interrupt system and re-execute the program to
determine the exact cause of the error.

Jobs running past their time limits
(nonbatch jobs only).
This occurs when a job runs longer than the limit set by the
SET TIME command.
The error message is:
?Time limit exceeded
You can issue the SET TIME command again, altering your job's
time limit,
and then use the CONTINUE or START monitor
command to restart your program.

6-3

TRAPPING, INTERCEPTING, AND INTERRUPTING

Requests for space that would exceed your
error message is:

disk

quota.

The

[Exceeding quota on str]
Where:

str is the name of the relevant file structure.
You
must delete some files from your disk area before the
program can execute properly.

Requests for space on a file structure that is full.
Your
j0b must wait until some blocks are freed on the structure.

CTRL/Cs typed from the controlling terminal.
The monitor
normally stops your program and puts your terminal in monitor
mode.
No message is displayed.

Device errors that the operator can
offline disk.
The error message is:

correct,

such

Device dev OPRnn Action requested
Where:

dev is the name of the relevant device.
nn is the number of the node where the operator
take action.

must

The operator at that node receives a message stating that
there is a problem on the device. After fixing the device,
the operator can continue your job by typing JCONTINUE.
This
generates the following message to your job:
Cont by opr
The function of JCONTINUE is automatically performed
monitor once a minute.
The bits that affect the monitor's handling of
described in Table 6-1.

6.2.1

these

the

conditions

are

Using the .JBINT Intercept Block

To intercept these conditions, your program must:
1.

Place the address of an intercept block in location .JBINT in
the job data area.

Contain an intercept block at the address placed in .JBINT.

As with APRENB traps,
.JBINT traps should resume the interrupted
program (if desired) by using a JRSTF, where the return address is the
interrupted PC as stored by the monitor in the trap block at offset
.EROPC.
Again,
as with APRENB,
the stored PC mayor may not have
anything to do with the intercept condition.
The intercept block contains the address to which control is to be
transferred to handle the intercept, a message control bit, and bits
specifying which errors are to be intercepted.
The format of the
intercept block is given in Table 6-1.

6-4

TRAPPING, INTERCEPTING, AND INTERRUPTING
Table 6-1:

Format of .JBINT Intercept Block

Word

Symbol

Contents

.ERNPC

Length and new PC, where the left half of this
word is the length of the block (at least 3
words), and the right half is the new PC for
the intercept-handling routine.

.ERCLS

Intercept message control and class flags.
Bit 0
(ER.MSG)
suppresses the error message
that the monitor displays by default.
The
class flags are:
Flag

Symbol

Error

29
30
31
32

ER.EIJ
ER.TLX
ER.QEX
ER.FUL
ER.OFL
ER. ICC
ER. IDV

Error in job.
Time limit exceeded.
Disk quota exceeded.
File structure full.
Disk unit off line.
CTRL/C typed.
Problem with device.

33
34
35
2

.EROPC

Old PC.
This location must be zero in the
intercept block,
unless you want the monitor
to stop your job.
The monitor fills this word
with
the interrupt PC when an intercept
occurs.

.ERCCL

When an intercept occurs,
the monitor fills
this word with the channel number in the right
half and the class of error that occurred ~n
the left half.
The class flags are listed
under
.ERCLS,
with 18 added to the bit
position.

For each type of error condition, there is an associated class flag.
The monitor examines the class flags in .ERCLS and .EROPC to determine
whether to interrupt your program or to stop the job.
The monitor
interrupts your program for an error if your program sets the
appropriate flag in .ERCLS, and .EROPC is zero.
It stops your job if
you clear the appropriate flag in .ERCLS or if .EROPC is non-zero.
When the monitor interrupts your program, it returns the interrupted
PC in
.EROPC and the reason for the intercept in .ERCCL.
Then it
restarts your job at the location specified in .ERNPC.

6-5

TRAPPING, INTERCEPTING, AND INTERRUPTING

6.2.2

Examples of Error Intercepts

The following example intercepts CTRL/Cs.
monitor level as quickly as possible.
LOC
EXP
RELOC
INTBLK: XWD
EXP
BLOCK

The user is returned to the

.JBINT
INTBLK

;Set pointer to .JBINT
;Address of intercept block
;Resume relocatable

4,INTLOC
ER. ICC

;4 words long"handler address
;Intercept CTRL/Cs
;For returned data

;Intercept routine starts here.
INTLOC: MOVEM
MOVSI
TDNN
HALT

AC1,TEMP##
AC1,ER.ICC
AC1,INTBLK+.ERCCL

;Save AC1
;Get CTRL/C bit
;Was this a CTRL/C?
;No

;Here if it was a CTRL/C.
;At this point the program should release any special resources,
taking care to be quick and not to loop.
MONRT.

;Return to monitor

;Here if user CONTINUEs.
MOVE
EXCH
SETZM
JRSTF

AC1,INTBLK+.EROPC
AC1,TEMP
INTBLK+.EROPC
@TEMP

;Get continuation PC
;Restore AC1
;Clear to allow another intercept
;Resume where program stopped

The following example shows how to enable and handle a
intercept, preventing the user from returning to monitor mode:
LOC
EXP
RELOC
INTBLK: XWD
EXP
BLOCK

CTRL/C

.JBINT
INTBLK

;Set pointer to .JBINT
;Address of intercept block
;Resume relocatable

4,INTLOC
ER. ICC

;4 words long"handler address
;Intercept CTRL/Cs
;For returned data

; Intercept routine starts here.
INTLOC: SKIPN
JRST
SETOM
PUSH
SETZM
POPJ

CCEXIT
EXITOK
CCSEEN
P,INTBLK+.EROPC
INTBLK+.EROPC
P,

;Can program be interrupted by
; CTRL/C?
;Yes, go clean up and exit
;Set flag that we saw a CTRL/C
;Put interrupt PC in stack
;Reenable intercept
;Return to interrupted PC

CCEXIT: EXP

-1

;Flag set non-zero if a CTRL/C
;May not interrupt execution

CCSEEN: EXP

;Flag set non-zero by INTLOC
if a CTRL/C was typed and
; CCEXIT was non-zero.

EXITOK: SETZM

INTBLK+.EROPC

;Here if it was OK to interrupt
execution of the program. Do
any cleanup and exit.
6-6

TRAPPING, INTERCEPTING, AND INTERRUPTING
6.3

USING PROGRAMMED SOFTWARE INTERRUPTS

Your job can use software interrupts that are generated by a wide
variety of conditions.
These interrupts allow your program to respond
to external conditions and to requests for error servicing.
Most interrupts occur after the execution of one instruction and
before the execution of the next.
(It is possible for certain
multiple-operation instructions,
such as BLT and ILDB,
to
be
interrupted before processing is completed.)
When an interrupt condition occurs, the monitor first determines if
this type of condition is to cause a transfer of control to an
interrupt servicing routine.
If a transfer is to take place,
the
monitor transfers control to the location specified by your program's
interrupt control block.
If a transfer is not to take place,
the
condition's
default action occurs.
Figure 6-1 illustrates the
software interrupt process.
INTERRUPT
LEVEL

PROGRAM (USER)
LEVEL
1
1

=========1=========
User program

===================
1

=========1=========
Interrupt
condition
occurs

1
1
1

===================
1

I
;

;

====1====

YES

Did user
\
; enable for this \
\
interrupt
;
\
condition
;

=========

=============================

----------->

;

The interrupt servicing
routine, designated by
the appropriate interrupt
control block
1

1
1

====================

Take default
action;
(do nothing;
stop job;
print error
message)

1
1

====================

===========1==========

=========1==========
1

User program

Figure 6-1:

DEBRK monitor call

======================

The Software Interrupt Process

6-7

TRAPPING, INTERCEPTING, AND INTERRUPTING

When a transfer of control takes place, the monitor transfers control
to your program's interrupt servicing routine.
This action is called
granting an interrupt request.
After an interrupt request has been granted, your program operates at
interrupt level until it issues the DEBRK. monitor call. DEBRK.
dismisses the interrupt servicing routine and causes any pending
interrupt requests to be granted by the monitor.
If there are no
pending interrupt requests, your program is restarted at the point of
interruption as though no interrupt had occurred. However, if the
location containing the interrupted PC is changed during the interrupt
handling,
your program will return to a different location.
If the
interrupt occurred during the processing of a multiple-operation
instruction,
such as BLT, and the location containing the interrupted
PC is changed, the remainder of the instruction is not completed.
When the monitor grants an interrupt request,
the conditions that
caused the interrupt are not changed.
If the interrupt service
routine that galns control after the interrupt does no further
processing but only issues the DEBRK. monitor call, the result is the
same as if the interrupt had not occurred.
The monitor performs no
special action on the condition (such as stopping a job on CTRL/C) .
If an error interrupt occurs while the monitor is executing a monitor
call for your program, the call is terminated.
The only conditions
that can cause interrupts during monitor call processing are error
conditions in the calls. All other interrupt conditions (such as I/O
completion) are deferred until the monitor call takes the error return
or normal return.
To use software interrupts, your program must perform the following:
1.

Initialize the software interrupt system.
To do this,
use
the PIINI. UUO.
PIINI.
specifies the base address of an
interrupt vector.
The vector contains one or more 4-word
interrupt control blocks, which control the PSI system.
The
PIINI. UUO clears any previous software interrupt system
established by the program.

Turn on the PSI system with the PISYS. UUO.
This call
describes the conditions on which your program wishes control
to be passed to an interrupt service routine and the offset
to
the appropriate interrupt control block within the
interrupt vector specified in PIINI.

Contain an interrupt service routine to handle the specified
interrupts.
If control is to return to the main program, the
interrupt service routine should end with the DEBRK. UUO.
DEBRK. dismisses the software interrupt and returns control
to the location where the interrupt occurred.
Unlike APRENB
and .JBINT trapping,
you should not resume the interrupted
program by using a JRSTF instruction.

6-8

TRAPPING, INTERCEPTING, AND INTERRUPTING
PSI Monitor Calls

6.3.1

The following monitor calls are provided
programmed interrupt service routines:
o

PIINI.

allow

you

write

and PISYS.

To initialize the PSI system for your program,
you must
specify the PIINI. UUO.
You can specify extended (30-bit)
addressing format by setting the PS.IEA bit in PIINI.
To
specify the conditions for interruption and the location of
the interrupt handling routine, use PISYS. UUO.
o

PIFLG.
The PIFLG. UUO allows you to read or write PC flags at the
time of the interrupt.
Use PIFLG.
when you have specified
extended addressing in PIINI .. No flags are stored in the PC
when extended addressing is in use.

PIJBI.
The PIJBI. UUO allows you to interrupt another job or JCH
(Job Context Handle).
The job you intend to interrupt must
be enabled for the cross-interrupt (non-I/O)
condition.
If
that job is currently handling an interrupt, the PIJBI.
interrupt will fail,
and your program should repeat its
attempt to interrupt the job.

PITMR.
The program can be written to receive an interrupt after a
specified amount of time.
You must enable .PCTMR interrupts,
and then use the PITMR. UUO to specify the amount of time
after which to interrupt your job.

PIBLK.
Your program can examine the location of its interrupt
control block when an interrupt is in progress by using the
PIBLK. UUO.
This is usually used by library modules that do
not have direct control over the PSI vector and need to find
out where it is.

PISAV.

and PIRST.

Some programs may need to save and restore the PSI system's
data base.
For example,
this may be used when calling
another program using a GETSEG call, and the called program
also wishes to use the PSI system.
The PISAV. UUO returns the entire monitor data base for the
PSI system to the program.
This data base can be saved for
reloading by using the PIRST. UUO,
or can be analyzed to
construct reports.
The PISAV. UUO clears the current system
after returning it to the program. Any interrupt conditions
that may have occurred between the PISAV.
and associated
PIRST.
call are lost.
The PIRST. monitor call restores (to the monitor)
the data
base for the PSI system; this data base is the one that was
saved by a PISAV. call.
The monitor checks the format of the
restored block for consistency.

6-9

TRAPPING, INTERCEPTING, AND INTERRUPTING
6.3.2

Interrupt Control Block

The interrupt control block is the controller of the PSI system.
control block keeps track of the following:

The

The instruction that would have been executed next
interrupt occurred.

when

the

The location of the interrupt service routine to be used
processing the current interrupt.

for

The reason for the current interrupt.

Your program can associate more than one interrupt condition with one
interrupt control block. But the preferred usage is for your program
to associate only one interrupt condition with an interrupt control
block. An interrupt control block is represented in Figure 6-2.

17 18

1
New PC
1 .PSVNP
1------------------------------------------------------------1
1
Old PC
1 .PSVOP
1------------------------------------------------------------1 .PSVFL
Control flags
Reason
1------------------------------------------------------------1
1

Status word

Figure 6-2:
Where:

.PSVIS

Interrupt Control Block

new PC is
be used
30-bit PC
left half

the location of the interrupt servicing routine to
for processing the current interrupt.
This is a
if you set PS.IEA in the PIINI. UUO.
Otherwise, the
is ignored.

old PC is the current contents of the program counter.
If you
set -PS.IEA in the PIINI. UUO, this is a 30-bit PC.
You must
use the PIFLG. UUO to read or write the flags.
Otherwise,
.PSVOP contains an 18-bit PC and flags.
This value is equal
to the address of the instruction after the location in your
program where the interrupt occurred.
If your program was in
the process of executing a monitor call when the program
received the interrupt,
old PC contains the address of the
call's return location (either error return or normal return).
If,
because there was an error condition in the call, the
monitor call was terminated by the monitor,
old PC contains
the address of the monitor call,
instead of its return
address.
This value is where your program will be resumed at
the execution of a DEBRK. call. You can change the flow of
the program by changing this value to another location within
the program.
control flags are indicators specifying "the circumstances
under which an interrupt is to occur as well as how the
monitor should treat the interrupt level code.
This is what
to do with other,
possibly unrelated, interrupts while at
interrupt level (refer to Table 6-2).

6-10

TRAPPING, INTERCEPTING, AND INTERRUPTING
reason is the type of interrupt condition that has occurred.
If BIT 18 is 0, refer to Table 6-3.
If Bit 18 is 1, refer to
Table 6-4.
status word contains status information pertinent to the
conditiO;--causing the interrupt.
The information returned in
the status word depends on the condition that caused the
interrupt.
For I/O conditions
(see Table 6-3), the status
word is returned as:

°
Where:

17 18
UDX

File status

udx is the Universal Device Index for the device
specified in the interrupt condition.
For disk
devices, this is the channel number.
file status is the file status
result of GETSTS monitor call) .

word

(same

If your program is enabled for interrupt conditions PS.RDO, PS.RIE, or
PS.ROE on a network device, the monitor signals that the network node
is no longer accessible by storing the "input error," "output error,"
and "device offline" status bits in the status word of the interrupt
control block.
Then the monitor generates the interrupt.
This also
occurs if I/O is attempted to a device on a CPU that has been DETACHed
by the system operator.
Table 6-2:

Bit

Control Flags

Symbol

Meaning
Reserved for use by DIGITAL.

PS.VPO

Disable all interrupts until your
re-enables them by using the PISYS.
call.

PS.VTO

Disable all interrupts of higher priority
until your program issues a DEBRK . monitor
call.

PS . VAl

Allow additional interrupts.

PS.VDS

Dismiss any additional interrupt requests for
this condition (Table 6-4) or device that are
received while an interrupt is in progress.
This bit is useful if the interrupt service
routine wants to perform functions that would
cause another interrupt.

PS. VPM

Print the standard message, if one is relevant
to this interrupt condition.

Reserved for use by DIGITAL.

6-11

program
monitor

TRAPPING, INTERCEPTING, AND INTERRUPTING
6.3.3

Interrupt Conditions

The interrupt conditions are divided into two categories:
I/O
interrupts and non-I/O interrupts.
You can specify an I/O condition
for any device.
The I/O conditions are listed in Table 6-3.
The
non-I/O conditions are listed in Table 6-4.
Table 6-3:

I/O Interrupt Conditions

Bit

Symbol

Meaning

Bit

Symbol

Meaning

PS.RID

Input done

PS .RQE

Quota exceeded

PS.ROD

Output done

PS .RWT

I/O wait

PS.REF

End-of-file

PS.ROL

Device on line

PS.RIE

Input error

PS.RRC

RIB has changed

PS.ROE

Output error

PS. RDH

Device hung

PS .RDO

Device off line

PS.RSW

Reel switch

PS.RDF

Device full

PS.RIA

Input available

Table 6-4:

Non-I/O Interrupt Conditions

Code

Symbol

Meaning

-1

. PCTLE

Not applicable to batch jobs.
Your job's time
limit
has
been
exceeded.
The runtime in
milliseconds for your job is returned in the
status word.
You can issue the SET TIME command
to alter your job's time limit.

-2

.PCTMR

A timer interrupt occurred.

-3

. PCSTP

You issued a CTRL/C.
If your job is in terminal
input wait state when this interrupt occurs, the
monitor returns a 1 in Bit 0 of the status word.
If the interrupt routine issues a DEBRK.
call
without altering the new PC, the program will not
return to terminal input wait but will resume at
the PC following the monitor call that caused the
terminal input wait.
This may not be desirable in
some applications.

6-12

TRAPPING, INTERCEPTING, AND INTERRUPTING
-4

.PCUUO

A monitor call is about to be processed.
The
status word contains the monitor call that was
intercepted.
If the interrupt routine issues a
DEBRK.
call without altering the old PC, the
program will re~rn to the intercepted monitor
call and another interrupt will occur.
Note that
the only way to have the monitor call actually
processed by the monitor is for the interrupt
routine to execute the call itself.
You cannot
use .PCUUO to trap any of the PSISER UUOs (such as
PIINI., PISYS., and DEBRK.).

-5

.PCIUU

-6

.PCIMR

-7

.PCACK

The

-10

.PCARI

arithmetic exception has occurred.

-11

.PCPDL

A push-down list overflow has occurred.

-12

.PCNSP

One of the following occurred on DECnet:
DECnet
data became available,
there was a logical link
status change, or interrupt data became available.
Refer to Chapter 5 for information about the
NSP. UUO.

-13

.PCNXM

A
non-existent
referenced.

-14

.PCAPC

A line frequency clock tick occurred.
The status
word contains the universal date/time word.
This
occurs only when your job is actually running;
this does not occur every clock tick.

-15

.PCUEJ

A fatal error has occurred in your job.

-16

.PCXEJ

external condition has caused a fatal error
your job.

-17

.PCKSY

A KSYS warning has occurred.
The status
contains the minutes left until KSYS.

word

-20

.PCDSC'

The dataset status has changed.
The
contains the new dataset status.

word

-21

.PCDAT

Either an ATTACH or DETACH monitor call has been
executed.
If DETACH, the status word contains a
-1;
if ATTACH,
the status word contains the
terminal's Universal Device Index.

-22

.PCWAK

A WAKE monitor call was executed.
The status word
contains the job number of the program that issued
the wake.
This interrupt is given only if the
WAKE monitor call was actually issued while the
job was hibernating.

illegal monitor call has been executed.
The
status word contains the illegal monitor call.

illegal memory location has been referenced.
The status word contains the illegal effective
address.

address check has occurred.
contains the device name.

6-13

memory

status

location

has

status

word

been

TRAPPING, INTERCEPTING, AND INTERRUPTING
-23

.PCABK

An address-break condition occurred.

-24

.PCIPC

Your job has received an IPCF packet in its input
queue.
The status word contains the associated
variable: the length of the packet in the left
The
half,
and the flag word in the right half.
in
IPCF communications facility is described
Chapter 7.

-25

.PCDVT

A DECnet event occurred. The status word contains
flags (DR.xxx) indicating the event.

-26

.PCQUE

An ENQ/DEQ resource is available for ownership.
The status word contains the request-id of the
request that was granted.
If multiple requests
were granted,
the request-ids are ORed into the
status word.
Refer to Chapter 8
for
more
information.

-27

.PCNET

The ANF-10 network topology has changed.
If your
program receives this interrupt, it should issue a
NODE. monitor call to determine the state of the
network.
This interrupt is useful for determining
when a network node goes offline or comes online.
!his event occurs only in the ANF-10 network
software.

-30

.PCJBI

A PIJBI. UUO was executed.
The status
word
contains the job number or JCH in the left half
and the value sent in the right half.

-31

.PCDTC

A date/time change occurred.
The status word
contains the universal date and time offset to be
added.

-32

.PCOOB

An out-of-band character was received.
The status
word contains either the character and the udx of
the TTY, or 400000"udx.

-33

.PCRC1

Reserved for customer use .

-34

. PCRC2

Reserved for customer use.

-35

.PCSCS

An SCS. event occurred.
Returned flags take the
form SC%xxx.
See the description of the .SSSTS
word of the SCS. monitor call in Volume 2 for a
list of the flags.

-36

.PCETH

An Ethernet event occurred.
Flags returned are in
the form ET.xxx.
See the description of the
.ETPSW word of the ETHNT. monitor call in Volume 2
for a list of the flags.

-37

. PCLLM

An LLMOP event occurred.

-40

.PCLVT

A LAT event
occurred.
A
request
for
a
host-initiated connection has been accepted or
rejected.
See the description of the
.LARHC
function of the LATOP. monitor call in Volume 2.

6-14

No flags are returned .

TRAPPING, INTERCEPTING, AND INTERRUPTING

When an interrupt is granted to a program,
the interrupt routine
should investigate all possible causes for the interrupt.
This is
necessary because the amount of time that elapses between the event
and the actual granting of the interrupt varies with system load and
various scheduling parameters. For example, a single interrupt for
network
topology change
(.PCNET)
could represent several nodes
appearing online or going offline.
It is possible for a condition enabled by a program to occur under
circumstances where the program could not be granted an interrupt.
In
this case, the monitor acts as though the program were not enabled for
these interrupts.
This may cause the job to be stopped with an error
message.
The reasons an interrupt cannot be granted immediately are:
o

The condition was caused by either the page fault handler
DDT.

The interrupt system is not active (turned off) .

The condition occurred during an interrupt routine that is of
equal or higher priority.

If the PSI vector is not usable, the monitor will
and the following message will be displayed:

halt

your

program

?PSI interrupt vector at addr, for CONDITION, DEVICE, is paged out,
(symbol)
(name)
writeprotected,
or
illegal
In the message, addr refers to the address of the illegal vector.
The
condition symbol-rs-the last three characters of the non-I/O condition
as listed above (.PCxxx, where xxx is the symbol).
If you run your program in a non-zero section,
you should set the
PS.IEA bit in the PIINI. UUO to allow interrupting.
If you have not,
the monitor halts your program and displays the following message on
an interrupt:
?Illegal non-zero section PSI interrupt at user PC addr

6-15

TRAPPING, INTERCEPTING, AND INTERRUPTING
6 • 3 ,. 4

Example Using Programmed Interrupts

The following program shows how to use the PSI system to optimize disk
I/O and compute-bound background activity:
TITLE PIEXMP - Example of programmed interrupts
iThis program writes a file containing the integers i from 0 to 100000
while doing a compute-bound background i task.
Because the program
never blocks for I/O, i it can use all of the available CPU time.
i
By using the programmed interrupt system, it drives i the disk at full
speed.
SEARCH

UUOSYM

iSymbol definitions

iACs
iWork N==2 iNumber to write on disk

T1==1
iI/O channels

iDisk file

DSK=l
ilnitialization
START: RESET
iGet address of PI vector block
HALT iNot implemented
for asynch binary output
HALT iCan't write
XWD O,PS . ROD
0]] iPriority O"reserved
on disk
HALT
iHere

iReset everything MOVE I
T1,VECTOR
PIINI.
T1,
ilnitialize PI system
OPEN DSK, [UU.AIO+.IOBIN iOpen disk
SIXBIT /DSK/
XWD OB, 0]
MOVE
T1, [PS.FAC+[EXP
DSK
iOffset"output
done
EXP
PISYS.
T1, iEnable for output done
iFailed MOVEI N,O ilnitialize N

on an output-done interrupt or at start of program

OUTDON: SOSGE
BYTECT
iNo, go output buffer
buffer CAME
N, [AD100000]
next number
CLOSE
iFinished

iRoom in this buffer? JRST DMPBUF
IDPB N,BYTEPT iYes, store in this
iDone? AOJA N,OUTDON iNO, back for
DSK, iYes, close the disk file EXIT

iHere to output the buffer
DMPBUF: OUT
DSK,
iNo errors and more buffers
HALT iFatal I/O error

iWrite out the buffer
JRST OUTDON
STATZ
DSK,IO.ERR
errors?
iAny

iHere all available buffers are full,
background task.
DEBRK.
never get here

so we want to go back

iDismiss the interrupt

6-16

the

HALT

iCan

TRAPPING, INTERCEPTING, AND INTERRUPTING

;Here if no interrupt was in progress.
We
were
initialization, and must now start the background task.
MOVSI
PISYS. TI,
on LOOP:
AOJA TI,LOOP

called

TI, (PS.FON)
;Turn on the PSI system so we can
; get traps from background task
HALT ;Can't turn it
MOVE I
TI,O ; Simple-minded background task
;Do it again

;Buffer ring header
OB:
BLOCK
1 BYTEPT:
BLOCK 1 ;Byte count

BLOCK

;Byte

pointer

BYTECT:

;Interrupt vector
VECTOR: EXP
;Flags
EXP 0
END

OUTDON
EXP

;New PC EXP 0 ;Old PC

o ;Status

START

6-17

stored

here

CHAPTER 7
COMMUNICATING BETWEEN PROCESSES USING IPCF

The TOPS-I0 interprocess communication facility (IPCF) allows jobs and
programs on the same computer system to communicate with each other.
This communication occurs when processes send and receive information
in the form of packets.
For the purposes of this description, a
program is called a "process."
When a sender process sends a packet of information to a receiver
process,
the packet is placed in 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 packet
input queue, the receiver can enable the PSI system to generate a
software interrupt when a packet is placed in the input queue.
Refer
to Chapter 6 for details on the PSI system.
The following monitor calls allow you to use IPCF:
0

The IPCFS. UUO sends an IPCF packet to another process.

The IPCFR. UUO retrieves a packet sent by another process.

The IPCFQ. UUO queries the IPCF input queue about your job.

The IPCFM. UUO replaces a
process.

message

exchange

with

system

Any user without privileges can use the IPCF calls.
A subset of
functions are limited to privileged users, because IPCF services many
communications needs of the monitor and the GALAXY batch and spooling
system. Most functions enabling communication between user processes,
however, do not require privileges.
The IPCFM. monitor call is fully
documented in Volume 2.
The words and functions described in the
following sections apply only to IPCFQ., IPCFR., and IPCFS ..

7.1

PACKETS

Information is transferred in the form of packets from one process
another.
Each packet is divided into two parts:
o

A Packet Header Block (PHB) of four to six words in length.

A Packet Message
message.

Block

(PMB),

which

contains

the

actual

The PHB describes the characteristics of the communication
(defines
the sender and the receiver, for example) and points to the PMB, where
the actual message is stored.

7-1

COMMUNICATING BETWEEN PROCESSES USING IPCF
The PMB will be either a short-form block consisting of a few words
(less than or equal to 12 (octal»
or a long-form block consisting of
an entire memory page (1000 words).
Use of the long-form block is
also called "page mode." The default packet is a short block, but you
can use the long form if you have privileges and if you set the
appropriate flags bits in the packet header block (refer to Section
7 .3) .

For the short block, the monitor copies the data into an internal
buffer to await a receiver.
The short message length must be within
the monitor's maximum, which is stored in the GETTAB Table
.GTIPC,
item number 0 (%IPCML).

7 _2

FORMAT OF THE PHB

The format of an IPCF Packet Header Block is as follows:

17 18

. IPCFL

Flags

.IPCFS

Sender's PID
Receiver's PID

. IPCFR

---------------------1------------------Length of message

. IPCFP

PMB address

---------------------1------------------Project-programmer number of sender

. IPCFU

Capabilities of sender

. IPCFC

Figure 7-1:

Packet Header Block

The PHB describes the sender of the message,
the receiver of the
message,
and the location of the actual data message (Packet Message
Block).
It also contains flags that instruct the monitor to handle
the communication of the data in different ways.
To set up the PHB, you may include the following words:
Word 0 (.IPCFL) contains instruction flags in the left half,
and
packet descriptor flags
in the right half.
Instruction flags are
listed in Section 7.2.1.
Descriptor flags are listed in Section
7.2.2.
Word 1 (.IPCFS) contains the sender's process identifier.
For the
sender,
this word is filled by the monitor.
For the receiver, one of
the following may be specified in .IPCFS:
o

The job number or JCH (Job Context
process.

the

sending

The sending process's PID.
(A PID is a unique
IDentifier that you can obtain from [SYSTEM] INFO.)

Process

The address of the sender's PID.
Setting the instruction
flag IP.CFS in Word 0 allows you to indirectly reference the
sender's PID.
The monitor assumes that .IPCFS contains the
location of the sender's PID.
7-2

Handle)

COMMUNICATING BETWEEN PROCESSES USING IPCF

Zero.
If you place a zero in this
assume one of the following:

word,

the

monitor

will

If your job has any PIO(s), the monitor will choose one.

If your job has no PIO(s), the monitor will use
for your current context.

the

JCH

In many cases, the job number sufficiently identifies a process, and a
PIO need never be used.
The PIO is used for programs that will be run
from different jobs, so the program does not depend on job numbers.
Refer to Section 7.8.2 for information about obtaining PIOs.
Word 2 (.IPCFR) contains the receiver's process identifier, which may
be a job number, JCH, 0, a PIO, or address of PIO (if IP.CFR is set in
Word 0).
This word has the same characteristics as Word 1.
For the
receiving process, if this word is zero, the monitor fills it with the
receiver's PIO.
Refer to Section 7.6 for more information about
receiving packets.
Word 3 (.IPCFP) contains, in the left half, the length of the PMB,
and,
in the right half, the location of the first word in the PMB.
For the short-form packet, the sender must include the actual length
of the PMB,
and the receiver must specify the maximum length of the
PMB it is expecting, in the left half of this word.
For the long-form
packet,
both sending and receiving PHBs must specify 1000 in the left
half of this word.
For the long-form packet, this word must be page
aligned.
Word 4 (.IPCFU)
contains the PPN of the sending process.
This
optional word is ignored for sending packets.
It is filled by the
monitor on a receive, if reserved by the process.
Word 5 (.IPCFC) contains the sender's IPCF capability word.
capability word is described in Section 7.2.5.

7.2.1

The

IPCF

IPCF Instruction Flags

The following instruction flags can be stored in the left half of Word
o (.IPCFL) of the PHB.
They are optional,
and are listed here
according to their bit positions.
Bits

Symbol

Meaning

IP.CFB

00 not block the receiver's job if there
is no
packet
in
the input queue.
This bit is
meaningful only when an IPCFR. monitor call is
issued.
If this bit is set when the IPCFR. is
issued and there is no packet in the input
queue,
the IPCFR. call takes the error return
and the monitor returns error code 3 (IPCNP%) in
the AC.
Use the HIBER monitor call or the PSI
system (see Chapter 6) to notify the job when
the packet arrives.

IP.CFS

Use the PIO obtained from the address specified
in
. IPCFS as the sender's PIO;
this PIO is
called the indirect sender's PIO.

7-3

COMMUNICATING BETWEEN PROCESSES USING IPCF

7.2.2

IP.CFR

Use the PID obtained from the address specified
in
.IPCFR as the receiver's PlD; this PID is
called the indirect receiver's PID.

IP.CFO

Allow the sending process to send one packet
more than the send packet quota.
(This is
called the "last phone call" bit.) This bit is
meaningful only when an IPCFS. monitor call is
issued.
The default send quota is two.
The
quota is stored in GETTAB Table .GTIPQ, bit
field IP.CQS.

IP.CFT

Truncate the message if it is longer than the
area reserved for it in .IPCFP.
This flag is
meaningful only when set for the IPCFR. monitor
call.
If the IPCFR. call does not set this bit
and the packet in the input queue is larger than
the area reserved for it, the IPCFR. monitor
call takes the error return and the monitor
returns error code IPCTL% in the AC.
You can
delete messages from your input queue by sett{ng
.IPCFP to 0 and IP.CFT to 1.
This is a
convenient way to delete long messages received
when your program accepts only short messages.

IP.CFL

Allow a privileged program to send short-form
packets that are larger than the installation's
defined maximum.
The system's absolute maximum
is 510
(decimal)
words.
The preferred method
for sending packets of this length is to use
page mode (long-form packets)

IP.CRP

Receive packets only if they are addressed to
the PID set in the . IPCFR word as specified in
the IPCFR. UUO.
This is called a
"PID-specific
receive".
If this bit is not set, the monitor
will simply return the next message received (in
chronological order)
for any PID owned by this
job.

IPCF Packet Descriptor Flags

You can specify the following flags by setting the appropriate bits in
the right half of . IPCFL, the first word in the packet header block.
Bits

Symbol

7-17

Meaning
Reserved for use by DIGITAL.

IP.CFP

This bit signifies
that
the
program
is
privileged and intends to perform privileged
functions.
If this bit is not set,
privileged
functions will not succeed.
If this bit is set,
both processes must be privileged processes.
If
an unprivileged process sets this bit, the error
return is taken from the monitor call and the
monitor returns error code IPCPI% in the AC.

IP.CFV

The packet message is a page of data
(1000
words) .
Both the sender and the receiver must
set this bit.
Refer to Section 7.3 for more
information about using long-form messages.
7-4

COMMUNICATING BETWEEN PROCESSES USING IPCF
20

IP.CFZ

Send a packet with a packet header block but no
packet message block;
this type of packet is
called a zero-length packet.

IP.CFA

The sender of the packet requires the receiver
to acknowledge receipt of the packet.
The
monitor does not ensure that the acknowledgement
is made.
Reserved for use by DIGITAL.

22-23
24-29

IP.CFE

The field for an error code sent by a privileged
process
([SYSTEM]INFO and [SYSTEM] IPCC) .
These
error codes (70 through 77) are listed in Volume
2,
in the description of the IPCFR. UUO.
An
error code in this field indicates that the
monitor call executed properly and the normal
return was taken with no errors returned in the
AC.
However, the sending process (for example,
[SYSTEM] INFO) is returning an error,
such as
"duplicate name."
If this field is empty, no
error occurred.

30-32

IP.CFC

The field for the system sender code.
This code
can
be set by a privileged process only;
however, the monitor will return the code so
that an unprivileged process can examine it.
The system sender codes are:
Code

Symbol

Meaning

. IPCCC

The
packet
[SYSTEM] IPCC.

sent

. IPCCF

The
packet
was
sent
system-wide [SYSTEM] INFO.

. IPCCP

The packet was sent by the
receiver's local [SYSTEM] INFO.

. IPCCG

The
packet
was
sent
by
[SYSTEM] GOPHER,
a privileged
process
that
sends
[SYSTEM]IPCF message types 40
and 50 listed
in
Section
7.8.3.
It does not accept
packets from user programs,
but
often conducts dialogs
with certain system programs.
GOPHER is an active task; IPCC
is a passive task.

33-35

IP.CFM

The packet in the input queue
is a packet that was returned
to the sender.
If IP.CFM is
equal to 1 (.IPCFN) the packet
was returned to the sender
because the PID was destroyed
before the packet was received
but after the packet was sent.
IP.CFM can only be set by a
privileged
process.
The
monitor returns the packet so
that a nonprivileged process
can examine it.

7-5

was

COMMUNICATING BETWEEN PROCESSES USING IPCF
7.2.3

Process Identifiers

Words 1
(.IPCFS)
and 2
(.IPCFR)
of the PHB are reserved for
identifying the sender and the receiver of the packet. When sending a
.IPCFR can be
packet, .IPCFS can be zero. When receiving a packet,
zero.
Job numbers may be used to identify a process.
However, if your job
has more than one process, or your job is communicating with more than
one process, the PID uniquely identifies each process.
PIOs are
assigned by
[SYSTEM] INFO,
and mayor may not be accompanied by a
symbol name.
PIOs are assigned to a process by
[SYSTEM] INFO.
There can be any
number of PIOs assigned to a process, up to the maximum PIO quota,
which by default is two.
Each PID is unique and never reused until
the system is reloaded; in this case, all previous PIO assignments are
cleared.
Both communicating processes should agree on the PIOs and
symbolic names being used.
This facility releases the programs from
system-specific characteristics that may change from execution to
execution, such as job numbers.
The method for sending packets to [SYSTEM]INFO is described in Section
7.8.2.

7.2.4

Symbolic Names

Symbolic names are specified by the process. A process specifies the
name
in
the
PMB when it requests a PID from
[SYSTEM] INFO.
[SYSTEM] INFO assigns a PID to the process and associates the symbolic
name with the PIO.
[SYSTEM] INFO will not allow the assignment of a
name that is already assigned to another PIO, unless the owner of that
name makes the request.
A symbolic name must be an ASCIZ string up to 29 characters long.
Therefore,
the maximum size of the name is six data words terminated
by a zero byte.
The symbolic names to be used should be agreed upon
in advance by the communicating processes.
A symbolic name can be written in one of the following formats:
Format

ExamEle

text

ASCIZ

/CORPORATION/

[project, programmer] text

ASCIZ

/[27,2407]TEST/

text [project, programmer]

ASCIZ

/TEST[26,7077]/

text ['ANY' ,programmer]

ASCIZ

/EXAMP['ANY' ,5332]/

['ANY' ,programmer] text

ASCIZ

/['ANY' ,2433]FOO/

text ['ANY' ,'ANY']

ASCIZ

/ACCT['ANY' ,'ANY']/

['ANY' ,'ANY']text

ASCIZ

/['ANY' ,'ANY']WONOER/

text[project,'ANY']

ASCIZ

/FILE[lO,'ANY']/

[project,'ANY']text

ASCIZ

/[23,'ANY']CLASS/

[SYSTEM]text

ASCIZ

/[SYSTEM]GOPHER/

text [SYSTEM]

ASCIZ
7-6

/GOTO[SYSTEM]/

COMMUNICATING BETWEEN PROCESSES USING IPCF
The wildcard character * can be substituted for
Note that the following strings are different:
Format

Example

Name [PPN]

ASCIZ/FOO[10,10]/

[PPN] Name

ASCIZ/[10,10)FOO/

the

phrase

'ANY'.

When a PPN is used as part ~f the symbolic name, it must be the PPN
under which the process ~s currently running.
[SYSTEM] can only be
specified as part of the symbolic name of a privileged process.
If a process wants to send a message to another process but it knows
only the process's name and not its PID, the sending process can ask
[SYSTEM]INFO for the PID associated with the name.
Note,
however,
that the list of PIDs and symbolic names that [SYSTEM] INFO keeps is
cleared when [SYSTEM]INFO or the system is reloaded.

7.2.5

IPCF Capability Word

Word 5 (.IPCFC) of the PRB contains flags representing the privileges
of the sender.
Ignored when specified for a sending process, this
word will be filled by the monitor on a receive,
if this word was
reserved.
The sender capability bits are:

7.3

Bits

Symbol

Meaning

IP.JAC

1
2
3

IP.JLG
IP.SXO
IP.POK

The sender of the packet is running with the
JACCT bit set; it is a privileged process.
The sender of the packet is logged-in.
The sender of the packet is an execute-only job.
The sender of the packet has POKE privileges.

IP.IPC

5-17
18-26
27-35

IP.SCN
IP.SJN

The sender of the packet has privileges allowing
him
to
perform
special,
privileged IPCF
functions.
Note that this requires your program
to have JP.IPC set in the job privilege word.
Reserved for DIGITAL.
Sender's context number
This field contains the job number of the
sender.

LONG-FORM MESSAGES

A packet can take either of two forms:
short
(normal)
or long.
A
short message has a PMB of 0 to 12 (octal) words. A long message has
a PMB consisting of one page (1000 octal words) and can be sent using
page mode.
Only one page can be sent per packet.
To use page mode,
both sending and receiving processes must:
o

Set the left half of Word 3 (.IPCFP) of the PRB to be 1000.

Specify the page number in the right half of .IPCFP.

Set Bit 19 (instruction flag IP.CFV) in Word
the PRB.

7-7

(.IPCFL)

COMMUNICATING BETWEEN PROCESSES USING IPCF

7.4

During an IPCFS., the page is removed from your program's
core image.
You can create a new page in its place using the
PAGE. UUO.

During an IPCFR., a page is created at the virtual address
specified in the right half of .IPCFP.
It is assumed that a
page has been reserved there for this purpose.
If the page
already exists,
the IPCFR. UUO fails.
Your program can
ensure that the page is available by destroying it with the
.PAGCD function of the PAGE. UUO (with PA.GAF set), before
using IPCFR.
If the page number is in a section that does
not exist, the section map will be created automatically.

QUOTAS

For each process, outstanding IPCF messages are counted for sending
and recelvlng.
The number of packets that have been received are
counted and this count is stored in GETTAB Table 105 (.GTIPP) in word
IP . CQO.
The number of packets that have been sent but have not been
received is stored in the same table in IP.CQP.
Both the send queue
and the receive queue are limited to a maximum number of packets that
can be outstanding:
these are the send quota and the receive quota.
This quota cannot be exceeded, and when the maximum is reached, the
process must wait until a packet has been sent/retrieved from its
queue.
The default quotas allow two messages outstanding in the send queue
and five messages outstanding in the receive queue.
However, the
system manager at each installation can set IPCF quotas on a per-user
basis.
If these quotas are zero, the process cannot use IPCF.
The send packet quota and the receive packet quota are stored in
GETTAB Table 77
(.GTIPQ).
The send quota is stored in field IP.CQS
and the receive quota is stored in field IP.CQR.
The quotas are used when the job sends packets using the IPCFS. UUO.
Error code 10 (lPCFRS%) is returned in the AC when the sender queue is
full.
The program should attempt to discover why the packets have not
been sent, and, resolving that, try to send the current packet again.
Error code 11 (IPCFRR%) is returned in the AC when the IPCFS. UUO
fails because the receiver's queue is full.
The program should handle
this error by building a resend queue, so that it can keep trying to
send the packet.

7.5

SENDING AN IPCF PACKET USING IPCFS. UUO

Any process can send a packet to another process using the IPCFS. UUO.
The calling sequence for lPCFS.
is show below:
MOVE
ac, [XWD len,addr]
lPCFS.
ac,
error return
normal return

;Point to PHB
;Send the packet
;Something wrong
; Continue

addr:

flags
sender's PlD
receiver's PlD
XWD len2,addr2

;PHB

addr2:

message

;PMB
7-8

COMMUNICATING BETWEEN PROCESSES USING IPCF

In this calling sequence, len is the length of the PHB,
and addr is
the address of the PHB-.--The PHB includes your own PIO and the the
receiver's PIO. Also in the PHB, len2 and addr2 are the length and
address of the PMB, and message is the actual packet of data.
The PMB
is a short-form message.

7.6

RETRIEVING AN IPCF PACKET USING IPCFR. UUO

For a process to retrieve a packet from its input queue,
the process
must issue the IPCFR. UUO.
To retrieve a packet, the process does not
have to know who sent the packet. The IPCFR. UUO merely checks the
IPCF receive queue for any waiting packets and retrieves the packet
that has been in the queue the longest period of time.
The calling sequence for the IPCFR. UUO is shown below:

addr:

MOVE
ac, [XWO len,addr]
IPCFR.
ac,
error return
normal return

;Set up call
;Retrieve the packet
;Something wrong
; Continue

flags

;PHB

XWO len2,addr2
addr2:

;PMB

BLOCK 12

In this calling sequence, len is the length of the PHB and addr is the
address for storing the--PHB of the retrieved message.
In the PHB,
neither sender's nor receiver's PIO need to be specified. Also in the
PHB, len2 and addr2 point to where the actual message will be stored.
Although the sender's and receiver's PIO (.IPCFS and .IPCFR in the
PHB)
need not be specified for the IPCFR. UUO, there are cases in
which it is very useful to include these.
Using PIO-specific
receives,
it is possible to retrieve a message from a specific
process, rather than the packet that is next in the queue.
On a normal return from the IPCFR. UUO, the associated variable is
returned in the AC.
The associated variable describes the next packet
in the process's input queue, if there is one.
It contains the length
of the next packet in the queue in its left half, and the right half
of the flag word (descriptor flags) of the PHB of the next packet in
its right half.
The associated variable is also stored in the PSI
status word when a software interrupt is generated (refer to Chapter
6) .

The associated variable is used to check the receive queue
next message, and the type of message that is waiting.

7-9

for

the

COMMUNICATING BETWEEN PROCESSES USING IPCF

7.7

QUERYING THE NEXT IPCF PACKET USING IPCFQ. UUO

You can query the IPCF receive queue for your job using the
IPCFQ. UUO.
This call returns the PHB for the next packet in your
queue, but includes the number of packets in your queue instead of the
address of the next packet's message block.
The value of the IP.CFV bit in the returned PHB tells your job whether
to expect a long or short message block on the next IPCFR. call.
The
more efficient programming technique, however, is to do an IPCFR. with
the expectation of receiving either a long or short packet.
If the
IPCFR. call fails, your program can toggle the IP.CFV bit and repeat
the IPCFR. UUO.
This reduces the number of monitor calls that your
program makes, substantially improving performance.
Most programs
need never use the IPCFQ. UUO.
To query the next IPCF packet
IPCFQ. monitor call as shown:

,:':I.ci,jr:

your

input

queue,

use

MOVE
ac, [len,addr]
IPCFQ.
ac,
error return
normal return

;Set up call
;Query the next packet
;Something wrong
; Continue

flags

;PHB

the

XWO len2,n
In this calling sequence, len is the length of the argument list and
addr is the address for--storing the retrieved packet.
The PHB
contains zero for sender and receiver PIOs.
Word 3, . IPCFP,
contains
len2,
the length of the next packet, and~, the number of messages in
the -.raceive queue.
Note that IPCFQ.
does not return the next packet in the queue;
it
returns only information about it.
Your program can identify the
sending process on an IPCFQ. call as it would for IPCFR., by including
the sender's PIO in Word 1 (.IPCFS) and setting the flag IP.CRP in the
flag word.
If there is no packet in the queue, IPCFQ.
with error code 3 (IPCNP%) in the AC.

7.8

takes

the

error

return,

SYSTEM PROCESSES

There are two system processes of general interest:
[SYSTEM]INFO and
[SYSTEM] IPCC.
The [SYSTEM] INFO process is the information center for
the Inter-Process Communication Facility.
This process performs
system functions related to process identifiers, and any IPCF process
can req~est these functions by sending packets to
[SYSTEM] INFO.
[SYSTEM] INFO is described in Section 7.8.1.
[SYSTEM] IPCC is the IPCF controller,
and it performs many packet
controlling
functions.
Privileged
processes can request
IPCC
functions by sending packets to [SYSTEM] IPCC.
Unprivileged processes
are limited in the functions they can request from [SYSTEM] IPCC.
[SYSTEM] IPCC is described in Section 7.8.2.

7-10

COMMUNICATING BETWEEN PROCESSES USING IPCF
7.8.1

[SYSTEM] INFO

[SYSTEM]INFO is the information center
for
the
Inter-Process
Communication Facility. Any IPCF process can request [SYSTEM]INFO to
perform a function for it. A process requests a function by sending
[SYSTEM]INFO a packet,
and [SYSTEM]INFO responds to the request by
sending a packet back to the initiating process.
The initiating
process obtains the response to its requested function by issuing the
IPCFR. call to retrieve the packet sent to it by [SYSTEM] INFO.
If the
process plans to block for the [SYSTEM] INFO response, the IPCFM. UUO
may provide a more convenient interface.
(Refer to the IPCFM. monitor
call description in Volume 2.)
The calling sequence of sending a request
below:

[SYSTEM]INFO

shown

MOVE
ac, [XWO len,addr]
IPCFS.
~c,
error return
normal return
flags

addr:

o
o

XWO len2,addr2+.IPCIO
XWO ack-code,fcn-code
o or duplicate PIO
argument

addr2+.IPCIO:
addr2+.IPCI1:
addr2+.IPCI2:

In the calling sequence, the PHB is set up as described
7.2. Note that the PIO for [SYSTEM]INFO is always O.
The PMB specifies
follows:

the

information

that

[SYSTEM]INFO

Section

requires,

ack-code is a unique code you may supply.
This code is returned
unchanged in the response from [SYSTEM] INFO.
If a process has
sent more than one request to
[SYSTEM] INFO,
the user code
provides a method of determining which response is for which
request.
function-code is a [SYSTEM] INFO function code.
function codes are listed below.

The

[SYSTEM] INFO

duplicate PIO is the PIO of the process that you would like
receive a duplicate copy of the response from [SYSTEM] INFO.
no process is to receive a duplicate copy, this value should
zero.

to
If
be

argument is the argument to the function code.
The argument
depends on the function code, and these are listed below.

7-11

COMMUNICATING BETWEEN PROCESSES USING IPCF

The calling sequence to retrieve a
shown below:

packet

sent

[SYSTEM]INFO

MOVE
ac, [len"addr]
IPCFR.
ac,
error return
normal return
addr:

flags

o
o

XWD len2,addr2
addr2:

BLOCK 12

To receive a packet from [SYSTEM] INFO, set up the PHB in the same way
as you constructed it for the IPCFS. UUO.
Location addr specifies the
beginning of the packet header block,
and add~specifies the
beginning of the packet message block.
The response from [SYSTEM]INFO
depends on the function code you specified in the PHB.
In general,
the PMB returned by [SYSTEM] INFO takes the following form:
Word

Contents

addr2+.IPCIO/
addr2+.IPCI1/
addr2+.IPCI2/

ack-code"fcn-code
PID
symbolic name

Because this information depends on the function you specified,
the
PMB returned for each function is described with the function codes
listed below. Words not needed for
[SYSTEM] INFO's response will
remain unchanged.
The functions recognized by [SYSTEM] INFO are:
Fcn-code

Symbol

Meaning

. IPCIW

Requests
[SYSTEM]INFO to return the
PID
associated with the specified symbolic name.
The format of the request is:
addr2:

XWD user-code, .IPCIW
PID for copy or zero
symbolic name

The format of the response is:
addr2:

.IPCIG

XWD user-code, . IPCIW
PID for name
symbolic name

Requests [SYSTEM] INFO to return the symbolic
name associated with the specified PID.
The
format of the request is:
addr2:

XWD user-code, .IPCIG
PID for copy or zero
PID

The format of the response is:
addr2:

XWD user-code, .IPCIG
PID in request
name for PID

7-12

COMMUNICATING BETWEEN PROCESSES USING IPCF

.IPCII

Requests [SYSTEM] INFO to assign a PIO to the
calling process and to associate the symbolic
name with the newly assigned PIO.
The format
of the request is:
addr2:

XWO user-code, .IPCII
PIO for copy or zero
symbolic name

The format of the response is:
addr2:

XWO user-code, .IPCII
PIO
symbolic name

Any PIO obtained from
[SYSTEM]INFO as a
result of an .IPCII request is disassociated
from the calling job when the job performs a
RESET. PIOs obtained with this function code
have the format:
4nnnnn"nnnnnn.
To obtain a PIO without a symbolic
simply zero the word at addr2+2.
4

.IPCIJ

name,

Requests [SYSTEM] INFO to assign a
job-wide
PIO.
This differs from .IPCII in that the
PIO requested with .IPCIJ will not be cleared
on a RESET.
It is retained until you destroy
the context or log out. The format of the
request is:
addr2:

XWO user-code, .IPCIJ
PIO for copy or zero
symbolic name

The format of the response is:
addr2:

XWD user-code, .IPCIJ
PIO
symbolic name

Any PIO obtained from
[SYSTEM]INFO as a
result of an .IPCIJ request is disassociated
from the calling job only when the job logs
off the system.
PIOs obtained with this
function
code
have
the
format:
Onnnnn"nnnnnn.
A job can have more than one PIO and symbolic
name assigned to it.
However, there is a
maximum number of PIOs that can be assigned
to a job.
If a request is made for a PIO and
the PIO quota has been filled, the flag word
of the response from [SYSTEM] INFO contains
error code 73 in the error code field.
The
PIO quota is stored in GETTAB Table .GTIPC,
Item %IPCOQ.

7-13

COMMUNICATING BETWEEN PROCESSES USING IPCF
5

.lPClO

Requests
[SYSTEM]lNFO to disassociate the
specified PlO from its job number.
This
function can be requested only by the owner
of the specified PIO or by an lPCF privileged
process.
The format of the request is:
addr2:

XWO user-code, .lPCIO
PlO for copy or zero
PlO to be dropped

The format of the response is:
addr2:

XWO user-code, .lPClO

PlO that was dropped
6

.IPClR

Requests
[SYSTEM]INFO to disassociate all
PIOs that were created by
.lPClI and are
associated with the specified job number.
This function can be requested only by the
owner of the job or JCH,
or
an
IPCF
privileged
process.
The format of the
request is:
addr2:

XWD user-code, .lPCIR
PlO for copy or zero
job-number or JCH

The format of the response is:
addr2:

XWO user-code, .lPCIR

job-number or JCH
7

.lPClL

Requests
[SYSTEM]lNFO to disassociate all
PlDs that were created by
.lPClJ and are
associated with the specified job number.
This function can be requested only by the
owner of the job or JCH,
or
an
lPCF
privileged
process.
The format of the
request is:
addr2:

XWO user-code, .lPClL
PlO for copy or zero
job-number or JCH

The format of the response is:
addr2:

XWO user-code, .lPClL

job-number or JCH

7-14

COMMUNICATING BETWEEN PROCESSES USING IPCF

.IPCIN

Requests notification from [SYSTEM]INFO when
a specified PIO has been disassociated from a
job.
The format of the request is:
addr2:

XWO user-code, . IPCIN
PIO for copy or 0
PIO

The format of the response is:
addr2:

XWO user-code, .IPCIN

PIO
15

7.8.2

.IPCIS

Used only by [SYSTEM] IPCC on the execution of
the LOGOUT and RESET monitor calls.

[SYSTEM] IPCC

[SYSTEM]IPCC is the IPCF controller.
Only privileged processes can
request all
[SYSTEM] IPCC functions.
A privileged process requests a
function by sending [SYSTEM]IPCC a packet, and
[SYSTEM]IPCC responds
by sending a packet back to the initiating process.
The initiating
process obtains the response to\its requested function by issuing the
IPCFR. UUO to retrieve the packet sent to it by [SYSTEM] IPCC.
The
IPCFM. UUO provides a more convenient interface to
[SYSTEM] IPCC.
Since
[SYSTEM]IPCC functions always complete immediately,
using
IPCFM. saves one UUO execution per request to [SYSTEM] IPCC.
To perform IPCF privileged functions and to send
packets
to
[SYSTEM] IPCC,
a process must have the JACCT bit set, be running under
[1,2], or have the IPCF privilege bit set.
The IPCF privilege bit 1S
in GETTAB Table .GTPRV, Bit 0, JP.IPC.
IP.CFP must also be set in the
PHB.
The format of sending a request to [SYSTEM]IPCC is:
MOVE
ac, [XWO len,addr]
IPCFS.
ac,
error return
normal return
addr:

flags
sender's PIO
receiver's PIO
XWO len2,addr2+.IPCSO

addr2+.IPCSO:
addr2+.IPCS1:
addr2+.IPCS2:
addr2+.IPCS3:

XWO ack-code,function-code
argument 1
argument2
argument3

In an IPCC request, the PHB is set up as described in Section 7.2.
[SYSTEM] IPCC's PIO,
to be stored in Word 2 (.IPCFR), can be obtained
from GETTAB Table 126, Item 0, %SIIPC.
The PMB to [SYSTEM] IPCC depends on the function code being used.
In
general,
Word 0 contains the ack-code, a code you supply'to determine
which response is for which request, and the function-code, one of the
[SYSTEM] IPCC function codes, which are listed below.

7-15

COMMUNICATING BETWEEN PROCESSES USING IPCF
The type of argument and number of argument words is different
Therefore, they are described
depending on the function code used.
with the function codes, listed below.
The format for retrieving a packet sent by [SYSTEM]lPCC is:
MOVE
ac, [len"addr]
lPCFR.
ac,
error return
normal return
addr:

flags

o
o

len2"addr2
addr2:
Where:

BLOCK 12

PHB is similar to that described in Section 7.2.
When
retrieving a packet,
it is not necessary to specify the
receiver's and sender's PlD.

The response, starting at addr2, will
format:

Word

Contents

addr2+.IPCSO/
addr2+.IPCS1/
addr2+.IPCS2/
addr2+.lPCS3/

ack-code"fcn-code
[SYSTEM] lPCC response

the

following

general

In the response, the ack-code and fcn-code are those you specified in
your PMB, and are returned unchanged for your verification.
The rest
of [SYSTEM]lPCC's response depends on the function you specified.
Responses for each function code are listed below.
Words not needed
for [SYSTEM]lPCC's response will remain unchanged.
[SYSTEM] IPCC Function Codes
Fcn-code

Symbol

-n
1

Meaning
Negative function codes are reserved for
by customer programs.

.IPCSE

use

Requests [SYSTEM] lPCC to enable the specified
job number to receive lPCF packets.
This
function can be requested only by an IPCF
privileged
process.
The format of the
request is:
addr2:

XWD user-code, .lPCSE
job-number

The format of the response from
[SYSTEM] lPCC
is identical to the format of the request.

7-16

COMMUNICATING BETWEEN PROCESSES USING IPCF
2

. IPCSD

Requests
[SYSTEM] IPCC
to
disable
the
specified job from being able to receive IPCF
packets.
This function can be requested only
by an IPCF privileged process.
The format of
the request is:
addr2:

XWD user-code, .IPCSD
job-number

The format of the response from
[SYSTEM] IPCC
is identical to the format of the request.
3

.IPCSI

Requests
[SYSTEM]IPCC to return the
PID
associated with
[SYSTEM] INFO.
Unprivileged
processes may request this function.
The PID
returned is for the local [SYSTEM]INFO (if
there is one) or the global [SYSTEM] INFO,
if
there is no local [SYSTEM] INFO.
This PID may
also be obtained from GETTAB Table
.GTSID,
item %SIINF.
The format of the request is:
addr2:

XWD user-code, .IPCSI

The format of the response from
is:
addr2:
4

. IPCSF

[SYSTEM] IPCC

XWD user-code, .IPCSI
PIDfor [SYSTEM]INFO

Requests [SYSTEM] IPCC to create a PID for
[SYSTEM] INFO.
This function can be requested
only by an IPCF privileged process.
The
format of the request is:
addr2:

XWD user-code, . IPCSF
m
n

In the PMB, m is the PID of a process to make
[SYSTEM] INFO- and ~ is the
job number for
which to create a
local
(job-specific)
[SYSTEM] INFO.
To create a PID for a global [SYSTEM] INFO,
n
should be O.
If n is a job number, a PID for
a
local
[SYSTEM]INFO is created for the
sp~cified job.
Local [SYSTEM]INFOs are valid
only if another (local or global)
does not
exist.
If m is 0, the specified [SYSTEM]INFO
is deleted.
A local [SYSTEM]INFO can be created only by
another local
[SYSTEM]INFO or by a global
[SYSTEM] INFO.
If
there
is
no
local
[SYSTEM] INFO,
any privileged job can create
one.
The global [SYSTEM]INFO can be changed
or destroyed only if the calling process is
[SYSTEM] INFO.
The format of the response is
identical to the format of the request.

7-17

COMMUNICATING BETWEEN PROCESSES USING IPCF
5

.IPCSZ

Requests [SYSTEM] IPCC to clear a specified
PID.
This function may be requested by an
unprivileged process for your own PID.
The
format of the request is:
addr2:

XWD user-code, .IPCSZ
PID to be destroyed

The format of the response
the format of the request.
\)

.I:t;:'CSC

Requests [SYSTEM] IPCC to create
specified job number or JCH.
is unprivileged for your job
within your PID quota.
The
request is:
addr2:

identical

a PID for a
This function
or JCH,
and
format of the

XWD user-code, .IPCSC
type"job-number (or JCH)

The format of the response is:
addr2:

XWD user-code, .IPCSC
type"job-number (or JCH)
PID

In
the
PMB,
you
specify
~
by
setting/clearing Bit O.
When Bit 0 is set,
the PID created by this function is valid
until the job performs a RESET.
When Bit 0
is clear, the PID created by this function is
valid unt~l the job logs off the system.
In
the left half of addr2+1,
you specify the
job-number for which the PID is desired.
[SYSTEMJIPCC returns
the
PID
for
the
specified job in addr2+1 .
I

. IPCSQ

Requests [SYSTEM] IPCC to set a send and a
receive quota for the specified job.
This
function can be requested only by an IPCF
privileged
process.
The format of the
request is:
addr2:

XWD user-code, .IPCSQ
PID or job-number

On a response to this function,
[SYSTEM] IPCC
returns the send quota in Bits 18-26 of
addr2+.IPCS2 and the receive quota in Bits
27-35 of addr2+.IPCS2.
.IPCSO

Requests
[SYSTEM]IPCC to change the
job
number associated with the specified PID.
This function can be requested only by an
IPCF privileged process.
The format of the
request is:
addr2:

XWD user-code, .IPCSO
PID
new-job-number (or JCH)

The format of the response
the format of the request.

7-18

identical

COMMUNICATING BETWEEN PROCESSES USING IPCF
11

.IPCSJ

JCH
Requests
[SYSTEM]IPCC to return the
associated
with
the
specified
PID.
Unprivileged processes may
request
this
function.
The format of the request is:
addr2:

XWD user-code, .IPCSJ
PID

The format of the response is:
addr2:

. IPCSP

XWD user-code, .IPCSJ
PID
JCH

Requests
[SYSTEM]IPCC to return the PIDs
associated with the specified job number or
JCH.
Unprivileged processes may request this
function.
The
number of PIDs returned
depends on the length of
the
reserved
argument block.
The format of the request
is:
addr2:
addr2+1:
addr2+2:

XWD user-code" .IPCSP
job-number or JCH
starting PID or 0

The PIDs are returned starting
in the form:

.IPCSR

addr2:

user-code, . IPCSP
job number or JCH
PID

addr+n:

PID

with

addr2+2

Requests [SYSTEM] IPCC to return the send and
rece1ve quotas associated with the specified
job number or specified PID.
Unprivileged
processes may request this function.
The
format of the request is:
addr2:

XWD user-code, .IPCSR
job-number or PID

The send quota is returned in Bits 18-26 of
addr2+2 and the receive quota is returned in
Bits 27-35.
14

. IPCSW

Obsolete

.IPCSS

Reserved for DIGITAL.

7-19

COMMUNICATING BETWEEN PROCESSES USING IPCF
16

. IPCQS

Sets the PID quota of the target specified in
the request to the value given at addr2+2.
A
target can be a
job number,
a
job-context
handle (JCH) , or a PID.
This function can be
requested only by an IPCF privileged process.
The format of the request is:
addr2:

XWD user-code, . IPCQS
target to be set
PID quota

The response
request.
17

. IPCQR

takes

the

same

form

the

Requests [SYSTEM] IPCC to read the PID quota
of
the
specified
target.
Unprivileged
processes may request this function.
The
format of the request is:
addr2:

XWD user-code, . IPCQR
target

The response takes the form:
addr2:

20-22
23

XWD user-code, . IPCQR
target
PID quota

Reserved to DIGITAL.
. IPCLP

Requests [SYSTEM] IPCC to locate a given PID
in the special system PID table (listed below
in
. IPCRP) .
Unprivileged
processes
may
request this function.
The format of the
request is:
addr2:

XWD user-code, . IPCLP
PID to locate

The response takes the form:
addr2:

. IPCWP

XWD user-code, . IPCLP
PID
Index of the located PID

[SYSTEM] IPCC will write the table of special
system PIDs
(listed below).
This function
can be requested only by an IPCF privileged
process.
The request is in the form:
code, , . IPCWP
offset
PID

. IPCRP

[SYSTEM] IPCC will read the special system PID
table.
Unprivileged processes may request
this function.
The request is in the form:
code, , . IPCRP
offset

7-20

COMMUNICATING BETWEEN PROCESSES USING IPCF

The response takes the form:
code, , . IPCRP
offset
PID
Special system PIDs are:
Code

Symbol

-2
-1

o
1

3
4
5

. IPCPS
.IPCPI
. IPCPQ
. IPCPM
. IPCPT
. IPCPF
. IPCPC

· IPCPA
. IPCPO
. IPCPL
. IPCPD

13
14
15
16
17

. IPCPE
· IPCNM
· IPCPG
· IPCPV
· IPCPX

10 .
11

Meaning
Reserved for customer
definition
Reserved for customer
definition
[SYSTEM] IPCC
[SYSTEM] INFO
[SYSTEM] QUASAR
Mountable Device Allocator
Tape Label Process
File Daemon
Tape Automatic Volume
Recognition Process
[SYSTEM] Accounting
Operator Interface
System Error Logger
Disk Automatic Volume
Recognition Process
[SYSTEM]TGHA
Network Management (NCP)
[SYSTEM] GOPHER
[SYSTEM] CATALOG
[SYSTEM] MAILER
NOTE

The following message types are sent
by
[SYSTEM]GOPHER or [SYSTEM] IPCC to
and from GALAXY components.
26

. IPCSU

[SYSTEM] IPCC
will
send
a
message
to
[SYSTEM]QUASAR indicating that a spooled file
is closed.

. IPCSL

[SYSTEM] IPCC will send a logout message to
[SYSTEM] QUASAR.
The job-number is returned
in addr2+1.

. IPCTL

[SYSTEM] IPCC sends a tape labeling message.

. IPCUO

A mountable unit is on-line.

. IPCON

. IPCAC

Accounting messages.

. IPCDE

MDA-controlled device deassigned.

. IPCME

MDA memory error.

. IPCCS

Reserved.

. IPCRS

Reset with locked structure to MDA.

. IPCQU

QUEUE UUO to MDA.
7-21

( IPCC)
(IPCC)

(IPCC)
(IPCC)

(IPCC)

(GOPHER)

(IPCC)

COMMUNICATING BETWEEN PROCESSES USING IPCF
41

. IPCLC

Search list change to MDA.

. IPCAT

Primary disk port attach to MDA.

(IPCC)

. IPCDT

Primary disk port detach to MDA.

(IPCC)

. IPCXC

Disk unit exchange to MDA.

(IPCC)

. IPCRM

Structure removal to MDA.

(IPCC)

. IPCMT

Magtape unit accessible to MDA .

. IPCST

Structure mount to MDA .

. IPCIM

IPCFM . UUO request to [SYSTEM] INFO.

. IPCSM

Schedule bits change to [SYSTEM] QUASAR.

(IPCC)

( IPCC)

(IPCC)
(GOPHER)

The following is an example program using IPCF communication to obtain
information about the GALAXY input and output queues.
TITLE IPCF demonstration
;This program demonstrates how to acquire a named PID
from [SYSTEM] INFO, and, using that PID, request a queue
listing from QUASAR.
The QUASAR communications logic
is similar to, but much less complex than that used
in the QUEUE CUSP.
SEARCH
SEARCH

IPCF:

UUOSYM
GLXMAC,QSRMAC

;For TOPS-IO UUO symbols
;For GALAXY and QUASAR symbols

T4=1+<T3=1+<T2=1+<Tl=1»>
P=17

;Define some ACs to use
;PHL pointer

PDLSIZ==30
PHBLEN==6
PMBLEN==12
NAMLEN==<D29/5>+1
ACKCOD==171004
PAGSIZ==1000
PAG==400

;Push down list length
;Packet header block length
;Packet message block length
;Max length of a name in words
;Initial ack code
;Length of a page in words
;Page number for page receives

JFCL
RESET
MOVE
MOVE I
MOVEM
MOVE
GETTAB
SETZ
JUMPE
MOVEM
PUSHJ
PUSHJ
PUSHJ
PUSHJ
EXIT

;No CCL entry
;Stop the world
P, [IOWD PDLSIZ,PDL] ;Set up push down list pointer
Tl,ACKCOD
;Get initial ack code
Tl,ACK
;Save it for later use
TI, [%SIQSR]
;Argument to return a PID
Tl,
;Get QUASAR's PID
TI,
;Assume QUASAR isn't running
TI,NOQSR
;Is it?
Tl,QSR
;Save the PID
P,GENNAM
;Generate a name
P,GETPID
;Get a PID from [SYSTEM]INFO
P,SNDQSR
;Send queue list request to QUASAR
P,RCVQSR
;Receive and list the queues
;Return to monitor level

7-22

COMMUNICATING BETWEEN PROCESSES USING IPCF
iGenerate an ASCIZ name to associate with our PID.
i To insure the name is unique, our job number will
i be appended to the end of the name text.
GENNAM: SETZM
MOVE
BLT
MOVE
MOVE
GENNA1: ILDB
JUMPE
IDPB
JRST
GENNA2: PJOB
SETZ
GENNA3: IDIVI
PUSH
SKIPE
AOJA
GENNA4: POP
ADD I
IDPB
SOJGE
POPJ

NAM
T1, [NAM, , NAM+1]
T1,NAM+NAMLEN-1
T4, [POINT 7,NAM]
T2, [POINT 7,TXT]
T1,T2
T1,GENNA2
T1,T4
GENNA1
T1,
T3,
T1,12
P,T2
T1
T3,GENNA3
P,T1
T1,"0"
T1,T4
T3,GENNA4
P,

iClear out
iName text
iStorage
;Set up byte ptr to storage
iSet up byte ptr to initial text
iGet a character
iEnd of text?
iPut a character
iLooP through text string
iGet our job number
iClear a counter
iDivide by 10 (decimal)
iSave remainder
iDone?

iNo--recurse
iGet a digit
;Make it ASCII
;Append to name
iLooP for all digits
iAnd return

iGet a named PID from [SYSTEM] INFO.
This routine uses
i the name text generated by GENNAM.
GETPID: SETZM
SETZM
SETZM
MOVE
MOVEM
SETZM
SETZM
AOS
HRLZS
HRRI
MOVEM
SETZM
MOVE
BLT
PUSHJ
3ETPI1: PUSHJ
HLRZ
CAME
JRST
MOVE
MOVEM
POPJ

PHB+.IPCFL
iClear first word of PHB
PHB+.IPCFS
;Default our PID
PHB+.IPCFR
iO is [SYSTEM] INFO's PID
T1, [PMBLEN"PMB]
;Load length"addr of PMB
T1,PHB+.IPCFP
;Point to PMB
PHB+.IPCFU
iNo PPN
PHB+.IPCFC
iZero capability word
T1,ACK
;Add one to make unique ack-code
T1
;Set up ack-code
T1, .IPCII
iRequest PID with name
T1,PMB+.IPCIO
iLoad ack"fcn-code into PMB
PMB+.IPCI1
iZero second word of PMB
T1, [NAM"PMB+.IPCI2]
;Pointer to load name into PMB
T1,PMB+.IPCI2+NAMLEN-1 ;Load name into PMB
P,IPCSND
;Send packet
P, IPCRCV
; Retrieve packet
T1,PMB+.IPCSO
;Get ack-code of packet
T1,ACK
iCompare with ack of sent packet
GETPI1
iAcks not equivalent, try again
T1,PMB+.IPCS1
iGet our PID
T1,PID
;Store our PID
P,
iReturn

7-23

COMMUNICATING BETWEEN PROCESSES USING IPCF
iBuild and send a message to QUASAR. A "normal" queue
listing will be requested
(that is, the same listing obtained
by issuing the QUEUE monitor command) .

i
i

SNDQSR: SETZM
MOVE
MOVEM
MOVE
MOVEM
MOVE
MOVEM
MOVE
MOVEM
SETZM
AOS
MOVEM
MOVE I
MOVEM
SETZM
MOVE
MOVEM
SETOM
PUSHJ
POPJ

PHB+.IPCFL
iNo IPCF flags
Tl,PID
iGet our PID
Tl,PHB+.IPCFS
iMake it the sender's PID
Tl,QSR
iGet QUASAR's PID
Tl,PHB+.IPCFR
iMake it the receiver's PID
Tl, [PMBLEN"PMB]
iGet length and address of PMB
Tl,PHB+.IPCFP
iPoint the monitor at the PMB
Tl, [PMBLEN" .QOLIS] ;Length"msg type (queue listing)
Tl,PMB+.MSTYP
iSave it
PMB+.MSFLG
iSend no flags to QUASAR
Tl,ACK
iGet a new ack code
Tl,PMB+.MSCOD
iSave for comparison later
Tl,l
iOne data block in the message
Tl,PMB+.OARGC
iSave count in message
PMB+.OFLAG
iRequest a normal queue listing
Tl, [2" .LSQUE]
iQueue block
Tl,PMB+.OHDRS+ARG.HD iSave queue block header
PMB+.OHDRS+ARG.DA
iSave queue block data
P,IPCSND
iSend queue listing request
P,
iReturn

; RecE~ive a queue listing from QUASAR.
This routine contains
; no provisions for handling multiple queue listing messages
; which can occur when there are many jobs in the queues.
RCVQSR: MOVE I
Tl, IP. CFV
iReturned message is a page
MOVEM
Tl,PHB+.IPCFL
iSave flag
MOVE
T 1, [P AG S I Z, , PAG ]
;Length and page where to put msg
MOVEM
TI,PHB+.IPCFP
iPoint monitor at it
P,IPCRCV
RCVQSl: PUSHJ
;Try to receive a msg
Tl,<PAG AD9>+.MSCOD ;Get ack code
MOVE
TI,ACK CAME
;Make the one we sent out?
JRST
RCVQSI
;No--try again
MOVE I
Tl,<PAG AD9>+.OHDRS ;Point to start of data in msg
T2 , ARG . HD (T I )
RCVQS2: HRRZ
iGet a block type
CAIN
T2, .CMTXT
iIs this the queue listing text?
RCVQS3
JRST
iYes--go output it
HLRZ
T2, (TI)
iNo--get this block length
ADDI
TI, (T2)
iOffset to the next block
JRST
RCVQS2
iKeep searching
RCVQS3: OUTSTR ARG. DA (Tl)
;Output listing text
POPJ
P,
; Return
IPCSND: MOVE
TI, [PHBLEN, , PHB]
iLoad length"addr of PHB
IPCFS.
Tl,
;Send packet
SKIPA
iAlways skip on failure
POPJ
P,
iReturn
OUTSTR [ASCIZ I? Error sending packetl]
iPrint error
EXIT
;Bomb out

7-24

COMMUNICATING BETWEEN PROCESSES USING IPCF

Tl, [PHBLEN,PHB]
IPCRCV: MOVE
;Load length"addr of PHB
Tl,
IPCFR.
;Get packet
;Always skip on failure
SKIPA
P,
; Return
POPJ
OUTSTR [ASCIZ I? Error receiving packetl]
;Print error
;Bomb out
EXIT
NOQSR:

OUTSTR
EXIT

[ASCIZ

TXT:

ASCIZ

IIPCF demo Job

; Symbolic name

POL:
PHB:
PMB:
NAM:
ACK:
PIO:
QSR:

BLOCK
BLOCK
BLOCK
BLOCK
BLOCK
BLOCK
BLOCK

POLSIZ
PHBLEN
PMBLEN
NAMLEN

;Push down list
;Packet header block
;Packet message block
;Name to assign to PIO
;Ack code
;Our pro
;QUASAR's PID

END

IPCF

1
1
1

I? Cannot get QUASAR's PID I]
;Bomb out

7-25

;Print error

CHAPTER 8
RESOURCE CONTROLS: -THE ENQ/DEQ FACILITY

When several users access the same file, problems of interference and
inconsistency can arise.
While one user is reading the file, other
users can also read that file; but no other user should be writing the
same portion of the file.
And while a user is writing the file, no
other user should be reading or writing the same portion of the file.
For example, suppose a group of users have
string of the form:

agreed

that

character

CUSTMR.DATnnnn
represents a block in the file CUSTMR.DAT, where nnnn is the block
number.
Then if one user has obtained exclusive use of block 14 in
that file, perhaps so that he can write the block,
the monitor will
not grant other requests for use of the same block until the user
releases it.
The ENQ/DEQ facility can be used for dynamic resource allocation,
computer networks,
and internal monitor queueing.
Simultaneous file
access, however, is its most common application.
The ENQ/DEQ facility
ensures data integrity among jobs, allowing multiple users to share
resources, and it ensures synchronism among cooperating jobs.
ENQ/DEQ ensures data integrity among jobs only when the participating
jobs cooperate when using both the facility and the resource.
The
facility does not prevent non-cooperating jobs from accessing a
resource without first enqueueing it. However, to enqueue a resource,
the requesting user must have access to
the
resource.
The
accessibility of the resource depends on the type of resource.
If,
for example, the resource is a file, access to the file is permitted
or denied depending on the access protection code of the file (see
Section 12.3).
A resource is an entity within the system.
Jobs compete with one
another to use the resource.
The physical resource itself has no
relationship with the resource definition supplied to the ENQ/DEQ
facility by the requesting programs.
Competing jobs, however, are
synchronized to allow controlled access to resources by the ENQ/DEQ
facility.
The ENQ/DEQ facility uses the resource definitions supplied
by cooperating programs to arbitrate use of a resource.
Some examples
of resources are files,
operations on files (such as reading and
writing), records, devices, and memory pages.

8-1

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY

The ENQ/DEQ facility maintains a queue of requesting jobs for each
resource that has been enqueued (requested) by any job.
You request
resource ownership by placing a request in the queue associated with
that resource.
You make this request for a resource using the
ENQ. monitor call. An ownership request indicates that you want the
ENQ/DEQ facility to create a lock between your job and the resource
you have defined.
Each request in the queue must be satisfied before
following requests can be considered. When you obtain a lock with a
resource, your are the "owner" of the resource until you dissolve the
lock using the DEQ. monitor call to dequeue the resource.
In the ENQ. call to request a resource, you specify information about
the
resource
itself, the type of ownership 'you require,
and
information about the way the request is to be handled.
Each
ENQ. request enters the queue associated with the resource.
The queue
is an ordered list of all requests for that resource.
When the monitor grants a lock to a requesting job, it establishes the
type of lock that the job specified. For each resource, the first
owner of the resource determines the characteristics of the lock and
the resource. While the lock is in effect, the requesting job is the
owner of the resource and can use the resource.
All other jobs
requesting access to the resource must specify the same resource
identifier.
The resource identifier is an ASCIZ string or numeric
value that is included in the ENQ. call.
If the owner of the resource has defined the lock to be sharable,
other jobs can be granted a sharable lock on the resource without
waiting for the first owner to relinquish the resource.
Without an
explicit
definition,
the first owner's lock is assumed to be
exclusive, and other jobs must wait in the queue for the previous
owner to relinquish the resource.
When the first owner relinquishes
the resource, the next requesting job is granted a lock.
If the
ENQ. call by the requesting job specifies a sharable lock, the lock
will be granted to subsequent jobs that also request shared ownership.
Therefore,
to share the ownership of a resource, all sharing owners
must cooperate in the shared ownership agreement.
Section 8.1.1
discusses sharable resources.
You relinquish ownership of the resource by using the DEQ. call.
This
call can also be used to remove a waiting request from the resource
queue.
This cycle of enqueueing and dequeueing requests for
resource
ownership continues until all requests have been granted for that
resource. After the last job relinquishes the resource,
the monitor
deletes the resource queue and all data associated with the resource.
When a new job makes a request for the resource,
a new queue is
created for the resource.

8.1

REQUESTING A RESOURCE

The ENQ. call places a request in the resource queue for th~ resource
that your program defines in the ENQ. argument list.
This definition
is an arbitrary ASCIZ text string pointed to by a. word in the
ENQ. argument list,
or a numeric value included in the ENQ. argument
list.
This resource definition governs the queue into which the
request is placed.
Therefore, cooperating programs must use the same
resource definition when competing for the same resource.
This
resource definition is an arbitrary value to the monitor, and is not
used to actually prevent or allow access to any physical resource.

8-2 .

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
As each request for the resource is made, the request is placed at the
end of an ordered list of requests for the resource. Depending on the
types of requests in the queue, a lock mayor may not be granted to
the requesting job immediately.
The first owner of the resource can
specify sharable access to the resource.
This allows subsequent
requests for sharable access to the same resource to be granted
immediately.
If the first owner does not specify sharable access, the
lock is assumed to be exclusive, and no further lock on the resource
can be granted until the owner relinquishes the resource.

8.1.1

Sharable Resources

Sharable access is useful when multiple jobs must access a resource
(such as a file) in a non-modifying mode (such as reading the file) .
When reading files, multiple jobs can share ownership of the resource
without interfering with one another's data. As long as the sharing
programs cooperate in ensuring data integrity,
they can
share
ownership without endangering one another.
If a request is made for
exclusive ownership, that request and all subsequent requests must
wait until all the sharing jobs have relinquished the resource.
When
the last sharing owner of the resource has dequeued the resource,
the
owner requesting exclusive ownership (who may intend to write to the
file) is granted a lock on the resource.
Any jobs making requests
after the exclusive request must wait until the exclusive lock is
dissolved by the owner.
Therefore, your ENQ. requests should specify
sharable access unless you must modify the resource.
The ENQ/DEQ facility allows you to limit the set of users that can
share a resource at the same time.
You provide a sharer group number
in your ENQ. argument list.
When your job 1S the owner of the
resource,
only other jobs specifying the same sharer group number can
access the resource. Again, note that jobs in the resource queue are
satisfied in order.
Thus, a request for sharable access with the same
sharer number must follow the first owner's request without any
intervening requests of another type.
Sharer group 0 is the default sharer group.
Thus, every request that
specifies sharable access,
without specifying a group number, is a
member of sharer group O.
To restrict access to a sharable resource,
a sharer group number other than 0 must be specified.

8.1.1.1 Resource Pools - A resource pool is a group of identical
resources
(such as magtape drives) or copies of the resource (such as
memory pages).
You specify the resource pool in the argument list to
the ENQ. call by specifying the number of units or copies of the
resource that are in the pool.
You also specify the number of units
or copies of the resource to which your job requires exclusive access.
A pooled resource cannot be requested for sharable access.
That is, a
resource may be either sharable or pooled, but never both. When the
owner has exclusively locked a certain number of units from the
resource pool,
subsequent jobs can gain exclusive access to the rest
of the units or copies in the pool. Each subsequent job must specify
the total number of units in the pool and the number of units to which
it requires access. As long as each request specifies the same pool
size,
the resource is pooled, and units are subtracted from the pool
according to the number of units requested by each job in the queue.
The ENQ/DEQ facility ensures that requests for pooled resources
specify the same pool size (that is,
the same number of units or
copies in the pool) and that requests are granted for the number of
units or copies available (unowned) in the pool.
8-3

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
Pooled resources can be actual physical units, such as magnetic tape
drives.
A certain number of these might be available on the system;
this number is the pool size. Each job requesting access to tape
drives must request a number of drives equal to or less than the total
pool size. A pooled resource might be only one actual unit (such as a
disk file) to which a limited number of users can be allowed access at
one time.
The disk file can be specified as a pool by a requestor of
the resource,
and subsequent access to the file is limited to the
number of copies of the file specified as the pool size, minus the
number of copies requested for ownership from the pool.
When the number of resources in the pool has been determined,
the
ENQ/DEQ facility allocates the resources until the pool is depleted,
or until a request is made for more units in the pool than are
available.
In the latter case,
the job making the request is not
granted ownership of any resources until enough resources have been
dequeued by other jobs to satisfy the request.
Because requests are
satisfied in the order they are queued, all subsequent requests must
wait for the previous request to be satisfied. As jobs relinquish
resources, the resources are returned to the pool of available
resources. When all resources have been returned, the monitor deletes
the resource pool.
The next request for a pooled resource redefines
the pool size and available number of units or copies in the pool.
A pooled resource is useful when a limited number of jobs wish to
modify the same resource at the same time.
If the resource were a
file, the jobs would be simultaneously updating the file.
Of course,
if there is no limit to the number of jobs modifying the resource,
there is no need to use the ENQ/DEQ facility.

8.1.1.2 Partitioned Resources - A resource
can
be
exclusively
accessed by more than one job if those jobs require a portion of the
resource.
The resource is requested in partitions,
thus allowing
several users access to the resource,
but with the intention of
modifying restricted and exclusive sections of the resource.
This is
specified using a bit mask that defines the partition.
For example, a user might require access to block 14 of a file
CUSTMR.DAT,
but only for certain records in that block. Another user
might require access to a different record in the same block of the
same file.
Each request can specify a bit pattern, where bits that
are set correspond to parts of the resource to be locked and bits that
are off denote portions that will be available to other jobs at the
same time.
If a job requests parts of a resource that are independent of parts of
the resource already owned by another job, a request for exclusive
access to the resource can be granted.
Therefore,
the bit mask
specified in the ENQ. request should specify unique bit masks for each
portion of the resource.
In the case of a disk file, each bit in the
bit mask might correspond to a record.
Thus, if a request is made for
exclusive access to a portion of a resource already owned by another
job,
the bit masks would overlap.
The requests would be conflicting,
and the second request would wait until the owner had relinquished the
resource.
If the bit masks did not overlap, the records would be
mutually exclusive, and the second request could be granted at the
same time that the resource is owned by the first job.
Since the monitor transfers one block at a time for I/O,
simultaneous
attempts to write to the same physical block of a file may cause data
corruption. Refer to Section 8.3 for information on passing data to
other jobs.
8-4

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.1.2

Multiple-Lock Requests

If your job requires access to several resources at one time, you may
place several lock requests in a single ENQ. call.
All of the
requests must be granted to your job before the ENQ. call is
successfully returned.
The lock requests in the ENQ. call must be
granted in the order that you specify the resources in the call.
When your job issues a multiple-lock request,
the first request is
considered before the subsequent requests.
Your job is placed in the
queue for the first resource until the first lock is granted.
Then
your job is placed in the queue for the second resource, and so forth.
The requests that have not yet been considered are "invisible" to the
monitor.
Other jobs requesting the same resource as the invisible
requests in your call can be granted access ahead of your job,
until
the request for that resource becomes visible (that is, until all
previous requests made by your ENQ. call are granted) .

8.1.2.1 ENQ. Quotas - A multiple-lock request must not request more
resources than your job's ENQ. quota allows.
The ENQ. quota is the
total number of requests that your job can have at one time.
Your job
cannot use the ENQ. facility if its ENQ. quota is O.
Your system administrator sets ENQ. quotas.
If you need a larger
quota,
see your system administrator.
You can check the quota for
your job by using the .ENQCG function of the ENQC. monitor call.
You can obtain the default ENQ. quota from item %EQDEQ in GETTAB Table
.GTENQ.

8.1.2.2 Request Levels - Each request in a multiple lock request is
granted in the order that it is presented in the ENQ. call. Each
request in the call must be assigned a level number, unless you bypass
level checking,
by setting the flag EQ.FBL.
In this case, it is
recommended that you use deadlock detection.
The level number for the
first request in the call must be equal to or greater than the level
number of any previous request for the same resource.
Sub~equent
requests in the call must have ascending level numbers.
The level numbers you include in each request for a resource in the
same ENQ. call help the ENQ/DEQ facility to avoid deadlocks between'
jobs. A deadlock occurs when two or more jobs are each waiting for
resources held by other jobs,
and no job can relinquish its own
resources until it is granted access to those resources owned by the
other jobs.
You can avoid deadlocks if you always request the same
resources in the same order.
This is accomplished using level
numbers.
Your job must use a level number for each resource it is
requesting, and all jobs must use the same level numbers for the same
resources.
The jobs must request the resources in ascending order,
and relinquish the resources in descending order.
This ensures that
your job will not be granted a lock for a resource until all
lower-level requests have been granted first.
Resources are best
utilized if the scarcest or most-requested resources are requested
with higher level numbers.

8-5

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.1.3

Granting Locks

Requests for resources are granted on a first-come first-served basis.
Multiple-request calls must be granted in the order that the resources
are requested, and the call is returned only when all the resources
have been locked for the job. By default, jobs must wait for the
requests to be granted.
However, there are methods for avoiding the wait.
The ENQ/DEQ
facility allows you to use the PSI system, a time limit, or a deadlock
detection flag to prevent undue interruption of processing.

8.1.3.1 ENQ. Software Interruption - You can enable the PSI system to
interrupt your program when a request is granted for your job.
To use
the PSI system, you should first consult Chapter 6.

Non-blocking jobs should use the ENQ. function
.ENQSI to enqueue a
request and to continue execution.
If all the requests in the call
can be granted at once, the call is returned successfully.
If any or
all requests cannot be granted, the ENQ. call takes the error return,
returning the error code ENQRU% in the accumulator.
The instruction
in your program at the non-skip return from the ENQ. call should
branch to a routine that can be processed while your program waits for
the request(s) to be granted.
When the monitor interrupts your job, your program should check the
status word of the PSI interrupt control block.
The interrupt reason
for ENQ. requests granted is .PCQUE.
To use the PSI system for ENQ. requests, your program should include a
request identifier for each request in the ENQ. argument block.
This
request-id is associated with the resource being requested,
and is
returned when that resource is granted, in the status word of the
interrupt control block.
When you make a multiple-request ENQ. call,
using the PSI system to interrupt your program when the requests are
granted, the request-ids of the granted requests are inclusively ORed
into the status word.
Therefore, for such a request, it is advisable
to use bit masks for the request-ids, specifying a single bit for each
request in the call.
This allows you to check which requests have
been granted.

8.1.3.2 Time Limits - Your program can avoid waiting an undue length
of time without enabling the PSI system.
If you have a specific time
limit within which the request must be granted, you can include this
time limit
(specified in seconds)
in the header block of the
ENQ. argument list.
If the requests in your call can be granted
immediately, the call returns successfully.
If not, the job waits the
specified number of seconds for each request that
cannot
be
immediately granted.
When that time is over, and all the requests in
the call have not been granted,
the call takes the error return,
returning error code ENQTL% in the accumulator.

8-6

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.1.3.3 Dead10ck Detection - If your program makes multiple requests
with multiple calls,
you can avoid creating a deadlock situation by
including the deadlock detection flag in your ENQ. call.
If you set
this flag,
your requests are compared against other requests for the
same resource, and the possibility of a deadlock is determined.
In
the case that the requests can be granted without causing a deadlock,
the call returns successfully.
However,
if granting your requests
would cause a deadlock, the call takes the error return, and the code
ENQDD% is returned in the accumulator.

If you specify both a time limit and deadlock detection,
the monitor
first waits until the request times out before checking for deadlocks.
This avoids the overhead of deadlock detection for the majority of
cases where the job is being blocked, but the resource will be freed
before the time limit is up.
You can use this feature to implement a form of deadlock priority.
For example,
a batch job could specify a long wait time, and an
interactive job could specify a short wait time.
The interactive job,
which wants quick response,
will time out first in the case of a
deadlock, and will back out of its transaction.
The batch job,
which
probably has more time invested in its transaction, can afford to wait
longer.
It continues processing when the interactive job releases its
resources.

8.2

RELEASING RESOURCES

Resources are released when you relinquish them using the DEQ. monitor
call.
The resources are also released if your program issues a RESET,
EXIT, or LOGOUT call.
If your job issues a CLOSE on the channel for
which ENQ. locks are in effect, the call fails, setting the I/O status
bit IO.IMP.
When resources are relinquished, they are freed according to level
number,
in descending order.
That is, resources locked first are
released last.
If your job is the only owner of any resource,
the
queue and data for the resource are eliminated when you relinquish the
resource, to be reset by any new request for the resource.
However,
your program can ensure that resource queues and data are preserved by
using a long-term lock or an eternal lock.
Normally the ENQ/DEQ facility retains its data for defined resources
only while one or more
jobs have locks or requests for those
resources; when the last request is dequeued, the monitor deletes the
data.
However, the overhead for deleting and redefining resource data can be
eliminated by using a long-term lock. A lock is "long-term" if the
EQ.FLT flag is set in the ENQ. call argument list for the resource.
When the last locking job releases the resource, the monitor retains
the resource data for approximately five minutes, instead of deleting
the data immediately.
Thus, when another job requests the resource,
the resource data is still in the ENQ. data base.
You can also define the lock as an "eternal lock." An eternal lock
prevents the resource from being automatically dequeued when your
program issues a RESET call.
The resource will only be relinquished
when you explicitly relinquish it with DEQ.

8-7

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.3

PASSING DATA TO OTHER JOBS

You can pass data to other jobs sharing ownership of the same resource
owned by your job.
The data is in the form of a lock-associated
block; its content is arbitrary to the monitor, and is meaningful only
to the participating programs.
A lock-associated block is defined in
block definition and data persist
occurs:

the ENQ. argument list.
The
until either of the following

Another job redefines it.

The monitor deletes its data for the resource.
This occurs
immediately when there are no further requests for the
resource (or five minutes later, for a long-term lock) .

A lock-associated block may be lost too soon if its queue does not
have a long-term lock.
Therefore, it is good programming practice to
use long-term locks when using lock-associated blocks.
The lock-associated block can also be used for local buffer caching
(also called distributed buffer management)
Local buffer caching
allows a number of jobs to maintain copies of data (for example,
disk
blocks),
in buffers local to each job. The job can be notified when
the buffers contain invalid data due to modifications by another job.
In applications where modification is infrequent, substantial I/O may
be saved by maintaining local copies of buffers
(hence the names
"local buffer caching" or "distributed buffer management") .
each
To support local buffer caching using the lock-associated block,
job maintains a cache of buffers with no locks on resources that
represent the current contents of each buffer.
If the buffer contains
diskblocks,
the lock-associated block associated with each resource
are used to contain a disk block version number.
The first time a
lock is obtained on a particular disk block, the current version
number of that disk block is returned in the job's lock-associated
block.
If the contents of the buffer are cached, this version number
is saved along with the buffer.
To re-use the contents of the buffer,
the resource associated with the buffer must have a long-term lock put
on it, in either shared or exclusive mode, depending on whether the
buffer will be read or written.
The lock-associated block returned
with the lock contains the latest version number of the disk block.
The version number of the disk block is compared with the saved
version number.
If they are equal, the cached copy is valid.
If they
are not equal, a fresh copy of the disk block must be read from disk.
Whenever a procedure modifies a buffer, it writes the modified buffer
to disk and then increments the version number in the lock-associated
block prior to dequeueing the lock on the resource associated with the
buffer.
This way, the next job that attempts to use its local copy of
the same buffer will find a version number mismatch and must read the
latest copy from disk,
rather than use its cached and now invalid
buffer.
If more than five minutes have passed since the last user of the
resource dequeued the lock, then no lock-associated block data will be
returned, and the program should invalidate its buffer anyway.

8-8

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.4

ENQ/DEQ MONITOR CALLS

The ENQ. facility offers three monitor calls:

8.S

The ENQ. call requests access to a resource.
When the
requested resource is not immediately available, the request
is queued until the resource is released. When the resource
is available, the request is granted, and a lock is placed on
the resource.
The request defines the characteristics of the
lock (for example, whether the resource is sharable; that is,
may be accessed simultaneously by another process) .

The DEQ. call releases a resource, cancelling the lock on the
resource, or cancels requests for a resource.

The ENQC. call allows you to obtain the request quota for a
job, change the request quota, and dump information about the
monitor's data base of ENQ/DEQ resources.
Note that some of
these operations require privileges.

BUILDING REQUESTS

When your program uses an ENQ., DEQ.,
or ENQC. call,
it must have
already constructed the argument block for the call, which defines the
resources.
This consists of a header block for the entire list of
requests and one lock block for each resource.
Together, the header
and all associated lock blocks are known as the request block.
The format of the header block is:
Word

Symbol

Contents

.ENQLL

Number of bloc1':s and length:
Bits

Symbol

Meaning:

0-5
6-17
18-35

EQ.BHS
EQ.LNL
EQ.LLB

Header block size
Number of lock blocks.
Total length of the
block.

. ENQRI

Request identifier .

.ENQTL

Time limit (number of seconds) .

request

The header block size (EQ.BHS) gives the length of the header block (1
to 3 words).
The default size (if you give the size as 0) is 2.
The number of lock blocks
list that follows.

(EQ.LNL) is the number of lock blocks in the

length of the argument list (EQ.LLB) gives the total length of the
request block. Note that all the lock blocks in a single ENQ. request
must be the same length.
Thus, the value of EQ.LLB must be the header
block size plus the length of each lock block times the number of lock
blocks.
ThE~

8-9

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY

The request identifier (.ENQRI) is an optional identifier for the
request.
The left half of .ENQRI must be O.
The request-id is stored
in the right half of this word.
If you use the ENQ/DEQ facility with
programmed interrupts,
an interrupt caused by the availability of a
resource returns the inclusive OR of the request-ids of resources that
have become available, in the status word for the PSI system.
(Refer
to Section 8.6.3.)
The time limit (.ENQTL) is an optional word in the header block that
you can use to specify a maximum amount of time for the job to block
while waiting for a .ENQBL function to be granted.
You specify the
number of seconds for your job to wait for requests to be granted
before returning from the ENQ. call.
(This word is used only by the
ENQ. UUO.)
When the time limit is exceeded, the monitor returns the
error code ENQTL%.
One or more lock blocks follow the header block.
Each lock block
requests a
lock for one resource.
All the lock blocks in a single
request block must be the same length.
The format for each lock block is:
Word

Symbol

Contents

.ENQFL

Flags, level, and channel:
Bits

Symbol

Meaning

EQ.FSR
EQ.FBL
EQ.FLT
EQ.FEL

EQ.FAB

5
6

EQ.FDD
EQ.FCW

7-8
9-17
18-35

EQ.FLV
EQ.FCC

Sharable lock.
Don't do level checking.
Long-term lock.
Eternal lock,
released
only
on
request.
Aborted lock.
This flag is useful
on a modification function (.ENQMA)
to prevent the resource from being
locked by any other jobs.
Enable deadlock detection.
Specifies that
.ENQBP contains a
36-bit user code.
Reserved.
Level number.
Channel number (if positive integer)
or code (if negative integer)
The
codes are:

1
2

Code

Symbol

Meaning

-3

.EQFPL

Privileged
global
(system-wide) lock.
This lock code can
be
used only by
jobs
logged
~n
under [1,2] or jobs
with
the
JACCT
privilege.
Thus,
only
other
jobs
with the
[1,2] or
JACCT
privileges
can share the lock.

8-10

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY

~ENQBP

-2

.EQFGL

-1

.EQFJB

Global lock.
This
flag prevents any
sharers, regardless
of privileges, and
requires that you
have
JP.ENQ
privileges set in
your
job's
privilege
word
(GETTAB
Table
.GTPRV) .
Job-wide
lock.
This flag prevents
other requests by
your job (including
other contexts) for
this resource from
being granted.

Resource identifier in the form of a numeric value or
a pointer to an ASCIZ string.
Bits 0 to 2 (EQ.BUC) have the value 5 if a 33-bit
numeric value is used.
The word contains a 36-bit
numeric value if EQ.FCW is set in the flag word
(.ENQFL).
The number is any arbitrary string that is
specified by all cooperating processes.
Otherwise, .ENQBP contains a pointer to an ASCIZ
string of up to 30 words (150 characters) that is the
name of the resource.
.ENQBP cannot use indirection
or indexing to address the name string.
This pointer
is either a byte pointer of the form:
POINT
Where:

7,address,bitplace

bitplace is the location of the rightmost bit
in the first byte in the first word.
address is the address of the first word,
a pointer of the form:
XWD
Where:

-l,address
address is the address of the first
word of the string. For the second
form, the string must be 7-bit bytes
and begin in the first byte of the
first word.

.ENQPS

Pool size or sharer group.
If a resource pool is
being specified, the left half of this word (EQ.PPS)
contains the total pool size,
and the right half
(EQ.PPR)
contains the number of units or copies
desired from the pool.
If a sharer group
is
specified,
the left half (EQ.PPS) contains 0 and the
right half (EQ.PPR) contains the sharer group number.
This optional word defaults to zero.

.ENQMS

Mask for partitioned lock,
where the left half
(EQ.MBL)
is the mask length, in words, and the right
half (EQ.MSK) is the address of the mask.
This
optional word defaults to zero.

8-11

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
Lock-associated block, where the left half
(EQ.TLN)
contains the length of the block, in words.
The
right half
(EQ.TBL)
contains the address of the
block.
This optional word defaults to ~ero.

.ENQTB

The ENQ. header/lock block structure looks as follows:

a
Header
Block

.ENQLL

EQ.LNL

EQ.LLB

.ENQRI
.ENQTL

Time Limit

EQ.FLV

Flags

EQ.FCC

.ENQBP

Byte Pointer or User Code

.ENQPS

Pool Size or Sharer Group

.ENQMS
.ENQTB

Figure 8-1:

EQ.BHS

--------------------1------------------a
Request-id

.ENQFL

Lock
Block

Partition Mask Pointer

----------------------------------------1
EQ.TLN
EQ.TBL
1

ENQ/DEQ Request Block

Note that the lock block is relative to the end of the header block,
which may vary in size, because the request-id (.ENQRI) and the time
limit (.ENQTL) are optional.
The lock block is repeated for each
resource in the request.

8.6

QUEUEING REQUESTS: ENQ. UUO

To request a lock on an ENQ. resource, use the
follows:
MOVE
ac, [XWD fcncode,addr]
ENQ.
ac,
error return
normal return
Where:

ENQ. monitor

call

;Set up call
;Enqueue the request
;Didn't get resource
;Got it

fcncode is one of the four ENQ. functions described below.
addr is the address of the argument list.
is described in Section 8.5.

The

argument

The monitor attempts to lock each resource described by a
in the argument list.

8-12

lock

list
block

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
The ENQ. function codes are:
Fen-code

Symbol

Meaning

.ENQBL

Enqueue the request and wait until
requested resources are available.

.ENQAA

Dequeue the request immediately if any of the
requested resources is unavailable.

.ENQSI

Enqueue the request and interrupt the program
when the requested resources are available.

.ENQMA

Modify a previous request.

the

Each of these function codes and procedures are discussed below.

8.6.1

Requesting and Waiting for Locks

Your job can request locks on one or more resources and wait until the
monitor
grants
the
request.
This type of request uses the
ENQ. function code .ENQBL.
When the request is enqueued,
your job
waits until the monitor can grant all the locks in the request.

8.6.2

Requesting Locks On1y if Avai1ab1e

Your job can request locks on one or more resources, and prevent the
moni.tor from queueing the request.
That is, the monitor grants the
request only if all the requested locks can be granted immediately;
othE~rwise,
the request is dequeued immediately.
This procedure uses
the ENQ. function code .ENQAA.
.
The monitor takes the error return, giving the ENQRU% error code,
if
any of the requested resources is unavailable.
Otherwise, the monitor
takE~s the normal return, having locked the requested resources.

8.6 .. 3

Requesting and Interrupting when Locked

Your job can request locks on one or more resources,
and have the
monitor execute a software interrupt for the job when the requested
resources are granted.
This procedure uses the ENQ. function code
.ENQSI.
If all the requested locks can be granted immediately,
the monitor
takes the normal return.
If not, it takes the error return, giving
the error code ENQRU%.
The instruction at the error return should
branch to some program task that can be performed while the job waits
for the requested locks.
This "task" could put the job to sleep.
When the monitor interrupts the job, your program should check the
status word of the interrupt block.
If the interrupt was caused by
the granting of the requested resources, the request identifiers of
the granted requests are inclusively ORed into the status word.
If
the interrupt was caused because the resource has been aborted,
the
sign bit of the status word will be on.
Your job must set up the PSI system for ENQ. interrupts before using
the
.ENQSI function of ENQ.
Refer to Chapter 6 for information on
setting up the PSI system.
8-13

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.6.4

Modifying a Previous Request

Your job can modify a previously queued request by using the
ENQ. function
.ENQMA.
The function fails if you attempt to change a
request from sharable to exclusive access when the resource already
belongs to a sharer group.
If the requested modification is already in effect, the monitor makes
no change and takes the normal return.
If your job tries to modify a
request that is not in the resource queue, the monitor takes the error
return, giving the ENQNE% error code.
If your call to the
.ENQMA function specifies more than
one
modification,
and the monitor takes the error return, your job must
use the ENQC. function .ENQCS to check the status of each request.
The error code returned is only for the first error that occurred in
the call.

8. 7

DEQUEUEING REQUESTS: DEQ. UUO

To release a lock on an ENQ. resource (or cancel
lock), use the DEQ. monitor call as follows:
MOVE
ac, [XWD fcncode,addr]
DEQ.
ac,
error return
normal return
Where:

request

for

the

;Set up call
;Dequeue the request
;Failed
; Dequeued

fcncode is one of the function codes discussed below.
addr is the address of the argument list for function codes
and 1, and contains the request-id for function 2.

The monitor releases each resource described by a lock
argument list.

block

the

locks

for

The DEQ. function codes are:
Fcn-code

Symbol

Meaning

. DEQDR

Dequeue or release a specified lock .

.DEQDA

DEQ. all requests and release all
the job.

.DEQID

DEQ. all requests and release all locks for a
given request identifier.

Each of these DEQ. functions is discussed below.

8.7.1

Cancelling a Specific Request

Your job can cancel a specific request by using the DEQ. function
.DEQDR.
This function deletes the request from the queue or releases
the lock on the requested resource.
If you use the .DEQDR function for a lock that is not in the queue and
is not in force, the monitor takes the error return, giving the ENQNO%
error code.

8-14

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.7.2

Cance11ing A11 Requests for a Job

Your job can cancel all its ENQ. requests by using the DEQ. function
.DEQDA.
This function cancels all of your requests from the queue and
releases all the locks you have placed on resources.
The monitor takes the error return, giving the ENQNO% error
you have no requests or locks.

8.7.3

code,

Cance11ing Requests Based on Request-id

Your job can cancel all its ENQ. requests that have the same request
identifier by using the DEQ. function .DEQID.
This function dequeues
all requests that have the specified identifier,
and releases all
locks that were requested using the specified identifier.
The .DEQID function does not use an argument list; instead,
it reads
the request identifier from the field that would otherwise point to
the address of the argument list.
Thus, the calling sequence for the
.DEQID function is:
MOVE
ac, [XWD .DEQID,request-id]
DEQ.
ac,
error return
normal return
Where:

request-id is the request identifier of the requests and locks
that are to be cancelled.

If your job has no requests or locks for the given request-id,
monitor takes the error return, giving the ENQNO% error code.

8.8

the

CONTROLLING ENQ/DEQ: ENQC. 000

The ENQ. facility offers the ENQC. monitor call for control of the
facility itself.
The calling sequence for the ENQC. UUO differs for
each function code.
The function codes for this monitor call are:
Fcn-code

Symbol

Meaning

.ENQCS

Obtain the status of a request.

.ENQCG

Obtain the ENQ. quota of a specified job.

. ENQCC

Set the ENQ . quota for a specified job.

. ENQCD

Examine the monitor's ENQ/DEQ database .

Note that some of these functions require privileges.
are described in the following sections.

8-15

The

functions

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.8.1

Obtaining the Status of a Request

Your program can use an ENQC. function .ENQCS to check on the status
of an ENQ. request, which is specified by the request identifier given
with the request.
The calling sequence for the .ENQCS function is:
MOVE
ac, [XWD .ENQCS,addr]
MOVE I ac+1,buffer
ENQC.
ac,
error return
normal return

buffer:
Where:

BLOCK <lock blocks>*3

addr is the address of the
Section 8.8

request

block,

described

On a normal return, the monitor returns a three-word status block for
each request at buffer.
Specify the amount of buffer space to reserve
as number of lock blocks times 3.
The format of the block returned at
buffer is:
Word

Symbol

Contents

.ENQCF

Flags:
Bits

Symbol

Meaning

EQ.CFI

Invalid lock.
The monitor sets this
bit if it found an error in the
corresponding
lock
request
specification.
When this bit is
set, bits 18-35 contain an error
code.

EQ.CFO

This user is owner.

EQ.CFQ

This user is in queue.

EQ.CFX

Owner's access is exclusive.

4-8

Reserved.

9-17

EQ.CFL

Level.

18-35

EQ.CFJ

Job context handle or error code.
(This
is
the
same error code
returned in the AC on an error
return from ENQC.) If several jobs
share the lock,
this job context
handle indicates only one of those
sharers. However, if you are one of
those sharers,
this value will be
your job context handle.
It is possible that there may be no
lock owner even though several jobs
may have requested ownership.
In
this case, the monitor returns a -1
in bits 18-36.
8-16

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY

.ENQCT

Time (in universal date-time format)
that the lock
was
granted
to its owner.
This 36-bit value
represents the last time someone was granted a
request for the specified resource.
This value is
written in UDT format.
If there is no owner of the
resource, this word will be zero.
This time stamp is useful if you want some type of
watch dog timer.
Such a timer could periodically
query the status of any queue in which throughput was
of maximum importance.
If it became obvious that the
time stamp of the queue had not changed for a long
time, the time process could signal the operator that
someone had held the resource for longer than the
allowable time interval.
The operator could then
take whatever action was deemed appropriate.

.ENQCI

The left half (EQ.CIQ) contains the number of owners
sharing
the resource.
The right half
(EQ.CID)
contains the request-id of the request.
If you are currently in the queue for a specified
resource,
this value will be the request-id for your
request in the queue (even if a lock has not yet been
granted) .
However,
if you are not the owner of the
resource and not in the queue for the resource,
the
request-id will be that used by the owner of the
resource.
The request-id field allows the use of
ENQ/DEQ with the PSI system.

8.8.2

Obtaining the Quota for a Job

You can use an ENQC. function (.ENQCG) to obtain the ENQ. quota for
user.
The calling sequence for this function is:

MOVE
ac, [XWD .ENQCG,addr]
ENQC.
ac,
error return
normal return

addr:
Where:

XWD O,jobno

addr is the address of the argument list.
jobno is the number of the job whose quota is required (-1 for
your own job) .

The monitor returns the quota for the specified job in ac.

8-17

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.8.3

Setting the Quota for a Job

If you have the required privileges (JP.POK, JACCT, or the [1,2] PPN) ,
you can use an ENQC.
function (.ENQCC) to set the ENQ. quota for a
user.
The calling sequence for this function is:
MOVE
ac, [XWD .ENQCC,addr]
ENQC.
ac,
error return
normal return

addr:
Where:

XWD quota,jobno

addr is the address of the argument list
quota is the new quota to be set for the job.
jobno is the number of the job whose quota is to
for your own job) .

set

(-1

The monitor sets the quota for the specified job.

8.8.4

Dumping the ENQ. Database

If you have the required privileges (JP.SPM, JP.SPA, JACCT, or [1,2]),
you
can use an ENQC. function
(.ENQCD)
to dump the monitor's
ENQ. database.
The calling sequence for this function is:
MOVE
ac, [XWD .ENQCD,buffer]
ENQC.
ac,
error return
normal return

buffer:
Where:

XWD O,buflength
BLOCK buflength

buffer is the address of a buffer for returned data.
buflength is the length of the buffer.

The monitor returns a dump of the ENQ. database beginning at buffer.
If the database does not fill the entire buffer, the balance is filled
with zeros; if the database will not fit
into the buffer,
it is
truncated.

8-18

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY

The following diagram shows the general format of the ENQC. dump:

1=======================================================1
1
Number of words in block
1
1=======================================================1
1
1

Dump block for first lock

1
1

1=======================================================1
I===================r===================================1

1
1

Dump block for last lock

1=======================================================1
The format for each dump block is:

1=======================================================1
1
1

Lock block for this lock

1
1

I==================~====================================1

1
1

Two-word queue block for first owner of this lock

1-------------------------------------------------------I
1-------------------------------------------------------I
1
1

Two-word queue block for

l~st

owner of this lock

1=======================================================1
1
1

Two-word queue block for first waiter for this lock

1-------------------------------------------------------I
1-------------------------------------------------------I
1
1

Two-word queue block for last waiter for this lock

1
1

1=======================================================1

8-19

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY

Where each lock block is in the format:
Word

Symbol

Contents

.EQDFL

Flags, level, and lock identifier:
Bits

Symbol

Meaning:

0
2
5

EQ.DLB
EQ.DLT
EQ.DLN

EQ.DLA

9-17
18-35

EQ.DFL
EQ.DFI

This is a lock block.
This lock has text.
This lock block will not be dequeued
on a reset.
This lock is
aborted;
no
new
requests will be granted.
Level number.
Lock identifier.
(That is,
the
access table address or code of -1,
-2, or -3. )

The flag word (.EQDFL) is returned as -1 at
of the list of queue blocks.
1

.EQDPR

the

end

Pooled request counts:
Bits

Symbol

Meaning:

0-17
18-35

EQ.DPS
EQ.DPL

Size of pool.
Number of resources available in the
pool.

.EQDTS

Time stamp.

.EQDSU

Resource identification string or numeric code.

The format of each 2-word queue block is:
Word

Symbol

Contents

.EQDFL

Flags in the left half, and associated job number
the right half.

.EQDGI

Bits

Symbol

Meaning:

1
3
4

EQ.DLO
EQ.DXA
EQ.DJW

7
8

EQ.DQI
EQ.DQD

This is the lock owner.
Exclusive access.
This
job is blocked waiting for
lock.
This queue block is invisible.
This queue block will be checked for
deadlocks.

Group number and request identifier:
Bits

Symbol

Meaning:

0-17
18-35

EQ.DGR
EQ.DRI

Group or number requested.
Request identifier.

8-20

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY

8. 9

ENQ. ERRORS

For errors from ENQ. monitor calls
(ENQ., DEQ.,
and ENQC.),
monitor returns one of the following error codes in the AC:

the

Code

Symbol

Error

ENQRU%

ENQBP%

3
4

ENQBJ%
ENQBB%

ENQST%

6
7

ENQBF%
ENQBL%

10
11
12

ENQIC%
ENQBC%
ENQPI%

ENQNC%

14
15

ENQFN%
ENQIN%

ENQNO%

17
20

ENQLS%
ENQCC%

ENQQE%

ENQPD%

ENQDR%

ENQNE%

25
26

ENQLD%
ENQED%

27
30
31

ENQME%
ENQTE%
ENQAB%

ENQGF%

33
34

ENQDD%
ENQTL%

At least one of the requested resources is not
available.
You requested an illegal number
of
pooled
resources.
You specified an illegal job number.
You specified an illegal byte size for the byte
pointer.
The byte pointer must be 1 to 36
(decimal) .
ASCIZ string is too long.
It must be less than
150 (decimal) characters.
You specified an illegal function code.
You specified an illegal argument list length.
The total length must be the header-block-size
plus
(request-block-size
times
number-of-requests) .
You specified an illegal number of requests.
You specified an illegal channel number.
Your program does not have enough privileges for
specified function.
Not enough core available, or the maximum number
of active locks
(item %EQMAQ in GETTAB Table
.GTENQ) has been exceeded.
File is not open or device is not a disk.
Address for byte pointer cannot be indirect or
indexed.
Your program cannot dequeue resources not owned
by your job.
Levels not specified in ascending order.
Illegal modification of ownership; you cannot
change
a
request from shared to exclusive
ownership. DEQ. first, then re-ENQ.
Enqueue quota exceeded; your quota is set by the
system administrator.
Number of resources in pool disagrees with number
in your request.
Duplicate request; the request is identical to ~
request already queued by your job.
The resource cannot be dequeued because it is not
enqueued for your job.
Level in request does not match lock.
Not enough privileges for ENQ/DEQ; you must have
JP.ENQ set.
Mask too long or lengths do not match.
Lock-associated block is too long.
A resource that was requested has been marked as
aborted.
An eternal lock cannot be placed on a
"ghost
file"
(that is, a file that is in the process of
being created or superseded on disk) .
A deadlock was detected.
The specified time limit was exceeded.

8-21

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.10
An

EXAMPLE USING THE ENQ. FACILITY

example of the ENQ. monitor call is shown below.

TITLE
SUBTTL

ENQEXA - A simple ENQ application
PETER VATNE 6-JUN-83
SEARCH JOBDAT,MACTEN,UUOSYM ;Get standard symbol definitions
SALL
;Make listing pretty

DEFINE

Tl=1
T2=2
T3=3
T4=4
P=17

;Temporary ACs

IO==1

;Input-output disk channel

LN$PDL==40
LN$DAT==200

;Stack size
;Data block size

ERROR
JRST

;Push down pointer

(COD,TXT),<
;;Standard error macro
[OUTSTR [ASCIZ/?ENQ'COD 'TXT/]
RESET
;;Clear all locks, etc.
MONRT.
;;Return to monitor fast
JRST START]
;;Start allover again>
;Make program sharable

TWOSEG 400000
START:

JFCL
RESET
MOVE
MOVE
MOVEM
MOVSI
MOVEM
MOVE

;In case of CCL entry
;Reset the world
P, [IOWD LN$PDL,PDLST] ;Initialize push down list
Tl, [SIXBIT /DATA/]
Tl,LKPBLK
;File name is DATA
Tl,'DAT'
Tl,LKPBLK+l
;File extension is .DAT
Tl, [6, , [IO, , . FOMAU
;Channel=IO,mode=MULTI-USER
. IODMP
; Mode=DUMP
SIXBIT /DSK/
; Device=DSK
0, , 0
;No buffer headers
0, , 0
;No buffers
ENTBLK, , LKPBLK] ]
;File name blocks
FILOP. Tl,
;Open a file in simul update mode
ERROR (COF,Can't open file DATA.DAT for simultaneous update)

RECORD:

MOVE
T2, [POINT 7,MSGBLK]
;Point to start of message
MOVE I
T3,LN$DAT*5
;Count of character
SETZM MSGBLK
;Zero out message block
MOVE
Tl, [MSGBLK"MSGBLK+l] ; ..
BLT
Tl,MSGBLK+LN$DAT-l
, ..
OUTSTR [ASCIZ /INPUT>/];PROMPT

8-22

RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
TTYINP:

INCHWL Tl
Tl, .CHCNZ
CAIN
EXIT
T3
SOSL
IDPB Tl,T2
CAIE
Tl, .CHLFD
JRST TTYINP

;Read a character (line mode)
; . . . Z?
;Yes, done with program
;Room left in message block
;Yes, append to message
;End of line?
;No, loop for more

MOVE

Tl, [.ENQBL" [lB5+lBl7+3 ;Header=l,locks=1,length=3
EQ.FCW+IO
;Code word,level=O,channel=l
-1]]
;Arbitrary code
ENQ.
Tl,
;Lock the resource
ERROR (CEB,Can't ENQ. a block for DATA.DAT)
USETI T1,1
;Set to block 1
INPUT Tl, [IOWD LN$DAT,DATBLK
;Read the block
Z]
;Set to block 1
USETO Tl,l
OUTPUT Tl, [IOWD LN$DAT,MSGBLK
Z]
;Write new message
MOVE
Tl, [.DEQDA"O]
;DEQ all locks
DEQ.
Tl,
;Unlock the resource
ERROR (CDB,Can't DEQ. a block for DATA.DAT)
OUTSTR [ASCIZ /
=> /]
OUTSTR DATBLK
;Type the contents of the block
JRST
RECORD
;Do it again

LKPBLK:
ENTBLK:
DATBLK:
MSGBLK:
PDLST:

LIT

; Store the literals in the high seg

RELOC

;Switch to low segment storage

BLOCK
BLOCK
BLOCK
BLOCK
BLOCK

LN$DAT
LN$DAT
LN$PDL

END

START

; Storage
; Storage
; Storage
; Storage
; Storage

4
4

8-23

for LOOKUP block
for ENTER block
for data block
for message input
for push-down list

CHAPTER 9
PROGRAMMING FOR REALTIME EXECUTION

Most jobs run under the TOPS-10 monitor as timesharing jobs.
The
system
scheduler schedules them for CPU time.
(Refer to the
SCHED. monitor call in Volume 2.) But realtime jobs are assigned
higher priorities than timesharing jobs and the CPU serves them on an
event-driven basis. Timesharing jobs use the CPU time left after
realtime jobs have been served.
NOTE
Realtime execution is not available
systems.

processor

Realtime programs connect devices to the CPU priority interrupt
(PI)
system.
The device is then under exclusive control of the realtime
program,
and is called
a
realtime
device.
Refer"
to
the
DECsystem-10/DECSYSTEM-20 Processor Reference Manual for a discussion
of the hardware Priority Interrupt system.
A realtime program must be locked in core so that the program can
service the device at interrupt level.
(The system cannot do
paging/swapping at interrupt level.) A realtime program
cannot
connect to a device unless the program is locked in core.
The monitor calls that are most important for realtime programs are:

9.1

RTTRP

Connects and releases realtime devices.

UJEN

Dismisses a realtime interrupt.

HPQ

Places a job in a high-priority run queue.
You should
not place a job in a high-priority run queue if the job
will run for a long time. Doing so can cause other jobs
to lose data.

TRPSET

Temporarily suspends execution of
facilitate realtime processing.

LOCK

Locks a job in core.

all

other

jobs

CONNECTING REALTIME DEVICES

To connect a realtime device, use the RTTRP monitor call. A realtime
device is controlled in one of four ways; this control is specified in
the RTTRP call that connects the device. The four control modes are:
o

Block mode in which the monitor reads an entire block of data
before--rt interrupts your program. To accomplish this, the
monitor places BLKI/BLKO in the skip chain.
9-1

PROGRAMMING FOR REALTIME EXECUTION
o

Fast block mode, in which the monitor also reads an entire
block of data before it runs the interrupt program, but
responds faster than normal block mode.
To accomplish this,
the monitor places BLKI/BLKO at the interrupt location.

Single mode, in which the monitor runs your interrupt routine
each time the device interrupts.
To accomplish this, the
monitor places an XPCW instruction at the interrupt location.

in which the
Executive Process Table (EPT) relative mode,
monitor responds to a vectored interrupt.
To accomplish
this, the monitor places the XPCW instruction into the EPT
vector.

Note that EPT mode responds to vectored interrupts.
The first three
modes are for non-vectored interrupts.
Your choice of the first three
modes should depend on the speed of response required by your program.
Interrupts are distinguished as standard or vectored, depending on how
they get a new pc.
with standard interrupts, two memory locations are
assigned to each channel starting at locations 40 + 2n and 41 + 2n in
the EPT.
The processor starts an interrupt on channel n by executing
the instruction in location 40 + 2n in the EPT.
The standard
interrupt follows the CaNSO skip chain testing all the devices in the
following way:
40+2n:

XPCW CH'N

CH'N:

Old flags
Old PC
New flags
New PC (always .+1)
JRST to CaNSO skip chain

DEV'INT:

CaNSO DEVl,bits
JRST DEV2'INT

DISMISS
DEV2'INT: CaNSO DEV2,bits
JRST DEV3'INT

DISMISS
The last entry on the chain contains an XJEN CH'N
With vectored interrupts, the device gives the new PC to the hardware
by using an offset into the Executive Process Table.
This location
contains the instruction which the hardware executes on an interrupt.
In the following example, the interval time uses location 514.
EPT+514/

XPCW TMOINT

The interval timer is a vectored interrupt device, as are the RH20's.
Normally, the interrupt service routine is run in user mode with user
I/O privileges.
However, your program can also use executive mode for
its realtime interrupts if it requires extremely fast response.
(See
Section 9. 1 .4. )

9-2

PROGRAMMING FOR REALTIME EXECUTION

Using normal or fast block mode places a
directly on a PI level.
Since -this
executive mode, you must first lock your
memory.

BLKI or BLKO instruction
instruction is executed in
job in executive virtual

In normal block mode, the monitor places the BLKI or BLKO instruction
directly after the entry for the device in the monitor's CaNSO skip
chain. Any number of realtime devices using either single mode or
normal block mode can be placed on any available PI level.
The level
is considered available if it is not used for a BLKI or BLKO
instruction by the system or by other realtime users, including the
APR channel.
(The average overhead per device on the same PI level is
5.5 microseconds per interrupt.)
In fast block mode, the monitor places the BLKI or BLKO instruction
directly in the PI location.
This requires that the interrupt level
be dedicated to the realtime job during data transfers.
In single mode, the monitor places an XPCW instruction into the
interrupt location to pass control to your program on every interrupt.
In EPT-relative mode, the monitor places the XPCW into the EPT vector
to pass the control to your program on an interrupt at that vector.
On a normal return from a RTTRP monitor call, the job is granted lOT
privileges,
allowing the job to execute restricted I/O instructions
from user mode.
These instructions could halt the system if used
improperly.
The restricted instructions are:
CONO
CONI
CaNSO
CONSZ

DATAl
DATAl
BLKI
BLKO

JEN
XSFM
XJEN

A RTTRP monitor call with the PI level
(see below)
given
produces,the lOT privilege without setting up a device.

zero

A realtime device must be placed on the same interrupt level in its
RTTRP monitor call, and in the CONO instruction which establishes the
interrupt level for the device.
If a CaNSO bit mask is set up for a device, but the device has not
been placed on its proper interrupt level, and if a flag for the
device is on, an interrupt to your program can occur~.
This is because
there is a CaNSO skip chain for each interrupt level; if a device
interrupts whose CaNSO instruction is further down the chain than the
device itself,
the CaNSO is executed.
If a hardware device flag is
set (and the corresponding bit is set in the CaNSO bit mask),
the
CaNSO skips and an interrupt to your interrupt service routine occurs
even though the device did not interrupt.
To avoid this, your program can store the CaNSO bit mask in the your
area (for example, at MSKADD) and use an indirect address in the CaNSO
instruction (for example, CaNSO device, @MSKADD).
This allows your
program to chain the device to its interrupt level, but keep a zero
bit mask until the device is placed on its interrupt level by a CONO
instruction.
When your program removes a device from the interrupt chain,
also remove it from the interrupt level with a CONO
instruction.

9-3

it must
device, 0

PROGRAMMING FOR REALTIME EXECUTION
The calling sequence for the RTTRP monitor call is:

MOVE I ac,addr
RTTRP ac,
error return
normal return
Where:

addr is the address of the argument list.
The contents of the
argument list depend on which mode is being set up by the
call.
The argument list for each mode is discussed in
Sections 9.1.1 through 9.1.5.

The RTTRP functions require the following types of information:
o

Realtime interrupt levels
The realtime interrupt level (given as level in the argument
lists in this chapter)
is the PI level for the realtime
device.
You may specify any of the !ollowing in the PI level
field:
1.

Specifying level 0 with the RTTRP
A positive PI channel.
Levels 1 and 2 are
monitor call releases the device.
often reserved for tape devices such as TD10 or TM10.
Level 7 is always
Levels 3 through 6 are legal levels.
reserved for the system.
If you lock your job on a CPU,
and then specify a
positive PI channel,
the system assumes the realtime
device is on that CPU.
If your job is not locked on a
CPU, the system locks it on CPUO, and attaches the device
to the channel you indicated.
The system then removes
all occurrences of the device on any PI channel on the
same CPU in the system.
This is useful when a device
uses
multiple PI levels for flags and data or a
software-generated interrupt is used for lower-level
processing.

A negative PI channel.
When your job is locked on a CPU,
the system assigns the PI channel in the same manner as
for a positive PI channel specification,
but does not
remove occurrences of the device from other PI channels.
When your job is not locked on a CPU, and you assign a
negative PI channel,
the system attaches the device to
the channel the same way as for a positive specification,
but does not remove other occurrences of the device.

A bit mask in the form:
1BO + <CPU no.>B8 + <PI chan.>B17.
The system assigns the
the CPU you indicate
If you do not specify
device to the channel
PI channel.

device on the specified channel on
in the CPU number (CPU no.) field.
a CPU,
the system assigns the
as though you specified a positive

A bit mask in the form:
1BO + 1B1 + <CPU no.>B8 + <PI chan.>B17.
The system assigns the device on the specified channel on
the CPU you indicate in the CPU number (CPU no.) field.
If you do not specify a CPU,
the system assigns the
device to the channel as though you specified a negative
PI channel.
9-4

PROGRAMMING FOR REALTIME EXECUTION

Trap location
The location to which a realtime interrupt traps is given as
realtrap in the argument lists in this chapter. Realtrap is
the start of the interrupt service routine. When a user mode
realtime
interrupt
occurs,
the
monitor
saves
all
accumulators; therefore a realtime interrupt service routine
can overwrite them without loss.

APR trap location
The location to which APR conditions trap is given as aprtrap
in the argument lists in this chapter.
On an APR trap such
as NXM or PDL overflow;
the monitor executes
a
JSR
instruction to the trap address.
(If a realtime device is on
a higher interrupt level than the APR level,
no
APR
conditions on the device are detected.)

Device name
A realtime device is defined by a symbol for the device code.
See the MACRO Reference Manual for a list of I/O device
symbols.

Bit mask
A mask is defined in each CaNSO instruction in a
tr~
The mask bits differ for each device.
Hardware Reference Manual for a list of the bits
mask.
The CaNSO instruction can be written as:
CaNSO
Where:

device, mask

mask is in the address field of the instruction;
the CaNSO instruction can be written as:

mskadd:
Where:

realtime
See the
in each

CaNSO

device,@mskadd

XWD

O,mask

mskadd is the address of
which
is
locked
in
containing the mask.

the word
executive

(in your area,
virtual memory)

mask is the 18-bit mask value.
The indirect addressing of this mask allows your program to
store the mask in your memory area.
However, the word
containing the mask must not have the indirect or index
fields set (that is, Bits 13 through 17 must be 0).
o

BLKI/BLKO pointer word
The address (in your memory area) of the BLKI/BLKO pointer
word is given in the argument lists in this chapter as
blockaddr.
On a realtime interrupt,
the monitor adds a
relocation constant to this pointer; therefore your program
must restore the pointer to its original value after each
interrupt.

9-5

PROGRAMMING FOR REALTIME EXECUTION
o

Interrupt flags
Realtime interrupt flags (given as flags
lists in this chapter) are as follows:

the

argument

Flag

Meaning

If set, Bits 6-8 contain the CPU number of the CPU
to which the device is connected.
If this flag is
not set, the device is on the same CPU that the
program is locked on.
If the program is not
locked on this CPU, RTTRP locks it on CPUO:.

There are multiple device references in
the
interrupt chain.
Thus,
the device can generate
interrupts on more than one PI channel.

This is an EPT-mode interrupt; the address given
in addr+2 is an offset into the executive page
table.

The device indicated in the argument list supports
and produces vectored interrupts.

The monitor patches the trap to a JSR to a trap
address.
If this bit is not set, the monitor
patches the trap to a JSR to the context switcher.
If this bit is set, your interrupt service routine
is entered in executive mode with no accumulators
saved.
(Refer to Section 9.1.4.)

Should the job running realtime abort the program using CTRL/C,
the
monitor uses the device field to execute a CONO instruction to reset
the device and remove it from realtime processing.

9.1.1

Normal Block Mode

The RTTRP argument list for normal block mode is:
addr:

Where:

XWD
XWD
CONSO
BLKx

level,realtrap
flags,aprtrap
device,mask
device,blockaddr

level is the interrupt level for the device.
realtrap is the address of the interrupt service
the given device.

routine

for

flags are realtime interrupt flags.
aprtrap is the trap location for all APR traps.
BLKx is your choice of BLKI or BLKO.

device is the device code for the realtime device.
mask is the bit mask.
blockaddr is the address in your area of the BLKI/BLKO pointer
word.

9-6

PROGRAMMING FOR REALTIME EXECUTION

Example
TITLE

RTNBLK - Papertape read test in BLKI mode

UUOSYM

;Standard symbols

;Some values
TAPE=400
BUSY=20
DONE=lO
AC1=1
AC2=2
TABLEN=200
PICHAN=6

;No more tape in reader if TAPE=O
;Device is busy reading
;A character has been read
;Work register
;Work register
;Table length
;PI channel

; Storage
;Realtime data block
RTBLK:

XWD
XWD
CONSO
BLKI

PICHAN,TRPADR
O,APRTRP
PTR,DONE
PTR,POINTR

;PI channel and trap address
;Flags and APR trap
;Wait only for done flag
;Read a block at a time

POINTR:
OPOINT:
TABLE:
DONFLG:

IOWD
BLOCK
BLOCK
BLOCK

TABLEN,TABLE

;Pointer for BLKI instruction
;Original pointer
;Table area for data being read
;PI level to user level command

RTBLK1: EXP 0
EXP 0
CONSO
EXP

TABLEN
1

;Data block to remove PTR
; from PI channel
PTR,O

;Here we begin
BLKTST: RESET
MOVE
LOCK
JRST
MOVE I
RTTRP
JRST
CONO
SETZM
MOVE I
RTTRP
JRST
MOVE
MOVEM
HLRZ
TRO
CONO
MOVE I
SLEEP
SKIPN
JRST
EXIT

;Reset the program
AC1, [LK.HLS+LK.LLS] ;Lock both segments
AC1,
;Lock the program in core
FAILED
;LOCK call failed
AC1,RTBLKl
;Get address of realtime block
AC1,
;Get user lOT privilege
FAILED
PTR,O
DONFLG
AC1,RTBLK
AC1,
FAILED
AC1,POINTR
AC1,OPOINT
AC2,RTBLK
AC2,BUSY
PTR, (AC2)
AC1,5
AC1,
DONFLG
.-3

;RTTRP call failed
;Clear all PTR bits
;Initialize the done flag
;Get address of realtime data block
;Put realtime device on PI level
;RTTRP call failed
;Get relocated pointer for later
;Store for interrupt level use
;Get PI number from RTBLK
;Set up CONO bits to start tape
;Turn on PTR
;For five seconds .
; Sleep
;Finished reading the tape?
;No, back to sleep
;Yes, stop the job
;Here's the trap

9-7

PROGRAMMING FOR REALTIME EXECUTION

TRPADR: CONSO
JRST
MOVE
MOVEM
UJEN

PTR,TAPE
TOONE
AC1,OPOINT
AC1,POINTR

iEnd-of-tape?
iYes, stop the job
iNO, get original pointer
iStore in pointer location
iDismiss the interrupt
iHere on end-of-tape

APRTRP : BLOCK

iAPR error trap address

TOONE:

AC1,RTBLKl
PTR,O
AC1,

iSet up to remove PTR
iTake device off hardware PI level
iTake device off software PI level
iIgnore errors
iIndicate that reading is over
iDismiss the interrupt

MOVE I
CONO
RTTRP
JFCL
SETOM
UJEN

DONFLG

iHere if LOCK or RTTRP call failed
FAILED: OUTSTR
/]
EXIT
END

9.1.2

[ASCIZ /RTTRP or LOCK call failed.
;Stop the job
BLKTST

Fast Block Mode

The RTTRP argument list for fast block mode is as follows:
addr:

Where:

XWD
XWD
BLKx

level,realtrap
flags,aprtrap
device,blockaddr

level is the interrupt level for the device.
realtrap is the address of the interrupt service
the given device.

routine

for

flags are realtime interrupt flags.
aprtrap is the trap location for all APR traps.
BLKx is your choice of BLKI or BLKO.
device is the device code for the realtime device.
blockaddr is the address in your area of the BLKI/BLKO pointer
word.

9-8

PROGRAMMING FOR REALTIME EXECUTION
Example
TITLE

RTFBLK - Papertape read test in BLKI mode

UUOSYM

;Standard symbols

;Some values
TAPE=400
BUSY=20
DONE=lO
TABLEN=5
AC1=1
AC2=2
PICHAN=6

;No more tape in reader
;Device is busy reading
;A character has been read
;Length of table
;Work register
;Work register
;PI channel

; Storage
POINTR:
OPOINT:
TABLE:
DONFLG:

IOWD
BLOCK
BLOCK
BLOCK

RTBLK1: BLOCK
BLOCK
CONSO
BLOCK

TABLEN,TABLE
1

;Po~nter for BLKI instruction
;Original pointer word for BLKI
;Table area for data being read
;PI level to user level command

1
1

;Data block to remove PTR
; from PI channel

TABLEN

PTR,O
1

;Realtime data block
RTBLK:

XWD
XWD
BLKI
BLOCK

PICHAN, TRPADR
O,APRTRP
PTR,POINTR

;PI channel and trap address
;APR error trap address
;Read a block at a time

;Here we begin
BLKTST: RESET
;Reset the program
MOVE
AC1, [LK.HLS+LK.LLS];Lock both segments
AC1,
LOCK
;Lock the job in core
JRST FAILED
;LOCK call failed
SETZM
DONFLG
;Initialize done flag
MOVE I
AC2,RTBLK
;Get address of realti~e data block
AC2,
R.TTRP
;Put realtime device on PI level
JRST FAILED
;RTTRP call failed
MOVE
AC2,POINTR
MOVEM
AC2,OPOINT
HLRZ
AC2,RTBLK
;Get PI number from RTBLK
TRO
AC2,BUSY
;Set up CONO bits to start tape
CONO
PTR, (AC2)
;Turn on PTR
MOVE I
AC1,5
;For five seconds .
SLEEP
AC1,
;Sleep
SKIPN DONFLG
;Finished reading the tape?
JRST
.-3
;No, back to sleep
EXIT
;Yes, stop the job
;Here's the trap
TRPADR: CONSO
JRST
MOVE
MOVEM
UJEN

PTR,TAPE
TDONE
AC2,OPOINT
AC2,POINTR

; End-of-tape?
;Yes, stop the job
;Get original pointer
;Restore BLKI pointer
;Dismiss the interrupt

9-9

PROGRAMMING FOR REALTIME EXECUTION

iHere on end-of-tape
APR'rRP: BLOCK

iAPR trap address

TDONE:

AC2,RTBLKI
PTR,O
AC2,

iSet up to remove PTR
iTake device off hardware PI level
iTake device off software PI level
iIgnore errors
iIndicate that reading is done
iDismiss the interrupt

MOVE I
CONO
RTTRP
JFCL
SETOM
UJEN

DONFLG

;Here on failure for LOCK or RTTRP call
FAILED: OUTSTR
/]
EXIT
END

9.1.3

[ASCIZ /RTTRP or LOCK call failed.
Stop the job
BLKTST

Sing1e Mode

The RTTRP argument list for single mode is as follows:
addr:

Where:

XWD
XWD
CONSO
BLOCK

level,realtrap
flags,aprtrap
device, mask
1

level is the interrupt level for the device.
realtrap is the address of the interrupt service
the given device.

routine

flags are realtime interrupt flags.
aprtrap is the trap location for all APR traps.
device is the device code for the realtime device.
mask is an 18-bit mask for the CONSO instruction.

TITLE

RTSNGL - Papertape read test using CONSO chain

UUOSYM

iStandard symbols

iSome values
PIOFF=400
PION=200
TAPE=400
BUSY=20
DONE=10
PICHAN=5
AC1==1
AC2=2

;Turn PI system off
;Turn PI system on
;No more tape in reader
;Device is busy reading
;A character has been read
;PI channel
;Work register
;Work register

; Storage
PDATA:

BLOCK

;Read data into this location
9-10

for

PROGRAMMING FOR REALTIME EXECUTION
;Realtime data block
RTBLK:

XWD
XWD
CONSO
BLOCK

PICHAN, TRPADR
O,APRTRP
PTR,@PTRCSO
1

;PI channel and trap address
;APR error trap address
;Indirect CONSO bit mask = PTRCSO
;No BLKI/O instruction

PTRCSO: BLOCK

;CONSO bit mask

DONFLG: BLOCK

;PI level to user level command

RTBLK1: BLOCK
BLOCK
CONSO
BLOCK

;Data block to remove PTR
; from PI channel

PTR,O
1

;Here we begin
PTRTST: RESET
;Reset the program
AC1, [LK.HLS+LK.LLS];Lock both segments
MOVE
AC1,
LOCK
JRST FAILED
;LOCK call failed
SETZM
PTRCSO
;Zero CONSO bits
DONFLG
SETZM
;Initialize done flag
AC1,RTBLK
MOVE I
;Address of realtime data block
AC1,
;Put realtime device on PI level
RTTRP
JRST FAILED
;RTTRP call failed
AC1,DONE
MOVE I
;Set up CONSO bit mask
AC2,RTBLK
HLRZ
;Get PI number from RTBLK
AC2,BUSY
TRO
;Set up CONO bits to start tape
PI,PIOFF
;Guard against interrupts
CONO
MOVEM
AC1,PTRCSO
;Store CONSO bit mask
PTR, (AC2)
;Turn on PTR
CONO
PI, PION
;Allow interrupts again
CONO
MOVE I
AC1,5
;For five seconds .
; SLEEP
SLEEP
AC1,
;Finished reading the tape?
SKIPN DONFLG
JRST
.-3
;No, back to sleep
EXIT
;Finished
;Here's the trap
TRPADR: CONSO
JRST
DATAl
UJEN

PTR, TAPE
TDONE
PTR,PDATA

;End of tape?
;Yes, stop job
;Read in data word
;Dismiss the interrupt

;Here on end-of-tape
APRTRP: BLOCK

;APR trap address

TDONE:

AC1,RTBLKl
PTR,O
AC1,

;Set up to remove PTR
;Take device off hardware PI level
;Take device off software PI level
;Ignore errors
;Indicate that read is done
;Clear CONSO bit mask
;Dismiss the interrupt

MOVE I
CONO
RTTRP
JFCL
SETOM
SETZM
UJEN

DONFLG
PTRCSO

;Here on failure of RTTRP or LOCK call
FAILED: OUTSTR
/]
EXIT
END

[ASCIZ /RTTRP or LOCK call failed.
;Stop the job
PTRTST
9-11

PROGRAMMING FOR REALTIME EXECUTION
9.1.4

EPT Mode

Executive page table (EPT) mode addresses an interrupt by an offset
into the executive page table.
This mode is only for KL10 processors.
The RTTRP argument list for EPT mode is as follows:
addr:

Where:

XWD
XWD
EXP
BLOCK

level,realtrap
flags,aprtrap
<device>B9+evaddr
1

level is the interrupt level for the device.
realtrap is the address of the interrupt service
the given device

routine

for

flags are realtime interrupt flags.
aprtrap is the trap location for all APR traps.
device is the device code for the realtime device.
evaddr is an offset within the executive process table
EPT-mode interrupt vector.

9.1.5

Exec-Mode Trapping

In special cases, the realtime user requires a faster response time
than that offered by the RTTRP monitor call when executed in user
mode.
To accommodate these cases, you can specify a special status
bit: in the RTTRP monitor call that gives the program control in exec
mode.
Exec-mode trapping gives response times of less than 10
microseconds to real-time interrupts.
To use this exec-mode trapping
feature, the job must have real-time privileges (granted by LOGIN) and
be locked in core (accomplished by using the LOCK monitor call).
The
job must also be mapped contiguously in exec virtual memory.
The
privilege bits that must be set in JBTPRV are:
JP.TRP(Bit 15)
JP.LCK(Bit 14)
JP .RTT (Bit 13)
Several restrictions must be placed on user programs in order to
achieve this level of response.
On receipt of an interrupt, program
control is transferred to the user's real-time program without saving
the accumulators and with the processor in exec mode.
Therefore, the
user program must save and restore all accumulators that are used,
must not execute any monitor calls, and cannot leave exec mode.
This
means that the programs must be self-relocating (that is, through the
use of an index or base register) .
CAUTION
Improper use of the exec mode feature of the RTTRP
monitor call can cause the system to fail in a number
of ways.
Unlike the user mode feature of RTTRP,
errors are not prevented because, in exec mode, the
programs run with no accumulators being saved.

9-12

PROGRAMMING FOR REALTIME,EXECUTION

To specify RTTRP exec mode trapping, Bit 17 of the second word in the
RTTRP argument block must be set to 1. This implies that no context
switching is to be done and that a JSR instruction is to be used to
enter the user's realtime interrupt routine.
The user program must
save and restore all accumulators and should dismiss the interrupt
with a JRSTF to an indirect location.
This instruction must be set up
prior to the start of the real-time device as an absolute or
unrelocated instruction.
This can be done because the LOCK monitor
call returns the exec virtual page' numbers of the low and high
segments after the job is locked in a fixed place in memory.
The exec mode trapping feature can be used with any
forms of the RTTRP monitor call.

the

standard

Example
TITLE

RTFXEX - Realtime trapping in executive mode

UUOSYM

iStandard symbols

iSome values
iNo more tape in reader if TAPE=O
iDevice is busy reading
iA character has been read
iWork register
iWork register
iPI channel

TAPE=400
BUSY=20
DONE=10
I=l
AC2=2
PICHAN=6
iStorage
DONFLG: BLOCK

iPI level to user level command

APRTRP: BLOCK

iAPR trap address

iRealtime data block
RTBLK:

PDATA:
INDEX:

XWD
XWD
CONSO
BLOCK
BLOCK
BLOCK

PICHAN, TRPADR
1,APRTRP
PTR,DONE

iPI channel and trap address
iBit 17 says trap in exec mode

1
1

iData word
iBase index register

iHere we begin

RTEXEC: RESET
SETZM
MOVE
LOCK
JRST
HRRZS
LSH
MOVEM
ADDM
ADDM
MOVE I
RTTRP
JRST
CONO

iReset the program
DONFLG
iInitialize the done flag
AC2, [LK.HLS+LK.LLS]iLock both segments
AC2,
iLock the job in core
; (Absolute address of job
i returned in AC2)
FAILED
iLOCK call failed
AC2,
iGet only low-segment address
AC2,9
iJustify the address
AC2,INDEX
iSave base address for later
AC2,EXCHWD
iRelocate interrupt level program
AC2,JENWD
iRelocate interrupt instruction
AC2,RTBLK
iConnect realtime device
AC2,
i to the PI system
FAILED
iRTTRP call failed
PTR,20+PICHAN
iStart realtime device reading

9-13

PROGRAMMING FOR REALTIME EXECUTION
SLEEP:

MOVE I
HIBER
JRST
SKIPN
JRST
EXIT

TRPADR: BLOCK
EXCHWD: EXCH
CONSO
JRST
DATAl
RETURN: EXCH
JENWD:
JRSTF
TDONE:

CONO
SETOM
JRST

FAILED: OUTSTR
/]
EXIT
END

9.2

AC2,"D1000
AC2,
FAILED
DONFLG
SLEEP

;For 1000 microseconds
; Sleep
;HIBER call failed
;Interrupt level program done?
;No, back to sleep
;Yes, stop the job

I,INDEX
PTR,TAPE
TDONE(I)
PTR, PDATA (I)
I,INDEX(I)
@TRPADR

;JSR TRPADR on interrupt
iSet up index register
;Tape finished?
;Yes, stop the reader
iNO, read next character
iRestore ACs used
iDismiss the interrupt

PTR,O
DONFLG(I)
RETURN (I)

;Take the reader off-line
ilndicate that the tape is finished
iGo dismiss the interrupt

[ASCIZ /LOCK, RTTRP, or HIBER call failed.
;Stop the job
RTEXEC

USING RTTRP AT THE INTERRUPT LEVEL

Your program can use the RTTRP call at interrupt level
(that is,
a
realtime trap can contain an RTTRP monitor call) if the following
rules are observed:

9.3

The program must save any accumulators
interrupt-level trap overwrites them.

The AC used in the interrupt-level
accumulator 16 or 17.

If the device given with the interrupt-level RTTRP is the
same one that caused the interrupt, then no monitor calls of
any kind can be executed in the routine.
Execution of any
further
monitor
calls
(including RTTRP)
dismisses the
interrupt.

RTTRP

may

need;

call

cannot

RELEASING REALTIME DEVICES

To release a realtime device, use
argument list as follows:
addr:

Where:

EXP
BLOCK
EXP

the

RTTRP

monitor

call

with

o
1

<device>B9

device is the device name of the device to be released.

9-14

PROGRAMMING FOR REALTIME EXECUTION
9.4

DISMISSING REALTIME INTERRUPTS

To dismiss a realtime interrupt, use the UJEN monitor calli this call
causes the Inonitor to execute a JEN (or XJEN) instruction to the
address saved by the previous JSR
(to trapaddr or to the context
switcher) .
Executing any monitor call
dismisses the interrupt.

9.5

other

than

RTTRP

during

interrupt

ASSIGNING RUN QUEUES

If your job has the JP.HPQ privilege, you can use the HPQ monitor call
to place the job in a high-priority run queue. When your job executes
a RESET or EXIT monitor call, the job returns to the queue given in
the most recent SET HPQ monitor command.
As the monitor executes timesharing jobs,
it scans high-priority
queues before normal-priority queues; therefore jobs in high-priority
queues are selected for execution before those in normal-priority
queues.
Jobs in high-priority queues are also given preferential treatment by
the monitor in its use of shared resources (such as shared device
controllers).
The monitor's swapper prefers high-priority jobs for
first swap-in and for last swap-out.
The calling sequence for HPQ is:
MOVE I
ac,queue
HPQ
ac,
error return
normal return
Where:

9.6

queue is the number of the high-priority queue that the job is
to be placed in.
If you give queue as 0, the job returns to
timesharing level.
The highest queue number is a system
configuration parameter (0-15).

SUSPENDING OTHER JOBS

If your job has the JP.TRP privilege, you can use the TRPSET monitor
call to temporarily suspend execution of other jobs.
This assures
fast response times to realtime interrupts by minimizing contention
for memory caused by other jobs' I/O.
The calling sequence for TRPSET is:
MOVE
ac, [XWD addrl,addr2]
TRPSET ac,
error return
normal return
In this calling sequence,
addrl
instruction
(must be between 40
address of the argument list.

9-15

is an address for storing an
and 57 octal), and addr2 is the

PROGRAMMING FOR REALTIME EXECUTION
The argument block that addr2 points to is one of the following:
o

addr2:

JSR

addr3

addr2:

BLKI

addr3

In this word, addr3 is a user virtual address.
When the TRPSET call is executed,
the monitor stops executing all
other jobs.
The contents of addr2 (a JSR or BLKI instruction) is
moved to temporary storage, where the given address is converted to an
executive virtual address.
This address is then written into the
location addr1.
The monitor also returns in the ac the previous contents of address;
this allows your program to restore the contents of addr1 after the
TRPSET is executed.
The routine addressed during the interrupt must be locked into
contiguous executive virtual memory; otherwise, the TRPSET call takes
the error return.
On a multiprocessor system,
the TRPSET call applies only to the
processor specified as your job's CPU
(use the SET CPU monitor
command).
The default is CPUO.
The calling sequence for resuming other jobs is:
MOVE I
ac,O
TRPSET ac,
error return
normal return

;insufficient privileges
;timesharing restarted

On a successful return, user I/O is set for the job.

9-16

CHAPTER 10
ANALYZING SYSTEM PERFORMANCE

The TOPS-10 monitor offers the following monitor calls to provide
privileged users with tools to measure system performance: the
PERF. call
to
control
the
system's
performance
meter
and
the SNOOP. monitor call to insert breakpoints in the monitor to trap
to user programs.

10.1

THE PERFORMANCE FACILITY: PERF.

The PERF. monitor call allows privileged jobs on a KL10 processor to
measure system performance over medium to long periods of time.
See
the DECsystem-10/DECSYSTEM-20 Processor Reference Manual
for
a
detailed presentation of the performance meter. PERF. allows you to
count rates associated with memory cache, PI interrupt channels,
program counters, microcode, hardware, and I/O channels
Only one job at a time can use the performance facility on any
particular cpu. A job can have more than one CPU's PERF meter in use
at the same time.

10.1.1

Performance Modes

The performance meter can operate in either of two modes:

10.1.2

Timer mode (bit PM.MOD of .PMCPU is set) counts the number of
cycles while a condition specified by enabled bits is
true. When the logical AND of all enabled bits is true,
the
counter counts at 1/2 the CPU cycle rate (Model A = 25MHz,
Model B = 30MHz) .

Counter mode (bit PM.MOD of .PMCPU is cleared)
number of times the specified conditions occur.

cpu

counts

the

Performance Enable Flags

The PERF. meter must be initialized before it can be started.
When
your job initializes the performance meter,
it specifies which
conditions are to be timed (timer mode) or counted (counter mode) .
The meter has classes of conditions that you can enable by including
flags in the argument list for .PRSET function of the PERF. UUO.
The
meter runs if all classes are true. A class is true if any condition
within that class is true. For PERF., if no conditions within a class
are specified, that class is ignored (forced true) .
10-1

ANALYZING SYSTEM PERFORMANCE
To obtain accurate measurement of the cache hit rate, set the PM.SYN
bit
in the cache enable word
(.PMCSH);
this synchronizes the
performance and accounting meters.
Your job can measure the number of cache hits by using the performance
meter to measure the total number of memory references and subtracting
the number of cache misses.
The cache hit rate is the number of cache
hits divided by the total number of memory references.
To measure the cache hit rate for a job, the accounting meters must
exclude both priority-interrupt time ,and monitor overhead.
You can
exclude these by rebuilding the monitor, after selecting the proper
accounting options with MONGEN.
Note, however, that these changes
affect the methods for gathering usage accounting data.
Alternatively, you can set the following bits in GETTAB Table .GTCNF:
Word

Symbol

Bit

Name

Meaning

%CNSTS

ST%EMO

Exclude monitor overhead from user
runtime.

106

%CNST2

ST%XPl

Exclude priority interrupt
from user runtime.

106

%CNST2

ST%ERT

Use EBOX/MBOX accounting.

time

Your job must also set bit PM.NPl in the priority-interrupt enable
word
(.PMPlE);
this enables the meter only when no interrupts are in
progress.
To measure the cache hit rate for the system,
the accounting meters
must include both priority-interrupt time and monitor overhead.
You
can include these by rebuilding the monitor
(selecting the proper
accounting options), or by setting bit ST%XPl to 0 and ST%ERT to 1, in
item %CNST2 of the GETTAB Table .GTCNF.
The performance meter must be
set to measure cache misses,
with no bits set in enable words 4
through 11 (.PMPlE through .PMCHN).
Note that the formats of accounting meter counts
make them consistent, divide MBOX counts by 10000

10.1.3

are different;
(octal) .

PERF. Functions

The following is a list of the PERF. functions:
Fcn-code

Symbol

Meaning

.PRSET
.PRSTR
.PRRED
.PRSTP
.PRRES
.PRBPF
.PRBPN

Sets up the performance meter.
Starts the performance meter.
Reads the performance meter.
Stops the performance meter.
Releases the performance meter.
Turns background PERF analysis off.
Turns background PERF analysis on.

2
3
4
5
6
7

10-2

ANALYZING SYSTEM PERFORMANCE

The PERF. functions are usually used in the following order:
1.

Initialize the performance meter (.PRSET).

Start the performance meter (.PRSTR).

Stop the performance meter (.PRSTP).

Release the performance meter (.PRRES).

Your program can also read the performance meter (.PRRED function)
time after initializing it, but before releasing it.

any

The calling sequence for the PERF. monitor call is:
MOVE
ac, [XWD len,addr]
PERF.
ac,
error return
normal return
addr:

arglst:
Where:

XWD

fcn-code,arglst

XWD

fcn-code,arglst

argument block
len is the length of the argument list.
addr is the address of the argument list.

At the address you loaded into the ac,
fcn-code is one of the
PERF. functions listed above and arglst is the address of the argument
list for the function code.
This format allows you to specify
multiple functions with a single PERF. call. At the address specified
in arglst, store the argument block for the function code.
Function
codes and their argument blocks are described in the following
sections.

10.1.3.1 Initializing the Performance Meter - Use the .PRSET function
to initialize the performance meter.
The format of the argument
block, with offsets from the beginning of arglst (see above)
for the
.PRSET function is:

Word

Symbol

Contents

.PMLEN

Length of the
word) .

.PMCPU

CPU type:

argument

Bits

Symbol

Meaning

0
1

PM.PD6
PM.KA
PM.KI
PM.KL
PS.KS

PDP-6.
KA10.
KIlO.
KL10.
KS10

3
4

10-3

block

(not

including

this

ANALYZING SYSTEM PERFORMANCE
2

.PMMOD

.PMCSH

CPU number and mode:
Bits

Symbol

Meaning

0-17
18

PM.CPN
PM.MOD

PM.CLR

CPU number.
Performance mode.
If this bit is
not set, the duration of time during
which enabled events are true is
counted.
If this bit is set, the
number of enabled events is counted.
Refer to Section 10.1.1.
Clear performance meter counts.

Cache enable flags:
Bits

Symbol

Meaning

PM.CCR
PM.CCF
PM.EWB
PM. SWB
PM. SYN

Count references.
Count fills.
Count EBOX writebacks.
Count sweep writebacks.
Synchronize
performance
accounting meters.

2
3
4

.PMPIE

Priority interrupt enable flags:
Bits

Symbol

Meaning

PM.PIO
PM.PI1
PM.PI2
PM.PI3
PM.PI4
PM.PI5
PM.PI6
PM.PI7
PM.NPI

Enable
Enable
Enable
Enable
Enable
Enable
Enable
Enable
Enable

2
3
4
5
6
7
8

.PMPCE

.PMMPE

for
for
for
for
for
for
for
for
for

channel O.
channell.
channel 2.
channel 3.
channel 4.
channel 5.
channel 6.
channel 7.
no interrupt in progress.

Program counter enable flags:
Bits

Symbol

Meaning

PM.UPC
PM.XPC

User-mode enable.
Executive-mode enable.

and

Microcode probe enable flag:
Bits

Symbol

Meaning

PM.MPE

Enable microcode probe.

10-4

ANALYZING SYSTEM PERFORMANCE
7

.PMHPE

.PMCHN

Hardware probe enable flags:
Bits

Symbol

Meaning:

0
1

PM.POL
PM.POH

Probe zero low.
Probe zero high.

.PMJOB

This contains the
Job enable word.
job number of the job for which the
meter is enabled,
or one of the
following values:

Code

Symbol

Meaning:

-2
-1

.PMNUL
.PMSLF

Enable for null job.
Enable for calling job.

Channel enable flags:
Bits

Symbol

Meaning:

0
1·
2
3
4
5
6
7

PM.ECO
PM.EC1
PM.EC2
PM.EC3
PM.EC4
PM.EC5
PM.EC6
PM.EC7

Enable
Enable
Enable
Enable
Enable
Enable
Enable
Enable

for
for
for
for
for
for
for
for

channel
channel
channel
channel
channel
channel
channel
channel

O.
1.
2.
3.
4.
5.
6.
7.

10.1.3.2 Starting the Performance Meter - To start the performance
meter,
use the .PRSTR function.
The argument block for this function
is listed here with offsets from arglst (See Section 10.1.3.)
Word

Symbol

Contents

.PMLEN

1
2

.PMCPN
.PMHTB

3
4
5
6

.PMLTB
.PMHPM
.PMLPM
.PMHMC
.PMLMC

Count of following words.
(Supply this in your
program. )
CPU number.
(Supply this in your program.)
High-order word of time-base.
(The rest of the
data is returned by the monitor.)
Low-order word of time-base.
High-order word of performance counter.
Low-order word of performance counter.
High-order MBOX reference count.
Low-order MBOX reference count.

Your program supplies the first two
(.PMLEN and .PMCPN); the monitor
normal return.

words of this argument block
returns the remaining words on a

10.1.3.3 Reading the Performance Meter - To read the performance
meter,
use the .PRRED function.
The argument block for this function
is the same as for the .PRSTR function.
Your program supplies the
first two words of the argument; the monitor returns the remaining
words on a normal return.

10-5

ANALYZING SYSTEM PERFORMANCE
10.1.3.4 Stopping the Performance Meter - To stop the performance
meter,
use the .PRSTP function.
The argument block for this function
is the same as for the .PRSTR function.
Your program supplies the
first two words of the argument; the monitor returns the remaining
words on a normal return.

10.1~3.5
Releasing the Performance Meter - To release the performance
meter,
use the .PRRES function.
The argument block for this function
is the same as for the .PRSTR function.
Your program supplies the
first two words of the argument; the monitor returns the remaining
words on a normal return.

10.1.4

Background PERF. Functions

When the performance meter is not assigned to a specific job,
it can
be set to gather system-wide statistics.
This is called "background
performance analysis." It is enabled using the PERF.
function .PRBPF,
and disabled with .PRBPN. While it is enabled, the monitor can sample
PI channel and RH20 usage.
When setting the background performance meter, i,t is advisable to set
bit 19 in .PMMOD to clear the counters.
You set the timing interval
in word .PSCSH, specifying the number of ticks.
The data for the background performance meter is kept in GETTAB Table
.GTCnV,
where n is the CPU number.
The table is formatted in 4-word
blocks, of which-the first pair of words contains the elapsed time
since the time was cleared.
The second pair of words in each block
contains the meter count for the performance meter.
Because each CPU has one performance meter, the monitor samples each
item in turn, for the specified period. At the end of the period, the
meter updates the counter.
The background performance meter is
suspended if a job assigns the performance meter for another purpose.
When it is deassigned, the background meter is restored.

10.1.5

PERF. Errors

On an error for a PERF. monitor call, one of the following error codes
is returned in the ac:
Code

Symbol

Error

1
2
3
4

PRCPU%
PRNXC%
PRMOD%
PRSET%
PRUSE%
PRRUN%
PRJOB%
PRNRN%
PRNIM%
PRFUN%
PRPRV%

Invalid CPU specified.
Nonexistent CPU specified.
Improper mode specified.
Meter not set up.
Meter already in use.
Meter already running.
Invalid job number.
Meter not running.
Function not implemented.
Invalid function code.
Not enough privileges.

6
7

10
11

12
13

10-6

ANALYZING SYSTEM PERFORMANCE
10.2

THE SNOOP FACILITY: SNOOP.

The SNOOP. UUO allows the
insert breakpoints into
the monitor code.

privileged program
([1,2]
or JACCT)
to
the monitor, thereby patching routines into

The breakpoints must be defined before they can
be
enabled.
The SNOOP. function to define breakpoints requires your program to
supply the checksum of the current monitor's symbol table.
This
requirement ensures that your program recognizes the current monitor
symbols and locations.
The checksum will be compared to the monitor's
own analysis of the checksum,
and if the two are not equal, the
SNOOP. UUO will fail.
In addition, the breakpoint definitions must supply monitor addresses
for locations that will be patched.
These addresses can be obtained
from the monitor symbol table as well.
To obtain the checksum and monitor addresses, your program can use its
own algorithms,
or you can call routines from the SNUP.MAC package
that is distributed with the monitor sources.
SNUP.MAC contains
several
routines
that
obtain
information
to
be
used
in
the SNOOP. argument block, and others serve as examples of how to use
the SNOOP. UUO.
To compute the checksum and locations yourself, you must obtain the
file specification of the current monitor.
The relevant information
can be obtained from GETTAB Table .GTCNF, where the important words
are:
Word

Contents

%CNBCP
%CNBCL
%CNNCR
%CNMBS
%CNMBF
%CNMBX
%CNMBD

Bootstrap CPU number.
Bootstrap line number.
Number of CPUs allowed to run.
File structure where bootstrap monitor is stored.
File name of bootstrap monitor.
File extension of bootstrap monitor.
Bootstrap file directory.

The maximum number of breakpoints that can be inserted is defined as
GETTAB symbol %CNBPM in Table .GTCNFi the default monitor defines this
value to be 64.
To insert the defined breakpoints, your program must be locked into
contiguous Executive Virtual Memory (EVM).
You can lock your job into
EVM using the LOCK. UUO, which will return the new starting address
(as the virtual page number) of your job. Remember that subsequent
references to user address space must be accompanied by the offset of
the relocation.
That is, you should compute the difference between
your original starting address in user space and the new starting
address in EVM, and use that difference as an offset for references to
locations in your program.
Because you must lock your job in EVM to use the
SNOOP.
UUO, you
must remember that the monitor will perform no functions to save data
when you pass control to the routines in your program that perform the
actually data gathering and analysis.
In other words, save'the state
of the current accumulators when you JRST to your routine at the
breakpoint. Observe that the monitor defines accumulator P=1, not 17,
as user programs normally do. While in breakpoint code, your program
cannot execute a monitor call or leave exec mode.

10-7

ANALYZING SYSTEM PERFORMANCE

After inserting the breakpoints, you can remove them at will with
SNOOP. UUO. After you remove them, you can re-enable them, or you can
delete the breakpoint definition.
To delete a breakpoint definition,
you must remove the breakpoint first.
Similarly,
to insert a
breakpoint, you must define it first.
As with real-time job execution, only one job can define breakpoints
at a time.
Until the job undefines its breakpoints, all other jobs
attempting to snoop will receive an error.
In the event of necessary
recovery functions, the monitor can delete the breakpoint definitions.
This might occur if a memory parity error occurred,
or if your
job
received a stopcode.
When your program issues a RESET, that also
removes and deletes definitions of breakpoints.
Examples of using SNOOP. are
monitor call in Chapter 22.

provided

the

description

The SNOOP. functions are listed here.
More specific
their action is given in following sections.

the

explanation

Fcn-code

Symbol

Meaning

.SODBP
. SOIBP
.SORBP
.SOUBP
.SONUL

Define breakpoints.
Insert breakpoints .
Remove breakpoints.
Delete breakpoint definitions.
Null function.
This function is useful when
you must patch code into the monitor to
perform functions at UUo level that cannot be
accomplished at interrupt level.

2
3
4

The calling sequence for the SNOOP. call depends on the function code.
Only the function to define breakpoints (.SODBP) requires an argument
block. After the breakpoints have been defined,
the subsequent
functions of the SNOOP. call will take action on the breakpoints you
have defined.
Each function and calling
sections.

10.2.1

sequence

described

the

following

Defining Breakpoints

The SNOOP. function 0 allows you to define the breakpoints that you
will insert into the monitor code.
The calling sequence for .SODBP
is:
MOVE
ac, [XWD .SODBP,addr]
SNOOP.
ac,
error return
normal return
In this calling sequence, the left half of the ac is loaded with the
function code (in this case, .SODBP, function code 0).
The right half
is loaded with addr, the address of the argument list.
On an error,
the SNOOP. call takes a non-skip return, and the error code is stored
in the ac.
(Error codes are listed in Section 10.2.5.) No breakpoints
will be defined on an error.
If, however, the call takes a successful
(skip) return, all the breakpoints in the argument list will be
defined.
You can issue the SNOOP. call with function code 1 to insert
the breakpoints, enabling the breakpoint facility.

10-8

ANALYZING SYSTEM PERFORMANCE

The argument list for SNOOP. function 0 (.SODBP) is:
Word

Symbol

Contents

. SOLEN

The total length of the argument list, including
this word.

. SOMSC

The checksum of the monitor symbol table .

Following these is a two-word pair for each breakpoint you want to
define.
Therefore, the total number of breakpoints will be the result
of:
{[.SOLEN minus 2] divided by 2}.
Word

Symbol

Contents

.SOMVA

The monitor virtual address where the breakpoint
instruction is to be inserted.
This address
must be obtained from the monitor symbol table
to ensure accuracy.

.SOBPI

The breakpoint instruction that is
to
be
inserted at the monitor address specified in
.SOMVA.

Repeat words .SOMVA and .SOBPI for each breakpoint to be defined.
Note that the inserted instruction is executed prior to the original
instruction.
If the inserted instruction skips on return,
the
original instruction will not be executed.
If
the
inserted
instruction skips more than one instruction,
or does not return,
the SNOOP. data base will be damaged.

10.2.2

Inserting Breakpoints

After your program defines the breakpoints, they can be inserted with
SNOOP. function 1, .SOIBP.
Your program must be locked in contiguous
EVM to use this function.
(Refer to the LOCK. UUO.)
The calling
sequence for the .SOIBP function is:
MOVE
ac, [XWD .SOIBP,O]
SNOOP.
ac,
error return
normal return
The .SOIBP function does not require an argument list.
If the error
return is taken, the error code is returned in the ac.
If the normal
return is taken, the breakpoints were inserted and are enabled.

10-9

ANALYZING SYSTEM PERFORMANCE
10.2.3

Removing Breakpoints

Breakpoints that have been inserted with the .SOIBP function can be
removed with the
.SORBP function (function code 2).
This function
will succeed if the breakpoints have been inserted,
and will remove
all the breakpoints.
The calling sequence for this function is:
MOVE
ac, [XWD .SORBP,O]
SNOOP.
ac,
error return
normal return
After removing the breakpoints,
you can insert them again
function
.SOIBP), or you can delete the breakpoint definitions
function .SOUBP).

10.?4

(using
(using

Deleting Breakpoint Definitions

After breakpoints have been removed
(using function
.SORBP),
the
breakpoint definitions can be deleted.
This clears the definitions
that you made with the .SODBP function.
The calling sequence for this
function is:
MOVE
ac, [XWD .SOUBP,O]
SNOOP.
ac,
error return
normal return
This function will delete all definition of the breakpoints,
and you
must redefine them by using .SODBP if you want to insert them again.
Note that breakpoint definitions can be deleted by the monitor and by
a RESET from your program (as described in Section 10.2) .

10.2.5

SNOOP. Error Codes

The following is a list of the error codes that can be returned in the
ac after a SNOOP. UUO fails:
Code

Symbol

Error

1
2

SOIAL%
SONPV%
SOSAS%
SOMBX%
SOIBI%
SONFS%
SOADC%
SOINL%
SOWMS%

Illegal argument list.
Not enough privileges.
Another program is already SNOOPing.
Maximum number of breakpoints is exceeded.
Breakpoints are already inserted.
No monitor free core is available.
Address check.
Program is not locked in contiguous EVM.
Monitor symbol table checksum does not match.

4
5

6
7

10
11

10-10

CHAPTER 11
PROGRAM INPUT AND OUTPUT

This chapter describes I/O programming in general terms.
Further
discussions of I/O programming for specific devices are included in
the chapters describing devices.

11.1

OVERVIEW OF THE I/O PROCESS

To perform I/O, your program should:
o

Initialize the program.

Initialize a device.

Initialize a buffer ring when using buffered I/O or define
command list when using dump I/O.

Select a file.

Transmit/receive data.

Close the file.

Release the device.

Stop the program.

There are two ways of performing I/O: buffered I/O and dump I/O.
The
list below summarizes the monitor calls you need to perform I/O with
each method. Each of the monitor calls listed below in the summary is
described in detail in Volume 2, Chapter 22. Note that any device
operation listed below can be done with the FILOP.
call, because I/O
operations using channels 20-117 can only be done with FILOP.
Buffered I/O

Dump I/O

Program Initialization

RESET

Device Initialization

INIT, OPEN, FILOP.

Buffer Initialization

INBUF, OUTBUF, FILOP.

File Selection

LOOKUP, ENTER
FILOP.

Device Position

USETI, USETO
UGETF, SUSET.,
FILOP., MTAPE

11-1

PROGRAM INPUT AND OUTPUT
Data Transmission

IN, INPUT, FILOP.
OUT, OUTPUT

IN, INPUT, FILOP.,
OUT, OUTPUT
command list

Command List Definition
File Termination

CLOSE, FILOP.

Device Termination

RELEASE, FILOP.

Program Termination

EXIT

In the summary above, when a group of monitor calls is listed for a
given I/O step, usually only one of the calls from the group must be
included in your program.
For example,
the data transmission step
lists four calls (IN, INPUT, OUT, and OUTPUT).
However, only one of
these is present in your program for each data transmission.
On the
other hand, there are three calls listed for the file selection step.
At times you should include more than one of these calls in your
program for proper file selection.
The following sections in this chapter describe the calls that are
necessary for each step.
Note that the file selection step and the
device position step apply only to directory devices
(DECtape,
labelled magtape,
and disk).
Unlabelled magnetic tapes can be
positioned using the MTAPE or TAPOP.
monitor calls.
The device
positioning monitor calls,
however, may be included in your program
for any device,
allowing device interchangeability,
because the
monitor ignores calls which are inappropriate for the device.

11.2

INITIALIZING A PROGRAM

To initialize a program,
use the RESET monitor call.
This call
performs most of the functions you will want when initializing your
program.
The RESET call should be the first monitor call in your
program.

11.3

INITIALIZING A DEVICE

To initialize a device, use the OPEN, INIT,
or FILOP. monitor call.
Each of these calls can initialize a channel for the device, making it
available for use in your program.
Your program can use up to 16 I/O
channels
(0-17 octal)
using OPEN or INIT.
The extended channel
facility, which you use with FILOP.
allows you to use up to 64
(decimal)
additional I/O channels
(providing a total of up to 80
channels)

11.3.1

TOPS-10 Devices

The TOPS-I0 operating system supports the following devices.
Note,
however,
that current versions of TOPS-I0 restrict the support status
of some devices.
For information about the current support status of
TOPS-I0 devices, refer to the TOPS-I0 Software Product Description.
o

Disks

(DSK).

DECtapes

Refer to Chapter 12.

(DTA).

Refer to Chapter 13.

11-2

PROGRAM INPUT AND OUTPUT

Magtape units (MTA).

Refer to Chapter 14.

Terminals (TTY). Refer to Chapter 15.
This chapter also
discusses the pseudo-terminal (PTY) device.
The remote data
terminal (RDx) device is discussed in Chapter 21.

Line printers (LPT).

Card readers (CDR) and card punches (CDP).

Refer to Chapter 16.
Refer to

Chapter

17.

Papertape readers (PTR) and papertape punches
to Chapter 18.

Plotters (PLT).

Display light pens (DIS).

Refer to Chapter 20.

Network nodes,
Chapter 5.

TSK

Multiplexed devices (MPX).

(PTP) .

Refer

Refer to Chapter 19.

using

the

logical

device.

Refer

Refer to Section 11.3.4.

This chapter contains information common to all these devices.
When the system is loaded, most devices are assigned to the monitor's
pool of available resources. When a program requests a device, the
monitor assigns it to the program; when the program releases the
device, the monitor returns it to the pool.
Most devices can be used interchangeably during program execution.
Therefore you can write a program for one device, and substitute a
different device during program execution. This substitution can be
accomplished by the ASSIGN command, or by the REASSI or DEVLNM monitor
call.
Specifically, TOPS-10 devices may be divided into "directory devices"
and "non-directory devices." A directory device contains named files
stored in directories.
Disk,
DECtape,
and labelled magtapes are
directory devices.
A DECtupe contains one directory; disk file
structures and magtapes may contain multiple directories.
Therefore,
to access data on disk, a file name and directory specification might
be required. TOPS-10 allows you to program I/O regardless of the type
of device.
You should include the file name and directory for all
references to files.
For non-directory devices, the monitor ignores
directory information.

11.3.2

Device Names

Your program refers to devices by their device names.
The various
formats of device names are described below.
In this description, dd
and ddd are 2- and 3-letter mnemonics, nn is a 2-digit node number;
and -U- is a 1-digit unit number. ~ote that many system and user
programs require a trailing colon for parsing; however, monitor calls
do not allow the trailing colon in device names.

11-3

PROGRAM INPUT AND OUTPUT

Format

Example

Do not use this format.

Meaning

The monitor tries to select a device of the
type specified
(in the example, a lowercase
line printer) at the job's node.
If all such devices are in use,
the monitor
takes the error return for the monitor call; if
no such device exists at the job's node,
the
monitor tries to select a device at the central
site.
If the job has such a device assigned but not
initialized, the monitor selects that device.

ddnn

LL23

The monitor tries to select a device of the
type specified at the specified node (in the
example, a lowercase line printer at node 23) .

ddnnu

Do not use this format.

ddu

Do not use this format.

ddd

LPT

The monitor tries to select a device of the
type specified at the job's node
(in the
example, a line printer).
See the meaning of
dd above.
If all such devices are in use,
the monitor
takes the error return for the monitor call; if
no such device exists at the job's node,
the
monitor tries to select a device at the central
site.

dddnn

LPT23

The monitor tries to select a device of the
type specified at the specified node (in the
example, a line printer at node 23) .
See the
meaning of ddnn above.

dddnnu

LPT231

The monitor tries to select the specified
device at the specified node (in the example,
line printer number 1 at node 23) .

dddu

LPT3

The monitor tries to select the specified
device at the job's node (in the example, line
printer number 3 at the job's node).
If all such devices are in use,
the monitor
takes the error return for the monitor call; if
no such device exists at the job's node,
the
monitor tries to select a device at the central
site.

ddnuuu

RAD222

The monitor tries to select the dd disk device,
unit uuu, on the HSC-50 node n.
In this case,
the device is an RAxx type, the unit is 222,
and the HSC-50 node is 4 (where A=l, B=2, and
so on) .
Unit numbers for disk are always
decimal.

11-4

PROGRAM INPUT AND OUTPUT
There are four types of device names:
o

Generic names specify general types of devices.
When you
specify a generic device name, the monitor chooses the first
available unit that satisfies the requirements of the generic
device name.

Physical names specify device units,
possibly on specific
controllers,
allowing you to specify the exact unit your job
requires.

Logical names are user-defined or monitor-defined names for
devices.
Monitor-defined logical names are specific devices
that have a special purpose in the system.

Ersatz names are logical device names assigned by the monitor
for disk areas that have a particular purpose, such as
libraries.
This allows you to specify a disk area with a
short device name.

11.3.2.1 Generic Device Names - A generic device name is the most
general name of a device.
When your program specifies a generic
device name, the monitor tries to select a free device of the
specified type at the job's node; if none is available, the monitor
tries to select a free device of the type specified at the central
site.
A generic device name is a 2- or 3-letter string.
Note that many
system and user programs require a trailing colon for parsing;
however, monitor calls do not allow the trailing colon in device
names.
The generic device names and their meanings are:
3-Letter Name

2-Letter Name

Meaning

TTY

User terminal.

DSK

Disk.
The monitor uses the
job
search list to select the device.
See Chapter 13 for a discussion of
job search lists.

MTx

Magtape unit on controller x.
For
example, MTA specifies a magtape unit
on controller A.

7-track magtape.

9-track magtape.

DTx

DECtape unit on controller x.
For
example, DTA specifies a DECtape unit
on controller A.

LPT

Line printer.

Uppercase and lowercase line printer.

Uppercase line printer.

Card reader.

CDR

11-5

PROGRAM INPUT AND OUTPUT

CDP

Card punch.

PTR

Papertape reader.

PTP

Papertape punch.

PLT

Plotter.

DIS

Display.

PTY

Pseudo-terminal.

Remote data terminal, where x is
controller name (A to Z) .

11.3.2.2 Physical Device Names - Every device has a
name of the form:

physical

the

device

dddnnu
ddct is a 3-letter generic device name.

Where:

nn is a node number.
u is a unit number.
For example,
LPT231 specifies line
printer number 1 at node 23.
This convention does not apply
to terminals, magtapes, and DECtapes, however.

11.3.2.3 Logical Device Names - A logical device
name
is
an
alphanumeric string of up to six characters, assigned by the monitor
or by the user.
The monitor has the following predefined logical
device names to refer to specific devices that are used for the
following purposes:

OPR specifies the physical terminal
operator as the operator terminal.

designated

the

NUL specifies a null device.
Output to NUL is lost.
If you
attempt input from NUL; your IN UUO fails and-GETSTS returns
IO.EOF (end-of-file) in the file status word.

CTY specifies the console terminal for the system.

TTY specifies your job's terminal.

User-defined logical names are defined by the ASSIGN or MOUNT monitor
command,
or by the REASSI or DEVLNM monitor call.
You can assign one
logical name to each nondisk physical device.
A logical device name takes precedence over a physical device name.
Therefore,
if your program defines the logical name DSK for a magtape
device, all references to DSK specify the magtape rather than the user
disk area.
There are methods for indicating that the monitor should ignore
logical name definitions.
This can be specified in the OPEN call, by
setting the bit UU.PHS in the argument block.
(Note that this bit can
also be set in FILOP. word .FOIOS).

11-6

PROGRAM INPUT AND OUTPUT
Alternatively,
you can disable logical name definitions for
a
particular CALLI function by XORing Bit 19 (UU.PHY) into the CALLI
monitor call. For example, to obtain the device type of a physical
device LPT, use the following sequence:
MOVE T1, [SIXBIT/LPT/]
DEVTYP T1,UU.PHY
This calling sequence ORs UU.PHY into the argument of the DEVTYP call,
with the device name LPT.
The information will be returned for
physical device LPT.
For negative CALLIs, you must place the NEGATIVE value of UU.PHY in
the address field.
For the LIGHTS monitor call (CALLI-I), and
customer-defined monitor calls (CALLI -2 and less), use the following
sequence to perform the call, ignoring logical names:
LIGHTS T1,-UU.PHY

11.3.2.4 Ersatz Device Names - An ersatz device is a disk-simulated
library. Although an ersatz device is OPENed like a directory device,
an ersatz device represents a particular project-programmer number on
disk structures that are specified in a search list.
The particular
search list used depends on the ersatz device specified in your
program.
The following is a list of TOPS-10 standard ersatz device
names.
It shows the ersatz device name, the PPN to which the name is
assigned (if any), the search list of file structures on which the PPN
exists, and the intended use of the disk area.
Table 11-1:

Ersatz Devices

Search List

Purpose of Area

SSL
SSL
ALL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
JSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
JSL
SSL
SSL

System accounting
ALGOL
All structures

Name

PPN

ACT
ALG
ALL

1,7
5,4
NONE
5,31
5,1
5,5
5,2
5,27
5,32
5,24
10,7
5,21
5,14
NONE
5,15
1,2
5,6
5,36
5,30
2,5
5,34
SETTABLE
5,7
1,1

APL

BAS
BLI
COB
CTL
D60
DBS
DEC
DMP
DOC
DSK
FAI
FFA
FOR
FNT
GAM

HLP
INI
LIB
MAC
MFD

APL

BASIC
BLISS
COBOL
Control files
DN60 (IBMCOM) files
DBMS
Field-image versions of programs
Dump area
Documentation
Default device
FAIL
Operator (Full File Access)
FORTRAN
LN01 fonts
Games
HELP files
Initialization files
Library
MACRO
Master file directory

11-7

PROGRAM INPUT AND OUTPUT
MIC
MUS
MXI
NEL
NEW
OLD
POP
PUB
REL
RNO
SNO
SPL
SSL
S'rD
SYS
TED
TPS
TST
UMD
UNV
UPS
u'rp
XPN

5,25
5,16
5,3
5,20
1,5
1,3
5,22
1, 6
5,11
5,12
5,13
3,3
NONE
1,4
1,4
5,10
5,26
5,23
6,10
5,17
5,35
5,33
10,1

SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL
SSL

MIC files
Music
PDP-II
NELIAC
New CUSPs
Old CUSPs
POP2
User maintained programs
.REL files
RUNOFF files
SNOBOL
Spooling area
System search list
Same as SYS, but /NEW doesn't apply
System CUSPs
Text editor
Text processing
Test area
TJser mode diagnostics
Universal files
Mail system area
UETP
Crash dumps

The search lists in this list are:
o

SSL (System Search List) is defined by the system manager
while running the ONCE startup dialog.
Refer to the TOPS-10
Software Installation Guide for more information.

JSL (Job Search List) is defined as equivalent to the SSL by
default; the default can be changed using the SETSRC program.
Refer to the TOPS-10 User Utilities Manual
for
more
information on SETSRC.

ALL (All Search List) is the definition of all
file structures in their order of accessibility.

the

public

11.3.2.5 Pathological Device Names - The user can define a
logical
name for a directory search path.
Such user-defined names are called
"pathological names." Pathological names can define one or more disk
directories, and are described in Section 12.6.5.

11.3.3

Universal Device Indexes

The monitor maintains an index to all active devices;
this index is
called the Universal Device Index (UDX).
For Versions 7.02 of TOPS-10
and later, the description of the Universal Device Index is fixed only
for terminal devices.
Many operations allow your program to use the
Universal Device Index for a device rather than its name or channel
number.
Use the IONDX. monitor call to obtain the Universal Device
Index for a device.

11-8

PROGRAM INPUT AND OUTPUT

The format of a Universal Device Index is:
Bits

Symbol

18-20

Meaning
Device or process:
Code

Symbol

Meaning

0
2
3

. UXCHN
. UXTRM
.UXPRC

Physical device .
Terminal .
Process.

21-26

UX.TYP

Device type.
Refer to the DEVTYP call in Volume
2,
Chapter 22,
for the list of device types.
This field is 0 for terminals.

27-35

UX.UNT

Unit number within type.

For example, the Universal Device Index 200114 indicates the device
TTYl14;
the 2 in Bits 18-26 shows that the device is a terminal, and
the 114 in Bits 27-35 shows that it is TTYl14.

11.3.4

MPX-Controlled Devices

MPX (multiplexed) channel can have many devices connected to it.
(Refer to the CNECT. monitor call.)
A device connected to an MPX
channel is an MPX-controlled device.
Only terminals,
line printers,
papertape punches,
card readers,
remote data terminal (RDx) , and
pseudo-terminals are MPX-controllable.

Your programs can refer to MPX-controlled devices by their physical or
logical names, or by their Universal Device Indexes.

11.3.5

Spooled Devices

Some devices can be spooled by the monitor.
This means that input
from or output to these devices is not necessarily done immediately.
Instead, the data is stored in a special system area and is input or
output at a convenient time.
Devices that can be spooled are:
card reader,
line printer,
card
punch,
papertape punch, and plotter.
The spoolers may be controlled
by GALAXY, which is documented in the TOPS-10 Operator's Guide.
For
the spooled devices for your job, the GETTAB Table .GTSPL contains a
bit for each type of device.
If the bit is on and the device is
ASSIGNed or INITed for your job, the device is spooled.
When you
CLOSE or RELEAS a spooled output device, output is saved until the
device becomes available.
The I/O is copied to disk, to the DSK: [3,3]
(spooling) area.
For example, if the system card reader is spooled, the monitor reads
any available input from the card reader into its storage area. When
a program requests card reader input, the monitor supplies the data
previously read.
For another example, if the system line printer is spooled, output for
the line printer is placed in the monitor's storage area.
Then the
system prints the data at a convenient time.

11-9

PROGRAM INPUT AND OUTPUT
You spool the device using the SET SPOOL monitor command or the SETUUO
monitor call.
Frequently, LOGIN spools devices under control of the
accounting files.
For input spooling, if a LOOKUP is given after the cardreader is
initiated with the INIT call, the LOOKUP is ignored and an automatic
LOOKUP is done, using the file name given in the previous SET CDR
monitor command with the file extension of
.CDR.
After every
automatic LOOKUP,
the name in the input-name counter .GTSPL is
incremented by 1,
so that the next automatic LOOKUP will use the
correct file name.
For output spooling, if an ENTER is done, the file name is stored in
the RIB in location .RBSPL so that the output spooler can label the
output.
Therefore, programs should specify a file name if possible.
If an ENTER is not done, an automatic ENTER is generated, using a file
name in the form:
xxxyyy.zzz
Where:

xxx is a unique, three-character name devised by the monitor.

yyy is either of the following:
o

Snn, where nn is the ANF-10 remote station node number for
a generic device.

The unit number of the specified unit.

zzz is a three letter generic device name, such as LPT.
Under
GALAXY 4.1 and later versions,
the file names for spooled
files are generated as:
filename.SPL
For previous versions of GALAXY or MPB, the file names are:
filename.CDP for
filename. CDR for
filename.LPT for
filename.PLT for
filename.PTP for

11.3.6

card punch
card readers
line printers
plotters
papertape punch

Restricted Access Devices

Any device except a disk or a terminal can be restricted to controlled
access.
This means that the operator (or a privileged user) can make
the device assignable only by the operator.
Privileged users can use
the DVRST. monitor call to designate a specified device as being
restricted and the DVURS. call to remove the restricted status of a
device.
The GALAXY 4.1 batch and spooling system controls devices with the
Mountable Device Allocator (MDA) routines.
Control by MDA is set with
the DEVOP. function .DVMDS, and cleared using function
.DVMDC.
This
MDA-controlled bit is set to prevent assignment of devices (except
disk devices) by user jobs. MDA control prevents access by programs
using the DVURS. call.
To request a restricted device, give the MOUNT monitor command.
The
operator or GALAXY system can then send you a message granting or
refusing your request.
11-10

PROGRAM INPUT AND OUTPUT
To release a restricted device, give a DISMOUNT, DEASSIGN,
or FINISH
command,
or log off the system.
This returns all devices assigned to
your job to the monitor.
You can request unrestricted devices for use either by your job or by
a program. To request a device for your job, give the ASSIGN monitor
command or use the REASSI UUO.
You will receive a message confirming
or denying your request.
To request a device for use by a program,
use the OPEN, INIT, or FILOP. monitor call.
To release an unrestricted device from your job, give the DEASSIGN or
FINISH command,
or log off the system.
To release an unrestricted
device from your program, use the RELEAS, RESET, or EXIT monitor call.

11.4

MODES

You can use eleven data modes when performing I/O.
are:

These

data

modes

*Image Binary
*Binary
Image Dump
Dump Records
Dump

*ASCII
*8-bit ASCII
*ASCII Line
*Packed Image
*Byte
*Image

Data modes preceded by an asterisk (*) transmit data in buffered I/O
mode.
Packed Image mode transmits data in buffered I/O mode for
terminals only. The remaining data modes do not use the normal
buffering scheme.
These data modes are sometimes referred to as
unbuffered modes or, more commonly, dump I/O data modes.
All data transmissions are performed in either buffered I/O mode or
dump I/O mode. Your program specifies the mode of transmission in an
argument to the INIT, OPEN, FILOP., or SETSTS monitor call.
The data
modes are listed in Table 11-2, and every data mode that is applicable
to each device is described in the chapter describing the device.
Tab1e 11-2:

Data Modes (Bits 32-35 of the fi1e status word)

Code

Symbo1

Data Mode

App1icab1e Devices

. IOASC

ASCII

Disk,
terminal,
magnetic
tape,
DECtape, plotter, card punch, card
reader, line printer, paper tape
punch, paper tape reader

. IOASL

ASCII Line

Disk,
terminal,
magnetic
tape,
DECtape, plotter, card punch, card
reader, line printer, paper tape
punch, paper tape reader

.IOPIM

Packed Image

Terminal

. IOBYT

Byte

Magnetic tape, ANF-10 network task

. IOAS8

8-bit ASCII

Terminal, network line printer, PTY

11-11

PROGRAM INPUT AND OUTPUT
5

Reserved for DEC

6-7

Reserved for customer

.IOIMG

Disk,
terminal,
magnetic
tape,
DECtape,
plotter, card punch, card
reader, line printer,
paper tape
punch, paper tape reader

Image

Reserved for DEC

11-12

.IOIBN

Image binary

Disk, magnetic tape, line printer,
DECtape,
plotter, card punch, card
reader,
paper tape punch,
paper
tape reader

.IOBIN

Binary

Disk, magnetic tape, line printer,
DECtape,
plotter, card punch, card
reader,
paper tape punch,
paper
tape reader

.IOIDP

Image dump

Display

. IODPR

Dump record

Disk, magnetic tape, DECtape

. IODMP

Dump

Disk, magnetic tape, DECtape

11.5

DEFINING A COMMAND LIST

Image Dump, Dump Record, and Dump modes are nonbuffered I/O modes.
These modes use a
command list that specifies the area in your
allocated memory to be read or written.
The address of the command
list is specified in your program with either an IN or INPUT monitor
call for input or an OUT or OUTPUT monitor call for output.
The command list must exist in your program's low segment.
Take care
not to load the command list into the high segment.
Otherwise, your
program will be stopped when the IN, INPUT, OUT,
or OUTPUT call is
executed and the following message will be printed by the monitor:
?Address check for device device; UUO at user PC addr
Your program specifies the first word of the command list in a FILOP.,
IN,
INPUT,
OUT, or OUTPUT monitor call.
Only three types of entries
can appear in a command list.
These entries are:
o

An I/O instruction,

A GOTO instruction

A terminator,

in IOWD format

in the form of a zero word

11-12

PROGRAM INPUT AND OUTPUT

An IOWD instruction causes a speclfied number of words to be
transmitted to or from a specified location in your program.
Its
format is:
IOWD n~loc
The n specifies the number of words to be transmitted,
and loc
specIfies the location of the first word to be transmitted. After the
specified data has been transmitted,
the monitor finds the next
command at the location immediately following the IOWD in your
program. Note that the following are equivalent:
IOWD n,loc = XWD -n,loc-1
Note that every IOWD that transmits data to the disk writes a separate
record on the disk.
The GOTO command specifies the
format is:

command

executed.

Its

XWD O,y
The y specifies the location of the next command. A maximum of three
consecutive GOTOs are permitted in a command list. After the third
consecutive GOTO, your program must include an IOWD that transfers
data.
The zero word must be present in the command list to terminate the
list.
When the command list has been completely processed, the
monitor returns control to your program.
However,
if the monitor
encounters an illegal address while processing the command list, the
monitor stops your job and prints the following message on your
terminal:
?Illegal address in UUO at user PC addr
Below are some sample command lists that can be used for
to disk:
OUTPUT DISK, [IOWD 70,BUF1
IOWD 70,BUF2
Z]

dumping

I/O

;Transmit 70 words beginning at BUF1
;Transmit 70 words beginning at BUF2
;A zero word

Another example is:
OUTPUT DSK,ADDR1

ADDR1: IOWD 70,BUF1
IOWD 70,BUF2

;ADDR1 is address of command list

;Transmit 70 words beginning at BUF1
;Transmit 70 words beginning at BUF2
;A zero word

Below is an example of dump mode input:
TITLE
SUBTTL
SEARCH

HOME - Routine to read HOME block
HANLEY A. STRAPPMAN 6-27-83/HAS
UUOSYM

;AC'S
T1=1
T2=T1+1
P=17

; Temp
;Stack pointer

11-13

PROGRAM INPUT AND OUTPUT

;MISCL
HOMNAM==O
;SIXBIT/HOM/
HOMCOD==176
;Code number
iCode for HOME
CODHOM==707070
;Size of a disk block
BLKSIZ==200
; Channel
11==0
;Routine to read the HOME block
;T1 passes the structure name
;The HOME block is returned in BF
;Skip if successful
;Store str name
HOME::
MOVEM
T1,DEV+.OPDEV
OPEN
II,DEV
;Open str
POPJ
P,
iLOOKUP HOME.SYS
LOOKUP
II,FIL
POPJ
P,
;Read a block
LOOP:
IN
II,CMD
;Pick up code word
SKIPA T1,BF+HOMCOD
;EOF
POPJ
P,
;pick up name
MOVS
T2,BF+HOMNAM
;Right block?
T1,CODHOM
CAIN
CAIE
T2,'HOM'
JRST
LOOP
iNO, keep searching
;Release channel
RELEAS
II,
;Skip return
AOS
(P)
POPJ
P,
DEV:

.RBEXT
XWD
SIXBIT
SIXBIT
IOWD

1,4
/HOME/
/SYS/
BLKSIZ,BF

iI/O command list

BLKSIZ

;Buffer

FIL:

CMD:
BF: :

11.6

;OPEN block

. IODMP
BLOCK

BLOCK
END

iLOOKUP block

SELECTING A FILE

There are several monitor calls you can use to select a file
in your program:

for

use

To CREATE or WRITE a new file,
use the FILOP.
or ENTER
monitor call.
This enters the file name into the directory.
You can then (optionally) use a USETO monitor call to specify
a block number for file output.
Then use OUT or OUTPUT
monitor calls to write the file.

To DELETE an existing file, use the LOOKUP monitor call to
identify the file;
then use the RENAME monitor call with a
zero file name to delete the file.
If the program must read
the file before it is deleted, use the IN or INPUT monitor
calls before the RENAME call.

To READ a file, use the LOOKUP monitor call to identify the
file.
You can then
(optionally)
use the USETI call to
specify a block number within the file.
Read from the file
using the IN or INPUT monitor calls.

11-14

PROGRAM INPUT AND OUTPUT

11.7

To UPDATE a file, use the LOOKUP and ENTER monitor calls to
identify the file.' You can then (optionally) use the USETI
and USETO calls to specify block numbers within the file.
Use the IN or INPUT calls to read from the file, and the OUT
or OUTPUT calls to write into the file.

To CHANGE THE ATTRIBUTES of a file, use the LOOKUP and RENAME
monitor calls, giving the desired new attributes.

To RENAME a file, use the LOOKUP monitor call to identify the
file; then use the RENAME call to define its new name.

To APPEND TO a file, use the LOOKUP and ENTER monitor calls
on the same,I/O channel to identify the file.
Then skip over
the old part of the file by using a USE TO call to the end of
the file.
~he FILOP.
monitor call may also be used; it will
do all the skipping for you. Append new data to the file by
using the OUT or OUTPUT calls.

TO SUPERSEDE a file, use the ENTER monitor call to identify
the file.
Then write the new file by using OUT or OUTPUT
calls.

TRANSMITTING DATA

To transmit data to and from files, use the IN, INPUT, OUT, and OUTPUT
monitor calls. These calls can be used only for initialized channels.
You can select a block number within a file for input or output by
using the USETI and USETO monitor calls (disk and DECtape devices
only) .

11.7.1

Output (Writing a File)

The monitor controls I/O in response to monitor calls issued from your
program through which data may be passed between memory and disk. As
many as 80 (decimal) channels are available to each user.
Note that
Channels 20-117 (octal) can only be used with the FILOP. call.
The request to open a channel is made with the OPEN call.
proceed by issuing:

You

would

OPEN channo,OPNBLK
Where:

channo is the I/O channel number.
OPNBLK is the starting address of an argument list.
At the
location starting with OPNBLK, you must reserve three words.

In the first word, among other things, you must declare the mode of
data transmission. Data transmission is always in bytes and the mode
designates the byte size that is to be used.
Suppose,
for example,
that the first word of OPNBLK contains O. Data transmission is then
in 7-bit ASCII mode
(IO.ASC),
five characters to a word.
All
available data modes are listed in Section 11.4.
The second word, OPNBLK+l, contains the device name.
If you wish
do disk I/O, the name for the disk is DSK, entered in SIXBIT.

11-15

PROGRAM INPUT AND OUTPUT

The third word contains the addresses of the ring headers
(used only
in buffered mode).
The format of the buffer ring header is described
in Section 11.9.
The left half specifies the address of the output
ring header.
The right half specifies the address of the input ring
header.
For present purposes, we shall not perform input, so we set
the right half of OPNBLK+2 to zero.
Thus, our 3-word bLock looks as
follows:
OPNBLK: 0
SIXBIT
XWD

/DSK/
OUTB,O

The next monitor call to be issued in connection with your output is
the OUTBUF call.
The monitor responds to this call by reservlng a
block of memory locations.
The monitor transmits data in blocks, with
the size of each block depending on the destination device.
A block
of data on the disk contains 200 octal words. An area of memory is
used by the monitor to hold data until a full block is collected for
output to the disk.
Data is written to disk in multiples of 200-word
blocks.
When a program writes a partial block, the remainder of the
block is filled with zeros.
For directory devices, you must now specify the name of a file to
which your data is to be output.
For this, use the ENTER call, which
causes the monitor to store a directory entry for subsequent use.
The
ENTER call is formatted as:
ENTER
Where:

channo,entblock

entblock is the starting address of an argument list that you
set up for reference by the monitor when it executes the ENTER
call.

The argument block for the ENTER UUO is called the LOOKUP/ENTER/RENAME
block because the same type of block is used for output operations and
input operations.
The LOOKUP /ENTER/RENAME argument block can be gi ve'n
in either of two forms:
a four-word argument block (also called the
"short form"), and an extended argument list (also called the "long
form") .
These argument blocks are described in greater detail in
Section 11.13. For the purposes of this discussion, the short form of
the argument block is used in the following examples.
The first word of the LOOKUP/ENTER block contains the name to be
assigned to the file.
The second word of the argument block contains
the file extension.
Both the first and second words are SIXBIT names.
Words 3 and 4,
for present purposes, may be considered null.
The
four-word argument block for ENTER, assuming we choose "NAME" as the
file name and EXT as the file extension, looks as follows:
entblock:

SIXBIT/NAME/
SIXBIT/EXT/

a
a

11-16

PROGRAM INPUT AND OUTPUT
A flow diagram for the I/O sequence is shown in Figure 11-1.
OPEN
CALL
1
1

Data mode
Device name

--------------------------

1 output addr 1 input addr 1
OPEN
BLOCK
1
1

OUTBUF
CALL

.BFADR 1 Buffer address 1---\
I----~-----------I

1---+-\
1----------------1
1 1
.BFCTR 1 Byte count
1---+-+-\
Buffer Control
Block

1
1

/--1 Buffer address 1 .BFADR

.BFPTR 1 Byte pointer

------------------

INBUF
CALL

1 1----------------1
/-+--1 Byte pointer
1 .BFPTR
1 1 1----------------1
/-+-+--1 Byte count
1 .BFCTR

--------------------

1
1

-------------------

* I/O Status
.BFSTSI
* Buffer size"addr <------/

------------------

Buffer Control
Block

* Buffer address

• BFSTS

-------------------1

* Buffer size"addrl

\------->

Additional buffers

Additional buffers 1

* Word count

.BFCNT

-------------------1
* Word count
1
-------------------1

.BFCNT

1
1

<--------/

--------->

1<----------/

----------->1

-------------------1
1
-------------------1

1
1

* indicates Buffer Header Block
Figure 11-1:

Flow Diagram -- I/O Sequence

Here OPEN, OUTBUF, and INBUF are monitor calls while OUTB, OBPTR,
others are arbitrary symbols.

11-17

and

PROGRAM INPUT AND OUTPUT
The following example shows a program that writes the file NAME.EXT on
disk.
The program uses several monitor calls in addition to those
already discussed in this chapter,
including RESET,
CLOSE,
OUTSTR,
OUT, INCHWL, and EXIT.
TITLE
SUBTTL
SEARCH

WRITEl - Write TTY input to disk
HANLEY A. STRAPPMAN 6-27-83/HAS
UUOSYM

iAC'S
Tl=l
P=17

iTemp
iStack pointer

iMISCL
D==l
ESC==33
PDLSIZ==4
WRITEl: RESET
MOVE
P, [IOWD PDLSIZ,PDLl
OPEN
D,DEV
HALT
OUTBUF D,
D,FIL
ENTER
HALT
OUTSTR
[ASCIZ /DATA: /]
LOOP:
INCHWL Tl
CAIN
Tl,ESC
JRST
DONE
PUSHJ
P,CO
JRST
LOOP

iChannel number for disk output
iUse ESCAPE to mark EOF
iSize of POL
ilnitialize
; Set up POL
iOPEN device
iCan't
iThis UUO is optional
iENTER the file
iCan't
iPrompt the user
ilnput a char from the TTY
iESCAPE?
iYes
iOutput char to disk

DONE:

iCLOSE the disk file
iProblems during CLOSE?
iYes
iThis UUO is optional

CLOSE
STATZ
HALT
RELEAS
EXIT

D,
D,IO.ERR
D,

iRoutine to output a char to disk
CO:
SOSGE
OBUF+.BFCTR
JRST
C02
IDPB
Tl,OBUF+.BFPTR
POPJ
P,
C02:
OUT
0,
JRST CO
HALT

iGet another buffer
iTry again
iDisk error

DEV:

iOPEN block

OBUF:
FIL:

. IOASC
SIXBIT
XWD
BLOCK
.RBEXT

/DSK/
OBUF, 0
3

iRoom in buffer?
iNo

iYes,

store char

iRing header
iENTER block

PDL:

SIXBIT
SIXBIT
BLOCK
END

/NAME/
/EXT/
PDLSIZ
WRITEI

iPush-down list

Note that after OUTBUF and RESET there are no error returns.
If CLOSE
returns with an error, use GETSTS, STATO, and STATZ to ascertain the
error condition.
The program continues to fill the output buffer until, in this case,
an ESCape
(octal 33)
character appears.
The byte pointer count in
location OBCT in word 2 of the buffer control block maintains a
count
of the number of bytes remaining in the output buffer.
11-18

PROGRAM INPUT AND OUTPUT

The OUT monitor call causes the contents of the output buffer to be
transferred to the destination device and then clears the buffer
except for the buffer header block.

11.7.2

Input (Reading a File)

For input, as for output, you issue an OPEN call and designate a
channel over which data is to be passed.
Since you are performing
input, the third word of OPNBLK must contain, in its right halfword,
the location of the first word of the input buffer control block in a
manner analogous to output.
For a directory device, the LOOKUP monitor call is then invoked to
find the file that is to be read.
The format of the LOOKUP call is:
LOOKUP
channo,entblock
error return
normal return
Where:

entblock is the address of an argument list that specifies the
file.
This is the same type of argument list as that used for
the ENTER ·call. Note, however, that separate argument lists
should be defined for ENTER and LOOKUP calls, because it is
possible for the data in the argument block to be changed by
the action of these calls.

The following is an example of a program that reads a file:
TITLE
SUBTTL
SEARCH

READI - Type out a disk file
HANLEY A. STRAPPMAN 6-27-83/HAS
UUOSYM

iAC'S
Tl=l
P=17

iTemp
iStack pointer

D==l
PDLSIZ==4

iChannel number for disk
iSize of PDL

iMISCL

ilnitialize
RESET
P, [IOWD PDLSIZ,PDL]iSet up PDL
MOVE
D,DEV
;OPEN device
OPEN
HALT
;Can't
;This UUO is optional
INBUF
D,
;LOOKUP the file
LOOKUP D,FIL
HALT
iCan't
PUSHJ
P,CI
i1nput a char from disk
LOOP:
;EOF
EXIT
;Output char to TTY
OUTCHR Tl
JRST
LOOP
;Routine to input a char from disk
iThis routine returns noskip if EOF, but otherwise skips
CI:
SOSGE
IBUF+.BFCTR
iMore chars in buffer?
JRST
CI2
;No
ILDB
Tl,IBUF+.BFPTR
iYes, get one
JUMPE
Tl,CI
ilgnore nulls
AOS
(P)
iSkip return
POPJ
P,

READI :

11-19

PROGRAM INPUT AND OUTPUT
CI2:

DEV:
IBUF:
FIL:

PDL:

IN
JRST
STATZ
HALT
POPJ
. IOASC
SIXBIT
IBUF
BLOCK
.RBEXT
0
SIXBIT
SIXBIT
BLOCK
END

D,
CI
D,IO.ERR
P,

iGet another buffer
;Try again
iError or just EOF?
iDisk error
;EOF
;OPEN block

/DSK/
3

;Ring header
;LOOKUP block

/NAME/
/EXT/
PDLSIZ
READ 1

;Push-down list

After the LOOKUP, issue an IN monitor call to pass data on the
designated channel to the input buffer, thus reading the file.
Note
that, as with the OUT monitor call, the normal return for IN is the
suc~eeding
line with the error return located in the second line
following the IN.
Each IN call rebds into the buffer one disk block.
Subsequent IN
calls read sequential blocks starting with the first block in the
file.
The IN call differs from the OUT call in that each issue of an
IN call, including the first in a program, fills a buffer with data as
long as there is data left in the file being read.
If there is no
more data in the file being read, IN takes the error (skip) return.

11.7.3

Writing a File Using FILOP.

The FILOP.
UUO can be used in place of the OPEN, OUTBUF,
INBUF,
and
other monitor calls.
It performs functions to delete, rename, and
append to a file that has been defined in a LOOKUP/ENTER/RENAME
argument block.
Refer to Chapter 22 for a complete discussion of the
FILOP.
call.
The following example shows a write operation using FILOP.:
TITLE
SUBTTL
SEARCH

WRITE2 - Write TTY input to disk
HANLEY A. STRAPPMAN 6-27-83/HAS
UUOSYM

;AC'S
Tl=1
T2=Tl+l
P=17

; Temp
;Stack pointer

ESC==33
PDLSIZ==4

;Use ESCAPE to mark EOF
;Size of PDL

;MISCL

WRITE2: RESET
MOVE
MOVE
FILOP.
HALT
MOVST
AND
MOVEM
OUTSTR

;Initialize
P, [IOWD PDLSIZ,PDL];Set up PDL
Tl, [XWD FLOPL,FLOP];ENTER the file
Tl,
;Can't
Tl, (FO. CHN)
;Isolate chan number
Tl,FLOP+.FOFNC
Tl,CHAN+.FOFNC
[ASCIZ /DATA: /] ;Prompt the user
11-20

PROGRAM INPUT AND OUTPUT

LOOP:

INCHWL
CAIN
JRST
PUSHJ
JRST

T1
T1,ESC
DONE
P,CO
LOOP

;Input a char from the TTY
; ESCAPE?
;Yes
;Output char to disk

DONE:

MOVE I
HRRM
MOVE
FILOP.
HALT
EXIT

T1, .FOCLS
T1,CHAN+.FOFNC
T1, [XWD 1,CHAN]
T1,

;Function code
;CLOSE the file
;Problems during CLOSE

;Routine to output a char to disk
SOSGE
OBUF+.BFCTR
;Room in buffer?
JRST
C02
;No
IDPB
T1,OBUF+.BFPTR
;Yes, store char
POPJ
P,
C02:
MOVE I
T2, . FOOUT
;Function code
HRRM
T2,CHAN+.FOFNC
MOVE
T2, [XWD 1,CHAN]
;Output the buffer
FILOP.
T2,
;Disk error
HALT
;Try again
JRST
CO

co:

FLOP:

FO.ASC+.FOWRT
. IOASC
SIXBIT /DSK/
XWD
OBUF, 0
XWD
-1,0
FIL

;Assign channel, write file

;Default number of buffers

CHAN:
OBUF:
FIL:

PDL:

11.7.4

FLOPL==.-FLOP
BLOCK
1
BLOCK
3
.RBEXT

;Size of block
;Channel number
;Ring header
;ENTER block

SIXBIT
SIXBIT
BLOCK
END

;Push-down list

/NAME/
/EXT/
PDLSIZ
WRITE2

Modifying Files (Update Mode)

To modify an existing file, you must be in update mode.
As with
writing and reading a file, you must first OPEN the channel. You then
issue a LOOKUP call and then an ENTER call to the same file,
in that
order.
If you issue an ENTER only, to a file already on disk, the
monitor writes a new file.
When the file is CLOSED, the old version
of the file is deleted from the disk with the new file superseding the
old file.
Note that to read from one file and write to another,
two
OPENs referencing two different channels must be used.
LOOKUP and ENTER both reference blocks of identical format;
however,
the monitor alters the contents of the block when it executes either
of these calls.
Thus, after a LOOKUP call, the block should usually
not be used by an ENTER call. Refer to Section 11.13.1 and 11.13.2
for more information.

11-21

PROGRAM INPUT AND OUTPUT
The monitor maintains pointers,
one for each channel in
use,
designating the block of the file being referenced.
You set the
pointer on a channel for input or output by using the USETI monitor
call (for input) or the USE TO monitor call (for output). After LOOKUP
and ENTER have been issued for a given file, input and output may be
performed on the same channel but there must be two separate buffer
header blocks.
To reference the first block of data in the file,
the
LOOKUP call sets the input block pointer to 1 and the ENTER call sets
the output block pointer to 1. Each successive IN call causes the
input block pointer to be incremented by 1 so the succeeding block
will be read by the next IN call.
This continues block by block until
there are no more blocks left, at which time the EOF bit in the I/O
status word is set.
The IN attempting to fill an unreserved block
will fail, taking the skip return.
Execution of a subsequent OUT call causes the output block pointer to
be incremented by 1, which prepares the next OUT call to write the
next block of the file.

11.7.5

Block Pointer Positioning

You can control the setting of the input and output data block
pointers instead of having them advanced one block at a time with the
IN and OUT calls. Using the USETI (User Set Input)
and USETO
(User
Set Output)
calls,
the pointers may be set to any ~elected block.
Note that the FILOP. and SUSET. calls can also
perform
these
functions.
The following instruction sets the input block pointer to
point to the sixth block from the beginning of the file that is open
on channel CHAN:
USETI

CHAN,6

No input is performed by the USETI call.
It simply sets the pointer
for a subsequent IN call to read the desired block. A program using
the USETO call should have only one buffer for input and output,
to
simplify keeping track of the block being referenced.
Buffered I/O is
not recommended for programs doing random access with USETI/USETO.
If a USETI designates a block number larger than that of the last
block in the file, the subsequent IN call fails.
If a USETI is then
issued to an existing bLock, the EOF bit is cleared by the monitor and
input is then again enabled.
Issuing the call USE TO CHAN,n with n greater than the number of blocks
in the file causes the monitor to allocate any intervening blocks as
part of the file.
For example, if a file contains 10 octal blocks,
the call USE TO CHAN, 60 followed by the callOUT CHAN, creates a file
of 60 octal blocks; the new data is written into the last block and
blocks 11-57 (octal) contain zeros.
The USETI and USE TO monitor calls do not actually perform any input or
output.
They change the pointers of the current pbsition of the file.
Note that each INPUT and OUTPUT monitor call in your program advances
the file.
Your program can rewrite or reread the same block by
issuing a USETI or USETO before issuing an INPUT or OUTPUT.
When a
USETI or USETO is executed, the monitor writes all output buffers that
your program filled before it changes the pointer to the current
position in the file.

11-22

PROGRAM INPUT AND OUTPUT

Because the monitor reads or writes as many buffers as it can when an
INPUT or OUTPUT monitor call is executed, it is difficult for your
program to determine which buffer the monitor is processing when a
USETI or USE TO is performed.
Therefore, the INPUT or OUTPUT your
program issues following the USETI
or
USETO
might
not
be
reading/writing the buffer that contains the specified block number.
A buffer ring consisting of one buffer will read/write the desired
block number because the device must stop after each INPUT or OUTPUT.
A device having a multiple buffer ring can be stopped after each
bufferful of data when your program sets Bit 30 (IO.SYN) in the I/O
status word.
This bit can be set with an INIT,
OPEN,
FILOP.,
or
SETSTS monitor call.
A subsequent USETI or USETO will then specify
the correct buffer to be used on the next INPUT or OUTPUT.
If the file protection code does not prevent your job from accessing a
file, your program can append data to the last block of an append-only
file.
You can append data to the file by issuing a USETO to the last
block of the file followed by a dummy OUTPUT.
The monitor reads the
block into the buffer, copies words n+1 through 200 from your buffer
into the monitor's buffer,
and rewrites the block.
On an INBUF
monitor call, the monitor sets the byte count.
Your program can
obtain the current length of the file and the last block by examining
the .RBSIZ word of the LOOKUP/ENTER/RENAME block.
It is not necessary
that your program read the last block of the file before appending to
it. Any data that 'was in the file will not be changed.
When your program appends to the end of a file with append-only
protection (protection code 4), the monitor sets the IO.BKT bit in the
file status word and performs no output when the following occurs:
o

Any block before the last block is written.

The last block of the file already contains 200 octal words.

Fewer words are written than the current size of the block.

If the last block of the file i~ output, the size of the last block
becomes 200 (octal) and cannot be appended to, but the entire file can
be appended to by creating new blocks.

11.7.6

Super USETI/USETO

The preferred
method
of
performing
the
functions
of
the
super-USETI/USETO is using the SUSET. monitor call. When using disk
packs, there may be a need for your program to read and write data
without using a directory hierarchy (such as, for testing a pack in a
timesharing environment or for a privileged recovery on any file
structure) .
You must be able to specify individual blocks on a file
structure and/or unit without referring to a file.
Super-USETI/USETO
(or SUSET.)
can specify logical blocks within a file structure or
physical blocks within a unit.
Under certain conditions,
USETI and
USETO can be used to specify these logical blocks. When the following
conditions are true, USETI and USE TO reference logical blocks numbers
in a file structure, instead of relative blocks within a file:
o

When the channel has been initialized with a
name, such as DSKB.

When no file has been opened on the channel specified in the
AC field (that is, no LOOKUP or ENTER has been performed) .

11-23

file

structure

PROGRAM INPUT AND OUTPUT

unit referencing occurs when both of the following are true:
o

The channel has been initialized with a physical unit name
(such as, DPA2) or a logical unit name (such as, DSKC3).

A file has not been opened on the channel specified in the ac
field
(that is,
no LOOKUP or ENTER has been performed) .
Super-USETI and super-USETO accept their arguments in the
contents of the effective address, because it is possible to
have file structures with more than 377777 octal blocks.

SUSET. requires either [1,2] or JACCT privileges, and if you attempt
to use it without sufficient privileges, the IO.IMP and IO.BKT bits
will be set in the I/O status word.
output function writes headers and data formats.
Only the output
immediately following the USETO writes the format.
Therefore, to
write two IONDs of format, the following sequence must be used:

USETO
OUTPUT
USETO
OUTPUT
INPUT does a read header and data operation if the unit is an RP04
or an RP06, and it uses an ordinary read operation if the unit is an
RP02 or RP03.

11.8

RECOVERING FROM ERRORS

The OPEN monitor call can fail (taking the
device is not available to your job.

non-skip

return)

the

If the ENTER, LOOKUP, or RENAME call fails, the error code is stored
in the LOOKUP/ENTER/RENAME block.
This is described in greater detail
in Section 11.13.
The error codes that can be returned are listed in
Section 11.14.
If the IN/INPUT or OUT/OUTPUT call fails, the error code is indicated
in the I/O status word (also known as the file status word) .
Each channel has an associated I/O status word maintained by the
monitor.
The setting of certain bits in the I/O status word indicates
any errors that may have occurred on the channel.
The I/O status word
is stored in the same data block with the file by the monitor after
you specify the settings of some of the I/O status bits and the data
mode in your argument block to the INIT, OPEN, or FILOP.
call to open
the I/O channel.
You can set I/O status bits that control the data
transmission.
The data mode that you specify for the channel will
also be stored in the I/O status word.
The I/O status word appears as the right half-word returned by the
GETSTS call.
Bits 18 through 29 contain the I/O status bits.
The I/O
status bits are usually set by the monitor to indicate the state of
the file after a transfer.
The I/O error bits are Bits 18 through 22
(IO.ERR).
Your program can set these bits using the SETSTS call.
However, the I/O status bits returned by the monitor are different for
each type of device.
They are described, therefore, in the chapters
describing specific types of devices.
The data mode is stored in the I/O status word in Bits 30 through
The data modes are described in Section 11.4.
11-24

35.

PROGRAM INPUT AND OUTPUT

The EOF (end-of-file) bit (Bit 22) is set to 1 if an IN call tries to
read past the EOF.
You can use the following instruction to check the
status of error bits in the I/O status word:
STATO

CHAN,x

The STATO call causes a skip if any of the bits in the I/O status word
for the channel CHAN that are masked by the right half word value x
are set to 1.
The error return for the IN call should therefore
contain the following code:
STATO
JRST

CHAN,IO.EOF
ERROR

;Not end-of-file

Before continuing as before, the remaining error bits of the I/O
status word could also be checked using STATO or STATZ monitor calls
Extended error codes are used to extend the limited set of error bits
allowed in the I/O status word.
On an extended error, all of the
error bits in IO.ERR are set.
If your program encounters such an
error, it should proceed to use the .DFRES function of the DEVOP. call
to determine the exact nature of the error.

11.9

USING BUFFERED I/O

Buffered I/O allows the monitor to overlap I/O transfers with other
program operations.
The buffered data modes are ASCII, ASCII Line,
Packed Image, Byte, Image, Image Binary, and Binary.
These modes use
a buffer ring for both input and output.
Your program specifies the location of a buffer control block,
which
the monitor sets up.
This buffer control block contains pointers to
the current buffer and the current byte in the buffer. A buffer ring
structure is shown in Figure 11-2.
A program using buffered I/O can become larger and larger because of
repeated INBUF and OUTBUF monitor calls.
Before an OPEN call, the
current pointers to the buffers should be saved from the buffer ring
header. After the OPEN call, the pointers may be restored.
Growth of
the user area may be thus avoided by saving and restoring Word 0 of
the buffer ring header before and after an OPEN call, or by setting
.JBFF in the job data area to an appropriate value.
The buffer control block is either three or four words long.
The
fourth word is present only for MPX-controlled devices.
When the
buffer ring is initialized, the buffer control block points to the
first buffer in the buffer ring.
Thereafter, the buffer control block
points to the current buffer in the buffer ring.
The buffers are
linked to form an endless ring.
The buffer header block of each
buffer points to the next buffer in the ring.
The monitor sets up and
maintains the buffer header blocks.
Your program need only specify the location of the buffer control
block.
This specification is made in an OPEN, INIT, or FILOP. monitor
call.
However, if your program should decide at a later time to
change the location of the ring control block, it can issue the
MVHDR. monitor call.
Your program can specify the number of buffers to be contained in a
buffer ring, or the monitor will set up the default number of buffers.
Figure 11-2 shows a buffer ring containing a buffer control block
three buffers.
11-25

and

PROGRAM INPUT AND OUTPUT

Buffer \
Control <
Block
I
\

1
I.
1-----------------1
1
1 . <--- Points to Current Buffer
1-----------------1
1

1-----------------1
\

1----------------------\
1

\
\

1
1

-------------------

· 1 1--------+--------1

->1
1 B
1\
1--------+--------1 \
1
1 1
1-----------------1 1
1

Buffer A

-------------------

IA
1

1
1

1---------------------1
1

-------------------

1
1

· 1 1--------+--------1

> F
\ F

->1
1 C
1\
1--------+--------1 \
1
1 1
1-----------------1 1
Buffer B
1 1
1
-------------------

1
1

R
I
1 N
1

-------------------

1 1
1
· 1 1--------+--------1
->1
1 A
+--1

1-----------------1
1

Figure 11-2:

Buffer C

1--------+--------1
1

E
R

1---------------------1
1

I U

The Buffer Structure

Normally, buffers are filled and emptied in the order in which they
are placed in the buffer ring.
However, your program can specify a
deviation from this normal buffering scheme.
To deviate from the
normal scheme, your program specifies the buffer's address in the IN,
INPUT, OUT, or OUTPUT monitor call.
Buffered I/O is performed in the same manner for all devices except
those connected to an MPX channel. For more information on buffered
I/o, refer to Sections 11.9.3 through 11.9.7.
Note that when a buffer ring is initialized, the monitor places the
buffers at the first free location, whose address is contained in
.JBFF in the job data area.
After placement of the buffers,
the
monitor updates
.JBFF to contain the first free location after the
buffers.
Your program must use FILOP. when placing buffers in a
non-zero section.
.JBFF is available for programs running in Section
o only.

11-26

PROGRAM INPUT AND OUTPUT
In buffered I/O, buffers allow overlap of a program's execution and
I/O transfers.
While your program processes data in one buffer, the
monitor fills or empties another buffer.
The I/O transfer also
overlaps the processing of other user jobs running on the same system.
Normally, the monitor sets up buffers at the end of your low segment,
unless you tell it otherwise.
However, your program may also set up
the buffers. An arbitrary number of buffers may be used for a given
device or file.
These buffers are linked to form a BUFFER RING
structure.
The first three words in each buffer are not used to hold data.
Instead,
they hold information pertaining to the buffer.
This
information includes:
the address of the next buffer in the buffer
ring,
status bits concerning the I/O device being used, and a bit
indicating whether the buffer has been filled.
These three words are
referred to as the BUFFER HEADER and are not part of the data on the
device.
Associated with every buffer ring is another group of three words
(four for MPX-controlled devices).
These three words are called a
BUFFER CONTROL BLOCK.
The buffer control block contains information
that is examined to determine whether your program can access the
buffers in the ring.
Your program must reserve space for the buffer
control block,
and your program must inform the monitor of its
location.
Buffer rings, buffer headers, and buffer control blocks are
described in detail in the following sections.
Typically, the monitor sets information in the buffer control block
every time your program issues a monitor call that requests that a new
buffer be made available to your program.
As your program works
through a buffer, your program usually increments the byte pointer and
decrements the byte counter.
Each time the counter expires,
your
program can execute another monitor call asking for another buffer.
To perform buffered input/output,
following monitor calls:

your

program

should

RESET initializes your program.

INIT, FILOP., and OPEN initialize devices.

INBUF,
OUTBUF,
(optional) .

LOOKUP, ENTER, FILOP., USETI, USETO,
file and a block within a file.

IN,

CLOSE and FILOP. close a file.

RELEASE and FILOP. terminate device activity.

RESET and RESDV. forcibly terminate device activity.

EXIT terminates your program.

and

FILOP.,

initialize
and

the

buffer ring

SUSET.

select

INPUT, OUTPUT, FILOP., and OUT transmit data.

11-27

use

PROGRAM INPUT AND OUTPUT
11.9.1

The INBUF and OUTBUF Monitor Calls

The INBUF and OUTBUF monitor calls set up an input and output buffer
ring with a specified number of buffers, starting at the location
pointed to by .JBFF. Alternatively,
the INBUF and OUTBUF monitor
calls can be left out of your program; in which case, the monitor sets
up one of the following:
o

A ring of two buffers for non-disk devices.

Or a ring of n buffers for disk devices.
You can set the
value of N by using the SET DEFAULT BUFFERS monitor command
or corresponding SETUUO monitpr call.
If no default is
specified,
the
monitor
uses
the system default,
an
installation parameter that can be defined with MONGEN
(usually 6) .

The calling sequences for the INBUF and OUTBUF monitor
follows:
INBUF channo,n
return
Where:

calls

are

OUTBUF channo,n
return

channo is the channel number associated with the device.
can initialize an I/O channel using OPEN, INIT, or FILOP.

You

If n is
n specifies the number of buffers in the buffer ring.
zero or omitted,
the monitor sets up the default number of
buffers.
FILOP. may be used to specify the number of input
and/or output buffers.

11.9.2

The Buffer Control Block

The buffer control block is initialized when your program executes its
first OPEN,
INIT,
or FILOP. 'monitor call specifying a buffered I/O
data mode.
Your program specifies the location of this control block
in either the OPEN, INIT, or FILOP. monitor call, and the monitor sets
up its contents.
You can change this address,
and therefore change
the control block, using the MVHDR. monitor call.
This call changes
the monitor pointer to a buffer control block from one address to
another.
The new control block is at the new address; the monitor
does not "move" the control block, but merely looks for it in the new
place you specified with the MVHDR.
call.
The format of the buffer
control block is shown below:

a I

.BFADR
.BFPTR
.BFCTR
.BFUDX

17 18

--------+-------+-------+---------------------1 U 1 XII
pointer
1
1-------+-------+-------+---------------------1
1
byte pointer
1
1---------------------------------------------1
1

byte counter

(MPX only) Universal Device Index

11-28

Word 1

Word 2

Word 3

1---------------------------------------------1
1

Word a

PROGRAM INPUT,AND OUTPUT
The information in the buffer control block is described below.
In Word 0 the symbol U, Bit 0, (BF.VBR) indicates the use bit,
which
is set if there has been any input to or output from the buffer
ring.

x (BF.IBC), Bit 1 is set to inhibit the clearing of output
buffers.
To enforce this, your program must set this bit as well
as UU.IBC in the OPEN argument block.
pointer (.BFADR) is the address of the current buffer in the
buffer ring.
This half-word points to the second word (Word 1)
of the current buffer.
In Word 1 the byte pointer (.BFPTR) points to the byte within
current buffer that contains the next input or output data.
byte size is determined by the data mode.

the
The

In Word 2 the byte counter (.BFCTR) is the count of the number of
bytes remaining in the current buffer on input and the number of
bytes for which there is still room on output.
In Word 3 the Universal Device Index' (.BFUDX)
is present only for
devices connected to an MPX channel. This word identifies which
of the devices connected to the MPX channel is the current device
(that is, the device to which the current buffer applies).
Your
program supplies this word in the buffer control block on output.
The monitor supplies it on input.
Selective input, therefore, is
not possible on MPX-controlled channels.
A user program cannot use the same buffer control block for both input
and output.
Also, the same buffer control block cannot be used for
more than one I/O device at a time (except for MPX-controlled devices,
refer to Section 11.9.7). Therefore, users cannot use the same buffer
control block for simultaneous input and output, and only one buffer
ring can be associated with each buffer control block.

11.9.3

The Buffer Header B10ck

There is one buffer header block for each buffer in a buffer ring.
The monitor maintains the contents of the buffer header blocks, and
all buffer linkages.
The format of a buffer header block is:

.BFSTS
.BFHDR
.BFCNT

17 18

-----------------------+---------------------1
1
I/O status
1 Word-l
1-----+----------------1---------------------1
1x
1 size
1 addr next buffer
1 Word 0
1-----+----------------1---------------------1
1 bookkeeping word
1
word count
1 Word 1

-----------------------+----------------------

11-29

PROGRAM INPUT AND OUTPUT

(Note that UUOSYM.MAC defines .BFSTS as 0.) The information maintained
by the monitor in the buffer header block is described below.
In Word 0, the I/O status (.BFSTS) contains the status of the file
This
when the -monitor advances to the next buffer in the ring.
word contains the errors received while working with the file.
User programs should not be written to reference this word;
instead, use the GETSTS, STATO, or STATZ monitor calls.
In Word 1, x (BF.IOU) is the buffer's use bit.
This bit is a flag
If the
that Indicates that the buffer contains active data.
buffer contains data, the bit is set.
If the buffer is empty,
this bit is off.
BF.IOU is set by the monitor when the buffer is full on output or
has been filled on input (that is, if the use bit = 0, the buffer
is available to the filler, if it is 1, the buffer is available
to the emptier).
The setting and clearing of the buffer's use
bit prevents the monitor and your program from interfering with
each other by attempting to use the same buffer simultaneously.
Your program does not advance to the next buffer; the monitor
advances the buffer ring on the execution of certain monitor
calls. Note that the monitor sets and clears the buffer's use
bit; your program should never change its state.
size (BF.SIZ) is the size, in words, of the data area in the
buffer, plus one.
The size of the data area is dependent on the
type of device being used.

addr next buffer (BF.NBA) is the address of the next buffer in
the ring.
(This address is the second word of the next buffer.)
In Word 2, bookkeeping word is reserved for bookkeeping purposes; the
exact purpose depends on the device used and the data mode
specified.
When a device connected to an MPX channel is
specified,
this
word contains the Universal Device Index
associated with that device. When using DECtape, it is the next
block number on the tape for the next record of the file.
word count (.BFCNT) is reserved for a count of the number of
words that actually contain data. When using byte mode, this
value is equal to the number of bytes that actually contain data.

11.9.4

Using Buffered Input

Using buffered input can speed your program's execution.
In buffered
input,
the monitor sometimes fills the buffers for your program while
the program is performing other tasks; thus buffers can be filled
ahead and be ready when the program requests more data.
Figure 11-3 is a flowchart showing the monitor's handling of
input.

11-30

buffered

PROGRAM INPUT AND OUTPUT

start
I
V

Has Input Already Been
Has Buffer Ring
Set Up
Done for This Device? --NO--> Been Set Up? ---NO--> Buffer Ring
I
I
I
YES
I
I

I
I

Is Use Bit Set
/---YES--- for Next Buffer?
I
NO
V

Call Device Service
Routine to Start the
Device

I
I
I
I
I
I

YES
I
I
I
V

<-------------------------/

I
V

Non-Blocking ---- YES --------> Return to User,
I
Error Return
NO
V

Put;. Job in I/O wait
I

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

The Device Service
I
Routine Takes the Job
I
Out of wait after
I
Buffer is Filled.
If
I
IO.SYN is Off, Service
I
Routine Continues to
:----->1
Fill Subsequent Buffers:
I
if They Are Available
I
•. . ••••••. . •. ••••••. •••••.
I
1
V
I
Is Use Bit Set
I
in Next Buffer? ----- NO -----> Error or
1
I
EOF
1
YES
I
V
I
Set Up Buffer Control Block
I
1) Address of New Buffer
Give Normal
\------------------>2) Byte Pointer to Data
3) Count of Bytes in Buffer
Return to
4) .BFUDX if MPX device --------> User
Figure 11-3:

Flowchart for Buffered Input

To use buffered input, your program should:
1.

Use the OPEN,
INIT,
or FILOP. monitor call to specify
buffered mode,
a device,
and the location of the buffer
control block for the input file.

Optionally, use the INBUF or FILOP. monitor call
the number of buffers in the ring.

Use IN or INPUT monitor calls to read from the file.

11-31

specify

PROGRAM INPUT AND OUTPUT
There are four ways to do buffered input:
o

In synchronous mode, blocking and non-blocking I/O.

In asynchronous mode
I/O.

(default),

blocking

and

non-blocking

For all of these methods, your program requests the next bufferful
data by using an IN, INPUT, or FILOP.
monitor call.

11.9.4.1 Normal Buffered Input - In normal
(asynchronous blocking)
buffered input, the monitor takes the following actions on each IN or
INPUT monitor call:
1.

Checks the use bit to determine whether to put your
job in
wait state.
When the data is ready, the monitor advances to
that buffer and gives a success or error return based on the
contents .BFSTS in that buffer.

Advances the buffer ring pointer to the next buffer.

Updates the buffer control block, including the pointer to
the current buffer,
the byte pointer to the data, and the
byte count.

Returns control to your program.

Note that if the next buffe~ is not ready, your job is put into a wait
state until the buffer 1S ready.
The advantage of using buffered
input is that after the monitor returns control to your program,
the
monitor continues to fill empty buffers in the ring.
The monitor does
this while your program is running.
Therefore,
subsequent INs or
INPUTs in your program have a chance of finding the next buffer ready
and avoiding the need to be put into the wait state.

11.9.4.2 Synchronous Buffered Input - You may want to prevent the
monitor from filling buffers ahead, perhaps because error recovery
procedures are in progress or you are doing USETIs to specify exact
blocks.
This is called synchronous buffered input.
To use synchronous buffered input, use the SETSTS monitor call to set
the IO.SYN bit in the I/O status word for the device.
Then, when the
recovery procedure is completed, you can clear this bit to resume
filling ahead.
The monitor may be filling buffers ahead of your
program.
After using SETSTS, your program should check the buffer use
bit to determine the current buffer.
You can also suspend your program's execution temporarily
(for
example, to recover from an I/O error) by using the WAIT monitor call.
This call causes your program's execution to wait for completion of
any I/O operations that are in progress on a given channel.

11-32

PROGRAM INPUT AND OUTPUT
11.9.4.3 Nonblocking Buffered Input - You may want the monitor to
continue executing your program, rather than place your job in a wait
state, if the next needed buffer is not ready.
For example,
you may
want your program to service several devices.
This is called
nonblocking buffered input.

To use nonblocking buffered i~put,
your program must set the bit
UU.AIO
(asynchronous I/O)
1n the first word of the OPEN argument
block.
Your program must use the IN or FILOP.
monitor call (NOT the
INPUT monitor call) for nonblocking buffered input.
In nonblocking buffered input mode, the monitor takes the error return
(with no error code in the I/O status word) from an IN monitor call if
the buffer is not ready.
Therefore your program can determine whether
the input was done, and can proceed appropriately.
To determine whether error bits are set on the return from an IN
monitor call,
use the GETSTS, STATZ, FILOP., or STATO monitor call.
If no error bits are set, then there are no buffers containing data
ready and your program can perform other operations not associated
with the same device (such as computations or I/O for other devices) .
Your program can periodically retry the IN call, to see if a buffer is
ready.
Your program can also be written to respond to an input-done
software interrupt when a buffer is ready (see Chapter 7), or to wake
from a hibernating state when the buffer is ready (see the HIBER UUO
in Chapter 22) .

11.9.5

Using Buffered Output

Using buffered output can speed your program's execution.
In buffered
output,
the monitor writes the buffer's data as soon as the buffer is
filled.
Thus your program need not determine when a buffer is ready
for output.
Figure 11-4 is a flowchart showing the monitor's handling of
output.

11-33

buffered

PROGRAM INPUT AND OUTPUT
Start
I
V

Has Buffer Ring
Set Up
Has Output Already Been
Done for This Device? --NO--> Been Set Up? ---NO--> Buffer Ring
1
I
I
YES
1
1
V

Is Use Bit Set
1
/---NO---- for Next Buffer?
YES
I
I
I
I
YES
1
I
V
I
I
Call Device Service
V
I
Routine to Start the
I
Device
I
I
I
V
I
Non-Blocking ---- YES --------> Return to User,
I
I
Error Return
I
NO
I
V
I
Put Job in I/O Wait
I
I
...........................
I
The Device Service
1
Routine Takes the Job
I
Out of Wait after Buffer:
1
is Emptied.
If IO.SYN
I
is Off, Service Routine
1
Continues to Empty
:--->1
Subsequent Buffers if
I
They Are Available
I

1
1
I
1
1

<---------------------------/

• • • '. • . • • • • • . • • . • • . • • • • • • • • •

I
V
I
Is Use Bit Set
i
in Next Buffer? ----- YES -----> Error or
I
I
EOF
I
NO
I
V
1
Set Up Ring Control Block
I
1) Address of New Buffer
\------------------>2) Byte Pointer to Data Area
Give Normal
3) Count of Bytes in Buffer
Return to
4) .BFUDX if MPX device ---------> User
Figure 11-4:

Flowchart for Buffered Output

11-34

PROGRAM INPUT AND OUTPUT

To use buffered output, your program should:
1.

Use the OPEN,
INIT,
or FILOP. monitor call to specify
buffered mode,
a device,
and the location of the buffer
control block for the output file.

Optionally, use the OUTBUF or FILOP. monitor call to
the number of buffers in the ring.

Issue a "dununy" OUT or OUTPUT monitor call to initialize the
buffer ring.
This is normally transparent to the program and
does not require special coding.

Use OUT or OUTPUT monitor calls to write to the file.

specify

If the BF.IOU bit in the buffer control block and the IO.UWC bit in
the I/O status word are both cleared, the monitor assumes that the
current buffer is empty.
The monitor then keeps track of the number
of bytes in the buffer as it is filled.
This value is stored in the
.BFCTR word of the buffer control block.
If the IO.UWC bit in the I/O status word is set, the monitor assumes
that your program has already computed the number of words in the
buffer.
If you are ~n .IOBYT mode,
the monitor assumes that your
program has already computed the number of bytes in the buffer.
The
monitor then sets the BF.IOU (use) bit in the buffer control block and
starts the device needed to empty the buffer.

11.9.5.1 Normal Buffered Output - In normal buffered output,
the
monitor takes the following actions on each OUT, OUTPUT, or FILOP.
output monitor call:
1.

Checks to make sure the next buffer in the ring is empty.
If
not,
the monitor places the job in a wait state and starts
the device needed to empty the buffer.

Advances the buffer ring pointer to the next buffer.

Updates the buffer control block, including the pointer to
the current buffer,
the byte pointer to the data, and the
item byte count.

Returns control to your program.

Note that if the next buffer is not ready, your job is put into a wait
state.

11.9.5.2 Synchronous Buffered Output - You may want to prevent the
monitor from filling buffers ahead, perhaps because error recovery
procedures are in progress.
This is called synchronous buffered
output.
To use synchronous buffered output, use the SETSTS monitor call to set
the IO.SYN bit in the I/O status word for the device.
Then, when the
recovery procedure is completed, you can clear this bit to resume
buffering ahead.
You can also suspend your program's execution temporarily
(for
example, to recover from an I/O error) by using the WAIT monitor call.
This call causes your program's execution to wait for completion of
any I/O o~erations that are in progress on a given channel.
11-35

PROGRAM INPUT AND OUTPUT

11.9.5.3 Nonblocking Buffered Output - You may want the monitor to
continue executing your program (rather than place your job in a wait
state) even if the next needed buffer is not ready.
For example,
you
may want your program to be allowed to service other devices.
This is
called nonblocking buffered output.
To use nonblocking buffered output, your program must set the bit
UU.AIO in the first word of the OPEN argument block.
Your program
must use the OUT or FILOP. monitor call (and NOT the OUTPUT monitor
call) for nonblocking buffered output.
In nonblocking buffered output mode,
the monitor takes the error
return
(with no error code in the I/O status word) from an OUT or
FILOP. monitor call if the buffer is not ready.
Therefore your
program can determine whether the output was done, and can proceed
appropriately.
To determine whether error bits are set on the return from an OUT
monitor call,
use the GETSTS, STATZ, or STATO monitor call.
If no
bits are set, your program can perform other operations not associated
with the same device (such as computations or I/O for other devices) .
Your program can periodically retry the OUT or FILOP.
call, to see if
the buffer is ready.
Your program can also be written to respond to
an output-done software interrupt when the buffer is ready
(see
Chapter 6),
or to wake from a hibernating state when the buffer is
ready (see Chapter 22) .

11.9.6

Buffered I/O for MPX-Controlled Devices

The monitor recognizes that I/O is for an MPX-controlled device
because you OPENed MPX (or a logical name for it).
The buffer control
block must be 4 words long; the last word will contain a Universal
Device Index.
For input, MPX-controlled devices use a conventional buffer ring
(as
described above).
For output,
they use a special buffer structure
that consists of a free chain (for the MPX channel)
and one device
chain for each device on the channel.
The free chain is a series of buffers in which each buffer points to
the next.
For each buffer in the series, the BF.NBA field of the
buffer header contains the address of the next buffer; BF.NBA in the
last buffer header contains O.
The .BFADR word of the buffer control block points to the current
buffer in the free chain, so that there is a continuous chain from the
buffer control block to the last buffer in the free chain.
The buffer control block and the buffers in the free chain are in user
core.
The device data block (DDB) for the MPX channel is in monitor
core.
Each device chain consists of a DDB for the device and one or more
buffers linked to the DDB.
The DDB points to the first buffer in the
device chain. Each buffer (in its .BFADR word)
points to the next
buffer; the last buffer has a in the right half of .BFADR.

11-36

PROGRAM INPUT AND OUTPUT

As output proceeds in your program, the
MPX-controlled devices as follows:

monitor

handles

output

for

The first OUT or OUTPUT monitor call to the MPX channel is
the "dummy" call.
The monitor creates the free chain for the
MPX channel.

For each call to a device on the MPX channel,
the monitor
moves a buffer from the top of the free chain to the bottom
of the device chain.
This is done by updating the
.BFADR
address in the buffer control block to point to the second
buffer in the free chain, which then becomes the top buffer
in the free chain.
The BF.NBA field in the moved buffer is
zeroed, because it is to be the end of the device chain.
The
address of the moved buffer is placed in BF.NBA for the old
end buffer in the device chain, so that the chain is extended
to include the moved buffer.

When a buffer is emptied (written to its device), the monitor
moves the buffer back to the bottom of the free chain.
This
is done by updating the pointers in both the device chain and
the free chain.

The following pages contain figures and explanations showing
monitor handles buffered output for an MPX channel.

11-37

how

the

PROGRAM INPUT AND OUTPUT
The first OUT or OUTPUT call for a different MPX-controlled device on
the channel
(a device with different Universal Device Index) moves a
buffer from the top of the free chain to the bottom of the
(formerly
empty)
device chain for that device.
Figure 11-5 shows this
situation, in which there are two device chains.

I
1
1-----------1

Buffer
Control
Block

I
I C 1--\
1-----------1 I

----------------1-----1
DDB1 1

--\

1--\

\-----1

-----------------

-------------

DDB2 1

1------------------1
1

-------------

1
1-----------1
\--> I I
0
I
1-----------1
1

1-----------1
I
Buffer B I
------------Figure 11-5:

-------------

--\
I

1-----------1

D 1-\
1-----------1
1
I 1
1-----------1 1
I
Buffer C 1 I

> Chain
1

I
I

I
1
1
1

1----------------1

1 Free
> Chain

-------------

--I

1--\
\-----1
I

\-->1

-----------------

-------------

I
1

1 Device
I
1
1

----------------1-----1

UDX2

1
I
I
I

1
1-----------1
\--> 1
I 0
1
1-----------1
1-----------1
1
Buffer A 1
-------------

1------------------1
1

1-----------1

I
\

1-----------1

\->1-----------1

--\
I

1
1

1-----------1

. 1 Buffer D 1
-------------

1 Device
> Chain
\
2

1
I

1
1

--I

One Buffer in Each of Two Device Chains

11-38

1
I

1
--I

PROGRAM INPUT AND OUTPUT

Another OUT or OUTPUT call for a device that already has a device
chain moves a buffer from the top of the free chain to the bottom of
the device chain for that device. Figure 11-6 shows this situation,
in which multiple device chains have multiple buffers.

1
1
1

------------1
1

1-----------1
1--\
< 1-----------1
1
1 1
I 1
1 1-----------1 1
1 1
UDX1
1 1
\- ------------- 1

Buffer
Control
Block

liD

/-----1

1
1

1 A 1--\
\-----1
1

1
1

-----------------

/------------------/
1
1

-------------

1
1-----------1
\-->1
1 C 1--\
1-----------1

1
1-----------1
\-->1
1 0 1
1-----------1
1

1-----------/

1
1

--\
1
1
/ Free
> Chain
\

1
1

--\

Buffer D

1
1

--I

1
1

/ Device
> Chain

--\
1
1

\-----1

/------------------/

-----------------

1
1

1-----------1
1

Buffer A

1
DDB2 /-----1
l i B 1--\

-------------

/------------------/

-------------

1
1-----------1
\--> 1
1 0 1
1-----------1
1

-------------

1
1-----------1
\-->1
1 0 1

1-----------1
1

1-----------1

Figure 11-6:

--I

Buffer B

Multiple Buffers in Multiple Device Chains

11-39

1
1
/ Device
> Chain
2
\
1
1
1
1

1-----------1
Buffer C

--I

PROGRAM INPUT AND OUTPUT

When the monitor has emptied a buffer in a device chain,
it returns
the buffer to the bottom of the free chain. Figure 11-7 shows this
situation, in which one of the buffers for a device has been moved
from the device chain to the bottom of the free chain.

Buffer
Control
Block

1
1
1-----------1
l i D 1--\
1-----------1 1
1
1 1
1-----------1 1
1
UDX
1 1

1
1

1
1
\
--\

1-----1

DDB1 1

1--\

\-----1

-----------------

1------------------1
1
1

-------------

1-----------1
1 0 1
1-----------1

\
1
1

Buffer C

--\

Buffer D 1
------------1

1
1
1
1
--I

1-----------1

1
1

1
1-----------1
1
\-->1
1 A 1--\
1-----------1
1
1
1-----------1

> Chain

1-----------1
1

1
1
1
1
1
1

1 Device

\--> 1
1

-------------

DDB2 1

1--\

\-----1

-----------------

1------------------1
1
1

-------------

1-----------1

\--> 1

1-----------1
1

Buffer B

Figure 11-7:
11.9.7

1 Free

1
1

-------------

> ,Chain
\

1
1-----------1
\-->1
1 0 1
1-----------1
1
1
1-----------1

1
1
1

1------------------1

Buffer A

--\

1-----1

1
1
1
1
1
1

--I

Note that Buffer A was
returned to the free chain
after it was emptied.

1
1

1 Device
> Chain
2
\
1
1

1
1

--I

One Buffer Moved Back to Free Chain

Generating Your Own Buffers

Your program can generate its own buffers instead of allowing the
monitor to generate them.
You might want to do this, for example, if
your buffers must use a nonstandard byte size.
The following example shows how to set up buffers for an input file.
This code sequence is similar in its performance to the INBUF monitor
call.
In the example, the device is MTAO; the undefined symbol BYTSIZ
gives the byte size for the buffers; the undefined symbol SIZE gives
the size of the buffers; the number of buffers in the ring is 2.
11-40

PROGRAM INPUT AND OUTPUT

;This example shows how to set up a 2-buffer input buffer ring.
OPEN
JRST
MOVE
MOVEM
MOVES I
MOVEM
JRST

GO:

ICHN,OPNBLK
;Initialize the channel
ERROR
;Not available
Tl, [BF.VBR+BUFl+.BFHDR]
Tl,MAGBUF+.BFADR
Tl, (POINT BYTSIZ)
Tl,MAGBUF+.BFPTR
CONTIN
iOn to something else

OPNBLK: BLOCK
SIXBIT
XWD

1
/MTAO/
O,MAGBUF

MAGBUF: BLOCK

;For flags and status bits
;Device name
;No output"input ring header

BUFl:

BLOCK
XWD
BLOCK.
BLOCK

1
SIZE+l,BUF2+.BFHDR
;
'SIZE

;For file status
;Size+l"next buffer
;For word count
; Space for the buffer

BUF2:

BLOCK
XWD
BLOCK
BLOCK

1
SIZE+l,BUFl+.BFHDR
1
SIZE

;For file status
;Size+l"next buffer
;For word count
;Space for the buffer
;Something else

CONTIN:

If you have a program with a specialized memory management scheme and
want to specify the buffer locations, you would want to generate your
own buffers.
The following example shows how this situation could be
handled.
Tl=l
T2=2
GO:

OPEN
JRST
MOVE I
DEVSIZ
JRST
HLRZ
HRRZS
IMULI
PUSHJ

ICHN,OPNBLK
ERROR
Tl,OPNBLK
Tl
ERROR
T2,Tl
Tl
Tl, (T2)
P,GETMEM

JRST
PUSH
MOVEM
INBUF

ERROR
P, . JBFF
Tl, .JBFF
Tl,O

POP

P, . JBFF

;OPEN file
;Not available
;Find number and
; size of
; default buffers
;Compute words needed
; for size and number
; of buffers
;Call your memory allocator
; with words to get in Tl,
;returns address of block in Tl
;Can't get?
;Save current first free
;Default number of buffers
;Make monitor put buffers
; where you want
;Restore .JBFF now that
; buffers are allocated

11-41

PROGRAM INPUT AND OUTPUT

The following example demonstrates the
buffered I/O:

general

TITLE

Buffered Input/Output Example for TOPS-10

COMMENT

principles

using

This program demonstrates the basic principles of buffered input and
output by reading the ASCII input file INPUT: INPUT. IN and copying it
to the ASCII output file OUTPUT:OUTPUT.OUT.
Note that the logical names INPUT: and OUTPUT: must be assigned by the
ASSIGN command.
These logical names can be assigned to any devices
that support ASCII line mode.
The monitor will ignore the LOOKUP and
ENTER calls if the devices do not support directories.
END COMMENT *
SEARCH

UUOSYM

;Use standard definitions
;Keep the program neat

SALL

;Definitions for registers and channels
T1=1
C=10
J=15

;For scratch
;For storing a character
;For JSPing around

ICHN==1
OCHN==2

;Input channel number
;Output channel number

;Macro for general messages
DEFINE
I]
>

ERROR(TEXT)<
JRST
[OUTSTR [ASCIZ I?'TEXT
;Output message to TTY:
JRST
MONRT]
;And back to monitor mode
;End of macro definition

;Here on entry to initialize program.
BUFENT: JFCL
RESET

;In case of CCL entry (ignore)
;Reset any I/O, .JBFF, etc.
; (In case of CTRL/C start)

OPEN
ICHN,INDEV
;Open input device
ERROR <CAN'T OPEN LOGICAL DEVICE INPUT:>
LOOKUP rCHN,INFIL
;Find input file
ERROR <CAN'T LOOKUP INPUT FILE INPUT.IN>
OPEN
OCHN,OUDEV
;Open output device
ERROR <CAN'T OPEN LOGICAL DEVICE OUTPUT:>
ENTER
OCHN,OUFIL
;Create output file
ERROR <CAN'T ENTER OUTPUT FILE OUTPUT.OUT>

COMMENT *
Here we could optionally set up buffer rings using the INBUF and
OUTBUF monitor calls.
Instead, we'll let the monitor do it for us on
the first IN and OUT monitor calls. This is normal.
END COMMENT *

11-42

PROGRAM INPUT AND OUTPUT
iHere's the main I/O loop to transfer the file.

IO:

JSP
JRST
JSP
JRST

J,GETBYT
EOF
J,PUTBYT
IO

iRead a byte of input
iEnd of input file
iWrite the byte
;Back for next byte

iHere on end of input file.

EOF:

RELEAS
CLOSE

ICHN,
OCHN,

STATZ
JRST
RELEAS

OCHN,IO.ERR
OUERR
OCHN,

iLet input device and channel go
iCLOSE output file
i (Writing last buffers)
iAny last errors?
iYes, complain to user
iNo, release output device

iHere to return to monitor mode.
ilf'user continues, restart.

MONRT:
COMMENT

MONRT.
JRST

BUFENT

iBack to monitor mode
iUser said continue

The following routines are the basic low-level buffered I/O routines.
Note that both GETBYT and PUTBYT are self-initializing. On the first
call to each, the input and output byte counts are 0
(set by the
monitor on the OPEN) .
GETBYT falls into the IN call to set up the default number of input
buffers and starts filling them.
Control returns to GETBYT when the
first buffer is full.
PUTBYT falls into the OUT call (the so-called "dummy" OUT) to set up
the default number of output buffers.
Then it returns so that the
program can fill and output the buffers.
END COMMENT

iGETBYT - Routine to read 7-bit ASCII input data.
GETBYT: SOSGE
JRST
ILDB
JUMPN
JRST

INCNT
GETBUF
C, INPTR

GETBUF: IN
JRST
GETSTS
TRNE
JRST
ERROR

ICHN,
GETBYT
ICHN,T1
T1,IO.EOF

C, 1 (J)

GETBYT

iAny chars in input buffer?
iNO, must read next buffer

iYes, return char in C
iSuccessful return is skip
iNul1 char, throwaway

iAdvance to next input buffer
;And back for next character
ilnput error
iWas it end-of-file?
(J)
iOk, not a real error
<I/O ERROR ON INPUT>

iPUTBYT - Routine to write 7-bit ASCII output data.
PUTBYT: SOSGE
JRST
IDPB
JRST

OUCNT
PUTBUF
C,OUPTR

PUTBUF: OUT
JRST
OUERR: ERROR

OCHN,
iWrite out this buffer
PUTBYT
;And start filling next
<I/O ERROR ON OUTPUT>

(J)

iAny room in current output buffer?
write out and get next
iYes, put it in output buffer
iReturn for more (note nonskip)

iNo,

11-43

PROGRAM INPUT AND OUTPUT
iHere all data blocks are defined.
iFirst the input and output OPEN blocks:

INDEV:

OUDEV:

. IOASL
SIXBIT
XWD

/INPUT/
O,INHDR

iASCII line mode
ilnput device name
iAddress of input buffer
iControl block

. IOASL
SIXBIT
XWD

/OUTPUT/
OUHDR,O

iASCII line mode
iOutput device name
iAddress of output buffer
iControl block

iNOW THE LOOKUP/ENTER BLOCKS:
INFIL:

OUFIL:

SIXBIT
SIXBIT
BLOCK
BLOCK

/INPUT/
/IN/
1

SIXBIT
SIXBIT
BLOCK
BLOCK

/OUTPUT/
/OUT/

1
1

ilnput file name
ilnput extension
iProtection, mode, creation date
iPPN or path number
iOutput file name
iOutput extension
iProtection, mode, creation date
iPPN or path pointer

iNext the buffer control blocks. (The monitor will build the
i buffers on the first IN and OUT calls.):
INHDR:
INPTR:
INCNT:

BLOCK
BLOCK
BLOCK

1
1
1

ilnput buffer control block
ilnput buffer ring byte pointer
ilnput buffer ring byte count

OUHDR:
OUPTR:
OUCNT:

BLOCK
BLOCK
BLOCK

1
1
1

iOutput buffer control block
; Output buffer ring byte pointer
iOutput buffer ring byte count

END

BUFENT

11.10

CLOSING A FILE

To close a file, use the CLOSE or FILOP.
monitor calls.
These calls
end I/O operations for the file and ensure that all data input or
output is completed.

11-44

PROGRAM INPUT AND OUTPUT
11.10.1

Maintaining File Integrity

Ordinarily, the integrity of a disk file is not assured until you
perform a CLOSE operation on the file.
For instance, if the syst 7m
crashes when writing a disk file, the entire disk file to date 1S
lost.
The entire current file may not be lost if a system crash
occurred during an update-mode writing of the file, but its integrity
cannot be guaranteed.
This happens because an update-mode writing
that extends the file allocates new disk blocks to the file;
therefore, the file's RIB must also be re-written.
However, after you
perform the CLOSE, the monitor guarantees the file's integrity even
across a system crash,
unless something destroys the physical file
structure.
There are, however, two methods you can use to assure file
integrity while actively using the file:
o

Using the FILOP . . FOURB function.
This
FILOP. function
writes the complete file to disk, and updates the file's RIB
on disk as though you had performed a CLOSE.
The
.FOURB
function acts as a checkpoint operation for a disk file.
After the FILOP . . FOURB, the file is guaranteed on disk and
will survive a system crash or any halt, such as a <CTRL/C>.
Programs that perform journaling operations use this function
to save user input in a separate file.
This journal file is
saved on disk if an unexpected halt occurs.
Later,
you can
recall this file and use it to restore previous input and
re-execute commands.
You should note that the monitor performs an OUT monitor call
for you when you use this procedure.
This positions the
buffer header byte pointer at the beginning of a word,
no
matter where the byte pointer was before the .FOURB call.
If
the byte pointer is in the last word of a buffer,
then the
header points at the next buffer in the ring after the .FOURB
call. As a result, the disk file may contain embedded null
bytes of data for each of the checkpoint operations executed.

Using either the FILOP . . FORRC function,
or setting the
UU.RRC bit in the OPEN monitor call.
If you periodically
issue the FILOP. monitor call with the .FORRC function,
the
monitor will checkpoint the file if the RIB has changed since
the last .FORRC call.
The program may enable a PSI program
interrupt whenever a disk file RIB has changed (interrupt
condition PS.RRC) .
If you set the UU.RRC flag when you issue the OPEN monitor
call,
the monitor automatically checkpoint~ your file when
you write enough data to cause a change in the RIB.

11.11

RELEASING A DEVICE

To release a device, use the RELEASE or FILOP. monitor call.
calls return the device and its channel to the monitor's pool.

11-45

These

PROGRAM INPUT AND OUTPUT
11.12

STOPPING A PROGRAM

To stop execution of a program, use the EXIT monitor call.
This call
terminates execution of the program, but leaves the program in your
user memory so that it can be restarted.
Most programs can also be stopped by the CTRL/C command.
If the
program is waiting for terminal input, type one CTRL/C.
If not, type
two CTRL/Cs.

11.13

THE LOOKUP/ENTER/RENAME ARGUMENT BLOCKS

As discussed in Section 11.7, the LOOKUP, ENTER,
and RENAME monitor
calls accept argument lists in the identical formats.
There are two
formats you can use to supply arguments to these calls.
The short
form allows you to accomplish the call by specifying a minimal amount
of information.
This form is used in Section 11.7 and following to
illustrate the general sequence of calls needed to accomplish I/O.
The short form of the argument block is described in detail in Section
11.13.1.
The long form of the argument block
(also called the "extended
argument list")
is used to specify information for disk files.
This
format of the LOOKUP/ENTER/RENAME argument block can also be used to
read the RIB (Retrieval Information Block) of the disk file.
For the
purpose of providing completely device-independent I/O code,
the
extended argument list can be used for I/O on any device.
The
information that is not applicable to each device is simply ignored.
The extended argument list is described in detail in Section 11.13.2.

11.13.1

The Short Form of the Argument List

The LOOKUP/ENTER/RENAME argument list may take the following form.
The short form of the argument list must always be 4 words long.
The
following list show s the contents of each word in the argument list.
The arguments are denoted by the following symbols for each of the
three monitor calls, LOOKUP, ENTER, and RENAME:
A

signifies an argument that your program must supply.

signifies an optional argument.
If your program does not
supply the contents, the monitor uses a default value.

signifies a value that is only returned
after the call is completed.

11-46

the

monitor

PROGRAM INPUT AND OUTPUT

The short form of the argument list
monitor calls is:

for

LOOKUP,

ENTER,

and

RENAME

Word

LOOKUP

ENTER

RENAME

File name in SIXBIT.

Bits 0-17:
SIXBIT.

Bits 18-20:
high-order
bits of the creation date.

Bits 21-35:

Bits 18-35: on an error return
from the call, the error code is
stored here.
Refer to Section
11.14.

Bits 0-8:

Bits 9-12:
data mode
when it was created.

file

Bits 13-23:
creation
minutes since midnight.

time

Bits 24-35:
low-order
bits of creation date.

Word 3 on input is: PPN or path
pointer.
A path pointer takes
the form:

Contents

file

extension

three

access date.

protection code.

twelve

O"addr
Where:
addr
is
the
address
~ the
path
block.
Refer
to
the
PATH. UUO in Chapter 22.
3

Word 3 is returned as:
Bits 0-17:
the
LOOKUP
call
returns the length of the file in
the left half as number of words
expressed as a negative number.
The file size is expressed as a
positive number when the file
contains more than 128K words.

11-47

PROGRAM INPUT AND OUTPUT
11.13.2

The Extended Argument List

The long form of the argument block for LOOKUP,
ENTER,
and RENAME
monitor calls allows you to specify more information about the file.
You can also maintain greater control over your I/O request using
flags provided in this argument list.
The extended argument list is signified by placing a zero in the left
half of the first word of the argument list, and the length of the
argument list in the right half.
The total length must be at least 3
words.
.RBMAX is the maximum number of words (50 octal) that the
block may contain.
The system ignores any value larger than this.
The argument list allows your program to supply information that is
passed to the monitor.
If your program includes an illegal argument,
the monitor ignores that information and returns the default value of
the incorrect argument.
Each word of the extended argument list is
described below.
The following symbols are used in the description to
denote the applicability of each argument to each of the monitor
calls, LOOKUP, ENTER, and RENAME.
The symbols in the colunns are:
A

an argument (supplied by either a privileged or unprivileged
program) and returned by the monitor as a value.

an argument like A, except that a 0 argument
monitor to substitute a default value.

an argument if supplied by a privileged program; if supplied
by an unprivileged program, it is ignored.

the value returned by the monitor cannot be set even by
privileged program; the monitor will ignore the argument.

Word

Symbol

LOOKUP

ENTER

RENAME

.RBCNT

11-48

causes

the

Contents
The count of the number of
arguments that follow.
Left half:
unused, must be
zero.
Right half:
flags + number
of
arguments
following
this.

PROGRAM INPUT AND OUTPUT

Where the flags can be:
Bits

Symbol

Meaning

RB.NSE

If set on an ENTER,
that
ENTER
is
a
non-superseding
ENTER.
If
your program
specifies an existent file name,
that file
will not be superseded.
The monitor will give
the error return and will return error code 4
(ERAEF%) in addr+3 of the argument block.

RB.DSL

(Don't Search LIB) During a LOOKUP,
if the
file is not found in the default path, the
monitor would, by default, proceed to search
LIB.
Failing that,
if /SYS is enabled, the
monitor would search SYS
(and,
with /NEW
enabled,
NEW).
Setting RB.DSL inhibits these
actions.
If the file is not found in the
default path,
the monitor will immediately
return error ERFNF% and no further searching
will take place.
The default path will always
be scanned.
RB.DSL does not effect the use of
SFD scanning.

RB.AUL

(Allow Updates in LIB) By default, if a LOOKUP
finds a file on device LIB, the monitor will
not allow a subsequent ENTER or RENAME.
This
action is intended to prevent the user from
accidentally modifying the wrong file.
If
RB.AUL is set, however, the user's actions are
regarded as deliberate,
and the subsequent
ENTER or RENAME will be allowed.
Note that
RB.AUL must be on at the time of the LOOKUP,
and that this bit is meaningless for ENTER and
RENAME calls.

RB.NLB

(No Load Balancing) When a user ENTERs a file
on a structure that consists of multiple disk
units, the monitor creates the file on the
unit
with
the most available space,
by
default.
However, if the user has a channel
open for another file on the same structure,
the monitor attempts to create the new file on
a different unit in the structure, regardless
of the unit that has the most space.
The two
files are created on 'different units in the
same structure to ensure that I/O to the
structure is evenly balanced.
If the program
sets RB.NLB, the new file is not forced to a
different unit than the originally opened
file, suppressing the load balancing action.
Under RB.NLB, each file is created on the unit
in the structure that has the most available
space.

11-49

PROGRAM INPUT AND OUTPUT

Word

Symbol

LOOKUP

CREATE/
SUPERSEDE

.RBPPN

UPDATE/
RENAME Contents
AO

A PPN or a pointer to a
For a path
path block.
left
half
pointer,
the
and the
contains
zero,
right half contains
the
address of the path block.
For a description of a path
block,
refer
to
the
PATH. UUO in Chapter 22.
The PPN is for the user
file directory in which the
file is to be LOOKed UP,
ENTERed,
or RENAMEd.
To
LOOKUP a UFD,
.RBPPN must
contain
1, , 1
(indicat ing
the MFD) .
The search defaults to
and
only
if
SYS
directory path
was
specified.

.RBNAM

The
SIXBIT
file
left-justified
trailing nulls.

LIB
the
not
name,
with

If
the
Master
File
Directory or a User File
Directory is being LOOKed
ENTERed, or RENAMEd on
UP,
this call,
this location
contains
the
directory
name.
The argument can be
0 on a RENAME or a LOOKUP
and ENTER if pathological
names are in use, in which
case the file
will
be
deleted.
3

.RBEXT

Bits 0-17:
The SIXBIT file
extension,
left-justified
with
trailing
nulls.
Although
file extensions
are
optional,
null
extensions are discouraged
because they
convey
no
information.

Bits 18-20
(RB. CRX) :
The
high-order three bits of
the 15-bit creation date.
The
system
updates the
creation date only when you
write additional blocks to
the file.
For instance,
altering the last block of
the file would not result
in
an
updated creation
date.

11-50

PROGRAM INPUT AND OUTPUT

.RBPRV

Bits 21-35
(RB .ACD)
access date.

Bits 18-35:
If the UUO
fails,
an error code is
returned in the right half
of this word.
Refer to
Section 11.14 for a list of
the error codes.

Bits 0-8:
(RB.PRV) .

Bits 9-12:
Data mode in
which the file was created
(RB.MOD) .

Bits 13-23: Creation time
in minutes since midnight
(RB .CRT) .
The
system
updates the creation time
when
only
you
write
additional blocks to the
file.

Bits 24-35:
The low-order
12
bits
of the IS-bit
creation date in standard
format (RB. CRD) .

Protection

The

code

.RBSIZ

The written length of the
If your
file,
in words.
program sets this value,
the monitor ignores it.

.RBVER

The octal version number of
the file, same as .JBVER.

.RBSPL

The file name to be used to
label the output from a
spooled device.
The file name is specified
on an ENTER to the spooled
device, or it is 0 if an
been
ENTER
has
not
performed.

.RBEST

The estimated length of the
file, in positive number of
blocks.
an
On the execution of
ENTER
call,
the monitor
the
uses this value as
number
of
blocks
to
allocate for the file.
If
the
requested number of
blocks cannot be allocated,
partial
allocation
is
performed, and the normal
return is taken.
.RBALC
always contains the actual
number of blocks allocated.

11-51

PROGRAM INPUT AND OUTPUT

.RBALC

The number of contiguous
128-word blocks allocated
to a file when an ENTER or
RENAME call is performed.
The
number
of
blocks
includes the RIBs of the
file and is equivalent to
the last block number of
the file .
. RBALC equal to 0 does not
change the allocation of
the file.
All of the data
blocks can be deallocated
by superseding the file and
performing no output before
the CLOSE.
This argument
can be used to allocate
additional space onto the
end of the file, deallocate
previously allocated
but
unwritten
space,
or
truncate written
blocks.
The smallest unit of disk
space that the monitor can
allocate is a cluster of
200-word
blocks.
Typically,
small devices
use a cluster size of 1
block.
If the number of
blocks allocated is
not
equal to the last block of
a cluster, the monitor will
round up; thereby adding a
few more blocks than the
user
requested.
If the
monitor cannot allocate the
specified number of blocks,
then the partial allocation
error
(error code 17) will
be returned; however,
your
program may still write the
file.
To
create
a
file
of
prespecified length,
your
program should perform an
extended ENTER with .RBEST
set and .RBALC cleared.
To
create
a
file
of
prespecified length
with
contiguous
blocks,
your
program should perform an
extended ENTER with .RBEST
cleared and
.RBALC
set.
After an ENTER, .RBALC will
contain
the
accurate
allocated file length.

11-52

PROGRAM INPUT AND OUTPUT
12

.RBPOS

The logical block number of
the first
allocated block
for a new group of clusters
appended to the file.
The logical block number is
specified with respect to
the entire file structure,
beginning with block number
O.
Combined
with
the
DSKCHR call,
this feature
allows your
program
to
allocate
a
file
with
respect
to
tracks
and
cylinders
for
maximum
efficiency when the program
is executed.

.RBUFW

Determines the disk drive
that the file was written
on;
the
format
is
as
follows:
Bits 0-9:
DIGITAL.

Reserved

for

Bits
10-17
(RB.UNI):
Unites)
that have written
the file
(Bit 17 set
drive 0, Bit 16 set = drive
1, and so forth) .
Bits 18-20
(RB.CON)
The
controller number
(0 = A,
1 = B, and so forth) of the
controller that last wrote
the file.
Bits 21-35
(RB.APR):
The
serial number of the CPU
that last wrote the file.
14

.RBNCA

Reserved
for
customer
definition;
does
not
require privileges.

.RBMTA

A 36-bit tape label, if the
file
has been put onto
magnetic tape.

.RBDEV

The logical name of the
unit on which the file is
located.

.RBSTS

The
I/O
status
word
(.RBSTS) .
Left half:
The status of
the UFD.
Right half:
The status of
the file.
Refer
to
.RBSTS
bit
definitions
in the next
table
for
the
bit
definitions of this word.

11-53

PROGRAM INPUT AND OUTPUT
20

.RBELB

The logical block number
within the unit on which
the first data error or
search
error
(IO.DTE)
occurred, as opposed to the
block
within
the
file
structure.
This value is set in the
RIB by the monitor when a
CLOSE is executed and the
hardware
has detected a
hard parity error or
a
search error while reading
or
writing
the
file.
Device
errors,
checksum
errors,
and
redundancy
errors are not stored in
this location.
Any data
you place in this location
will be ignored,
but the
following
bits
may
be
returned by the monitor:
Bits 0-2
(RB.EVR):
type:
bad version
number.

Error
block

Bit 3
(RB.ETO) :
Error
type:
other
(not data or
search error) .
Bit 4
(RB.ETD)
Error
type:
data (parity or hard
ECC)
Bit 5
(RB.ETS) :
type:
search or
compare.

Error
header

Bits 3-8 (RB.ETM):
Mask of
all error type bits.
Bits 9-35 (RB.EBN):
Number
(within unit) of first bad
block.
21

.RBEUN

Left half:
The
logical
unit number within the file
structure on which the last
bad region was detected.
Right half:
The number of
bad
blocks in the last
detected bad region.
The bad region may extend
beyond
the
file.
This
argument is ignored, and a
value is returned.
Bits 0-8 (RB.ENB):
Number
of contiguous bad blocks.

11-54

PROGRAM INPUT AND OUTPUT
unit
Bits 10-17 (RB.EUN) :
number within controller;
bit 10 = unit 7, bit 17
unit o.
Bits
18-20
(RB.EKN)
Controller number.
Bits 21-35
number.
22

.RBQTF

Contains
quota.

(RB.ECN)
the

cpu

logged-in

This quota is the maximum
of data and RIB
number
blocks that can be in this
structure's directory while
The
the user is logged-in.
UFO and the UFO's RIB are
not included in this count.
22

.RBTYP

Contains file
and
type
flags.
This word is used
by system programs (such as
FORTRAN) , and its format is
determined
by
the
application in which it is
used.
Refer to UUOSYM for
a complete description of
this word.

.RBQTO

Contains
the
logged-out
(meaningful for the
quota
UFO only) .
This quota is the maximum
number
of data and RIB
blocks that can be left in
this structure's directory
LOGOUT
after you log out.
requires that the user must
be below this quota to log
out.

.RBBSZ

Contains byte and record
length information.
System
programs (such as FORTRAN)
and its
this word,
use
format is determined by the
application in which it is
Refer to UUOSYM for
used.
a complete description of
this word.

.RBQTR

Reserved
quota
(applies
only
UFOs)
This
to
information
is
not
completely implemented by
the monitor.
(Meaningful
for UFD only. )

11-55

PROGRAM INPUT AND OUTPUT
24

.RBRSZ

contains record and block
System
size information.
programs (such as FORTRAN)
use this word; its format
the
determined
by
is
application in which you
use it.
Refer to UUOSYM
for a complete description
of this word.

.RBUSD

Contains the number of data
and RIB blocks allocated to
files in this structure's
directory when the owner
last logged off (meaningful
for the UFD only) .
LOGIN reads this word so
that it does not have to
LOOKUP all files to set up
the
number
written
of
LOGIN sets Bit 0
blocks.
(RP. LOG) of the file status
below) ,
and
word
(see
it
to
LOGOUT
clears
indicate whether LOGOUT has
stored the quantity.

.RBFFB

Contains first free byte
and
application-specific
information.
This word is
used
by system programs
(such as FORTRAN. ) Refer to
for
complete
UUOSYM
a
description of this word.

.RBAUT

The PPN of the job creating
or superseding the file, as
opposed to the owner of the
file.
Usually the author and the
owner are the same.
Only
when a file is created in a
different
directory
are
these different.

.RBIDT

BACKUP'S incremental
and time in UFD.

.RBPCA

Privileged
reserved
for
definition.

.RBUFD

The logical block number in
the file structure of the
RIB for the UFD in which
the file appears.

11-56

date

argument
customer

PROGRAM INPUT AND OUTPUT
33

.RBFLR

The relative block number
of the file to which the
first pointer of this RIB
points;
this is used for
multiple RIBs (for example,
0 = prime RIB) .

.RBXRA

The extended RIB address
(that is, the logical unit
number and
the
cluster
address of the next RIB in
a multiple RIB file) .

.RBTIM

The internal creation and
time of the file, in the
universal date-time format.

.RBLAD

The last accounting
Valid only for UFOs.

.RBOEO

The directory
expiration
date.
For
disk
directories, this is valid
only
for
UFOs.
For
magtape, this is valid only
for
labelled
tapes and
refers to the expiration
date of the file.

.RBACT

Account string word
ASCII.

date.

This is non-zero on
an
ENTER, and is not valid for
UFOs.
41

.RBAC2

Account string word
ASCII.

.RBAC3

Account string word
ASCII

.RBAC4

Account string word
ASCII.

.RBAC5

Account string word
ASCII.

.RBAC6

Account string word
ASCII.

.RBAC7

Account string word
ASCII.

.RBAC8

Account string word
ASCIZ.

A null byte terminates the string.

11-57

PROGRAM INPUT AND OUTPUT

Bits

Symbol

Meaning

RP .LOG

Set if the user is logged in.
bit; LOGOUT clears it.

RP.CHG

Set if some file has changed in this UFO since
the last BACKUP.

7Bll

RP. UER

All UFO errors.

RP. UCE

Set if any file in this UFO has had a software
checksum error or a redundancy check error.

RP. UWE

Set if any file in this UFO
data error while writing.

has

had

hard

RP. URE

Set if any file in this UFO
data error while reading.

has

had

hard

RP.OIR

Set if the file is a directory file;
this
protects the system from a user trying to
modify a directory file.
The protection error
is given if the extension UFO is specified on
an ENTER or RENAME and this bit is not set.

RP .NOL

If set, the file cannot be deleted,
renamed,
or superseded, even by a privileged program.

RP .OMP

Set if this is an unprocessed crash file.
This bit is set on CRASH.EXE files and used by
the CRSCPY program.

RP.NFS

Set if the file should not be dumped by disk
backup programs because certain files (for
example, SWAP.SYS, SAT.SYS) contain no useful
data to write on the tape.

RP . ABC

Set if the file always has bad checksums
(because
the
monitor never recomputes a
checksum) for example, SWAP.SYS, SAT.SYS.

RP.CBS

If set, RP.CMP
compressor.

RP . ABU

If set, disk backup
dump this file.

RP .NQC

If set, the file is a non-quota checked file,
and it is not billed to the user's disk quota.

RP .CMP

If set, the UFO is being compressed.

RP .FCE

If set, the file has a software checksum error
or a redundancy check error (the IO.IMP bit
has been set) .

RP .FWE

If set, the file has had a hard data error
while writing.
An
entry is made in the BAT
block so that the bad region is not reused.

RP .FRE

If set, the file has had a hard data error
while reading.
An
entry is made in the BAT
block so that the bad region is not reused.

11-58

(Bit 26)

is set on entry to UFO

programs

should

always

PROGRAM INPUT AND OUTPUT

11.14

RP.RMS

If set, this file was created
Record Management Service).

RMS

RP . PAL

If set, this is a preallocated file.
This bit
is set when you preallocate a file (using
FILOP.) but the file has not been created yet
(that is,
the file is nUll).
This bit is
cleared when data is in the file.

RP.BFA

If set, the file is bad because of a tape read
error during a restore.

RP .CRR

If set, the file was closed after a crash.

RP . BOA

If set, the file has been marked as bad
damage assessment program.

715

RP . ERR

All file errors.

(the

ERROR CODES

Error codes are restricted to a maximum of 15 bits to eliminate
problems when recovering from an error in a file with a zero creation
date.
The following error codes are returned from ENTER,
LOOKUP,
RENAME, RUN, GETSEG, MERGE., FILOP., SAVE. and SEGOP. calls. For more
information, refer to the appropriate call in Chapter 22.
Code

Symbol

Error

ERFNF%

ERIPP%

ERPRT%

3
4

ERFBM%
ERAEF%

ERISU%

ERTRN%

The specified file was not found,
a null file
name was specified, file names do not match on
an update operation, or RENAME after a LOOKUP
failed.
For a FILOP.,
this error code is
returned if the specified device cannot perform
I/O in the direction indicated.
The UFO does not exist on the specified file
structure (incorrect PPN) .
Protection failure, or directory is full for a
OECtape.
File being modified (ENTER, RENAME).
The specified file already exists
(RENAME,
FILOP.),
a different file name was specified
(ENTER after a LOOKUP), the file was superseded
(on a non-superseding ENTER) .
Inclusion of an illegal sequence of monitor
calls (such as a RENAME with no preceding LOOKUP
or ENTER, or a LOOKUP after an ENTER).
For
example,
the system returns this error code if
you attempt to RENAME a file on device LIB
without setting FILOP. bit RB.AUL first.
One of the following errors occurred:
o

Transmission, device, or
GETSEG, MERGE. only).

Hardware-detected device or
data
error
detected while reading the UFO's RIB or the
file's RIB.

Software-detected data inconsistency error
detected while reading the UFO's RIB or the
file's RIB.
11-59

data

error

(RUN,

PROGRAM INPUT AND OUTPUT
7

ERNSF%

ERNEC%

ERDNA%

ERNSD%

13
14

ERILU%
ERNRM%

ERWLK%

ERNET%

17
20

ERPOA%
ERBNF%

21
22

ERCSD%
ERDNE%

ERSNF%

ERSLE%

ERLVL%

ERNCE%

ERSNS%

30
31

ERFCU%
ERLOH%

32
33
34

ERNLI%
ERENQ%
ERBED%

ERBEE%

ERDTB%

ERENC%

ERTNA%

ERUNN%

42
43

ERSIU%
ERNDR%

44
45
46

ERJCH%
ERSSL%
ERCNO%

File is not in executable format
(RUN,
GETSEG,
MERGE.
only).
Not enough core available to load the file (RUN,
GETSEG, MERGE., SAVE. only).
Device not available
(RUN,
GETSEG,
FILOP.,
SAVE., MERGE.).
No such device
(RUN,
GETSEG,
MERGE.,
SAVE.).
For FILOP.,
this error code is returned if an
open function fails to assign the device.
Illegal monitor call for FILOP. or GETSEG.
There is no room on this file structure or the
disk space quota was exceeded (an overdraw quota
is not considered).
A write-lock error occurred.
The program cannot
write on this device.
Not enough table space is available in the
monitor's free core.
Partial allocation only.
Block not free at allocated position
(ENTER,
RENAME) .
Cannot supersede a directory (ENTER).
Cannot delete a directory that is not empty
(RENAME) .
The sub-file directory was not found
(some SFD
in the specified path was 'not found).
The search list is empty (a LOOKUP or an ENTER
was performed on the generic device DSK and the
search list was empty) .
You cannot create an SFD nested deeper than the
maximum allowed level of nesting.
No file structure in the job's search list has
both the no-create bit and the write-lock bit
equal to zero and has the UFD or SFD specified
by the default or explicit path (ENTER on the
generic device DSK only) .
The program performed a GETSEG from a locked low
segment to a high segment that was not a
dormant, active, or idle segment.
The segment
was not on the swapping space (SAVE. or GETSEG) .
Cannot update file.
Low segment overlaps high segment
(GETSEG or
RUN), or page overlap error (MERGE.)
The user is not logged in (RUN, SAVE.
only).
The file has outstanding locks set.
The file has a bad EXE file directory
(GETSEG,
RUN, MERGE.).
The file has a bad extension for an
.EXE file
(GETSEG, RUN, MERGE.).
The file's EXE directory is too big
(GETSEG,
RUN, MERGE.).
The network capacity has been exceeded;
not
enough space for the connect message (LOOKUP,
ENTER) .
The task was not available
(LOOKUP,
ENTER,
RENAME) .
An unknown network node was
specified,
or the
node went down during the connect (ENTER).
SFD is in use (RENAME)
File has an NDR
(No Delete or Rename)
lock
(FILOP. ) .
Job count high (too many simultaneous accesses) .
Cannot rename SFD to lower level.
Channel not OPENed (FILOP.).

11-60

PROGRAM INPUT AND OUTPUT

47
50
51

ERDDU%
ERDRS%
ERDCM%

52
53
54
55
56

ERDAJ%
ERIDM%
ERUOB%
ERDUM%
ERNPC%

57
60
61
62
63
64
65
66
67
70
71
72

ERNFC%
ERUFF%
ERCTB%
ERCIF%
ERACR%
ERACS%
ERNZA%
ERATS%
ERLBL%
ERDPS%
ERNFS%
ERSII%

Device is not useable; it is offline.
Device is restricted.
Device is under control of Mountable Device
Allocator (MDA) (GALAXY).
Device is allocated to another job.
Illegal data mode specified (FILOP.).
Unknown or undefined bits set (OPEN).
Device is in use on an MPX-controlled channel.
No per-process space available for extended I/O
channel.
No free channels are available.
Unknown FILOP.
function.
Channel too big.
Function illegal on this channel.
Address check occurred while reading arguments.
Address check occurred while storing arguments.
A negative or zero argument count was specified.
Argument block was too short.
Magnetic tape labelling error.
Duplicate segment in address space.
No free section (SEGOP.).
Segment information inconsistent.
A segment
number and name do not match.

11-61

CHAPTER 12

Disks store ordered sets of data called files.
One or more disk units
can be associated by the monitor as file structures. The physical
unit of the disk is generally transparent to users; therefore you do
not need a detailed knowledge of disk units to use disks effectively.
Your system may have several types of disks.
The
monitor's
disk-service routines handle all disk operations,
including file
structuring, executing disk-specific monitor calls, queueing disk
requests, and optimizing disk usage.
The monitor handles all disk file structures as logical units first,
then converts these to physical units in its device-dependent service
routines. All disk addr~sses discussed in this manual are logical, or
relative, addresses, not physical locations on the disk.
The basic unit on the disk is the logical disk block,
which has 200
octal
(128 decimal) 36-bit words of storage. A disk file can be any
length, and you can store as many disk files as your disk quota will
allow.

12.1

DISK NAMES

Each disk file structure has a SIXBIT name; this name is defined by
the operator at system initialization time. A file structure name can
be up to four alphanumeric characters in length, but must not
duplicate any device name, unit name, existing file structure name, or
ersatz device name.
Public file structures names should be of the form DSKn, where n is A
to Z. Public file structures are created by the system administrator
at ONCE-only time.
When your program issues an OPEN, INIT,
or FILOP. monitor call,
it
specifies a file structure. For subsequent LOOKUP or ENTER calls, the
monitor searches only the file structure named in the OPEN,
INIT,
or
FILOP. call that initialized the channel. Therefore, to initialize a
file structure, you must know the name of the file structure that
contains the required file.
Often a program does not initialize a file structure, but instead
initializes the generic disk device name DSK.
The monitor then
searches the user's job search list to determine which file structure
to use.
See Section 12.8 for a discussion of job search lists.

12-1

DISKS (DSK)
12.1.1

Logical Unit Names

If your program specifies a single file structure name (such as DSKA) ,
it is implicitly referring to all units in that file structure.
However, your program can specify a logical unit within a file
structure
in
the
form DSKnm.
n is an alphabetic character
representing structure; m is a unit number.
When your program reads a file, the monitor generalizes a logical unit
specification
(such
as
DSKAO)
to the larger file structure
specification (such as DSKA), which may contain more than one logical
unit (such as DSKAO and DSKAl).
Therefore the monitor will locate the
required file regardless of which logical unit it is on.
When your program writes a file, the monitor places the file on the
logical unit specified if space is available;
if space is not
available, the monitor places the file on another logical unit in the
same file structure.
For example, if you specify DSKAI for a file,
the monitor places the file on DSKAI if there is room;
if not,
it
places it on another logical unit (such as DSKAO) in the same file
structure (DSKA).
Nevertheless, it can be worthwhile to specify logical units for files,
because file processing usually proceeds faster if the files are on
different logical units.

12.1.2

Physical Controller and Disk Unit Names

Your program can refer to a disk by the generic name DSK,
by a file
structure name (such as DSKA) , by a logical unit name (such as DSKAO),
by a controller class name, by a controller designation,
or by a
physical disk unit name.
Controller classes, physical controller names, and the
physical disk units they control are:
o

Controller class RP.
Physical controller
class are of the form RPc, where c is A-Z.

names
names

the

for

this

Physical disk unit names for this class are of the form RPcn,
where c completes the controller name and n is the disk unit
number (in the range 0 to 7). RP designates RH20 controllers
with RP04, RP06, RP07 units, or RHll controllers (KSI0 only)
with RP06 or RM03 units.
o

Controller class RN for RP20 disk devices on a DX20/RH20
controller.
Physical controller names for this class are of
the form RNc, where c is A-Z.
Physical disk unit names for this class are of the form RNcn,
where c completes the controller name; and n is the disk unit
number-(in the range 0 to 15) .

Controller class RA for an RA60, RA80, or RA81 drive on an
HSC-50 controller. Physical controller names for this class
are of the form RAc, where ~ is A-Z.
Physical disk unit names for this class are of the form RAcn,
where c completes the controller name and n is the disk unit
number (in the range 0 to 255) .

12-2

DISKS (DSK)
12.1.3

Abbreviations

You can abbreviate disk names in ASSIGN commands and OPEN,
INIT,
FILOP.,
LOOKUP,
and ENTER monitor calls.
In creating files, the
monitor places the file on the first disk that begins with the
abbreviation you used.
In $earching for files, the monitor searches
all disk units that begin with the abbreviation until it finds the
file.
The LOOKUP/ENTER calls apply to as wide a class of units as
possible. For example, MO might include MONI, MONZ, and MOBY.

12.2

DISK FILE NAMES

A disk file has a file name and an extension.
The file name is a
SIXBIT string of up to 6 characters.
The extension is a SIXBIT string
of up to 3 characters.
Most programs that scan file names accept them in the format
filnam.ext,
where filnam is the file name, and ext is the extension.
The file name cannot be null, but the extension can.
Most programs
that scan file names will interpret a file as having a null extension
if it is written with a period after the file name.
For example,
the
system interprets:
MYFILE.
as the file name and a null extension.
In monitor calls,
you use SIXBIT to specify the file name and
you specify the file TEST.TST in a monitor
extension.
For example,
call as:
SIXBIT/TEST/
SIXBIT/TST/
When you create a file, a file name is associated with the file.
The
name remains associated with the file until you delete or rename the
file.

12.3

DISK FILE PROTECTIONS

Every disk file has a protection code that indicates the users who can
and
cannot
access the file.
The protection code in a file
specification appears as:
<xyz>
Where:

the first digit ~ refers to the owner field.
the second digit y refers
number as the owner.

users

with

the

same

the third digit ~ refers to all other users.
NOTE
Directory files (*.UFD and *.SFD)
are protected by
codes that appear similar to data file protection
codes, but the meaning of the codes is different.
For
information about directory files, refer to Section
12.6.
12-3

project

DISKS (DSK)

The protection code for a file is stored
three 3-bit fields:

its

RIB,

and

contains

The first 3-bit field gives a protection code that determines
access by the owner of the file.

The middle 3-bit field gives a protection
code
that
determines access by users with the same project number as
the owner of the file.

The last 3-bit field gives a protection code that
access for all other users.

determines

When the monitor symbol INDPPN=O (default), the owner of a file is the
user whose project and programmer number matches the User File
Directory containing the file.
The actual definition of a file owner
is set at monitor generation time using the MONGEN program.
(If the
symbol INDPPN is set to <0,,-1> with MONGEN, the owner of the file is
any user whose programmer number matches the UFD containing the
file.)
No matter who an installation defines as a file owner, project
numbers less than 10 are always independent of programmer numbers.
For example, a user having a PPN of [1234,4]
is not considered the
owner of files in [1,4].
The setting of INDPPN can be obtained from
GETTAB Table %CNSTS, bit ST%IND.
The file owner may be protected from inadvertently destroying his
files by the access protection indicated by the first field in the
protection code <nnn>.
The owner protection code also specifies
whether the File Daemon
(FILDAE)
should be called on attempts to
access a file.
Specifically, the digit in the owner field means the
following:
Code

Meaning

Any access is allowed.
The owner can exec1lte,
read,
append to,
update,
write,
rename,
and change the
protection of his file.

Same as code O.

Any access to the file,
allowed.

The owner cannot append to, update,
or write to the
file.
The owner can execute, read, rename, or change
the protection code of the file.

This code is equivalent to 0 and 1.
However,
if the
File Daemon is running, any attempt to access this file
that results in a protection failure will result in a
call to the File Daemon.
(Refer to Section 12.4.)

This code is equivalent to code 2, but the File Daemon
is called on any attempted access that violates the
protection codes.

The owner cannot append to, update, rename, or write to
the file.
The owner can execute, read, or change the
protection code of the file.
The File Daemon is called
on any attempted access that violates the protection
code.

The owner can execute, read, and change the protection
of the file.
The File Daemon is called on any
attempted access that violates the protection code.
12-4

except

for

renaming

it,

DISKS (DSK)
\

Note that codes 4 through 7 speci~¥ that the File Daemon program
should be called when any users (owner or others) attempt to access
the file in a manner that results in ~ violation of the protection
code.
The function of the File Daemon is discussed in Section 12.4.
Table 12-1 illustrates the access allowed to the file owner for each
code.
Capabilities are indicated by Y, prevention against that type
of access is indicated by ~.
Table 12-1:

File Access Protection -- Owner Field

Access Type

EXECUTE
READ
APPEND TO
UPDATE
WRITE
RENAME
CHANGE PROTECTION
CALL FILDAE

Code
0

Y
y
y
y
Y
Y
y

Y
y
y
y
Y
y
y

y
y
y
y
Y

y
y

y
y
y
y
Y

y
y
N

y
y

y
y
y
y
Y
Y
y
Y

N
N

N
y

Y
y

N
y
y

N
N
N
y
y

N
N
N
N
y
y

The second field of the protection code <nnn> applies to users in the
same project group
(that is, having the same project number) as the
owner.
The third field applies to all other PPNs.
The codes for
these fields have the same meaning to be applied to the different
types of users.
The meanings of the codes are:
Code

Symbol

Meaning

.PTCPR

The user is allowed any access to the file.
He
can execute,
read,
append to, update, write,
rename, and change the protection code for the
file.

.PTREN

The user is not allowed to change the protection
of the file.
However,
the user can execute,
read, append to, update, write,
or rename the
file.

.PTWRI

The user is not allowed to rename or change the
protection of the file.
However, the user can
execute, read, append to, update, or write the
file.

.PTUPD

The user cannot write,
rename,
or change the
protection.
However,
the user can execute,
read, append to, or update the file.

.PTAPP

The user cannot update, write, rename, or change
the protection of the file.
However, the user
can execute, read, or append to the file.

.PTRED

The user cannot append to,
update,
write,
rename,
or change the protection of the file.
However, the user can execute or read the file.

12-5

DISKS (DSK)
6

.PTEXO

The user can only execute the file.

.PTNON

The user cannot access the file.

Table 12-2 shows the access allowed and prevented by each
each type of access by project members and by other users.
Table 12-2:

code

for

File Access Protection -- Second and Third Digits

Access Type

EXECUTE
READ
APPEND TO
UPDATE
WRITE
RENAME
CHANGE PROTECTION

Code

Y
Y
Y
Y
Y
Y
Y

Y
Y
Y
Y
Y
Y
N

Y
Y
Y
Y
Y
N
N

Y
Y
Y
Y
N
N
N

Y
Y
Y
N
N
N
N

Y
Y
N
N
N
N
N

Y
N
N
N
N
N
N

N
N
N
N
N
N
N

The greatest protection that a file can have is code 7, and the least
protection is code O.
Usually, the owner's field is a or 1.
It is
always possible for the owner of a file to change the protection code
associated with his file, even Lf the owner's protection code is set
to 7.
Therefore, codes a and 1 are equal when they appear in the
owner's field.
You can change the file access protection code by issuing the RENAME
monitor call,
the FILOP. monitor call with the RENAME option, or the
PROTECT command.
When your program issues an ENTER that does not specify a protection
code and the file does not exist, the monitor substitutes either:
o

The standard protection code.

The default protection code that you specified either by the
SET DEFAULT PROTECTION command or by the SETUUO monitor call.

The normal system standard protection code is 057.
This protection
code prevents users in different projects from accessing another
user's files; however, a standard protection of 055 is recommended for
systems where privacy is not as important as the capability of sharing
files among projects.
In fact, the monitor automatically assigns default protection codes to
system files that it must be able to access.
For SYS:*.SYS files
(those files in directory [1,4] with file extension .SYS) the default
protection code is <157>.
All other files on SYS are assigned
protection code <155>.

12-6

DISKS (DSK)

However, no program should be coded to assume knowledge of the
standard protection code;
it should be obtained through a GETTAB
monitor call.
The relevant GET TAB 'items are:
%LDSTP
%LDUFP
%LDSPP
%LDSYP
%LDSSP

Standard file protection.
Standard directory protection.
Spooled file protection.
Standard SYS protection.
SYS:*.SYS protection.

You can set a default file protection code by using either the SET
DEFAUL,T PROTECTION command or the
. STDEF function of the SETUUO
monitor call.
If you (or your program) set a default protection code
by either of the above methods, the monitor creates the file with the
default code if the ENTER block contains zero in its file protection
code field.
If you
(or your program)
did not specify a default
protection code or specified the SET DEFAULT PROTECTION OFF command,
the monitor creates the file with the installation's default file
protection code.
The SET DEFAULT PROTECTION OFF/ON command turns
off/on the previous setting of the default protection code.
(Refer to
the TOPS-10 Operating System Commands Manual for more information on
the SET DEFAULT PROTECTION command.)
Programs that set a default
protection code should GETTAB the installation's default protection
code
(unless FILDAE has specified otherwise) and then set the user
default protection code to that returned on the GETTAB, if the default
protection code is desired.

12.4

THE FILE DAEMON

A File Daemon is
functions:

(FILDAE)

privileged

Oversees file accessing

Aids in accounting

Tracks program use

program

that

serves

the

following

DIGITAL provides and supports the interface to a File Daemon.
DIGITAL
provides
but
does
not support a File Daemon
(FILDAE);
each
installation should write and support its own File Daemon to meet its
own rE~quirements.
When a File Daemon is running, the monitor calls it every time someone
tries to access a
file that has a
4, 5, 6, or 7 in the owner's
protection code field and the access fails due to a protection error.
The ~lonitor also calls a File Daemon for a directory when attempted
access fails due to a protection error.
(Appendix C contains a
description of the File Daemon and the ACCESS.USR file.)

12-7

DISKS (DSK)
12.5

DISK FILE FORMATS

A disk file contains the data that makes up the file, and information
that the monitor needs to retrieve the file.
Each disk block is 200
(octal) words long.
The monitor writes a full block on each disk write (when your program
outputs a buffer).
Any unused portion of the block is filled with
zeros, but the monitor keeps track of the actual length of the last
block in the file only.
Therefore, if your program outputs a buffer
that is not full, the block is filled with zeros; but on reading the
block, it will appear to be a full block of data.
The first data block for a file is pointed to by an entry in the
retrieval information block (RIB) for the file.
The RIB is pointed to
by an entry in a UFD or an SFD.
Thus there is a
chain from the
directory through the RIB to the first block of the file.

1
PPN
1
1------------1
--------------Data
1 UFD 1 CFP 1----->1
1
Blocks
------1------1
RIB
1
---------1
1------>1
---------------

Figure 12-1:

Disk Chain

The RIB for a file contains pointers to the entire file.
At the
physical end of a file (unless it is open), there is a copy of the RIB
for the file.
This spare RIB is the block immediately following the
last data block of the file.
Users are not allowed to access the
spare RIB.
Thus the file has two overhead RIB blocks:
one for the
prime RIB (in relative block 0) and one for the spare RIB (in the last
relative block of the file) .

12.6

DISK DIRECTORIES

A directory is itself a file; it serves as an index to other files
on
a device.
You can read a directory like any other file, but you
cannot write a directory.
Each fi18 structure has directories
arranged in a tree structure of three levels:
1.

The Master Flle Directory (MFD) is at the root of the tree.
It serves as an index to User File Directories (UFDs) on the
file structure.

The User File Directories (UFDs) are at the next level of the
tree structure.
UFDs contain pointers to and data about user
files and subfile directories (SFDs).

Subfile Directories (SFDs) are at the remaining levels of the
tree structure.
SFDs contain pointers to and data about user
files and subordinate SFDs.

The general disk file organization for a file structure
Figure 12-2.

12-8

shown

DISKS (DSK)
Haster File
Directory

User File
Directories

/-----------------\
1
1
1

------

\->

1
1
1

--I

UFD

/----->

File 1

Ext

------------->1

------------

---------->1
-----1---1
Ext

------/

UFD

-----1---File 2

1
1

Data
Files

UFD

1---

------------

------\

-----1-----

File 3

Ext 1

-----1----1

-------> 1

1
1

1---

1
1

-----------

\----->1
.~

File x

---------Ext

------------->1

-----1----

1
1

File y

------------

Ext

---------->1

-----1---File z

-----1----1

-------> 1

1
1

1---

------------

Ext

1---

1
1
1

Figure 12-2:
12.6.1

General Disk File Organization for a File Structure

The Master File Directory (MFD)

The Master File Directory is a directory of all the individual user
file directories on the file structure.
It consists of 2-word
entries.
Each entry gives the name and address of a user file
directory (UFD) in the file structure.
Each entry in the MFD is in the format:
XWD
XWD
Where:

proj,prog
'UFD' ,CFP
~

;Project-programmer number
;UFD"compressed file pointer to UFD

and ~ give the project-programmer number (PPN)

for

UFD.
UFD is the name of the UFD in SIXBIT.
The Compressed File
Pointer
(CFP)
is the supercluster number of the RIB for the
UFD.

12-9

DISKS (DSK)

The MFD contains an entry for each UFD on the system.
A "continued
MFDil is the set of all MFDs for all file structures in a job's search
list.

12.6.2

User File Directories (UFDs)

User File Directory (UFD) is a list of the names of files existing
in a given project-programmer area within the file structure.
It
consists of 2-word entries.
Each entry gives the name and address of
a user file, or a Subfile Directory (SFD)

Each entry in the UFD is in the format:
SIXBIT
XWD
Where:

/filename/
'extension' ,CFP

;File name
;Extension"CFP to file

file name is a SIXBIT file name of up to six characters.
extension is
characters.

SIXBIT

file

extension

three

CFP is the compressed file pointer to the RIB of the file.
A
continued UFD is the set of all UFDs on all file structures in
the job's search list for the given PPN.
When you log in, each file structure on which you have disk space
contains a UFD for your PPN.
Each UFD indexes your files for that
file structure only.
UFDs are created by programs, such as LOGIN, CREDIR, and PULSAR when
Only
the program is run in a privileged account, such as [1,2].
privileged programs can create UFDs, and only the monitor can write
UFD data.
Any program can attempt to read a UFD.
Whether the attempt succeeds
depends on the directory protection code for the UFD.
See Section
12.7 for a discussion of directory protections.

12.6.3

Subfile Directories (SFDs)

A Subfile Directory (SFD) consists of 2-word entries in the same
format as a UFD entry.
The UFD or a superior SFD points to an SFD;
each SFD entry points to a user file or to a subordinate SFD.
Unlike
UFDs,
SFDs can be created by any program.
Figure 12-3 illustrates
file organization.
The maximum number of levels for SFDs (which cannot be more than five)
is a MaNGEN parameter; you can obtain this value from the right half
of the item %LDSFD in the GETTAB Table .GTLVD. A "continued SFD" is
the set of all SFDs on all file structures in a job's search list that
have the same PPN and directory path.
See Section 12.6 for a
discussion of directory paths.
SFDs can be useful to your programs because they allow you to organize
files in your area; for example, you might group files according to
their functions.
Files that have the same name, but are in different
SFDs, are uniquely identifiable.
Therefore simultaneous batch runs of
the same program for a single user can use the same file names without
conflicting with each other.

12-10

DISKS (DSK)
You can create subfile directories by using the CREDIR program,
which
is described in the TOPS-10 User utilities Manual.
You can delete
SFOs using either the OELETE command or the delete function of the
RENAME: call.
Note, however, that an error will occur if you try to
deletel an SFO when it is included in your job's default path in your
job search list, or when it contains files.

12.6. -41

Directory Paths

A disk file is uniquely identifiable by a string giving its file
struct.ure name,
its directory path, and its file name and extension.
The directory path is an ordered list of directory names
(without
regard to file structure).
This path always begins with a UFO.
Your program can use the PATH. monitor call to read or set the default
directory path for your job. A default path can contain any of the
follo'iiring:
o

Your job's UFD.

Your job's UFO and one or more SFOs in a chain originating in
your UFO.

A UFO different from your job's UFO.

A UFO different from your job's UFD and one or more SFDs in a
chain originating in that UFD.
specify

projno and progno give the project-programmer number,
UFO.

the

sfd1 is the name of a subfile directory pointed to by
in t.he UFD.

file

sfd2 is the name of a subfile directory pointed to by
in sfd1 and so forth.

file

The initial default path for a
job is your UFO.
different path, you must give the path in the format:

[projno,progno,sfd1,sfd2, ... ]
Where:

For example, if you have not changed the initial default path for your
job, t~hen the commands
.R MACRO
j,:FOO . REL=FOO . MAC
specif:y the files FOO.REL and FOO.MAC in your job's UFD (that is, your
PPN) .
HowevE~r,

you can specify a different path.

The commands:

.R MACRO
*FOO.REL=MINE:FOO.MAC[27,5031,OLO]
specify FOO.REL in your UFD and FOO.MAC in the SFD called OLD
UFD for PPN [27,5031] on the file structure MINE:.

12-11

the

DISKS (DSK)
12.6.5

Pathological Device Names

TOPS-10 allows logical names for disk directory paths, as well as for
specific devices.
The logical name for a device can be obtained using
the DEVNAM monitor call. A logical name for a directory path is
called a "pathological name." You can obtain the pathological name for
a device using the PATH. monitor call, .PTFRN function.
You can set
pathological names using the DEVLNM monitor call,
or the .PTFSN
function of the PATH. monitor call.
You can use the PATH. monitor call to define, read, and delete logical
path names.
You could define the pathological name to be a path
including multiple file structures, UFDs, and SFDs.
For example,
to
define FOO:
to be the pathological name for the following:
DSKB: [10, 664,A] ,ALL: [10,675] ,NEW: [27,4072]
you could issue the following monitor call:

MOVE
PATH.
JRST
JRST
ARGLST:

AC1, [XWD ARGLEN,ARGLST]
AC1,
ERR

NORM

EXP .PTFSN
EXP
SIXBIT /FOO/
EXP
SIXBI'r /DSKB/
EXP 0
EXP 0
XWD 10,664
SIXBIT /A/
EXP 0
EXP 0
SIXBIT /ALL/
EXP 0
EXP 0
XWD 10,675
EXP 0
EXP 0
SIXBIT /NEW/
EXP 0
EXP 0
XWD 27,4072
EXP
EXP 0
EXP 0
ARGLEN = .-ARGLST

°
°

Refer to Figure 12-3.

The path for File A is:

X.MAC[10,63]

12-12

DISKS (DSK)
The path for File B is:
Z.ALG[14,5,M]
OSK: [1, 1] . UFO

/
/

[14,5] . UFD

[10, 63] . UE'D

-------

I
I
I
I
I
I
I,

X.MAC

[20,7] . UFO

\
------B

------Y.CB

M.SFO

Z.ALG
Figure 12-3:

Directory Paths on a Single File Structure

Refer to Figure 12-4.

The job's search list in this figure is:

DSKA, DSKB, DSKC
The job's default path is:
[PPN,A,B,C]/SCAN
The following describes the order of the monitor's search when the job
issues LOOKUP and ENTER monitor calls.
The order of the search for a
file with /SCAN set by SETSRC, is:
1.

DSKA: [PPN,A,B,C]

DSKB: [PPN,A,B,C]

DSKC: [PPN,A,B,C]

DSKA: [PPN,A,B]

DSKB: [PPN,A,B]

DSKC: [PPN;A,B]

DSKA: [PPN,A]

DSKB: [PPN, A]

12-13

DISKS (DSK)

DSKC:[PPN,A]

10.

DSKA: [PPN]

11.

DSKB: [PPN]

12.

DSKC: [PPN]

If any of these SFDs do not exist, the search step involving it is
omitted.
Therefore,
if DSKC:A.SFD[PPN] does not exist, Steps 3, 6,
and 9 are omitted.
If /SCAN is not set,
Steps 4 through 12 are
omitted.
If the file exists in multiple directories, the search ends
with the first occurrence found.

DSK

DSKA: [1,1] . UFD

DSKB: [1,1] . UFD

DSKC: [1, 1] . UFD

DSKA:PPN.UFD

DSKB:PPN.UFD

DSKC:PPN.UFD

File1

A.SFD

Y.SFD

File1

B.SFD

File4
File2

File3

B.SFD

File6

C.SFD

D.SFD

File2

File4

D.SFD

File7

File6

File2

FileS

Figure 12-4:

Directory Paths on Multiple File Structures

12-14

FileS

DISKS (DSK)
Refer to Figure 12-~. LOOKUP on SIXBIT/DSK/ with no
in the search that is indicated.

matches

results

DSK

DSKB: [1,1] . UFD

DSKA: [1,1] . UFD

DSKA:PPN.UFD

DSKC: [1,1] . UFD

----------> DSKB:PPN.UFD -----> DSKC:PPN.UFD

I
\-----------\

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

\
\

A.SFD -------> A.SFD

Filel

Y.SFD

I
\---------\
File3

B.SFD -------> B.SFD

File6

\---------\

Figure 12-5:

C.SFD -------> C.SFD

D.SFD

File7

File2

D.SFD

File4

FileS

B.SFD

File4

\
File2

File1

LOOKUP on DSK with No Matches

12-15

FileS

DISKS (DSK)

Refer to Figure 12-6.
LOOKUP on SIXBIT/DSK/ and SIXBIT/FILE2/ results
in DSKA:FILE2[PPN,A,B].
LOOKUP on SIXBIT/DSKB/ and SIXBIT/FILE2/ or LOOKUP on SIXBIT/DSKC/ and
SIXBIT/FILE2/ fails.
ENTER on SIXBIT/DSK/ and SIXBIT/FILE9/ results in an error because no
file structure has both the no-create bit cleared and the directory
structure [PPN,A,B,C,D].

DSK

DSKA: [1, 1] . UFD - - - \
I
I

DSKB: [1, 1] . UFD

DSKC: [1,1] .UFD

DSKA,: PPN. UFD ------\
-------------I
I
I
I

DSKB:PPN.UFD

DSKC:PPN.UFD

-------------- <--I

<--I

File1

File2

File3

A.SFD -----\
I
I
I
I
I
B.SFD <----/

A.SFD

Y.SFD

B.SFD

File6

C.SFD

D.SFD

File?

File2

I
I
I
\-----------/

File2

File4

D.SFD

FileS

Figure 12-6:

B.SFD

File4

r..

C.SFD

File1

LOOKUP on DSK for FILE2

12-16

FileS

DISKS

(DSK)

Refer to Figure 12-7. ENTER on SIXBIT/DSKA/ and SIXBIT/FILE1/ results
in the file being created at the .end of the path on DSKA.

DSK

DSKA: [1,1] . UFD

DSKB: [1,1] . UFD

DSKC: [1,1] .UFD

DSKA:PPN.UFD

DSKB:PPN.UFD

DSKC:PPN.UFD

A.SFD

File1

Y.SFD

File1

B.SFD

File4
File2

File3

C.SFD

File4

B.SFD

<----- I

File2

I
I
I
D.SFD--/

FileS

File1

C.SFD

D.SFD

File7

File2

=====
=====

Figure 12-7:

File6

ENTER on DSKA for FILE1

12-17

FileS

DISKS (DSK)

Refer to
Figure
DSKB: [PPN,A,B, C],
fashion.

12-8.
When
the following

ENTER on SIXBIT/DSK/ and
created on DSKB.

the
calls

SIXBIT!FILE6/

job's
default
results in the
results

the

path
is
described
file

being

DSK

DSKA: [1, 1] . UFD

DSKB: [1, 1] . UFD

DSKC: [1,1] .UFD

DSKA:PPN.UFD

DSKB:PPN.UFD

DSKC:PPN.UFD

Filel

A.SFD

Y.SFD

File1

B.SFD

File4
File2

File3

B.SFD

File6

C.SFD

D.SFD

File2

D.SFD

File7

File6
=====

File4

FileS

Figure 12-8:

Filel

ENTER on DSK for FILE6

12-18

File2

FileS

DISKS (DSK)
ENTER on SIXBIT/OSK/
and
SIXBIT/FILE2/
OSKA:FILE2[PPN,A] as shown in Figure 12-9.

supersedes

FILE2

OSK

OSKA: [1,1] .UFO

OSKB: [1, 1] . UFO

DSKC: [1, 1] . UFO

OSKA:PPN.UFO

OSKB:PPN.UFO

OSKC:PPN.UFO

A.SFO

File1

Y.SFO

File1

B.SFO

File4
-=-=-

File2

-=-=-

File4

File3

B.SFO

File6

C.SFO

O.SFO

File2

O.SFO

FileS

File1

Figure 12-9:

File7

File6

ENTER on DSK for FILE2

12-19

File2

FileS

DISKS· (DSK)

ENTER on SIXBIT/DSK/ and SIXBIT/FILE7/ supersedes FILE7
illustrated in Figure 12-10.

DSKB,

DSK

DSKA: [1, 1] . UFD

DSKB: [1, 1] . UFD

DSKC: [1, 1] . UFD

DSKA:PPN.UFD

DSKB:PPN.UFD

DSKC:PPN.UFD

File1

A.SFD

Y.SFD

File1

B.SFD

File4
File2

File3

B.SFD

File6

C.SFD

D.SFD

File2

File4

D.SFD

File7

File6

File5

Figure 12-10:

ENTER on DSK for FILE7

12-20

File2

File5

DISKS (DSK)
Example
Assume that you set up the following path:
MOVE
PATH.
HALT
MOVE
PATH.
HALT

AC1, [XWD 5,A]
AC1,
AC1, [XWD 3,B]
AC1,

.PTFSD
;Define default path
.PTSCY
;Scanning in effect
10,,63
;UFD=[10,63]
SIXBIT/NAME/
;SFD=NAME
o
;Default path is 10,63,NAME

.PTFSL
;Define additional path
PT.SNW + PT.SSY
;NEW: and SYS:
10,,7
;User library

If you then logged-in as a [10,10]
job and performed a LOOKUP
DSK:FILTST.EXT, the following directories would be searched:
[10, 63,NAME]
[10,63]
[10,7]

;Your search list

[1,5]
[1,4]

;System search list

If you are logged-in as a [10,10] job and your program performs a
LOOKUP
on DSK:PRJFIL.EXT[10,155],
the following directories are
searched:
[10,155]
[10,7]

;Your search list

[1,5]
[1, 4]

12.7

;System search list

DISK DIRECTORY PROTECTIONS

The ability of a program to create files in a directory is controlled
by the protection code for the directory.
The directory can be a UFD
or an SFD.
By changing the protection code associated with a directory you can
also specify a class of users who cannot LOOKUP any file in the
directory.
This specification is independent of the specification of
individual files' protection codes.

12-21

DISKS (DSK)

Directories may be read in the same manner as any other file.
The
right to read a directory as a file is also controlled by the
directory's protection code.
Note that directory files cannot be
explicitly written;
therefore,
the only operations possible are the
following:
o

LOOKUPs for files in the directory (PT.LOK).

Creates (ENTERs and
(PT. CRE)

Reads for the directory itself (PT.SRC).

RENAMEs)

for

files

the