Trailing-Edge
-
PDP-10 Archives
-
tops10v704_docc
-
10,7/docupd/mcv1.mem
Click 10,7/docupd/mcv1.mem to
see without markup as text/plain
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