Trailing-Edge
-
PDP-10 Archives
-
tops10v704_docb
-
10,7/docupd/mcv1.mem
There is 1 other file named mcv1.mem in the archive. Click here to see a list.
TOPS-10
Monitor Calls Manual
Volume 1
|
|
| Electronically Distributed
|
|
|
| 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 supercedes the TOPS-10 Monitor Calls
| Manual, Volume 1 published in October, 1988. The
| order number for that manual, AA-0974G-TB, is
| obsolete.
Operating System: TOPS-10 Version 7.04
Software: GALAXY Version 5.1
digital equipment corporation marlborough, massachusetts
| TOPS-10 Software Update Tape No. 03, September 1990
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 only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.
Copyright C 1975, 1984, 1988, 1990 Digital Equipment Corporation.
All Rights Reserved.
The following are trademarks of Digital Equipment Corporation:
CI DECtape LA50 SITGO-10
DDCMP DECUS LN01 TOPS-10
DEC DECwriter LN03 TOPS-20
DECmail DELNI MASSBUS TOPS-20AN
DECnet DELUA PDP UNIBUS
DECnet-VAX HSC PDP-11/24 UETP
DECserver HSC-50 PrintServer VAX
DECserver 100 KA10 PrintServer 40 VAX/VMS
DECserver 200 KI Q-bus VT50
DECsystem-10 KL10 ReGIS
DECSYSTEM-20 KS10 RSX d i g i t a l
CONTENTS
PREFACE
CHAPTER 1 INTRODUCTION TO MONITOR CALLS
1.1 MONITOR CALL SYMBOLS . . . . . . . . . . . . . . . 1-3
1.2 PROCESSING MODES . . . . . . . . . . . . . . . . . 1-3
1.2.1 User Mode . . . . . . . . . . . . . . . . . . . 1-4
1.2.2 Executive Mode . . . . . . . . . . . . . . . . . 1-4
1.2.3 User I/O Mode . . . . . . . . . . . . . . . . . 1-5
CHAPTER 2 MEMORY
2.1 MEMORY ALLOCATION . . . . . . . . . . . . . . . . 2-1
2.2 USER-MODE EXTENDED ADDRESSING . . . . . . . . . . 2-3
2.3 USER MEMORY . . . . . . . . . . . . . . . . . . . 2-4
2.4 CONTROLLING PROGRAM SEGMENTS . . . . . . . . . . . 2-5
2.4.1 Adjusting the Size of Segments . . . . . . . . . 2-6
2.4.2 Merging Low Segments . . . . . . . . . . . . . . 2-6
2.4.3 Writing Into High Segments . . . . . . . . . . . 2-6
2.4.4 Testing for a Sharable High Segment . . . . . . 2-7
2.4.5 Finding the Origin of a High Segment . . . . . . 2-7
2.4.6 Modifying a High Segment and Meddling . . . . . 2-8
2.5 RUNNING A PROGRAM . . . . . . . . . . . . . . . 2-10
2.5.1 Functions of RUN and GETSEG . . . . . . . . . 2-10
2.5.2 Reading Command Files . . . . . . . . . . . . 2-13
2.6 CONTROLLING PAGES . . . . . . . . . . . . . . . 2-14
2.6.1 Handling Page Faults . . . . . . . . . . . . . 2-14
2.6.2 The System's Page Fault Handler . . . . . . . 2-15
2.6.3 Building Your Own Page Fault Handler . . . . . 2-15
2.7 LOCKING AND UNLOCKING A JOB IN MEMORY . . . . . 2-17
CHAPTER 3 JOB CONTROL
3.1 EXECUTING A PROGRAM . . . . . . . . . . . . . . . 3-1
3.1.1 Starting a Program . . . . . . . . . . . . . . . 3-2
3.1.2 Stopping a Program . . . . . . . . . . . . . . . 3-3
3.1.3 Suspending a Program . . . . . . . . . . . . . . 3-3
3.2 CONTROLLING MULTIPLE JOB CONTEXTS . . . . . . . . 3-4
3.3 RUNTIMES, TIMES, AND DATES . . . . . . . . . . . . 3-5
3.3.1 Runtimes . . . . . . . . . . . . . . . . . . . . 3-6
3.3.2 The System Date . . . . . . . . . . . . . . . . 3-6
3.3.3 The Universal Date . . . . . . . . . . . . . . . 3-7
3.3.4 The System Time . . . . . . . . . . . . . . . . 3-7
3.3.5 Date-Time Elements from GETTAB Tables . . . . . 3-8
iii
CHAPTER 4 THE JOB DATA AREA
4.1 JOB DATA IN THE LOW SEGMENT . . . . . . . . . . . 4-1
4.2 JOB DATA IN THE HIGH SEGMENT . . . . . . . . . . . 4-5
CHAPTER 5 NETWORKS
5.1 ANF-10 NETWORK MONITOR CALLS . . . . . . . . . . . 5-3
5.2 ANF-10 INTERTASK COMMUNICATION . . . . . . . . . . 5-4
5.2.1 Initiating a Connection . . . . . . . . . . . . 5-5
5.2.1.1 Using the LOOKUP/ENTER UUOs . . . . . . . . . 5-5
5.2.1.2 Using the TSK. UUO . . . . . . . . . . . . . . 5-6
5.2.2 Sending and Receiving Between Tasks . . . . . . 5-8
5.2.3 Breaking the Intertask Communication . . . . . . 5-9
5.3 TASK TO TASK PROGRAMMING WITH DECnet-10 . . . . . 5-9
5.3.1 Specifying a Destination Task . . . . . . . . 5-12
5.3.2 Specifying a Source Task . . . . . . . . . . . 5-15
5.3.3 Reading the Connect Information . . . . . . . 5-17
5.3.4 Accepting the Connection . . . . . . . . . . . 5-19
5.3.5 Rejecting the Connection . . . . . . . . . . . 5-20
5.3.6 Reading the Connect Confirm Data . . . . . . . 5-20
5.3.7 Reading the Status of the Link . . . . . . . . 5-21
5.3.8 Using the PSI System . . . . . . . . . . . . . 5-24
5.3.9 Setting the PSI Reason Mask . . . . . . . . . 5-24
5.3.10 Enabling the PSI Interface . . . . . . . . . . 5-25
5.3.11 Reading and Setting the Link Quota and Goal . 5-26
5.3.12 Transferring Information Over the Network . . 5-27
5.3.13 Sending Normal Data . . . . . . . . . . . . . 5-28
5.3.14 Receiving Normal Data . . . . . . . . . . . . 5-29
5.3.15 Sending Interrupt Data . . . . . . . . . . . . 5-31
5.3.16 Receiving Interrupt Data . . . . . . . . . . . 5-32
5.3.17 Closing a Network Connection . . . . . . . . . 5-32
5.3.18 Releasing a Channel . . . . . . . . . . . . . 5-34
5.3.19 Aborting a Connection . . . . . . . . . . . . 5-35
5.3.20 Reading the Disconnect Data . . . . . . . . . 5-35
5.4 OBTAINING INFORMATION ABOUT DECNET-10 . . . . . 5-36
5.5 ETHERNET NETWORKS . . . . . . . . . . . . . . . 5-43
5.5.1 Transmitting and Receiving Information . . . . 5-44
5.5.2 Returned Channel Information . . . . . . . . . 5-45
5.5.3 Returned Portal Information . . . . . . . . . 5-47
5.5.4 Returned Controller Information . . . . . . . 5-48
CHAPTER 6 TRAPPING, INTERCEPTING, AND INTERRUPTING
6.1 TRAPPING ERRORS AND CONDITIONS . . . . . . . . . . 6-2
6.2 INTERCEPTING ERRORS . . . . . . . . . . . . . . . 6-4
6.2.1 Using the .JBINT Intercept Block . . . . . . . . 6-5
6.2.2 Examples of Error Intercepts . . . . . . . . . . 6-7
6.3 USING PROGRAMMED SOFTWARE INTERRUPTS . . . . . . . 6-8
6.3.1 PSI Monitor Calls . . . . . . . . . . . . . . 6-11
iv
6.3.2 Interrupt Control Block . . . . . . . . . . . 6-12
6.3.3 Interrupt Conditions . . . . . . . . . . . . . 6-14
6.3.4 Example Using Programmed Interrupts . . . . . 6-19
CHAPTER 7 COMMUNICATING BETWEEN PROCESSES USING IPCF
7.1 PACKETS . . . . . . . . . . . . . . . . . . . . . 7-2
7.2 FORMAT OF THE PHB . . . . . . . . . . . . . . . . 7-2
7.2.1 IPCF Instruction Flags . . . . . . . . . . . . . 7-4
7.2.2 IPCF Packet Descriptor Flags . . . . . . . . . . 7-5
7.2.3 Process Identifiers . . . . . . . . . . . . . . 7-7
7.2.4 Symbolic Names . . . . . . . . . . . . . . . . . 7-7
7.2.5 IPCF Capability Word . . . . . . . . . . . . . . 7-9
7.3 LONG-FORM MESSAGES . . . . . . . . . . . . . . . . 7-9
7.4 QUOTAS . . . . . . . . . . . . . . . . . . . . . 7-10
7.5 SENDING AN IPCF PACKET USING IPCFS. UUO . . . . 7-10
7.6 RETRIEVING AN IPCF PACKET USING IPCFR. UUO . . . 7-11
7.7 QUERYING THE NEXT IPCF PACKET USING IPCFQ. UUO . 7-12
7.8 SYSTEM PROCESSES . . . . . . . . . . . . . . . . 7-13
7.8.1 [SYSTEM]INFO . . . . . . . . . . . . . . . . . 7-13
7.8.2 [SYSTEM]IPCC . . . . . . . . . . . . . . . . . 7-18
CHAPTER 8 RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.1 REQUESTING A RESOURCE . . . . . . . . . . . . . . 8-3
8.1.1 Sharable Resources . . . . . . . . . . . . . . . 8-3
8.1.1.1 Resource Pools . . . . . . . . . . . . . . . . 8-4
8.1.1.2 Partitioned Resources . . . . . . . . . . . . 8-5
8.1.2 Multiple-Lock Requests . . . . . . . . . . . . . 8-6
8.1.2.1 ENQ. Quotas . . . . . . . . . . . . . . . . . 8-6
8.1.2.2 Request Levels . . . . . . . . . . . . . . . . 8-6
8.1.3 Granting Locks . . . . . . . . . . . . . . . . . 8-7
8.1.3.1 ENQ. Software Interruption . . . . . . . . . . 8-7
8.1.3.2 Time Limits . . . . . . . . . . . . . . . . . 8-8
8.1.3.3 Deadlock Detection . . . . . . . . . . . . . . 8-8
8.2 RELEASING RESOURCES . . . . . . . . . . . . . . . 8-9
8.3 PASSING DATA TO OTHER JOBS . . . . . . . . . . . . 8-9
8.4 ENQ/DEQ MONITOR CALLS . . . . . . . . . . . . . 8-11
8.5 BUILDING REQUESTS . . . . . . . . . . . . . . . 8-11
8.6 QUEUEING REQUESTS: ENQ. UUO . . . . . . . . . . 8-15
8.6.1 Requesting and Waiting for Locks . . . . . . . 8-16
8.6.2 Requesting Locks Only if Available . . . . . . 8-16
8.6.3 Requesting and Interrupting when Locked . . . 8-16
8.6.4 Modifying a Previous Request . . . . . . . . . 8-17
8.7 DEQUEUEING REQUESTS: DEQ. UUO . . . . . . . . . 8-17
8.7.1 Cancelling a Specific Request . . . . . . . . 8-18
8.7.2 Cancelling All Requests for a Job . . . . . . 8-18
8.7.3 Cancelling Requests Based on Request-id . . . 8-19
8.8 CONTROLLING ENQ/DEQ: ENQC. UUO . . . . . . . . . 8-19
8.8.1 Obtaining the Status of a Request . . . . . . 8-20
v
8.8.2 Obtaining the Quota for a Job . . . . . . . . 8-22
8.8.3 Setting the Quota for a Job . . . . . . . . . 8-22
8.8.4 Dumping the ENQ. Database . . . . . . . . . . 8-23
8.9 ENQ. ERRORS . . . . . . . . . . . . . . . . . . 8-25
8.10 EXAMPLE USING THE ENQ. FACILITY . . . . . . . . 8-27
CHAPTER 9 PROGRAMMING FOR REALTIME EXECUTION
9.1 CONNECTING REALTIME DEVICES . . . . . . . . . . . 9-2
9.1.1 Normal Block Mode . . . . . . . . . . . . . . . 9-8
9.1.2 Fast Block Mode . . . . . . . . . . . . . . . 9-10
9.1.3 Single Mode . . . . . . . . . . . . . . . . . 9-12
9.1.4 EPT Mode . . . . . . . . . . . . . . . . . . . 9-15
9.1.5 Exec-Mode Trapping . . . . . . . . . . . . . . 9-15
9.2 USING RTTRP AT THE INTERRUPT LEVEL . . . . . . . 9-18
9.3 RELEASING REALTIME DEVICES . . . . . . . . . . . 9-18
9.4 DISMISSING REALTIME INTERRUPTS . . . . . . . . . 9-18
9.5 ASSIGNING RUN QUEUES . . . . . . . . . . . . . . 9-18
9.6 SUSPENDING OTHER JOBS . . . . . . . . . . . . . 9-19
CHAPTER 10 ANALYZING SYSTEM PERFORMANCE
10.1 THE PERFORMANCE FACILITY: PERF. . . . . . . . . 10-1
10.1.1 Performance Modes . . . . . . . . . . . . . . 10-1
10.1.2 Performance Enable Flags . . . . . . . . . . . 10-2
10.1.3 PERF. Functions . . . . . . . . . . . . . . . 10-3
10.1.3.1 Initializing the Performance Meter . . . . . 10-4
10.1.3.2 Starting the Performance Meter . . . . . . . 10-6
10.1.3.3 Reading the Performance Meter . . . . . . . 10-6
10.1.3.4 Stopping the Performance Meter . . . . . . . 10-6
10.1.3.5 Releasing the Performance Meter . . . . . . 10-7
10.1.4 Background PERF. Functions . . . . . . . . . . 10-7
10.1.5 PERF. Errors . . . . . . . . . . . . . . . . . 10-7
10.2 THE SNOOP FACILITY: SNOOP. . . . . . . . . . . . 10-8
10.2.1 Defining Breakpoints . . . . . . . . . . . . . 10-10
10.2.2 Inserting Breakpoints . . . . . . . . . . . . 10-11
10.2.3 Removing Breakpoints . . . . . . . . . . . . . 10-11
10.2.4 Deleting Breakpoint Definitions . . . . . . . 10-11
10.2.5 SNOOP. Error Codes . . . . . . . . . . . . . . 10-12
CHAPTER 11 PROGRAM INPUT AND OUTPUT
11.1 OVERVIEW OF THE I/O PROCESS . . . . . . . . . . 11-1
11.2 INITIALIZING A PROGRAM . . . . . . . . . . . . . 11-2
11.3 INITIALIZING A DEVICE . . . . . . . . . . . . . 11-3
11.3.1 TOPS-10 Devices . . . . . . . . . . . . . . . 11-3
11.3.2 Device Names . . . . . . . . . . . . . . . . . 11-4
11.3.2.1 Generic Device Names . . . . . . . . . . . . 11-6
11.3.2.2 Physical Device Names . . . . . . . . . . . 11-7
vi
11.3.2.3 Logical Device Names . . . . . . . . . . . . 11-7
11.3.2.4 Ersatz Device Names . . . . . . . . . . . . 11-8
11.3.2.5 Pathological Device Names . . . . . . . . . 11-10
11.3.3 Universal Device Indexes . . . . . . . . . . . 11-10
11.3.4 MPX-Controlled Devices . . . . . . . . . . . . 11-11
11.3.5 Spooled Devices . . . . . . . . . . . . . . . 11-11
11.3.6 Restricted Access Devices . . . . . . . . . . 11-12
11.4 MODES . . . . . . . . . . . . . . . . . . . . . 11-13
11.5 DEFINING A COMMAND LIST . . . . . . . . . . . . 11-15
11.6 SELECTING A FILE . . . . . . . . . . . . . . . . 11-17
11.7 TRANSMITTING DATA . . . . . . . . . . . . . . . 11-18
11.7.1 Output (Writing a File) . . . . . . . . . . . 11-19
11.7.2 Input (Reading a File) . . . . . . . . . . . . 11-23
11.7.3 Writing a File Using FILOP. . . . . . . . . . 11-25
11.7.4 Modifying Files (Update Mode) . . . . . . . . 11-26
11.7.5 Block Pointer Positioning . . . . . . . . . . 11-27
11.7.6 Super USETI/USETO . . . . . . . . . . . . . . 11-29
11.8 RECOVERING FROM ERRORS . . . . . . . . . . . . . 11-30
11.9 USING BUFFERED I/O . . . . . . . . . . . . . . . 11-31
11.9.1 The INBUF and OUTBUF Monitor Calls . . . . . . 11-34
11.9.2 The Buffer Control Block . . . . . . . . . . . 11-35
11.9.3 The Buffer Header Block . . . . . . . . . . . 11-36
11.9.4 Using Buffered Input . . . . . . . . . . . . . 11-37
11.9.4.1 Normal Buffered Input . . . . . . . . . . . 11-39
11.9.4.2 Synchronous Buffered Input . . . . . . . . . 11-39
11.9.4.3 Nonblocking Buffered Input . . . . . . . . . 11-40
11.9.5 Using Buffered Output . . . . . . . . . . . . 11-40
11.9.5.1 Normal Buffered Output . . . . . . . . . . . 11-42
11.9.5.2 Synchronous Buffered Output . . . . . . . . 11-43
11.9.5.3 Nonblocking Buffered Output . . . . . . . . 11-43
11.9.6 Buffered I/O for MPX-Controlled Devices . . . 11-43
11.9.7 Generating Your Own Buffers . . . . . . . . . 11-48
11.10 CLOSING A FILE . . . . . . . . . . . . . . . . . 11-53
11.10.1 Maintaining File Integrity . . . . . . . . . . 11-53
11.11 RELEASING A DEVICE . . . . . . . . . . . . . . . 11-54
11.12 STOPPING A PROGRAM . . . . . . . . . . . . . . . 11-54
11.13 THE LOOKUP/ENTER/RENAME ARGUMENT BLOCKS . . . . 11-54
11.13.1 The Short Form of the Argument List . . . . . 11-55
11.13.2 The Extended Argument List . . . . . . . . . . 11-56
11.14 ERROR CODES . . . . . . . . . . . . . . . . . . 11-70
CHAPTER 12 DISKS (DSK)
12.1 DISK NAMES . . . . . . . . . . . . . . . . . . . 12-1
12.1.1 Logical Unit Names . . . . . . . . . . . . . . 12-2
12.1.2 Physical Controller and Disk Unit Names . . . 12-2
12.1.3 Abbreviations . . . . . . . . . . . . . . . . 12-3
12.2 DISK FILE NAMES . . . . . . . . . . . . . . . . 12-4
12.3 DISK FILE PROTECTIONS . . . . . . . . . . . . . 12-4
12.4 THE FILE DAEMON (FILDAE) . . . . . . . . . . . . 12-9
12.5 DISK FILE FORMATS . . . . . . . . . . . . . . . 12-10
vii
12.6 DISK DIRECTORIES . . . . . . . . . . . . . . . . 12-11
12.6.1 The Master File Directory (MFD) . . . . . . . 12-13
12.6.2 User File Directories (UFDs) . . . . . . . . . 12-13
12.6.3 Subfile Directories (SFDs) . . . . . . . . . . 12-14
12.6.4 Directory Paths . . . . . . . . . . . . . . . 12-14
12.6.5 Pathological Device Names . . . . . . . . . . 12-16
12.7 DISK DIRECTORY PROTECTIONS . . . . . . . . . . . 12-26
12.8 JOB SEARCH LISTS . . . . . . . . . . . . . . . . 12-28
12.9 DISK PRIORITIES . . . . . . . . . . . . . . . . 12-30
12.10 DISK I/O . . . . . . . . . . . . . . . . . . . . 12-31
12.11 DISK I/O PROCESSING . . . . . . . . . . . . . . 12-32
12.12 DUAL-PORT HANDLING . . . . . . . . . . . . . . . 12-34
12.13 ERRORS . . . . . . . . . . . . . . . . . . . . . 12-34
12.13.1 DATA TRANSFER ERRORS . . . . . . . . . . . . . 12-35
12.13.1.1 ECC Correctable Error . . . . . . . . . . . 12-35
12.13.1.2 Non-data Error . . . . . . . . . . . . . . . 12-35
12.13.1.3 Data Error . . . . . . . . . . . . . . . . . 12-35
12.13.2 SEEK AND STATUS ERRORS . . . . . . . . . . . . 12-36
12.13.2.1 Drive Powered Down . . . . . . . . . . . . . 12-36
12.13.2.2 Drive Powered Up . . . . . . . . . . . . . . 12-37
12.13.2.3 Seek Incomplete . . . . . . . . . . . . . . 12-37
12.13.2.4 Hung Device . . . . . . . . . . . . . . . . 12-37
12.13.2.5 Rib Errors . . . . . . . . . . . . . . . . . 12-37
12.13.2.6 RAE Errors . . . . . . . . . . . . . . . . . 12-37
12.14 BAT BLOCKS . . . . . . . . . . . . . . . . . . . 12-38
12.15 DSKRAT . . . . . . . . . . . . . . . . . . . . 12-38
12.16 DISK DATA MODES . . . . . . . . . . . . . . . . 12-38
12.17 DETERMINING THE PHYSICAL ADDRESS OF A BLOCK
WITHIN A DISK FILE . . . . . . . . . . . . . . . 12-39
12.17.1 Buffered Modes . . . . . . . . . . . . . . . . 12-43
12.17.2 Dump Modes . . . . . . . . . . . . . . . . . . 12-43
12.18 DISK I/O STATUS . . . . . . . . . . . . . . . . 12-44
CHAPTER 13 DECTAPES (DTA)
13.1 DECTAPE DEVICE NAMES . . . . . . . . . . . . . . 13-1
13.2 DECTAPE DATA MODES . . . . . . . . . . . . . . . 13-1
13.2.1 Buffered Data Modes . . . . . . . . . . . . . 13-2
13.2.2 Unbuffered Data Modes . . . . . . . . . . . . 13-2
13.2.3 Nonstandard Data Mode . . . . . . . . . . . . 13-3
13.2.4 Semistandard Data Mode . . . . . . . . . . . . 13-3
13.3 DECTAPE I/O . . . . . . . . . . . . . . . . . . 13-4
13.3.1 Monitor Calls for DECtape I/O . . . . . . . . 13-5
13.3.2 Special Argument Lists . . . . . . . . . . . . 13-7
13.3.2.1 Using LOOKUP with DECtapes . . . . . . . . . 13-7
13.3.2.2 Using ENTER with DECtapes . . . . . . . . . 13-9
13.3.2.3 Using RENAME with DECtapes . . . . . . . . . 13-9
13.4 DECTAPE FORMATS . . . . . . . . . . . . . . . . 13-10
13.4.1 Directory Format . . . . . . . . . . . . . . . 13-11
13.4.1.1 Summary of DECtape Directory Block . . . . . 13-12
13.4.1.2 Block-to-File Index . . . . . . . . . . . . 13-14
viii
13.4.1.3 List of File Names . . . . . . . . . . . . . 13-15
13.4.1.4 List of File Extensions . . . . . . . . . . 13-16
13.4.1.5 File Creation Dates . . . . . . . . . . . . 13-17
13.4.1.6 DECtape Label . . . . . . . . . . . . . . . 13-18
13.4.2 Data Block Format . . . . . . . . . . . . . . 13-19
13.5 DECTAPE I/O STATUS . . . . . . . . . . . . . . . 13-20
CHAPTER 14 MAGTAPES (MTA)
14.1 MAGTAPE DEVICE NAMES . . . . . . . . . . . . . . 14-2
14.2 MAGTAPE DATA MODES . . . . . . . . . . . . . . . 14-2
14.3 MAGTAPE I/O . . . . . . . . . . . . . . . . . . 14-4
14.4 MAGTAPE I/O STATUS . . . . . . . . . . . . . . . 14-5
14.5 MODES SET BY .TFMOD . . . . . . . . . . . . . . 14-7
14.6 READ BACKWARDS (TX01, TM02, AND TX02 ONLY) . . . 14-12
14.7 PROGRAMMING I/O TO LABELLED MAGTAPES . . . . . . 14-13
CHAPTER 15 TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
15.1 TERMINAL DEVICE NAMES . . . . . . . . . . . . . 15-1
15.2 TERMINAL DATA MODES . . . . . . . . . . . . . . 15-1
15.3 TERMINAL CHARACTER HANDLING . . . . . . . . . . 15-3
15.4 BREAK CHARACTER SET . . . . . . . . . . . . . . 15-8
15.5 LAT TERMINALS . . . . . . . . . . . . . . . . . 15-10
15.6 TERMINAL CLASSES, TYPES, AND ATTRIBUTES . . . . 15-10
15.6.1 Reading and Setting Terminal Class . . . . . . 15-10
15.6.2 Reading and Setting Terminal Type . . . . . . 15-11
15.6.3 Reading and Setting Terminal Attributes . . . 15-11
15.6.4 Terminal Characteristics Definitions . . . . . 15-12
15.7 TERMINAL I/O . . . . . . . . . . . . . . . . . . 15-13
15.8 NON-BLOCKING TERMINAL I/O . . . . . . . . . . . 15-14
15.9 TERMINAL PAPERTAPE I/O . . . . . . . . . . . . . 15-15
15.9.1 Using Terminal Papertape Input . . . . . . . . 15-15
15.9.2 Using Terminal Papertape Output . . . . . . . 15-16
15.10 TERMINAL I/O STATUS . . . . . . . . . . . . . . 15-16
15.11 PSEUDO-TERMINALS . . . . . . . . . . . . . . . . 15-17
15.11.1 Pseudo-Terminal Names . . . . . . . . . . . . 15-18
15.11.2 Pseudo-Terminal I/O . . . . . . . . . . . . . 15-19
15.12 PSEUDO-TERMINAL DATA MODES . . . . . . . . . . . 15-21
15.13 PSEUDO-TERMINAL I/O STATUS . . . . . . . . . . . 15-21
CHAPTER 16 LINE PRINTERS (LPT)
16.1 LINE PRINTER NAMES . . . . . . . . . . . . . . . 16-1
16.1.1 Controller Names . . . . . . . . . . . . . . . 16-1
16.1.2 Unit Names . . . . . . . . . . . . . . . . . . 16-1
16.2 LINE PRINTER DATA MODES . . . . . . . . . . . . 16-2
16.3 LINE PRINTER I/O . . . . . . . . . . . . . . . . 16-2
16.4 LINE PRINTER I/O STATUS . . . . . . . . . . . . 16-3
ix
CHAPTER 17 CARD READERS (CDR) AND CARD PUNCHES (CDP)
17.1 CARD DEVICE NAMES . . . . . . . . . . . . . . . 17-1
17.2 CARD READER DATA MODES . . . . . . . . . . . . . 17-2
17.3 CARD PUNCH DATA MODES . . . . . . . . . . . . . 17-3
17.4 CARD DEVICE I/O . . . . . . . . . . . . . . . . 17-4
17.5 CARD DEVICE I/O STATUS . . . . . . . . . . . . . 17-4
CHAPTER 18 PAPERTAPE READERS (PTR) AND PUNCHES (PTP)
18.1 PAPERTAPE DEVICE NAMES . . . . . . . . . . . . . 18-1
18.2 PAPERTAPE READER DATA MODES . . . . . . . . . . 18-1
18.3 PAPERTAPE PUNCH DATA MODES . . . . . . . . . . . 18-2
18.4 PAPERTAPE I/O . . . . . . . . . . . . . . . . . 18-3
18.5 PAPERTAPE I/O STATUS . . . . . . . . . . . . . . 18-3
CHAPTER 19 PLOTTERS (PLT)
19.1 PLOTTER DEVICE NAMES . . . . . . . . . . . . . . 19-1
19.1.1 Controller Names . . . . . . . . . . . . . . . 19-1
19.1.2 Unit Names . . . . . . . . . . . . . . . . . . 19-1
19.2 PLOTTER DATA MODES . . . . . . . . . . . . . . . 19-1
19.3 PLOTTER I/O . . . . . . . . . . . . . . . . . . 19-2
19.4 PLOTTER I/O STATUS . . . . . . . . . . . . . . . 19-2
CHAPTER 20 DISPLAY LIGHT PENS (DIS)
20.1 DISPLAY LIGHT PEN NAMES . . . . . . . . . . . . 20-1
20.1.1 Unit Names . . . . . . . . . . . . . . . . . . 20-1
20.2 DISPLAY LIGHT PEN DATA MODES . . . . . . . . . . 20-1
20.3 DISPLAY LIGHT PEN I/O . . . . . . . . . . . . . 20-1
20.4 DISPLAY I/O STATUS . . . . . . . . . . . . . . . 20-3
CHAPTER 21 REMOTE DATA TERMINALS (RDA)
21.1 REMOTE DATA TERMINAL NAMES . . . . . . . . . . . 21-1
21.2 REMOTE DATA TERMINAL I/O . . . . . . . . . . . . 21-2
21.3 REMOTE DATA TERMINAL DATA MODES . . . . . . . . 21-2
21.4 REMOTE DATA TERMINAL I/O STATUS . . . . . . . . 21-2
INDEX
x
FIGURES
6-1 The Software Interrupt Process . . . . . . . . . . 6-9
6-2 Interrupt Control Block . . . . . . . . . . . . 6-12
7-1 Packet Header Block . . . . . . . . . . . . . . . 7-2
8-1 ENQ/DEQ Request Block . . . . . . . . . . . . . 8-15
11-1 Flow Diagram -- I/O Sequence . . . . . . . . . . 11-21
11-2 The Buffer Structure . . . . . . . . . . . . . . 11-32
11-3 Flowchart for Buffered Input . . . . . . . . . . 11-38
11-4 Flowchart for Buffered Output . . . . . . . . . 11-41
11-5 One Buffer in Each of Two Device Chains . . . . 11-45
11-6 Multiple Buffers in Multiple Device Chains . . . 11-46
11-7 One Buffer Moved Back to Free Chain . . . . . . 11-47
12-1 Disk Chain . . . . . . . . . . . . . . . . . . . 12-10
12-2 General Disk File Organization for a File
Structure . . . . . . . . . . . . . . . . . . . 12-12
12-3 Directory Paths on a Single File Structure . . . 12-17
12-4 Directory Paths on Multiple File Structures . . 12-19
12-5 LOOKUP on DSK with No Matches . . . . . . . . . 12-20
12-6 LOOKUP on DSK for FILE2 . . . . . . . . . . . . 12-21
12-7 ENTER on DSKA for FILE1 . . . . . . . . . . . . 12-22
12-8 ENTER on DSK for FILE6 . . . . . . . . . . . . . 12-23
12-9 ENTER on DSK for FILE2 . . . . . . . . . . . . . 12-24
12-10 ENTER on DSK for FILE7 . . . . . . . . . . . . . 12-25
13-1 DECtape Buffer . . . . . . . . . . . . . . . . . 13-2
13-2 DECtape Format . . . . . . . . . . . . . . . . . 13-10
13-3 DECtape Directory Block . . . . . . . . . . . . 13-12
13-4 Directory Block for FILE.MAC . . . . . . . . . . 13-13
13-5 First 83 Words on the DECtape of the Directory
Block . . . . . . . . . . . . . . . . . . . . . 13-14
13-6 Words 83 through 104 of DECtape Directory . . . 13-15
13-7 Words 105 to 126 of the Directory Block . . . . 13-16
13-8 High-Order Three Bits of Creation Date . . . . . 13-17
13-9 Data Block Format . . . . . . . . . . . . . . . 13-19
15-1 PTY I/O . . . . . . . . . . . . . . . . . . . . 15-18
TABLES
5-1 NSP. UUO Functions . . . . . . . . . . . . . . . 5-11
5-2 Allowable Combinations of Task Descriptor Values 5-13
5-3 Fields in .NSACH (status variables) . . . . . . 5-21
5-4 NSP. Connection States . . . . . . . . . . . . . 5-22
6-1 Format of .JBINT Intercept Block . . . . . . . . . 6-6
6-2 Control Flags . . . . . . . . . . . . . . . . . 6-14
6-3 I/O Interrupt Conditions . . . . . . . . . . . . 6-15
6-4 Non-I/O Interrupt Conditions . . . . . . . . . . 6-15
11-1 Ersatz Devices . . . . . . . . . . . . . . . . . 11-9
11-2 Data Modes (Bits 32-35 of the file status word) 11-14
12-1 File Access Protection -- Owner Field . . . . . 12-6
12-2 File Access Protection -- Second and Third Digits 12-8
13-1 LOOKUP/ENTER/RENAME Argument Block for DECtape . 13-8
xi
14-1 9-Track DEC Dump Mode . . . . . . . . . . . . . 14-8
14-2 7-Track Dump Mode . . . . . . . . . . . . . . . 14-9
14-3 9-Track Industry-Compatible Dump Mode . . . . . 14-10
14-4 9-Track SIXBIT Mode . . . . . . . . . . . . . . 14-11
14-5 ANSI ASCII Mode . . . . . . . . . . . . . . . . 14-12
15-1 Terminal Handling of ASCII Characters . . . . . 15-4
15-2 Terminal Characteristics . . . . . . . . . . . . 15-12
PREFACE
The TOPS-10 Monitor Calls Manual is a complete reference set for using
the TOPS-10 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 each 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-10 Monitor Calls Manual, you should
have a basic familiarity with the structure, paging mechanisms, and
hardware of the DECsystem-10. The TOPS-10 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-10 Monitor Calls Manual:
o The DECsystem-10 MACRO Assembler Reference Manual is very
important to an understanding of the methods for programming
in assembly language on TOPS-10. The TOPS-10 monitor calls
xiii
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.
o Restrictions and capabilities of higher-level programming
languages on TOPS-10 are not described in the TOPS-10 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-10.
o 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.
xiv
CHAPTER 1
INTRODUCTION TO MONITOR CALLS
A program written in MACRO-10 assembly language has four types of
statements:
o Pseudo-op statements, such as BLOCK, TITLE, and RADIX, are
instructions to the MACRO assembler and do not generate code.
o Direct-assignment statements, such as T1=1 and P=17, resolve
definitions of symbols. Pseudo-ops and direct-assignment
statements are described in the DECsystem-10 MACRO Assembler
Reference Manual.
o Machine instructions, such as ADD, MOVEM, and JRST, are
direct hardware instructions. Machine instructions and their
symbols are discussed in the DECsystem-10/DECSYSTEM-20
Processor Reference Manual.
o 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-10 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
1-1
INTRODUCTION TO MONITOR CALLS
o 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
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.
o Opcodes 101 and 104 cause the monitor to stop your program
and display the following message:
?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-2
INTRODUCTION TO MONITOR CALLS
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 PROCESSING MODES
The DECsystem-10 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-10 in user mode.
1-3
INTRODUCTION TO MONITOR CALLS
1.2.1 User Mode
The majority of user programs execute in user mode. For a user-mode
program, the processor:
o Performs automatic memory protection and mapping.
o 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 if an opcode
less than 40 (but not 0) executes (see Chapter 3).
User mode requires an assigned area of memory. Illegal user mode
instructions are:
o I/O instructions (opcodes 700 through 777) except those
giving a device code greater than 734. KS10 I/O instructions
are all illegal.
o All unimplemented opcodes (those not defined as machine
instructions or monitor calls).
o Any JRST instruction with an accumulator greater than 2,
except JRST 5 (XJRSTF) and JRST 15 (XJRST).
If your program executes an illegal instruction, one of the following
messages prints (and your program stops):
?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-10 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-4
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-5
2-1
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.
2-1
MEMORY
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.
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-10 monitor itself always remains in memory.
On the KS, if you need to exceed the virtual memory limit of 512P, you
must use an overlay structure. On the KL processor, if your program
requires more than the virtual memory limit of 16384P, 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-10 Link Reference
Manual.
The monitor enforces the following limits on memory space:
Symbol Application
GPPL (Global Physical Page Limit) is the maximum amount of
core available to any user.
GVPL (Global Virtual Page Limit) is the maximum amount of
virtual memory available to any user. GVPL is 512P on
the KS and 16384P on the KL. You may change this limit
using the privileged SETUUO function .STMVM.
MPPL (Maximum Physical Page Limit) is the maximum amount of
core available to a given user.
MVPL (Maximum Virtual Page Limit) is the maximum amount of
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.
2-2
MEMORY
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.
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 of
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 0. KL-paging allows the monitor to refer to code and data in
non-zero sections. Refer to the DECsystem-10/DECSYSTEM-20 Processor
Reference Manual for more information about KL-paging.
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 0.
Generally, however, if your program requires inter-section references,
do not execute it in Section 0.
2-3
MEMORY
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 your program in a section other than
Section 0. They are:
o Using the XJRST or XJRSTF instruction to place your program
in an extended section. See the DECsystem-10/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.
o Placing a section number before a page number in any UUO that
accepts page numbers as arguments. These UUOs include PAGE.
and IPCFR..
o 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.
o Formatting the core argument word to the GETSEG, MERGE, RUN,
or SAVE UUO to include a section number.
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
MEMORY
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). 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-10. 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, and REMAP monitor calls provide for
controlling single 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 .SGCOR
allocation of a low or high
segment.
GETSEG Create a high segment. .SGGET
Replace a high segment. .SGREL plus .SGGET
SETUWP Sets or clears the high .SGSWP
segment's write-protect bit.
2-5
MEMORY
REMAP Create a high segment from .SGRMP
already-existing memory in a
program's low segment.
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 of the
program that is currently in memory by using the MERGE. UUO.
2.4.3 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.).
2-6
MEMORY
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.
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 AC1,[XWD -1,.GTSGN] ;Set up GETTAB
GETTAB AC1, ;Get hiseg parameters
JRST ERROR ;GETTAB failed
TLNN AC1,(SN%SHR) ;Is it sharable?
JRST NOTSHR ;No
JRST SHAR ;Yes
2.4.5 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.
2-7
MEMORY
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 AC,[XWD -2,.GTUPM] ;Set up GETTAB
GETTAB AC, ;Get origin
JRST NOHIGH ;GETTAB failed
HLRZ AC,AC ;Set up origin
JUMPE AC,NOHIGH ;If 0, no high segment
MOVEM AC,HIORGN ;Store hiseg origin
;Code for no hiseg
2.4.6 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.
These calls are legal from either the low or high segment if the
following is true:
o You have write privileges for the file from which the high
segment was loaded.
o 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 meddled if any of the
following is true:
o 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.
o The D (deposit) monitor command was used.
o The high segment was obtained with a GETSEG monitor call, or
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.
2-8
MEMORY
If you have privileges to write to the file from which the sharable
high segment came, 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 user-mode
write-protect bit to protect the high segment.
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.
If your program modifies a sharable hiseg, you are responsible for
coordinating the changes with other users of the hiseg. Remember that
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-9
MEMORY
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, which (among other
functions) releases all user I/O channels.
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 argument
block.
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.5.1 Functions of RUN and GETSEG
To successfully program the RUN monitor call on 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.
2-10
MEMORY
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 hiseg origin at the
.JBHGH location.
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.)
3. 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).
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-11
MEMORY
5. 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.
o 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
b. 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 call, except for
the following differences:
o 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.
2-12
MEMORY
o The only changes made to the Job Data Area are:
1. the left half of .JBHRL is set to zero.
2. the right half of .JBHRL is set to the highest legal high
segment address.
3. .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
o 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.
o The call should be made from the low segment unless the
normal return coincides with the starting address of the new
high segment.
o User channels are not released. Channel 0, however, is
released because it was used by the GETSEG monitor call.
o The contents of the job's accumulators are not preserved.
Therefore, any AC used as a stack pointer will become
invalid.
2.5.2 Reading Command Files
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 by the argument to the RUN monitor call. If
the RUN UUO has a 0 in 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.
2-13
MEMORY
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 ;Job 9 commands to PIP
039MAC.TMP ;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.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-14
MEMORY
2.6.2 The System's Page Fault Handler
Unless your program has its own page fault handler, the monitor uses
its internal page fault handler when a page fault occurs. This
default page handler selects the page to swap out of memory to make
room for a needed page that is not in memory.
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 0.
2-15
MEMORY
The format of your page fault handler must be:
Word Symbol Contents
0 .PFHJS The instruction "JRST .+.PFHST".
1 .PFHOP Old PC and flags. That is, the flag/PC word used for
JRSTF, same as .JBTPC, .JBOPC, and so on.
2 .PFHFC Fault word, filled in by the monitor on each page
fault. The fault word is described below.
3 .PFHVT Virtual time.
4 .PFHPR Paging rate.
5 .PFHPV Highest PSI vector in use (in left half); address of
PSI vector (in right half).
6 .PFHUR Version number of the page fault handler.
7-11 Reserved for runtime statistics.
12 .PFHST Origin of the page fault handler (first instruction)
The fault word (.PFHFC) contains the following information:
Bits Symbol Contents
0 PF.HCB Working set was changed by a routine other than this
page fault handler.
1 PF.HBS Working set has been scrambled.
2-8 Reserved for use by DIGITAL.
9-17 PF.HPN Page number of the page causing the fault.
18-35 PF.HFC Fault code, described below.
The fault code (PF.HFC) is one of the following:
Code Symbol Meaning
1 .PFHNA Page is inaccessible (access-allowed bit is cleared)
but in core.
2 .PFHNI Page has been paged out and is not in memory.
3 .PFHUU A page containing a monitor call argument has been
paged out. This is a monitor-detected fault.
4 .PFHTI 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.
5 .PFHZI The page has been allocated, but is a zero page,
occurring after a user instruction.
6 .PFHZU The page has been allocated, but is zero after a
monitor call is executed.
2-16
MEMORY
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 to interrupts
promptly, without the delay of swapping.
o The job uses a display device that must refresh the display
from a buffer without flickering.
o The job analyzes system performance, and must be invoked
quickly.
o The job uses the SNOOP. UUO.
You must have the lock privilege to use the LOCK UUO. This is set by
the JP.LCK bit in GETTAB Table .GTPRV.
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-17
3-1
CHAPTER 3
JOB CONTROL
This chapter discusses initializing, starting, stopping, and
suspending programs, timing considerations, and other functions
pertaining to jobs.
3.1 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 Operating 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 must be recompiled and
reloaded before it can be executed.
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 as well as from
monitor command level.
3-1
JOB CONTROL
3.1.1 Starting a Program
You can start a program from the monitor level by using any of the
following monitor commands:
o RUN loads an .EXE file from disk and starts execution at the
address given by .JBSA in the job data area.
o 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.
o START starts (or restarts) execution of an already-loaded
program at its normal start address.
o CSTART starts execution of an already-loaded program at its
normal start address, but leaves the terminal at monitor
level.
o 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 monitor
level by using either of the following monitor commands:
o CONTINUE continues execution of an already-loaded program at
the place where the program was interrupted.
o 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 any of the
following monitor calls:
o 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.
o GETSEG replaces the high segment of the calling program with
a specified high segment.
o MERGE. merges specified pages of an .EXE file into the low
segment of the current program.
3-2
JOB CONTROL
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 the following
commands or monitor calls:
o CTRL/C, if your program is waiting for terminal input, or if
your program is running but your terminal is at monitor
level.
o Two CTRL/Cs, if your program is not waiting for terminal
input, but is attached to your terminal.
o The HALT monitor command.
o The EXIT monitor call in your program code.
o The LOGOUT monitor call in your program code.
o The FRCUUO monitor call in your program code.
If a fatal error occurs (including a HALT), the monitor will stop your
program.
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.
o The SLEEP monitor call suspends execution of your program
until a specified time has elapsed.
You can also use the PSI system, which can interrupt a job when a
particular event occurs. (Refer to Chapter 6.)
3-3
JOB CONTROL
3.2 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
any one 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, the
context is considered idle. The items saved in a context are:
o Program run; from physical SYS bit (JB.LSY from JBTLIM(J))
o Monitor mode bit: LDLCOM from LDBDCH(U)
o SAVCTX word in the PDB: .PDSCX(W)
o Break mask words: LDBBKM(U), LDBBKB(U), and LDBCSB(U)
o PSI data base address: JBTPIA(J)
o All IPCF-related words in the PDB
o Enqueue block chain address: .PDEQJ(W)
o Selected words in the TTY DDB
o Job status word: JBTSTS(J)
o Swapped out disk address: JBTSWP(J)
o Swapped in image size: JBTIMI(J)
o Swapped out image size: JBTIMO(J)
3-4
JOB CONTROL
o High segment number: JBTSGN(J)
o Funny space (per-process space) page count: JBTPDB(J)
o Swapped out checksum: JBTCHK(J)
o Program name: JBTNAM(J)
o User PC: JBTPC(J)
o I/O wait DDB: JBTDDB(J)
o Program run data: .PDNAM(W), .PDSTR(W), .PDDIR(W), .PDSFD(W)
o Time of last reset: PDSTM(W)
o Address of user-defined commands: PDCMN(W)
o Address of UNQTAB for user-defined commands: PDUNQ(W)
o Address of DECnet session control block: 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-10 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-5
JOB CONTROL
3.3.1 Runtimes
The TOPS-10 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.
The DK10 clock has higher resolution than the APR clock, and is
therefore more reliable for job accounting. High-precision runtime
simulates the DK10 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 be included in these runtimes,
depending on MONGEN parameters.
3.3.2 The System Date
The DATE monitor call returns the system date as a 15-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-6
JOB CONTROL
3.3.3 The Universal Date
The monitor also keeps the date in an alternate format, the universal
date standard. This fullword value is in the form:
day,,fraction
Where: day is the number of days since November 17, 1858 (where
November 17th is day 0, the 18th is day 1, and so on).
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).
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: 0 = 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-7
JOB CONTROL
3.3.5 Date-Time Elements from GETTAB Tables
The GETTAB Table .GTCNF contains the parts of the date and time.
These items are:
Symbol Contents
%CNYER Local year.
%CNMON Local month.
%CNDAY Local day of the month.
%CNHOR Local hour.
%CNMIN Local minute.
%CNSEC Local 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-8
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 (octal).
Locations relevant to your job are:
Word Symbol Contents
40 .JBUUO Used by hardware for processing local UUOs (opcodes
0 through 37); the hardware stores the opcode and
the effective address in this location.
41 .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.
4-1
THE JOB DATA AREA
42 .JBERR System program error count. The left half is
reserved; the right half is the number of errors in
the previous compilation.
44 .JBREL The left half is reserved; the right half is the
highest physical memory location available to the
user program (low segment).
45 .JBBLT First location of three words used by LINK to move
the program before calling the exit routine. This
location is used by the PA1050 program to store the
return address for the user program.
74 .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.
74 .JBPFI The highest location that is protected from user
access. User programs cannot write into locations
up to .JBPFI.
75 .JBHSO Reserved for use by DIGITAL.
76 .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. If zero, there is no high
segment.
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.
4-2
THE JOB DATA AREA
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.
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.
4-3
THE JOB DATA AREA
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 the
address of a trap routine to handle APR traps. See
the APRENB monitor call.
126 .JBCNI The state of the APR as stored by the monitor
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
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.
4-4
THE JOB DATA AREA
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 version number of any
program can be obtained using the VERSION monitor
command.
Bits Meaning
0-2 Modifier flag:
Flag Meaning
0 DIGITAL development group last
modified the program.
1 Other DIGITAL employees last
modified the program.
2-4 A customer last modified the
program.
5-7 A customer's user last modified
the program.
3-11 DIGITAL's latest major revision number,
usually incremented by 1 for each release.
12-17 DIGITAL's minor revision number, which is
usually 0, unless the program has been
modified since the last release.
18-35 The edit number, increased by 1 after each
edit to the program. This value is never
reset.
140 .JBDA First location available for user program.
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 origin (usually 400000), so that
your program actually begins at the origin + 10 (usually 400010).
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 offsets
are from the high-segment origin, usually .JBHGH (400000).
4-5
THE JOB DATA AREA
The format of the vestigial job data area is:
Word Symbol Contents
0 .JBHSA Copy of .JBSA in the job data area.
1 .JBH41 Copy of .JB41 in the job data area.
2 .JBHCR Copy of .JBCOR in the job data area.
3 .JBHRN LH: used to set LH of .JBHRL
RH: used to set RH of .JBREN
4 .JBHVR Copy of .JBVER in the job data area.
5 .JBHNM High segment name set on execution of SAVE command.
6 .JBHSM 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.
7 .JBHGA GET address page number (bits 9-17).
10 .JBHDA First word in high segment that is available to the
user program.
4-6
CHAPTER 5
NETWORKS
TOPS-10 supports four types of data networks:
o ANF-10, the TOPS-10 native communications software, supports
communication among DECsystem-10s and certain remote
stations. ANF-10 provides terminal concentration, remote job
entry, and front-end services for the monitor. Using ANF-10,
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-10
software is bundled with the TOPS-10 monitor. This chapter
discusses the monitor calls and facilities available in the
ANF-10 communications environment.
o DECnet-10 allows data communication among many of DIGITAL's
operating systems, for the purpose of file transfer, network
virtual terminal capability, and intertask communication.
(DECnet-10 must be purchased separately.) DECnet-10 is
TOPS-10's implementation of the Digital Equipment Corporation
Network Architecture. DECnet-10 Version 4 supports the
standards defined in the DECnet Phase IV Architecture
Specification, for Level 1 routing. Three monitor calls deal
directly with DECnet-10:
1. The NTMAN. call is used only by the DECnet Network
Management Layer.
2. The NSP. call is used for task-to-task program
communication over DECnet network links. Section 5.3
discusses the NSP. monitor call.
3. The DNET. call is used to access monitor-stored
information about DECnet nodes, links, and networks.
Section 5.4 discusses the DNET. call.
5-1
NETWORKS
o IBM Emulation/Termination facility provides communication
with IBM systems using batch job submission. IBM E/T, a
separately purchased product, interacts with the GALAXY
spooling and batch subsystem (Versions 4.1 and later),
allowing users to submit TOPS-10 batch jobs from IBM remote
stations, or to submit IBM-style batch jobs from the TOPS-10
host. This facility runs on a DN60 front end. IBM
communication is described in the TOPS-10 IBM
Emulation/Termination manual.
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 as a 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-2
NETWORKS
5.1 ANF-10 NETWORK MONITOR CALLS
A MACRO program can include the following monitor calls to accomplish
intertask communication in the ANF-10 network environment.
o GTNTN. UUO returns the line and remote station number of a
terminal.
o GTXTN. UUO returns a terminal name for a physical node and
line number.
o LOCATE UUO allows your job to send direct spooled output to
the device at the node you specify.
o NODE. UUO can perform several network functions. Among them
are:
- 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 name for
node number.
- Send station control messages.
- Receive boot request messages.
- Return system configuration information (similar to the
NODE command).
- Connect or disconnect a terminal to or from a remote
system.
- 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.
o 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, OUT,
INBUF, OUTBUF, FILOP., and OPEN.
The following sections discuss the use of monitor calls to establish
intertask communication between nodes on an ANF-10 network.
5-3
NETWORKS
5.2 ANF-10 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 programs must open a channel for I/O for intertask
communication. This is 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 for intertask
communication is:
OPEN channo,argblk
error return
normal return
. . .
argblk: EXP mode
SIXBIT /TSKnn/
XWD outblk,inblk
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
o Byte mode, in 8-bit bytes
o 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 of the
output (outblk) and input (inblk) buffer control blocks.
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-4
NETWORKS
5.2.1 Initiating a Connection
The intertask connection can be initiated by either of the following
methods:
o 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.
o 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.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 /tsknam/
0
0
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 ppn 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.
5-5
NETWORKS
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 /tsknam/
0
0
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 in LOOKUP by the
passive task).
ppn 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.2.1.2 Using the TSK. UUO - Both the passive and active 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 .TKNND Node number of the task.
1 .TKLNL Length of task name.
2 .TKNPN First word of task name.
.
.
n .TKLNL+n Last word of task name.
5-6
NETWORKS
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 any one character.
^V Quote next character, allowing you to specify
asterisks and question marks (for wildcard
characters) in the task name.
The TSK. call is invoked as shown in the following calling sequence:
MOVE ac,[XWD length,argblk]
TSK. ac,
error return
normal return
argblk: 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.
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. This is
identical to the channel number used in the OPEN UUO.
5-7
NETWORKS
In Word 2, the address of the local Network Process Descriptor,
indicated here by locnpd. This is the task's own NPD.
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, the passive task
can wait for input from the active 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 the node number generated
from the OPEN call
Where: 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-8
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:
Fcn-code Symbol Meaning
1 .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 confirmation.
2 .TKFEP Creates a passive link.
3 .TKFEA Creates an active link.
4 .TKFEI Enters idle state. This allows the monitor
to CLOSE the connection.
5 .TKFWT Enters wait state.
6 .TKFOT Outputs messages with control of message
disassembly.
7 .TKFIN Inputs messages with control of message
reassembly.
10 .TKFRX Returns the state of the link and the
maximum data message size.
5.2.3 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-10
You can write MACRO programs to communicate with tasks on another
DECnet node. When doing so, you use the NSP. monitor call to
interface to DECnet-10. This section describes the functions of the
NSP. monitor call. These functions allow you to:
o Declare a network task as willing to accept connections.
o Initiate a request for a connection to another network task.
5-9
NETWORKS
o Accept or reject a request for a connection from another
network task.
o Transmit data to and receive data from another network task.
o Request the status of a logical link.
o Read the connect attributes of a network task.
o Exchange interrupt messages with other network tasks.
o Set buffer quotas for the link.
o Set a reason mask for PSI interrupts.
o Disconnect a network connection.
The basic form of the NSP. monitor call is:
MOVEI AC,ADDR ;Arg block pointer
NSP. AC, ;Do the UUO
Error return ;AC contains error code
Normal return ;UUO succeeded, AC unchanged
The AC always points to a data block that has the general form:
Word Symbol Contents
0 17 18 35
---------------------------------
0 .NSAFN | Flags+Fcn | Length |
---------------------------------
1 .NSACH | Status | Channel # |
---------------------------------
2 .NSAA1 | First Argument |
---------------------------------
3 .NSAA2 | Second Argument |
---------------------------------
4 .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.
5-10
NETWORKS
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.
o NS.EOM (bit 1 of .NSAFN) indicates whether an end of message
is to be sent with a message. DECnet-10 returns the NS.EOM
flag as appropriate on a data read. If the program sets
NS.EOM on a normal data read call, DECnet-10 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.
Table 5-1: NSP. UUO Functions
______________________________________________________________________
Fcn-code Symbol Meaning
______________________________________________________________________
1 .NSFEA Enter Active State
2 .NSFEP Enter Passive State
3 .NSFRI Read Connect Information
4 .NSFAC Accept Connect
5 .NSFRJ Reject the Connect
6 .NSFRC Read Confirm Information
7 .NSFSD Synchronous Disconnect
10 .NSFAB Abort and Release
11 .NSFRD Read Disconnect Data
12 .NSFRL Release Channel
13 .NSFRS Read Channel Status
14 .NSFIS Send Interrupt Data
15 .NSFIR Receive Interrupt Data
16 .NSFDS Send Normal Data
17 .NSFDR Receive Normal Data
20 .NSFSQ Set Quotas
21 .NSFRQ Read Quotas
22 .NSFJS Set Job Quotas
23 .NSFJR Read Job Quotas
24 .NSFPI Set PSI Conditions
______________________________________________________________________
5-11
NETWORKS
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 Flags+XWD .NSFEP,3
.NSACH XWD Status, Channel number (assigned by this call)
.NSAA1 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-10 uses the connect block specified by the connect block
pointer (.NSAA1) 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.
The connect block has the following format:
Word Symbol Field Type
0 .NSCNL 0 , Length length of this argument block
1 .NSCND Node name pointer to string block (max 6 bytes)
2 .NSCSD Source pointer to task descriptor block
3 .NSCDD Destination pointer to task descriptor block
4 .NSCUS User-id pointer to string block (max 39 bytes)
5 .NSCPW Password pointer to string block (max 39 bytes)
6 .NSCAC Account pointer to string block (max 39 bytes)
7 .NSCUD User Data pointer to string block (max 16 bytes)
The connect block contains pointers to other blocks, such as those
containing the node name or accounting information, and those
containing information describing the source and destination tasks.
5-12
NETWORKS
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 Type
0 .NSASL NS.ASC,NS.ASL LH: byte count; RH: block
length in words
1 .NSAST c1,c2,c3,c4,0 8-bit bytes of data
NS.ASL-1 cn-1,cn,0
The user-id, password, 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 destination task.
Its format is shown below:
Word Symbol Field Type
0 .NSDFL 0 , Length length of the argument block
1 .NSDFM Format type 0, 1 or 2
2 .NSDOB Object type integer
3 .NSDPP PPN 2 half words (16 bits, 16 bits)
4 .NSDPN task name 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.
Table 5-2: Allowable Combinations of Task Descriptor Values
______________________________________________________________________
Kind of Program Format Type Object Type PPN Task Name
______________________________________________________________________
DECnet system 0 1-127 0 0
Customer system 0 128-255 0 0
User, name only 1 0 0 string pointer
User, with PPN 2 0 n,n string pointer
______________________________________________________________________
5-13
NETWORKS
Use format type 0 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 0 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 be up to 12
characters long because DECnet-10 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-10 puts the
link in the Connect Received (.NSSCR) state, and passes control to the
destination program. At this point the program can read the connect
data and accept or reject the connection.
Example of Specifying a 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:
MOVEI T1,EPBLK ; Pointer to Enter Passive arg block
NSP. T1, ; Enter Passive
JRST [OUTSTR [ASCIZ /?Can't Enter Passive /]; 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 for Enter Passive
CONBLK: EXP 4 ; Length of block in words
EXP 0 ; Accept connects from any host
EXP 0 ; Accept connections from any source
EXP TDB1B ; Destination task descriptor block
5-14
NETWORKS
; Destination task descriptor block
TDB1B: EXP 5 ; Length of TDB
EXP 2 ; Format type 2
EXP 0 ; 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 Flags+XWD .NSFEA,length (length = 3 to 5)
.NSACH XWD Status, Channel number (assigned by this call)
.NSAA1 Connect block pointer
.NSAA2 Segment size (optional; default: maximum allowed)
.NSAA3 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.
5-15
NETWORKS
o 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.
o No flow control (.NSFC0) - 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-10 sets the link state to
Running (.NSSRN); if the attempt fails, DECnet-10 sets the link state
to Connect Rejected (.NSSRJ).
Example of Specifying a Source Task
; Begin by using the Enter Active function to attempt to establish
; a logical link with PGMB on system HOSTB.
MOVEI T1,EABLK ; Point to Enter Active arg block
NSP T1, ; Enter Active
JRST [OUTSTR [ASCIZ /?Can't Enter Active /]; Error
JRST EREXIT] ; return
; Argument block for Enter Active
EABLK: NS.WAI+XWD .NSFEA,3 ; Wait bit, function, block length
XWD 0,0 ; No status or channel number yet
XWD CONBLK ; Pointer to connect block
; Connect block for Enter Active
CONBLK: EXP 4 ; Length of block in words
EXP STRB1A ; Pointer to string block of node name
EXP TDB1A ; Source task descriptor block
EXP TDB1B ; Destination task descriptor block
; String block for node name
STRB1A: XWD 5,3 ; Number of bytes, number of words
BYTE (8) "H", "O", "S", "T", "B" ; Name of destination node
; Source task descriptor block
TDB1A: EXP 5 ; Length of TDB
EXP 2 ; Format type 2
EXP 0 ; Object type 0
XWD 20,7100 ; Project-programmer number on HOSTA
EXP STRB1B ; String block for source name
; String block for source name
STRB1B: XWD 4,2 ; Number of bytes, number of words
BYTE (8) "P", "G", "M", "A"
5-16
NETWORKS
; Destination task descriptor block
TDB1B: EXP 5 ; Length of TDB
EXP 2 ; Format type 2
EXP 0 ; Object type 0
XWD 20,7200 ; Project-programmer number on HOSTB
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.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 (.NSFRI) 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 Flags+XWD .NSFRI,length (length = 3 to 5)
.NSACH XWD Status, Channel number
.NSAA1 Connect block pointer
.NSAA2 Segment size (optional)
.NSAA3 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 0.
If the destination program has included fields for segment size and
flow control, DECnet-10 stores those values for the source node.
The UUO takes the error return if the link is not in one of the
following states:
.NSSCR Connect Received
.NSSCW Connect Wait
.NSSRN 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.
5-17
NETWORKS
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
MOVEI T1,RIBLK ; Point to Read Connect Info arg block
NSP. T1, ; Read Connect Info
JRST [OUTSTR [ASCIZ /?Can't Read Connect Info /]; Error
JRST EREXIT] ; return
; Here the program checks to make sure that the source PPN is [20,*].
HLRZ T1,SRCPDB+.NSDPP; Get left half of source PPN field
CAIE T1,20 ; Test for project number 20
JRST REJCON ; Reject connection if not
JRST ACCCON ; 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
; Connect Block for Read Connect Info
SRCCNB: EXP ^D8 ; Length of block in words
EXP STNODE ; String block for node name
EXP SRCTDB ; Source task descriptor block
EXP DSTTDB ; Destination task descriptor block
EXP STUSID ; String block for user id
EXP STPSWD ; String block for password
EXP STACCT ; String block for account
EXP STDATA ; String block for user data
; String block for node name
STNODE: XWD 0,3 ; Number of words -- max 6 bytes
BLOCK 2
; Source task descriptor block
SRCTDB: XWD 0,5 ; Number of words
EXP 0,0,0 ; Format type, Object type, PPN
EXP STNAME ; 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 0,^D11 ; Number of words -- max 39 bytes
BLOCK ^D10
; String block for password
STPSWD: XWD 0,^D11 ; Number of words -- max 39 bytes
BLOCK ^D10
5-18
NETWORKS
; String block for account
STACCT: XWD 0,^D11 ; Number of words -- max 39 bytes
BLOCK ^D10
; String block for data
STDATA: XWD 0,5 ; Number of words -- max 16 bytes
BLOCK 4
; String block for source name
STNAME: XWD 0,5 ; Number of words -- max 16 bytes
BLOCK 4
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 XWD .NSFAC,length (length = 2 to 5)
.NSACH XWD Status, Channel number
.NSAA1 Pointer to user data (string block pointer, optional)
.NSAA2 Segment size (optional; default: maximum allowed)
.NSAA3 Flow-control (optional, privileged; default: segment)
If execution of the Accept Connect function succeeds, DECnet-10 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.
If the link is not in Connect Received state when the Accept Connect
function executes, the UUO takes the error return.
Example of the Accept Connection Function
; The program comes here to accept the requested connection
ACCCON:
HRRM CHAN,ACBLK+.NSACH; Store channel number into arg block
MOVEI T1,ACBLK ; Point to Accept Connection arg block
NSP. T1, ; Accept Connection
JRST [OUTSTR [ASCIZ /?Can't Accept Connection /]; 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-19
NETWORKS
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 XWD .NSFRJ,length (length = 2 or 3)
.NSACH XWD Status, Channel number
.NSAA1 String block pointer to user data (optional)
If the link is not in Connect Received state upon execution of the
Reject Connect function, the UUO takes the error return.
Example of the Reject Connection Function
; The program comes here to reject the requested connection
REJCON:
HRRM CHAN,RJBLK+.NSACH; Store channel number into arg block
MOVEI T1,RJBLK ; Point to Reject Connection arg block
NSP. T1, ; Reject Connection
JRST [OUTSTR [ASCIZ /?Can't Reject Connection /]; Error
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.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:
.NSAFN Flags+XWD .NSFRC,length (length = 2 to 5)
.NSACH XWD Status, Channel number
.NSAA1 String block pointer to user data (optional)
.NSAA2 Segment size (optional)
.NSAA3 Transmit flow control mode (optional)
5-20
NETWORKS
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-10 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 (and therefore
the link) by executing the Read Channel Status function (.NSFRS). The
.NSFRS argument list has the format:
.NSAFN XWD .NSFRS,length (length = 2 to 4)
.NSACH XWD Status, Channel number
.NSAA1 Segment size for this link (optional)
.NSAA2 XWD Remote flow control, local flow control (optional)
The left half of the second argument (.NSACH) contains the status
variable, which contains the following fields:
Table 5-3: Fields in .NSACH (status variables)
______________________________________________________________________
Bits Symbol Meaning
______________________________________________________________________
If set:
0 NS.IDA Single bit. Interrupt data can be read.
1 NS.IDR Single bit. Interrupt data can be sent.
2 NS.NDA Single bit. Normal data can be read.
3 NS.NDR Single bit. Normal data can be sent.
12-17 NS.STA 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 link is in an appropriate
state for the indicated functions. Table 5-4 lists the NSP. UUO
connection states.
5-21
NETWORKS
Table 5-4: NSP. Connection States
______________________________________________________________________
Code Symbol Meaning
______________________________________________________________________
1 .NSSCW Connect wait:
The task has executed the Enter Passive function
and is awaiting the receipt of a connect
initiate message.
2 .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.
3 .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
entry into the Reject state).
4 .NSSRJ Reject:
The remote node has rejected this node's connect
initiate attempt. The task should read the
disconnect data and release the channel.
5 .NSSRN Running:
The link is up and may be used for the transfer
of data.
6 .NSSDR Disconnect Received:
The task has received a disconnect initiate
message. The task should read the disconnect
data and release the channel.
7 .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.
10 .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.
5-22
NETWORKS
11 .NSSCF No 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.
12 .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.
13 .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.
14 .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
MOVEI T1,RSBLK ; Point to Read Status arg block
NSP. T1, ; Read Status
JRST [OUTSTR [ASCIZ /?Can't Read Status /]; Error
JRST TYPRET] ; return
5-23
NETWORKS
; Argument block for Read Status
RSBLK: XWD <(NS.WAI)>+.NSFRS,2 ; Wait bit, function, block length
XWD 0,0 ; Code supplies channel number
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-10 can cause an
interrupt.
5.3.9 Setting the PSI Reason Mask
The PSI reason mask is an 18-bit value that contains fields
corresponding to the fields in the DECnet-10 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 Flags+XWD .NSFPI,3
.NSACH XWD Status, Channel number
.NSAA1 XWD 0,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-10 I/O.
When a program executes the Set PSI Reason Mask function, DECnet-10
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-10 condition in the reason mask, when the program
executes the .NSFPI function, DECnet-10 causes a PSI interrupt. This
"free" interrupt enables a PSI-driven program to do all its DECnet
checking in the PSI routine.
5-24
NETWORKS
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.3.10 Enabling the PSI Interface
The program can enable the PSI system for any DECnet-10 channel by
doing the following:
MOVEI AC,IVB ;address of Interrupt Vector Block
PIINI. AC, ;initiate PSI system
error return
normal return
MOVE AC,[PS.FON!PS.FAC,PSIARG]
PISYS. AC, ;enable PSI
error return
normal return
...
MOVEI AC,NSPARG
NSP. AC, ;NSP. argument list
error return ;to specify reason for interrupt
normal return
IVB: ... ;interrupt vector: allow one
;4-word control block per channel
ICB: EXP HANDLER ;interrupt control block
0 ;specifies address of code
0 ;to handle interrupt
0
...
PSIARG: EXP .PCNSP ;NSP.-type interrupt
XWD <ICB-IVB>,0 ;offset in IVB to ICB
XWD priority,0 ;priority of NSP. interrupts
NSPARG: XWD .NSFPI,3 ;function code length
XWD 0,channel ;status word (status,channel number)
XWD 0,reason mask ;reason word
HANDLER: ... ;code to handle NSP. interrupt
5-25
NETWORKS
When DECnet-10 interrupts the program, the status word of the
interrupt control block contains:
XWD status, channel
Note that the PISYS. status word has the same format as the second
argument (.NSACH word) of the NSP. function argument block.
A program that has several links open at one time can include tables
indexed by the channel numbers of the links. DECnet-10 assigns
consecutive channel numbers starting with the lowest number available.
Note, however, that DECnet-10 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-10 PSI interrupt is zero, the program
should ignore the interrupt.
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-10 can be asked to send data requests before the receiving
program issues a read request. DECnet-10 queues message segments that
arrive before the receiving program issues a read function 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"). DECnet-10 allows cached messages to be discarded at
any time because the source node will resend them after a timeout.
5-26
NETWORKS
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 Flags+XWD .NSFSQ,length (length = 3 to 5)
.NSACH XWD status, channel number
.NSAA1 Link quota
.NSAA2 Percent of input (optional)
.NSAA3 Input goal (privileged optional)
The program can set the link quota for each link to any value up to
the maximum 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 between 0 and
100; the default is 50.
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 Flags+XWD .NSFRQ,length (length = 3 to 5)
.NSACH XWD status, channel number
.NSAA1 Link quota
.NSAA2 Percent of input (optional)
.NSAA3 Input goal (privileged, optional)
If the argument block contains five words, all the values (quota,
percent input, and input goal) will be returned.
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.
5-27
NETWORKS
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
destination 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 FLAGS+XWD .NSFDS,4
.NSACH XWD status, channel number
.NSAA1 EXP byte count
.NSAA2 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-10 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-10
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.
5-28
NETWORKS
If the program sets the NS.WAI flag, it waits until the UUO returns.
The UUO returns when DECnet-10 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.
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 CHAN,DSBLK+.NSACH;Store channel number into arg block
MOVE1 T1,DSBLK ; Point to Send Normal Data arg block
NSP. T1, ; Send Normal Data
JRST [OUTSTR [ASCIZ /?Can't Send Normal Data /]; 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 Flags+XWD .NSFDR,4
.NSACH XWD status, channel number
.NSAA1 EXP byte count
.NSAA2 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.
5-29
NETWORKS
As DECnet-10 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-10 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.
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 immediately
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 CHAN,DRBLK+.NSACH;Store channel number into arg block
MOVEI T1,500 ; Maximum number of bytes
MOVEM T1,DRBLK+.NSAA1 ; Store into argument block
MOVE T1,[POINT 7,MESSAG]; Same with message byte pointer
MOVEM T1,DRBLK+.NSAA2
MOVEI T1,DRBLK ; Point to Receive Normal Data arg block
NSP. T1, ; Receive Normal Data
JRST REDERR ; Error in Receive Normal Data
5-30
NETWORKS
; When control comes here, there's a message
MOVE T1,[POINT 7,MESSAG]; Get byte pointer to message
MOVEI 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
SOJG T2.-2 ; 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 ; Turn off EOM bit in arg block for
; next call
JRST READMS ; 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.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 Flags+XWD .NSFIS,3
.NSACH XWD Status, Channel number
.NSAA1 Pointer to string block containing the data
The pointer in .NSAA1 points to a string block containing the data.
The data cannot be longer than 16 bytes.
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.
5-31
NETWORKS
The UUO takes the error return under any of the following conditions:
o There are no outstanding interrupt data requests
o There is already an interrupt message for transmission
o The link is not in Running or Connect Sent state
o The NS.WAI flag is not set while the link is in the Connect
Sent state
5.3.16 Receiving Interrupt Data
To receive an interrupt message from another task, the program
executes the Receive Interrupt Data function (.NSFIR). The .NSFIR
argument list has the format:
.NSAFN Flags+XWD .NSFIR,3
.NSACH XWD Status, Channel number
.NSAA1 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
exceed that size. If the string block is too small, DECnet-10
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.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.
5-32
NETWORKS
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 XWD .NSFSD, length (length = 2 or 3)
.NSACH XWD Status, Channel number
.NSAA1 String block pointer to disconnect data (optional)
.NSAA1 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-10 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-10 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 CHAN,SDBLK+.NSACH; Store channel number into arg block
MOVEI T1,SDBLK ; Point to Sync Disconnect arg block
NSP. T1, ; Synchronous Disconnect
JRST [OUTSTR [ASCIZ /?Can't Sync Disconnect /]; 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-33
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 the format:
.NSAFN XWD .NSFRL,2
.NSACH 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-10
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-10 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 CHAN,RLBLK+.NSACH; Store channel number into arg block
MOVEI T1,RLBLK ; Point to Release Channel arg block
NSP. T1, ; Release Channel
JRST [OUTSTR [ASCIZ /?Can't Release Channel /]; 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-34
NETWORKS
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 XWD .NSFAB,length (length = 2 or 3)
.NSACH XWD status, channel number
.NSAA1 Pointer to disconnect data (optional)
.NSAA1 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-10 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.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 XWD .NSFRD,length (length = 3 or 4)
.NSACH XWD status, channel number
.NSAA1 Pointer to string block to receive the data
.NSAA2 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:
0 - Rejected or disconnected by object (task)
1 - No Resources
2 - Unrecognized node name
3 - Remote node shut down
4 - Unrecognized object
5 - Invalid object name format
6 - Object too busy
5-35
NETWORKS
8 - Abort by network management
9 - Abort by object
10 - Invalid node name format
11 - Local node shut down
34 - Access control rejection
38 - No response from object
39 - Node unreachable
41 - No link or logical link has been lost
42 - Disconnect complete
43 - Image field too long (rqstrid, password, account, usrdata, etc.)
44 - 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.4 OBTAINING INFORMATION ABOUT DECNET-10
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:
Fcn-code Symbol Meaning
1 .DNLNN Lists the names of the nodes in the
network.
2 .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).
3 .DNSLS Returns information about each logical link
established from your node. A logical link
is the path of communication used for
DECnet intertask communication.
5-36
NETWORKS
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:
MOVEI ac,addr
DNET. ac,
error return
normal return
addr: flags+.DNLNN,,length+1
BLOCK length
Where: 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
1 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.
2 DN.FLR List only reachable nodes. This flag
restricts the returned list to only those
nodes that are currently in the network.
3 DN.FLE List only the EXECUTOR node. This is the node
at which the program is running.
When the information is returned at addr+1, the form of the returned
block is:
addr: flags+.DNLNN,,length
count
first node name
second node name
.
.
.
5-37
NETWORKS
Where: Word 0 (.DNFFL) contains the same information you place in
this word.
Word 1 (.DNCNT) contains the number of node names returned.
Words 2 and following (.DNNMS) each contain a SIXBIT node
name.
Example
The following is an example of the use of .DNLNN:
MOVE T1,[<.DNLNN>B17!DN.FLK!.DNLLN] ;Function word to return
; known nodes up to the
; maximum length arg block
(.DNLLN)
MOVEM T1,DNARG ;Save word in arg block
MOVEI T1,DNARG ;Point to arg block
DNET. T1, ;Ask for information
HALT ;Shouldn't happen
At this point, the argument block should be:
DNARG: DN.FLK!<.DNLNN>B17!.DNLLN
20 ;20 nodes
SIXBIT/ONE/ ;First node
SIXBIT/TWO/ ;Second node
SIXBIT/THREE/
SIXBIT/KL1026/
SIXBIT/JINX/
SIXBIT/GNOME/
.
.
.
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 information is returned for each
node in the network, arranged by node address. Under step mode, you
must clear addr+1 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+1. 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-38
NETWORKS
Where the flags are:
Bits Symbol Meaning
0 DN.FLS Set step mode for controlling returned
information about every node in the DECnet
network.
1 DN.FLK List information about known nodes. Set this
flag only if you set step mode (DN.FLS).
2 DN.FLR List reachable nodes. Set this flag only if
you set step mode (DN.FLS).
3 DN.FLE List EXECUTOR node.
If you do not set DN.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+.DNNDI,,length
node-name
router information
link information
node address
circuit name
Where each word at addr is returned as follows:
Word Symbol Contents
0 .DNFFL Flag word that you specified.
1 .DNNAM The node name of the currently listed node.
2 .DNRTR Router information. Bit 0 (DN.RCH) of this
word is set if the node is reachable. If bit
0 equals 0, the node is not reachable. The
remainder of the left half of this word
(DN.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
(DN.CST) contains the relative cost of the
path to the specified node.
5-39
NETWORKS
3 .DNLLI Link information. Bit 0 (DN.VLD) 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.
4 .DNADR Node address.
5-10 .DNCKT 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.
Example
The following example shows how the DNET. function .DNNDI might be
used in step mode to show information about known nodes:
MOVE T1,[<.DNNDI>B17!DN.FLK!DN.FLS!.DNNLN] ;Show link status
; up to the maximum
; length of the
; argument block (.DNNLN)
MOVEM T1,DNARG ;Save in arg block
SETZM DNARG+.DNNAM ;Clear arg+1 to start at
; First node name
MOVEI T1,DNARG ;Point to arg block
DNET. T1, ;Ask for information
HALT ;Shouldn't happen
The argument block returned may be:
DNARG: DN.FLK!DN.FLS!<.DNNDI>B17!.DNNLN ;Flag word
SIXBIT/ONE/ ;Node name
1B0!3B17!4B35 ;Reachable,3 hops, cost=4
0 ;No active links
1 ;Node address=1
ASCII/DTE-0/ ;Circuit-id
ASCII/-1/ ;Continuation of
; Circuit-id
5-40
NETWORKS
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: DN.FLS+<.DNSLS,,length>
jobno,,channo
BLOCK n
Where: 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+1 (.DNJCN) the first time the
call is issued.
If DN.FLS is not set, non-step mode is the control method, and
addr+1 (.DNJCN) should contain the job number and DECnet
channel number of the link for which you want the following
information.
The link information is returned to you in the following form:
Word Symbol Contents
0 .DNFFL The flag word you specified in the argument
block.
1 .DNJCN The job number and channel number for which
the following information is appropriate.
2 .DNNOD The node name (in SIXBIT) of the node to which
the link is made.
3 .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 0.
5-41
NETWORKS
4 .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:
Symbol Meaning
CF No confidence
CM No communication
CR Connect received
CS Connect sent
CW Connect wait
DC Disconnect confirmed
DR Disconnect received
DS Disconnect sent
LK No link
NR No resources
RJ Remote node rejected
connect initiate message
RN Link is running
5 .DNQUO Quota word, where the left half (DN.QUI)
contains the input quota, and the right half
(DN.QUO) contains the output quota of
outstanding messages allowed on the link.
6 .DNSEG Contains the segment size.
7 .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.
10 .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.
11 .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 process NRTSER's
link.
5-42
NETWORKS
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] ;Link status, step
; control
MOVEM T1,DNARG ;Save in arg block
SETZM DNARG+.DNJCN ;Start at first link
MOVEI T1,DNARG ;Point to arg block
DNET. T1, ;Ask for information
HALT ;Shouldn't happen
At this point, the argument block should look like:
DNARG: DN.FLS!,.DNSLS>B17!.DNSLN ;Flag word
-1,,1 ;NRTSER pseudo-job,
; channel 1
SIXBIT/THREE/ ;Connected to node THREE
27,,27 ;NRT object type on both
; sides of the link
240005,,'RN' ;Binary status,running
; link
10,,10 ;10 credits either
; direction
100 ;Segment size
2,,1 ;Segment flow control,,no
; flow control
2073,,1241 ;Messages sent and
; received
110 ;Link is NRT TTY110
5.5 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-43
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
0 .UBNXT Address of the next user buffer descriptor.
1 .UBBID User buffer ID.
2 .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.
3 .UBBSZ Length of the datagram (in bytes).
4 .UBBFA A byte pointer to the datagram.
6 .UBPTY Protocol type.
7 .UBDEA A two-word Ethernet destination address.
11 .UBSEA A two-word Ethernet source address.
5-44
NETWORKS
The User Buffer descriptor block has a length of 13; .UBLEN is the
symbol for block length.
An example of the ETHNT. queue receive buffers function follows.
This function includes returns from .ETRRQ, the Read Receive Queue
function.
XMOVEI ac,addr
ETHNT. ac
error return
normal return
addr: .ETQRB,,3 ;Function,,block length
portal ID ;Portal ID
UBL ;Address of buffer
; descriptor list
UBL: 0 ;Address of next buffer
; descriptor list
buffer ID ;Returned on .ETRRQ
; function
0 ;Status, returned on
; .ETRRQ
1000 ;Datagram length in bytes
POINT 8,DGM ;Byte pointer
0
0 ;Protocol type, returned
; on .ETRRQ
0 ;Destination Ethernet
0 ; addr,returned on .ETRRQ
0 ;Source Ethernet addr,
0 ; returned on .ETRRQ
DGM: BLOCK <1000+3>/4 ;Space for datagram
5.5.2 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.)
5-45
NETWORKS
The form of the return buffer for .ETRCI is:
Word Symbol Contents
0 .EICNM The Ethernet channel number.
1 .EICEA The current (two-word) Ethernet address.
The form of the return buffer for .ETRCC is:
Word Symbol Contents
0 .ECCSZ Seconds since the counters were last zeroed.
1 .ECCBR Number of bytes received.
2 .ECCBX Number of bytes transmitted.
3 .ECCDR Datagrams received.
4 .ECCDX Datagrams transmitted.
5 .ECCMB Multicast bytes received.
6 .ECCMD Multicast datagrams received.
7 .ECCXD Datagrams transmitted, but initially
deferred.
10 .ECCX1 Datagrams transmitted, single collision. A
collision occurs when two station's
transmissions overlap.
11 .ECCXM Datagrams transmitted, multiple collisions.
12 .ECCXF Transmit failures.
13 .ECCXX The transmit failures bit mask. The bits
are:
Bit Symbol Meaning
28 EC.XCL Carrier was lost.
29 EC.XBP Transmit buffer parity error.
30 EC.XFD Remote failure to defer.
31 EC.XFL Transmitted frame too long.
32 EC.XOC Open circuit.
33 EC.XSC Short circuit.
34 EC.XCC Collision detect check
failed.
35 EC.XEC Excessive collisions.
5-46
NETWORKS
14 .ECCRF Receive failures.
15 .ECCRX The receive failures bit mask. The bits are:
Bit Symbol Meaning
31 EC.RFP Free list parity error.
32 EC.RNB No free buffers.
33 EC.RFL Frame too long.
34 EC.RFE Framing error.
35 EC.RBC Block check error.
16 .ECCUD Unrecognized frame destination.
17 .ECCDO Data overrun.
20 .ECCSU System buffer unavailable.
21 .ECCUU User datagram buffer unavailable.
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
0 .EIPCJ Job Context Handle (JCH) of the portal owner.
1 .EIPPI Protocol identification word.
2 .EIPCS Channel status word.
3 .EIPKC Controller status word.
5-47
NETWORKS
The returned buffer for a Read Portal Counters has the format:
Word Symbol Meaning
0 .ECPSZ Seconds since the counters were last zeroed.
1 .ECPBR Bytes received.
2 .ECPDR Datagrams received.
3 .ECPBX Bytes transmitted.
4 .ECPDX Datagrams transmitted.
5 .ECPUU User datagram buffer unavailable.
5.5.4 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
0 .EIKCS Channel status word.
1 .EIKCP CPU number of controller.
2 .EIKTY Controller type. A value of 1 (EI.KNI) is
returned for an NIA20 interface.
3 .EIKNO Controller number.
4 .EIKHA A two-word Ethernet hardware address.
5-48
NETWORKS
The buffer returned for a Read Controller Counters request is:
Word Symbol Contents
0 .ECKSZ Seconds since the counters were last zeroed.
1 .ECKBR Number of bytes received.
2 .ECKBX Number of bytes transmitted.
3 .ECKDR Datagrams received.
4 .ECKDX Datagrams transmitted.
5 .ECKMB Multicast bytes received.
6 .ECKMD Multicast datagrams received.
7 .ECKXD Datagrams transmitted, but initially
deferred.
10 .ECKX1 Datagrams transmitted, single collision.
11 .ECKXM Datagrams transmitted, multiple collisions.
12 .ECKXF Transmit failures.
13 .ECKXX The transmit failures bit mask. The bits are
listed in Section 5.5.2
14 .ECKRF Receive failures.
15 .ECKRX The receive failures bit mask. The bits are
listed in Section 5.5.2
16 .ECKUD Unrecognized frame destination.
17 .ECKDO Data overrun.
20 .ECKSU System buffer unavailable.
21 .ECKUU User datagram buffer unavailable.
5-49
6-1
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).
o Intercepting specific kinds of errors. The monitor then
transfers control to a predefined address for error handling
(generally I/O conditions).
o 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, interrupting 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-10 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.
6-1
TRAPPING, INTERCEPTING, AND INTERRUPTING
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.
To set an APRENB trap, your program must:
1. Place the address of the trap-service routine in location
.JBAPR in the job data area.
2. Enable one or more conditions for trapping by issuing an
APRENB monitor call.
3. 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:
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. The
address specified in the error messages is your current PC.
o Pushdown list overflows. If your program does not trap these
overflows, the monitor stops the job and prints:
?Pushdown list overflow at user PC address
o Illegal memory references. If your program does not trap
these violations, the monitor 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
6-2
TRAPPING, INTERCEPTING, AND INTERRUPTING
o 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
o Memory parity errors. If your program does not trap these
errors, the monitor stops the job and prints:
?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.
o 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 preferred method for handling
arithmetic overflows.
When an enabled trap condition occurs, the monitor performs the
following functions:
1. 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.
2. 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.
3. 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-3
TRAPPING, INTERCEPTING, AND INTERRUPTING
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.
o 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.
o Requests for space that would exceed your disk quota. The
error message is:
[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.
o Requests for space on a file structure that is full. Your
job must wait until some blocks are freed on the structure.
o CTRL/Cs typed from the controlling terminal. The monitor
normally stops your program and puts your terminal in monitor
mode. No message is displayed.
6-4
TRAPPING, INTERCEPTING, AND INTERRUPTING
o Device errors that the operator can correct, such as an
offline disk. The error message is:
Device dev OPRnn Action requested
Where: dev is the name of the relevant device.
nn is the number of the node where the operator must
take action.
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 by the
monitor once a minute.
The bits that affect the monitor's handling of these conditions are
described in Table 6-1.
6.2.1 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.
2. 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 may or 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-5
TRAPPING, INTERCEPTING, AND INTERRUPTING
Table 6-1: Format of .JBINT Intercept Block
______________________________________________________________________
Word Symbol Contents
______________________________________________________________________
0 .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.
1 .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 ER.EIJ Error in job.
30 ER.TLX Time limit exceeded.
31 ER.QEX Disk quota exceeded.
32 ER.FUL File structure full.
33 ER.OFL Disk unit off line.
34 ER.ICC CTRL/C typed.
35 ER.IDV Problem with device.
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.
3 .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 in
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-6
TRAPPING, INTERCEPTING, AND INTERRUPTING
6.2.2 Examples of Error Intercepts
The following example intercepts CTRL/Cs. The user is returned to the
monitor level as quickly as possible.
LOC .JBINT ;Set pointer to .JBINT
EXP INTBLK ;Address of intercept block
RELOC ;Resume relocatable
INTBLK: XWD 4,INTLOC ;4 words long,,handler address
EXP ER.ICC ;Intercept CTRL/Cs
BLOCK 2 ;For returned data
;Intercept routine starts here.
INTLOC: MOVEM AC1,TEMP## ;Save AC1
MOVSI AC1,ER.ICC ;Get CTRL/C bit
TDNN AC1,INTBLK+.ERCCL ;Was this a CTRL/C?
HALT ;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 AC1,INTBLK+.EROPC ;Get continuation PC
EXCH AC1,TEMP ;Restore AC1
SETZM INTBLK+.EROPC ;Clear to allow another intercept
JRSTF @TEMP ;Resume where program stopped
The following example shows how to enable and handle a CTRL/C
intercept, preventing the user from returning to monitor mode:
LOC .JBINT ;Set pointer to .JBINT
EXP INTBLK ;Address of intercept block
RELOC ;Resume relocatable
INTBLK: XWD 4,INTLOC ;4 words long,,handler address
EXP ER.ICC ;Intercept CTRL/Cs
BLOCK 2 ;For returned data
6-7
TRAPPING, INTERCEPTING, AND INTERRUPTING
;Intercept routine starts here.
INTLOC: SKIPN CCEXIT ;Can program be interrupted by
; CTRL/C?
JRST EXITOK ;Yes, go clean up and exit
SETOM CCSEEN ;Set flag that we saw a CTRL/C
PUSH P,INTBLK+.EROPC ;Put interrupt PC in stack
SETZM INTBLK+.EROPC ;Reenable intercept
POPJ P, ;Return to interrupted PC
CCEXIT: EXP -1 ;Flag set non-zero if a CTRL/C
;May not interrupt execution
CCSEEN: EXP 0 ;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.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.
6-8
TRAPPING, INTERCEPTING, AND INTERRUPTING
PROGRAM (USER) INTERRUPT
LEVEL LEVEL
|
|
=========|=========
| User program |
===================
|
|
=========|=========
| Interrupt |
| condition |
| occurs |
===================
|
|
|
/ ====|==== \ =============================
/ Did user \ YES | The interrupt servicing |
/ enable for this \ -----------> | routine, designated by |
\ interrupt / | the appropriate interrupt |
\ condition / | control block |
\ ========= / =============================
| |
| NO |
| |
V |
==================== |
| Take default | |
| action/ | |
| (do nothing/ | |
| stop job/ | |
| print error | |
| message) | |
==================== |
| |
| |
=========|========== ===========|==========
| User program | | DEBRK monitor call |
==================== ======================
Figure 6-1: The Software Interrupt Process
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.
6-9
TRAPPING, INTERCEPTING, AND INTERRUPTING
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 gains 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.
2. 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.
3. 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-10
TRAPPING, INTERCEPTING, AND INTERRUPTING
6.3.1 PSI Monitor Calls
The following monitor calls are provided to allow you to write
programmed interrupt service routines:
o PIINI. 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.
o 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.
o 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.
o 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.
o 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.
6-11
TRAPPING, INTERCEPTING, AND INTERRUPTING
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.3.2 Interrupt Control Block
The interrupt control block is the controller of the PSI system. The
control block keeps track of the following:
o The instruction that would have been executed next when the
interrupt occurred.
o The location of the interrupt service routine to be used for
processing the current interrupt.
o 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.
0 17 18 35
--------------------------------------------------------------
| New PC | .PSVNP
|------------------------------------------------------------|
| Old PC | .PSVOP
|------------------------------------------------------------|
| Control flags | Reason | .PSVFL
|------------------------------------------------------------|
| Status word | .PSVIS
--------------------------------------------------------------
Figure 6-2: Interrupt Control Block
6-12
TRAPPING, INTERCEPTING, AND INTERRUPTING
Where: new PC is the location of the interrupt servicing routine to
be used for processing the current interrupt. This is a
30-bit PC if you set PS.IEA in the PIINI. UUO. Otherwise, the
left half 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).
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
condition 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:
0 17 18 35
----------------------------------
| UDX | File status |
----------------------------------
Where: 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 word (same as
result of GETSTS monitor call).
6-13
TRAPPING, INTERCEPTING, AND INTERRUPTING
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: Control Flags
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 Reserved for use by DIGITAL.
1 PS.VPO Disable all interrupts until your program
re-enables them by using the PISYS_. monitor
call.
2 PS.VTO Disable all interrupts of higher priority
until your program issues a DEBRK_. monitor
call.
3 PS.VAI Allow additional interrupts.
4 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.
5 PS.VPM Print the standard message, if one is relevant
to this interrupt condition.
6 Reserved for use by DIGITAL.
______________________________________________________________________
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.
6-14
TRAPPING, INTERCEPTING, AND INTERRUPTING
Table 6-3: I/O Interrupt Conditions
______________________________________________________________________
Bit Symbol Meaning Bit Symbol Meaning
______________________________________________________________________
19 PS.RID Input done 26 PS.RQE Quota exceeded
20 PS.ROD Output done 27 PS.RWT I/O wait
21 PS.REF End-of-file 28 PS.ROL Device on line
22 PS.RIE Input error 29 PS.RRC RIB has changed
23 PS.ROE Output error 30 PS.RDH Device hung
24 PS.RDO Device off line 31 PS.RSW Reel switch
25 PS.RDF Device full 32 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-15
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 return 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 An illegal monitor call has been executed. The
status word contains the illegal monitor call.
-6 .PCIMR An illegal memory location has been referenced.
The status word contains the illegal effective
address.
-7 .PCACK An address check has occurred. The status word
contains the device name.
-10 .PCARI An 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 memory location has been
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 An external condition has caused a fatal error in
your job.
-17 .PCKSY A KSYS warning has occurred. The status word
contains the minutes left until KSYS.
-20 .PCDSC The dataset status has changed. The status word
contains the new dataset status.
6-16
TRAPPING, INTERCEPTING, AND INTERRUPTING
-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.
-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
half, and the flag word in the right half. The
IPCF communications facility is described in
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.
This 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.
6-17
TRAPPING, INTERCEPTING, AND INTERRUPTING
-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. No flags are returned.
-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.
______________________________________________________________________
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 or
DDT.
o The interrupt system is not active (turned off).
o The condition occurred during an interrupt routine that is of
equal or higher priority.
If the PSI vector is not usable, the monitor will halt your program
and the following message will be displayed:
?PSI interrupt vector at addr, for CONDITION, DEVICE, is paged out,
(symbol) (name) write-
protected,
or
illegal
6-18
TRAPPING, INTERCEPTING, AND INTERRUPTING
In the message, addr refers to the address of the illegal vector. The
condition symbol is 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.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
;This program writes a file containing the integers ; from 0 to 100000
while doing a compute-bound background ; task. Because the program
never blocks for I/O, ; it can use all of the available CPU time. ;
By using the programmed interrupt system, it drives ; the disk at full
speed.
SEARCH UUOSYM ;Symbol definitions
;ACs
T1==1 ;Work N==2 ;Number to write on disk
;I/O channels
DSK=1 ;Disk file
;Initialization
START: RESET ;Reset everything MOVEI T1,VECTOR
;Get address of PI vector block PIINI. T1, ;Initialize PI system
HALT ;Not implemented OPEN DSK,[UU.AIO+.IOBIN ;Open disk
for asynch binary output SIXBIT /DSK/ XWD OB, 0]
HALT ;Can't write MOVE T1,[PS.FAC+[EXP DSK
XWD 0,PS.ROD ;Offset,,output done EXP
0]] ;Priority 0,,reserved PISYS. T1, ;Enable for output done
on disk HALT ;Failed MOVEI N,0 ;Initialize N
6-19
TRAPPING, INTERCEPTING, AND INTERRUPTING
;Here on an output-done interrupt or at start of program
OUTDON: SOSGE BYTECT ;Room in this buffer? JRST DMPBUF
;No, go output buffer IDPB N,BYTEPT ;Yes, store in this
buffer CAME N,[^D100000] ;Done? AOJA N,OUTDON ;No, back for
next number CLOSE DSK, ;Yes, close the disk file EXIT
;Finished
;Here to output the buffer
DMPBUF: OUT DSK, ;Write out the buffer JRST OUTDON
;No errors and more buffers STATZ DSK,IO.ERR ;Any errors?
HALT ;Fatal I/O error
;Here all available buffers are full, so we want to go back ; to the
background task.
DEBRK. ;Dismiss the interrupt HALT ;Can
never get here
;Here if no interrupt was in progress. We were called by
; initialization, and must now start the background task.
MOVSI T1,(PS.FON) ;Turn on the PSI system so we can
PISYS. T1, ; get traps from background task HALT ;Can't turn it
on LOOP: MOVEI T1,0 ;Simple-minded background task
AOJA T1,LOOP ;Do it again
;Buffer ring header
OB: BLOCK 1 BYTEPT: BLOCK 1 ;Byte pointer BYTECT:
BLOCK 1 ;Byte count
;Interrupt vector
VECTOR: EXP OUTDON ;New PC EXP 0 ;Old PC stored here
EXP 0 ;Flags EXP 0 ;Status
END START
6-20
CHAPTER 7
COMMUNICATING BETWEEN PROCESSES USING IPCF
The TOPS-10 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:
o The IPCFS. UUO sends an IPCF packet to another process.
o The IPCFR. UUO retrieves a packet sent by another process.
o The IPCFQ. UUO queries the IPCF input queue about your job.
o The IPCFM. UUO replaces a message exchange with a system
process.
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
COMMUNICATING BETWEEN PROCESSES USING IPCF
7.1 PACKETS
Information is transferred in the form of packets from one process to
another. Each packet is divided into two parts:
o A Packet Header Block (PHB) of four to six words in length.
o A Packet Message Block (PMB), which contains the actual
message.
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.
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:
0 17 18 35
-------------------------------------------
.IPCFL | Flags |
|-----------------------------------------|
.IPCFS | Sender's PID |
|-----------------------------------------|
.IPCFR | Receiver's PID |
|---------------------|-------------------|
.IPCFP | Length of message | PMB address |
|---------------------|-------------------|
.IPCFU | Project-programmer number of sender |
|-----------------------------------------|
.IPCFC | Capabilities of sender |
-------------------------------------------
Figure 7-1: Packet Header Block
7-2
COMMUNICATING BETWEEN PROCESSES USING IPCF
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 Handle) of the sending
process.
o The sending process's PID. (A PID is a unique Process
IDentifier that you can obtain from [SYSTEM]INFO.)
o 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.
o Zero. If you place a zero in this word, the monitor will
assume one of the following:
1. If your job has any PID(s), the monitor will choose one.
2. If your job has no PID(s), the monitor will use the JCH
for your current context.
In many cases, the job number sufficiently identifies a process, and a
PID need never be used. The PID 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 PIDs.
Word 2 (.IPCFR) contains the receiver's process identifier, which may
be a job number, JCH, 0, a PID, or address of PID (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 PID. Refer to Section 7.6 for more information about
receiving packets.
7-3
COMMUNICATING BETWEEN PROCESSES USING IPCF
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. The IPCF
capability word is described in Section 7.2.5.
7.2.1 IPCF Instruction Flags
The following instruction flags can be stored in the left half of Word
0 (.IPCFL) of the PHB. They are optional, and are listed here
according to their bit positions.
Bits Symbol Meaning
0 IP.CFB Do 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.
1 IP.CFS Use the PID obtained from the address specified
in .IPCFS as the sender's PID; this PID is
called the indirect sender's PID.
2 IP.CFR Use the PID obtained from the address specified
in .IPCFR as the receiver's PID; this PID is
called the indirect receiver's PID.
3 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.
7-4
COMMUNICATING BETWEEN PROCESSES USING IPCF
4 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 setting
.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.
5 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).
6 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.
7.2.2 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 Meaning
7-17 Reserved for use by DIGITAL.
18 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.
19 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-5
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.
21 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.
22-23 Reserved for use by DIGITAL.
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
1 .IPCCC The packet was sent by
[SYSTEM]IPCC.
2 .IPCCF The packet was sent by
system-wide [SYSTEM]INFO.
3 .IPCCP The packet was sent by the
receiver's local [SYSTEM]INFO.
4 .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.
7-6
COMMUNICATING BETWEEN PROCESSES USING IPCF
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.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
packet, .IPCFS can be zero. When receiving a packet, .IPCFR can be
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. PIDs are
assigned by [SYSTEM]INFO, and may or may not be accompanied by a
symbol name.
PIDs are assigned to a process by [SYSTEM]INFO. There can be any
number of PIDs assigned to a process, up to the maximum PID quota,
which by default is two. Each PID is unique and never reused until
the system is reloaded; in this case, all previous PID assignments are
cleared. Both communicating processes should agree on the PIDs 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 PID. [SYSTEM]INFO will not allow the assignment of a
name that is already assigned to another PID, unless the owner of that
name makes the request.
7-7
COMMUNICATING BETWEEN PROCESSES USING IPCF
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 Example
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']WONDER/
text[project,'ANY'] ASCIZ /FILE[10,'ANY']/
[project,'ANY']text ASCIZ /[23,'ANY']CLASS/
[SYSTEM]text ASCIZ /[SYSTEM]GOPHER/
text[SYSTEM] ASCIZ /GOTO[SYSTEM]/
The wildcard character * can be substituted for the phrase 'ANY'.
Note that the following strings are different:
Format Example
Name[PPN] ASCIZ/FOO[10,10]/
[PPN]Name ASCIZ/[10,10]FOO/
When a PPN is used as part of the symbolic name, it must be the PPN
under which the process is 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-8
COMMUNICATING BETWEEN PROCESSES USING IPCF
7.2.5 IPCF Capability Word
Word 5 (.IPCFC) of the PHB 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:
Bits Symbol Meaning
0 IP.JAC The sender of the packet is running with the
JACCT bit set; it is a privileged process.
1 IP.JLG The sender of the packet is logged-in.
2 IP.SXO The sender of the packet is an execute-only job.
3 IP.POK The sender of the packet has POKE privileges.
4 IP.IPC 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.
5-17 Reserved for DIGITAL.
18-26 IP.SCN Sender's context number
27-35 IP.SJN This field contains the job number of the
sender.
7.3 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 PHB to be 1000.
o Specify the page number in the right half of .IPCFP.
o Set Bit 19 (instruction flag IP.CFV) in Word 0 (.IPCFL) of
the PHB.
o 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.
o 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.
7-9
COMMUNICATING BETWEEN PROCESSES USING IPCF
7.4 QUOTAS
For each process, outstanding IPCF messages are counted for sending
and receiving. 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 (IPCFRS%) 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 IPCFS. is show below:
MOVE ac,[XWD len,addr] ;Point to PHB
IPCFS. ac, ;Send the packet
error return ;Something wrong
normal return ;Continue
. . .
addr: flags ;PHB
sender's PID
receiver's PID
XWD len2,addr2
. . .
addr2: message ;PMB
7-10
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 PID and the the
receiver's PID. 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:
MOVE ac, [XWD len,addr] ;Set up call
IPCFR. ac, ;Retrieve the packet
error return ;Something wrong
normal return ;Continue
. . .
addr: flags ;PHB
0
0
XWD len2,addr2
. . .
addr2: BLOCK 12 ;PMB
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 PID 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 PID (.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 PID-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 for the
next message, and the type of message that is waiting.
7-11
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 in your input queue, use the
IPCFQ. monitor call as shown:
MOVE ac, [len,addr] ;Set up call
IPCFQ. ac, ;Query the next packet
error return ;Something wrong
normal return ;Continue
. . .
addr: flags ;PHB
0
0
XWD 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 PIDs. Word 3, .IPCFP, contains
len2, the length of the next packet, and n, the number of messages in
the receive 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 PID in Word 1 (.IPCFS) and setting the flag IP.CRP in the
flag word.
If there is no packet in the queue, IPCFQ. takes the error return,
with error code 3 (IPCNP%) in the AC.
7-12
COMMUNICATING BETWEEN PROCESSES USING IPCF
7.8 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 request 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.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 to [SYSTEM]INFO is shown
below:
MOVE ac,[XWD len,addr]
IPCFS. ac,
error return
normal return
. . .
addr: flags
0
0
XWD len2,addr2+.IPCI0
. . .
addr2+.IPCI0: XWD ack-code,fcn-code
addr2+.IPCI1: 0 or duplicate PID
addr2+.IPCI2: argument
In the calling sequence, the PHB is set up as described in Section
7.2. Note that the PID for [SYSTEM]INFO is always 0.
7-13
COMMUNICATING BETWEEN PROCESSES USING IPCF
The PMB specifies the information that [SYSTEM]INFO requires, as
follows:
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. The [SYSTEM]INFO
function codes are listed below.
duplicate PID is the PID of the process that you would like to
receive a duplicate copy of the response from [SYSTEM]INFO. If
no process is to receive a duplicate copy, this value should be
zero.
argument is the argument to the function code. The argument
depends on the function code, and these are listed below.
The calling sequence to retrieve a packet sent by [SYSTEM]INFO is
shown below:
MOVE ac,[len,,addr]
IPCFR. ac,
error return
normal return
. . .
addr: flags
0
0
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 addr2 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+.IPCI0/ ack-code,,fcn-code
addr2+.IPCI1/ PID
addr2+.IPCI2/ symbolic name
7-14
COMMUNICATING BETWEEN PROCESSES USING IPCF
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
1 .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: XWD user-code,.IPCIW
PID for name
symbolic name
2 .IPCIG 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
3 .IPCII Requests [SYSTEM]INFO to assign a PID to the
calling process and to associate the symbolic
name with the newly assigned PID. The format
of the request is:
addr2: XWD user-code,.IPCII
PID for copy or zero
symbolic name
The format of the response is:
addr2: XWD user-code,.IPCII
PID
symbolic name
7-15
COMMUNICATING BETWEEN PROCESSES USING IPCF
Any PID obtained from [SYSTEM]INFO as a
result of an .IPCII request is disassociated
from the calling job when the job performs a
RESET. PIDs obtained with this function code
have the format: 4nnnnn,,nnnnnn.
To obtain a PID without a symbolic name,
simply zero the word at addr2+2.
4 .IPCIJ Requests [SYSTEM]INFO to assign a job-wide
PID. This differs from .IPCII in that the
PID 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: XWD user-code,.IPCIJ
PID for copy or zero
symbolic name
The format of the response is:
addr2: XWD user-code,.IPCIJ
PID
symbolic name
Any PID 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. PIDs obtained with this
function code have the format:
0nnnnn,,nnnnnn.
A job can have more than one PID and symbolic
name assigned to it. However, there is a
maximum number of PIDs that can be assigned
to a job. If a request is made for a PID and
the PID quota has been filled, the flag word
of the response from [SYSTEM]INFO contains
error code 73 in the error code field. The
PID quota is stored in GETTAB Table .GTIPC,
Item %IPCDQ.
7-16
COMMUNICATING BETWEEN PROCESSES USING IPCF
5 .IPCID Requests [SYSTEM]INFO to disassociate the
specified PID from its job number. This
function can be requested only by the owner
of the specified PID or by an IPCF privileged
process. The format of the request is:
addr2: XWD user-code,.IPCID
PID for copy or zero
PID to be dropped
The format of the response is:
addr2: XWD user-code,.IPCID
0
PID that was dropped
6 .IPCIR Requests [SYSTEM]INFO to disassociate all
PIDs that were created by .IPCII 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,.IPCIR
PID for copy or zero
job-number or JCH
The format of the response is:
addr2: XWD user-code,.IPCIR
0
job-number or JCH
7 .IPCIL Requests [SYSTEM]INFO to disassociate all
PIDs that were created by .IPCIJ 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,.IPCIL
PID for copy or zero
job-number or JCH
The format of the response is:
addr2: XWD user-code,.IPCIL
0
job-number or JCH
7-17
COMMUNICATING BETWEEN PROCESSES USING IPCF
10 .IPCIN Requests notification from [SYSTEM]INFO when
a specified PID has been disassociated from a
job. The format of the request is:
addr2: XWD user-code,.IPCIN
PID for copy or 0
PID
The format of the response is:
addr2: XWD user-code,.IPCIN
0
PID
15 .IPCIS Used only by [SYSTEM]IPCC on the execution of
the LOGOUT and RESET monitor calls.
7.8.2 [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 is
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,[XWD len,addr]
IPCFS. ac,
error return
normal return
. . .
addr: flags
sender's PID
receiver's PID
XWD len2,addr2+.IPCS0
. . .
addr2+.IPCS0: XWD ack-code,function-code
addr2+.IPCS1: argument1
addr2+.IPCS2: argument2
addr2+.IPCS3: argument3
7-18
COMMUNICATING BETWEEN PROCESSES USING IPCF
In an IPCC request, the PHB is set up as described in Section 7.2.
[SYSTEM]IPCC's PID, 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.
The type of argument and number of argument words is different
depending on the function code used. Therefore, they are described
with the function codes, listed below.
The format for retrieving a packet sent by [SYSTEM]IPCC is:
MOVE ac,[len,,addr]
IPCFR. ac,
error return
normal return
. . .
addr: flags
0
0
len2,,addr2
. . .
addr2: BLOCK 12
Where: 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 PID.
The response, starting at addr2, will be in the following general
format:
Word Contents
addr2+.IPCS0/ ack-code,,fcn-code
addr2+.IPCS1/ [SYSTEM]IPCC response
addr2+.IPCS2/ .
addr2+.IPCS3/ .
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]IPCC's response depends on the function you specified.
Responses for each function code are listed below. Words not needed
for [SYSTEM]IPCC's response will remain unchanged.
7-19
COMMUNICATING BETWEEN PROCESSES USING IPCF
[SYSTEM]IPCC Function Codes
Fcn-code Symbol Meaning
-n Negative function codes are reserved for use
by customer programs.
1 .IPCSE Requests [SYSTEM]IPCC to enable the specified
job number 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,.IPCSE
job-number
The format of the response from [SYSTEM]IPCC
is identical to the format of the request.
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 [SYSTEM]IPCC
is:
addr2: XWD user-code,.IPCSI
PID for [SYSTEM]INFO
7-20
COMMUNICATING BETWEEN PROCESSES USING IPCF
4 .IPCSF 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 n 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 0. If n is a job number, a PID for
a local [SYSTEM]INFO is created for the
specified 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.
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 is identical to
the format of the request.
7-21
COMMUNICATING BETWEEN PROCESSES USING IPCF
6 .IPCSC Requests [SYSTEM]IPCC to create a PID for a
specified job number or JCH. This function
is unprivileged for your job or JCH, and
within your PID quota. The format of the
request is:
addr2: 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 type by
setting/clearing Bit 0. 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 until the job logs off the system. In
the left half of addr2+1, you specify the
job-number for which the PID is desired.
[SYSTEM]IPCC returns the PID for the
specified job in addr2+1.
7 .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.
10 .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 is identical to
the format of the request.
7-22
COMMUNICATING BETWEEN PROCESSES USING IPCF
11 .IPCSJ Requests [SYSTEM]IPCC to return the JCH
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: XWD user-code,.IPCSJ
PID
JCH
12 .IPCSP 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: XWD user-code,,.IPCSP
addr2+1: job-number or JCH
addr2+2: starting PID or 0
The PIDs are returned starting with addr2+2
in the form:
addr2: user-code,.IPCSP
job number or JCH
PID
.
.
.
addr+n: PID
13 .IPCSR Requests [SYSTEM]IPCC to return the send and
receive 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
7-23
COMMUNICATING BETWEEN PROCESSES USING IPCF
15 .IPCSS Reserved for DIGITAL.
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 takes the same form as the
request.
17 .IPCQR 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: XWD user-code,.IPCQR
target
PID quota
20-22 Reserved to DIGITAL.
23 .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: XWD user-code,.IPCLP
PID
Index of the located PID
7-24
COMMUNICATING BETWEEN PROCESSES USING IPCF
24 .IPCWP [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
25 .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
The response takes the form:
code,,.IPCRP
offset
PID
Special system PIDs are:
Code Symbol Meaning
-2 - - Reserved for customer
definition
-1 - - Reserved for customer
definition
0 .IPCPS [SYSTEM]IPCC
1 .IPCPI [SYSTEM]INFO
2 .IPCPQ [SYSTEM]QUASAR
3 .IPCPM Mountable Device Allocator
4 .IPCPT Tape Label Process
5 .IPCPF File Daemon
6 .IPCPC Tape Automatic Volume
Recognition Process
7 .IPCPA [SYSTEM]Accounting
10 .IPCPO Operator Interface
11 .IPCPL System Error Logger
12 .IPCPD Disk Automatic Volume
Recognition Process
13 .IPCPE [SYSTEM]TGHA
14 .IPCNM Network Management (NCP)
15 .IPCPG [SYSTEM]GOPHER
16 .IPCPV [SYSTEM]CATALOG
17 .IPCPX [SYSTEM]MAILER
7-25
COMMUNICATING BETWEEN PROCESSES USING IPCF
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.
27 .IPCSL [SYSTEM]IPCC will send a logout message to
[SYSTEM]QUASAR. The job-number is returned
in addr2+1.
30 .IPCTL [SYSTEM]IPCC sends a tape labeling message.
31 .IPCUO A mountable unit is on-line. (IPCC)
32 .IPCON LOGIN message sent to [SYSTEM]QUASAR. (IPCC)
33 .IPCAC Accounting messages. (IPCC)
34 .IPCDE MDA-controlled device deassigned. (IPCC)
35 .IPCME MDA memory error. (IPCC)
36 .IPCCS Reserved.
37 .IPCRS Reset with locked structure to MDA. (IPCC)
40 .IPCQU QUEUE UUO to MDA. (GOPHER)
41 .IPCLC Search list change to MDA. (IPCC)
42 .IPCAT Primary disk port attach to MDA. (IPCC)
43 .IPCDT Primary disk port detach to MDA. (IPCC)
44 .IPCXC Disk unit exchange to MDA. (IPCC)
45 .IPCRM Structure removal to MDA. (IPCC)
46 .IPCMT Magtape unit accessible to MDA. (IPCC)
47 .IPCST Structure mount to MDA. (IPCC)
50 .IPCIM IPCFM. UUO request to [SYSTEM]INFO. (GOPHER)
51 .IPCSM Schedule bits change to [SYSTEM]QUASAR.
7-26
COMMUNICATING BETWEEN PROCESSES USING IPCF
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 UUOSYM ;For TOPS-10 UUO symbols
SEARCH GLXMAC,QSRMAC ;For GALAXY and QUASAR symbols
T4=1+<T3=1+<T2=1+<T1=1>>> ;Define some ACs to use
P=17 ;PHL pointer
PDLSIZ==30 ;Push down list length
PHBLEN==6 ;Packet header block length
PMBLEN==12 ;Packet message block length
NAMLEN==<D29/5>+1 ;Max length of a name in words
ACKCOD==171004 ;Initial ack code
PAGSIZ==1000 ;Length of a page in words
PAG==400 ;Page number for page receives
IPCF: JFCL ;No CCL entry
RESET ;Stop the world
MOVE P,[IOWD PDLSIZ,PDL] ;Set up push down list pointer
MOVEI T1,ACKCOD ;Get initial ack code
MOVEM T1,ACK ;Save it for later use
MOVE T1,[%SIQSR] ;Argument to return a PID
GETTAB T1, ;Get QUASAR's PID
SETZ T1, ;Assume QUASAR isn't running
JUMPE T1,NOQSR ;Is it?
MOVEM T1,QSR ;Save the PID
PUSHJ P,GENNAM ;Generate a name
PUSHJ P,GETPID ;Get a PID from [SYSTEM]INFO
PUSHJ P,SNDQSR ;Send queue list request to QUASAR
PUSHJ P,RCVQSR ;Receive and list the queues
EXIT ;Return to monitor level
7-27
COMMUNICATING BETWEEN PROCESSES USING IPCF
;Generate an ASCIZ name to associate with our PID.
; To insure the name is unique, our job number will
; be appended to the end of the name text.
GENNAM: SETZM NAM ;Clear out
MOVE T1,[NAM,,NAM+1] ;Name text
BLT T1,NAM+NAMLEN-1 ;Storage
MOVE T4,[POINT 7,NAM] ;Set up byte ptr to storage
MOVE T2,[POINT 7,TXT] ;Set up byte ptr to initial text
GENNA1: ILDB T1,T2 ;Get a character
JUMPE T1,GENNA2 ;End of text?
IDPB T1,T4 ;Put a character
JRST GENNA1 ;Loop through text string
GENNA2: PJOB T1, ;Get our job number
SETZ T3, ;Clear a counter
GENNA3: IDIVI T1,12 ;Divide by 10 (decimal)
PUSH P,T2 ;Save remainder
SKIPE T1 ;Done?
AOJA T3,GENNA3 ;No--recurse
GENNA4: POP P,T1 ;Get a digit
ADDI T1,"0" ;Make it ASCII
IDPB T1,T4 ;Append to name
SOJGE T3,GENNA4 ;Loop for all digits
POPJ P, ;And return
;Get a named PID from [SYSTEM]INFO. This routine uses
; the name text generated by GENNAM.
GETPID: SETZM PHB+.IPCFL ;Clear first word of PHB
SETZM PHB+.IPCFS ;Default our PID
SETZM PHB+.IPCFR ;0 is [SYSTEM]INFO's PID
MOVE T1,[PMBLEN,,PMB] ;Load length,,addr of PMB
MOVEM T1,PHB+.IPCFP ;Point to PMB
SETZM PHB+.IPCFU ;No PPN
SETZM PHB+.IPCFC ;Zero capability word
AOS T1,ACK ;Add one to make unique ack-code
HRLZS T1 ;Set up ack-code
HRRI T1,.IPCII ;Request PID with name
MOVEM T1,PMB+.IPCI0 ;Load ack,,fcn-code into PMB
SETZM PMB+.IPCI1 ;Zero second word of PMB
MOVE T1,[NAM,,PMB+.IPCI2] ;Pointer to load name into PMB
BLT T1,PMB+.IPCI2+NAMLEN-1 ;Load name into PMB
PUSHJ P,IPCSND ;Send packet
GETPI1: PUSHJ P,IPCRCV ;Retrieve packet
HLRZ T1,PMB+.IPCS0 ;Get ack-code of packet
CAME T1,ACK ;Compare with ack of sent packet
JRST GETPI1 ;Acks not equivalent, try again
MOVE T1,PMB+.IPCS1 ;Get our PID
MOVEM T1,PID ;Store our PID
POPJ P, ;Return
7-28
COMMUNICATING BETWEEN PROCESSES USING IPCF
;Build 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).
SNDQSR: SETZM PHB+.IPCFL ;No IPCF flags
MOVE T1,PID ;Get our PID
MOVEM T1,PHB+.IPCFS ;Make it the sender's PID
MOVE T1,QSR ;Get QUASAR's PID
MOVEM T1,PHB+.IPCFR ;Make it the receiver's PID
MOVE T1,[PMBLEN,,PMB] ;Get length and address of PMB
MOVEM T1,PHB+.IPCFP ;Point the monitor at the PMB
MOVE T1,[PMBLEN,,.QOLIS] ;Length,,msg type (queue listing)
MOVEM T1,PMB+.MSTYP ;Save it
SETZM PMB+.MSFLG ;Send no flags to QUASAR
AOS T1,ACK ;Get a new ack code
MOVEM T1,PMB+.MSCOD ;Save for comparison later
MOVEI T1,1 ;One data block in the message
MOVEM T1,PMB+.OARGC ;Save count in message
SETZM PMB+.OFLAG ;Request a normal queue listing
MOVE T1,[2,,.LSQUE] ;Queue block
MOVEM T1,PMB+.OHDRS+ARG.HD ;Save queue block header
SETOM PMB+.OHDRS+ARG.DA ;Save queue block data
PUSHJ P,IPCSND ;Send queue listing request
POPJ P, ;Return
;Receive 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: MOVEI T1,IP.CFV ;Returned message is a page
MOVEM T1,PHB+.IPCFL ;Save flag
MOVE T1,[PAGSIZ,,PAG] ;Length and page where to put msg
MOVEM T1,PHB+.IPCFP ;Point monitor at it
RCVQS1: PUSHJ P,IPCRCV ;Try to receive a msg
MOVE T1,<PAG_^D9>+.MSCOD ;Get ack code
CAME T1,ACK ;Make the one we sent out?
JRST RCVQS1 ;No--try again
MOVEI T1,<PAG_^D9>+.OHDRS ;Point to start of data in msg
RCVQS2: HRRZ T2,ARG.HD(T1) ;Get a block type
CAIN T2,.CMTXT ;Is this the queue listing text?
JRST RCVQS3 ;Yes--go output it
HLRZ T2,(T1) ;No--get this block length
ADDI T1,(T2) ;Offset to the next block
JRST RCVQS2 ;Keep searching
RCVQS3: OUTSTR ARG.DA(T1) ;Output listing text
POPJ P, ;Return
IPCSND: MOVE T1,[PHBLEN,,PHB] ;Load length,,addr of PHB
IPCFS. T1, ;Send packet
SKIPA ;Always skip on failure
POPJ P, ;Return
OUTSTR [ASCIZ |? Error sending packet|] ;Print error
EXIT ;Bomb out
7-29
COMMUNICATING BETWEEN PROCESSES USING IPCF
IPCRCV: MOVE T1,[PHBLEN,PHB] ;Load length,,addr of PHB
IPCFR. T1, ;Get packet
SKIPA ;Always skip on failure
POPJ P, ;Return
OUTSTR [ASCIZ |? Error receiving packet|] ;Print error
EXIT ;Bomb out
NOQSR: OUTSTR [ASCIZ |? Cannot get QUASAR's PID|] ;Print error
EXIT ;Bomb out
TXT: ASCIZ |IPCF demo Job | ;Symbolic name
PDL: BLOCK PDLSIZ ;Push down list
PHB: BLOCK PHBLEN ;Packet header block
PMB: BLOCK PMBLEN ;Packet message block
NAM: BLOCK NAMLEN ;Name to assign to PID
ACK: BLOCK 1 ;Ack code
PID: BLOCK 1 ;Our PID
QSR: BLOCK 1 ;QUASAR's PID
END IPCF
7-30
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 agreed that a character
string of the form:
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).
8-1
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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.
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.
8-2
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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 the 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.
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 may or 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.
8-3
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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 is 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 0. 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.
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.
8-4
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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-5
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 0.
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. Subsequent
requests in the call must have ascending level numbers.
8-6
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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.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.
8-7
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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.1.3.3 Deadlock 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-8
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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.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 the ENQ. argument list. The
block definition and data persist until either of the following
occurs:
o Another job redefines it.
o 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).
8-9
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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").
To support local buffer caching using the lock-associated block, each
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-10
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.4 ENQ/DEQ MONITOR CALLS
The ENQ. facility offers three monitor calls:
o 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).
o The DEQ. call releases a resource, cancelling the lock on the
resource, or cancels requests for a resource.
o 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.
8.5 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
0 .ENQLL Number of blocks and length:
Bits Symbol Meaning
0-5 EQ.BHS Header block size
6-17 EQ.LNL Number of lock blocks.
18-35 EQ.LLB Total length of the request
block.
1 .ENQRI Request identifier.
2 .ENQTL Time limit (number of seconds).
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 (EQ.LNL) is the number of lock blocks in the
list that follows.
8-11
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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 request identifier (.ENQRI) is an optional identifier for the
request. The left half of .ENQRI must be 0. 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
0 .ENQFL Flags, level, and channel:
Bits Symbol Meaning
0 EQ.FSR Sharable lock.
1 EQ.FBL Don't do level checking.
2 EQ.FLT Long-term lock.
3 EQ.FEL Eternal lock, released only on
request.
4 EQ.FAB Aborted lock. This flag is useful
on a modification function (.ENQMA)
to prevent the resource from being
locked by any other jobs.
5 EQ.FDD Enable deadlock detection.
6 EQ.FCW Specifies that .ENQBP contains a
36-bit user code.
7-8 Reserved.
9-17 EQ.FLV Level number.
8-12
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
18-35 EQ.FCC Channel number (if positive integer)
or code (if negative integer). The
codes are:
Code Symbol Meaning
-3 .EQFPL Privileged global
(system-wide) lock.
This lock code can
be used only by
jobs logged in
under [1,2] or jobs
with the JACCT
privilege. Thus,
only other jobs
with the [1,2] or
JACCT privileges
can share the lock.
-2 .EQFGL 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).
-1 .EQFJB Job-wide lock.
This flag prevents
other requests by
your job (including
other contexts) for
this resource from
being granted.
8-13
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
1 .ENQBP 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 7,address,bitplace
Where: bitplace is the location of the rightmost bit
in the first byte in the first word.
address is the address of the first word, or
a pointer of the form:
XWD -1,address
Where: 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.
2 .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.
3 .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.
4 .ENQTB 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 zero.
8-14
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
The ENQ. header/lock block structure looks as follows:
0 5 8 17 35
------------------------------------------
Header .ENQLL | EQ.BHS EQ.LNL | EQ.LLB |
Block |--------------------|-------------------|
.ENQRI | 0 | Request-id |
|----------------------------------------|
.ENQTL | Time Limit |
|----------------------------------------|
Lock .ENQFL | Flags EQ.FLV EQ.FCC |
Block |----------------------------------------|
.ENQBP | Byte Pointer or User Code |
|----------------------------------------|
.ENQPS | Pool Size or Sharer Group |
|----------------------------------------|
.ENQMS | Partition Mask Pointer |
|----------------------------------------|
.ENQTB | EQ.TLN | EQ.TBL |
------------------------------------------
Figure 8-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 ENQ. monitor call as
follows:
MOVE ac,[XWD fcncode,addr] ;Set up call
ENQ. ac, ;Enqueue the request
error return ;Didn't get resource
normal return ;Got it
Where: fcncode is one of the four ENQ. functions described below.
addr is the address of the argument list. The argument list
is described in Section 8.5.
The monitor attempts to lock each resource described by a lock block
in the argument list.
8-15
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
The ENQ. function codes are:
Fcn-code Symbol Meaning
0 .ENQBL Enqueue the request and wait until the
requested resources are available.
1 .ENQAA Dequeue the request immediately if any of the
requested resources is unavailable.
2 .ENQSI Enqueue the request and interrupt the program
when the requested resources are available.
3 .ENQMA Modify a previous request.
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 Only if Available
Your job can request locks on one or more resources, and prevent the
monitor from queueing the request. That is, the monitor grants the
request only if all the requested locks can be granted immediately;
otherwise, 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
takes 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.
8-16
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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.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 a request for the
lock), use the DEQ. monitor call as follows:
MOVE ac,[XWD fcncode,addr] ;Set up call
DEQ. ac, ;Dequeue the request
error return ;Failed
normal return ;Dequeued
Where: fcncode is one of the function codes discussed below.
addr is the address of the argument list for function codes 0
and 1, and contains the request-id for function 2.
8-17
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
The monitor releases each resource described by a lock block in the
argument list.
The DEQ. function codes are:
Fcn-code Symbol Meaning
0 .DEQDR Dequeue or release a specified lock.
1 .DEQDA DEQ. all requests and release all locks for
the job.
2 .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.7.2 Cancelling All 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 code, if
you have no requests or locks.
8-18
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.7.3 Cancelling 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, the
monitor takes the error return, giving the ENQNO% error code.
8.8 CONTROLLING ENQ/DEQ: ENQC. UUO
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
0 .ENQCS Obtain the status of a request.
1 .ENQCG Obtain the ENQ. quota of a specified job.
2 .ENQCC Set the ENQ. quota for a specified job.
3 .ENQCD Examine the monitor's ENQ/DEQ database.
Note that some of these functions require privileges. The functions
are described in the following sections.
8-19
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]
MOVEI ac+1,buffer
ENQC. ac,
error return
normal return
.
.
.
buffer: BLOCK <lock blocks>*3
Where: addr is the address of the request block, as described in
Section 8.8
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
0 .ENQCF Flags:
Bits Symbol Meaning
0 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.
1 EQ.CFO This user is owner.
2 EQ.CFQ This user is in queue.
3 EQ.CFX Owner's access is exclusive.
4-8 Reserved.
9-17 EQ.CFL Level.
8-20
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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.
1 .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.
2 .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-21
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.8.2 Obtaining the Quota for a Job
You can use an ENQC. function (.ENQCG) to obtain the ENQ. quota for a
user. The calling sequence for this function is:
MOVE ac,[XWD .ENQCG,addr]
ENQC. ac,
error return
normal return
.
.
.
addr: XWD 0,jobno
Where: 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.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: XWD quota,jobno
Where: 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 be set (-1
for your own job).
The monitor sets the quota for the specified job.
8-22
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
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: XWD 0,buflength
BLOCK buflength
Where: 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.
The following diagram shows the general format of the ENQC. dump:
|=======================================================|
| Number of words in block |
|=======================================================|
| |
| Dump block for first lock |
| |
|=======================================================|
\ \
. . .
\ \
|=======================================================|
| |
| Dump block for last lock |
| |
|=======================================================|
8-23
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
The format for each dump block is:
|=======================================================|
| |
| Lock block for this lock |
| |
|=======================================================|
| |
| Two-word queue block for first owner of this lock |
| |
|-------------------------------------------------------|
\ \
. . .
\ \
|-------------------------------------------------------|
| |
| Two-word queue block for last owner of this lock |
| |
|=======================================================|
| |
| Two-word queue block for first waiter for this lock |
| |
|-------------------------------------------------------|
\ \
. . .
\ \
|-------------------------------------------------------|
| |
| Two-word queue block for last waiter for this lock |
| |
|=======================================================|
Where each lock block is in the format:
Word Symbol Contents
0 .EQDFL Flags, level, and lock identifier:
Bits Symbol Meaning
0 EQ.DLB This is a lock block.
2 EQ.DLT This lock has text.
5 EQ.DLN This lock block will not be dequeued
on a reset.
6 EQ.DLA This lock is aborted; no new
requests will be granted.
9-17 EQ.DFL Level number.
18-35 EQ.DFI Lock identifier. (That is, the
access table address or code of -1,
-2, or -3.)
The flag word (.EQDFL) is returned as -1 at the end
of the list of queue blocks.
8-24
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
1 .EQDPR Pooled request counts:
Bits Symbol Meaning
0-17 EQ.DPS Size of pool.
18-35 EQ.DPL Number of resources available in the
pool.
2 .EQDTS Time stamp.
3 .EQDSU Resource identification string or numeric code.
The format of each 2-word queue block is:
Word Symbol Contents
0 .EQDFL Flags in the left half, and associated job number in
the right half.
Bits Symbol Meaning
1 EQ.DLO This is the lock owner.
3 EQ.DXA Exclusive access.
4 EQ.DJW This job is blocked waiting for
lock.
7 EQ.DQI This queue block is invisible.
8 EQ.DQD This queue block will be checked for
deadlocks.
1 .EQDGI Group number and request identifier:
Bits Symbol Meaning
0-17 EQ.DGR Group or number requested.
18-35 EQ.DRI Request identifier.
8.9 ENQ. ERRORS
For errors from ENQ. monitor calls (ENQ., DEQ., and ENQC.), the
monitor returns one of the following error codes in the AC:
Code Symbol Error
1 ENQRU% At least one of the requested resources is not
available.
2 ENQBP% You requested an illegal number of pooled
resources.
3 ENQBJ% You specified an illegal job number.
4 ENQBB% You specified an illegal byte size for the byte
pointer. The byte pointer must be 1 to 36
(decimal).
8-25
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
5 ENQST% ASCIZ string is too long. It must be less than
150 (decimal) characters.
6 ENQBF% You specified an illegal function code.
7 ENQBL% You specified an illegal argument list length.
The total length must be the header-block-size
plus (request-block-size times
number-of-requests).
10 ENQIC% You specified an illegal number of requests.
11 ENQBC% You specified an illegal channel number.
12 ENQPI% Your program does not have enough privileges for
specified function.
13 ENQNC% Not enough core available, or the maximum number
of active locks (item %EQMAQ in GETTAB Table
.GTENQ) has been exceeded.
14 ENQFN% File is not open or device is not a disk.
15 ENQIN% Address for byte pointer cannot be indirect or
indexed.
16 ENQNO% Your program cannot dequeue resources not owned
by your job.
17 ENQLS% Levels not specified in ascending order.
20 ENQCC% Illegal modification of ownership; you cannot
change a request from shared to exclusive
ownership. DEQ. first, then re-ENQ.
21 ENQQE% Enqueue quota exceeded; your quota is set by the
system administrator.
22 ENQPD% Number of resources in pool disagrees with number
in your request.
23 ENQDR% Duplicate request; the request is identical to a
request already queued by your job.
24 ENQNE% The resource cannot be dequeued because it is not
enqueued for your job.
25 ENQLD% Level in request does not match lock.
26 ENQED% Not enough privileges for ENQ/DEQ; you must have
JP.ENQ set.
27 ENQME% Mask too long or lengths do not match.
30 ENQTE% Lock-associated block is too long.
31 ENQAB% A resource that was requested has been marked as
aborted.
32 ENQGF% 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).
33 ENQDD% A deadlock was detected.
34 ENQTL% The specified time limit was exceeded.
8-26
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
8.10 EXAMPLE USING THE ENQ. FACILITY
An example of the ENQ. monitor call is shown below.
TITLE ENQEXA - A simple ENQ application
SUBTTL PETER VATNE 6-JUN-83
SEARCH JOBDAT,MACTEN,UUOSYM ;Get standard symbol definitions
SALL ;Make listing pretty
T1=1 ;Temporary ACs
T2=2
T3=3
T4=4
P=17 ;Push down pointer
IO==1 ;Input-output disk channel
LN$PDL==40 ;Stack size
LN$DAT==200 ;Data block size
DEFINE ERROR (COD,TXT),< ;;Standard error macro
JRST [OUTSTR [ASCIZ/?ENQ'COD 'TXT/]
RESET ;;Clear all locks, etc.
MONRT. ;;Return to monitor fast
JRST START] ;;Start all over again>
TWOSEG 400000 ;Make program sharable
START: JFCL ;In case of CCL entry
RESET ;Reset the world
MOVE P,[IOWD LN$PDL,PDLST] ;Initialize push down list
MOVE T1,[SIXBIT /DATA/]
MOVEM T1,LKPBLK ;File name is DATA
MOVSI T1,'DAT'
MOVEM T1,LKPBLK+1 ;File extension is .DAT
MOVE T1,[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. T1, ;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
MOVEI T3,LN$DAT*5 ;Count of character
SETZM MSGBLK ;Zero out message block
MOVE T1,[MSGBLK,,MSGBLK+1] ;..
BLT T1,MSGBLK+LN$DAT-1 ;..
OUTSTR [ASCIZ /INPUT>/];PROMPT
8-27
RESOURCE CONTROLS: THE ENQ/DEQ FACILITY
TTYINP: INCHWL T1 ;Read a character (line mode)
CAIN T1,.CHCNZ ;^Z?
EXIT ;Yes, done with program
SOSL T3 ;Room left in message block
IDPB T1,T2 ;Yes, append to message
CAIE T1,.CHLFD ;End of line?
JRST TTYINP ;No, loop for more
MOVE T1,[.ENQBL,,[1B5+1B17+3 ;Header=1,locks=1,length=3
EQ.FCW+IO ;Code word,level=0,channel=1
-1]] ;Arbitrary code
ENQ. T1, ;Lock the resource
ERROR (CEB,Can't ENQ. a block for DATA.DAT)
USETI T1,1 ;Set to block 1
INPUT T1,[IOWD LN$DAT,DATBLK
Z] ;Read the block
USETO T1,1 ;Set to block 1
OUTPUT T1,[IOWD LN$DAT,MSGBLK
Z] ;Write new message
MOVE T1,[.DEQDA,,0] ;DEQ all locks
DEQ. T1, ;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
LIT ;Store the literals in the high seg
RELOC ;Switch to low segment storage
LKPBLK: BLOCK 4 ;Storage for LOOKUP block
ENTBLK: BLOCK 4 ;Storage for ENTER block
DATBLK: BLOCK LN$DAT ;Storage for data block
MSGBLK: BLOCK LN$DAT ;Storage for message input
PDLST: BLOCK LN$PDL ;Storage for push-down list
END START
8-28
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 on KS processor
systems.
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:
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 all other jobs to
facilitate realtime processing.
LOCK Locks a job in core.
9-1
PROGRAMMING FOR REALTIME EXECUTION
9.1 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 it interrupts your program. To accomplish this, the
monitor places BLKI/BLKO in the skip chain.
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.
o 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.
o Executive Process Table (EPT) relative mode, in which the
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 CONSO 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 CONSO skip chain
DEV'INT: CONSO DEV1,bits
JRST DEV2'INT
.
.
.
DISMISS
9-2
PROGRAMMING FOR REALTIME EXECUTION
DEV2'INT: CONSO 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 TM0INT
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.)
Using normal or fast block mode places a BLKI or BLKO instruction
directly on a PI level. Since this instruction is executed in
executive mode, you must first lock your job in executive virtual
memory.
In normal block mode, the monitor places the BLKI or BLKO instruction
directly after the entry for the device in the monitor's CONSO 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.
9-3
PROGRAMMING FOR REALTIME EXECUTION
On a normal return from a RTTRP monitor call, the job is granted IOT
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 DATAI JEN
CONI DATAI XSFM
CONSO BLKI XJEN
CONSZ BLK0
A RTTRP monitor call with the PI level (see below) given as zero
produces the IOT privilege without setting up a device.
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 CONSO 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 CONSO skip chain for each interrupt level; if a device
interrupts whose CONSO instruction is further down the chain than the
device itself, the CONSO is executed. If a hardware device flag is
set (and the corresponding bit is set in the CONSO bit mask), the
CONSO 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 CONSO bit mask in the your
area (for example, at MSKADD) and use an indirect address in the CONSO
instruction (for example, CONSO 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, it must
also remove it from the interrupt level with a CONO device,0
instruction.
The calling sequence for the RTTRP monitor call is:
MOVEI 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.
9-4
PROGRAMMING FOR REALTIME EXECUTION
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 following in the PI level
field:
1. A positive PI channel. Specifying level 0 with the RTTRP
monitor call releases the device. Levels 1 and 2 are
often reserved for tape devices such as TD10 or TM10.
Levels 3 through 6 are legal levels. Level 7 is always
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 CPU0, 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.
2. 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.
3. A bit mask in the form:
1B0 + <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 positive
PI channel.
4. A bit mask in the form:
1B0 + 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-5
PROGRAMMING FOR REALTIME EXECUTION
o 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.
o 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.)
o 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.
o Bit mask
A mask is defined in each CONSO instruction in a realtime
trap. The mask bits differ for each device. See the
Hardware Reference Manual for a list of the bits in each
mask. The CONSO instruction can be written as:
CONSO device,mask
Where: mask is in the address field of the instruction; or
the CONSO instruction can be written as:
CONSO device,@mskadd
. . .
mskadd: XWD 0,mask
Where: mskadd is the address of the word (in your area,
which is locked in executive virtual memory)
containing the mask.
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).
9-6
PROGRAMMING FOR REALTIME EXECUTION
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.
o Interrupt flags
Realtime interrupt flags (given as flags in the argument
lists in this chapter) are as follows:
Flag Meaning
0 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 CPU0:.
1 There are multiple device references in the
interrupt chain. Thus, the device can generate
interrupts on more than one PI channel.
15 This is an EPT-mode interrupt; the address given
in addr+2 is an offset into the executive page
table.
16 The device indicated in the argument list supports
and produces vectored interrupts.
17 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-7
PROGRAMMING FOR REALTIME EXECUTION
9.1.1 Normal Block Mode
The RTTRP argument list for normal block mode is:
addr: XWD level,realtrap
XWD flags,aprtrap
CONSO device,mask
BLKx device,blockaddr
Where: level is the interrupt level for the device.
realtrap is the address of the interrupt service routine for
the given device.
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.
Example
TITLE RTNBLK - Papertape read test in BLKI mode
SEARCH UUOSYM ;Standard symbols
;Some values
TAPE=400 ;No more tape in reader if TAPE=0
BUSY=20 ;Device is busy reading
DONE=10 ;A character has been read
AC1=1 ;Work register
AC2=2 ;Work register
TABLEN=200 ;Table length
PICHAN=6 ;PI channel
;Storage
;Realtime data block
RTBLK: XWD PICHAN,TRPADR ;PI channel and trap address
XWD 0,APRTRP ;Flags and APR trap
CONSO PTR,DONE ;Wait only for done flag
BLKI PTR,POINTR ;Read a block at a time
9-8
PROGRAMMING FOR REALTIME EXECUTION
POINTR: IOWD TABLEN,TABLE ;Pointer for BLKI instruction
OPOINT: BLOCK 1 ;Original pointer
TABLE: BLOCK TABLEN ;Table area for data being read
DONFLG: BLOCK 1 ;PI level to user level command
RTBLK1: EXP 0 ;Data block to remove PTR
EXP 0 ; from PI channel
CONSO PTR,0
EXP 0
;Here we begin
BLKTST: RESET ;Reset the program
MOVE AC1,[LK.HLS+LK.LLS] ;Lock both segments
LOCK AC1, ;Lock the program in core
JRST FAILED ;LOCK call failed
MOVEI AC1,RTBLK1 ;Get address of realtime block
RTTRP AC1, ;Get user IOT privilege
JRST FAILED ;RTTRP call failed
CONO PTR,0 ;Clear all PTR bits
SETZM DONFLG ;Initialize the done flag
MOVEI AC1,RTBLK ;Get address of realtime data block
RTTRP AC1, ;Put realtime device on PI level
JRST FAILED ;RTTRP call failed
MOVE AC1,POINTR ;Get relocated pointer for later
MOVEM AC1,OPOINT ;Store for interrupt level use
HLRZ AC2,RTBLK ;Get PI number from RTBLK
TRO AC2,BUSY ;Set up CONO bits to start tape
CONO PTR,(AC2) ;Turn on PTR
MOVEI 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 PTR,TAPE ;End-of-tape?
JRST TDONE ;Yes, stop the job
MOVE AC1,OPOINT ;No, get original pointer
MOVEM AC1,POINTR ;Store in pointer location
UJEN ;Dismiss the interrupt
;Here on end-of-tape
APRTRP: BLOCK 1 ;APR error trap address
9-9
PROGRAMMING FOR REALTIME EXECUTION
TDONE: MOVEI AC1,RTBLK1 ;Set up to remove PTR
CONO PTR,0 ;Take device off hardware PI level
RTTRP AC1, ;Take device off software PI level
JFCL ;Ignore errors
SETOM DONFLG ;Indicate that reading is over
UJEN ;Dismiss the interrupt
;Here if LOCK or RTTRP call failed
FAILED: OUTSTR [ASCIZ /RTTRP or LOCK call failed.
/]
EXIT ;Stop the job
END BLKTST
9.1.2 Fast Block Mode
The RTTRP argument list for fast block mode is as follows:
addr: XWD level,realtrap
XWD flags,aprtrap
BLKx device,blockaddr
Where: level is the interrupt level for the device.
realtrap is the address of the interrupt service routine for
the given device.
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-10
PROGRAMMING FOR REALTIME EXECUTION
Example
TITLE RTFBLK - Papertape read test in BLKI mode
SEARCH UUOSYM ;Standard symbols
;Some values
TAPE=400 ;No more tape in reader
BUSY=20 ;Device is busy reading
DONE=10 ;A character has been read
TABLEN=5 ;Length of table
AC1=1 ;Work register
AC2=2 ;Work register
PICHAN=6 ;PI channel
;Storage
POINTR: IOWD TABLEN,TABLE ;Pointer for BLKI instruction
OPOINT: BLOCK 1 ;Original pointer word for BLKI
TABLE: BLOCK TABLEN ;Table area for data being read
DONFLG: BLOCK 1 ;PI level to user level command
RTBLK1: BLOCK 1 ;Data block to remove PTR
BLOCK 1 ; from PI channel
CONSO PTR,0
BLOCK 1
;Realtime data block
RTBLK: XWD PICHAN,TRPADR ;PI channel and trap address
XWD 0,APRTRP ;APR error trap address
BLKI PTR,POINTR ;Read a block at a time
BLOCK 1
;Here we begin
BLKTST: RESET ;Reset the program
MOVE AC1,[LK.HLS+LK.LLS];Lock both segments
LOCK AC1, ;Lock the job in core
JRST FAILED ;LOCK call failed
SETZM DONFLG ;Initialize done flag
MOVEI AC2,RTBLK ;Get address of realtime data block
RTTRP AC2, ;Put realtime device on PI level
JRST FAILED ;RTTRP call failed
MOVE AC2,POINTR
MOVEM AC2,OPOINT
9-11
PROGRAMMING FOR REALTIME EXECUTION
HLRZ AC2,RTBLK ;Get PI number from RTBLK
TRO AC2,BUSY ;Set up CONO bits to start tape
CONO PTR,(AC2) ;Turn on PTR
MOVEI 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 PTR,TAPE ;End-of-tape?
JRST TDONE ;Yes, stop the job
MOVE AC2,OPOINT ;Get original pointer
MOVEM AC2,POINTR ;Restore BLKI pointer
UJEN ;Dismiss the interrupt
;Here on end-of-tape
APRTRP: BLOCK 1 ;APR trap address
TDONE: MOVEI AC2,RTBLK1 ;Set up to remove PTR
CONO PTR,0 ;Take device off hardware PI level
RTTRP AC2, ;Take device off software PI level
JFCL ;Ignore errors
SETOM DONFLG ;Indicate that reading is done
UJEN ;Dismiss the interrupt
;Here on failure for LOCK or RTTRP call
FAILED: OUTSTR [ASCIZ /RTTRP or LOCK call failed.
/]
EXIT ;Stop the job
END BLKTST
9.1.3 Single Mode
The RTTRP argument list for single mode is as follows:
addr: XWD level,realtrap
XWD flags,aprtrap
CONSO device,mask
BLOCK 1
9-12
PROGRAMMING FOR REALTIME EXECUTION
Where: level is the interrupt level for the device.
realtrap is the address of the interrupt service routine for
the given device.
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.
Example
TITLE RTSNGL - Papertape read test using CONSO chain
SEARCH UUOSYM ;Standard symbols
;Some values
PIOFF=400 ;Turn PI system off
PION=200 ;Turn PI system on
TAPE=400 ;No more tape in reader
BUSY=20 ;Device is busy reading
DONE=10 ;A character has been read
PICHAN=5 ;PI channel
AC1=1 ;Work register
AC2=2 ;Work register
;Storage
PDATA: BLOCK 1 ;Read data into this location
;Realtime data block
RTBLK: XWD PICHAN,TRPADR ;PI channel and trap address
XWD 0,APRTRP ;APR error trap address
CONSO PTR,@PTRCSO ;Indirect CONSO bit mask = PTRCSO
BLOCK 1 ;No BLKI/O instruction
PTRCSO: BLOCK 1 ;CONSO bit mask
DONFLG: BLOCK 1 ;PI level to user level command
RTBLK1: BLOCK 1 ;Data block to remove PTR
BLOCK 1 ; from PI channel
CONSO PTR,0
BLOCK 1
9-13
PROGRAMMING FOR REALTIME EXECUTION
;Here we begin
PTRTST: RESET ;Reset the program
MOVE AC1,[LK.HLS+LK.LLS];Lock both segments
LOCK AC1,
JRST FAILED ;LOCK call failed
SETZM PTRCSO ;Zero CONSO bits
SETZM DONFLG ;Initialize done flag
MOVEI AC1,RTBLK ;Address of realtime data block
RTTRP AC1, ;Put realtime device on PI level
JRST FAILED ;RTTRP call failed
MOVEI AC1,DONE ;Set up CONSO bit mask
HLRZ AC2,RTBLK ;Get PI number from RTBLK
TRO AC2,BUSY ;Set up CONO bits to start tape
CONO PI,PIOFF ;Guard against interrupts
MOVEM AC1,PTRCSO ;Store CONSO bit mask
CONO PTR,(AC2) ;Turn on PTR
CONO PI,PION ;Allow interrupts again
MOVEI AC1,5 ;For five seconds . . .
SLEEP AC1, ;SLEEP
SKIPN DONFLG ;Finished reading the tape?
JRST .-3 ;No, back to sleep
EXIT ;Finished
;Here's the trap
TRPADR: CONSO PTR,TAPE ;End of tape?
JRST TDONE ;Yes, stop job
DATAI PTR,PDATA ;Read in data word
UJEN ;Dismiss the interrupt
;Here on end-of-tape
APRTRP: BLOCK 1 ;APR trap address
TDONE: MOVEI AC1,RTBLK1 ;Set up to remove PTR
CONO PTR,0 ;Take device off hardware PI level
RTTRP AC1, ;Take device off software PI level
JFCL ;Ignore errors
SETOM DONFLG ;Indicate that read is done
SETZM PTRCSO ;Clear CONSO bit mask
UJEN ;Dismiss the interrupt
;Here on failure of RTTRP or LOCK call
FAILED: OUTSTR [ASCIZ /RTTRP or LOCK call failed.
/]
EXIT ;Stop the job
END PTRTST
9-14
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: XWD level,realtrap
XWD flags,aprtrap
EXP <device>B9+evaddr
BLOCK 1
Where: level is the interrupt level for the device.
realtrap is the address of the interrupt service routine for
the given device
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 of an
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
9-15
PROGRAMMING FOR REALTIME EXECUTION
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.
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 of the standard
forms of the RTTRP monitor call.
Example
TITLE RTFXEX - Realtime trapping in executive mode
SEARCH UUOSYM ;Standard symbols
;Some values
TAPE=400 ;No more tape in reader if TAPE=0
BUSY=20 ;Device is busy reading
DONE=10 ;A character has been read
I=1 ;Work register
AC2=2 ;Work register
PICHAN=6 ;PI channel
;Storage
DONFLG: BLOCK 1 ;PI level to user level command
APRTRP: BLOCK 1 ;APR trap address
9-16
PROGRAMMING FOR REALTIME EXECUTION
;Realtime data block
RTBLK: XWD PICHAN,TRPADR ;PI channel and trap address
XWD 1,APRTRP ;Bit 17 says trap in exec mode
CONSO PTR,DONE
BLOCK 1
PDATA: BLOCK 1 ;Data word
INDEX: BLOCK 1 ;Base index register
;Here we begin
RTEXEC: RESET ;Reset the program
SETZM DONFLG ;Initialize the done flag
MOVE AC2,[LK.HLS+LK.LLS];Lock both segments
LOCK AC2, ;Lock the job in core
; (Absolute address of job
; returned in AC2)
JRST FAILED ;LOCK call failed
HRRZS AC2, ;Get only low-segment address
LSH AC2,9 ;Justify the address
MOVEM AC2,INDEX ;Save base address for later
ADDM AC2,EXCHWD ;Relocate interrupt level program
ADDM AC2,JENWD ;Relocate interrupt instruction
MOVEI AC2,RTBLK ;Connect realtime device
RTTRP AC2, ; to the PI system
JRST FAILED ;RTTRP call failed
CONO PTR,20+PICHAN ;Start realtime device reading
SLEEP: MOVEI AC2,^D1000 ;For 1000 microseconds . . .
HIBER AC2, ;Sleep
JRST FAILED ;HIBER call failed
SKIPN DONFLG ;Interrupt level program done?
JRST SLEEP ;No, back to sleep
EXIT ;Yes, stop the job
TRPADR: BLOCK 1 ;JSR TRPADR on interrupt
EXCHWD: EXCH I,INDEX ;Set up index register
CONSO PTR,TAPE ;Tape finished?
JRST TDONE(I) ;Yes, stop the reader
DATAI PTR,PDATA(I) ;No, read next character
RETURN: EXCH I,INDEX(I) ;Restore ACs used
JENWD: JRSTF @TRPADR ;Dismiss the interrupt
TDONE: CONO PTR,0 ;Take the reader off-line
SETOM DONFLG(I) ;Indicate that the tape is finished
JRST RETURN(I) ;Go dismiss the interrupt
FAILED: OUTSTR [ASCIZ /LOCK, RTTRP, or HIBER call failed.
/]
EXIT ;Stop the job
END RTEXEC
9-17
PROGRAMMING FOR REALTIME EXECUTION
9.2 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:
o The program must save any accumulators it may need; an
interrupt-level trap overwrites them.
o The AC used in the interrupt-level RTTRP call cannot be
accumulator 16 or 17.
o 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.
9.3 RELEASING REALTIME DEVICES
To release a realtime device, use the RTTRP monitor call with an
argument list as follows:
addr: EXP 0
BLOCK 1
EXP <device>B9
Where: device is the device name of the device to be released.
9.4 DISMISSING REALTIME INTERRUPTS
To dismiss a realtime interrupt, use the UJEN monitor call; this call
causes the monitor 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 other than RTTRP during an interrupt
dismisses the interrupt.
9.5 ASSIGNING RUN QUEUES
If your job has the JP.HPQ privilege, you can use the HPQ monitor call
9-18
PROGRAMMING FOR REALTIME EXECUTION
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:
MOVEI ac,queue
HPQ ac,
error return
normal return
Where: 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).
9.6 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 addr1,addr2]
TRPSET ac,
error return
normal return
. . .
In this calling sequence, addr1 is an address for storing an
instruction (must be between 40 and 57 octal), and addr2 is the
address of the argument list.
The argument block that addr2 points to is one of the following:
o addr2: JSR addr3
9-19
PROGRAMMING FOR REALTIME EXECUTION
o 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 CPU0.
The calling sequence for resuming other jobs is:
MOVEI ac,0
TRPSET ac,
error return ;insufficient privileges
normal return ;timesharing restarted
On a successful return, user I/O is set for the job.
9-20
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:
o Timer mode (bit PM.MOD of .PMCPU is set) counts the number of
CPU 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).
o Counter mode (bit PM.MOD of .PMCPU is cleared) counts the
number of times the specified conditions occur.
10-1
ANALYZING SYSTEM PERFORMANCE
10.1.2 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).
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
17 %CNSTS 15 ST%EMO Exclude monitor overhead from user
runtime.
106 %CNST2 19 ST%XPI Exclude priority interrupt time
from user runtime.
106 %CNST2 20 ST%ERT Use EBOX/MBOX accounting.
Your job must also set bit PM.NPI in the priority-interrupt enable
word (.PMPIE); 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%XPI 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 (.PMPIE through .PMCHN).
Note that the formats of accounting meter counts are different; to
make them consistent, divide MBOX counts by 10000 (octal).
10-2
ANALYZING SYSTEM PERFORMANCE
10.1.3 PERF. Functions
The following is a list of the PERF. functions:
Fcn-code Symbol Meaning
1 .PRSET Sets up the performance meter.
2 .PRSTR Starts the performance meter.
3 .PRRED Reads the performance meter.
4 .PRSTP Stops the performance meter.
5 .PRRES Releases the performance meter.
6 .PRBPF Turns background PERF analysis off.
7 .PRBPN Turns background PERF analysis on.
The PERF. functions are usually used in the following order:
1. Initialize the performance meter (.PRSET).
2. Start the performance meter (.PRSTR).
3. Stop the performance meter (.PRSTP).
4. Release the performance meter (.PRRES).
Your program can also read the performance meter (.PRRED function) any
time after initializing it, but before releasing it.
The calling sequence for the PERF. monitor call is:
MOVE ac,[XWD len,addr]
PERF. ac,
error return
normal return
. . .
addr: XWD fcn-code,arglst
. . .
XWD fcn-code,arglst
. . .
arglst: argument block
Where: 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-3
ANALYZING SYSTEM PERFORMANCE
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
0 .PMLEN Length of the argument block (not including this
word).
1 .PMCPU CPU type:
Bits Symbol Meaning
0 PM.PD6 PDP-6.
1 PM.KA KA10.
2 PM.KI KI10.
3 PM.KL KL10.
4 PS.KS KS10
2 .PMMOD CPU number and mode:
Bits Symbol Meaning
0-17 PM.CPN CPU number.
18 PM.MOD 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.
19 PM.CLR Clear performance meter counts.
3 .PMCSH Cache enable flags:
Bits Symbol Meaning
0 PM.CCR Count references.
1 PM.CCF Count fills.
2 PM.EWB Count EBOX writebacks.
3 PM.SWB Count sweep writebacks.
4 PM.SYN Synchronize performance and
accounting meters.
10-4
ANALYZING SYSTEM PERFORMANCE
4 .PMPIE Priority interrupt enable flags:
Bits Symbol Meaning
0 PM.PI0 Enable for channel 0.
1 PM.PI1 Enable for channel 1.
2 PM.PI2 Enable for channel 2.
3 PM.PI3 Enable for channel 3.
4 PM.PI4 Enable for channel 4.
5 PM.PI5 Enable for channel 5.
6 PM.PI6 Enable for channel 6.
7 PM.PI7 Enable for channel 7.
8 PM.NPI Enable for no interrupt in progress.
5 .PMPCE Program counter enable flags:
Bits Symbol Meaning
0 PM.UPC User-mode enable.
1 PM.XPC Executive-mode enable.
6 .PMMPE Microcode probe enable flag:
Bits Symbol Meaning
0 PM.MPE Enable microcode probe.
7 .PMHPE Hardware probe enable flags:
Bits Symbol Meaning
0 PM.P0L Probe zero low.
1 PM.P0H Probe zero high.
10 .PMJOB Job enable word. This contains the
job number of the job for which the
meter is enabled, or one of the
following values:
Code Symbol Meaning
-2 .PMNUL Enable for null job.
-1 .PMSLF Enable for calling job.
10-5
ANALYZING SYSTEM PERFORMANCE
11 .PMCHN Channel enable flags:
Bits Symbol Meaning
0 PM.EC0 Enable for channel 0.
1 PM.EC1 Enable for channel 1.
2 PM.EC2 Enable for channel 2.
3 PM.EC3 Enable for channel 3.
4 PM.EC4 Enable for channel 4.
5 PM.EC5 Enable for channel 5.
6 PM.EC6 Enable for channel 6.
7 PM.EC7 Enable for channel 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
0 .PMLEN Count of following words. (Supply this in your
program.)
1 .PMCPN CPU number. (Supply this in your program.)
2 .PMHTB High-order word of time-base. (The rest of the
data is returned by the monitor.)
3 .PMLTB Low-order word of time-base.
4 .PMHPM High-order word of performance counter.
5 .PMLPM Low-order word of performance counter.
6 .PMHMC High-order MBOX reference count.
7 .PMLMC Low-order MBOX reference count.
Your program supplies the first two words of this argument block
(.PMLEN and .PMCPN); the monitor returns the remaining words on a
normal return.
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.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-6
ANALYZING SYSTEM PERFORMANCE
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, it 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 PRCPU% Invalid CPU specified.
2 PRNXC% Nonexistent CPU specified.
3 PRMOD% Improper mode specified.
4 PRSET% Meter not set up.
5 PRUSE% Meter already in use.
6 PRRUN% Meter already running.
7 PRJOB% Invalid job number.
10 PRNRN% Meter not running.
11 PRNIM% Function not implemented.
12 PRFUN% Invalid function code.
13 PRPRV% Not enough privileges.
10-7
ANALYZING SYSTEM PERFORMANCE
10.2 THE SNOOP FACILITY: SNOOP.
The SNOOP. UUO allows the privileged program ([1,2] or JACCT) to
insert breakpoints into the monitor, thereby patching routines into
the monitor code.
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 Bootstrap CPU number.
%CNBCL Bootstrap line number.
%CNNCR Number of CPUs allowed to run.
%CNMBS File structure where bootstrap monitor is stored.
%CNMBF File name of bootstrap monitor.
%CNMBX File extension of bootstrap monitor.
%CNMBD Bootstrap file directory.
The maximum number of breakpoints that can be inserted is defined as
GETTAB symbol %CNBPM in Table .GTCNF; 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.
10-8
ANALYZING SYSTEM PERFORMANCE
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.
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 provided in the description of the
monitor call in Chapter 22.
The SNOOP. functions are listed here. More specific explanation of
their action is given in following sections.
Fcn-code Symbol Meaning
0 .SODBP Define breakpoints.
1 .SOIBP Insert breakpoints.
2 .SORBP Remove breakpoints.
3 .SOUBP Delete breakpoint definitions.
4 .SONUL 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.
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 sequence is described in the following
sections.
10-9
ANALYZING SYSTEM PERFORMANCE
10.2.1 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.
The argument list for SNOOP. function 0 (.SODBP) is:
Word Symbol Contents
0 .SOLEN The total length of the argument list, including
this word.
1 .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
2 .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.
3 .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-10
ANALYZING SYSTEM PERFORMANCE
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,0]
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.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,0]
SNOOP. ac,
error return
normal return
After removing the breakpoints, you can insert them again (using
function .SOIBP), or you can delete the breakpoint definitions (using
function .SOUBP).
10.2.4 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,0]
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-11
ANALYZING SYSTEM PERFORMANCE
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 SOIAL% Illegal argument list.
2 SONPV% Not enough privileges.
3 SOSAS% Another program is already SNOOPing.
4 SOMBX% Maximum number of breakpoints is exceeded.
5 SOIBI% Breakpoints are already inserted.
6 SONFS% No monitor free core is available.
7 SOADC% Address check.
10 SOINL% Program is not locked in contiguous EVM.
11 SOWMS% Monitor symbol table checksum does not match.
10-12
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.
o Initialize a device.
o Initialize a buffer ring when using buffered I/O or define a
command list when using dump I/O.
o Select a file.
o Transmit/receive data.
o Close the file.
o Release the device.
o 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.
11-1
PROGRAM INPUT AND OUTPUT
Step Buffered I/O Dump I/O
Program Initialization RESET RESET
Device Initialization INIT, OPEN, FILOP. INIT, OPEN, FILOP.
Buffer Initialization INBUF, OUTBUF, FILOP.
File Selection LOOKUP, ENTER LOOKUP, ENTER
FILOP. FILOP.
Device Position USETI, USETO USETI, USETO
UGETF, SUSET., UGETF, SUSET.,
FILOP., MTAPE FILOP., MTAPE
Data Transmission IN, INPUT, FILOP. IN, INPUT, FILOP.,
OUT, OUTPUT OUT, OUTPUT
Command List Definition command list
File Termination CLOSE, FILOP. CLOSE, FILOP.
Device Termination RELEASE, FILOP. RELEASE, FILOP.
Program Termination EXIT 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-2
PROGRAM INPUT AND OUTPUT
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-10 operating system supports the following devices. Note,
however, that current versions of TOPS-10 restrict the support status
of some devices. For information about the current support status of
TOPS-10 devices, refer to the TOPS-10 Software Product Description.
o Disks (DSK). Refer to Chapter 12.
o DECtapes (DTA). Refer to Chapter 13.
o Magtape units (MTA). Refer to Chapter 14.
o 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.
o Line printers (LPT). Refer to Chapter 16.
o Card readers (CDR) and card punches (CDP). Refer to Chapter
17.
o Papertape readers (PTR) and papertape punches (PTP). Refer
to Chapter 18.
o Plotters (PLT). Refer to Chapter 19.
o Display light pens (DIS). Refer to Chapter 20.
o Network nodes, using the TSK logical device. Refer to
Chapter 5.
o Multiplexed devices (MPX). 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.
11-3
PROGRAM INPUT AND OUTPUT
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 DECtape 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. 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.
Format Example Meaning
d Do not use this format.
dd LL 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.
11-4
PROGRAM INPUT AND OUTPUT
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=1, B=2, and
so on). Unit numbers for disk are always
decimal.
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.
o Physical names specify device units, possibly on specific
controllers, allowing you to specify the exact unit your job
requires.
o 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.
11-5
PROGRAM INPUT AND OUTPUT
o 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 TT User terminal.
DSK DS Disk. The monitor uses the job
search list to select the device.
See Chapter 13 for a discussion of
job search lists.
MTx MT Magtape unit on controller x. For
example, MTA specifies a magtape unit
on controller A.
M7 7-track magtape.
M9 9-track magtape.
DTx DT DECtape unit on controller x. For
example, DTA specifies a DECtape unit
on controller A.
LPT LP Line printer.
LL Uppercase and lowercase line printer.
LU Uppercase line printer.
CDR CR Card reader.
CDP CP Card punch.
11-6
PROGRAM INPUT AND OUTPUT
PTR PR Papertape reader.
PTP PP Papertape punch.
PLT - Plotter.
DIS - Display.
PTY - Pseudo-terminal.
RDx - Remote data terminal, where x is the
controller name (A to Z).
11.3.2.2 Physical Device Names - Every device has a physical device
name of the form:
dddnnu
Where: ddd is a 3-letter generic device name.
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:
o OPR specifies the physical terminal designated by the
operator as the operator terminal.
o 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.
o CTY specifies the console terminal for the system.
o 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.
11-7
PROGRAM INPUT AND OUTPUT
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).
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 -1), 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.
11-8
PROGRAM INPUT AND OUTPUT
Table 11-1: Ersatz Devices
______________________________________________________________________
Name PPN Search List Purpose of Area
______________________________________________________________________
ACT 1,7 SSL System accounting
ALG 5,4 SSL ALGOL
ALL NONE ALL All structures
APL 5,31 SSL APL
BAS 5,1 SSL BASIC
BLI 5,5 SSL BLISS
COB 5,2 SSL COBOL
CTL 5,27 SSL Control files
D60 5,32 SSL DN60 (IBMCOM) files
DBS 5,24 SSL DBMS
DEC 10,7 SSL Field-image versions of programs
DMP 5,21 SSL Dump area
DOC 5,14 SSL Documentation
DSK NONE JSL Default device
FAI 5,15 SSL FAIL
FFA 1,2 SSL Operator (Full File Access)
FOR 5,6 SSL FORTRAN
FNT 5,36 SSL LN01 fonts
GAM 5,30 SSL Games
HLP 2,5 SSL HELP files
INI 5,34 SSL Initialization files
LIB SETTABLE JSL Library
MAC 5,7 SSL MACRO
MFD 1,1 SSL Master file directory
MIC 5,25 SSL MIC files
MUS 5,16 SSL Music
MXI 5,3 SSL PDP-11
NEL 5,20 SSL NELIAC
NEW 1,5 SSL New CUSPs
OLD 1,3 SSL Old CUSPs
POP 5,22 SSL POP2
PUB 1,6 SSL User maintained programs
REL 5,11 SSL .REL files
RNO 5,12 SSL RUNOFF files
SNO 5,13 SSL SNOBOL
SPL 3,3 SSL Spooling area
SSL NONE SSL System search list
STD 1,4 SSL Same as SYS, but /NEW doesn't apply
SYS 1,4 SSL System CUSPs
TED 5,10 SSL Text editor
TPS 5,26 SSL Text processing
TST 5,23 SSL Test area
11-9
PROGRAM INPUT AND OUTPUT
UMD 6,10 SSL User mode diagnostics
UNV 5,17 SSL Universal files
UPS 5,35 SSL Mail system area
UTP 5,33 SSL UETP
XPN 10,1 SSL 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.
o 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.
o ALL (All Search List) is the definition of all the public
file structures in their order of accessibility.
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.
The format of a Universal Device Index is:
Bits Symbol Meaning
18-20 Device or process:
Code Symbol Meaning
0 .UXCHN Physical device.
2 .UXTRM Terminal.
3 .UXPRC Process.
11-10
PROGRAM INPUT AND OUTPUT
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
TTY114; the 2 in Bits 18-26 shows that the device is a terminal, and
the 114 in Bits 27-35 shows that it is TTY114.
11.3.4 MPX-Controlled Devices
An 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-11
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.
o 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 card punch
filename.CDR for card readers
filename.LPT for line printers
filename.PLT for plotters
filename.PTP for papertape punch
11.3.6 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.
11-12
PROGRAM INPUT AND OUTPUT
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.
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. These data modes
are:
*ASCII *Image Binary
*8-bit ASCII *Binary
*ASCII Line Image Dump
*Packed Image Dump Records
*Byte Dump
*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.
11-13
PROGRAM INPUT AND OUTPUT
Table 11-2: Data Modes (Bits 32-35 of the file status word)
______________________________________________________________________
Code Symbol Data Mode Applicable Devices
______________________________________________________________________
0 .IOASC ASCII Disk, terminal, magnetic tape,
DECtape, plotter, card punch, card
reader, line printer, paper tape
punch, paper tape reader
1 .IOASL ASCII Line Disk, terminal, magnetic tape,
DECtape, plotter, card punch, card
reader, line printer, paper tape
punch, paper tape reader
2 .IOPIM Packed Image Terminal
3 .IOBYT Byte Magnetic tape, ANF-10 network task
4 .IOAS8 8-bit ASCII Terminal, network line printer, PTY
5 Reserved for DEC
6-7 Reserved for customer
10 .IOIMG Image Disk, terminal, magnetic tape,
DECtape, plotter, card punch, card
reader, line printer, paper tape
punch, paper tape reader
11-12 Reserved for DEC
13 .IOIBN Image binary Disk, magnetic tape, line printer,
DECtape, plotter, card punch, card
reader, paper tape punch, paper
tape reader
14 .IOBIN Binary Disk, magnetic tape, line printer,
DECtape, plotter, card punch, card
reader, paper tape punch, paper
tape reader
15 .IOIDP Image dump Display
16 .IODPR Dump record Disk, magnetic tape, DECtape
17 .IODMP Dump Disk, magnetic tape, DECtape
______________________________________________________________________
11-14
PROGRAM INPUT AND OUTPUT
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, in IOWD format
o A GOTO instruction
o A terminator, in the form of a zero word
An IOWD instruction causes a specified 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 next command to be executed. Its
format is:
XWD 0,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.
11-15
PROGRAM INPUT AND OUTPUT
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 dumping I/O
to disk:
OUTPUT DISK,[IOWD 70,BUF1 ;Transmit 70 words beginning at BUF1
IOWD 70,BUF2 ;Transmit 70 words beginning at BUF2
Z] ;A zero word
Another example is:
OUTPUT DSK,ADDR1 ;ADDR1 is address of command list
.
.
.
ADDR1: IOWD 70,BUF1 ;Transmit 70 words beginning at BUF1
IOWD 70,BUF2 ;Transmit 70 words beginning at BUF2
0 ;A zero word
Below is an example of dump mode input:
TITLE HOME - Routine to read HOME block
SUBTTL HANLEY A. STRAPPMAN 6-27-83/HAS
SEARCH UUOSYM
;AC'S
T1=1 ;Temp
T2=T1+1
P=17 ;Stack pointer
;MISCL
HOMNAM==0 ;SIXBIT/HOM/
HOMCOD==176 ;Code number
CODHOM==707070 ;Code for HOME
BLKSIZ==200 ;Size of a disk block
II==0 ;Channel
11-16
PROGRAM INPUT AND OUTPUT
;Routine to read the HOME block
;T1 passes the structure name
;The HOME block is returned in BF
;Skip if successful
HOME:: MOVEM T1,DEV+.OPDEV ;Store str name
OPEN II,DEV ;Open str
POPJ P,
LOOKUP II,FIL ;LOOKUP HOME.SYS
POPJ P,
LOOP: IN II,CMD ;Read a block
SKIPA T1,BF+HOMCOD ;Pick up code word
POPJ P, ;EOF
MOVS T2,BF+HOMNAM ;Pick up name
CAIN T1,CODHOM ;Right block?
CAIE T2,'HOM'
JRST LOOP ;No, keep searching
RELEAS II, ;Release channel
AOS (P) ;Skip return
POPJ P,
DEV: .IODMP ;OPEN block
BLOCK 1
0
FIL: .RBEXT ;LOOKUP block
XWD 1,4
SIXBIT /HOME/
SIXBIT /SYS/
CMD: IOWD BLKSIZ,BF ;I/O command list
0
BF:: BLOCK BLKSIZ ;Buffer
END
11.6 SELECTING A FILE
There are several monitor calls you can use to select a file for use
in your program:
o 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.
o 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.
11-17
PROGRAM INPUT AND OUTPUT
o 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.
o 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.
o To CHANGE THE ATTRIBUTES of a file, use the LOOKUP and RENAME
monitor calls, giving the desired new attributes.
o To RENAME a file, use the LOOKUP monitor call to identify the
file; then use the RENAME call to define its new name.
o 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 USETO call to the end of
the file. The 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.
o To SUPERSEDE a file, use the ENTER monitor call to identify
the file. Then write the new file by using OUT or OUTPUT
calls.
11.7 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-18
PROGRAM INPUT AND OUTPUT
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. You would
proceed by issuing:
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 0. 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+1, contains the device name. If you wish to
do disk I/O, the name for the disk is DSK, entered in SIXBIT.
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 /DSK/
XWD OUTB,0
The next monitor call to be issued in connection with your output is
the OUTBUF call. The monitor responds to this call by reserving 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.
11-19
PROGRAM INPUT AND OUTPUT
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 channo,entblock
Where: 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 given
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/
0
0
11-20
PROGRAM INPUT AND OUTPUT
A flow diagram for the I/O sequence is shown in Figure 11-1.
OPEN
CALL
|
|
V
Data mode
----------------------------
| Device name |
|--------------------------|
| output addr | input addr |
----------------------------
| OPEN |
---------- ---------- BLOCK ---------- ---------
| OUTBUF | | | | INBUF |
| CALL | | | | CALL |
---------- V V ---------
------------------ ------------------
.BFADR | Buffer address |---\ /--| Buffer address | .BFADR
|----------------| | | |----------------|
.BFPTR | Byte pointer |---+-\ /-+--| Byte pointer | .BFPTR
|----------------| | | | | |----------------|
.BFCTR | Byte count |---+-+-\ /-+-+--| Byte count | .BFCTR
------------------ | | | | | | ------------------
Buffer Control | | | | | | Buffer Control
Block | | | | | | Block
| | | | | |
--------------------- | | | | | | ---------------------
|* I/O Status | .BFSTS| | | | | | .BFSTS |* Buffer address |
|-------------------| | | | | | | |-------------------|
|* Buffer size,,addr|<------/ | | | | \------->|* Buffer size,,addr|
| | | | | | | |
| Additional buffers| | | | | | Additional buffers|
|-------------------| | | | | |-------------------|
|* Word count | .BFCNT | | | | .BFCNT |* Word count |
|-------------------| | | | | |-------------------|
| | | | | | | |
| | | | | | | |
|-------------------| | | | | |-------------------|
| |<--------/ | | \--------->| |
|-------------------| | | |-------------------|
| |<----------/ \----------->| |
| | | |
--------------------- ---------------------
* indicates Buffer Header Block
Figure 11-1: Flow Diagram -- I/O Sequence
11-21
PROGRAM INPUT AND OUTPUT
Here OPEN, OUTBUF, and INBUF are monitor calls while OUTB, OBPTR, and
others are arbitrary symbols.
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 WRITE1 - Write TTY input to disk
SUBTTL HANLEY A. STRAPPMAN 6-27-83/HAS
SEARCH UUOSYM
;AC'S
T1=1 ;Temp
P=17 ;Stack pointer
;MISCL
D==1 ;Channel number for disk output
ESC==33 ;Use ESCAPE to mark EOF
PDLSIZ==4 ;Size of PDL
WRITE1: RESET ;Initialize
MOVE P,[IOWD PDLSIZ,PDL] ;Set up PDL
OPEN D,DEV ;OPEN device
HALT ;Can't
OUTBUF D, ;This UUO is optional
ENTER D,FIL ;ENTER the file
HALT ;Can't
OUTSTR [ASCIZ /DATA: /] ;Prompt the user
LOOP: INCHWL T1 ;Input a char from the TTY
CAIN T1,ESC ;ESCAPE?
JRST DONE ;Yes
PUSHJ P,CO ;Output char to disk
JRST LOOP
DONE: CLOSE D, ;CLOSE the disk file
STATZ D,IO.ERR ;Problems during CLOSE?
HALT ;Yes
RELEAS D, ;This UUO is optional
EXIT
;Routine to output a char to disk
CO: SOSGE OBUF+.BFCTR ;Room in buffer?
JRST CO2 ;No
IDPB T1,OBUF+.BFPTR ;Yes, store char
POPJ P,
CO2: OUT D, ;Get another buffer
JRST CO ;Try again
HALT ;Disk error
11-22
PROGRAM INPUT AND OUTPUT
DEV: .IOASC ;OPEN block
SIXBIT /DSK/
XWD OBUF,0
OBUF: BLOCK 3 ;Ring header
FIL: .RBEXT ;ENTER block
0
SIXBIT /NAME/
SIXBIT /EXT/
PDL: BLOCK PDLSIZ ;Push-down list
END WRITE1
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.
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.
11-23
PROGRAM INPUT AND OUTPUT
The following is an example of a program that reads a file:
TITLE READ1 - Type out a disk file
SUBTTL HANLEY A. STRAPPMAN 6-27-83/HAS
SEARCH UUOSYM
;AC'S
T1=1 ;Temp
P=17 ;Stack pointer
;MISCL
D==1 ;Channel number for disk
PDLSIZ==4 ;Size of PDL
READ1: RESET ;Initialize
MOVE P,[IOWD PDLSIZ,PDL];Set up PDL
OPEN D,DEV ;OPEN device
HALT ;Can't
INBUF D, ;This UUO is optional
LOOKUP D,FIL ;LOOKUP the file
HALT ;Can't
LOOP: PUSHJ P,CI ;Input a char from disk
EXIT ;EOF
OUTCHR T1 ;Output char to TTY
JRST LOOP
;Routine to input a char from disk
;This routine returns noskip if EOF, but otherwise skips
CI: SOSGE IBUF+.BFCTR ;More chars in buffer?
JRST CI2 ;No
ILDB T1,IBUF+.BFPTR ;Yes, get one
JUMPE T1,CI ;Ignore nulls
AOS (P) ;Skip return
POPJ P,
CI2: IN D, ;Get another buffer
JRST CI ;Try again
STATZ D,IO.ERR ;Error or just EOF?
HALT ;Disk error
POPJ P, ;EOF
DEV: .IOASC ;OPEN block
SIXBIT /DSK/
IBUF
IBUF: BLOCK 3 ;Ring header
FIL: .RBEXT ;LOOKUP block
0
SIXBIT /NAME/
SIXBIT /EXT/
PDL: BLOCK PDLSIZ ;Push-down list
END READ1
11-24
PROGRAM INPUT AND OUTPUT
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
succeeding line with the error return located in the second line
following the IN.
Each IN call reads 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 WRITE2 - Write TTY input to disk
SUBTTL HANLEY A. STRAPPMAN 6-27-83/HAS
SEARCH UUOSYM
;AC'S
T1=1 ;Temp
T2=T1+1
P=17 ;Stack pointer
;MISCL
ESC==33 ;Use ESCAPE to mark EOF
PDLSIZ==4 ;Size of PDL
WRITE2: RESET ;Initialize
MOVE P,[IOWD PDLSIZ,PDL];Set up PDL
MOVE T1,[XWD FLOPL,FLOP];ENTER the file
FILOP. T1,
HALT ;Can't
MOVSI T1,(FO.CHN) ;Isolate chan number
AND T1,FLOP+.FOFNC
MOVEM T1,CHAN+.FOFNC
OUTSTR [ASCIZ /DATA: /] ;Prompt the user
LOOP: INCHWL T1 ;Input a char from the TTY
CAIN T1,ESC ;ESCAPE?
JRST DONE ;Yes
PUSHJ P,CO ;Output char to disk
JRST LOOP
11-25
PROGRAM INPUT AND OUTPUT
DONE: MOVEI T1,.FOCLS ;Function code
HRRM T1,CHAN+.FOFNC
MOVE T1,[XWD 1,CHAN] ;CLOSE the file
FILOP. T1,
HALT ;Problems during CLOSE
EXIT
;Routine to output a char to disk
CO: SOSGE OBUF+.BFCTR ;Room in buffer?
JRST CO2 ;No
IDPB T1,OBUF+.BFPTR ;Yes, store char
POPJ P,
CO2: MOVEI T2,.FOOUT ;Function code
HRRM T2,CHAN+.FOFNC
MOVE T2,[XWD 1,CHAN] ;Output the buffer
FILOP. T2,
HALT ;Disk error
JRST CO ;Try again
FLOP: FO.ASC+.FOWRT ;Assign channel, write file
.IOASC
SIXBIT /DSK/
XWD OBUF,0
XWD -1,0 ;Default number of buffers
FIL
0
FLOPL==.-FLOP ;Size of block
CHAN: BLOCK 1 ;Channel number
OBUF: BLOCK 3 ;Ring header
FIL: .RBEXT ;ENTER block
0
SIXBIT /NAME/
SIXBIT /EXT/
PDL: BLOCK PDLSIZ ;Push-down list
END WRITE2
11.7.4 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-26
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 USETO 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 selected 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 USETO 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 USETO CHAN,60 followed by the call OUT CHAN, creates a file
of 60 octal blocks; the new data is written into the last block and
blocks 11-57 (octal) contain zeros.
11-27
PROGRAM INPUT AND OUTPUT
The USETI and USETO monitor calls do not actually perform any input or
output. They change the pointers of the current position 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.
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 USETO 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.
o The last block of the file already contains 200 octal words.
o Fewer words are written than the current size of the block.
If the last block of the file is 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-28
PROGRAM INPUT AND OUTPUT
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 USETO reference logical blocks numbers
in a file structure, instead of relative blocks within a file:
o When the channel has been initialized with a file structure
name, such as DSKB.
o When no file has been opened on the channel specified in the
AC field (that is, no LOOKUP or ENTER has been performed).
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).
o 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.
An output function writes headers and data formats. Only the output
immediately following the USETO writes the format. Therefore, to
write two IOWDs of format, the following sequence must be used:
USETO
OUTPUT
USETO
OUTPUT
An 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-29
PROGRAM INPUT AND OUTPUT
11.8 RECOVERING FROM ERRORS
The OPEN monitor call can fail (taking the non-skip return) if the
device is not available to your job.
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 35.
The data modes are described in Section 11.4.
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 CHAN,IO.EOF
JRST 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.
11-30
PROGRAM INPUT AND OUTPUT
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.
11-31
PROGRAM INPUT AND OUTPUT
Figure 11-2 shows a buffer ring containing a buffer control block and
three buffers.
- -------------------
/ | |.
/ |-----------------| .
Buffer \ | | . <--- Points to Current Buffer
Control < |-----------------| .
Block / | | .
\ |-----------------| .
\ | | . /----------------------\ -
- ------------------- .. | \ \
. . | | \
. . | ------------------- | |
. . | | | | |
. .| |--------+--------| | |
. ->| | B |\ | |
. |--------+--------| \ | |
. | | | | | A
. |-----------------| | | |
. | Buffer A | | | |
.. ------------------- | | |
. . /---------------------/ | |
. . | ------------------- | | B
. . | | | | / U
. .| |--------+--------| | > F
. ->| | C |\ | \ F
. |--------+--------| \ | | E
. | | | | | R
. |-----------------| | | |
. | Buffer B | | | |
. ------------------- | | |
. /---------------------/ | | R
. | ------------------- | | I
. | | | | | N
.| |--------+--------| / | G
->| | A +--/ |
|--------+--------| |
| | |
|-----------------| /
| Buffer C | /
------------------- -
Figure 11-2: The Buffer Structure
11-32
PROGRAM INPUT AND OUTPUT
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
0 only.
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.
11-33
PROGRAM INPUT AND OUTPUT
To perform buffered input/output, your program should use the
following monitor calls:
o RESET initializes your program.
o INIT, FILOP., and OPEN initialize devices.
o INBUF, OUTBUF, and FILOP., initialize a buffer ring
(optional).
o LOOKUP, ENTER, FILOP., USETI, USETO, and SUSET. select a
file and a block within a file.
o IN, INPUT, OUTPUT, FILOP., and OUT transmit data.
o CLOSE and FILOP. close a file.
o RELEASE and FILOP. terminate device activity.
o RESET and RESDV. forcibly terminate device activity.
o EXIT terminates your program.
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.
o 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 monitor 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 calls are as
follows:
INBUF channo,n OUTBUF channo,n
return return
11-34
PROGRAM INPUT AND OUTPUT
Where: channo is the channel number associated with the device. You
can initialize an I/O channel using OPEN, INIT, or FILOP.
n specifies the number of buffers in the buffer ring. If n is
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:
0 1 17 18 35
--------+-------+-------+----------------------
.BFADR | U | X | | pointer | Word 0
|-------+-------+-------+---------------------|
.BFPTR | byte pointer | Word 1
|---------------------------------------------|
.BFCTR | byte counter | Word 2
|---------------------------------------------|
.BFUDX | (MPX only) Universal Device Index | Word 3
-----------------------------------------------
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.
11-35
PROGRAM INPUT AND OUTPUT
In Word 1 the byte pointer (.BFPTR) points to the byte within the
current buffer that contains the next input or output data. The
byte size is determined by the data mode.
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 Block
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:
0 17 18 35
-----------------------+----------------------
.BFSTS | | I/O status | Word -1
|-----+----------------|---------------------|
.BFHDR | x | size | addr next buffer | Word 0
|-----+----------------|---------------------|
.BFCNT | bookkeeping word | word count | Word 1
-----------------------+----------------------
(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
when the monitor advances to the next buffer in the ring. This
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.
11-36
PROGRAM INPUT AND OUTPUT
In Word 1, x (BF.IOU) is the buffer's use bit. This bit is a flag
that indicates that the buffer contains active data. If the
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 buffered
input.
11-37
PROGRAM INPUT AND OUTPUT
Start
|
V
Has Input Already Been Has Buffer Ring Set Up
Done for This Device? --NO--> Been Set Up? ---NO--> Buffer Ring
| | |
YES | |
V | |
Is Use Bit Set | |
/---YES--- for Next Buffer? YES |
| | | |
| NO | |
| V | |
| Call Device Service V |
| Routine to Start the <-------------------------/
| Device
| |
| V
| Non-Blocking ---- YES --------> Return to User,
| | Error Return
| NO
| V
| Put Job in I/O Wait
| |
.......................... |
: The Device Service : |
: Routine Takes the Job : |
: Out of Wait after : |
: Buffer is Filled. If : |
: IO.SYN is Off, Service : |
: Routine Continues to :----->|
: Fill Subsequent Buffers: |
: if They Are Available : |
.........................: |
| V
| Is Use Bit Set
| in Next Buffer? ----- NO -----> Error or
| | EOF
| YES
| V
| Set Up Buffer Control Block
| 1) Address of New Buffer
\------------------>2) Byte Pointer to Data Give Normal
3) Count of Bytes in Buffer Return to
4) .BFUDX if MPX device --------> User
Figure 11-3: Flowchart for Buffered Input
11-38
PROGRAM INPUT AND OUTPUT
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.
2. Optionally, use the INBUF or FILOP. monitor call to specify
the number of buffers in the ring.
3. Use IN or INPUT monitor calls to read from the file.
There are four ways to do buffered input:
o In synchronous mode, blocking and non-blocking I/O.
o In asynchronous mode (default), blocking and non-blocking
I/O.
For all of these methods, your program requests the next bufferful of
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.
2. Advances the buffer ring pointer to the next buffer.
3. Updates the buffer control block, including the pointer to
the current buffer, the byte pointer to the data, and the
byte count.
4. Returns control to your program.
Note that if the next buffer is not ready, your job is put into a wait
state until the buffer is 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.
11-39
PROGRAM INPUT AND OUTPUT
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.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 input, your program must set the bit
UU.AIO (asynchronous I/O) in 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.
11-40
PROGRAM INPUT AND OUTPUT
Figure 11-4 is a flowchart showing the monitor's handling of buffered
output.
Start
|
V
Has Output Already Been Has Buffer Ring Set Up
Done for This Device? --NO--> Been Set Up? ---NO--> Buffer Ring
| | |
YES | |
V | |
Is Use Bit Set | |
/---NO---- for Next Buffer? YES |
| | | |
| YES | |
| V | |
| Call Device Service V |
| Routine to Start the <---------------------------/
| Device
| |
| V
| Non-Blocking ---- YES --------> Return to User,
| | Error Return
| NO
| V
| Put Job in I/O Wait
| |
........................... |
: The Device Service : |
: Routine Takes the Job : |
: Out of Wait after Buffer: |
: is Emptied. If IO.SYN : |
: is Off, Service Routine : |
: Continues to Empty :--->|
: Subsequent Buffers if : |
: They Are Available : |
..........................: |
| V
| Is Use Bit Set
| in Next Buffer? ----- YES -----> Error or
| | EOF
| NO
| V
| Set Up Ring Control Block
| 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-41
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.
2. Optionally, use the OUTBUF or FILOP. monitor call to specify
the number of buffers in the ring.
3. Issue a "dummy" OUT or OUTPUT monitor call to initialize the
buffer ring. This is normally transparent to the program and
does not require special coding.
4. Use OUT or OUTPUT monitor calls to write to the file.
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 in .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.
2. Advances the buffer ring pointer to the next buffer.
3. Updates the buffer control block, including the pointer to
the current buffer, the byte pointer to the data, and the
item byte count.
4. Returns control to your program.
Note that if the next buffer is not ready, your job is put into a wait
state.
11-42
PROGRAM INPUT AND OUTPUT
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 operations that are in progress on a given channel.
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.
11-43
PROGRAM INPUT AND OUTPUT
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 0.
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 0 in the right half of .BFADR.
As output proceeds in your program, the monitor handles output for
MPX-controlled devices as follows:
1. 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.
2. 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.
3. 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 how the
monitor handles buffered output for an MPX channel.
11-44
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.
- -------------
/ | |
Buffer | |-----------|
Control | | | C |--\
Block < |-----------| |
| | | |
| |-----------| |
\ | UDX2 | |
----------------- --\ - ------------- |
| /-----| | |
| DDB1 | A |--\ | | ------------- --\
| \-----| | | | | | |
----------------- | | | |-----------| |
/------------------/ / Device \-->| | D |-\ |
| ------------- > Chain |-----------| | |
| | | \ 1 | | | |
| |-----------| | |-----------| | |
\-->| | 0 | | | Buffer C | | |
|-----------| | ------------- | / Free
| | | /----------------/ > Chain
|-----------| | | ------------- \
| Buffer A | | | | | |
------------- --/ | |-----------| |
| | | 0 | |
----------------- --\ \->|-----------| |
| /-----| | | | |
| DDB2 | B |--\ | |-----------| |
| \-----| | | | Buffer D | |
----------------- | | ------------- --/
/------------------/ |
| ------------- / Device
| | | > Chain
| |-----------| \ 2
\-->| | 0 | |
|-----------| |
| | |
|-----------| |
| Buffer B | |
------------- --/
Figure 11-5: One Buffer in Each of Two Device Chains
11-45
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.
/- -------------
| | |
| |-----------|
Buffer | | | D |--\
Control < |-----------| |
Block | | | |
| |-----------| |
| | UDX1 | |
\- ------------- |
| ------------- --\
----------------- --\ | | | |
| | | | |-----------| |
| /-----| | \-->| | 0 | / Free
| | A |--\ | |-----------| > Chain
| \-----| | | | | \
| | | | |-----------| |
----------------- | | | Buffer D | |
/------------------/ | ------------- --/
| ------------- |
| | | |
| |-----------| | ----------------- --\
\-->| | C |--\ / Device | | |
|-----------| | > Chain | DDB2 /-----| |
| | | \ 1 | | B |--\ |
|-----------| | | | \-----| | |
| Buffer A | | | | | | |
------------- | | ----------------- | / Device
/------------------/ | /------------------/ > Chain
| ------------- | | ------------- \ 2
| | | | | | | |
| |-----------| | | |-----------| |
\-->| | 0 | | \-->| | 0 | |
|-----------| | |-----------| |
| | | | | |
|-----------| | |-----------| |
| Buffer C | | | Buffer B | |
------------- --/ ------------- --/
Figure 11-6: Multiple Buffers in Multiple Device Chains
11-46
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 | | | D |--\
Block < |-----------| |
| | | |
| |-----------| |
\ | UDX | |
- ------------- |
----------------- --\ | ------------- --\
| /-----| | | | | |
| DDB1 | C |--\ | | |-----------| |
| \-----| | | \-->| | A |--\ |
----------------- | | |-----------| | |
/------------------/ | | | | |
| ------------- | |-----------| | |
| | | / Device | Buffer D | | / Free
| |-----------| > Chain ------------- | > Chain
\-->| | 0 | \ 1 /------------------/ \
|-----------| | | ------------- |
| | | | | | |
|-----------| | | |-----------| |
| Buffer C | | \-->| | 0 | |
|-----------| | |-----------| |
| Buffer C | | | | |
------------- --/ |-----------| |
| Buffer A | |
----------------- --\ ------------- --/
| /-----| |
| DDB2 | B |--\ | Note that Buffer A was
| \-----| | | returned to the free chain
----------------- | | after it was emptied.
/------------------/ |
| ------------- |
| | | / Device
| |-----------| > Chain
\-->| | 0 | \ 2
|-----------| |
| | |
|-----------| |
| Buffer B | |
------------- --/
Figure 11-7: One Buffer Moved Back to Free Chain
11-47
PROGRAM INPUT AND OUTPUT
11.9.7 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 MTA0; 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.
;This example shows how to set up a 2-buffer input buffer ring.
GO: OPEN ICHN,OPNBLK ;Initialize the channel
JRST ERROR ;Not available
MOVE T1,[BF.VBR+BUF1+.BFHDR]
MOVEM T1,MAGBUF+.BFADR
MOVESI T1,(POINT BYTSIZ)
MOVEM T1,MAGBUF+.BFPTR
JRST CONTIN ;On to something else
OPNBLK: BLOCK 1 ;For flags and status bits
SIXBIT /MTA0/ ;Device name
XWD 0,MAGBUF ;No output,,input ring header
MAGBUF: BLOCK 3
BUF1: BLOCK 1 ;For file status
XWD SIZE+1,BUF2+.BFHDR ;Size+1,,next buffer
BLOCK 1 ;For word count
BLOCK SIZE ;Space for the buffer
BUF2: BLOCK 1 ;For file status
XWD SIZE+1,BUF1+.BFHDR ;Size+1,,next buffer
BLOCK 1 ;For word count
BLOCK SIZE ;Space for the buffer
CONTIN: ;Something else
11-48
PROGRAM INPUT AND OUTPUT
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.
T1=1
T2=2
GO: OPEN ICHN,OPNBLK ;OPEN file
JRST ERROR ;Not available
MOVEI T1,OPNBLK ;Find number and
DEVSIZ T1 ; size of
JRST ERROR ; default buffers
HLRZ T2,T1 ;Compute words needed
HRRZS T1 ; for size and number
IMULI T1,(T2) ; of buffers
PUSHJ P,GETMEM ;Call your memory allocator
; with words to get in T1,
;returns address of block in T1
JRST ERROR ;Can't get?
PUSH P,.JBFF ;Save current first free
MOVEM T1,.JBFF ;Default number of buffers
INBUF T1,0 ;Make monitor put buffers
; where you want
POP P,.JBFF ;Restore .JBFF now that
; buffers are allocated
.
.
.
.
The following example demonstrates the general principles of using
buffered I/O:
TITLE Buffered Input/Output Example for TOPS-10
COMMENT *
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 *
11-49
PROGRAM INPUT AND OUTPUT
SEARCH UUOSYM ;Use standard definitions
SALL ;Keep the program neat
;Definitions for registers and channels
T1=1 ;For scratch
C=10 ;For storing a character
J=15 ;For JSPing around
ICHN==1 ;Input channel number
OCHN==2 ;Output channel number
;Macro for general messages
DEFINE ERROR(TEXT)<
JRST [OUTSTR [ASCIZ |?'TEXT
|] ;Output message to TTY:
JRST MONRT] ;And back to monitor mode
> ;End of macro definition
;Here on entry to initialize program.
BUFENT: JFCL ;In case of CCL entry (ignore)
RESET ;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 ICHN,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 *
;Here's the main I/O loop to transfer the file.
IO: JSP J,GETBYT ;Read a byte of input
JRST EOF ;End of input file
JSP J,PUTBYT ;Write the byte
JRST IO ;Back for next byte
11-50
PROGRAM INPUT AND OUTPUT
;Here on end of input file.
EOF: RELEAS ICHN, ;Let input device and channel go
CLOSE OCHN, ;CLOSE output file
;(Writing last buffers)
STATZ OCHN,IO.ERR ;Any last errors?
JRST OUERR ;Yes, complain to user
RELEAS OCHN, ;No, release output device
;Here to return to monitor mode.
;If user continues, restart.
MONRT: MONRT. ;Back to monitor mode
JRST BUFENT ;User said continue
COMMENT *
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 *
;GETBYT - Routine to read 7-bit ASCII input data.
GETBYT: SOSGE INCNT ;Any chars in input buffer?
JRST GETBUF ;No, must read next buffer
ILDB C,INPTR ;Yes, return char in C
JUMPN C,1(J) ;Successful return is skip
JRST GETBYT ;Null char, throw away
GETBUF: IN ICHN, ;Advance to next input buffer
JRST GETBYT ;And back for next character
GETSTS ICHN,T1 ;Input error
TRNE T1,IO.EOF ;Was it end-of-file?
JRST (J) ;Ok, not a real error
ERROR <I/O ERROR ON INPUT>
;PUTBYT - Routine to write 7-bit ASCII output data.
11-51
PROGRAM INPUT AND OUTPUT
PUTBYT: SOSGE OUCNT ;Any room in current output buffer?
JRST PUTBUF ;No, write out and get next
IDPB C,OUPTR ;Yes, put it in output buffer
JRST (J) ;Return for more (note nonskip)
PUTBUF: OUT OCHN, ;Write out this buffer
JRST PUTBYT ;And start filling next
OUERR: ERROR <I/O ERROR ON OUTPUT>
;Here all data blocks are defined.
;First the input and output OPEN blocks:
INDEV: .IOASL ;ASCII line mode
SIXBIT /INPUT/ ;Input device name
XWD 0,INHDR ;Address of input buffer
;Control block
OUDEV: .IOASL ;ASCII line mode
SIXBIT /OUTPUT/ ;Output device name
XWD OUHDR,0 ;Address of output buffer
;Control block
;NOW THE LOOKUP/ENTER BLOCKS:
INFIL: SIXBIT /INPUT/ ;Input file name
SIXBIT /IN/ ;Input extension
BLOCK 1 ;Protection, mode, creation date
BLOCK 1 ;PPN or path number
OUFIL: SIXBIT /OUTPUT/ ;Output file name
SIXBIT /OUT/ ;Output extension
BLOCK 1 ;Protection, mode, creation date
BLOCK 1 ;PPN or path pointer
;Next the buffer control blocks. (The monitor will build the
; buffers on the first IN and OUT calls.):
INHDR: BLOCK 1 ;Input buffer control block
INPTR: BLOCK 1 ;Input buffer ring byte pointer
INCNT: BLOCK 1 ;Input buffer ring byte count
OUHDR: BLOCK 1 ;Output buffer control block
OUPTR: BLOCK 1 ;Output buffer ring byte pointer
OUCNT: BLOCK 1 ;Output buffer ring byte count
END BUFENT
11-52
PROGRAM INPUT AND OUTPUT
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.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 system
crashes when writing a disk file, the entire disk file to date is
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.
11-53
PROGRAM INPUT AND OUTPUT
o 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 checkpoints 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. These
calls return the device and its channel to the monitor's pool.
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-54
PROGRAM INPUT AND OUTPUT
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.
A0 signifies an optional argument. If your program does not
supply the contents, the monitor uses a default value.
V signifies a value that is only returned by the monitor
after the call is completed.
The short form of the argument list for LOOKUP, ENTER, and RENAME
monitor calls is:
Word LOOKUP ENTER RENAME Contents
0 A A A File name in SIXBIT.
1 A A A Bits 0-17: file extension in
SIXBIT.
V A0 A0 Bits 18-20: high-order three
bits of the creation date.
V A0 A0 Bits 21-35: access date.
V V V Bits 18-35: on an error return
from the call, the error code is
stored here. Refer to Section
11.14.
2 V A0 A Bits 0-8: protection code.
V V V Bits 9-12: data mode of file
when it was created.
V A0 A Bits 13-23: creation time in
minutes since midnight.
V A0 A Bits 24-35: low-order twelve
bits of creation date.
11-55
PROGRAM INPUT AND OUTPUT
3 A A A Word 3 on input is: PPN or path
pointer. A path pointer takes
the form:
0,,addr
Where: addr is the
address of the path
block. Refer to the
PATH. UUO in Chapter 22.
3 V - - 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.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 columns are:
A = an argument (supplied by either a privileged or unprivileged
program) and returned by the monitor as a value.
A0 = an argument like A, except that a 0 argument causes the
monitor to substitute a default value.
11-56
PROGRAM INPUT AND OUTPUT
A1 = an argument if supplied by a privileged program; if supplied
by an unprivileged program, it is ignored.
V = the value returned by the monitor cannot be set even by a
privileged program; the monitor will ignore the argument.
Word Symbol LOOKUP ENTER RENAME Contents
0 .RBCNT A A A The count of the number of
arguments that follow.
Left half: unused, must be
zero.
Right half: flags + number
of arguments following
this.
Where the flags can be:
Bits Symbol Meaning
18 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.
19 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.
20 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.
11-57
PROGRAM INPUT AND OUTPUT
21 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.
CREATE/ UPDATE/
Word Symbol LOOKUP SUPERSEDE RENAME Contents
1 .RBPPN A0 A0 A0 A PPN or a pointer to a
path block. For a path
pointer, the left half
contains zero, and the
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 (indicating
the MFD).
The search defaults to LIB
and SYS only if the
directory path was not
specified.
11-58
PROGRAM INPUT AND OUTPUT
2 .RBNAM A A A The SIXBIT file name,
left-justified with
trailing nulls.
If the Master File
Directory or a User File
Directory is being LOOKed
UP, ENTERed, or RENAMEd on
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 A A A 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.
V A0 A0 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.
V A0 A0 Bits 21-35 (RB.ACD): The
access date.
V V V 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.
11-59
PROGRAM INPUT AND OUTPUT
4 .RBPRV V A0 A Bits 0-8: Protection code
(RB.PRV).
V V A Bits 9-12: Data mode in
which the file was created
(RB.MOD).
V A0 A Bits 13-23: Creation time
in minutes since midnight
(RB.CRT). The system
updates the creation time
only when you write
additional blocks to the
file.
V A0 A Bits 24-35: The low-order
12 bits of the 15-bit
creation date in standard
format (RB.CRD).
5 .RBSIZ V V V The written length of the
file, in words. If your
program sets this value,
the monitor ignores it.
6 .RBVER V A A The octal version number of
the file, same as .JBVER.
7 .RBSPL V A A 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
ENTER has not been
performed.
11-60
PROGRAM INPUT AND OUTPUT
10 .RBEST V A A The estimated length of the
file, in positive number of
blocks.
On the execution of an
ENTER call, the monitor
uses this value as the
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 .RBALC V A A 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.
11-61
PROGRAM INPUT AND OUTPUT
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.
12 .RBPOS V A A 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
0. 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.
11-62
PROGRAM INPUT AND OUTPUT
13 .RBUFW V V V Determines the disk drive
that the file was written
on; the format is as
follows:
Bits 0-9: Reserved for
DIGITAL.
Bits 10-17 (RB.UNI):
Unit(s) 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 A A A Reserved for customer
definition; does not
require privileges.
15 .RBMTA V A1 A1 A 36-bit tape label, if the
file has been put onto
magnetic tape.
16 .RBDEV V V V The logical name of the
unit on which the file is
located.
17 .RBSTS V A1 A1 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-63
PROGRAM INPUT AND OUTPUT
20 .RBELB V V V 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): Error
type: bad version block
number.
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): Error
type: search or header
compare.
Bits 3-8 (RB.ETM): Mask of
all error type bits.
Bits 9-35 (RB.EBN): Number
(within unit) of first bad
block.
11-64
PROGRAM INPUT AND OUTPUT
21 .RBEUN V V V 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.
Bits 10-17 (RB.EUN): Unit
number within controller;
bit 10 = unit 7, bit 17 =
unit 0.
Bits 18-20 (RB.EKN):
Controller number.
Bits 21-35 (RB.ECN): CPU
number.
22 .RBQTF V A1 A1 Contains the logged-in
quota.
This quota is the maximum
number of data and RIB
blocks that can be in this
structure's directory while
the user is logged-in. The
UFD and the UFD's RIB are
not included in this count.
22 .RBTYP V A A Contains file type and
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.
11-65
PROGRAM INPUT AND OUTPUT
23 .RBQTO V A1 A1 Contains the logged-out
quota (meaningful for the
UFD only).
This quota is the maximum
number of data and RIB
blocks that can be left in
this structure's directory
after you log out. LOGOUT
requires that the user must
be below this quota to log
out.
23 .RBBSZ V A A Contains byte and record
length information. System
programs (such as FORTRAN)
use this word, and its
format is determined by the
application in which it is
used. Refer to UUOSYM for
a complete description of
this word.
24 .RBQTR V A1 A1 Reserved quota (applies
only to UFDs). This
information is not
completely implemented by
the monitor. (Meaningful
for UFD only.)
24 .RBRSZ V A A Contains record and block
size information. System
programs (such as FORTRAN)
use this word; its format
is determined by the
application in which you
use it. Refer to UUOSYM
for a complete description
of this word.
25 .RBUSD V A1 A1 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).
11-66
PROGRAM INPUT AND OUTPUT
LOGIN reads this word so
that it does not have to
LOOKUP all files to set up
the number of written
blocks. LOGIN sets Bit 0
(RP.LOG) of the file status
word (see below), and
LOGOUT clears it to
indicate whether LOGOUT has
stored the quantity.
25 .RBFFB V A A Contains first free byte
and application-specific
information. This word is
used by system programs
(such as FORTRAN.) Refer to
UUOSYM for a complete
description of this word.
26 .RBAUT V A1 A1 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.
30 .RBIDT V A1 A1 BACKUP'S incremental date
and time in UFD.
31 .RBPCA V A1 A1 Privileged argument
reserved for customer
definition.
32 .RBUFD V V V The logical block number in
the file structure of the
RIB for the UFD in which
the file appears.
33 .RBFLR V V V 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).
11-67
PROGRAM INPUT AND OUTPUT
34 .RBXRA V V V The extended RIB address
(that is, the logical unit
number and the cluster
address of the next RIB in
a multiple RIB file).
35 .RBTIM V V V The internal creation and
time of the file, in the
universal date-time format.
36 .RBLAD V A1 A1 The last accounting date.
Valid only for UFDs.
37 .RBDED V A1 A1 The directory expiration
date. For disk
directories, this is valid
only for UFDs. For
magtape, this is valid only
for labelled tapes and
refers to the expiration
date of the file.
40 .RBACT A A1 A1 Account string word 1, in
ASCII.
This is non-zero on an
ENTER, and is not valid for
UFDs.
41 .RBAC2 A A1 A1 Account string word 2, in
ASCII.
42 .RBAC3 A A1 A1 Account string word 3, in
ASCII
43 .RBAC4 A A1 A1 Account string word 4, in
ASCII.
44 .RBAC5 A A1 A1 Account string word 5, in
ASCII.
45 .RBAC6 A A1 A1 Account string word 6, in
ASCII.
46 .RBAC7 A A1 A1 Account string word 7, in
ASCII.
47 .RBAC8 A A1 A1 Account string word 8, in
ASCIZ.
11-68
PROGRAM INPUT AND OUTPUT
A null byte terminates the string.
Bits Symbol Meaning
0 RP.LOG Set if the user is logged in. LOGIN sets this
bit; LOGOUT clears it.
5 RP.CHG Set if some file has changed in this UFD since
the last BACKUP.
7B11 RP.UER All UFD errors.
9 RP.UCE Set if any file in this UFD has had a software
checksum error or a redundancy check error.
10 RP.UWE Set if any file in this UFD has had a hard
data error while writing.
11 RP.URE Set if any file in this UFD has had a hard
data error while reading.
18 RP.DIR 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 UFD is specified on
an ENTER or RENAME and this bit is not set.
19 RP.NDL If set, the file cannot be deleted, renamed,
or superseded, even by a privileged program.
20 RP.DMP Set if this is an unprocessed crash file.
This bit is set on CRASH.EXE files and used by
the CRSCPY program.
21 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.
22 RP.ABC Set if the file always has bad checksums
(because the monitor never recomputes a
checksum) for example, SWAP.SYS, SAT.SYS.
23 RP.CBS If set, RP.CMP (Bit 26) is set on entry to UFD
compressor.
24 RP.ABU If set, disk backup programs should always
dump this file.
25 RP.NQC If set, the file is a non-quota checked file,
and it is not billed to the user's disk quota.
11-69
PROGRAM INPUT AND OUTPUT
26 RP.CMP If set, the UFD is being compressed.
27 RP.FCE If set, the file has a software checksum error
or a redundancy check error (the IO.IMP bit
has been set).
28 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.
29 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.
30 RP.RMS If set, this file was created by RMS (the
Record Management Service).
31 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.
32 RP.BFA If set, the file is bad because of a tape read
error during a restore.
33 RP.CRH If set, the file was closed after a crash.
35 RP.BDA If set, the file has been marked as bad by a
damage assessment program.
715 RP.ERR All file errors.
11.14 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
0 ERFNF% 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.
1 ERIPP% The UFD does not exist on the specified file
structure (incorrect PPN).
11-70
PROGRAM INPUT AND OUTPUT
2 ERPRT% Protection failure, or directory is full for a
DECtape.
3 ERFBM% File being modified (ENTER, RENAME).
4 ERAEF% 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).
5 ERISU% 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.
6 ERTRN% One of the following errors occurred:
o Transmission, device, or data error (RUN,
GETSEG, MERGE. only).
o Hardware-detected device or data error
detected while reading the UFD's RIB or the
file's RIB.
o Software-detected data inconsistency error
detected while reading the UFD's RIB or the
file's RIB.
7 ERNSF% File is not in executable format (RUN, GETSEG,
MERGE. only).
10 ERNEC% Not enough core available to load the file (RUN,
GETSEG, MERGE., SAVE. only).
11 ERDNA% Device not available (RUN, GETSEG, FILOP.,
SAVE., MERGE.).
12 ERNSD% No such device (RUN, GETSEG, MERGE., SAVE.).
For FILOP., this error code is returned if an
open function fails to assign the device.
13 ERILU% Illegal monitor call for FILOP. or GETSEG.
14 ERNRM% There is no room on this file structure or the
disk space quota was exceeded (an overdraw quota
is not considered).
15 ERWLK% A write-lock error occurred. The program cannot
write on this device.
16 ERNET% Not enough table space is available in the
monitor's free core.
17 ERPOA% Partial allocation only.
20 ERBNF% Block not free at allocated position (ENTER,
RENAME).
21 ERCSD% Cannot supersede a directory (ENTER).
22 ERDNE% Cannot delete a directory that is not empty
(RENAME).
23 ERSNF% The sub-file directory was not found (some SFD
in the specified path was not found).
11-71
PROGRAM INPUT AND OUTPUT
24 ERSLE% The search list is empty (a LOOKUP or an ENTER
was performed on the generic device DSK and the
search list was empty).
25 ERLVL% You cannot create an SFD nested deeper than the
maximum allowed level of nesting.
26 ERNCE% 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).
27 ERSNS% 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).
30 ERFCU% Cannot update file.
31 ERLOH% Low segment overlaps high segment (GETSEG or
RUN), or page overlap error (MERGE.).
32 ERNLI% The user is not logged in (RUN, SAVE. only).
33 ERENQ% The file has outstanding locks set.
34 ERBED% The file has a bad EXE file directory (GETSEG,
RUN, MERGE.).
35 ERBEE% The file has a bad extension for an .EXE file
(GETSEG, RUN, MERGE.).
36 ERDTB% The file's EXE directory is too big (GETSEG,
RUN, MERGE.).
37 ERENC% The network capacity has been exceeded; not
enough space for the connect message (LOOKUP,
ENTER).
40 ERTNA% The task was not available (LOOKUP, ENTER,
RENAME).
41 ERUNN% An unknown network node was specified, or the
node went down during the connect (ENTER).
42 ERSIU% SFD is in use (RENAME).
43 ERNDR% File has an NDR (No Delete or Rename) lock
(FILOP.).
44 ERJCH% Job count high (too many simultaneous accesses).
45 ERSSL% Cannot rename SFD to lower level.
46 ERCNO% Channel not OPENed (FILOP.).
47 ERDDU% Device is not useable; it is offline.
50 ERDRS% Device is restricted.
51 ERDCM% Device is under control of Mountable Device
Allocator (MDA) (GALAXY).
52 ERDAJ% Device is allocated to another job.
53 ERIDM% Illegal data mode specified (FILOP.).
54 ERUOB% Unknown or undefined bits set (OPEN).
55 ERDUM% Device is in use on an MPX-controlled channel.
56 ERNPC% No per-process space available for extended I/O
channel.
57 ERNFC% No free channels are available.
60 ERUFF% Unknown FILOP. function.
61 ERCTB% Channel too big.
62 ERCIF% Function illegal on this channel.
11-72
PROGRAM INPUT AND OUTPUT
63 ERACR% Address check occurred while reading arguments.
64 ERACS% Address check occurred while storing arguments.
65 ERNZA% A negative or zero argument count was specified.
66 ERATS% Argument block was too short.
67 ERLBL% Magnetic tape labelling error.
70 ERDPS% Duplicate segment in address space.
71 ERNFS% No free section (SEGOP.).
72 ERSII% Segment information inconsistent. A segment
number and name do not match.
11-73
12-1
CHAPTER 12
DISKS (DSK)
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 addresses 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.
12-1
DISKS (DSK)
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.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 DSKA0) to the larger file structure
specification (such as DSKA), which may contain more than one logical
unit (such as DSKA0 and DSKA1). 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 DSKA1 for a file,
the monitor places the file on DSKA1 if there is room; if not, it
places it on another logical unit (such as DSKA0) 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 DSKA0),
by a controller class name, by a controller designation, or by a
physical disk unit name.
12-2
DISKS (DSK)
Controller classes, physical controller names, and the names of the
physical disk units they control are:
o Controller class RP. Physical controller names for this
class are of the form RPc, where c is A-Z.
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 RH11 controllers (KS10 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).
o 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 c 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.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 searching 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-3
DISKS (DSK)
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
extension. For example, you specify the file TEST.TST in a monitor
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 x refers to the owner field.
the second digit y refers to users with the same project
number as the owner.
the third digit z 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-4
DISKS (DSK)
The protection code for a file is stored in its RIB, and contains
three 3-bit fields:
1. The first 3-bit field gives a protection code that determines
access by the owner of the file.
2. 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.
3. The last 3-bit field gives a protection code that determines
access for all other users.
When the monitor symbol INDPPN=0 (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
0 Any access is allowed. The owner can execute, read,
append to, update, write, rename, and change the
protection of his file.
1 Same as code 0.
2 Any access to the file, except for renaming it, is
allowed.
3 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.
4 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.)
12-5
DISKS (DSK)
5 This code is equivalent to code 2, but the File Daemon
is called on any attempted access that violates the
protection codes.
6 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.
7 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.
Note that codes 4 through 7 specify 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 a 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 N.
Table 12-1: File Access Protection -- Owner Field
______________________________________________________________________
Access Type Code
______________________________________________________________________
0 1 2 3 4 5 6 7
EXECUTE Y Y Y Y Y Y Y Y
READ Y Y Y Y Y Y Y Y
APPEND TO Y Y Y N Y Y N N
UPDATE Y Y Y N Y Y N N
WRITE Y Y Y N Y Y N N
RENAME Y Y N Y Y N N N
CHANGE PROTECTION Y Y Y Y Y Y Y Y
CALL FILDAE N N N N Y Y Y Y
______________________________________________________________________
12-6
DISKS (DSK)
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
0 .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.
1 .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.
2 .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.
3 .PTUPD The user cannot write, rename, or change the
protection. However, the user can execute,
read, append to, or update the file.
4 .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.
5 .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.
6 .PTEXO The user can only execute the file.
7 .PTNON The user cannot access the file.
Table 12-2 shows the access allowed and prevented by each code for
each type of access by project members and by other users.
12-7
DISKS (DSK)
Table 12-2: File Access Protection -- Second and Third Digits
______________________________________________________________________
Access Type Code
______________________________________________________________________
0 1 2 3 4 5 6 7
EXECUTE Y Y Y Y Y Y Y N
READ Y Y Y Y Y Y N N
APPEND TO Y Y Y Y Y N N N
UPDATE Y Y Y Y N N N N
WRITE Y Y Y N N N N N
RENAME Y Y N N N N N N
CHANGE PROTECTION Y N N N N N N N
______________________________________________________________________
The greatest protection that a file can have is code 7, and the least
protection is code 0. Usually, the owner's field is 0 or 1. It is
always possible for the owner of a file to change the protection code
associated with his file, even if the owner's protection code is set
to 7. Therefore, codes 0 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.
o 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-8
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 GETTAB items are:
%LDSTP - Standard file protection.
%LDUFP - Standard directory protection.
%LDSPP - Spooled file protection.
%LDSYP - Standard SYS protection.
%LDSSP - SYS:*.SYS protection.
You can set a default file protection code by using either the SET
DEFAULT 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 (FILDAE)
A File Daemon is a privileged program that serves the following
functions:
o Oversees file accessing
o Aids in accounting
o Tracks program use
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 requirements.
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 monitor 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-9
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.
--------------
| PPN |
|------------| --------------- Data
| UFD | CFP |----->| | Blocks
------|------- | RIB | ----------
| |------>| |
--------------- | |
----------
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-10
DISKS (DSK)
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 file structure has directories
arranged in a tree structure of three levels:
1. The Master File Directory (MFD) is at the root of the tree.
It serves as an index to User File Directories (UFDs) on the
file structure.
2. 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).
3. Subfile Directories (SFDs) are at the remaining levels of the
tree structure. SFDs contain pointers to and data about user
files and subordinate SFDs.
12-11
DISKS (DSK)
The general disk file organization for a file structure is shown in
Figure 12-2.
Master File User File Data
Directory Directories Files
/-----------------\
| | ------------
| ------------- | /----->| File 1 |
\->| 1 | 1 | | | |----------| ------------
|-----|-----| | | | Ext | |------------->| |
| UFD | |--/ | |-----|----| | |
|-----|-----| | | File 2 | | |
| 10 | 10 | | |----------| ------------ |
|-----|-----| | | Ext | |---------->| | |
| UFD | |------/ |-----|----| | | |
|-----|-----| | File 3 | | |---
| 20 | 20 | |----------| ------------ |
|-----|-----|------\ | Ext | |------->| | |
| UFD | | | |-----|----| | | |
|-----|-----| | | . | | |---
| . | | | . | | |
| . | | | . | | |
| . | | ------------ | |
------------- | ------------
| ------------
\----->| File x |
|----------| ------------
| Ext | |------------->| |
|-----|----| | |
| File y | | |
|----------| ------------ |
| Ext | |---------->| | |
|-----|----| | | |
| File z | | |---
|----------| ------------ |
| Ext | |------->| | |
|-----|----| | | |
| . | | |---
| . | | |
| . | | |
------------ | |
------------
Figure 12-2: General Disk File Organization for a File Structure
12-12
DISKS (DSK)
12.6.1 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 proj,prog ;Project-programmer number
XWD 'UFD',CFP ;UFD,,compressed file pointer to UFD
Where: proj and prog give the project-programmer number (PPN) for a
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.
The MFD contains an entry for each UFD on the system. A "continued
MFD" is the set of all MFDs for all file structures in a job's search
list.
12.6.2 User File Directories (UFDs)
A 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 /filename/ ;File name
XWD 'extension',CFP ;Extension,,CFP to file
Where: file name is a SIXBIT file name of up to six characters.
extension is a SIXBIT file extension of up to three
characters.
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.
12-13
DISKS (DSK)
UFDs are created by programs, such as LOGIN, CREDIR, and PULSAR when
the program is run in a privileged account, such as [1,2]. Only
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 MONGEN 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.
You can create subfile directories by using the CREDIR program, which
is described in the TOPS-10 User Utilities Manual. You can delete
SFDs using either the DELETE command or the delete function of the
RENAME call. Note, however, that an error will occur if you try to
delete an SFD when it is included in your job's default path in your
job search list, or when it contains files.
12.6.4 Directory Paths
A disk file is uniquely identifiable by a string giving its file
structure 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 UFD.
12-14
DISKS (DSK)
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
following:
o Your job's UFD.
o Your job's UFD and one or more SFDs in a chain originating in
your UFD.
o A UFD different from your job's UFD.
o A UFD different from your job's UFD and one or more SFDs in a
chain originating in that UFD.
The initial default path for a job is your UFD. To specify a
different path, you must give the path in the format:
[projno,progno,sfd1,sfd2,...]
Where: projno and progno give the project-programmer number, or the
UFD.
sfd1 is the name of a subfile directory pointed to by a file
in the UFD.
sfd2 is the name of a subfile directory pointed to by a file
in sfd1, and so forth.
For example, if you have not changed the initial default path for your
job, then the commands
.R MACRO
*FOO.REL=FOO.MAC
specify the files FOO.REL and FOO.MAC in your job's UFD (that is, your
PPN).
However, you can specify a different path. The commands:
.R MACRO
*FOO.REL=MINE:FOO.MAC[27,5031,OLD]
specify FOO.REL in your UFD and FOO.MAC in the SFD called OLD in the
UFD for PPN [27,5031] on the file structure MINE:.
12-15
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:
Example
MOVE AC1,[XWD ARGLEN,ARGLST]
PATH. AC1,
JRST ERR
JRST NORM
ARGLST: EXP .PTFSN
EXP 0
SIXBIT /FOO/
EXP 0
SIXBIT /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 0
EXP 0
EXP 0
ARGLEN = .-ARGLST
12-16
DISKS (DSK)
Refer to Figure 12-3. The path for File A is:
X.MAC[10,63]
The path for File B is:
Z.ALG[14,5,M]
----------------------------
DSK:[1,1].UFD
----------------------------
/ | \
/ | \
/ | \
--------------- -------------- --------------
[10,63].UFD [14,5].UFD [20,7].UFD
--------------- -------------- --------------
/ \ / | \ /
/ \ / | \ /
------- ------- ------- | ------- -------
A | B
------- ------- ------- | ------- -------
X.MAC | Y.CB
|
-------
M.SFD
-------
/
/
-------
C
-------
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
12-17
DISKS (DSK)
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]
2. DSKB:[PPN,A,B,C]
3. DSKC:[PPN,A,B,C]
4. DSKA:[PPN,A,B]
5. DSKB:[PPN,A,B]
6. DSKC:[PPN,A,B]
7. DSKA:[PPN,A]
8. DSKB:[PPN,A]
9. 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.
12-18
DISKS (DSK)
---
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 A.SFD Y.SFD File1 B.SFD File5
----- ----- ----- ----- ----- ----- -----
: : :
..............: :........... -----
: : : : : File4
----- ----- ----- ----- ----- -----
File2 File3 B.SFD B.SFD File6
----- ----- ----- ----- -----
: :.........
: : :
----- ----- -----
C.SFD C.SFD D.SFD
----- ----- -----
.....:..... .....:..... :.....
: : : : :
----- ----- ----- ----- -----
File2 D.SFD File7 File6 File2
----- ----- ----- ----- -----
...................:
: :
----- -----
File4 File5
----- -----
Figure 12-4: Directory Paths on Multiple File Structures
Refer to Figure 12-5. LOOKUP on SIXBIT/DSK/ with no matches results
in the search that is indicated.
12-19
DISKS (DSK)
---
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 -------> A.SFD Y.SFD File1 B.SFD File5
----- ----- ----- ----- ----- ----- -----
: ^ : :
: | : -----
..............: \---------\ :........... File4
: : : \ : : -----
----- ----- ----- ----- -----
File2 File3 B.SFD -------> B.SFD File6
----- ----- ----- ----- -----
: ^ :
: | :
: \---------\ :...........
: \ : :
----- ----- -----
C.SFD -------> C.SFD D.SFD
----- ----- -----
.....:..... : :
: : ----- -----
----- ----- File7 File2
File2 D.SFD ----- -----
----- -----
..........:
: :
----- -----
File4 File5
----- -----
Figure 12-5: LOOKUP on DSK with No Matches
Refer to Figure 12-6. LOOKUP on SIXBIT/DSK/ and SIXBIT/FILE2/ results
in DSKA:FILE2[PPN,A,B].
12-20
DISKS (DSK)
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 ---\ DSKB:[1,1].UFD DSKC:[1,1].UFD
-------------- | -------------- --------------
: | : :
-------------- <--/ -------------- --------------
DSKA:PPN.UFD ------\ DSKB:PPN.UFD DSKC:PPN.UFD
-------------- | -------------- --------------
: | : :
......:...... | ....:.... .........:........
: : | : : : : :
----- ----- <--/ ----- ----- ----- ----- -----
File1 A.SFD -----\ A.SFD Y.SFD File1 B.SFD File5
----- ----- | ----- ----- ----- ----- -----
: | : :
..............: | :........... -----
: : : | : : File4
----- ----- ----- | ----- ----- -----
File2 File3 B.SFD <----/ B.SFD File6
----- ----- ----- ----- -----
^ | : :
| | : :
\-----------/ : :...........
: : :
----- ----- -----
C.SFD C.SFD D.SFD
----- ----- -----
.....:..... : :
: : : :
----- ----- ----- -----
File2 D.SFD File7 File2
----- ----- ----- -----
...................:
: :
----- -----
File4 File5
----- -----
Figure 12-6: LOOKUP on DSK for FILE2
12-21
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
-------------- -------------- --------------
: : :
......:...... ....:.... .........:........
: : : : : : :
----- ----- ----- ----- ----- ----- -----
File1 A.SFD A.SFD Y.SFD File1 B.SFD File5
----- ----- ----- ----- ----- ----- -----
: : :
..............: :........... -----
: : : : : File4
----- ----- ----- ----- ----- -----
File2 File3 B.SFD B.SFD File6
----- ----- ----- ----- -----
: :.........
: : :
----- ----- -----
C.SFD <----- C.SFD D.SFD
----- | ----- -----
.....:..... | : :
: : | : :
----- ----- | ----- -----
File2 D.SFD--/ File7 File2
----- ----- ----- -----
...................:
: : :
----- ----- =====
File4 File5 File1
----- ----- =====
Figure 12-7: ENTER on DSKA for FILE1
12-22
DISKS (DSK)
Refer to Figure 12-8. When the job's default path is
DSKB:[PPN,A,B,C], the following calls results in the described
fashion.
ENTER on SIXBIT/DSK/ and SIXBIT/FILE6/ results in the file being
created on 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 A.SFD Y.SFD File1 B.SFD File5
----- ----- ----- ----- ----- ----- -----
: : :
..............: :........... -----
: : : : : File4
----- ----- ----- ----- ----- -----
File2 File3 B.SFD B.SFD File6
----- ----- ----- ----- -----
: :.........
: : :
----- ----- -----
C.SFD C.SFD D.SFD
----- ----- -----
.....:..... .....:..... :.....
: : : : :
----- ----- ----- ===== -----
File2 D.SFD File7 File6 File2
----- ----- ----- ===== -----
...................:
: : :
----- ----- -----
File4 File5 File1
----- ----- -----
Figure 12-8: ENTER on DSK for FILE6
12-23
DISKS (DSK)
ENTER on SIXBIT/DSK/ and SIXBIT/FILE2/ supersedes FILE2 on
DSKA:FILE2[PPN,A] as shown in Figure 12-9.
---
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 A.SFD Y.SFD File1 B.SFD File5
----- ----- ----- ----- ----- ----- -----
: : :
..............: :........... -----
: : : : : File4
-=-=- ----- ----- ----- ----- -----
File2 File3 B.SFD B.SFD File6
-=-=- ----- ----- ----- -----
: :.........
: : :
----- ----- -----
C.SFD C.SFD D.SFD
----- ----- -----
.....:..... .....:..... :.....
: : : : :
----- ----- ----- ----- -----
File2 D.SFD File7 File6 File2
----- ----- ----- ----- -----
...................:
: : :
----- ----- -----
File4 File5 File1
----- ----- -----
Figure 12-9: ENTER on DSK for FILE2
12-24
DISKS (DSK)
ENTER on SIXBIT/DSK/ and SIXBIT/FILE7/ supersedes FILE7 on DSKB, as
illustrated in Figure 12-10.
---
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 A.SFD Y.SFD File1 B.SFD File5
----- ----- ----- ----- ----- ----- -----
: : :
..............: :........... -----
: : : : : File4
----- ----- ----- ----- ----- -----
File2 File3 B.SFD B.SFD File6
----- ----- ----- ----- -----
: :.........
: : :
----- ----- -----
C.SFD C.SFD D.SFD
----- ----- -----
.....:..... .....:..... :.....
: : : : :
----- ----- -=-=- ----- -----
File2 D.SFD File7 File6 File2
----- ----- -=-=- ----- -----
...................:
: :
----- -----
File4 File5
----- -----
Figure 12-10: ENTER on DSK for FILE7
12-25
DISKS (DSK)
Example
Assume that you set up the following path:
MOVE AC1,[XWD 5,A]
PATH. AC1,
HALT .
MOVE AC1,[XWD 3,B]
PATH. AC1,
HALT .
A: .PTFSD ;Define default path
.PTSCY ;Scanning in effect
10,,63 ;UFD=[10,63]
SIXBIT/NAME/ ;SFD=NAME
0 ;Default path is 10,63,NAME
B: .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 on
DSK:FILTST.EXT, the following directories would be searched:
[10,63,NAME]
[10,63] ;Your search list
[10,7]
[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] ;System search list
12.7 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.
12-26
DISKS (DSK)
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.
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).
o Creates (ENTERs and RENAMEs) for files in the directory
(PT.CRE).
o Reads for the directory itself (PT.SRC).
Users are divided into the same three privilege classes for UFDs and
SFDs as they are for files. Each privilege class has three
independent bits, specifying a protection code. The directory
protection codes are:
Code Symbol Meaning
0 No access allowed.
1 PT.SRC Search directory.
2 PT.CRE Allow file creation.
3 PT.SRC+PT.CRE Search directory and allow
creates.
4 PT.LOK Allow LOOKUPs.
5 PT.SRC+PT.LOK Search directory and allow
LOOKUPs.
6 PT.CRE+PT.LOK Allow creates and LOOKUPs.
7 PT.SRC+PT.CRE+PT.LOK Search directory and allow
creates and LOOKUPs.
Note that, for disk files, 7 is the highest protection code. For
directories, 0 is the highest protection.
As the owner of your UFD, you can control the access to your UFD and
SFDs. You can always change the protection code of your directories
through the use of the RENAME monitor call. Any program can create or
delete SFDs; however only privileged programs can create or delete
UFDs. The monitor checks for the following types of privileged
programs:
o Jobs logged in under [1,2].
o Jobs running with the JACCT bit set in JBTSTS.
12-27
DISKS (DSK)
Programs meeting the above requirements can do the following:
o Create UFDs and/or SFDs.
o Delete empty UFDs and/or SFDs.
o Set privileged arguments to LOOKUP, ENTER, and RENAME monitor
calls.
o Ignore file protection codes unless FTFDAE = 1 and the File
Daemon is running.
Privileges are similar for both UFDs and SFDs except that SFDs can be
created, renamed, and deleted by both a privileged program and the
owner of the SFD.
The MONGEN parameter M.XFFA can be set to prevent [1,2] jobs from
being able to access files. If M.XFFA equals 0 (the default
condition), FILDAE can prevent files from being accessed by [1,2]. If
M.XFFA is set to -1, FILDAE is not invoked on attempted access by
[1,2] jobs.
As when accessing existing files, it is possible to control the
operations in a directory by using a File Daemon. Whenever an
operation fails due to an access protection failure, the monitor calls
a File Daemon (if one is running). Therefore, a protection code of
775 allows users in the same project to create files in the directory
without the File Daemon being called. However, because of the 5 code
in the other users' field, any other user's attempt to create a file
in that directory causes the monitor to call the File Daemon. The
File Daemon checks the ACCESS.USR associated with the directory. The
file is created if the /CREATE switch is specified in the ACCESS.USR
file. The File Daemon is called automatically when a directory access
protection failure occurs.
12.8 JOB SEARCH LISTS
For most program uses, a file structure name serves the same purposes
as a device name. Many programs use the generic device name DSK:.
This causes the monitor to search a list of file structures called the
job search list.
Your job search list is in two parts: the active search list and the
passive search list. The active search list is searched whenever you
use the generic device name DSK. The passive search list is never
searched; it is checked when your job logs out, to make sure you have
not exceeded your disk quota for the structures listed there.
12-28
DISKS (DSK)
The SETSRC program (described in the TOPS-10 User Utilities Manual)
can list and change your job search list. The program reports the
list in the form:
strname,...strname, FENCE strname,...strname
Where: strname is the name of a file structure.
FENCE represents the boundary between the active and passive
search lists. Structures are searched in the order they are
listed, from left to right. The structures listed on the left
of the FENCE are the active job search list; the structures
listed on the right of the FENCE are the passive search list.
Each strname may be followed by an optional switch that
indicates how the file structure can be accessed (for example,
read only).
A default search list is defined for you by the system administrator
when you are given your PPN for the system. When you log in, the
LOGIN program sets the default search list for your job and makes sure
that you have a UFD on each structure for which you have a nonzero
quota. You can modify the search list for your job by:
o Using the SETSRC program (see the TOPS-10 User Utilities
Manual). This program allows you to add to or delete from
the list of structures in your job search list. In addition,
you can use the /NOCREATE switch to SETSRC to prevent
creation of files on a structure unless you have specified
that structure explicitly. There are other options for
SETSRC provided through other switches.
o Using the MOUNT monitor command (see the TOPS-10 Operating
System Commands Manual). This command makes a structure
available to your program, and adds the structure name to the
end of your active search list. When you modify your search
list with MOUNT, the modifications are abolished when you log
off the system. When you log back on the system, your
predefined search list is used.
When you request that a structure be removed from your search list
(using the SETSRC program), the structure is moved from the active to
the passive search list. This is done so the structure can be
quota-checked when you log off the system. The LOGOUT program
requires that the number of blocks allocated to a user on each file
structure be less than or equal to the logged-off quota on that file
structure.
12-29
DISKS (DSK)
If a job's search list is:
DSKA:/NOCREATE,DSKB:, FENCE
and the user OPENs a channel for device DSKA, an ENTER on that channel
will create a file on DSKA. If the channel is opened for device DSK,
the ENTER will create a file on DSKB.
When your program issues a LOOKUP for device DSK, the monitor searches
the file structures in the order specified by your job's search list.
When your program issues an ENTER specifying a non-existent file name,
the monitor places the file on the first file structure in your search
list that has space and does not have the NOCREATE or NOWRITE flag
set. When your program issues an ENTER specifying an existing file
name on any file structure in your search list, the monitor places the
file on the same structure that contains the older version of the file
(and the file is superseded).
When you set the NOWRITE flag, the monitor will not allow your job to
write on the structure.
When you set the NOCREATE flag, you cannot create new files on the
file structure, unless you explicitly specify that file structure.
For example, if you set the NOCREATE flag for DSKA and you make the
following specification:
DSKA:FOO=
the monitor creates FOO on DSKA because you explicitly specified DSKA.
But, when you make the following specification:
DSK:FOO=
the monitor creates FOO on the first file structure specified in your
job's search list that does not have the NOCREATE or NOWRITE flag set.
12.9 DISK PRIORITIES
You can use the DISK. monitor call to set and examine the parameters
associated with disk file systems. DISK. allows your program to
assign a priority level for disk operations such as data transfers and
head positionings. You can set these priorities either for a specific
I/O channel or for all channels associated with your job. When you
use disk priority operations, the disk operation request with the
highest priority level is chosen. If no priorities are set, the
request most satisfying disk optimization is chosen.
12-30
DISKS (DSK)
12.10 DISK I/O
A number of monitor calls are useful for disk I/O. The LOOKUP, ENTER,
and RENAME calls can use an extended argument list for calls to disk.
The extended argument list is described in Section 12.13.
The monitor calls that are especially useful for disk I/O are:
CLOSE Closes a disk file.
DEVPPN Returns the PPN associated with a disk device.
DISK. Sets or returns disk file parameters.
DSKCHR Returns disk characteristics.
ENTER Selects a file for output.
FILOP. Performs many file operations, including creating,
deleting, writing, reading, renaming, and superseding a
file.
GOBSTR Returns file structure names from the search list for a
given job or the system search list.
JOBSTR Returns file structure names from the search list for
the current job.
LOOKUP Selects a file for input.
PATH. Sets or reads the user's default directory path, reads
the default directory path for a device or channel, or
sets or reads logical name definitions.
RENAME Renames a file. This "renaming" can include changing
the file name, extension, protection for the file, and
deleting the file.
STRUUO Modifies the search list for a job or for the system.
SUSET. Selects a logical block on a disk unit, either with
respect to file structure or to unit name.
SYSPHY Returns the names of physical disk units.
SYSSTR Returns the names of file structures on the system.
USETI Selects a block for next input.
USETO Selects a block for next output.
12-31
DISKS (DSK)
12.11 DISK I/O PROCESSING
The following description of disk I/O processing assumes that a disk
request has been processed, an I/O list has been built, and the
initial sector address is known. The disk is not necessarily on the
correct cylinder.
The general flow is illustrated below as a series of steps:
1. The correct cylinder is determined by dividing the sector
number by the number of sectors per cylinder.
2. To determine if a seek is needed, the cylinder number is
compared with the current cylinder number, which is
remembered from the last transfer. There are some limited
conditions under which the drive will not be on the cylinder
which is recorded in the software. In these cases, the
implied seek of the drive will be used.
3. The system can only start a seek if the drive is idle. For
non-MASSBUS drives, both the drive and the controller must be
idle.
4. If there is a data transfer in progress the request is queued
for the unit and will be started at a later time at interrupt
level.
5. If the drive is free, a seek will be started.
6. If the drive is already on the correct cylinder, the seek
logic is bypassed.
7. If the drive and channel are busy, the request is added to a
queue for the required channel to be started at interrupt
level at a later time.
8. If the drive and channel are not already busy, attention
interrupts are disabled and the transfer is started.
A transfer may range in size from a single word to a whole
cylinder; the longest possible transfer is attempted in order
to maximize I/O throughput. An implied seek is never
attempted in the middle of a transfer. Such a request would
be broken into two or more transfers with explicit
intermediate seeks.
9. When an interrupt occurs, the system may or may not have just
completed a data transfer. Since attention interrupts were
disabled during the data transfer, there may be a number of
outstanding attention conditions when the interrupt is
actually honored.
12-32
DISKS (DSK)
10. First, the system reads the attention summary register.
11. Each drive (except the one which was completing a transfer)
is checked for an attention bit on.
12. If there is an attention bit on, and if there is a seek
complete, the transfer request is added to the channel queue
to be started for I/O.
13. If there was no seek in progress, then the drive has just
come on line or powered up.
14. Once all outstanding seeks are processed, the data transfer
completion is handled.
15. If there was no error, or after error correction, the channel
termination word is compared to the predicted channel
termination word.
16. If the check fails, error recovery is started.
17. After completing the processing for the interrupt, any
outstanding seeks are started. For each drive, the closest
(shortest) seek is the one selected for startup. A fairness
count will cause the system to select the oldest transfer
every nth time.
18. After seeks are started, the channel queue is checked for
positioned drives and the transfer with the shortest latency
is started (again unless the fairness count says otherwise).
SWAPPER requests receive preference over file I/O (unless
fairness count expires).
There is some special processing for interrupts on a MASSBUS
device caused by the fact that the system may be attempting
some operation using the device registers at UUO level at the
time of the interrupt. When the interrupt occurs, the system
reads RHxx and saves the drive and register number to which
the RH was pointing.
19. Before dismissing the interrupt, a DATAO is done to restore
the drive number and register number.
The need for reading the register from the RH at interrupt
and restoring them before dismissing the interrupt is made
worse by the fact that the system must wait 3 microseconds
after the DATAO specifying what data is needed before the
DATAI can read the data.
12-33
DISKS (DSK)
There are other special considerations with the front end disk unit.
In general, both the front end and TOPS-10 may attempt to use the disk
at the same time. The most frequent conflict occurs at system
startup, when the front end is using the disk at the same time that
TOPS-10 is running INITIA on all lines. There is a count of the
number of times that TOPS-10 tries to get to the disk and finds it
busy; this normally rises quickly at system startup to about 40 and
seldom changes thereafter. It is possible to do an assembly on the
front end while timesharing continues on the system, but this may
generate considerable conflict.
When the TOPS-10 system attempts to get the disk and finds that it is
in use by the front end, the requests are delayed and restarted when
the drive is available. Because TOPS-10 may complete a seek for the
front end drive and the front end may grab the disk and rotate it
before the data transfer is started, it is possible that the drive
will not be on the correct cylinder when TOPS-10 tries to start the
transfer. In this case, implied seek will be used since TOPS-10 will
not realize that the cylinder number has changed. This would also
happen if TOPS-10 got two different requests for the same cylinder and
would decide that no seek is necessary when in fact, the front end had
moved the heads.
12.12 DUAL-PORT HANDLING
The dual-port facility is used when the system attempts a data
transfer on one channel and finds it busy. It then tries the other
port. At no other time is the dual-port facility used.
At system startup, the system reads the drive type and serial number
from each drive on all channels. When the same serial number and
drive type is found on two different channels, the disk is determined
to be dual ported. The first path found is designated the primary
path; the second path is the alternate path. When starting a
transfer, the system will attempt to use the primary path. If that
path is busy, it will then check for the alternate path; if that is
available, the transfer is started. Otherwise, the request is placed
in the channel queue for the primary channel.
12.13 ERRORS
There are a number of possible error conditions that can occur while
TOPS-10 attempts to operate the disks. This section lists the error
conditions, the circumstances under which they occur, and the action
taken by the system. In general, the error processing is called as
soon as possible after the error is detected.
12-34
DISKS (DSK)
12.13.1 DATA TRANSFER ERRORS
Data transfer errors are detected on the completion interrupt for a
read or write data transfer. These do not include the software
detected error of the channel termination word not agreeing with the
predicted channel termination word.
12.13.1.1 ECC Correctable Error - When a transfer terminates with an
ECC correctable error, the transfer stops after the sector in error.
The software will reconstruct the data and restart the transfer at the
sector following the sector in error.
12.13.1.2 Non-data Error - When a transfer completes that is not a
data error (for example, a header error) the software will attempt to
retry the transfer a number of times before recording the error as a
hard error. The retry sequence is:
Retry 10 times
Recalibrate
Seek
Retry 10 times
Recalibrate
Seek
Retry 10 times
If the transfer fails after 30 tries the error is considered hard and
an error is returned to the user. The data is recorded by DAEMON in
ERROR.SYS and the number of hard errors for this device is
incremented.
If the count of hard errors reaches a system default, a message is
given to the operator saying that there has been an excessive number
of hard errors and the count is zeroed. The expectation is that the
operator may want to set some hardware offline or call his field
service representative to run diagnostics.
12.13.1.3 Data Error - If a data error (including header compare
error) occurs which is not ECC correctable, then the system will retry
the transfer and will use the offset register to vary the head
position on each side of the track centerline. The retry sequence is:
Retry 16 times on centerline
Offset head to +200 microinches
Retry 2 times
Offset head to -200 microinches
Retry 2 times
12-35
DISKS (DSK)
Offset head to +400 microinches
Retry 2 times
Offset head to -400 microinches
Retry 2 times
Offset head to +600 microinches
Retry 2 times
Offset head to -600 microinches
Retry 2 times
Return to centerline
Retry disabling stop on error
Retry
Every retry except the next to last is done with stop on error
enabled. This enables a maximum amount of information to be recorded
in ERROR.SYS.
For an RP04 the offset distances are twice the above. If the transfer
is recovered at the offset position, the drive is left positioned at
offset. If the next transfer on that drive is for that cylinder, it
is first to be attempted at the same offset. If that fails, the head
is returned to centerline and the entire above sequence is tried. If
any seek is done, the heads will be on centerline (including transfers
which cause the head to return to the cylinder on which an error was
recovered at offset). If the device is not an RP04 or RP06 (MASSBUS
drive), the error recovery is 10 retries of the sequence: read/write
10 times, recalibrate, seek.
On a hard non-recoverable error, an error is returned to the user and
the system remembers the block number in error. When the file is
subsequently closed, the system checks for a remembered block number.
It starts reading from the bad block number+1 until it finds a good
sector (or 1000 sectors whichever is smaller). This gives the extent
of the error region, which is then recorded in both the RIB of the
file and the BAT block. If the program does not close the file after
the error, but continues processing and hits a second error, the
second error is lost.
12.13.2 SEEK AND STATUS ERRORS
In the attention summary register, on an interrupt, there may be
attention interrupts for drives that were not transferring or seeking.
In this case the drive is going through some sort of status change,
such as coming on line or going down.
12.13.2.1 Drive Powered Down - If medium-on-line (MOL) is 0, the
drive has just powered down. It is marked as such in the monitor
tables.
12-36
DISKS (DSK)
12.13.2.2 Drive Powered Up - If medium-on-line (MOL) is 1 and volume
valid (VV) is 0, then the drive has just powered up. The monitor will
read the home blocks and check that the pack is the expected pack on
that drive.
12.13.2.3 Seek Incomplete - On all seek errors, the error is counted
and ignored. This will cause the data transfer to use the implied
seek facility to perform the actual seek. If that implied seek fails,
the data transfer will return an error and the appropriate retry
sequence will be started.
12.13.2.4 Hung Device - Any time a seek or data transfer is started,
the monitor starts an independent hung timer that will fire in 7
seconds if the device has not responded with a completion interrupt
for the operation.
If the failing request was a seek, then it is retried. If it was a
data transfer, the monitor does a CONO to clear BUSY and set DONE.
After this, the appropriate retry sequence for a data error is
started. If 8 hung retries in a row fail, the monitor will set the
drive offline and tell the operator that it is offline (message is
Inconsistent Status for Drive x).
12.13.2.5 Rib Errors - Every RIB error detected (along with every n
hard errors) is reported to the operator.
12.13.2.6 RAE Errors - On an RH10, Register Access Error (RAE) is
ignored. The hardware will set the Selected Drive RAE at which point
error recovery is started.
On the RH20, after every DATAO, a CONSZ on RAE is done, if there was
an RAE, then it is cleared and the DATAO is retried. There is also a
system count of RAE's per controller for the RH20's.
12-37
DISKS (DSK)
12.14 BAT BLOCKS
The BAT blocks provide a record of up to 63 errors on the disk. After
each detected error, the monitor will update the BAT blocks with the
blocks in error and the type of error encountered. It is possible
that the BAT blocks will be filled to overflowing and there will be no
room for additional entries. The system will leave bad blocks marked
as allocated in the SAT table and thus avoid reallocating them. SPEAR
will notify the user when there are less than 5 entries remaining in
the BAT block.
12.15 DSKRAT
DSKRAT is a program that can be run to check for RIB errors and the
disk space allocated as reported in the SAT table with the allocation
as reported by the RIBs of the files on the pack. In general, it will
find four kinds of errors:
o RIB errors. A RIB is not consistent in format with a valid
RIB.
o Lost blocks. Blocks that are marked as allocated in the SAT
but are not a part of any file.
o Free blocks. Blocks that are owned by some file on the
system but are not marked as allocated in the SAT table. If
one of these files is deleted, a BAZ STOPCD results.
o Multiply Defined blocks. Blocks that are marked as owned in
two or more files.
The safest procedure when a disk has significant problems in terms of
free or multiply defined blocks is to BACKUP the pack, refresh it, and
restore it.
12.16 DISK DATA MODES
Data transfers to and from disk can be made in buffered mode or dump
mode.
12-38
DISKS (DSK)
12.17 DETERMINING THE PHYSICAL ADDRESS OF A BLOCK WITHIN A DISK FILE
The following procedure allows a non-privileged program to find the
physical block number corresponding to a relative block, R, in a file.
1. Read the HOME block. For the desired unit:
LOOKUP HOME.SYS[1,4]
Read the file until a block whose first word is SIXBIT 'HOM'
is found. This should be block N + 1, where N is the number
of blocks per cluster.
2. Save the following words:
10 HOMLUN - Logical unit number within the structure.
16 HOMCNP - Count-pointer for retrieval pointers.
20 HOMCLP - Address-pointer for retrieval pointers.
21 HOMBPC - Blocks per cluster.
3. Read the First RIB of the File.
LOOKUP FILE.EXT
USETI 0
INPUT
Note: If writing, the file should be in UPDATE mode. Write
it once, then CLOSE, LOOKUP, ENTER. Otherwise, the Retrieval
Information Block (RIB) will not be written on the disk.
4. Scan the First RIB for the Relative Block, R. Retrieval
pointers start at relative word N of the RIB, where
N = RH (word 0).
Start with BASE=0.
o If you find a retrieval pointer that equals 0, you have
made an error.
o If you find a pointer that equals XWD 0,400000 + n you
have found a "unit-change-pointer". The following
retrieval pointers, until another unit-change is found,
refer to unit n, where n is the relative unit within the
file structure of the unit (for example, DSKBn). All
RIBs start with a unit-change-pointer as the first
retrieval pointer.
12-39
DISKS (DSK)
o If you find a pointer with LH non-0, then:
The number of blocks described by this pointer is equal
to L, where L is equal to HOMBPC * K, and K is obtained
by an LDB c(HOMCNP). If BASE is equal to or less than R,
which is less than BASE + L, you have found the pointer.
Otherwise, if BASE is equal to BASE + L, try the next
pointer.
If the next pointer equals XWD 0,-1, the block you are
looking for is not in this RIB. To read the next RIB:
USETI -n (n = 2 to read the 2nd RIB, and so on.)
INPUT
Set BASE equal to the contents of Word 33 of the RIB and
scan this RIB as described above.
You are successful if the physical address equals
R - BASE+J, where J is obtained from an
LDB c(HOMCNP) * HOMBPC. The unit on which the block
resides is found from the last unit-change pointer. It
should be the same as HOMLUN.
The following program shows how to find the physical block number that
corresponds to a relative block in a file.
TITLE FNDBLK
;THIS PROGRAM FINDS OUT THE PHYSICAL BLOCK NUMBER
;CORRESPONDING TO BLOCK ^D1153 IN FILE FOO
ST: RESET
INIT 14
SIXBIT /DSK/
HOMHDR
HALT
LOOKUP HOMBLK
HALT
HOMLUP: INPUT
ILDB 1,HOMHDR+1
CAME 1,['HOM ']
JRST HOMLUP
;FOUND THE HOME BLOCK
HRRZ 1,HOMHDR+1
MOVE 2,10(1) ;HOMLUN
MOVEM 2,LUN
MOVE 2,16(1) ;COUNT-FIELD PNTR
HLLM 2,CNP
MOVE 2,20(1) ;ADDRESS-FIELD PNTR
HLLM 2,CLP
MOVE 10,21(1) ;BLOCKS PER CLUSTER
RELEASE
12-40
DISKS (DSK)
;READ THE PRIME RIB OF FILE 'FOO'
INIT 14
SIXBIT /DSK/
RIBHDR
HALT
LOOKUP FOO
HALT
USETI 0
INPUT
SETOM RIB ;INDICATE WE JUST READ
;THE PRIME RIB(-1)
;FIND THE RETRIEVAL POINTERS
ILDB 1,RIBHDR+1 ;RH=LOC OF POINTERS
ADD 1,RIBHDR+1 ;1=LOC OF 1ST POINTER
MOVE 2,(1) ;SHOULD BE A UNIT-CHANGE
TRZ 2,400000 ;1ST UNIT (WITHIN STR)
;OF FILE
ADDI 1,1 ;POINT TO 1ST REAL
;POINTER
SETZ 3, ;3 IS BASE ADR. OF THE
;POINTER
HLL 1,CNP ;1 IS A POINTER TO
;POINTER COUNTS
LOOP: LDB 4,1 ;COUNT FIELD
IMULI 4,(10) ;TIME NUMBER OF BLOCKS
;PER CLUSTER
ADD 4,3 ;TOP ADR+1 OF PNTR
CAIG 3,^D1153 ;IS 1153 PAST START
;OF PNTR
CAIG 4,^D1153 ; AND NOT PAST END
SKIPA 3,4 ;NO, SET 3=START OF NEXT
;POINTER
JRST FOUND ;FOUND THE POINTER
ADDI 1,1 ;STEP TO NEXT POINTER
SKIPN 4,(1) ;IS THERE ONE?
HALT ;THAT'S TOO BAD
CAIN 4,-1 ;PICKED UP RIBCOD WORD?
JRST NXTRIB ;YES, PROPER POINTER IS
;PROBABLY IN EXTENDED RIB
TLNE 4,-1 ;IS IT A UNIT-CHANGE?
JRST LOOP ;NO, SEE IF IT'S THE
;RIGHT ONE
TRZ 4,400000 ;ZAP THE EXTRA BIT
MOVE 2,4 ;AND SAVE THE UNIT NUMBER
;IN 2
12-41
DISKS (DSK)
;HERE TO READ THE NEXT RIB FOR FILE 'FOO'
NXTRIB: SOS 5,RIB ;POINT TO NEXT RIB
USETI 0(5) ;USETI TO NTH RIB
INPUT
ILDB 1,RIBHDR+1 ;RH = OFFSET OF POINTERS
MOVE 6,RIBHDR+1 ;START OF DATA BLOC
MOV 3,33(6) ;SET BASE TO BASE OF THIS
;RIB
ADD 1,RIBHDR+1 ;1=LOC OF FIRTS POINTER,
;THIS RIB
MOVE 2,(1) ;GET THE FIRST POINTER
HLL 1,CNP ;1 IS A POINTER TO
;POINTER COUNTS
JRST LOOP ;NOW GO SCAN THIS RIB
FOUND: CAME 2,LUN ;IS IT THE RIGHT UNIT?
HALT ;NO
HLL 1,CLP ;YES, SET TO
;ADDRESS-POINTER
LDB 4,1
IMULI 4,(10) ;1ST BLOCK DESCRIBED BY
;POINTER
SUBI 3,^D1153 ;DISTANCE FROM START
;OF POINTER
SUB 4,3 ;4 CONTAINS THE PHYSICAL
;BLOCK!!!!!
EXIT
;STORAGE
HOMHDR: BLOCK 3
RIBHDR: BLOCK 3
HOMBLK: SIXBIT /HOME/
SIXBIT /SYS/
0
XWD 1,4
FOO: SIXBIT /FOO/
0
0
0
RIB: 0
CLP: 0
CNP: 0
LUN: 0
END ST
12-42
DISKS (DSK)
12.17.1 Buffered Modes
The buffer size for all buffered-mode disk transfers is 203 (octal)
words: 3 header words and 200 data words. The monitor always assumes
this buffer size, even if you have mistakenly used smaller or larger
buffers in your program. Thus, if you use a smaller buffer, the
monitor reads past the end of the buffer (for example, into the header
and data of the next buffer), thus destroying that data. By using the
SET BIGBUF command, you can enable larger buffers for disk I/O. With
big buffers, your program transmits and receives disk I/O in multiples
of 200 words. For example, the command:
.SET BIGBUF 3
will result in 603 (octal) words: a 3-word header and 3*200=600 data
words.
The buffered data modes that you can use for disk transfers are:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
10 .IOIMG Image mode.
13 .IOIBN Image binary mode.
14 .IOBIN Binary mode.
All of these data modes are transferred without processing by the
monitor.
12.17.2 Dump Modes
In dump modes, data can be read from or written into any locations in
your user memory area. For output to disk from user memory, the
disk-service routine uses disk space in increments of 200 (octal)
words, filling the last 200-word block with zeros if necessary.
The dump data modes that you can use for disk transfers are:
Code Symbol Meaning
16 .IODPR Dump record mode.
17 .IODMP Dump mode.
12-43
DISKS (DSK)
12.18 DISK I/O STATUS
I/O status bits for disk are as follows:
Bits Symbol Meaning
18-21 IO.ERR Error flags:
Flag Symbol Error
18 IO.IMP Attempt to write on software
write-locked file structure or
software redundancy failure
occurred.
19 IO.DER Error detected by device.
20 IO.DTE Hard data error.
21 IO.BKT Block too large.
22 IO.EOF End of file.
23 IO.ACT Device active.
29 IO.WHD Write disk pack headers.
30 IO.SYN Synchronous I/O.
32-35 IO.MOD Data mode:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
10 .IOIMG Image mode.
13 .IOIBN Image binary mode.
14 .IOBIN Binary mode.
16 .IODPR Dump record mode.
17 .IODMP Dump mode.
12-44
CHAPTER 13
DECTAPES (DTA)
A DECtape device reads and writes a DECtape. It is a sequential
device, and has a directory. The tape is 260 feet (79.24 m) long and
10 tracks wide.
13.1 DECTAPE DEVICE NAMES
The physical name of a DECtape unit is of the form:
DTcu
Where: c is either Controller A or Controller B.
u is the unit number in the range 0 to 7.
A CPU may have up to two DECtape controllers. The name of the DECtape
controller is TD10.
The unit name of the DECtape device is either TU55 or TU56.
13.2 DECTAPE DATA MODES
A DECtape device can be operated in any of the following data modes:
o Buffered modes: ASCII, ASCII line, image, image binary, and
binary.
o Unbuffered data modes: dump record and dump.
o Nonstandard data mode.
o Semistandard data mode.
13-1
DECTAPES (DTA)
13.2.1 Buffered Data Modes
The buffered data modes (ASCII, ASCII line, image, image binary, and
binary) use buffers of 200 (octal) data words. Data is transferred
between the DECtape device and memory without change. Checksumming is
performed by the DECtape service routine.
In buffered mode, the buffers are 200 (octal) words long, but data is
still in blocks of 177 (octal) words (see Figure 13-1).
---------------------
(Word 202).BFSTS | |
|-------------------|
(Word 201).BFHDR | |
|-------------------| \
.BFCNT | ^ | \
/ |---------|---------| |
/ | | | |
| | | | |
| | 200 Words | /
\ | (octal) | > Read/Written
177 Words < | Read from | \ from Tape
(octal) / | Tape | |
| | | | |
| | | | |
\ | V | /
\ --------------------- /
Figure 13-1: DECtape Buffer
The first word in the buffer (.BFCNT) is the link pointer directly to
the tape. Ususally, the monitor passes over this word. Programs that
require .BFCNT may read it using buffered I/O mode.
13.2.2 Unbuffered Data Modes
The unbuffered data modes (dump record and dump) use command lists to
transfer data between DECtape and memory. The I/O monitor call (IN,
INPUT, OUT, or OUTPUT) gives the address of the command list.
Each word of the command list is in one of the following forms:
IOWD buflength,buffer
XWD 0,nextcmd
Z
13-2
DECTAPES (DTA)
Where:
In the IOWD instruction:
buflength is the number of words to be transferred.
buffer is the address for reading or writing the data; in the
XWD instruction.
nextcmd is the address of the next command in the list.
Z (zero) word ends the command list.
File-structured dump mode data is blocked into standard DECtape blocks
by the DECtape service routine. Each block read or written contains a
link word and 177 (octal) data words. On output, if the data does not
fill the last block, it is left blank. On input, your program must
read only the words that were written, skipping these blank words.
13.2.3 Nonstandard Data Mode
Your program selects nonstandard DECtape data mode by setting bit
IO.NSD in the I/O status word (using the SETSTS monitor call). In
nonstandard mode, the monitor does not perform file-structuring
operations on the data. The monitor reads and writes each block
sequentially, but it does not generate links on output, nor does it
recognize links on input.
Nonstandard mode treats link words on the DECtape as data words;
therefore a data block is up to 200 (octal) words, and your program
must select the block to be read or written by using the USETI or
USETO monitor call.
A LOOKUP, ENTER, or UTPCLR monitor call to a DECtape device in
nonstandard mode is a no-op. Your program is prohibited from reading
or writing Block 0 of the tape in dump mode, because this block cannot
be read or written in a forward direction.
The monitor checks block numbers for validity, but does not perform
dead-reckoning computations for the requested blocks (because a block
may be shorter than 200 words).
13.2.4 Semistandard Data Mode
Semistandard mode allows you to specify block numbers greater than
1101 (octal). It is useful for DECtapes formatted on machines other
than DECsystem-10s, for example, a PDP-8. The block size of such
tapes might not be 200 words; therefore, semistandard mode does not
limit the tape to 578 blocks of data.
13-3
DECTAPES (DTA)
To select semistandard mode, your program must set both the IO.SSD and
IO.NSD bits in the I/O status word (using the SETSTS monitor call).
Semistandard mode is identical to nonstandard mode, except that the
monitor:
o Checks block numbers to determine position.
o Starts the tape in the same direction it last went.
o Performs dead-reckoning computations for the requested
blocks. (Refer to Section 13.3.)
13.3 DECTAPE I/O
On the first LOOKUP, ENTER, or UGETF call to a DECtape device, the
DECtape service routine reads the directory into memory. The
directory is maintained and updated in memory until the device channel
is released by a RELEAS monitor call; at that time the directory is
copied to the DECtape.
When you change DECtapes on a DECtape device, you should issue an
ASSIGN command to inform the monitor that a new tape is on the device;
otherwise, the wrong directory may be copied onto the tape.
If you use monitor calls (USETI and USETO) to position a DECtape, the
monitor uses dead reckoning to locate the correct block on the tape.
This means that the service routine begins turning the tape and
estimates the time needed to reach the block; it then performs
services for other users. Just before the estimated time has passed,
the routine checks to see if the block has been reached.
If your program attempts to write on a write-locked tape, or to access
a DECtape device that has no tape on it, the monitor stops your job
and prints (on the terminal) the message:
DEVICE DTcu OPERATOR ACTION REQUESTED
Where: c is the controller designation A or B.
u is the unit number.
When the problem is corrected, you can use the CONTINUE command to
resume the job (unless an explicit or implicit RESET has been issued
for the program).
Your program can initialize a DECtape device on only one channel.
Input and output occur on this channel; however, they do not occur
simultaneously.
13-4
DECTAPES (DTA)
Because a DECtape is a directory device, your program must select a
file before it can perform I/O to the DECtape. To select a file on a
DECtape, use one of the following calls: LOOKUP, ENTER, USETI, USETO,
UGETF, or a function of the FILOP. call.
13.3.1 Monitor Calls for DECtape I/O
The monitor calls of greatest interest in using DECtapes are:
CLOSE Closes the DECtape file.
ENTER Creates, writes, supersedes, or (after a LOOKUP)
appends to a DECtape file. The special DECtape
argument list for the ENTER call is described in
Section 13.3.2.
FILOP. Performs various DECtape functions.
IN,INPUT Performs normal input from the DECtape, except
that the DECtape service routine reads the link in
each block to determine the next block to read,
and to determine when to set the end-of-file flag
(IO.EOF) in the file status word.
LOOKUP Selects a file for input. The LOOKUP call can be
used in deleting, reading, updating, renaming, or
appending to a file.
A LOOKUP call to a DECtape device uses the special
LOOKUP argument list. For more information, refer
to Section 13.3.2.
MTREW. Rewinds the DECtape. This function is also
available with the FILOP. call, function .FOMTP.
MTUNL. Rewinds and unloads the DECtape. This function is
also available with the FILOP. call, function
.FOMTP.
OUT,OUTPUT Performs output to the DECtape device. The buffer
control block is processed as follows:
If the left half of word 2 of the buffer control
block contains -1, the DECtape service routine
changes it to 0, thereby terminating the file. If
the halfword is positive, the routine uses the
value as the block number for the next OUT or
OUTPUT call. If the halfword is 0, the routine
assigns the block number for the next OUT or
OUTPUT call.
13-5
DECTAPES (DTA)
RELEAS Releases the DECtape channel. The monitor copies
its directory for the DECtape (maintained in
memory) to the DECtape. Commands that issue
implicit RELEAS calls (for example, KJOB) also
copy the directory to the DECtape.
RENAME Renames or deletes the DECtape file. A RENAME
call to a DECtape device uses a special argument
list for the call. You provide the file name,
extension, and creation date. The argument list
is described in Section 13.3.2.
UGETF Returns the next free block of the DECtape. If no
ENTER or LOOKUP precedes the UGETF call, the
monitor returns -1 in the first word of the
argument list. If an ENTER or LOOKUP precedes the
UGETF call, the monitor returns the first free
block nearest the beginning of the tape (instead
of nearest the directory). The monitor also
changes the spacing factor from four to two. The
spacing factor separates blocks, allowing tape to
stop and then restart without having to back up.
This function is also available with the
FILOP. function .FOGTF.
USETI Sets the DECtape to the specified block number for
next input. To assure that the buffer containing
the block number is the next one used for input,
either use a single buffer or set the IO.SYN bit
in the I/O status word (using SETSTS). This
forces the monitor to stop after each IN or INPUT
call.
USETO Sets the DECtape to the specified block number for
next output. To assure that the buffer containing
the block number is the next one used for output,
either use a single buffer or set the IO.SYN bit
in the I/O status word (using SETSTS). This
forces the monitor to stop after each OUT or
OUTPUT call.
NOTE
USETI/USETO calls do not operate with
DECtape the same way as they do with disk.
On disk, USETO n puts you at block n in
the file, regardless of the block's actual
position on the disk. On DECtape, USETO n
puts you at block n on the tape,
regardless of the file that contains that
block.
13-6
DECTAPES (DTA)
UTPCLR Clears the DECtape directory. This function is
also available with FILOP. function .FOUTP.
On each interrupt, the monitor updates the device status word for the
DECtape; use the DEVSTS monitor call to retrieve the status.
13.3.2 Special Argument Lists
The LOOKUP, ENTER, and RENAME monitor calls for a DECtape device use
special formats for the argument list for the call.
13.3.2.1 Using LOOKUP with DECtapes - The LOOKUP call selects a file
for input. It is used in the process of deleting, reading, changing,
renaming, or appending to a file. The calling sequence for a LOOKUP
to a DECtape file is:
LOOKUP channo,addr
error return
normal return
addr: SIXBIT/filename/
SIXBIT/extension/
0
0
Where: LOOKUP call accepts a channel number (channo) and the address
of the argument list (addr). The information you must provide
and the information returned in the argument block is listed
in Table 13-1. The LOOKUP monitor call sets up an input file
(specified by filename and extension in the the argument
block) on the specified I/O channel. (Note that you must
initialize the channel first, using the OPEN call.)
NOTE
The LOOKUP/ENTER extended argument list can be used
with DECtapes. Refer to Chapter 11.
The contents of the argument block are matched against the file names
and extensions in the DECtape directory. If the monitor does not find
a match, the error return is taken and the monitor returns an error
code in the right half of addr+1. The error codes are described in
Chapter 11. If the file name is matched, the normal return is taken,
and the information listed in Table 13-1 is returned in the argument
block.
13-7
DECTAPES (DTA)
Table 13-1: LOOKUP/ENTER/RENAME Argument Block for DECtape
______________________________________________________________________
Word Bits Contents LOOKUP ENTER RENAME
______________________________________________________________________
0 0 - 35 SIXBIT/filename/ A A A
1 0 - 17 SIXBIT/extension/ A A A
18 - 20 High-order 3 bits of V A0 A0
the creation date.
21 - 25 Zero
26 - 35 First block number. V V V
2 0 - 23 Zero.
24 - 35 Low-order 12 bits of V A0 A0
the creation date.
3 0 - 17 Negative word length V - -
of the zero-compressed
file.
18 - 35 Core address of the - - -
first word of the file
minus 1 (obsolete).
______________________________________________________________________
A = argument in your program
V = value returned from the monitor
I = ignored.
______________________________________________________________________
On a normal return, the first block of the file is found as follows:
o The first 83 words in the DECtape directory block are
searched backwards, beginning with the slot immediately
before the slot pointing to the directory block. The search
procedure stops when the slot containing the desired file
number is found.
o The block associated with this slot is read; bits 18-27 of
the block's first word (the bits containing the block number
of the first block of the file) are checked. If the bits are
equal to the block number of this block, then this block is
the first block; if not, then the block with that block
number is read as the first block of the file.
13-8
DECTAPES (DTA)
13.3.2.2 Using ENTER with DECtapes - The ENTER call selects a file
for output. It is used in the process of creating, writing, appending
to, and superseding files.
The calling sequence for the ENTER call for DECtapes is:
ENTER channo,addr
error return
normal return
Where: addr is the address of the argument block, described in Table
13-1.
The ENTER call requires the channel number (channo) and address of the
argument list (addr). The argument list, the information you must
supply, and the information returned by the monitor, are listed in
Table 13-1. If you specify an extended argument list, the monitor
ignores the extra words and leaves them unchanged.
The monitor searches the DECtape directory for the specified file name
and file extension. If the monitor does not find a match, and there
is room in the directory, the monitor records information in the
DECtape directory. If the monitor finds a match, the specified entry
replaces the old entry and the old file is reclaimed immediately. The
monitor then records the file information in the DECtape directory.
When the monitor replaces an existing file with a new file, it is
superseding a file. Superseding a file on DECtape differs from
superseding a file on disk. On DECtape, because of its small size,
the space is reclaimed before the file is written instead of after the
file is written. That is, once the ENTER has been performed, the old
file is deleted.
13.3.2.3 Using RENAME with DECtapes - The RENAME call changes the
file name or file extension of a file, or deletes it from the DECtape.
For use with DECtapes, the RENAME calling sequence is:
RENAME channo,addr
error return
normal return
In the calling sequence, RENAME requires a channel number (channo) and
the address of the argument list (addr). If you specify an extended
argument list (longer than 4 words) the extra words are ignored and
left unchanged. Table 13-1 lists the contents of the argument list
before the call and after a successful return by the monitor.
13-9
DECTAPES (DTA)
Unlike a RENAME on a disk device, a RENAME on DECtape works on the
last file selected (using LOOKUP or ENTER) on the device, not the last
file on the specified channel. The calling sequence required to
successfully RENAME a file on DECtape is:
LOOKUP channo,addr
RENAME channo,addr1
or
ENTER channo,addr
RENAME channo,addr1
13.4 DECTAPE FORMATS
A DECtape is 260 feet (79.24 m) long and 10 tracks wide. The monitor
views the tape as having 577 decimal blocks, numbered from 0 to 1101
(octal). Blocks 1 and 2 are reserved for the bootstrap loader. Block
100 (decimal) is the directory block. The directory contains up to 22
(decimal) files.
Each block of a DECtape can contain 128 36-bit words; the entire tape
can contain 73,856 words.
Reserved User Data User Data
/------^------\ /--------^-------\ /-----------^------------\
----------------------- --------------------- --------------
|Block | Block | Block / / Block | Block | Block / / Block | Block|
|1 | 2 | 3 / / 99 | 100 | 101 / / 576 | 577 |
----------------------- --------------------- --------------
\-----/
Directory
Block
Figure 13-2: DECtape Format
13-10
DECTAPES (DTA)
Blocks on a DECtape (see Figure 13-2) are used as follows (block
numbers in decimal):
Block Use
0 Not used. May be read in buffered I/O mode.
1-2 Reserved for bootstrap loader
3-99 Data
100 Directory
101-577 Data
If your program requests a block number larger than 577, the monitor
sets the IO.BKT bit in the I/O status word.
13.4.1 Directory Format
The directory block is block number 100 (decimal) and is 128 decimal
words long.
A DECtape directory contains the following:
1. A block-to-file index, showing which blocks belong to which
files.
2. A list of file names.
3. A list of file extensions.
4. A list of file creation dates.
5. A DECtape label.
Note that, unlike disk files, DECtape files do not have protection
codes associated with them.
13-11
DECTAPES (DTA)
13.4.1.1 Summary of DECtape Directory Block - Figure 13-3 is a
summary of the DECtape directory block. For example, if block number
14 contained file number 10, which was named FILE.MAC, the directory
would appear as shown in Figure 13-4.
0 35
----------------------------------------------------
Word 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |
|------+------+------+------+------+------+------+-|
Word 1 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | |
|------+------+------+------+------+------+------+-|
Word 2 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | |
----------------------------------------------------
.
83 Words .
----------------------------------------------------
Word 65 | 456 | 457 | 458 | 459 | 460 | 461 | 462 | |
|------+------+------+------+------+------+------+-|
Word 66 | 463 | 464 | 465 | 466 | 467 | 468 | 469 | |
----------------------------------------------------
.
.
----------------------------------------------------
Word 81 | 568 | 569 | 570 | 571 | 572 | 573 | 574 | |
|------+------+------+------+------+------+------+-|
Word 82 | 575 | 576 | 577 | -- | -- | -- | -- | |
|------+------+------+------+------+------+------+-|
Word 83 | File name for File 1 |
|--------------------------------------------------|
Word 84 | File name for File 2 |
----------------------------------------------------
.
22 Words .
----------------------------------------------------
Word 104 | File name for File 22 |
|----------------+---------------+-----------------|
Word 105 | Extension | 0 | Creation Date |
|----------------+---------------+-----------------|
Word 106 | Extension | 0 | Creation Date |
----------------------------------------------------
22 Words .
.
----------------------------------------------------
Word 126 | Extension | 0 | Creation Date |
|----------------+---------------+-----------------|
Word 127 | Tape Label |
----------------------------------------------------
1 Word
Figure 13-3: DECtape Directory Block
13-12
DECTAPES (DTA)
0 35
---------------------------------------------
Word 0 | | | | | | | | |
|-----+-----+-----+-----+-----+-----+-----+-|
Word 1 | | | | | | | 10 | |
|-----+-----+-----+-----+-----+-----+-----+-|
Word 2 | | | | | | | | |
---------------------------------------------
.
.
.
---------------------------------------------
Word 92 | File | : in SIXBIT
---------------------------------------------
.
.
.
---------------------------------------------
Word 114 | MAC | 0 | Date |
---------------------------------------------
Bit 35 of Words 9, 31, and 53 Contain the
High-Order Three Bits of the Creation Date
Figure 13-4: Directory Block for FILE.MAC
13-13
DECTAPES (DTA)
13.4.1.2 Block-to-File Index - The block-to-file index is in the
first 83 words of the directory, words 0 through 82 (see Figure 13-5).
Each word contains seven 5-bit file numbers; bit 35 is used otherwise
(see creation dates).
/------ For example, Slot for Block 3
|
|
F / 0 4 5 9 10|14 15 19 20 24 25 29 30 34 35
i | ---------------V----------------------------- -\
r | Word 0 | * | * | 3 | 4 | 5 | 6 | 7 | | |
s | |-----+-----+-----+-----+-----+-----+-----+-| | Hi-
t | Word 1 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | | | order
| |-----+-----+-----+-----+-----+-----+-----+-| / Bit
8 | Word 2 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | | > of
3 | --------------------------------------------- \ Creation
| | Date
W | |
o \ --------------------------------------------- |
r < Word 65 | 456 | 457 | 458 | 459 | 460 | 461 | 462 | | -/
d / |-----+-----+-----+-----+-----+-----+-----+-|
s | Word 66 | 463 | 464 | 465 | 466 | 467 | 468 | 469 | | -\
| --------------------------------------------- |
o | |
f | /
| --------------------------------------------- > Unused
B | Word 81 | 568 | 569 | 570 | 571 | 572 | 573 | 574 | | \
l | |-----+-----+-----+-----+-----+-----+-----+-| |
o | Word 82 | 575 | 576 | 577 | ** | ** | ** | ** | | |
c \ --------------------------------------------- -/
k
110 (Decimal) * Reserved Blocks
** Non-existent Blocks
Figure 13-5: First 83 Words on the DECtape of the Directory Block
Each file number in the block-to-file index shows which file owns the
corresponding block. For example, the third file number (third byte
of directory word 0) indicates that block 3 of the DECtape contains
part of the given file. The 11th file number (fourth byte of
directory word 1) indicates that block 11 of the DECtape contains part
of the given file.
13-14
DECTAPES (DTA)
Note that while a five-bit byte can represent 32 files, there are only
22 files. Code 30 is stored in the byte corresponding to the
directory block, and code 31 is stored in bytes corresponding to
blocks 1, 2, and 578-581. Thus all bytes with 0 on them represent
real, existing, valid-to-use, free blocks on the tape. Codes 23-29
are reserved.
Blocks 1, 2, and 100 are not used because they are reserved blocks;
blocks 578 through 581 are not used because these blocks do not exist.
13.4.1.3 List of File Names - The list of file names is in words 83
through 104 of the directory (see Figure 13-6). Each word contains
the SIXBIT name of a file on the DECtape. This list is the key to the
block-to-file index in the directory. A block having the file number
4 in the block-to-file index belongs to the file listed fourth in the
list of file names.
0 35
----------------------------------------------
Word 83 | SIXBIT/Name/for File 1 |
|--------------------------------------------|
Word 84 | SIXBIT/Name/for File 3 |
----------------------------------------------
.
.
.
----------------------------------------------
Word 104 | SIXBIT/Name/for File 22 |
----------------------------------------------
Figure 13-6: Words 83 through 104 of DECtape Directory
13-15
DECTAPES (DTA)
13.4.1.4 List of File Extensions - The list of file extensions is in
the left halves of words 105 through 126 of the directory (see Figure
13-7). The first extension is for the first file name in the list of
file names, and so forth.
0 17 18 23 24 35
----------------------------------------------
Word 105 | Extension | 0 | Creation Date |
|----------------+---------+-----------------|
Word 106 | Extension | 0 | Creation Date |
----------------------------------------------
.
.
.
----------------------------------------------
Word 126 | Extension | 0 | Creation Date |
----------------------------------------------
Figure 13-7: Words 105 to 126 of the Directory Block
13-16
DECTAPES (DTA)
13.4.1.5 File Creation Dates - The low-order 12 bits of the creation
date for each file is in bits 24 through 35 of the same word
containing the extension for the file. The high-order 3 bits of the
creation dates are stored in the last bits of words 0 through 82 of
the directory (see Figure 13-8).
Bit 35 of
|
V
/-- Word 0 --\
/---|-- Word 1 --|---\
/---|---|-- Word 2 | |
F | F | F | Word 3 | |
i | i | i | . | |
l | l | l | . | |
e | e | e | . | <------ High Order
| | | . | | Bits for
3 | 2 | 1 | . | | File 1
| | | Word 19 | |
/---|---|---|-- Word 20 | |
/---|---|---|---|-- Word 21 --|---|---\
F | F | | | | Word 22 --|---* |
i | i | | | *-- Word 23 --* | |
l | l | | *---|-- Word 24 | | |
e | e | *---|---|-- . | | |
| | | | | . | | <------- High Order
2 | 2 | | | | . | | | Bits for
2 | 1 | | | | Word 41 | | | File 2
| *---|---|---|-- Word 42 | | |
*---|---|---|---|-- Word 43 --|---|---*
| | | | \-- Word 44 --/ | |
| | | \------ Word 45 ------/ |
| | \---------- Word 46 | <------------ High Order
| | . | Bits for
| | . | File 22
| | . |
| | Word 63 |
| \-------------- Word 64 |
\------------------ Word 65 ----------/
Figure 13-8: High-Order Three Bits of Creation Date
13-17
DECTAPES (DTA)
Note that bits 18-23 are apparently free. These bits are not free,
however. Old DECtape formats used these as the amount of memory
needed to hold the .SAV file (meaningless for non-.SAV files). Thus,
because of old tapes, these bits cannot be reused.
For example, the 15-bit creation date for the first file is stored as
follows:
Bits Stored
1 Bit 35 of directory word 0
2 Bit 35 of directory word 22
3 Bit 35 of directory word 44
4-15 Bits 24-35 of directory word 105
More generally, the 15-bit creation date for file number n is stored
as follows:
Bits Stored
1 Bit 35 of directory word n-1
2 Bit 35 of directory word n+21
3 Bit 35 of directory word n+43
4-15 Bits 24-35 of directory word n+104
13.4.1.6 DECtape Label - A SIXBIT label for the DECtape is stored in
word 127 of the directory.
13-18
DECTAPES (DTA)
13.4.2 Data Block Format
A data block on a DECtape (see Figure 13-9) has a link word and up to
127 (decimal) data words. All user data blocks on a DECtape have this
format. The link word is in the format:
0 17 18 27 28 35
----------------------------------------------
Word 0 | Link | Block # | Word Count |
|----------------+----------+----------------|
Word 1 | |
----------------------------------------------
.
.
.
----------------------------------------------
Word N | Data |
----------------------------------------------
Figure 13-9: Data Block Format
Bits Contents
0-17 Block number of next block in file.
18-27 Block number of first block in file.
28-35 Number of data words in block.
If Bits 0 through 17 contain 0, the current block is the last in the
file.
The DECtape service routine allocates the first free block that is
before and closest to the directory block; that is, the routine begins
reading backwards at block 99 and allocates the first free block it
finds. When the routine encounters the end of the tape, it reverses
direction.
The DECtape service routine does not write blocks contiguously; each
allocated block is separated by a spacing factor, which allows the
tape to stop and start again without having to back up. The spacing
factor is normally four blocks; if your program uses dump mode and
issues a UGETF monitor call followed by an ENTER call, the spacing
factor is set to two.
13-19
DECTAPES (DTA)
13.5 DECTAPE I/O STATUS
The I/O status bits for DECtape are as follows:
Bits Symbol Meaning
18-21 IO.ERR Error flags:
Flag Symbol Error
18 IO.IMP Tape being read/written in improper
mode.
19 IO.DER Data was missed on the tape.
20 IO.DTE Parity error.
21 IO.BKT Block too large or too small, or
the tape was full when the OUT or
OUTPUT call was issued.
22 IO.EOF End-of-file reached.
23 IO.ACT Device active.
28 IO.SSD Semistandard mode.
29 IO.NSD Nonstandard mode.
32-35 IO.MOD Data mode:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
10 .IOIMG Image mode.
13 .IOIBN Image binary mode.
14 .IOBIN Binary mode.
16 .IODPR Dump record mode.
17 .IODMP Dump mode.
You can set the I/O status bits IO.SSD and IO.NSD and the data mode in
your OPEN or INIT call for the DECtape I/O channel. You can also set
these I/O status bits with SETSTS. Bits 18 through 23 of the I/O
status word, however, are set by the monitor on an error return from a
data transmission call (IN, INPUT, OUT, or OUTPUT) to indicate the
reason for the error return.
13-20
CHAPTER 14
MAGTAPES (MTA)
An unlabelled magtape is a sequential I/O, nondirectory device. The
data on the tape begins with a beginning-of-tape (BOT) mark. Each
file on the tape ends with an end-of-file (EOF) mark. The last file
ends with an end-of-tape (EOT) mark, which is two EOF marks. The
physical end of the tape also has a mark: a metal reflector attached
to the tape.
A file on a magtape contains one or more records; each record occupies
one or more blocks. If the last block used by a record is not filled
by the record, a gap is left unused (up to the end of the block).
Magtapes cannot be connected to MPX (multi-plexed) channels.
TOPS-10 supports both 7-track and 9-track magtape devices. A 9-track
tape device can be operated in either DIGITAL-compatible or
industry-compatible mode.
A 9-track tape can be either labelled or unlabelled. A tape label
identifies, defines, and protects the data on the tape. A labelled
magtape can be accessed using LOOKUP and ENTER calls, like a directory
device. For a discussion of the format of tape labels, see the
TOPS-10 Tape Processing Manual.
The default density of tapes is defined by the system administrator
when the monitor is generated by MONGEN. You can read the density of
a tape with the .TFDEN function of the TAPOP. monitor call. You can
set a different density for a tape by using the SET DENSITY command or
by setting the bit IO.DEN in the file status word. This is
accomplished by using the SETSTS monitor call or by using the .TFDEN
function plus the offset .TFSET of the TAPOP. monitor call.
Magnetic tape density can be one of the following:
200 bits/inch (8.1 rows/mm)
556 bits/inch (22.5 rows/mm)
800 bits/inch (32.2 rows/mm)
1600 bits/inch (65.3 rows/mm)
6250 bits/inch (225.5 rows/mm)
14-1
MAGTAPES (MTA)
The default buffer size for a magtape device is 128 decimal words.
A magtape transfer is limited to 7681 words for KS systems, and, for
KL systems, is limited according to the type of controller as listed
here and in the TAPUUO source module.
Controller Limit (in words)
TX01 128K
DX20 16K
TM02 16K
TM02/RH11 16K
TM78 16K
Specific information about magnetic tape usage, as appropriate to each
type of magtape, is given in the TOPS-10 Operator's Hardware Device
and Maintenance Manual.
14.1 MAGTAPE DEVICE NAMES
A magtape device has a name of the form:
MTcu
Where: c is the controller name: A, B, C, and so forth.
u is a unit number in the range 0 to 15.
The magtape controllers and the magtape units that are supported for
TOPS-10 are listed in the TOPS-10 Operator's Hardware Device and
Maintenance Manual.
14.2 MAGTAPE DATA MODES
A magtape device can use any of the following data modes: ASCII,
ASCII line, byte, image, image binary, binary, dump record, or dump
mode. The default buffer size for buffered modes is 200 (octal)
words; you can change the buffer size by using the SET BLOCKSIZE
command, or by using the TAPOP. .TFBSZ function.
1. ASCII mode reads or writes ASCII characters exactly the same
in the buffer and on the tape. Parity checking is done by
the magtape system, not by the monitor.
2. ASCII line mode is identical to ASCII mode.
14-2
MAGTAPES (MTA)
3. Byte mode transfers bytes between buffer and tape according
to a byte pointer and byte count. For output, the monitor
computes the byte count and reads the byte size from the
buffer ring control block. Each byte is written as a tape
record (also called the "tape frame"). For input, the
monitor obtains the byte count from the magtape service
routine and reads the byte size from the buffer ring control
block. The default byte size is 8 bits, where the low-order
4 bits of each 36-bit word are lost.
NOTE
In other modes, whole words of 36 bits are
transferred regardless of the actual number
of bytes in the buffer (exception: see
TAPOP. function .TFMFC). In byte mode, only
the actual number of data bytes are
transferred.
4. Image mode is identical to ASCII mode, except that data is
taken as 36-bit bytes.
5. Image binary mode is identical to image mode.
6. Binary mode is identical to image mode.
7. Dump record mode is unbuffered and uses a command list to
transfer data between memory and the magtape device. The
monitor call that requests the magtape I/O gives the address
of the command list, such as an IN, INPUT, OUT, or OUTPUT
call.
The default block size is 200 (octal) words; you can change
the record size by using the SET BLOCKSIZE command or the
TAPOP. .TFBSZ function.
A command list consists of words of one of the following
forms:
IOWD buflength,buffer
XWD 0,nextcmd
Z
Where: IOWD format calls for the number of words given by buflength
to be transferred between the magtape device and memory
beginning at buffer.
XWD format directs that the command list continues at nextcmd.
Z (zero) word ends the command list.
14-3
MAGTAPES (MTA)
On input, each IOWD command begins a new buffer in memory. If the
record read is too short for the buffer, input continues in the next
record on the tape; if the record read is too long, the IO.BKT bit in
the file status word is set and the monitor takes the error return
from the relevant monitor call.
On output, each IOWD command begins a new record on the magtape. If
the buffer is too long for the record length, the data continues to
new records on the tape, as required; if the buffer does not fill the
last record, it remains a short record on the tape.
On an I/O error or physical end-of-tape, the magtape service routine
ends I/O and stops reading from the command list. On an end-of-file
input, the input call takes the error return and the IO.EOF bit is set
in the file status word. On the next input call, the next record (in
the next file) is read from the tape.
The read backwards function is not allowed in dump record mode.
8. Dump mode is unbuffered and transfers variable-length records
between the magtape device and memory. Dump mode uses a command list
identical to that of dump record mode.
Unlike DUMP RECORD mode, DUMP mode processes exactly one tape record
for each IOWD. If an INPUT operation encounters a record that is
shorter than that specified in the IOWD, the remainder of the memory
buffer is not changed. On output, the records are not split up, and
the length of each record written to the tape is exactly that
specified in the IOWD.
14.3 MAGTAPE I/O
A number of monitor calls can be used for magtape I/O. These are:
DEVSTS Reads file status bits.
ENTER Opens a labelled magtape for writing.
FILOP. Performs directory device functions for labelled
magtape.
LOOKUP Opens a labelled magtape for reading.
MTAID. Defines a tape reel identifier for a magtape device.
MTBLK. Writes three inches of blank tape.
MTBSF. Skips backward over one file on tape.
MTBSR. Skips backward one record on tape.
14-4
MAGTAPES (MTA)
MTCHR. Returns characteristics for a magtape device.
MTDEC. Initializes for DIGITAL-compatible 9-track tape.
MTEOF. Writes an end-of-file mark on tape.
MTEOT. Skips forward to end-of-tape.
MTIND. Initializes for industry-compatible 9-track tape.
MTLTH. Sets tape to read next record at low threshold (TM10
only).
MTREW. Rewinds the tape.
MTSKF. Skips forward over one file on tape.
MTSKR. Skips forward one record on tape.
MTWAT. Waits for tape I/O to complete.
TAPOP. Performs any of the above functions and many other
functions for a tape.
14.4 MAGTAPE I/O STATUS
The I/O status bits for magtapes are listed below.
Bits Symbol Meaning
18-21 IO.ERR Error flags. If all these bits are set, the error
was detected by the tape label handler; use the
DEVOP. call to determine the extended error code.
Flag Symbol Error
18 IO.IMP Output attempted on a write-locked
unit, or an illegal operation was
attempted.
19 IO.DER Data was missed on the tape or the
tape was bad, or the transport is
hung.
20 IO.DTE Parity error.
21 IO.BKT The record read from the tape is
too long for the buffer.
22 IO.EOF End-of-file mark found. You must clear this bit
using SETSTS before reading further, or CLOSE to
reset the tape status.
14-5
MAGTAPES (MTA)
23 IO.ACT Device active.
24 IO.BOT Beginning of tape.
25 IO.EOT Physical end of tape was encountered. Physical EOT
is several feet before the actual end of tape. It
is seen when passed over on a write operation as an
error return with this bit set in the file status
word. You must clear this bit and condition (using
the SETSTS call) before another write operation can
be successful. Physical EOT is not seen on read
operations. Physical EOT does not prevent your
program from writing off the end of tape. If your
program does not heed the physical EOT warning, it
is allowed to keep writing. Logical EOT does not
prevent your program from reading past it. Your
program must check for two consecutive EOF marks,
which indicates the logical EOT.
26 IO.PAR Parity:
0 = even (BCD only)
1 = odd
27-28 IO.DEN Density:
0 = standard
1 = 200 BPI
2 = 556 BPI
3 = 800 BPI
Other densities (1600, 6250) must be specified by
setting IO.DEN to 0 on an OPEN, and then using a
TAPOP. to set the desired density.
Odd parity is preferred. The user program should
specify even parity only when creating a tape to be
read in binary coded decimal (BCD) on another type
of computer system.
29 IO.NRC Read without reread check.
32-35 IO.MOD Data mode. Defines method for writing data into
buffers. The modes are:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
3 .IOBYT Byte mode.
10 .IOIMG Image mode.
13 .IOIBN Image binary mode.
14 .IOBIN Binary mode.
16 .IODPR Dump record mode.
17 .IODMP Dump mode.
14-6
MAGTAPES (MTA)
14.5 MODES SET BY .TFMOD
The magnetic tape data formats, which can be set with TAPOP. function
.TFMOD (Code 1007/2007) are described in this section. These hardware
data modes describe how data is stored on a magnetic tape.
The following sections describe which bits are stored in which tracks
and how many frames are required to store a word of data. Refer to
the description of the TAPOP. monitor call in Chapter 22 for a
description of how to set the desired magnetic tape data mode. The
diagrams in this section are logical representations of data on a
magnetic tape. In actuality, the parity frame is in the center of the
tape, and the order of the other frames is not necessarily as
pictured.
Code 0 (.TFMDD) sets DEC-compatible core dump mode for either 7-track
or 9-track magnetic tapes (MTAPE 100 also sets this mode.) The type
chosen depends on the magnetic tape unit used. This data mode
function code is the equivalent of code 1 (.TFMID) for 9-track tapes
and code 5 (.TFM7T) for 7-track tapes. On a 9-track tape,
DEC-compatible core dump mode stores one 36-bit word of data in five
frames. Note that the last frame is only half-used. One word
actually requires 4 and one-half frames.
Each data word in 9-track DEC-compatible core dump mode is formatted
as shown below.
0 7 8 15 16 23 24 31 32 33 34 35
--------------------------------------------------------
| | | | | |
--------------------------------------------------------
1st 2nd 3rd 4th 5th
frame frame frame frame frame
For each data word in memory, there are five magnetic tape bytes per
36-bit word, with parity bits unavailable to the user. Bits are read
and written on the tape as shown below.
14-7
MAGTAPES (MTA)
Table 14-1: 9-Track DEC Dump Mode
______________________________________________________________________
Tracks
______________________________________________________________________
9 8 7 6 5 4 3 2 1
0 1 2 3 4 5 6 7 P
8 9 10 11 12 13 14 15 P
16 17 18 19 20 21 22 23 P Frames
24 25 26 27 28 29 30 31 P
0 0 0 0 32 33 34 35 P
______________________________________________________________________
When writing on TM10s, bits 30 and 31 are written twice. First they
are written as shown in the diagram above and they are then copied in
tracks 7 and 6 of byte 5. Tracks 9 and 8 of byte 5 remain zero. When
writing with a DX10, TM02-C, or TM10-C, bits 30 and 31 are written
only once. Tracks 9, 8, 7, and 6 contain zero.
When reading from a TM10, parity bits and tracks 9 and 8 of frame 5
are ignored. Frame 4, tracks 2 and 3 are ORed with Frame 5, tracks 6
and 7. These are bits 30 and 31 of the data word. On a DX10, TM02-C,
and TC10-C, the parity bits, frames 9, 8, 7, and 6 are ignored.
Code 1 (.TFMID) sets 7-track core dump mode, one 6-bit byte is stored
in each frame of the tape. Six frames are required to store one
36-bit word. This mode is the only hardware mode supported for
7-track magnetic tapes.
Each data word in 7-track DEC-compatible core dump mode is formatted
as shown below.
0 5 6 11 12 17 18 23 24 29 30 35
-------------------------------------------------------------
| | | | | | |
-------------------------------------------------------------
1st 2nd 3rd 4th 5th 6th
frame frame frame frame frame frame
14-8
MAGTAPES (MTA)
Bits are read and written on the tape as shown below.
Table 14-2: 7-Track Dump Mode
______________________________________________________________________
Tracks
______________________________________________________________________
7 6 5 4 3 2 1
0 1 2 3 4 5 P
6 7 8 9 10 11 P
12 13 14 15 16 17 P Frames
18 19 20 21 22 23 P
24 25 26 27 28 29 P
30 31 32 33 34 35 P
______________________________________________________________________
Code 2 (.TFM8B) sets industry-compatible core dump mode for 9-track
tapes. This mode is compatible on any machine that reads and writes
8-bit bytes (for example, System 360/370 and PDP-11s). When a read
operation is performed, four frames (8-bit bytes) are read into each
word (left-justified). The TM02 and TM10-C in industry compatible
mode at 800 bpi in bits 32-35 give an indication of a parity error in
the corresponding frame of a word. In industry compatible mode at
1600 bpi, bits 32-35 are indeterminate. The DX10 and TC10-C, return
zeroes in these four bits. The information read into bits 32 through
35 is not user data. On a write operation, the left most four 8-bit
bytes of each word are written out in four frames; the remaining 4
rightmost bits (that is, bits 32 through 35) are ignored. Only bits 0
through 31 are written onto the tape.
Each data word in 9-track Industry-compatible core dump mode is
formatted as shown below.
0 7 8 15 16 23 24 31 32 35
--------------------------------------------------
| | | | | |
--------------------------------------------------
1st 2nd 3rd 4th
frame frame frame frame
14-9
MAGTAPES (MTA)
Bits are read and written on the tape as shown below.
Table 14-3: 9-Track Industry-Compatible Dump Mode
______________________________________________________________________
Tracks
______________________________________________________________________
9 8 7 6 5 4 3 2 1
0 1 2 3 4 5 6 7 P
8 9 10 11 12 13 14 15 P Frames
16 17 18 19 20 21 22 23 P
24 25 26 27 28 29 30 31 P
______________________________________________________________________
When using industry-compatible mode and buffered I/O, your program
should insert the byte size in the byte pointer before issuing the
first IN, INPUT, OUT, or OUTPUT monitor call.
Code 3 (.TFM6B) sets SIXBIT mode for 9-track magnetic tapes. This
mode is only available on TU7x - series drives. The format of the
data word is shown below.
0 5 6 11 12 17 18 23 24 29 30 35
-------------------------------------------------------------
| | | | | | |
-------------------------------------------------------------
1st 2nd 3rd 4th 5th 6th
frame frame frame frame frame frame
14-10
MAGTAPES (MTA)
Bits are read and written on the tape as shown below.
Table 14-4: 9-Track SIXBIT Mode
______________________________________________________________________
Tracks
______________________________________________________________________
9 8 7 6 5 4 3 2 1
0 0 0 1 2 3 4 5 P
0 0 6 7 8 9 10 11 P
0 0 12 13 14 15 16 17 P Frames
0 0 18 19 20 21 22 23 P
0 0 24 25 26 27 28 29 P
0 0 30 31 32 33 34 35 P
______________________________________________________________________
Code 4 (.TFM7B) sets 7-bit mode, called ANSI ASCII (not available on
TM10s and TC10-Cs). This mode stores one 7-bit ASCII byte in each
frame of the tape. This mode is useful for transferring ASCII data
from DECsystem-10s to 8-bit byte-oriented machines, such as PDP-11s
and System 360/370s. Five left-justified (in core) 7-bit bytes are
stored in five frames on the magnetic tape. Bit 35 must be zero to
conform to ANSI standards. Bit 35 is written into the high-order bit
of the last frame of each word. The other high-order bits are set to
zero on write operations. When the tape is read, all five high-order
bits are ORed and the result is stored in bit 35.
Each data word in ANSI ASCII mode is formatted as shown below.
0 6 7 13 14 20 21 27 28 35
-----------------------------------------------------
| | | | | | |
-----------------------------------------------------
1st 2nd 3rd 4th 5th
frame frame frame frame frame
14-11
MAGTAPES (MTA)
Data is read and written on the tape in the following format.
Table 14-5: ANSI ASCII Mode
______________________________________________________________________
Tracks
______________________________________________________________________
9 8 7 6 5 4 3 2 1
0 0 1 2 3 4 5 6 P
0 7 8 9 10 11 12 13 P
0 14 15 16 17 18 19 20 P Frames
0 21 22 23 24 25 26 27 P
35 28 29 30 31 32 33 34 P
______________________________________________________________________
14.6 READ BACKWARDS (TX01, TM02, AND TX02 ONLY)
When reading a tape backwards, the monitor reads data forwards (i.e.,
inverted) into the buffer. If the buffer is larger than the record, a
zero-fill will result at the beginning of the buffer. For example:
BUFSIZ - WRDCNT = first word of data
If your program contains a multiple IOWD list your program must
reverse the I/O bit to enable read forward. Reading backwards into
BOT will set the EOF and BOT bits. Note that a tape cannot be read
backwards if mode 16 or labelled tapes are used.
Read backwards must be set after the INIT, OPEN, or FILOP. monitor
call, because the read backwards function is cleared on an OPEN, INIT,
FILOP., or RELEAS monitor call.
When reading backwards, the records are returned to the user in
reverse order, but the bytes within each physical record are returned
in forward order. Therefore, to prevent the appearance of scrambled
data when reading backwards, you should read the records on physical
boundaries only.
14-12
MAGTAPES (MTA)
14.7 PROGRAMMING I/O TO LABELLED MAGTAPES
By default, a magtape contains only the information described in
Section 14.5. However, GALAXY 4.1 batch and spooling system provides
the opportunity to write labelled magnetic tapes, which can be
accessed in a manner similar to a directory device such as disk and
DECtape.
With unlabelled magtapes, the LOOKUP and ENTER monitor calls are not
operational. They are ignored to provide your program with device
independence. (Note that your program will always skip when these
calls are ignored.) However, the calls are used with directory devices
and labelled magtapes.
Label parameters are temporarily stored in the monitor's data base for
the tape drive until the first input or output operation is performed
on the tape drive. When I/O is done, the label parameters are
transferred to the tape or made available to the program, depending on
the direction of I/O. An ENTER call loads the parameters from the
argument block onto the tape. A LOOKUP call loads the parameters from
the tape into the argument block. A LOOKUP with no file name or
extension will return information about the current file on the tape.
Both the four-word and extended argument blocks for LOOKUP/ENTER are
allowed.
For a labelled magtape, ENTER loads the label parameter block, and a
LOOKUP reads the label parameter block, to find the requested file by
file name and extension. This functionality is also provided by the
TAPOP. monitor call with function .TFLPR.
Magnetic tape label processing is not fully supported by the TOPS-10
monitor. Therefore, if you issue a monitor call that reports your
position on the tape, the number of files will include the number of
label record files (2 per data file). As a result, the MTCHR. UUO and
the .TFSTA function of TAPOP. UUO reports the number of data files
times 3.
The following information is loaded from the label parameter block of
a labelled magtape. For more information about the contents of each
word, refer to the description of the .TFLPR function of TAPOP. in
Chapter 22.
Word Byte Contents
.TPREC: TR.FCT Forms control.
TR.RFM Record format.
.TPRSZ Record size.
.TPBSZ Block size.
14-13
MAGTAPES (MTA)
.TPEXP: TP.ECR Creation date.
TP.EEX Expiration date.
.TPPRO Protection code.
.TPSEQ File sequence number.
.TPFNM File name and extension.
.TPGEN: TP.GEN Generation.
TP.VER Version.
The following defaults for the label parameters will be set by an
ENTER to the tape label:
Parameter Default
Forms Control No forms control. Same as .TFCNO code in
argument block for function .TFLPR of TAPOP.
call.
Record Format Fixed record format. Same as .TRFDF in
argument block for function .TFLPR of TAPOP.
call.
Record Size Buffer size times number of bytes per word.
Buffer size is reported by DEVSIZ monitor
call. Number of bytes per word depends on
the format used to write the tape (refer to
Section 14.5).
Block Size Default is the buffer size.
Creation date Defaults to "today" (current date).
Expiration date Defaults to "today."
Protection code No default. Taken from ENTER argument block.
File Sequence No. Every file on the tape is assigned a
sequential sequence number as it is written
to the tape.
File name Both file name and extension are taken from
ENTER argument block. If file name in
argument block is 0, FILE.nnn is used, where
nnn is the file sequence number.
Generation No. Defaults to 0.
Version No. Defaults to 0.
14-14
CHAPTER 15
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
15.1 TERMINAL DEVICE NAMES
The name of a terminal is of the form TTYnnn, where nnn is a 3-digit
octal number (leading zeroes may be omitted).
Local terminals (connected to the RSX-20F front end on the KL or
directly to the KS) will always have the terminal name that contains
the number of the terminal line. Therefore, the terminal connected to
line 27 will always have the name TTY027. However, terminals
connected through an ANF-10 remote station will have a terminal name
based on the node name, such as NOVA_22, where the node name is NOVA;
or 32_22, where the ANF-10 node number is 32 and the line number is
22. When a remotely-connected terminal is connected to the system,
the monitor assigns it a terminal name on a dynamic basis, from a pool
of unassigned terminal names. Therefore, when NOVA_22 is connected to
the system, the monitor assigns it a terminal name, such as TTY150.
If the terminal is disconnected and connected again, it may be
assigned a different terminal name, such as TTY56.
15.2 TERMINAL DATA MODES
A terminal uses a buffer size of 23 (octal) words. A terminal can use
any of the following buffered data modes:
o ASCII mode transmits 7-bit characters packed left justified,
five characters per word. If you attempt to do input from
the terminal in ASCII mode, the monitor will use ASCII line
mode.
15-1
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
o ASCII line mode receives 7-bit characters packed
left-justified, 5 characters per word. When doing input from
the terminal, the monitor will return a buffer to your
program when either the buffer is filled (132 characters) or
if a break character (such as linefeed) is input. If you
attempt to do output in ASCII line mode, the monitor will use
ASCII mode instead. To do the equivalent of ASCII line mode
on output, your program must issue OUT or OUTPUT calls
itself, after putting each break character in the buffer.
See Section 15.4 for more information about break characters.
ASCII mode and ASCII line mode are essentially equivalent, in
that each line (up to a break) uses a buffer, even though the
buffer might be capable of storing more characters. Note
that, with IO.BKA set, each character initiates a break
condition.
o 8-bit ASCII mode receives 8-bit characters, packed
left-justified, in four 8-bit bytes. 8-bit ASCII mode is
legal for pseudo-terminals (PTY).
o Image mode is allowed only for terminal I/O and is not
allowed for pseudo-terminals. Image mode makes any sequence
of input characters legal. Because image mode is a "literal"
mode, the terminal settings to prompt processing by the
monitor (such as FORMFEED, TABS, and so forth) are not
effective in image mode. Carriage-return does not generate
an automatic line-feed, line editing is not performed, and
control characters, like CTRL/C and CTRL/Z, do not halt the
program.
To avoid having a terminal get hung in image mode (when no
input can change the input mode), the monitor simulates an
end-of-file if no characters are input for ten seconds.
After another ten seconds, the monitor simulates a CTRL/C to
release the terminal from image mode.
The simulation of these CTRL/Zs and CTRL/Cs can be prevented
by sending any output to the terminal before the ten seconds
have passed. (If no output is needed, you can output a
null.)
15-2
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
o Packed image mode (PIM) is allowed for terminal I/O and for
pseudo-terminals (PTYs) in full-SCNSER mode. Packed image
mode allows efficient throughput of data between programs and
terminals; this efficiency is accomplished by minimizing the
monitor's manipulation and testing of characters. PIM does
not echo terminal input, and the OPEN bit IO.SUP is ignored
in this mode.
A packed-image character is stored in the buffer as an 8-bit
value (7-bit ASCII plus parity bit); four characters are
stored in each word. Your program can define a "break set"
consisting of from one to four break characters for each line
initialized in packed image mode. These break characters are
defined by using the TRMOP. monitor call. Note that your
break set may take into account the parity setting.
When the monitor receives a break character from the
terminal, the character is placed in the buffer and the
controlling program is awakened. Other characters are placed
into the buffer without waking the program.
If you define a null break set (0), your controlling program
is awakened whenever input is available. All available input
is returned, as in image mode. Note, however, that CTRL/S
and CTRL/Q will stop/start output to the terminal in this
mode; this avoids getting the terminal hung in packed image
mode.
15.3 TERMINAL CHARACTER HANDLING
The ASCII character set consists of 128 7-bit character codes. The
8-bit ASCII character set has 256 8-bit character codes. Table 15-1
shows the 7-bit ASCII codes and their display characters, and
describes any special handling for terminal I/O. The monitor
interprets some control characters as line-editing commands. The
TOPS-10 Operating System Commands Manual describes monitor command
line editing.
15-3
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
Table 15-1: Terminal Handling of ASCII Characters
______________________________________________________________________
Code Prints Name and Special Terminal Handling
______________________________________________________________________
000 Null character ignored on input, suppressed on
output (except for image modes).
001 ^A CTRL/A acts as a CTRL/C for OPSER subjobs and
MIC.
002 ^B CTRL/B acts as a break character for MIC.
003 ^C CTRL/C returns the job to monitor command level,
if issued while the program is waiting for
input. All current type-ahead is cleared. When
used while the program is doing output to the
terminal, CTRL/C acts like CTRL/U, clearing the
current line. Two successive CTRL/Cs will
return the job to monitor command level.
004 ^D CTRL/D sends an EOT character (ASCII 004) to the
monitor. If this same value were returned to
your terminal it might cause certain types of
modems to hang up and your terminal connection
would be lost. To prevent this from happening,
CTRL/D is echoed as ^D (136,104). Note that
CTRL/D acts as an unsolicited DDT/EDDT
breakpoint when the SET DDT/EDDT BREAKPOINT
facility is enabled (refer to the TOPS-10
Operating System Commands Manual).
005 ^E CTRL/E.
006 ^F CTRL/F.
007 CTRL/G rings the terminal bell instead of
echoing, and is a default break character.
010 CTRL/H echoes as a backspace and functions as a
DELETE (ASCII 177). The backspace is not passed
to your program unless it is in APL or a special
editor mode.
011 CTRL/I echoes as a tab or an equivalent number
of spaces. See SET TTY TAB in the Commands
Manual.
012 CTRL/J echoes as a linefeed and is a default
break character.
15-4
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
013 CTRL/K echoes as a vertical tab (default break
character) or four linefeeds. See SET TTY FORM
in the Commands Manual.
014 CTRL/L echoes as a formfeed (default break
character) or eight linefeeds. See SET TTY FORM
in the Commands Manual.
015 CTRL/M echoes as a carriage-return/line-feed and
is passed to the program as a carriage return
and linefeed; the linefeed is a default break
character. Note: if the terminal is in
papertape input mode (SET TTY TAPE), the
carriage return is merely passed to the program.
016 ^N CTRL/N.
017 ^O CTRL/O echoes, but is not passed to the program.
CTRL/O inverts the terminal output suppression
bit, allowing output to be turned on and off.
The suppression bit is cleared by a CTRL/C input
character and by all of the following monitor
calls: IN, INPUT, OPEN, INIT, FILOP., DDTIN,
INCHRW, INCHRS, INCHWL, INCHSL, SKPINC, SKPINL
and the TRMOP. equivalents.
020 ^P CTRL/P acts as a proceed character for MIC.
021 ^Q CTRL/Q echoes unless SET TTY XONXOFF is set, in
which case it continues output stopped by
CTRL/S. Note: CTRL/Q starts papertape if SET
TTY TAPE is set. See the SET TTY XONXOFF and
SET TTY TAPE commands in the Commands Manual.
022 CTRL/R does not echo, but causes the current
terminal line to be retyped. This includes any
edits to the line. Note: in RTCOMP mode,
CTRL/R is a break character, and does not type
the line. See the SET TTY RTCOMP command in the
Commands Manual.
023 ^S CTRL/S echoes unless SET TTY XONXOFF is set, in
which case it stops terminal output. The output
is not lost, as it is for CTRL/O, but waits for
CTRL/Q. Note: if the terminal is in papertape
mode, CTRL/S stops the tape.
024 CTRL/T does not echo unless SET TTY RTCOMP is
set (see the Commands Manual). If SET TTY
RTCOMP is set, it echoes as ^T and is a break
character. CTRL/T (not in RTCOMP mode) is
equivalent to the USESTAT command, which
displays job status and timing information.
15-5
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
025 ^U CTRL/U deletes the current terminal input line
back to the last break character. CTRL/U echoes
as CTRL/U followed by a carriage return and
linefeed. On video terminals, ^U erases the
current line on the screen. Note: for special
editors, CTRL/U is passed to the editor.
026 ^V CTRL/V.
027 ^W CTRL/W deletes one word from the terminal input
line. On video terminals, the word is erased
from the screen. For special editors, CTRL/W is
passed to the editor.
030 ^X CTRL/X.
031 ^Y CTRL/Y.
032 ^Z CTRL/Z acts as an end-of-file character for
terminal input, and is a default break
character. CTRL/Z echoes as CTRL/Z followed by
a carriage return and linefeed but only the
CTRL/Z is passed. Many system CUSPs recognize
CTRL/Z as an EXIT command.
033 $ CTRL/[ echoes as a dollar sign ($) and is the
ESCAPE character. ESCAPE is a default break
character (see also codes 175 and 176.)
034 ^\ CTRL/\ is control-backslash, and when typed on
the CTY of KL and KS systems does not echo, but
causes the terminal to be connected to the
front-end command processor.
035 ^] CTRL/].
036 ^^ CTRL/^.
037 ^_ CTRL/underscore.
040 (space) Blank character.
041 ! Exclamation point.
042 " Quotation mark.
043 # Number sign.
044 $ Dollar sign.
045 % Percent sign.
15-6
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
046 & Ampersand.
047 ' Apostrophe.
050 ( Left parenthesis.
051 ) Right parenthesis.
052 * Asterisk.
053 + Plus sign.
054 , Comma.
055 - Minus sign (hyphen).
056 . Period (decimal point).
057 / Slash.
060 0 Zero.
... ... Intervening numerals.
071 9 Nine.
072 : Colon.
073 ; Semicolon.
074 < Left angle bracket.
075 = Equal sign.
076 > Right angle bracket.
077 ? Question mark.
100 @ At sign.
101 A Uppercase A.
... ... Intervening uppercase letters.
132 Z Uppercase Z.
133 [ Left square bracket.
134 \ Backslash.
135 ] Right square bracket.
15-7
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
136 ^ Up-arrow.
137 _ Underscore.
140 (grave) Grave accent.
141 a Lowercase a.
Note: Lowercase letters are translated to
uppercase unless SET TTY LC is set or the
appropriate terminal type has been specified.
Refer to the Commands Manual.
... ... Intervening lowercase letters.
172 z Lowercase z.
173 { Left brace.
174 | Vertical line.
175 } Right brace. This is converted to ASCII 033
(ESCAPE), if altmode conversion is enabled.
176 ~ Tilde. This is converted to ASCII 033 (ESCAPE)
if altmode conversion is enabled (using SET TTY
ALTMODE command).
177 DELETE deletes a character from the current
terminal input line. DELETE is ignored in
papertape mode, and is passed to DDT and special
editors.
______________________________________________________________________
15.4 BREAK CHARACTER SET
A set of control characters acts as a default set of break characters.
A break character defines the end of line for an INCHWL call.
The default break character set is:
CTRL/G
CTRL/J
CTRL/K
CTRL/L
CTRL/Z
ESCAPE
In addition, if the terminal has SET TTY RTCOMPATIBILITY set, CTRL/R
and CTRL/T act as break characters.
15-8
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
If the terminal is in SLAVE mode, the following characters are also
break characters:
CTRL/C
DELETE
CTRL/U
CTRL/W
CTRL/R
CTRL/T
You can define your own set of break characters by setting the I/O
status bit IO.ABS in the OPEN call, and including a bit mask in the
argument to the OPEN call for this channel. The IO.ABS state can be
set or cleared at any time using the SETSTS call. When set, the state
is controlled using the TRMOP. call. When IO.ABS is initially set,
the break mask will be set to all zeros, implying that no characters
are defined as break characters, and the field width is initially set
to one, causing normal echo of control characters and a wakeup with
each character that is typed.
You handle input with INCHWL, the appropriate TRMOP. function (input
line), or with buffered terminal input. Each field (line) will be
determined by the break set or the field width. Wakeup can occur
prematurely, such as when monitor buffer space is limited. You should
ensure that your program can handle early breaks.
The call can be used to read the break set as well as write it. On a
read function, the field width and break mask will be returned to the
user at BLOCK+3.
IO.ABS mode allows you to control the field width using the .TOSBS
function. The mode can be set or cleared at any time. Clearing the
mode clears the break mask, and setting the mode creates a new table
of break masks. The default table has no break characters and a field
width of one, thus setting the terminal up for single-character I/O.
Even when IO.ABS is set, echoing is controlled by IO.SUP. If IO.SUP
is set in the I/O status word, no characters are echoed by the
monitor. If IO.SUP is not set, printing characters (ASCII codes 101
to 176) are echoed by the monitor, and control characters that are not
defined as break characters are echoed. Control characters defined as
break characters will never be echoed. This includes RETURN, line
feed, vertical tab, and bell characters.
When IO.ABS is set, the monitor will do no line editing functions, so
CTRL/T, CTRL/W, CTRL/U, CTRL/R, and DELETE will not function. IO.ABS
mode has no effect on CTRL/C processing, however.
15-9
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
Setting IO.ABS also implies deferred echo mode. Characters are not
echoed until the program requests input from the terminal. The
monitor postpones the echo of any characters after a break character
is typed, until the program attempts to read the next field. That
field is echoed up to its break character, and so forth. This
prevents echoing during any change in IO.SUP or IO.ABS states, and
ensures synchronization of echo and program output.
15.5 LAT TERMINALS
Local Area Transport (LAT) is a protocol that supports virtual
terminal connections over Ethernet. TOPS-10 can serve as a host
system that users on LAT servers can access. Any TOPS-10 system that
has an Ethernet connection and is running TOPS-10 Version 7.03 or
later can use LAT.
Serial line printers can be connected to ports on LAT servers and
accessed as terminals by a TOPS-10 host. Printers that are connected
to LAT servers can be shared by multiple hosts on the Ethernet much
like printers on ANF-10 nodes can be shared by multiple hosts on the
ANF-10 network. Such terminal ports are defined as a service and are
called "application terminals". See the descriptions of the
LATOP. UUO and the TRMOP. UUO in Volume 2.
15.6 TERMINAL CLASSES, TYPES, AND ATTRIBUTES
Terminal classes are defined by the attributes and characteristics
exhibited by that class as a whole. Within a class, the presence of
additional attributes distinguish one terminal type from another. The
TOPS-10 monitor supports DIGITAL-defined terminal classes and provides
the means to support customer-defined classes. You may define
terminal classes and assign member types to these classes by your
answers to the appropriate questions in the MONGEN dialog.
Terminal characteristics definitions for all DIGITAL-defined terminal
classes are contained in COMDEV.MAC. The definitions for some
commonly used terminals are listed in Table 15-2.
15.6.1 Reading and Setting Terminal Class
The TRMOP. function .TOTCN reads the terminal class name. The GETTAB
Table .GTTCN reads the terminal class names known to the monitor. The
default terminal type name can be obtained by the GETTAB item %CNDTT,
in Table .GTCNF.
15-10
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
15.6.2 Reading and Setting Terminal Type
The TRMOP. function .TOTTN examines and sets the real terminal type
name for unknown terminal types. This is stored in the LDB as a
SIXBIT word, and is not used by the monitor.
15.6.3 Reading and Setting Terminal Attributes
The TRMOP. functions .TOATR, .TOAT2, and .TOAT3 allow users to read
and set the attributes words.
Attributes used by the monitor are the overstrike and ISO attributes
(TA.OVR and TA.ISO). These affect how eight-bit characters are
translated to seven-bit for fallback presentation when TA.8BT is
clear.
The attributes defined by .TOATR are listed below:
Bit Symbol Description
0 TA.8BT Eight-bit terminal
1 TA.DIS Display
2 TA.OVR Overprinting
3 TA.8BA 8-bit Architecture
4 TA.NRC NRCs
5 TA.ISO ISO/Latin-1 (not DEC/MCS)
6 TA.LID Line Insertion/Deletion
7 TA.CID Character Insertion/Deletion
8 TA.SRM Scroll Regions (DECSTBM)
9 TA.GAT Guarded Area Transfer
10 TA.SEM Selective Erase (DECSEL/DECSED)
11 TA.AVO Advanced Video Option
12 TA.PPO Printer Port Option
13 TA.GPO ReGIS
14 TA.SXL SIXEL Graphics
15 TA.TEK TEK 4010/4014 Emulation
16 TA.RCS Dynamically Redefinable Character Sets
17 TA.UDK User-Defined Keys
18 TA.VFW Variable Forms Width
19 TA.VFL Variable Forms Length
20 TA.V52 VT52 Emulation
21 TA.ESL Extra Status Line
22 TA.JTK Katakana
23 TA.TCS DEC Technical Character Set
24 TA.TSI Terminal State Interrogation
25 TA.BMT Block-Mode Transfer
26 TA.BTA Block Transfer is ANSI
27 TA.HSR Horizontal Scrolling
28 TA.UWN User Windows
29 TA.SSU Multiple Sessions
30 TA.CLR Colored terminal screen
15-11
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
The attributes defined by .TOAT2 are listed below:
Bit Symbol Description
0-2 T2.LDT Locator Device Type (Mouse/Tablet)
0 .T2UNK Unknown
1 .T2MOU Mouse
2 .T2TAB Tablet
3-6 T2.ACL ANSI Conformance Level
7-10 T2.DCL DEC Conformance Level
The remainder of the bits returned for .TOATR and .TOAT2 are reserved
for future definition by Digital.
The bits for .TOAT3 are reserved for customer definition. The symbols
for bits and fields in .TOAT3 are of the form T3.xxx.
15.6.4 Terminal Characteristics Definitions
The terminal characteristics definitions for VT52, VT100, and VT220
type terminals are listed in the table below, as well as definitions
for the serial line laser printers LN01S and LN03. Note that class
and type designation may be the same; additional attributes present in
a particular type within a class distinguishe that type from others
within the class.
Table 15-2: Terminal Characteristics
______________________________________________________________________
Type VT52 VT100 VT220 LN01S LN03
______________________________________________________________________
Class VT52 VT100 VT200 LN01S LN03
Attributes on DIS SRM DIS NKB NKB
V52 DIS SEM 8BA
AVO 8BA
VFW LID
V52 CID
SRM
AVO
PPO
VFW
V52
NRC
Attributes off --- --- --- --- ---
15-12
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
Width 80 80 80 80 80
Length 24 24 24 66 66
Fill 0 0 0 0 0
ANSI level 0 1 2 1 2
DEC level 0 1 2 1 1
BPERAS VTXXEP V100EP V100EP 0 1
BPRUBO VTXXBP VTXXBP VTXXBP 0 0
Characters TAB TAB TAB FF FF
LC LC LC TAB TAB
XON XON XON LC LC
CRLF CRLF CRLF XON XON
______________________________________________________________________
15.7 TERMINAL I/O
TTCALLs operate only on a controlling terminal. TRMOP. must be used
for other terminals and may also be used for the controlling terminal.
In addition to its general I/O monitor calls, TOPS-10 offers a number
of special terminal monitor calls to make terminal I/O simpler.
Special terminal monitor calls include:
GETLIN Returns the SIXBIT physical name of the controlling
terminal.
TRMNO. Returns the Universal Device Index for the controlling
terminal. This index includes the terminal number in
bits 27-35.
TRMOP. Performs many useful terminal operations. See the
TRMOP. functions in Chapter 22.
INCHRW Inputs a character from the controlling terminal (waits
for the character).
OUTCHR Outputs a character to the controlling terminal.
INCHRS Inputs a character from the controlling terminal (skips
only if a character is received).
OUTSTR Outputs an ASCIZ string to the controlling terminal.
INCHWL Inputs a character from the controlling terminal only
if a break character has been typed.
15-13
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
INCHSL Inputs a character from the controlling terminal only
if a break character has been typed and skips if the
character is received.
GETLCH Returns the characteristics for a terminal line.
SETLCH Sets the characteristics for the controlling terminal.
RESCAN Allows your program to read the monitor command that
invoked it.
CLRBFI Clears any typeahead on the controlling terminal.
Useful following detection of an error on a previous
command.
CLRBFO Clears the buffer for output to terminal.
SKPINC Skips if at least one character has been typed on the
controlling terminal.
SKPINL Skips if at least one line has been typed on the
controlling terminal.
IONEOU Displays an 8-bit image mode character on the
controlling terminal.
CHTRN. Translates characters from one interpretation to
another. For instance, you can use CHTRN. to
translate 8-bit characters to 7-bit characters. You
should use this UUO instead of writing a program for
character translation, because CHTRN. translates using
an ANSI standard table.
15.8 NON-BLOCKING TERMINAL I/O
A program can perform non-blocking I/O with the terminal by posting a
read request for the terminal. You can do this using either of the
following methods:
o A TTCALL, such as:
- SKPINL to select line mode without committing to actually
reading a character or line.
- INCHRS or INCHSL to select the mode and to commit to
accepting any available character or line.
o A HIBER call, setting HB.RTC to set character mode, or HB.RTL
to set line mode. In this case, the program will HIBER until
a WAKE is made, and the program must determine the reason for
awakening.
15-14
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
Otherwise, the program can rely on the PSI system (described in
Chapter 6) to interrupt the program when a character or line is ready
to be processed.
Your program must use one of the above methods for non-blocking I/O if
the terminal is set to deferred echo mode. In deferred echo mode, the
monitor echoes no characters until the program has posted a read
request, and the terminal input cannot be processed until the
characters have been echoed. The program need not block while waiting
for input, but it must indicate its ability to accept commands by
using one of the above methods, so that the monitor will echo terminal
input at the first opportunity.
The user program must be aware of the fact that input character
echoing activity has a lower priority to the monitor than output
character activity from the program. As long as the program is
sending characters to the terminal, all input characters are being
stored by the monitor, waiting for an opportunity to echo to the
terminal, in deferred echo mode. It is possible for a program to keep
the terminal busy processing output, so that the terminal will never
be available for input. The program must allow for this possibility
by stopping output or by checking the terminal input buffer to
determine whether echoing is required. Use the TRMOP. function .TOECC
to determine whether echoing is required.
15.9 TERMINAL PAPERTAPE I/O
If a terminal has a papertape device attached, it can perform
papertape I/O. To enable papertape I/O from the terminal, issue the
SET TTY TAPE monitor command. This enables the four required
characters: CTRL/Q (XON), CTRL/S (XOFF), CTRL/R (AUX ON), and CTRL/T
(AUX OFF).
15.9.1 Using Terminal Papertape Input
To begin reading from a terminal papertape, you must type CTRL/Q.
Papertape input ends when a CTRL/S is read from the papertape or from
the terminal keyboard.
15-15
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
The following example shows how to read from a terminal papertape
reader into the disk file DSK:FILE.FIL:
.SET TTY TAPE
.R PIP
*DSK:FILE.FIL=TTY:
^QThis line is from the papertape.
So is this one.
And even this last one.
^Z
^S^C
.
15.9.2 Using Terminal Papertape Output
The terminal papertape punch is connected in parallel with the
keyboard printer; therefore when the punch is on, all characters typed
on the keyboard are punched on the papertape.
Papertape output begins with a CTRL/R typed at the terminal; for the
LT33B or LT33H terminal, a CTRL/R character output from a program can
begin papertape output.
Papertape output continues until a CTRL/T character occurs in the
punched output (either from a program or from the terminal keyboard).
The CTRL/T is the last character punched on the papertape.
If your program is punching papertape at a terminal, it should punch
several inches of blank tape before the final CTRL/T; this permits you
to tear off and discard the CTRL/T character at the end of the tape.
15.10 TERMINAL I/O STATUS
The I/O status bits for the terminal are listed below. The error
flags are set by the monitor, but the I/O status bits (bits 23 through
35) can be set by your program to initiate different modes of I/O.
15-16
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
Bits Symbol Meaning
18-21 IO.ERR Error flags. These are returned by the monitor
after an I/O operation that failed:
Flag Symbol Error
18 IO.IMP Not assigned to a job for image
mode input.
19 IO.DER Ignore interrupts for 0.75 seconds.
20 IO.DTE Echo failure on output.
21 IO.BKT Character lost on input.
If all of these bits are set, the remote node to
which the terminal is connected has failed.
23 IO.ACT Device active.
25 IO.ABS Enable using break mask. (Refer to Section 15.4.)
26 IO.BKA Break on all characters. An IN or INPUT call will
terminate on the first character typed, thus
enabling character input mode.
27 IO.TEC Truth in echoing mode. This causes all control
characters to be output as themselves (for example,
the ESCAPE character is not echoed as $ but as octal
33).
28 IO.SUP Suppress echoing.
29 IO.LEM Enable special editor mode. This causes some
control characters (CTRL/R, CTRL/H, CTRL/U, CTRL/W,
and DELETE) to be passed to the program and ignored
by the monitor, except to echo the control
characters and to act as break characters.
32-35 IO.MOD Data mode:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
2 .IOPIM Packed image mode.
4 .IOAS8 8-bit ASCII mode.
10 .IOIMG Image mode.
Using the TRMOP. call's function .TOBKA, your program can test whether
the terminal is in line input or character input mode. Unless you set
the file status bit IO.BKA, line input mode is assumed.
15.11 PSEUDO-TERMINALS
Most jobs that run on the TOPS-10 monitor are initiated by a user at a
terminal with the LOGIN command. Unless the job is detached by the
DETACH command, it remains under control of the terminal until it is
logged out (using KJOB).
15-17
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
A program can control a job by simulating a terminal. The
pseudo-terminal (a software-defined device) simulates terminal
interaction between the job and the pseudo-terminal (called a PTY).
The controlling program (for example, the batch processor) uses the
PTY device in the same way that a user uses a physical terminal. It
initiates the job on the PTY, provides input, accepts output, and
closes the PTY, all by means of monitor calls.
A controlling job (BATCON, for example) communicates with controlled
jobs (such as batch jobs) through a PTY. The PTY device handles the
terminal commands for the controlling job. It passes input to the
terminal input buffer of the controlled job and passes output from the
controlled job's terminal output buffer to the controlling job. Input
is only echoed if the full-SCNSER PTY bit is set. Figure 15-1
illustrates PTY I/O.
Output <===
.......... ........ ..... .......... ........
:User : <=== : : <=== : : <=== :Software: <=== : :
:terminal: ---> :Prog A: ---> :PTY: ---> :Terminal: ---> :Prog B:
:........: :......: :...: :........: :......:
Input --->
Figure 15-1: PTY I/O
In Figure 15-1, Program A is the controlling job. For example,
Program A might be OPSER. Program B is the controlled job. Program B
performs I/O just as though it were performing I/O with a command
terminal, by placing I/O into its terminal I/O buffer. However, the
PTY replaces the controlling terminal function by passing I/O to and
from the controlling job (Program A).
A PTY is never in I/O wait state. Therefore, a program will not block
for PTY I/O. This allows the program to control multiple PTYs.
Therefore, the program can use HIBER, read I/O status bits, or JOBSTS
to determine whether I/O from a PTY is necessary.
The buffer size for a PTY is the same as for a terminal: 23 (octal)
words.
15.11.1 Pseudo-Terminal Names
The device name of a PTY is of the form:
PTYnnn
Where: nnn is a 3-digit octal number (leading zeros must be omitted).
15-18
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
15.11.2 Pseudo-Terminal I/O
A number of monitor calls are especially important to a PTY-controlled
program. These include:
OPEN Sets up for PTY I/O. Optionally, you may set the
full-SCNSER PTY bit, allowing the PTY to be controlled
directly by a terminal. Setting this bit creates a PTY
with all the characteristics of a terminal. (Some of
the TRMOP. functions are meaningless for a PTY.)
HIBER Allows the controlling program to temporarily suspend
execution until either of the following occurs:
o The PTY has I/O. If your controlling program set
HB.RPT when is used the HIBER call, your program
will be woken whenever I/O is necessary.
o A specified amount of time has passed since your
program went to sleep. Your program will wake even
if no activity has occurred in the controlled job.
Your program should check JOBSTS to determine
whether the PTY has I/O. Your controlling program
can abort any controlled programs by sending two
CTRL/Cs to the PTY of the controlled job.
If the controlling job need not interrupt the
controlled jobs, it should put itself back to sleep
with another HIBER call.
If your program does not set the HB.RPT bit for a HIBER
call, the monitor wakes the controlling job every time
there is a change in the I/O status bits. This
prevents your job from sleeping when it should be
servicing the controlled jobs.
OUT/OUTPUT
The output is sent from your controlling program to the
PTY, and thus read by the controlled job from its
terminal input buffer, just as though it came from its
own terminal. When your program performs an OUT or
OUTPUT to the controlled job, the first OUT/OUTPUT
after an OPEN, INIT, or FILOP. causes the monitor to
discard the contents of the PTY's output buffer.
(Refer to the RELEAS monitor call, below.) Thus, your
program should send a "dummy" OUT/OUTPUT before its
first real output.
15-19
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
The OUT or OUTPUT calls cause the monitor to:
1. Place characters from your controlling program's
buffer ring into the input buffer of the terminal
linked to the PTY.
2. Clear the IO.PTI bit in the I/O status word, so
that the job is not in input wait state.
3. Set or clear the IO.PTM bit in the I/O status word,
depending on the state of the terminal.
For PTY output, the monitor also:
1. Discards all null characters (ASCII 000).
2. If more output is performed than the PTY can
accept, the monitor sets the IO.BKT bit in the I/O
status word, discarding the remainder of the
controlling program's output buffer.
3. The monitor also translates all lowercase
characters sent to the PTY to uppercase, if the
appropriate bit is not set for the PTY, using
TRMOP. function .TOLCT. Many of the
TRMOP. characteristics can be set for a full-SCNSER
PTY. (See the OPEN call in Chapter 22.)
IN/INPUT
The input comes from the controlled job, which places
the data in the PTY's output buffer, from which your
controlling job can read it with IN or INPUT. If no
characters are read, the monitor returns an empty
buffer. An INPUT call does not cause a wait state.
The monitor passes all available characters to your
controlling program. If there are more characters than
can fit in the buffer of the controlling program, the
monitor sets bit IO.PTO in the file status word and
waits for another INPUT monitor call. When the
terminal's buffer is emptied by an INPUT call, the
monitor clears bit IO.PTO.
15-20
TERMINALS (TTY) AND PSEUDO-TERMINALS (PTY)
RELEAS For a PTY, the RELEAS call causes the monitor to:
1. Discard the contents of the terminal's output
buffer.
2. Detach the controlled job from the terminal (if it
is attached).
3. Release the PTY from its channel.
NOTE
Haphazard use of RELEAS with PTYs may leave
detached jobs on the system; these use system
resources unnecessarily.
JOBSTS Returns data about the PTY and the controlled job.
CTLJOB On a normal (skip) return, this call returns the job
number of the controlling job; you must specify the job
number of the controlled job. On an error return, you
specified an invalid (non-existent) job number. The AC
is not cleared on an error return.
15.12 PSEUDO-TERMINAL DATA MODES
A pseudo-terminal can use ASCII or ASCII line mode. These modes are
identical in action to the same modes for terminal devices.
15.13 PSEUDO-TERMINAL I/O STATUS
The I/O status bits for the PTY are:
Bits Symbol Meaning
21 IO.BKT More output sent than was accepted by the PTY.
23 IO.ACT Device active.
24 IO.PTI Job is waiting to receive input.
25 IO.PTO Job is waiting to send output.
26 IO.PTM Subjob is in monitor mode.
32-35 IO.MOD Data mode:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
2 .IOPIM Packed image mode (for full-SCNSER
PTYs only).
4 .IOAS8 8-bit ASCII mode.
15-21
16-1
CHAPTER 16
LINE PRINTERS (LPT)
TOPS-10 supports up to three line printers for each CPU in a KL
system. For KS systems, TOPS-10 supports one line printer. The
printers discussed in this chapter are parallel line devices. Serial
devices, such as the LN01S and the LN03 printers, are discussed in
Chapter 15.
16.1 LINE PRINTER NAMES
The physical names of the line printers are LPTnn0, LPTnn1, and
LPTnn2, where nn is the node number for the system.
16.1.1 Controller Names
The controller name for the line printers is either BA10, LP100,
LP200, LP11, or LP20.
16.1.2 Unit Names
The unit name of a line printer is LSP10-LA, LSP10-LB, LP10-Fc,
LP10-Hc, (where c is A, B, C, or D), LPT20xx, LP14, LP25, LP26, LP27,
LP05, LP14, LP07, or LN01. The LN01 is a laser printer.
16-1
LINE PRINTERS (LPT)
16.2 LINE PRINTER DATA MODES
The buffer size for a line printer is 37 (octal) words.
A line printer can use any of the following data modes:
o In ASCII mode, ASCII characters are sent to the line printer
exactly as they appear in the buffer. The line printer
prints from 1 to 8 spaces for a tab, feeds four lines for a
vertical tab, and skips to top-of-page for a formfeed; a
linefeed moves the paper up one line and returns the carriage
to the left position; a carriage-return returns the carriage
return to the left position.
o ASCII line mode is identical to ASCII mode.
o 8-bit ASCII mode is allowed only on a line printer attached
to a network line. Otherwise, it functions identically to
ASCII mode.
o Image mode is identical to ASCII mode.
16.3 LINE PRINTER I/O
The monitor normally sends a formfeed to the line printer on the first
OUT or OUTPUT call, and on a CLOSE call. Your program can suppress
these formfeeds by setting the IO.SFF bit in the I/O status word.
The DEVOP. call reads and sets various line printer characteristics,
and performs other operations for line printers. For local-line
printers and console front-end printers, use DEVSTS. to read line
printer characteristics. Refer to Chapter 22 in Volume 2.
16-2
LINE PRINTERS (LPT)
16.4 LINE PRINTER I/O STATUS
The I/O status bits for the line printer are as follows:
Bits Symbol Meaning
23 IO.ACT Device active.
25 IO.SVF Suppresses the vertical format unit on a line
printer. This allows LN01 fonts and graphics to
print correctly. Refer to the TOPS-10 Operating
System Commands Manual for information on using LN01
fonts.
29 IO.SFF Suppress formfeeds on OUT, OUTPUT, and CLOSE monitor
calls.
32-35 IO.MOD Data mode:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
4 .IOAS8 8-bit ASCII mode, for network line
printers only.
10 .IOIMG Image mode.
16-3
17-1
CHAPTER 17
CARD READERS (CDR) AND CARD PUNCHES (CDP)
TOPS-10 supports two card readers and 2 card punch units for each CPU
(KL processors only) on the system. For KS processors, one reader is
supported, but no card punch device is supported. A card reader is an
input device that can be connected to an MPX (multi-plexed) channel.
A card punch is an output device to punch data on punched cards, which
are then read by the card reader.
A card reader can read cards in either 026 code or in ANSI code. The
first card contains a punch code in column 1 that shows which code is
used: 12-11-8-9 for 026 code or 12-0-2-4-6-8 for ANSI code.
See the Commands Manual for a table of ASCII codes, ANSI card codes,
026 card codes, and binary coded decimal (BCD) codes.
The end-of-file for a card deck is indicated in one of two ways:
o The deck ends with an end-of-file card (12-11-0-1-6-7-8-9 in
column 1).
o The operator or user presses the end-of-file key on the card
reader.
17.1 CARD DEVICE NAMES
The card reader names are CDRnn0 and CDRnn1 and the card punch names
are CDPnn0 and CDPnn1.
Where: nn is the node number.
The unit name of a card reader is one of the following: CR10-D,
CR10-E, or CR10-F.
The unit name of a card punch is either CP10A or CP10D.
17-1
CARD READERS (CDR) AND CARD PUNCHES (CDP)
17.2 CARD READER DATA MODES
A card reader can use any of five data modes:
1. In ASCII mode,all 80 columns of each card are translated to
ASCII characters and placed in the buffer. A header card can
be the first card in the file; if so, this card indicates in
column 1 whether the deck is in 026 code (12-11-8-9 punch) or
in ANSI code (12-0-2-4-6-8 punch).
The card reader service routine inserts a carriage-return and
a linefeed after each card. As many cards as possible are
read into the buffer; data from a card is not divided between
buffers. For the default buffer size of 24 (octal) words,
data from only one card is placed in a buffer.
2. ASCII line mode is identical to ASCII mode.
3. In image mode, each buffer is 36 (octal) words and receives
one card of 80 characters. Each character is placed in the
buffer as a 12-bit byte; the last byte of the buffer is not
used.
4. In image binary mode, column 1 of each card must contain a
7-9 punch (to verify that the mode is image binary). If this
punch is missing, the monitor sets the IO.IMP bit in the file
status word. Column 1 also contains the word count for the
card in punch fields 12 through 3. Column 2 contains a
12-bit folded checksum. For image binary mode, a buffer is
35 (octal) words long.
The folded checksum is formed by adding the data words (two's
complement arithmetic), then dividing the result into three
12-bit bytes that are added (one's complement arithmetic).
5. In superimage mode, the 36 bits from the I/O bus are placed
(BLKI) directly into the buffer. To use superimage mode,
your program must set the IO.SIM bit in the file status word.
The buffer size in superimage mode is 123 (octal) words.
17-2
CARD READERS (CDR) AND CARD PUNCHES (CDP)
17.3 CARD PUNCH DATA MODES
A card punch can use any of five data modes:
1. In ASCII mode, characters are read from the buffer and
punched in a card code (026 code if IO.D29 is not set; ANSI
code if IO.D29 is set). Each buffer contains up to 80 ASCII
characters, and is punched on one card. Tabs are simulated
by punching from 1 to 8 blanks; a linefeed ends a card and
begins a new one; formfeeds and carriage-returns are ignored;
all other nontranslatable characters are punched as question
marks. A buffer in ASCII mode is 23 (octal) words.
A card can be split between buffers, but an attempt to punch
more than 80 characters on a card sets the IO.BKT bit in the
file status word.
On the first OUT or OUTPUT call to the card punch, an entire
card is punched indicating which card code is used: 12-2-4-8
punches for 026 code; 12-2-4-6-8 punches for ANSI code.
On a CLOSE monitor call to the card punch, the monitor
punches the last card (from the buffer) and punches an
end-of-file card.
2. ASCII line mode is identical to ASCII mode.
3. In image mode, each 12-bit byte of data from the buffer is
punched as one card column; the last byte in the last word is
discarded. (The monitor usually sets up this handling using
36-bit bytes; if your program specifies 12-bit bytes, it must
skip the last byte in the buffer.) For image mode, the buffer
size is 36 (octal).
On a CLOSE monitor call to the card punch, the monitor
punches the last card (from the buffer) and punches an
end-of-file card.
4. In image binary mode, one card is punched for each output
buffer. A buffer is 36 (octal) words. Your program should
not force output after each 80 columns, since this wastes
disk space if the output file is spooled.
On a CLOSE monitor call to the card punch, the monitor
punches the last card (from the buffer) and punches an
end-of-file card.
17-3
CARD READERS (CDR) AND CARD PUNCHES (CDP)
5. In binary mode, each card contains data in columns 3 through
80. A buffer is 35 (octal) words. Column 1 contains a
binary word count in punches 12 through 3, and a 7-9 punch;
column 2 contains a folded checksum.
The folded checksum is formed by adding the data words (two's
complement arithmetic), then dividing the result into three
12-bit bytes that are added (one's complement arithmetic).
17.4 CARD DEVICE I/O
On each interrupt for card readers and punches connected to the I/O
bus, the device status word is updated (it stores the result of a CONI
in the DDB); use the DEVSTS monitor call to retrieve the status.
On a CLOSE monitor call to the card punch, the monitor punches the
last card (from the buffer) and punches an end-of-file card. The
end-of-file card and columns 2 through 80 of the header card contain
the same punch that appears in column 1 for file identification. On
input, these punches are ignored by the device service routine.
17.5 CARD DEVICE I/O STATUS
The I/O status bits for the card reader and card punch are as follows:
Bits Symbol Meaning
18-21 IO.ERR Error flags:
Flag Symbol Error
18 IO.IMP Column 1 of a card presumed binary
did not have 7-9 punch; the reader
is stopped. (For card reader
only.)
19 IO.DER For card reader, a photocell error
occurred, indicating that a card
motion error caused data to be
missed; the reader is stopped. For
card punch, a punch error occurred.
20 IO.DTE Checksum read from card different
from computed checksum; the reader
is stopped. (For card reader
only.)
21 IO.BKT End-of-file reached with data still
in buffer. Attempted to punch more
than 80 columns on one card (card
punch only).
17-4
CARD READERS (CDR) AND CARD PUNCHES (CDP)
22 IO.EOF End-of-file card read or end-of-file key pressed
(card reader only).
23 IO.ACT Device active.
29 IO.SIM Superimage mode for card readers.
29 IO.D29 For card punches, specifies that ANSI codes should
be punched in ASCII mode. If this bit is cleared,
punch codes will be 026.
32-35 IO.MOD Data mode:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
10 .IOIMG Image mode.
13 .IOIBN Image binary mode.
14 .IOBIN Binary mode.
17-5
18-1
CHAPTER 18
PAPERTAPE READERS (PTR) AND PUNCHES (PTP)
TOPS-10 supports one papertape reader and one papertape punch for each
CPU on the system.
18.1 PAPERTAPE DEVICE NAMES
The physical name of the papertape reader on a system is PTRnn0 and
the name of a papertape punch is PTPnn0.
Where: nn is the node number of the system for the reader.
The unit name of a papertape reader is PC04 or PC05. The unit name of
a papertape punch is PC09.
18.2 PAPERTAPE READER DATA MODES
The buffer size for a papertape reader is 43 (octal) words.
A papertape reader uses any of five data modes: ASCII, ASCII line,
image, binary image, or binary. For all these data modes, the
physical end-of-tape sets the end-of-file bit (IO.EOF) in the file
status word, but does not send an end-of-file character to the buffer.
1. In ASCII mode, the monitor ignores blanks (000), delete
characters (377), and nulls (200). The parity bit (punch 8)
is not sent to the buffer, so that characters put into the
buffer are 7-bit ASCII.
2. In ASCII line mode, the monitor behaves the same as in ASCII
mode, except that each line ends with a linefeed, a formfeed,
or a vertical tab.
3. In image mode, 8-bit characters are copied into the buffer
exactly as they are received from the reader.
18-1
PAPERTAPE READERS (PTR) AND PUNCHES (PTP)
4. In image binary mode, if punch 8 is not punched, the
character is ignored; otherwise, the first six punch fields
are sent to the buffer as a SIXBIT character.
5. In binary mode, the monitor reads checksummed binary data
into the buffer. The right half of the first word of each
physical block contains the number of data words that follow;
the left half contains half of the folded checksum.
The folded checksum is formed by adding the data words (two's
complement arithmetic), then dividing the result into three
12-bit bytes that are added (one's complement arithmetic).
The maximum block length is 40 (octal) words. The byte
pointer is initialized to point to the second word, skipping
the word containing the word count and folded checksum.
18.3 PAPERTAPE PUNCH DATA MODES
The buffer size for a papertape punch is 43 (octal) words. A
papertape punch uses any of five data modes:
1. In ASCII mode, ASCII characters are sent to the punch. For
each character, the 8th hole is punched if needed to make
even parity.
2. In ASCII line mode, ASCII characters are sent to the punch.
A tapefeed character (000) is inserted after each formfeed.
A delete character is inserted after each vertical tab and
horizontal tab. Nulls are deleted. ASCII line mode is
identical to ASCII mode.
3. In image mode, 8-bit characters are sent to the punch,
exactly as they appear in the buffer.
4. In image binary mode, SIXBIT characters are sent to the
punch, exactly as they appear in the buffer. For each
character, the 7th hole is left unpunched and the 8th is
punched. There is no format control, and no checksumming.
5. In binary mode, each bufferful of data is sent to the punch
as a single checksummed binary block. The format of this
block is described in the previous section. Several blank
characters are punched after each bufferful to provide visual
clarity.
18-2
PAPERTAPE READERS (PTR) AND PUNCHES (PTP)
18.4 PAPERTAPE I/O
On each interrupt, the papertape device status word is updated (it
stores the result of a CONI in the DDB); use the DEVSTS monitor call
to retrieve the status.
On the first OUT or OUTPUT call to the papertape punch, the monitor
sends two fanfolds of blank tape to the punch; on a CLOSE call, the
monitor sends one fanfold of blank tape. A CLOSE call does not
automatically append an end-of-file character to the data sent.
18.5 PAPERTAPE I/O STATUS
The I/O status bits for the papertape devices are listed below. Note
that IO.ERR (bits 18-21) can be set only for papertape readers.
Bits Symbol Meaning
18 IO.IMP Incomplete binary block.
20 IO.DTE Bad checksum in binary mode.
22 IO.EOF Physical end-of-tape found; no end-of-file character
is in the buffer.
23 IO.ACT Device active (for readers and punches).
32-35 IO.MOD Data mode:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
10 .IOIMG Image mode.
13 .IOIBN Image binary mode.
14 .IOBIN Binary mode.
18-3
19-1
CHAPTER 19
PLOTTERS (PLT)
TOPS-10 supports two plotters for each CPU on the system (KL processor
only).
19.1 PLOTTER DEVICE NAMES
The physical names of plotters are PLTnn0 and PLTnn1.
Where: nn is the node name.
19.1.1 Controller Names
The controller name for the plotters is XY10.
19.1.2 Unit Names
The unit names for the plotters are XY10A and XY10B.
19.2 PLOTTER DATA MODES
Data modes for the plotter are ASCII, ASCII line, image, image binary,
and binary.
For ASCII and ASCII line modes, five 7-bit characters are transmitted
per word. The monitor drops the leftmost bit of each 7-bit ASCII
character to form a SIXBIT character.
For image, binary image, and binary modes, the monitor sends the
contents of the buffer without change. Six SIXBIT characters are
transmitted per word.
19-1
PLOTTERS (PLT)
19.3 PLOTTER I/O
The buffer size for a plotter is 46 (octal) words. This buffer
contains characters that are interpreted by the plotter service
routine in sets of six SIXBIT bytes, as follows:
1. First in set: Raise pen.
2. Second in set: Lower pen.
3. Third in set: Move drum up (-x).
4. Fourth in set: Move drum down (x).
5. Fifth in set: Move carriage left (-y).
6. Sixth in set: Move carriage right (y).
Your program cannot combine pen movements with drum or carriage
movements. See the Hardware Reference Manual.
Some monitor calls have special behavior for the plotter:
1. On the first OUT or OUTPUT call, a raise-pen command is
prefixed to the output.
2. On a CLOSE call, a raise-pen command is prefixed to the data
remaining in the buffer.
3. After each interrupt, plotter status is updated (it stores
the result of a CONI in the DDB); to retrieve the status, use
the DEVSTS call.
19.4 PLOTTER I/O STATUS
The I/O status bits for the plotter are as follows:
Bits Symbol Meaning
23 IO.ACT Device active.
32-35 IO.MOD Data mode:
Code Symbol Meaning
0 .IOASC ASCII mode.
1 .IOASL ASCII line mode.
10 .IOIMG Image mode.
13 .IOIBN Image binary mode.
14 .IOBIN Binary mode.
19-2
CHAPTER 20
DISPLAY LIGHT PENS (DIS)
The device service routine for a display light pen device guarantees a
flicker-free picture if your job is locked in core; if the system is
lightly loaded, the picture may be satisfactory even if your job is
not locked in core. To lock your job in core, refer to the LOCK call.
20.1 DISPLAY LIGHT PEN NAMES
The physical name of the display light pen is DIS.
20.1.1 Unit Names
The TOPS-10 monitor supports the following display light pen units:
VR30, VB10C, Type 30, and type 340.
20.2 DISPLAY LIGHT PEN DATA MODES
A display light pen uses only image dump mode for its I/O; the device
uses no buffer.
20.3 DISPLAY LIGHT PEN I/O
For display light pen I/O, a few monitor calls behave in special ways.
The data mode for the device must be image dump mode (.IOIDP in
IO.MOD). The number of buffers must be zero.
On an IN or INPUT call, the value returned at the specified address is
the location of the last light pen hit, or -1 if none was detected.
20-1
DISPLAY LIGHT PENS (DIS)
On an OUT or OUTPUT call, the address given in the call is the address
of a table of commands. These commands are of four types:
1. An output command of the form:
IOWD buflength,buffer
Where: buflength is the length of the output buffer.
buffer is the address of the buffer.
2. A skip command of the form:
XWD 0,nextcmd
Where: nextcmd is the address of the next command to be
read.
3. An intensity command (except for Type 340) of the form:
XWD intensity,0
Where: intensity is the value of the desired intensity.
These values range from 4 (dim) to 13 (bright).
4. An end-list command of the form:
Z
that ends the command list.
The following two examples show how to use these command lists for
display pen devices. The first example is for a VR30 device. The
values at the last six labels define data for the device.
OUTPUT CHANNO,LIST ;Output data at command list
. . .
LIST: XWD 5,0 ;Intensity 5 (DIM)
IOWD 1,A ;Plot coordinates A
IOWD 5,SUBP1 ;Plot subpicture SUBP1
XWD 13,0 ;Intensity 13 (BRIGHT)
IOWD 1,C ;Plot coordinates C
IOWD 2,SUBP2 ;Plot subpicture SUBP2
XWD 0,LIST1 ;Skip to LIST1 for next command
. . .
LIST1: XWD 10,0 ;Intensity 10 (NORMAL)
IOWD 1,B ;Plot coordinates B
IOWD 1,D ;Plot coordinates D
Z ;End command list
20-2
DISPLAY LIGHT PENS (DIS)
A: XWD 6,6 ;X=6 Y=6
B: XWD 105,70 ;X=105 Y=70
C: XWD 70,105 ;X=70 Y=105
D: XWD 1000,200 ;X=1000 Y=200
SUBP1: BLOCK 5 ;Subpicture 1
SUBP2: BLOCK 2 ;Subpicture 2
The next example shows how to use the command list for a Type 340
display light pen. In this example, the coordinates and subpictures
are used more than once.
OUTPUT CHANNO,LIST ;Output data at command list
. . .
LIST: IOWD 1,A ;Start at (6,6)
IOWD 5,SUBP1 ;Draw a circle
IOWD 1,C ;Set to (70,105)
IOWD 5,SUBP1 ;Draw another circle
IOWD 1,B ;Set to (105,70)
IOWD 2,SUBP2 ;Draw a triangle
XWD 0,LIST1 ;Skip to LIST1 for next command
. . .
LIST1: IOWD 1,D ;Set to (1000,200)
IOWD 5,SUBP1 ;Draw a circle
IOWD 1,A ;Set to (6,6)
IOWD 2,SUBP2 ;Draw a triangle
Z ;End of command list
A: XWD 6,6 ;X=6 Y=6
B: XWD 105,70 ;X=105 Y=70
C: XWD 70,105 ;X=70 Y=105
D: XWD 1000,200 ;X=1000 Y=200
SUBP1: BLOCK 5 ;A circle
SUBP2: BLOCK 2 ;A triangle
20.4 DISPLAY I/O STATUS
The I/O status bits for the display are as follows:
Bits Symbol Meaning
23 IO.ACT Device active.
32-35 IO.MOD Data mode:
Code Symbol Meaning
15 .IOIDP Image dump mode.
20-3
21-1
CHAPTER 21
REMOTE DATA TERMINALS (RDA)
A remote data terminal is a multidrop or intelligent buffered
terminal. Remote data terminal devices exist only on DN80-series
remote concentrators running network software (ANF-10). The monitor
sets bit 35 in the DEVSTS word if the device is a multidrop device.
A remote data terminal can be multiplexed with other devices on an MPX
channel. It can perform nonblocking I/O and can be used for
programmed interrupts (refer to Chapter 6).
21.1 REMOTE DATA TERMINAL NAMES
A remote data terminal is identified by a device name in the form:
RDcnnu
Where: c is a letter in the range A through H.
nn is a 2-digit octal node number in the range 1 to 77.
u is a 1-digit octal unit number in the range 0 to 7.
For example, the device name RDA013 identifies the remote data
terminal on controller A at node 13 with unit number 3.
NOTE
No generic searches are allowed or performed for
remote data terminals; only the specific device name
can be used.
21-1
REMOTE DATA TERMINALS (RDA)
21.2 REMOTE DATA TERMINAL I/O
A remote data terminal uses a buffer of 103 (octal) words; three of
these are buffer header words. The first word contains a 2-character
function code (in ASCII) in bits 0 to 14; and (for multi-drop lines) a
3-character right-justified multidrop number in bits 15 to 35. The
multidrop number must have leading ASCII blank or zeros as needed.
21.3 REMOTE DATA TERMINAL DATA MODES
The monitor performs no processing of the data for remote data
terminals. The device sends and receives data exactly as it appears
in the buffer. The monitor does not insert fillers or delete
characters that are followed by RUBOUTs.
21.4 REMOTE DATA TERMINAL I/O STATUS
The I/O status bits for the remote data terminal are as follows:
Bits Symbol Meaning
18-21 IO.ERR Error flags:
Flag Symbol Error
18 IO.IMP Line number not in polling
sequence. This bit can be set on
an OUT/OUTPUT error, indicating
that an illegal drop number was
specified. (Drop number less than
5 characters or contains
non-alphanumeric characters.)
19 IO.DER Terminal is in polling list, but
device failed. This bit can be set
on either IN/INPUT or OUT/OUTPUT,
if the network connection is lost
for some reason. The DDB is not
deleted, but is retained, with the
device name set to ___nnu, rather
than RDxnnu. This is the name
assigned to unknown devices until
the user releases the device.
20 IO.DTE Error on the entire multi-drop
line.
21-2
REMOTE DATA TERMINALS (RDA)
21 IO.BKT User buffer exceeded maximum length
of DDCMP message. This bit is set
when the message is too large for
the I/O buffer.
22 IO.EOF End-of-file reached.
23 IO.ACT The device is active.
21-3
INDEX
-A- Buffers
DECtape, 13-2
Abbreviating disk names, 12-3 disk, 12-43
Aborting a network connection, magtape, 14-2
5-34 terminal, 15-1
Account
NSP., 5-12 -C-
strings, 11-68
Active Card punch I/O, 17-1
search list, 12-28 Card reader I/O, 17-1
task, 5-4 Card reader/punch device names,
Addressing, 2-1 17-1
ALL search list, 11-10 CCL entry, 2-13
Allocating disk blocks, 11-61 CFP, 12-13
ANF-10, 5-1 Channel status, 5-21
Appending to files, 11-28 Cluster, 11-62
APR Command
clock, 3-6 files, 2-13
traps, 9-6 Command list definition, 11-15
APRENB traps, 6-2 Compiling programs, 3-1
Assigning PIDs, 7-15 Compressed File Pointer, 12-13
Associated variable, 7-11 Connect block, 5-12
Asynchronous Connect Received state, 5-20,
buffered input, 11-40 5-22
buffered output, 11-43 Connect Sent state, 5-22
Asynchronous programming, 5-24 Connect Wait state, 5-22, 5-34
AUX ON/OFF, 15-15 CONSO skip chain, 9-2
Context handling, 3-4
-B- Core, 2-1
CPPC, 2-3
BACKUP date/time, 11-67 CPPL, 2-2
Backward read mode, 14-12 Creating buffers, 11-48
Big buffers, 12-43 CREDIR program, 12-14
Bit mask, 1-3 CTY device, 11-7
Blocks, 12-1 CVPC, 2-3
Break character set, 15-8 CVPL, 2-3
Buffer
control block, 11-33 -D-
header, 11-33
quotas, 5-26 Data messages, 5-27
rings, 11-33 Data modes, 11-13
use bit, 11-35 card punch, 17-3
size, 11-37 card reader, 17-2
use bit, 11-37 DECtape, 13-1
Buffered line printer, 16-2
I/O, 11-31 magtape, 14-2
input, 11-39 papertape punch, 18-2
output, 11-40, 11-42 papertape reader, 18-1
Index-1
Data modes (Cont.) Disk (Cont.)
plotters, 19-1 parameters, 12-30
pseudo-terminal, 15-21 Disk-simulated library, 11-8
terminal, 15-1 Display light pen devices, 20-1
DATE monitor call, 3-6 DK10 clock, 3-6
DDBs, 11-44 DNET. UUO, 5-36
Dead reckoning, 13-4 DSK device, 12-2
Declaring data mode, 11-19
DECnet-10, 5-1 -E-
DECtape
controllers, 13-1 EBOX/MBOX runtime, 3-6
data blocks, 13-19 Enabling
device names, 13-1 PSI system, 5-25
directory, 13-11 realtime interrupts, 9-4
ENTERs, 13-9 End-of-file mark, 11-30
LOOKUPs, 13-7 End-of-message flag (NS.EOM),
RENAMEs, 13-9 5-28
Default ENQ.
break characters, 15-8 database, 8-23
disk, 12-2 header block, 8-11
path, 12-15 UUO, 8-15
protection codes, 12-8 ENQC. UUO, 8-19
search list, 12-29 Enter Passive function, 5-12
Deferred echo mode, 15-15 EOF, 11-30
Defining break characters, 15-9 Ersatz device names, 11-6
Deleting SFDs, 12-14 Eternal locks, 8-9
Density of magtapes, 14-1 Ethernet, 5-2
DEQ. UUO, 8-17 custom protocol development,
Destination task, 5-14 5-43
specifying, 5-12 endnode, 5-37
Device data blocks, 11-44 .EXE files, 3-1
Device-independant I/O, 11-4 Executive mode, 1-3
Devices, 11-3 Expiration dates, 11-68
Directory Extended
devices, 11-4 addressing, 2-3
file protection codes, 12-5 argument block, 11-54
path, 12-15 error codes, 11-31
protection codes, 12-26
search path, 12-16 -F-
DIS devices, 20-1
Disconnect Confirmed state, 5-22, FENCE, 12-29
5-34 FILDAE, 12-5, 12-28
Disconnect Received state, 5-22, File, 12-1
5-34 extensions, 12-4
Disconnect Sent state, 5-22 names, 12-4
Disk owner, 12-5
block, 12-1 positions, 11-62
buffers, 12-43 protection codes, 12-4
controllers, 12-3 status word, 11-30
data blocks, 12-10 structures, 12-1
device names, 12-2 File Daemon, 12-5, 12-28
file specification, 12-14 FILOP. UUO, 11-25
Index-2
Flow control, 5-20 Input
Format type task descriptor, 5-14 goal, 5-26
Full file access, 12-28 spooling, 11-12
Full-SCNSER PTY, 15-19 terminal characters, 15-3
Inserting breakpoints, 10-8
-G- Intercepts, 6-4
Interprocess Communication
Generic device names, 11-5 Facility (IPCF), 7-1
GETSEG UUO, 2-11 Interrupt
GPPL, 2-2 control flags, 6-14
GVPL, 2-2 flags, 9-7
messages, 5-27, 5-32
-H- requests, 6-9
Interrupts, 6-1
Hardware instructions, 1-1 Intertask communication, 5-4
High priority run queues, 9-19 Invisible requests, 8-6
High segment, 2-5 IOT privilege, 9-4
origin, 2-7 IPCF
High-precision runtime, 3-6 privileges, 7-13
Host node, 5-2 quota, 7-10
HPQ UUO, 9-19 IPCFQ. UUO, 7-12
HSC-50 nodes, 11-5 IPCFR. UUO, 7-11
IPCFS. UUO, 7-10
-I-
-J-
I/O
error recovery, 11-30 .JBINT, 6-5
Interrupt Reasons, 6-15 JBPFH, 2-15
modes, 1-3, 11-13 JBxxx symbols, 4-1
pointers, 11-27 JDA, 4-1
programming, 11-1 Job-wide PIDs, 7-16
I/O status Job/Context handle (JCH), 3-5
flags, 11-69 JOBDAT, 4-1
word, 11-30, 11-63 JSL, 11-10
I/O status bits
card reader/punch, 17-4 -K-
DECtape, 13-20
disk, 12-44 K (1000 octal), 2-1
line printer, 16-3 KL-paging, 2-3
magtape, 14-5
papertape devices, 18-3 -L-
plotters, 19-2
pseudo-terminal, 15-21 Labelled magtapes, 14-1, 14-13
terminals, 15-17 LIB searching, 11-57
I/O-related error codes, 11-70 Line printer controllers, 16-1
IBM communications, 5-2 LINK program, 3-1
ICB, 6-12 Link quota, 5-27
Ignoring logical name definitions, Load balancing, 11-58
11-8 Local
Indirect node, 5-2
command files, 2-13 UUO, 1-2
PIDs, 7-4 Lock blocks, 8-11
Index-3
Lock-associated blocks, 8-9 Non-blocking IPCF, 7-4
Locking jobs, 2-17 Non-directory devices, 11-4
Logged-in quota, 11-65 Non-I/O interrupt conditions,
Logged-out quota, 11-66 6-15
Logical device names, 11-5 Non-superseding ENTER, 11-57
Long-term locks, 8-9 Non-zero sections, 2-3
Low segment, 2-5 Normal messages, 5-27
LUUO, 1-2 NSP. states
Connect Received, 5-22
-M- Connect Sent, 5-22
Disconnect Confirmed, 5-22
Magnetic tape I/O, 14-1 Disconnect Received, 5-22
Magtape Disconnect Sent, 5-22
data formats, 14-7 No Communication, 5-22
density, 14-1 No Confidence, 5-22
records, 14-3 No Link, 5-22
Mask No Resources, 5-22
bit, 1-3 Reject, 5-22
Master File Directory (MFD) Running, 5-22
continued, 12-13 NSP. UUO, 5-10
Master file directory (MFD), NUL device, 11-7
12-11
MDA-controlled devices, 11-13 -O-
Measuring
cache hit rates, 10-2 Object types for DECnet, 5-14
system performance, 10-1 Obtaining
Meddling, 2-8 PIDs, 7-15
Memory, 2-1 [SYSTEM]INFO's PID, 7-20
MFD, 12-11 Old PC, 4-4
Modes, 1-3 OPR device, 11-7
Modifying search lists, 12-29 Origin of a high segment, 2-7
Monitor calls, 1-1 Output spooling, 11-12
MPPL, 2-2 Outstanding IPCF messages, 7-10
MPX, 11-11 Owner PPN, 12-5
I/O, 11-43
MTA device, 14-1 -P-
Multiplexed (MPX) channels, 11-11,
11-43 Packed image mode, 15-3
MUUO, 1-2 Packet Header Block (PHB), 7-2
MVPL, 2-2 Page Fault Handler, 2-2, 2-15
Paging, 2-2, 2-14
-N- Papertape I/O, 18-1
terminal, 15-15
Names for devices, 11-4 Passive
Network Process Descriptor (NPD), search list, 12-28
5-5 task, 5-4
No Communication state, 5-22 Patching the monitor, 10-8
No Confidence state, 5-22 Path names, 11-10
No Link state, 5-22 Pathological device, 12-16
No Resources state, 5-22 Paths, 12-15
Node, 5-2 PERF. UUO, 10-3
name, 5-12 Performance meter modes, 10-1
Index-4
Performing Resource (Cont.)
DECtape I/O, 13-4 ownership request, 8-2
I/O, 11-1, 11-18 Restricted devices, 11-12
Physical Retrieval Information Block (RIB),
addressing, 2-1 11-54, 12-10
device names, 11-5 RTTRP UUO, 9-4
PID-specific receive, 7-5 RUN UUO, 2-10
PIM mode, 15-3 Running state, 5-22
Plotters, 19-1 Runtimes, 3-6
service routine, 19-2
PLT device, 19-1 -S-
Pooled resources, 8-4
Positioning DECtape, 13-4 SCAN switch, 12-18
Prime RIB, 12-10 Search lists, 12-28
Priorities Sections, 2-3
disk I/O, 12-30 Segment size, 5-15
Process identifier (PID), 7-3 Segments, 2-5
Programmed Software Interrupt Sender capability word, 7-9
(PSI) system, 5-24 SETSRC program, 12-29
Project-programmer number, 5-14 Setting
Protecting directories, 12-27 I/O pointers, 11-27
Protection codes, 12-4 MPPL, 2-3
Pseudo-ops, 1-1 SFD, 12-11
Pseudo-terminals, 15-17 Sharable high segment, 2-5, 2-7
PSI Sharer group numbers, 8-4
enabling system, 5-25 Simultaneous file access, 8-1
interrupts, 6-8 SN%SHR, 2-7
PTP devices, 18-1 SNOOP. UUO, 10-9
PTR devices, 18-1 Software interrupts, 6-8
PTY Spare RIB, 12-10
devices, 15-17 Special system PIDs, 7-25
I/O, 15-19 Specifying disk files, 12-14
PTY-controlled job, 15-18 Spooled
file names, 11-12
-R- I/O, 11-11
SSL, 11-10
RDA devices, 21-1 String block, 5-12
Reading link status, 5-21 Sub-File Directory (SFD), 12-11
Realtime continued, 12-14
jobs, 9-1 deleting, 12-14
traps, 9-6 Superseding DECtape files, 13-9
Reason codes, 5-35 SUSET. UUO, 11-29
Reject state, 5-22 Suspending PTY I/O, 15-19
.REL files, 3-1 Swapping, 2-1
Releasing locks, 8-17 Symbol files, 1-3
Relinquishing resources, 8-9, Synchronous I/O, 11-28
8-17 System
Remote data entry devices, 21-1 time, 3-7
Remote station, 5-2 System file protection, 12-8
Requesting locks, 8-15 System PIDs, 7-8
Resource [SYSTEM]INFO functions, 7-15
definition, 8-3 [SYSTEM]IPCC functions, 7-20
Index-5
-T- Updating LIB, 11-57
Use bit
Tape label format, 14-13 buffer, 11-37
Task descriptor block, 5-12 buffer ring, 11-35
Task to task communication, 5-4 User
Task to task communications, 5-9 ID for NSP., 5-12
Terminal User file directory, 12-11
break characters, 15-8 User mode, 1-3
buffer size, 15-1 User-defined logical names, 11-7
device names, 15-1 UUOs, 1-1
I/O, 15-1
simulation, 15-17 -V-
Testing error bits, 11-30
.TMP files, 2-14 Vectored interrupts, 9-3
TMPCOR, 2-13 Vestigial job data area, 4-6
Traps, 6-1 Virtual
TRPSET UUO, 9-19 addressing, 2-1
TSK device, 5-4 paging, 2-2
TSK. UUO, 5-7
TTY device, 11-7, 15-1 -W-
-U- Word, 2-1
UDX, 11-10
UFD, 12-11 -X-
Unit referencing, 11-29
Universal date standard, 3-7 XON/XOFF, 15-15
Index-6