TOPS-20 Monitor Calls User's Guide | | | Electronically Distributed | | | | This manual describes the use of TOPS-20 monitor | calls, which provide user programs with system | services such as input/output, process control, | file handling, and device control. | | This manual supersedes the TOPS-20 Monitor Calls | User's Guide published in June 1988. The order | number for that document, AA-D859DM-TM, is | obsolete. Change bars in the margins indicate material that has been added or changed since the previous printing of this manual. Operating System: TOPS-20 Version 7.0 digital equipment corporation maynard, massachusetts | TOPS-20 Software Update Tape No. 04, November 1990 First Printing, May 1976 Revised, April 1982 Revised, September 1985 Revised, June 1988 | Revised, November 1990 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 1976, 1982, 1985, 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 1.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 1-1 1.2 MONITOR CALLS . . . . . . . . . . . . . . . . . . 1-2 1.2.1 Calling Sequence . . . . . . . . . . . . . . . . 1-3 1.2.2 Error Returns . . . . . . . . . . . . . . . . . 1-4 1.3 PROGRAM ENVIRONMENT . . . . . . . . . . . . . . . 1-6 CHAPTER 2 INPUT AND OUTPUT USING THE TERMINAL 2.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 2-1 2.2 PRIMARY I/O DESIGNATORS . . . . . . . . . . . . . 2-2 2.3 PRINTING A STRING . . . . . . . . . . . . . . . . 2-3 2.4 READING A NUMBER . . . . . . . . . . . . . . . . . 2-4 2.5 WRITING A NUMBER . . . . . . . . . . . . . . . . . 2-5 2.6 INITIALIZING AND TERMINATING THE PROGRAM . . . . . 2-7 2.6.1 RESET% Monitor Call . . . . . . . . . . . . . . 2-8 2.6.2 HALTF% Monitor Call . . . . . . . . . . . . . . 2-8 2.7 READING A BYTE . . . . . . . . . . . . . . . . . . 2-8 2.8 WRITING A BYTE . . . . . . . . . . . . . . . . . . 2-8 2.9 READING A STRING . . . . . . . . . . . . . . . . . 2-9 2.10 SUMMARY . . . . . . . . . . . . . . . . . . . . 2-14 CHAPTER 3 USING FILES 3.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 3-1 3.2 JOB FILE NUMBER . . . . . . . . . . . . . . . . . 3-2 3.3 ASSOCIATING A FILE WITH A JFN . . . . . . . . . . 3-3 3.3.1 GTJFN% Monitor Call . . . . . . . . . . . . . . 3-4 3.3.1.1 Short Form of GTJFN% . . . . . . . . . . . . . 3-4 3.3.1.2 Long Form of GTJFN% . . . . . . . . . . . . 3-12 3.3.1.3 Summary of GTJFN% . . . . . . . . . . . . . 3-15 3.4 OPENING A FILE . . . . . . . . . . . . . . . . . 3-16 3.4.1 OPENF% Monitor Call . . . . . . . . . . . . . 3-16 3.5 TRANSFERRING DATA . . . . . . . . . . . . . . . 3-19 3.5.1 File Pointer . . . . . . . . . . . . . . . . . 3-20 3.5.2 Source and Destination Designators . . . . . . 3-20 3.5.3 Transferring Sequential Bytes . . . . . . . . 3-21 3.5.4 Transferring Strings . . . . . . . . . . . . . 3-22 3.5.5 Transferring Nonsequential Bytes . . . . . . . 3-24 3.5.6 Mapping Pages . . . . . . . . . . . . . . . . 3-24 3.5.6.1 Mapping File Pages to a Process . . . . . . 3-26 3.5.6.2 Mapping Process Pages to a File . . . . . . 3-27 3.5.6.3 Unmapping Pages in a Process . . . . . . . . 3-28 3.5.7 Mapping File Sections to a Process . . . . . . 3-28 3.6 CLOSING A FILE . . . . . . . . . . . . . . . . . 3-30 3.6.1 CLOSF% Monitor Call . . . . . . . . . . . . . 3-30 3.7 ADDITIONAL FILE I/O MONITOR CALLS . . . . . . . 3-31 3.7.1 GTSTS% Monitor Call . . . . . . . . . . . . . 3-31 3.7.2 JFNS% Monitor Call . . . . . . . . . . . . . . 3-33 3.7.3 GNJFN% Monitor Call . . . . . . . . . . . . . 3-36 3.8 SUMMARY . . . . . . . . . . . . . . . . . . . . 3-40 3.9 FILE EXAMPLES . . . . . . . . . . . . . . . . . 3-40 CHAPTER 4 USING THE SOFTWARE INTERRUPT SYSTEM 4.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 4-1 4.2 INTERRUPT CONDITIONS . . . . . . . . . . . . . . . 4-4 4.3 SOFTWARE INTERRUPT CHANNELS AND PRIORITIES . . . . 4-4 4.4 SOFTWARE INTERRUPT TABLES . . . . . . . . . . . . 4-6 4.4.1 Specifying the Software Interrupt Tables . . . . 4-6 4.4.2 Channel Table . . . . . . . . . . . . . . . . . 4-7 4.4.3 Priority Level Table . . . . . . . . . . . . . . 4-8 4.5 ENABLING THE SOFTWARE INTERRUPT SYSTEM . . . . . . 4-9 4.6 ACTIVATING INTERRUPT CHANNELS . . . . . . . . . . 4-9 4.7 GENERATING AN INTERRUPT . . . . . . . . . . . . 4-10 4.8 PROCESSING AN INTERRUPT . . . . . . . . . . . . 4-10 4.8.1 Dismissing an Interrupt . . . . . . . . . . . 4-11 4.9 TERMINAL INTERRUPTS . . . . . . . . . . . . . . 4-12 4.10 ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS . . 4-14 4.10.1 Testing for Enablement . . . . . . . . . . . . 4-14 4.10.2 Obtaining Interrupt Table Addresses . . . . . 4-15 4.10.2.1 The RIR% Monitor Call . . . . . . . . . . . 4-15 4.10.2.2 The XRIR% Monitor Call . . . . . . . . . . . 4-15 4.10.3 Disabling the Interrupt System . . . . . . . . 4-16 4.10.4 Deactivating a Channel . . . . . . . . . . . . 4-16 4.10.5 Deassigning Terminal Codes . . . . . . . . . . 4-17 4.10.6 Clearing the Interrupt System . . . . . . . . 4-17 4.11 SUMMARY . . . . . . . . . . . . . . . . . . . . 4-17 4.12 SOFTWARE INTERRUPT EXAMPLE . . . . . . . . . . . 4-18 CHAPTER 5 PROCESS STRUCTURE 5.1 USES FOR MULTIPLE PROCESSES . . . . . . . . . . . 5-2 5.2 PROCESS COMMUNICATION . . . . . . . . . . . . . . 5-3 5.2.1 Direct Process Control . . . . . . . . . . . . . 5-4 5.2.2 Software Interrupts . . . . . . . . . . . . . . 5-4 5.2.3 IPCF and ENQ/DEQ Facilities . . . . . . . . . . 5-4 5.2.4 Memory Sharing . . . . . . . . . . . . . . . . . 5-5 5.3 PROCESS IDENTIFIERS . . . . . . . . . . . . . . . 5-5 5.4 OVERVIEW OF MONITOR CALLS FOR PROCESSES . . . . . 5-7 5.5 CREATING A PROCESS . . . . . . . . . . . . . . . . 5-8 5.5.1 Process Capabilities . . . . . . . . . . . . . 5-11 5.6 SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A PROCESS . . . . . . . . . . . . . . . . . . . . 5-11 5.6.1 GET% Monitor Call . . . . . . . . . . . . . . 5-11 5.6.2 PMAP% Monitor Call . . . . . . . . . . . . . . 5-14 5.7 STARTING AN INFERIOR PROCESS . . . . . . . . . . 5-15 5.8 INFERIOR PROCESS TERMINATION . . . . . . . . . . 5-16 5.9 INFERIOR PROCESS STATUS . . . . . . . . . . . . 5-17 5.10 PROCESS COMMUNICATION . . . . . . . . . . . . . 5-19 5.11 DELETING AN INFERIOR PROCESS . . . . . . . . . . 5-20 5.12 PROCESS EXAMPLES . . . . . . . . . . . . . . . . 5-21 CHAPTER 6 ENQUEUE/DEQUEUE FACILITY 6.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 6-1 6.2 RESOURCE OWNERSHIP . . . . . . . . . . . . . . . . 6-2 6.3 PREPARING FOR THE ENQ/DEQ FACILITY . . . . . . . . 6-3 6.4 USING THE ENQ/DEQ FACILITY . . . . . . . . . . . . 6-6 6.4.1 Requesting Use of a Resource . . . . . . . . . . 6-6 6.4.1.1 ENQ% Functions . . . . . . . . . . . . . . . . 6-6 6.4.1.2 ENQ% Argument Block . . . . . . . . . . . . . 6-8 6.4.2 Releasing a Resource . . . . . . . . . . . . . 6-12 6.4.2.1 DEQ% Functions . . . . . . . . . . . . . . . 6-13 6.4.2.2 DEQ% Argument Block . . . . . . . . . . . . 6-14 6.4.3 Obtaining Information About Resources . . . . 6-14 6.5 SHARER GROUPS . . . . . . . . . . . . . . . . . 6-17 6.6 AVOIDING DEADLY EMBRACES . . . . . . . . . . . . 6-19 CHAPTER 7 INTER-PROCESS COMMUNICATION FACILITY 7.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 7-1 7.2 QUOTAS . . . . . . . . . . . . . . . . . . . . . . 7-1 7.3 PACKETS . . . . . . . . . . . . . . . . . . . . . 7-2 7.3.1 Flags . . . . . . . . . . . . . . . . . . . . . 7-3 7.3.2 PIDs . . . . . . . . . . . . . . . . . . . . . . 7-5 7.3.3 Length and Address of Packet Data Block . . . . 7-6 7.3.4 Directories and Capabilities . . . . . . . . . . 7-6 7.3.5 Packet Data Block . . . . . . . . . . . . . . . 7-6 7.4 SENDING AND RECEIVING MESSAGES . . . . . . . . . . 7-7 7.4.1 Sending a Packet . . . . . . . . . . . . . . . . 7-7 7.4.2 Receiving a Packet . . . . . . . . . . . . . . . 7-9 7.5 SENDING MESSAGES TO INFO . . . . . . . . 7-12 7.5.1 Format of INFO Requests . . . . . . . 7-13 7.5.2 Format of INFO Responses . . . . . . . 7-14 7.6 PERFORMING IPCF UTILITY FUNCTIONS . . . . . . . 7-15 CHAPTER 8 USING EXTENDED ADDRESSING 8.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 8-1 8.2 ADDRESSING MEMORY AND ACS . . . . . . . . . . . . 8-2 8.2.1 Instruction Format . . . . . . . . . . . . . . . 8-3 8.2.2 Indexing . . . . . . . . . . . . . . . . . . . . 8-4 8.2.3 Indirection . . . . . . . . . . . . . . . . . . 8-5 8.2.3.1 Instruction Format Indirect Word (IFIW) . . . 8-5 8.2.3.2 Extended Format Indirect Word (EFIW) . . . . . 8-6 8.2.3.3 Macros for Indirection . . . . . . . . . . . . 8-6 8.2.4 AC References . . . . . . . . . . . . . . . . . 8-6 8.2.5 Extended Addressing Examples . . . . . . . . . . 8-7 8.2.6 Immediate Instructions . . . . . . . . . . . . . 8-8 8.2.6.1 XMOVEI . . . . . . . . . . . . . . . . . . . . 8-8 8.2.6.2 XHLLI . . . . . . . . . . . . . . . . . . . . 8-9 8.2.7 Other Instructions . . . . . . . . . . . . . . . 8-9 8.2.7.1 Instructions that Affect the PC . . . . . . 8-10 8.2.7.2 Stack Instructions . . . . . . . . . . . . . 8-10 8.2.7.3 Byte Instructions . . . . . . . . . . . . . 8-10 8.3 USING MONITOR CALLS . . . . . . . . . . . . . . 8-11 8.3.1 Mapping Memory . . . . . . . . . . . . . . . . 8-12 8.3.1.1 Mapping File Sections to a Process . . . . . 8-12 8.3.1.2 Mapping Process Sections to a Process . . . 8-13 8.3.1.3 Creating Sections . . . . . . . . . . . . . 8-14 8.3.1.4 Unmapping a Process Section . . . . . . . . 8-15 8.3.2 Starting a Process in Any Section . . . . . . 8-16 8.3.3 Setting the Entry Vector in Any Section . . . 8-16 8.3.4 Obtaining Information About a Process . . . . 8-17 8.3.4.1 Memory Access Information . . . . . . . . . 8-17 8.3.4.2 Entry Vector Information . . . . . . . . . . 8-19 8.3.4.3 Page-Failure Information . . . . . . . . . . 8-19 8.3.5 Program Data Vectors . . . . . . . . . . . . . 8-19 8.3.5.1 Manipulating PDV Addresses . . . . . . . . . 8-20 8.3.5.2 PDV Names . . . . . . . . . . . . . . . . . 8-20 8.3.5.3 Version Number . . . . . . . . . . . . . . . 8-21 8.4 MODIFYING EXISTING PROGRAMS . . . . . . . . . . 8-21 8.4.1 Data Structures . . . . . . . . . . . . . . . 8-21 8.4.1.1 Index Words . . . . . . . . . . . . . . . . 8-22 8.4.1.2 Indirect Words . . . . . . . . . . . . . . . 8-22 8.4.1.3 Stack Pointers . . . . . . . . . . . . . . . 8-22 8.5 WRITING MULTISECTION PROGRAMS . . . . . . . . . 8-22 INDEX FIGURES 4-1 Basic Operational Sequence of the Software Interrupt System . . . . . . . . . . . . . . . . . 4-3 6-1 Deadly Embrace Situation . . . . . . . . . . . . . 6-5 6-2 Use of Sharer Groups . . . . . . . . . . . . . . 6-18 7-1 IPCF Packet . . . . . . . . . . . . . . . . . . . 7-2 8-1 Program Counter Address Fields . . . . . . . . . . 8-2 8-2 Instruction Word Address Fields . . . . . . . . . 8-4 8-3 Instruction Format Indirect Word . . . . . . . . . 8-5 8-4 Extended Format Indirect Word . . . . . . . . . . 8-6 TABLES 2-1 NOUT% Format Option . . . . . . . . . . . . . . . 2-6 2-2 RDTTY% Control Bits . . . . . . . . . . . . . . 2-10 3-1 Standard System Values for File Specifications . . 3-3 3-2 GTJFN% Flag Bits . . . . . . . . . . . . . . . . . 3-5 3-3 Bits Returned on GTJFN% Call . . . . . . . . . . 3-10 3-4 Long Form GTJFN% Argument Block . . . . . . . . 3-13 3-5 OPENF% Access Bits . . . . . . . . . . . . . . . 3-17 3-6 PMAP% Access Bits . . . . . . . . . . . . . . . 3-26 3-7 SMAP% Access Bits . . . . . . . . . . . . . . . 3-29 3-8 CLOSF% Flag Bits . . . . . . . . . . . . . . . . 3-30 3-9 Bits Returned on GTSTS% Call . . . . . . . . . . 3-31 3-10 JFNS% Format Options . . . . . . . . . . . . . . 3-34 3-11 GNJFN% Return Bits . . . . . . . . . . . . . . . 3-37 4-1 Software Interrupt Channel Assignments . . . . . . 4-5 4-2 Terminal Codes and Conditions . . . . . . . . . 4-12 5-1 Process Handles . . . . . . . . . . . . . . . . . 5-6 5-2 Inferior Process Characteristic Bits . . . . . . . 5-9 5-3 GET% Flag Bits . . . . . . . . . . . . . . . . . 5-12 5-4 GET% Argument Block . . . . . . . . . . . . . . 5-13 5-5 GET% Argument Block Flags . . . . . . . . . . . 5-13 5-6 Process Status Word . . . . . . . . . . . . . . 5-17 5-7 RFSTS% Status-Return Block . . . . . . . . . . . 5-18 6-1 ENQ% Functions . . . . . . . . . . . . . . . . . . 6-7 6-2 ENQ% Argument Block . . . . . . . . . . . . . . . 6-8 6-3 Lock Specification Flags . . . . . . . . . . . . 6-10 6-4 DEQ% Functions . . . . . . . . . . . . . . . . . 6-13 6-5 DEQ% Argument Block . . . . . . . . . . . . . . 6-14 6-6 ENQC% Flag Bits . . . . . . . . . . . . . . . . 6-16 7-1 Packet Descriptor Block Flags . . . . . . . . . . 7-3 7-2 Flags Meaningful on a MSEND% Call . . . . . . . . 7-8 7-3 Flags Meaningful on a MRECV% Call . . . . . . . 7-10 7-4 MRECV% Return Bits . . . . . . . . . . . . . . . 7-12 7-5 INFO Functions and Arguments . . . . . . 7-14 7-6 INFO Responses . . . . . . . . . . . . . 7-15 7-7 MUTIL% Functions . . . . . . . . . . . . . . . . 7-16 PREFACE The TOPS-20 Monitor Calls User's Guide is written for the assembly language user who is unfamiliar with the DECSYSTEM-20 monitor calls. The manual introduces the user to the functions that he can request of the monitor from within his assembly language programs. The manual also teaches him how to use the basic monitor calls for performing these functions. This manual is not a reference document, nor is it complete documentation of the entire set of monitor calls. It is organized according to functions, starting with the simple and proceeding to the more advanced. Each chapter should be read from beginning to end. A user who skips around in his reading will not gain the full benefit of this manual. Once the user has a working knowledge of the monitor calls in this _______ _______ _____ _________ document, he should then refer to the TOPS-20 Monitor Calls Reference ______ Manual for the complete descriptions of all the calls. To understand the examples in this manual, the user must be familiar with the MACRO language and the DECSYSTEM-20 machine instructions. _______ _____ _________ _________ ______ The TOPS-20 MACRO Assembler Reference Manual documents the MACRO _______ ____ _________ ______ language. The TOPS-20 LINK Reference Manual describes the linking _________________________ _________ _________ ______ loader. The DECsystem-10/DECSYSTEM-20 Processor Reference Manual contains the information on the machine instructions. These three manuals should be used together with the Monitor Calls User's Guide, and should be referred to when questions arise on the MACRO language ____________ __ or the instruction set. Another useful reference is Introduction to ____________ ________ ________ ___________ DECSYSTEM-20 Assembly Language Programming by Ralph E. Gorin, published by the Digital Press. It provides a thorough treatment of assembly language programming for the DECSYSTEM-20, emphasizing the analysis of programs and various methods of program synthesis. In addition, some of the examples in this manual contain macros and symbols (MOVX, TMSG, JSERR, or JSHLT, for example) from the MACSYM system file. This file is a universal file of definitions available iii to the user as a means of producing consistent and readable programs. Finally, the user should be familiar with the TOPS-20 Command Language _______ ______ _____ to enter and run the examples. The TOPS-20 User's Guide describes the _______ ________ _________ TOPS-20 commands and system programs. The TOPS-20 Commands Reference ______ Manual describes all operating system commands available to the nonprivileged user of TOPS-20. 4 CHAPTER 1 CHAPTER 1 INTRODUCTION INTRODUCTION 1.1 OVERVIEW 1.1 OVERVIEW A program written in MACRO assembly language consists of a series of statements, each statement usually corresponding to one or more machine language instructions. Each statement in the MACRO program may be one of the following types: 1. A MACRO assembler directive, or pseudo-operation (pseudo-op), such as SEARCH or END. These pseudo-ops are commands to the MACRO assembler and are performed when the program is ____________ _____ _________ assembled. Refer to the DECSYSTEM-20 MACRO Assembler _________ ______ Reference Manual for detailed descriptions of the MACRO pseudo-ops. 2. A MACRO assembler direct assignment statement. These statements are in the form symbol=value and are used to assign a specific value to a symbol. Assignment statements are processed by the MACRO assembler when the program is assembled. These statements do not generate instructions or data in the assembled program. 3. A MACRO assembler constant declaration statement, such as ONE: EXP 1 These statements are processed when the program is assembled. 4. An instruction mnemonic, or symbolic instruction code, such as MOVE or ADD. These symbolic instruction codes represent the operations performed by the central processor when the _________________________ program is executed. Refer to the DECsystem-10/DECSYSTEM-20 _________ _________ ______ Processor Reference Manual for detailed descriptions of the symbolic instruction codes. 1-1 INTRODUCTION INTRODUCTION 5. A monitor call, or JSYS, such as RESET or BIN. These calls are commands to the monitor and are performed when the program is executed. This manual describes the commonly-used _______ monitor calls. However, the user should refer to the TOPS-20 _______ _____ _________ ______ Monitor Calls Reference Manual for detailed descriptions of all the calls. When the MACRO program is assembled, the MACRO assembler processes the statements in the program by o translating symbolic instruction codes to binary codes. o relating symbols to numeric values. o assigning relocatable or absolute memory addresses. The MACRO assembler also converts each symbolic call to the monitor into a Jump-to-System (JSYS) instruction. 1.2 MONITOR CALLS 1.2 MONITOR CALLS Monitor calls are used to request monitor functions, such as input or output of data (I/O), error handling, and number conversions, during the execution of the program. These calls are accomplished with the JSYS instruction (operation code 104), where the address portion of the instruction indicates the particular function. Each monitor call has a predefined symbol indicating the particular monitor function to be performed (for example, OPENF% to indicate opening a file). The symbols are defined in a system file called MONSYM. Monitor calls defined in Release 4 and later require a percent sign (%) as the final character in the call symbol. Monitor calls defined prior to Release 4 do not require the %, but do accept it. The current convention is that all monitor calls use the % as part of the call symbol. This manual follows that convention. To use the symbols and to cause them to be defined correctly, the user's program must contain the statement SEARCH MONSYM at the beginning of the program. During the assembly of the program, the assembler replaces the monitor call symbol with an instruction containing the operation code 104 in the left half and the appropriate function code in the right half. Arguments for a JSYS instruction are placed in accumulators (ACs). Any data resulting from the execution of the JSYS instruction are returned in the accumulators or in an address in memory to which an accumulator points. Therefore, before the JSYS instruction can be executed, the appropriate arguments must be placed in the specific accumulators. 1-2 INTRODUCTION INTRODUCTION The system file MACSYM.MAC contains a number of useful macros for the assembly language programmer. To use MACSYM macros, the user's program must contain the statements SEARCH MACSYM .REQUIRE SYS:MACREL ;include support routines at the beginning of the program. Since most bits defined for use with the monitor have symbolic names, macros enable the programmer to utilize these bits without knowledge of their exact position. Several MACSYM macros that are especially valuable to the TOPS-20 assembly language programmer are MOVX, TXnn (where nn indicates one of the 64 test instructions provided by the hardware), and FLD. MOVX loads an AC with a constant using the proper MOVE instructions, depending on the constant's position in the word. The TXnn macros expand to allow all combinations of modification and testing to be defined. For example TXNN AC1,GS%EOF tests AC1 for the presence of GS%EOF, no modification, and skip if not equal to zero. This instruction will work regardless of the actual bit position of GS%EOF. The FLD macro causes a value to be right justified in a field. For example FLD(7,OF%BSZ) places the value 7 in position OF%BSZ, right justified at bit 5 (OF%BSZ is defined as bits 0-5). These macros will be used consistently throughout this document. 1.2.1 Calling Sequence 1.2.1 Calling Sequence Arguments for the calls are placed in accumulators 1 through 4 (AC1-AC4). If more than four arguments are required for a particular call, the arguments are placed in a list to which an accumulator points. The arguments for the calls are specific bit settings or values. These bit settings and values are defined in MONSYM with symbol names, which can be used in the program. In fact, it is recommended that the user write his program using symbols whenever possible. This makes the program easier to read by another user. Use of symbols also allows the values of the symbols to be redefined without requiring the program to be changed. In this manual, the arguments for the monitor calls are described with both the bit settings and the symbol names. All program examples are written using the symbol names. 1-3 INTRODUCTION INTRODUCTION The set of instructions that place the arguments in the accumulators is followed by one line of code giving the particular monitor call symbol. During the program's execution, control is transferred to the monitor when this line of code is reached. 1.2.2 Error Returns 1.2.2 Error Returns TOPS-20 provides a consistent way to handle all JSYS errors. For most monitor calls upon a successful return, the instruction following the call is executed. If an error occurs during the execution of the call, the monitor examines the instruction following the call. If the instruction is a JUMP instruction with the AC field specified as 12-17, the monitor transfers control to a user-specified address. If the instruction is not a JUMP instruction, the monitor generates an illegal instruction trap indicating an illegal instruction, which the user's program can process via the software interrupt system (refer to Chapter 4). If the user's program is not prepared to process the instruction trap, the program execution halts, and a message is output stating the reason for failure. To place a JUMP instruction in his program, the user can include a statement using one of six predefined symbols. These symbols are ERJMPR address (= JUMP 12,address) ERCALR address (= JUMP 13,address) ERJMPS address (= JUMP 14,address) ERCALS address (= JUMP 15,address) ERJMP address (= JUMP 16,address) ERCAL address (= JUMP 17,address) and cause the assembler to generate a JUMP instruction. The JUMP instruction is a non-operation instruction (that is, a no-op) as far as the hardware is concerned. However, the monitor executes the JUMP instruction by transferring control to the address specified, which is normally the beginning of an error processing routine written by the user. If the user includes the ERJMP symbol, control is transferred as though a JUMPA instruction had been executed, and control does not return to his program after the error routine is finished. If the user includes the ERCAL symbol, control is transferred as though a PUSHJ 17, address instruction had been executed. If the error routine executes a POPJ 17, instruction, control returns to the user's program at the location following the ERCAL. If the user includes the ERJMPR symbol, the monitor behaves the same as it would if the ERJMP symbol had been included, except that the last error encountered by the process is stored in the user's AC1. _______ _______ _____ _________ ______ (Refer to Appendix B of the TOPS-20 Monitor Calls Reference Manual for the list of error codes, mnemonics, and message strings.) The ERCALR symbol functions the same as ERCAL except the error code encountered is returned in the user's AC1. ERJMPS and ERCALS function similarly except the monitor suppresses the storing of the error code in the 1-4 INTRODUCTION INTRODUCTION user's AC1. Instead, AC1 is preserved and contains either the original contents from when the monitor call was given, or a partially updated value prior to the error. Prior to the implementation of the ERJMP/ERCAL facilities, certain monitor calls returned control to the user's program at various locations after the calling address. Approximately one third of the JSYSs return to the +1 address only on failure, and to the location immediately following that (the +2 address) on successful execution of the call. A few calls return +1, +2, or +3, dependent on varying conditions of success or failure (for examples, see ERSTR% or GACTF% _______ _______ _____ _________ ______ in the TOPS-20 Monitor Calls Reference Manual); and some calls do not return at all (see HALTF% or WAIT%). Refer to Chapter 3 of the _______ _______ _____ _________ ______ TOPS-20 Monitor Calls Reference Manual for the possible returns for each monitor call. When a failure occurs during the execution of a monitor call, the monitor stores an error code. The error code indicates the cause of the failure. This error code is usually stored in the right half of AC1, but can also be stored in the monitor's data base or a user's data block. In either case, you can obtain the message associated with the error by using the GETER% or ERSTR% call. The ERJMP/ERCAL facilities can also be used following a machine instruction, and will trap for the following conditions: o Illegal instruction o Illegal memory read o Illegal memory write o Pushdown list overflow The ERJMP/ERCAL facilities can be used after all monitor calls, regardless of whether the call has one or two returns. To handle errors consistently, users are encouraged to employ either the ERJMPR, ERCALR, ERJMPS, or ERCALS symbol with all calls. All of the six predefined jump symbols are no-ops, unless they immediately follow a monitor call or instruction that fails. Error codes can be obtained by the program and translated into their corresponding error mnemonic and message strings with the GETER% and ERSTR% monitor calls. TOPS-20 provides convenient macros and subroutines for handling monitor call error routines. They can be found in the system file MACSYM.MAC. Two such macros are EJSERR and EJSHLT. EJSERR prints out an error message and returns control to the next instruction following the failing monitor call. EJSHLT prints out an error message and halts processing of the program. The following is an example of executing the BIN% monitor call (see Chapter 3 for more information on this monitor call) that has a single 1-5 INTRODUCTION INTRODUCTION return. If the execution of the call is successful, the program reads and stores a character. If the execution of the call is not successful, the program transfers control to an error routine. This routine processes the error and then returns control back to the main program sequence. Note that ERCALS stores the return address on the stack. DOIT: MOVE T1,INJFN ;obtain JFN for input file BIN% ;input one character ERCALS ERROR ;call error routine if problem MOVEM T2,CHAR ;store character JRST DOIT ;and get another ERROR: GTSTS% ;read file status TXNE T2,GS%EOF ;end of file? JRST EOF ;yes, process end-of-file condition HRROI T1,[ASCIZ/ ?INPUT ERROR, CONTINUING /] ;no, data error PSOUT% ;print message RET ;return to program (POPJ 17,) The ASCIZ pesudo-op specifies a left-justified ASCII string terminated with a null (that is, a byte containing all bits equal to zero) byte. 1.3 PROGRAM ENVIRONMENT 1.3 PROGRAM ENVIRONMENT The user program environment in the TOPS-20 operating system consists of a job structure that can contain many processes. A process is a runnable or schedulable entity capable of performing computations in parallel with other processes. This means that a runnable program is associated with at least one process. Each process has its own address space for storing its computations. This address space is called virtual space because it is actually a "window" into physical storage. The address space is divided into 32 (decimal) sections. Each section is divided into 512 (decimal) pages, and each page contains 512 (decimal) words. Each word contains 36 bits. A process can communicate with other processes in the following ways: o explicitly, by software interrupts or system facilities (the inter-process communication facility, or IPCF, for example). o implicitly, by changing parts of its environment (its address space, for instance) that are being shared with other processes. A process can create other processes inferior to it, but there is one control process from which the chain of creations begins. A process 1-6 INTRODUCTION INTRODUCTION is said to exist when a superior process creates it and is said to end when a superior process deletes it. Refer to Chapter 5 for more information on the process structure. A set of one or more related processes, normally under control of a single user, is a job. Each active process is part of some job on the system. A job is defined by a user name, an account number, some open files, and a set of running and/or suspended processes. A job can be composed of several running or suspended programs. The following diagram illustrates a job structure consisting of four processes. ----------------- | | | TOP PROCESS | | | ----------------- | | | --------------------------- | | ---------------- --------------- | | | | | PROCESS A | | PROCESS B | | | | | ---------------- --------------- | | | --------------- | | | PROCESS C | | | --------------- Both process A and 1 process B are created by the TOP PROCESS and thus are directly inferior to it. Process C is created by process B and thus is directly inferior to process B only. Process C is indirectly inferior to the TOP PROCESS. In summary, processes can be considered as independent virtual jobs with well-defined relationships to other processes in the system, and a job is a collection of these processes. 1-7 2-1 CHAPTER 2 CHAPTER 2 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL One of the main reasons for using monitor calls is to transfer data from one location to another. This chapter discusses moving data to and from the user's terminal. 2.1 OVERVIEW 2.1 OVERVIEW Data transfers to and from the terminal are in the form of either individual bytes or text strings. The bytes are 7-bit bytes. The strings are ASCII strings ending with a 0 byte. These strings are called ASCIZ strings. To designate the desired string, the user's program must include a statement that points to the beginning of the string being read or written. The MACRO pseudo-op, POINT, can be used to set up this pointer, as shown in the following sequence of statements: MOVE AC1,PTR . . . PTR: POINT 7,MSG MSG: ASCIZ/TEXT MESSAGE/ Accumulator 1 contains the symbolic address (PTR) of the pointer. At the address specified by PTR is the pointer to the beginning of the string. The pointer is set up by the POINT pseudo-op. The general format of the POINT pseudo-op is: POINT decimal-byte-size,address,decimal-byte-position _______ _____ _________ _________ ______ (Refer to the TOPS-20 MACRO Assembler Reference Manual for more information on the POINT pseudo-op.) In the example above, the POINT pseudo-op has been written to indicate 7-bit bytes starting before the left-most bit in the address specified by MSG. 2-1 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL Another way of setting up an accumulator to contain the address of the pointer is with the following statement: HRROI AC1,[ASCIZ/TEXT MESSAGE/] The instruction mnemonic HRROI causes a -1 to be placed in the left half of accumulator 1 and the address of the string to be placed in the right half. However, in the above statement, a literal (enclosed in square brackets) has been used instead of a symbolic address. The literal causes the MACRO assembler to: o store data within brackets (the string) in a table. o assign an address to the first word of the data. o insert that address as the operand to the HRROI instruction. Literals have the advantage of showing the data at the point in the program where it will be used, instead of showing it at the end of the program. As far as the I/O monitor calls are concerned, a word in this format (-1 in the left half and an address in the right half) designates the system's standard pointer (that is, a pointer to a 7-bit ASCIZ string beginning before the leftmost byte of the string). The result of the HRROI statement is interpreted by the monitor as functionally equivalent to the word assembled by the POINT 7, address pseudo-op and is the recommended statement to use in preparation for a monitor call. However, byte manipulation instructions (for example, ILDB, IBP, ADJBP) will not operate properly with this type of pointer. After a string is read, the pointer is advanced to the character following the terminating character of the string. After a string is written, the pointer is advanced to the character following the last non-null character written. Most TOPS-20 monitor calls accept one-word global byte pointers when executed from a nonzero section (see Section 8.3). Global byte pointers are used with extended addressing and are fully explained in Chapter 8 of this document. Unless specifically stated, TOPS-20 monitor calls do not accept two-word global byte pointers. 2.2 PRIMARY I/O DESIGNATORS 2.2 PRIMARY I/O DESIGNATORS To transfer data from one location to another, the user's program must indicate the source from which the data is to be obtained and the destination where the data is to be placed. By default, the user's terminal is defined as the source and destination. The default can be _______ overridden by using the SPJFN% monitor call (refer to the TOPS-20 _______ _____ _________ ______ Monitor Calls Reference Manual). Examples in this book assume the 2-2 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL user's terminal to be the source (input) and destination (output) device. Two designators are used to represent the user's terminal: 1. The symbol .PRIIN to represent the user's terminal as the source (input) device. 2. The symbol .PRIOU to represent the user's terminal as the destination (output) device. These symbols are called the primary input and output designators and by default are used to represent the terminal running the program. They are defined in the system file MONSYM.MAC and do not have to be defined in the user's program as long as the program contains the statement SEARCH MONSYM 2.3 PRINTING A STRING 2.3 PRINTING A STRING Many times a program may need to print an error message or some other string, such as a prompt to request input from the user at the terminal. The PSOUT% (Primary String Output) monitor call is used to print such a string on the terminal. This call copies the designated string from the program's address space. Thus, the source of the data is the program's address space, and the destination for the data is the terminal. The program need only supply the pointer to the string being printed. Accumulator 1 (AC1) is used to contain the address of the pointer. After AC1 is set up with the pointer to the string, the next line of code is the PSOUT% call. Thus, an example of the PSOUT% call is: HRROI AC1,[ASCIZ/TEXT MESSAGE/] ;string to print PSOUT% ;print TEXT MESSAGE The PSOUT% call prints on the terminal all the characters in the string until it encounters a null byte. Note that the string is printed exactly as it is stored in the program, starting at the current position of the terminal's print head or cursor and ending with the last character in the string. If a carriage return and line feed are to be output, either before or after the string, these characters should be inserted as part of the string. For example, to print TEXT MESSAGE on one line and to output a carriage return-line feed after it, the user's program includes the call HRROI AC1,[ASCIZ/TEXT MESSAGE /] PSOUT% 2-3 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL After the string is printed, the instruction following the PSOUT% call in the user's program is executed. Also, the pointer in AC1 is updated to point to the character following the last non-null character written. The macro TMSG, found in the system file MACSYM, does the same thing as the example above. This macro offers the programmer a convenient way for printing messages on the terminal. For example TMSG caused the text message contained between the angle brackets, including the carriage return and line feed, to print on the terminal. The TMSG macro, along with others previously mentioned, will be used consistently in examples throughout this document. Refer to the system file MACSYM.MAC for further information on MACSYM macros. Refer to Section 1.2.2 for information concerning error returns. 2.4 READING A NUMBER 2.4 READING A NUMBER The NIN% (Number Input) monitor call is used to read an integer. This call does not assume the terminal as the source designator; therefore, the user's program must specify this. The NIN% call accepts the number from any valid source designator, including a string in memory. This section discusses reading a number directly from the terminal. Refer to Section 2.9 for an example of using the NIN% call to read the number from a string in memory. The destination for the number is AC2, and the NIN% call places the binary value of the number read into this accumulator. The user's program also specifies a number in AC3 that represents the radix of the number being input. The radix given can be in the range 2-36. Thus, the setup for the NIN% monitor call is the following: MOVEI AC1,.PRIIN ;AC1 contains the primary input designator ;(the user's terminal) MOVEI AC3,^D10 ;AC3 contains the radix of the number being ;input (in this case a decimal number) NIN% ;The call to input the number After completion of the NIN% call, control returns to the program at one of two places (refer to Section 1.2.2). If an error occurs during the execution of the call, control returns to the instruction following the call. This instruction should be a jump-type instruction to an error processing routine (see Section 1.2.2). Also, _______ an error code is placed in AC3 (refer to Appendix B of the TOPS-20 _______ _____ _________ ______ Monitor Calls Reference Manual for the error codes). If the execution 2-4 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL of the NIN% call is successful, control returns to the second instruction following the call. The number input from the terminal is placed in AC2. The NIN% call terminates when it encounters a nondigit character (for example, a letter, a punctuation character, or a control character). This means that if 32X1 were typed on the terminal, on return AC2 contains a 40 (octal) because the NIN% call terminated when it read the X. The following program prints a message and then accepts a decimal number from the user at the terminal. Note that the NIN% call terminates reading on any nondigit character; therefore, the user cannot edit his input with any of the editing characters (for example, DELETE, CTRL/W). The RDTTY% call (refer to Section 2.9) should be used in programs that read from the terminal because it allows the user to edit his input as he is typing it. SEARCH MONSYM HRROI AC1,[ASCIZ/ Enter # of seconds: /] PSOUT% ;output a prompt message MOVEI AC1,.PRIIN ;input from the terminal MOVEI AC3,^D10 ;use the decimal radix NIN% ;input a decimal number ERJMP NINERR ;error-go to error routine MOVEM AC2, NUMSEC ;save number entered . . . NUMSEC:BLOCK 1 . . . 2.5 WRITING A NUMBER 2.5 WRITING A NUMBER The NOUT% (Number Output) monitor call is used to output an integer. The user's program moves the number to be output into AC2. The program must specify the destination for the number in AC1 and the radix in which the number is to be output in AC3. The radix given cannot be greater than base 36. In addition, the user's program can specify certain formatting options to be used when printing the number. Thus, the general setup for the NOUT% monitor call is as follows: AC1: output designator AC2: number being output AC3: format options in left half and radix in right half 2-5 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL The format options that can be specified in the left half of AC3 are described in Table 2-1. Table 2-1: NOUT% Format Option Table 2-1: NOUT% Format Option ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 NO%MAG Print the number as a positive 36-bit number. For example, -1 would be printed as 777777 777777 if radix=8). 1 NO%SGN Print the appropriate sign (+ or -) before the number. If bits NO%MAG and NO%SGN are both on, a plus sign is always printed. 2 NO%LFL Print leading filler. If this bit is not set, trailing filler is printed and bit NO%ZRO is ignored. 3 NO%ZRO Use 0's as the leading filler if the specified number of columns allows filling. If this bit is not set, blanks are used as the leading filler if the number of columns allows filling. 4 NO%OOV Output on column overflow and return an error. If this bit is not set, column overflow is not output. 5 NO%AST Print asterisks when the column overflows. If this bit is not set, and bit 4 (NO%OOV) is set, all necessary digits are printed when the columns overflow. 6-10 Reserved for Digital (must be 0). 11-17 NO%COL Print the number of columns indicated. This value includes the sign column. If this field is 0, as many columns as necessary are printed. ______________________________________________________________________ The following instruction sequence is an example of the NOUT% monitor call. This sequence prints a number, stored in location NUMB, on the user's terminal. The number can be positive, negative or zero, with no special formatting. 2-6 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL MOVX AC1,.PRIOU ;use primary output MOVE AC2,NUMB ;get number from location NUMB MOVX AC3,^D10 ;no special format ;decimal radix NOUT% ;print number EJSHLT ;unexpected fatal error. Halt ;and print message. Refer to Section 1.2.2 for information concerning error returns. The following example illustrates the use of the three monitor calls described so far, as well as the TMSG macro. The RESET% and HALTF% monitor calls are described in Section 2.6. SEARCH MONSYM SEARCH MACSYM .REQUIRE SYS:MACREL AC1==1 AC2==2 AC3==3 START: RESET% ;prepare program environment HRROI AC1,[ASCIZ/PLEASE TYPE A DECIMAL NUMBER: /] PSOUT% MOVEI AC1,.PRIIN ;source designator MOVEI AC3,^D10 ;decimal radix NIN% ERJMPS ERROR ;if input error print message ;halt. TMSG MOVEI AC1,.PRIOU ;destination designator MOVEI AC3,^D8 ;octal radix NOUT% EJSHLT ;fatal error. ;Same as ERJMPS ERROR. HALTF% ;return to command language JRST START ;begin again, if continued ERROR: TMSG< ?ERROR-TYPE START TO BEGIN AGAIN> HALTF% JRST START ;user types continue-start ;again END START 2.6 INITIALIZING AND TERMINATING THE PROGRAM 2.6 INITIALIZING AND TERMINATING THE PROGRAM Two monitor calls that have not yet been described were used in the above program - RESET% and HALTF%. 2-7 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL 2.6.1 RESET% Monitor Call 2.6.1 RESET% Monitor Call A good programming practice is to include the RESET% monitor call at the beginning of every assembly language program. This call closes any existing open files and releases their JFNs, kills any inferior processes, clears the software interrupt system (see Chapter 4), and performs various other process initilization functions. For a complete list of the functions provided by the RESET% monitor call, _______ _______ _____ refer to the description of the call in the TOPS-20 Monitor Calls _________ ______ Reference Manual. The format of the call is RESET% and control always returns to the next instruction following the call. 2.6.2 HALTF% Monitor Call 2.6.2 HALTF% Monitor Call To stop the execution of a program and return control to the TOPS-20 Command Language, the user must include the HALTF% monitor call as the last instruction performed in the program. The user can then resume execution of the program at the instruction following the HALTF% call by typing the CONTINUE command after control has returned to command level. 2.7 READING A BYTE 2.7 READING A BYTE The PBIN% (Primary Byte Input) monitor call is used to read a single byte (that is, one character) from the terminal. The user's program does not have to specify the source and destination for the byte because this call uses the primary input designator (that is, the user's terminal) as the source and accumulator 1 as the destination. After execution of the PBIN% call, control returns to the instruction following the PBIN%. If execution of the call is successful, the byte read from the terminal is right-justified in AC1. If execution of the call is not successful, an illegal instruction trap is generated, as explained in Section 1.2.2. 2.8 WRITING A BYTE 2.8 WRITING A BYTE The PBOUT% (Primary Byte Output) monitor call is used to write a single byte to the terminal. This call uses the primary output designator (that is, the user's terminal) as the destination for the byte; thus, the user's program does not have to specify the destination. The source of the byte being written is accumulator 1; therefore, the user's program must place the byte right-justified in AC1 before the call. 2-8 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL After execution of the PBOUT% call, control returns to the instruction following the PBOUT%. If execution of the call is successful, the byte is written to the user's terminal. If execution of the call is not successful, an illegal instruction trap is generated, as explained in Section 1.2.2. 2.9 READING A STRING 2.9 READING A STRING Up to this point, monitor calls have been presented for printing a string, reading and writing an integer, and reading and writing a byte. The next call to be discussed obtains a string from the terminal and, in addition, allows the user at the terminal to edit his input as he is typing it. The RDTTY% (Read from Terminal) monitor call reads input from the user's terminal (that is, from .PRIIN) into the program's address space. Input is read until the user either types an appropriate terminating (break) character or inputs the maximum number of characters allowed in the string, whichever occurs first. Output generated as a result of character editing is printed on the user's terminal (that is, output to .PRIOU). The RDTTY% call handles the following editing functions: 1. Delete the last character in the string if the user presses the DELETE key while typing his input. 2. Delete back to the last punctuation character in the string if the user types CTRL/W while typing his input. 3. Delete the current line if the user types CTRL/U while typing his input. 4. Retype the current line if the user types CTRL/R while typing his input. Because the RDTTY% call can handle these editing functions, a program can accept input from the terminal and allow this input to be corrected by the user as he is typing it. For this reason, the RDTTY call should be used to read input from the terminal before processing that input with calls such as NIN%. The RDTTY% call accepts three words of arguments in AC1 through AC3. AC1: pointer to area in program's address space where input is to be placed. This area is called the text input buffer. AC2: control bits in the left half, and maximum number of bytes in the text input buffer in the right half. 2-9 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL AC3: pointer to buffer for text to be output before the user's input if the user types a CTRL/R, or 0 if only the user's input is to be output on a CTRL/R. The control bits in the left half of AC2 specify the characters on which to terminate the input. These bits are described in Table 2-2. Table 2-2: RDTTY% Control Bits Table 2-2: RDTTY% Control Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 RD%BRK Terminate input when user types a CTRL/Z or presses the ESC key. 1 RD%TOP Terminate input when user types one of the following: CTRL/G CTRL/L CTRL/Z ESC key RETURN key Line feed key 2 RD%PUN Terminate input when user types one of the following: CTRL/A-CTRL/F CTRL/H-CTRL/I CTRL/K CTRL/N-CTRL/Q CTRL/S-CTRL/T CTRL/X-CTRL/Y ASCII codes 34-36 ASCII codes 40-57 ASCII codes 72-100 ASCII codes 133-140 ASCII codes 173-176 The ASCII codes listed above represent the punctuation characters in the ASCII character set. Refer to the ASCII character set table in Appendix _______ _______ _____ A of the TOPS-20 Monitor Calls _________ ______ Reference Manual for these characters. 3 RD%BEL Terminate input when user types the RETURN or line feed key (that is, end of line). 2-10 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL 4 RD%CRF Store only the line feed in the input buffer when the user presses the RETURN key. A carriage return will still be output to the terminal but will not be stored in the buffer. If this bit is not set and the user presses the RETURN key, both the carriage return and the line feed will be stored as part of the input. 5 RD%RND Return to program if the user attempts to delete past the beginning of his input. This allows the program to take control if the user tries to delete all of his input. If this bit is not set, the program waits for more input. 6 Reserved for Digital (must be 0). 7 RD%RIE Return to program when there is no input (that is, the text input buffer is empty). If this bit is not set, the program waits for more input. 8 Reserved for Digital (must be 0). 9 RD%BEG Return to user program if the user attempts to edit beyond the beginning of the input buffer. 10 RD%RAI Convert lower case input to upper case. 11 RD%SUI Suppress the CTRL/U indication on the terminal when a CTRL/U is typed by the user. This means that if the user types a CTRL/U, XXX will not be printed and, on display terminals, the characters will not be deleted from the screen. If this bit is not set and the user types a CTRL/U, XXX will be printed and, if appropriate, the characters will be deleted from the screen. In neither case is the CTRL/U stored in the input buffer. 2-11 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL 15 RD%NED Disable editing characters in user break mask. If this bit is set, then any editing character (^R, ^U, ^V, ^W, and DELETE) in the user supplied break mask does not have its editing function. ______________________________________________________________________ If no control bits are set in the left half of AC2, the input will be terminated when the user presses the RETURN or line feed key (that is, terminated on an end-of-line condition only). The count in the right half of AC2 specifies the number of bytes available for storing the string in the program's address space. The input is terminated when this count is exhausted, even if a specified break character has not yet been typed. The pointer in AC3 is to the beginning of a buffer containing the text to be output if the user types a CTRL/R. When this happens, the text in this separate buffer is output, followed by any text that has been typed by the user. The text in this buffer cannot be edited with any of the editing characters (that is, DELETE, CTRL/W, or CTRL/U). If the contents of AC3 is zero, then no such buffer exists, and if the user types CTRL/R, only the text in the input buffer will be output. If execution of the RDTTY% call is successful, the input is in the specified area in the program's address space. The character that terminated the input is also stored. (If the terminating character is a carriage return followed by a line feed, the line feed is also stored.) Control returns to the user's program at the second location following the call. The pointer in AC1 is advanced to the character following the last character stored. The count in the right half of AC2 is updated to reflect the remaining bytes in the buffer, and appropriate bits are set in the left half of AC2. The bits that can be set on a successful return are: Bit 12 RD%BTM The input was terminated because one of the specified break characters was typed. This break character is placed in the input buffer. If this bit is not set, the input was terminated because the byte count was exhausted. Bit 13 RD%BFE Control was returned to the program because there is no more input and RD%RIE was set in the call. 2-12 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL Bit 14 RD%BLR The limit to which the user can backup for editing his input was reached. For consistent handling of error returns refer to Section 1.2.2. The following example illustrates the recommended method for reading data from the terminal. This example is essentially the same as the one in Section 2.5; however, the RDTTY% call is used to read the number before the NIN% call processes it. This program stores the last error encountered in location LASTER and therefore uses the ERJMPR pseudo-op. SEARCH MONSYM SEARCH MACSYM .REQUIRE SYS:MACREL AC1==1 AC2==2 AC3==3 START: RESET% ;prepare program environment HRROI AC1,PROMPT PSOUT% ;type prompt HRROI AC1,BUFFER ;location to store number MOVEI AC2,BUFLEN*5 ;size of buffer HRROI AC3,PROMPT ;pointer to prompt RDTTY% ;read number from term. with editing ERJMPR ERROR ;save error code, print message HRROI AC1,BUFFER ;and halt source designator MOVEI AC3,^D10 ;decimal radix NIN% ERJMPR ERROR ;if input error, print message TMSG MOVEI AC1,.PRIOU ;and halt destination designator MOVEI AC3,^D8 ;octal radix NOUT% ERJMPR ERROR ;save error code, print message HALTF% ;and halt return to command JRST START ;language begin again, if continued PROMPT: ASCIZ/PLEASE TYPE A DECIMAL NUMBER: / BUFLEN==10 BUFFER: BLOCK BUFLEN LASTER: BLOCK 1 ERROR: MOVEM AC1,LASTER ;save error code TMSG < ?ERROR-TYPE START TO BEGIN AGAIN>;print general error message HALTF% ;halt JRST START ;start over if continued END START 2-13 INPUT AND OUTPUT USING THE TERMINAL INPUT AND OUTPUT USING THE TERMINAL 2.10 SUMMARY 2.10 SUMMARY Data transfers of sequential bytes or text strings can be made to and from the terminal. The monitor calls for transferring bytes are PBIN% and PBOUT% and for transferring strings are PSOUT% and RDTTY%. The NIN% and NOUT% monitor calls can be used for reading and writing a number. In general, the user's program must specify a source from which the data is to be obtained and a destination where the data is to be placed. In the case of terminal I/O, the symbol .PRIIN represents the user's terminal as the source, and the symbol .PRIOU represents the user's terminal as the destination. 2-14 CHAPTER 3 CHAPTER 3 USING FILES USING FILES 3.1 OVERVIEW 3.1 OVERVIEW All information stored in the DECSYSTEM-20 is kept in files. The basic unit of storage in a file is a page containing bytes from 1 to 36 bits in length. Thus, a sequence of pages constitutes a file. In most cases, files have names. Although all files are handled in the same manner, certain operations are unavailable for files on particular devices. Programs can reference files by several methods: o In a sequential byte-by-byte manner. o In a multiple byte or string manner. o In a random byte-by-byte manner if the particular file-storage device allows it. o In a page-mapping or section-mapping manner for files on disk. Byte and string input/output are the most common types of operations. Generally, all programs perform I/O by moving bytes of data from one location to another. For example, programs can move bytes from one memory area to another, from memory to a disk file, and from the user's terminal to memory. In addition, a program can map multiple 512-word pages or 512-page sections from a disk file into memory or vice versa. Data transfer operations on files require four steps: 1. Establishing a correspondence between a file and a Job File Number (JFN), because all files are referenced by JFNs. 2. Opening the file to establish the data mode, access mode, and byte size and to set up the monitor tables that permit data to be accessed. 3-1 USING FILES USING FILES 3. Transferring data either to or from the file. 4. Closing the file to complete any I/O, to update the directory if the file is on the disk, and to release the monitor table space used by the file. Some operations on files do not require the execution of all four steps above. Examples of these operations are: deleting or renaming a file, or changing the access code or account of a file. Although these operations do not require all four steps, they do require that the file has a JFN associated with it (step 1 above). It is possible for disk files on the DECSYSTEM-20 to be simultaneously read or written by any number of processes. To make sharing of files possible, all instances of opening a specific file in a specific directory cause a reference to the same data. Therefore, data written into a file by one process can immediately be seen by other processes reading the file. Access to files is controlled by the 6-digit (octal) file access code assigned to a file when it is created. This code indicates the types of access allowed to the file for the three classes of users: the owner of the file, the users with group access to the file, and all _______ ______ _____ other users. (Refer to the TOPS-20 User's Guide for more information on the file access codes.) If the user is allowed access to a file, he requests the type of access desired when opening the file with the OPENF% monitor call (refer to Section 3.4.1) in his program. If the access requested in the OPENF% call does not conflict with the current access to the file, the user is granted access. Essentially, the current access to the file is set by the first user who opens it. Thus, for a user to be granted access to a specific file, two conditions must be met: 1. The file access code must allow the user to access the file in the desired manner (for example, read, write). 2. The file must not be opened for a conflicting type of access. 3.2 JOB FILE NUMBER 3.2 JOB FILE NUMBER The Job File Number (JFN) is one of the more important concepts in the operating system because it serves as the identifier of a particular file on a particular device during a process' execution. It is a small integer assigned by the system upon a request from the user's program. JFNs are usually assigned sequentially starting with 1. 3-2 USING FILES USING FILES The JFN is valid for the job in which it is assigned and may be used by any process in the job. The system uses the JFN as an index into the table of files associated with the job and always assigns a JFN that is unique within the job. Even though a particular JFN within the job can refer to only one file, a single file can be associated with more than one JFN. This occurs when two or more processes are using the same file concurrently. In this case, each of the processes will probably have a different JFN for the file, but all of the JFNs will be associated with the same file. 3.3 ASSOCIATING A FILE WITH A JFN 3.3 ASSOCIATING A FILE WITH A JFN In order to reference a file, the first step the user program must complete is to associate the specific file with a JFN. This correspondence is established with the GTJFN% (Get Job File Number) monitor call. One of the arguments to this call is the string representing the desired file. The string can be specified within the program (that is, come from memory) or can be accepted as input from the user's terminal or from another file. The string can represent the complete specification for the file: dev:name.typ.gen;T(temporary);P(protection);A(account); (device dependent attributes) If you omit any fields of the specification, the system can provide _______ ______ values for all except the name field. Refer to the TOPS-20 User's _____ Guide for a complete explanation of the specification for a file. Table 3-1 lists the values the system will assign to fields not specified by the input string. Table 3-1: Standard System Values for File Specifications Table 3-1: Standard System Values for File Specifications ______________________________________________________________________ Field Value ______________________________________________________________________ Device DSK: Directory Directory to which user is currently connected. Name No default; this field must be specified. Type Null. 3-3 USING FILES USING FILES Generation number The highest existing generation number if the file is an input file. The next higher generation number if the file is an output file. Protection Protection of next lower generation of file, if one exists; otherwise, protection as specified in the directory. Account Account specified when user logged in. ______________________________________________________________________ If the string specified identifies a single file, the monitor returns a JFN that remains associated with that file until either the process releases the JFN or the job logs off the system. After the assignment of the JFN is complete, the user's program uses the JFN in all references to that file. The user's program can set up either the short or the long form of the GTJFN% monitor call. The long form of the GTJFN% call requires an argument block; the short form does not. The long form of GTJFN% has functions and flexibility not available in the short form of the call. The short form of GTJFN% allows a file specification to be obtained from a string in memory or from a file, but not from both. Fields not specified by the input are taken from the standard system values for those fields (refer to Table 3-1). This form is sufficient for most uses of the call. The long form allows a file specification to be obtained from both a string in memory and a file. If both are given as arguments, the string is used first, and then the file is used if more fields are needed to complete the specification. This form also allows the user's program to specify nonstandard values to be used for fields not given and to request the assignment of a specific JFN. 3.3.1 GTJFN% Monitor Call 3.3.1 GTJFN% Monitor Call The GTJFN% monitor call assigns a JFN to the specified file. It accepts two words of arguments. These argument words are different depending on the form of GTJFN% being used. The user's program indicates the desired GTJFN% form by setting bit 17(GJ%SHT) of AC1 to 1 for the short form or by clearing bit 17(GJ%SHT) for the long form. 3.3.1.1 Short Form of GTJFN% 3.3.1.1 Short Form of GTJFN% - The short form of the GTJFN% monitor call requires the following two words of arguments. 3-4 USING FILES USING FILES 0 17 18 35 !=======================================================! AC1 ! flag bits ! default generation number ! !=======================================================! 0 35 !=======================================================! AC2 ! source designator for file specification per ! ! bit 16 (GJ%FNS) of AC1 ! !=======================================================! The flag bits that can be specified in AC1 are described in Table 3-2. Table 3-2: GTJFN% Flag Bits Table 3-2: GTJFN% Flag Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 GJ%FOU The file specification given is to be assigned the next higher generation number. This bit indicates that a new version of a file is to be created and is normally set if the file is for output use. 1 GJ%NEW The file specification given must not refer to an existing file (that is, the file must be a new file). 2 GJ%OLD The file specification given must refer to an existing file. This bit has no effect on a parse-only JFN. (See bit GJ%OFG.) 3 GJ%MSG One of the appropriate messages is to be printed after the file specification is obtained. The message is printed only if the user types the ESC key to end his file specification (that is, he is using recognition input). [NEW FILE] [NEW GENERATION] [OLD GENERATION] [OK] if GJ%CFM (bit 4) is off [CONFIRM] if GJ%CFM (bit 4) is on 3-5 USING FILES USING FILES 4 GJ%CFM Confirmation from the user will be required to verify that the file specification obtained is correct. To confirm the file specification, the user can press the RETURN key. 5 GJ%TMP The file specified is to be a temporary file. 6 GJ%NS Only the first file specification in a multiple logical name assignment is to be searched for the file. 7 GJ%ACC The JFN specified is not to be accessed by inferior processes in this job. However, any process can access the file by acquiring a different JFN. To prevent the file from being accessed by other processes, the user's program can set OF%RTD (bit 29) in the OPENF call (refer to Section 3.4.1). 8 GJ%DEL The file specified is not to be considered as deleted, even if it is marked as deleted. 9-10 GJ%JFN These bits are off in the short form of the GTJFN call (refer to Section 3.3.1.2 for their description). 11 GJ%IFG The file specification given is allowed to have one or more of its fields specified with a wildcard character (* or %). This bit is used to process a group of files and is generally used for input files. The monitor verifies that at least one value exists for each field that contains a wildcard and assigns the JFN to the first file in the group. The monitor also verifies that fields not containing wildcards represent a new or old file according to the setting of GJ%NEW and GJ%OLD. 12 GJ%OFG The JFN is to be associated with the given file specification string only and not to the actual file. The string may contain a wildcard character (* or %) in one or more of 3-6 USING FILES USING FILES its fields. It is checked for correct punctuation between fields, but is not checked for the validity of any field. This bit allows a JFN to be associated with a file specification even if the file specification does not refer to an actual file. The JFN returned cannot be used to refer to an actual file (for example, cannot be used in an OPENF call) but can be used to obtain the original input string via the JFNS monitor call (refer to Section 3.7.2). 13 GJ%FLG Flags are to be returned in the left half of AC1 on a successful return. 14 GJ%PHY Logical names specified for the current job are to be ignored and the physical device is to be used. 15 GJ%XTN This bit is off in the short form of the GTJFN call (refer to Section 3.3.1.2 for its description). 16 GJ%FNS The contents of AC2 are to be interpreted as follows: 1. If this bit is on, AC2 contains an input JFN in the left half and an output JFN in the right half. The input JFN is used to obtain the file specification to be associated with the JFN. The output JFN is used to indicate the destination for printing the names of any fields being recognized. To omit either JFN, the user's program must specify the symbol .NULIO (377777). 2. If this bit is off, AC2 contains a pointer to a string in memory that specifies the file to be associated with the JFN. 17 GJ%SHT This bit must be on (set) for the short form of the GTJFN% call; it must be off for the long form of the call. 3-7 USING FILES USING FILES 18-35 The generation number of the file (between 1 and 377777) or one of the following: 0(.GJDEF) to indicate that the next higher generation number of the file is to be used if GJ%FOU (bit 0) is on, or to indicate that the highest existing generation number of the file is to be used if GJ%FOU is off. (This value is usually used in this field.) -1(.GJNHG) to indicate that the next higher generation number of the file is to be used if no generation number is supplied. -2(.GJLEG) to indicate that the lowest existing generation number of the file is to be used. -3(.GJALL) to indicate that all generation numbers (*) of the file are to be used and that the JFN is to be assigned to the first file in the group. (Bit GJ%IFG must be set.) ______________________________________________________________________ 3-8 USING FILES USING FILES If the GTJFN% call is given with the appropriate flag bit set (GJ%IFG or GJ%OFG), the file specification given as input can have a wildcard character (either an asterisk or a percent sign) appearing in the directory, name, type, or generation number field. (The percent sign cannot appear in the generation number field.) The wildcard character is interpreted as matching any existing occurrence of the field. For example, the specification *.MAC identifies all the files with the file type .MAC in the directory named . The specification MYFILE.FO% identifies all the files in directory with the name MYFILE and a three-character file type in which the first two characters are .FO. Upon completion of the GTJFN call, the JFN returned is associated with the first file found in the group according to the following: o in numerical order by directory number o in alphabetical order by filename o in alphabetical order by file type o in ascending numerical order by generation number The GNJFN% (Get Next JFN) monitor call can then be given to assign the JFN to the next file in the group (refer to Section 3.7.3). Normally, a program that accepts wildcard characters in a file specification will successively reference all files in the group using the same JFN and not obtain another JFN for each one. If execution of the GTJFN% call is not successful because problems were encountered in performing the call, the JFN is not assigned and an error code is returned in the right half of AC1. The execution of the program continues at the instruction following the GTJFN% call. If execution of the GTJFN% call is successful, the JFN assigned is returned in the right half of AC1 and various bits are set in the left half, if flag bits 11, 12, or 13 were on in the call. (The bits returned on a successful call are described in Table 3-3.) If bit 11, 12, or 13 was not on in the call, the left half of AC1 is zero. The execution of the program continues at the second instruction after the GTJFN% call. 3-9 USING FILES USING FILES Table 3-3: Bits Returned on GTJFN% Call Table 3-3: Bits Returned on GTJFN% Call ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 GJ%DEV The device field of the file specification contains wildcard characters. 1 GJ%UNT The unit field of the file specifications contains wildcard characters. This bit is never set because wildcard characters are not allowed in unit fields. 2 GJ%DIR The directory field of the file specification contains wildcard characters. 3 GJ%NAM The filename field of the file specification contains wildcard characters. 4 GJ%EXT The file type field of the file specification contains wildcard characters. 5 GJ%VER The generation number field of the file specification contains wildcard characters. 6 GJ%UHV The file used has the highest generation number because a generation number of 0 was given in the call. 7 GJ%NHV The file used has the next higher generation number because a generation number of 0 or -1 was given in the call. 8 GJ%ULV The file used has the lowest generation number because a generation number of -2 was given in the call. 9 GJ%PRO The protection field of the file specification was given. 10 GJ%ACT The account field of the file specification was given. 3-10 USING FILES USING FILES 11 GJ%TFS The file specification is for a temporary file. 12 GJ%GND Files marked for deletion are not considered when assigning JFNs in subsequent calls. This bit is set if GJ%DEL was not set in the call. 13 GJ%NOD The node name field of the file specification was given. 17 GJ%GIV Invisible files were not considered when assigning JFNs. ______________________________________________________________________ Examples of the short form of the GTJFN% monitor call are shown in the following paragraphs. The following sequence of instructions is used to obtain, from the user's terminal, the specification of an existing file. MOVX AC1,GJ%OLD+GJ%FNS+GJ%SHT MOVE AC2,[.PRIIN,,.PRIOU] GTJFN% The bits specified for AC1 indicate that the file specification given must refer to an existing file (GJ%OLD), that the file specification is to be accepted from the input JFN in AC2 (GJ%FNS), and that the short form of the GTJFN% call is being used (GJ%SHT). Because the right half of AC1 is zero, the standard generation number algorithm will be used. In this GTJFN% call, the file with the highest existing generation number is used. Because GJ%FNS is set in AC1, the contents of AC2 are interpreted as containing an input JFN and an output JFN. In this example, the file specification is obtained from the terminal (.PRIIN). The following sequence of instructions is used to obtain, from the user's terminal, the specification of an output file and to require confirmation from the user once the file specification has been obtained. MOVX AC1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT MOVE AC2,[.PRIIN,,.PRIOU] GTJFN% In this example, the bits specified for AC1 indicate that o the file obtained is to be an output file (GJ%FOU), o after the file specification is obtained, a message is to be typed (GJ%MSG), 3-11 USING FILES USING FILES o the user is required to confirm the file specification that was obtained (GJ%CFM), o the file specification is to be obtained from the input JFN in AC2 (GJ%FNS), o the short form of the GTJFN% call is being used (GJ%SHT). Because the right half of AC1 is zero, the generation number given to the file will be one greater than the highest generation number existing for the file. The contents of AC2 are interpreted as containing an input JFN and an output JFN because GJ%FNS is set in AC1. The following sequence of instructions is used to obtain the name of an existing file from a location in the user's program. MOVX AC1,GJ%OLD+GJ%SHT MOVE AC2,[POINT 7,NAME] GTJFN% . . . NAME:ASCIZ/MYFILE.TXT/ The bits specified for AC1 indicate that the file obtained is to be an existing file (GJ%OLD) and that the short form of the GTJFN% call is being used (GJ%SHT). Since the right half of AC1 is zero, the file with the highest generation number will be used. Because GJ%FNS is not set, the contents of AC2 are interpreted as containing a pointer to a string in memory that specifies the file to be associated with the JFN. The setup of AC2 indicates that the string begins at location NAME in the user's program. The file specification obtained from location NAME is MYFILE.TXT. An alternate way of specifying the same file is the sequence MOVX AC1,GJ%OLD+GJ%SHT HRROI AC2,[ASCIZ/MYFILE.TXT/] GTJFN% 3.3.1.2 Long Form of GTJFN% 3.3.1.2 Long Form of GTJFN% - The long form of the GTJFN% monitor call requires the following two words of arguments: 0 17 18 35 !=======================================================! AC1 ! 0 ! address of argument table ! !=======================================================! 3-12 USING FILES USING FILES 0 35 !=======================================================! AC2 ! pointer to ASCIZ file specification string, or 0 ! !=======================================================! The argument block for the long form is described in Table 3-4. Table 3-4: Long Form GTJFN% Argument Block Table 3-4: Long Form GTJFN% Argument Block ______________________________________________________________________ Word Symbol Meaning ______________________________________________________________________ 0 .GJGEN Flag bits appear in the left half and generation number appears in the right half. 1 .GJSRC An input JFN appears in the left half and an output JFN appears in the right half. To omit either JFN, the user's program must specify the symbol .NULIO (377777). 2 .GJDEV Pointer to ASCIZ string that specifies the device to be used when none is given. If this word is 0, DSK will be used. 3 .GJDIR Pointer to ASCIZ string that specifies the directory to be used when none is given. If this word is 0, the user's connected directory will be used. 4 .GJNAM Pointer to ASCIZ string that specifies the filename to be used when none is given. If this word is 0, the input must specify the filename. 5 .GJEXT Pointer to ASCIZ string that specifies the file type to be used when none is given. If this word is 0, a null type will be used. 6 .GJPRO Pointer to ASCIZ string or 3B2+octal protection code. This word indicates the protection to be used when none is given. If this word is 0, the protection as specified in the directory will be used. 3-13 USING FILES USING FILES 7 .GJACT Pointer to ASCIZ string or 3B2+decimal account number. This word indicates the account to be used when none is given. If this word is 0, the account specified when the user logged in will be used. 10 .GJJFN The JFN to assign to the file specification if flag bit GJ%JFN is set in word .GJGEN (word 0) of the argument block. 11-17 Additional words allowed if flag bit GJ%XTN (bit 15) is set in word .GJGEN (word 0) of the argument block. These additional words are used when performing command input parsing and _______ _______ are described in the TOPS-20 Monitor _____ _________ ______ Calls Reference Manual. ______________________________________________________________________ The flag bits accepted in the left half of .GJGEN (word 0) of the argument block are the same as those accepted in the short form of the GTJFN% call. The entire set of flag bits is listed in Table 3-2. The generation number values accepted in the right half of .GJGEN (word 0) of the argument block can be 0, -1, -2, -3, or a specified number, although 0 is the normal case. Refer to Bits 18-35 of Table 3-2 for explanations of these values. If execution of the GTJFN% call is successful, the JFN assigned is returned in the right half of AC1 and various bits are set in the left half if flag bits 11, 12 or 13 were on in the call. Refer to Table 3-3 for the explanations of the bits returned. Execution of the program continues at the second instruction following the call. If execution of the GTJFN call is not successful, the JFN is not assigned and an error code is returned in the right half of AC1. The execution of the program continues at the instruction following the GTJFN% call. The following sequence of instructions obtains a specification for an existing file from the user's terminal, assigns the JFN to the next higher generation of that file, and specifies default fields to be used if the user omits a field when he gives his file specification. MOVEI AC1,JFNTAB SETZ AC2, GTJFN% . . . 3-14 USING FILES USING FILES JFNTAB: GJ%FOU XWD .PRIIN,.PRIOU 0 POINT 7,[ASCIZ/TRAIN/] ;default directory 0 POINT 7,[ASCIZ/MEM/] ;default file type 0 0 0 The address of the argument table for the GTJFN% call (JFNTAB) is given in the right half of AC1. AC2 contains 0, which means no pointer to a string is given; thus, fields for the file specification will be taken only from the user's terminal. The first word of the argument block contains a flag bit for the GTJFN% call. This bit (GJ%FOU) indicates that the next higher generation number is to be assigned to the file. The second word of the argument block indicates that the file specification is to be obtained from the user's terminal, and any output generated because of the user employing recognition is to be printed on his terminal. If the user does not supply a directory name as part of his file specification, the directory will be used. And if the user does not give a file type, the type MEM will be used. If the user omits other fields from his specification, the system standard value (refer to Table 3-1) will be used. 3.3.1.3 Summary of GTJFN% 3.3.1.3 Summary of GTJFN% - The GTJFN% monitor call is required to associate a JFN with a particular file. In most cases, the short form of the GTJFN% call is sufficient for establishing this association. However, the long form is more powerful because it provides the user's program more control over the file specification that is obtained. The following summary compares the characteristics of the two forms of the GTJFN% monitor call. _____ ____ ____ ____ Short Form Long Form Assigns a JFN to a file. Assigns a JFN to a file. System decides the JFN User program may request to assign. a particular JFN. Accepts the file specification Accepts the file specification from a string in memory from a string in memory or a file. and a file. Uses standard system values Allows user-supplied values for fields not given to be used for fields not in the file given in the file specification. specification. 3-15 USING FILES USING FILES 3.4 OPENING A FILE 3.4 OPENING A FILE Once a JFN has been obtained for a file, the user's program must open the file in order to transfer data. The user's program supplies the JFN of the file to be opened and a word of bits indicating the desired byte size, data mode, and access to the file. The desired access to the file is specified by a separate bit for each type of access. The file is successfully opened only if the desired access does not conflict with the current access to the file (refer to Section 3.1). For example, if the user requests both read and write access to the file, but write access is not allowed, then the file is not opened for this user. The allowed types of access to a file are: o Read access. The file can be read with byte, string, or random input. o Write access. The file can be written with byte, string, or random output. o Append access. The file can be written only with sequential byte or dump output, and the current byte pointer (refer to Section 3.5.1) cannot be changed. The initial position of the file pointer is at the end of the file. o Frozen access. The file can be concurrently accessed by at most one user writing the file, but by any number of users reading the file. This is the default access to a file. o Thawed access. The file can be accessed even if other users are reading and writing the file. o Restricted access. The file cannot be accessed if another user already has opened the file. o Unrestricted read access. The file can be read regardless of what other users might be doing with the file. 3.4.1 OPENF% Monitor Call 3.4.1 OPENF% Monitor Call The OPENF% (Open File) monitor call opens a specified file. It requires the following two words of arguments. 3-16 USING FILES USING FILES 0 17 18 35 !=======================================================! AC1 ! 0 ! JFN of file to be opened ! !=======================================================! 0 5 6 9 18 30 31 35 !=======================================================! AC2 ! byte !data ! 0 ! access bits ! 0 ! ! size !mode ! ! ! ! !=======================================================! If the left half of AC1 is not 0, the contents of AC1 is interpreted as a pointer to a string, not as a JFN. If the user's program requests bits returned in AC1 from the GTJFN% call, these bits must be cleared before executing the OPENF% call. The byte size (OF%BSZ) in AC2 specifies the number of bits in each byte of the file and can be between 1 and 36 (decimal). If this field is 0 a byte size of 36 (decimal) is assumed. The file data mode field (OF%MOD) usually has one of two values: Value Meaning 0 Normal data mode of the file (that is, byte I/O). Dump I/O is illegal. 17 Dump mode (that is, unbuffered word I/O). Byte I/O is illegal and the byte size is ignored. The access bits are described in Table 3-5. Table 3-5: OPENF% Access Bits Table 3-5: OPENF% Access Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0-5 OF%BSZ Byte size (maximum of 36 decimal). 6-9 OF%MOD Data mode in which to open file. 18 OF%HER Halt on the occurrence of an I/O device or medium error during subsequent I/O to the file. If this bit is not set, a software interrupt is generated if a device or medium error occurs during subsequent I/O. 3-17 USING FILES USING FILES 19 OF%RD Allow read access. 20 OF%WR Allow write access. 21 OF%EX Allow execute access. 22 OF%APP Allow append access. 23 OF%RDU Allow unrestricted read access. 24 Reserved for Digital. 25 OF%THW Allow thawed access. If this bit is not set, the file is opened for frozen access. 26 OF%AWT Block (that is, temporarily suspend) the program until access to the file is permitted. 27 OF%PDT Do not update the access dates of the file. 28 OF%NWT Return an error if access to the file cannot be permitted. 29 OF%RTD Allow access to the file to only one process (that is, restricted access). 30 OF%PLN Do not check for line numbers in the file. 31 OF%DUD Suppress system updating of modified pages in memory to thawed files on disk unless CLOSF or UFPGS issued. 32 OF%OFL Open device even if off-line. 33 OF%FDT Force update of .FBREF (last read) in FDB and increment RH of .FBCNT (number of references). 34 OF%RAR Wait if file off-line. ______________________________________________________________________ If bits OF%AWT and OF%NWT are both off, an error code is returned if access to the file cannot be permitted (that is, the action taken is identical to OF%NWT being on). 3-18 USING FILES USING FILES If execution of the OPENF% monitor call is successful, the file is opened, and the execution of the program continues at the second instruction after the OPENF% call. If execution of the OPENF% call is not successful, the file is not opened, and an error code is returned in AC1. The execution of the program continues at the next instruction after the OPENF% call. Two samples of the OPENF% call follow. The sequence of instructions below opens a file for input. HRRZ AC1,JFNEXT MOVX AC2,FLD(44,OF%BSZ)+OF%RD+OF%PLN OPENF% The JFN of the file to be opened is contained in the location indicated by the address in AC1 (JFNEXT). The bits specified for AC2 indicate that the byte size is one word FLD(44,OF%BSZ), that read access is being requested to the file (OP%RD), and that no check will be made for line numbers in the file; that is, the line numbers will not be discarded (OF%PLN). Because bit OF%THW is not set, the file can be accessed for reading by any number of processes. The following sequence of instructions can be used to open a file for output. MOVE AC1,JFN MOVX FLD(7,OF%BSZ)+OF%HER+OF%WR+OF%AWT OPENF% The right half of AC1 contains the address that has the JFN of the file to be opened. The bits specified for AC2 indicate that the byte size is 7-bit bytes FLD(7,OF%BSZ), that the program is to be halted when an I/O error occurs in the file (OF%HER), that write access is being requested to the file (OF%WR), and that the program is to be blocked if access cannot be granted (OF%AWT). Because bit OF%THW is not set, if another user has been granted write access to the file, this user's program will be blocked until access can be granted. 3.5 TRANSFERRING DATA 3.5 TRANSFERRING DATA Data transfers of sequential bytes are the most common form of transfer and can be used with any file. For disk files, nonsequential bytes and entire pages can also be transferred. 3-19 USING FILES USING FILES 3.5.1 File Pointer 3.5.1 File Pointer Every open file is associated with a pointer that indicates the last byte read from or written to the file. When the file is initially opened, this pointer is normally positioned before the beginning of the file so that the first data operation will reference the first byte in the file. The pointer is then advanced through the file as data is transferred. However, if the file is opened for append-only access (bit OF%APP set in the OPENF% call), the pointer is positioned after the last byte of the file. This allows the first write operation to append data to the end of the file. For disk files, the pointer may be repositioned arbitrarily throughout the file, such as in the case of nonsequential data transfers. When the pointer is positioned beyond the end of the file, an end-of-file indication is returned when the program attempts a read operation using byte input. When the program performs a write operation beyond the end of the file using byte output, the end-of-file indicator is updated to point to the end of the new data. However, if the program writes pages beyond the end of the file with the PMAP% monitor call (refer to section 3.5.6), the byte count is not updated. Therefore, it is possible for a file to contain pages of data beyond the end-of-file indicator. To allow sequential I/O to be performed later to the file, the program should update the byte count before closing the file. (Refer to the CHFDB% monitor call description in the _______ _______ _____ _________ ______ TOPS-20 Monitor Calls Reference Manual.) 3.5.2 Source and Destination Designators 3.5.2 Source and Destination Designators Because I/O operations occur by moving data from one location to another, the user's program must supply a source and a destination for any I/O operation. The most commonly-used source and destination designators are the following: 1. A JFN associated with a particular file. The JFN must be previously obtained with the GTJFN% or GNJFN% monitor call before it can be used. 2. The primary input and output designators .PRIIN and .PRIOU, respectively (refer to Section 2.2). These designators should be used when referring to the terminal. 3. A byte pointer to the beginning of the string of bytes in the program's address space that is being read or written. The byte pointer can take one of two forms: o A word with a -1 in the left half and an address in the right half. This form is used to designate a 7-bit ASCIZ string starting in the left-most byte of the specified address. A word in this form is functionally equivalent to a word assembled by the POINT 7,ADR pseudo-op. 3-20 USING FILES USING FILES o A full word byte pointer with a byte size of 7 bits. Most monitor calls dealing with strings deal specifically with ASCII strings. Normally, ASCII strings are assumed to terminate with a byte of 0 (that is, are assumed to be ASCIZ strings). However some calls optionally accept an explicit byte count and/or terminating byte. These calls are generally ones that handle non-ASCII strings and byte sizes other than 7 bits. 3.5.3 Transferring Sequential Bytes 3.5.3 Transferring Sequential Bytes The BIN% (Byte Input) and BOUT% (Byte Output) monitor calls are used for sequential byte transfers. The BIN% call takes the next byte from the given source and places it in AC2. The BOUT% call takes the byte from AC2 and writes it to the given destination. The size of the byte is that given in the OPENF% call for the file. The BIN% monitor call accepts a source designator in AC1, and upon successful execution of the call, the byte is right-justified in AC2. If execution of the call is not successful, an illegal instruction trap is generated. Control returns to the user's program at the instruction following the BIN% call. If the end of the file is reached, AC2 contains 0 instead of a byte. The program can process this end-of-file condition if a jump style error return is the next instruction following the BIN% call. The BOUT% monitor call accepts a destination designator in AC1 and the byte to be output, right-justified in AC2. Upon successful execution of the call, the byte is written to the destination. If execution of the call is not successful, an illegal instruction trap is generated Control returns to the user's program at the instruction following the BOUT% call. The following sequence shows the transferring of bytes from an input file to an output file. The bytes are read from the file indicated by INJFN and written to the file indicated by OUTJFN. LOOP: MOVE 1,INJFN ;get source designator from INJFN BIN% ;read a byte from the source ERJMP DONE ;check for end of file, if 0 LOOP2: MOVE 1,OUTJFN ;get destination from OUTJFN BOUT% ;write the byte to the destination JRST LOOP ;continue until 0 byte is found DONE: GTSTS% ;obtain status of source TXNN 2,GS%EOF ;test for end of file JRST NOTYET ;no, test for 0 in input file : ;yes, process end of file condition NOTYET:MOVEI 2,0 ;0 in input file JRST LOOP2 3-21 USING FILES USING FILES 3.5.4 Transferring Strings 3.5.4 Transferring Strings The SIN% (String Input) and SOUT% (String Output) monitor calls are used for string transfers. These calls transfer either a string of a specified number of bytes or a string terminated with a specific byte. The SIN% monitor call reads a string from the specified source into the program's address space. The call accepts four words of arguments in AC1 through AC4. AC1: source designator AC2: pointer to area in program's address space AC3: count of number of bytes to read, or 0 AC4: byte on which to terminate input (optional) The contents of AC3 are interpreted as the number of characters to read. o If AC3 is 0, then reading continues until a 0 byte is found in the input. o If AC3 is positive, then reading continues until either the specified number of bytes is read, or a byte equal to that given in AC4 is found in the input, whichever occurs first. o If AC3 is negative, then reading continues until minus the specified number of bytes is read. The contents of AC4 needs to be specified only if the contents of AC3 is a positive number. The byte in AC4 is right-justified. The input is terminated when one of the following occurs: o The byte count becomes zero. o The specified terminating byte is reached. o The end of the file is reached. o An error occurs during the transfer (for example, a data error occurs). Control returns to the user's program at the instruction following the SIN% call. If an error occurs (including the end of the file is reached), an illegal instruction trap is generated. In addition, several locations are updated: 3-22 USING FILES USING FILES 1. The position of the file's pointer is updated for subsequent I/O to the file. 2. The pointer to the string in AC2 is updated to reflect the last byte read or, if AC3 contained 0, the last nonzero byte read. 3. The count in AC3 is updated, if pertinent, by subtracting the number of bytes actually read from the number of bytes requested to be read (that is, the count is updated toward zero). From this count, the user's program can determine the number of bytes actually transferred. The SOUT% monitor call writes a string from the program's address space to the specified destination. Like the SIN% call, this call accepts four words of arguments in AC1 through AC4. AC1: destination designator AC2: pointer to string to be written AC3: count of the number of bytes to write, or 0 AC4: byte on which to terminate output (optional) The contents of AC3 and AC4 are interpreted in the same manner as they are in the SIN% monitor call. The transfer is terminated when one of the following occurs. o The byte count becomes zero. o The specified terminating byte is reached. This terminating byte is written to the destination. o An error occurs during the transfer. Control returns to the user's program at the instruction following the SOUT% call. If an error occurs, an illegal instruction trap is generated. In addition, the position of the file's pointer, the pointer to the string in AC2, and the count in AC3, if pertinent, are also updated in the same manner as in the SIN% monitor call. The following code sequence shows transferring a string from an input file to an output file. The procedure is the same as at the end of Section 3.5.3, using SIN% and SOUT% calls instead of BIN% and BOUT%. LOOP: MOVE 1,INJFN ;get source from INJFN HRROI 2,BUF128 ;pointer to string to read into (128 ;word buffer) 3-23 USING FILES USING FILES MOVNI 3,^D128*5 ;input a maximum of 640 bytes SIN% ;transfer until end of buffer or end of ;file ERCAL EOFQ ;error occurred ADDI 3,^D128*5 ;determine negative number of ;bytes transferred MOVN 3,3 ;convert to positive MOVE 1,OUTJFN ;get destination from OUTJFN HRROI 2,BUF128 ;pointer to string to write from SOUT% ;transfer as many bytes as read EOFQ: MOVE 1,INJFN GTSTS% ;obtain status of source TXNN 2,GS%EOF ;test for end of file RET ;no, continue copying 3.5.5 Transferring Nonsequential Bytes 3.5.5 Transferring Nonsequential Bytes As discussed in Section 3.5.3, the BIN% and BOUT% calls transfer bytes sequentially, starting at the current position of the file's pointer. The RIN% (Random Input) and ROUT% (Random Output) monitor calls allow the user's program to specify where the transfer will begin by accepting a byte number within the file. The size of the byte is the size given in the OPENF% call for the file. The RIN% and ROUT% calls can only be used when transferring data to or from disk files. The RIN% monitor call takes a byte from the specified location in the file and places it into the accumulator. The call accepts the JFN of the file in AC1 and the byte number within the file in AC3. Upon successful completion of the call, the byte is right-justified in AC2, and the file's pointer is updated to point to the byte following the one just read. If an error occurs, an illegal instruction trap is generated. Control returns to the user's program at the instruction following the RIN% call. The ROUT% monitor call takes a byte from the accumulator and writes it into the specified location in the file. The call accepts the JFN of the file in AC1, the byte to write right-justified in AC2, and the byte number within the file in AC3. Upon successful completion of the call, the byte is written into the specified byte in the file, and the file's pointer is updated to point to the byte following the one just written. If an error occurs, an illegal instruction trap is generated. Control returns to the user's program at the instruction following the ROUT% call. 3.5.6 Mapping Pages 3.5.6 Mapping Pages Up to this point, monitor calls have been presented for transferring 3-24 USING FILES USING FILES bytes and strings of data. The next call to be discussed is used to transfer entire pages of data between a file and a process. Both files and process address spaces are divided into pages of 512(decimal) words. A page within a file can be identified by one word, where the JFN of the file is in the left half and the page number within the file is in the right half. A page within a process address space can also be identified by one word, where the identifier of the process (refer to Section 5.3) is in the left half and the page number within the process' address space is in the right half. Each one-word identifier for the pages in the process address space is placed in what is called the process page map. When identifiers for file pages are placed in the process page map, references to the process page actually refer to the file page. The following diagram illustrates a process map that has identifiers for pages from two files. File 1 __________ | | Process Map | | _____________ | | | | | | | | | | |-------------| |----------| |JFN1 |Page 1|-------------->| Page 1 | |-------------| |----------| | | | | | | | | |-------------| |__________| | | | | | | File 2 | | __________ | | | | | | | | |-------------| |----------| |JFN2 |Page 2|-------------->| Page 2 | |-------------| |----------| | | | | | | | | |_____________| | | | | | | |__________| The PMAP% (Page Mapping) monitor call is used to map one or more entire pages from a file to a process (for input), from a process to a file (for output), or from one process to another process. In general, this call changes the entries in the process map by accepting 3-25 USING FILES USING FILES file page identifiers and process page identifiers as arguments. Mapping pages between a file and a process is described below; mapping pages between two processes is described in Chapter 5. 3.5.6.1 Mapping File Pages to a Process 3.5.6.1 Mapping File Pages to a Process - This use of the PMAP% call changes the map of the process so that references to pages in the process reference pages in a file. This does not actually cause data to be transferred; it simply changes the contents of the map. Later when changes are made to the actual page in the process, the changes will also be made to the page in the file, if write access has been specified for the file. Note that you cannot map file pages to pages in a process section that does not exist in the the process map. If you use PMAP% to input file pages to pages in a nonexistent section of a process, the monitor generates an illegal instruction trap. In addition, you can map one or more file sections (of 512 pages each) into a process. See Section 8.3.1 for details. The PMAP% call accepts three words of arguments in AC1 through AC3. AC1: JFN of the file in the left half, and the page number in the file in the right half AC2: process identifier (refer to Section 5.3) in the left half, and page number in the process in the right half AC3: repetition count and access The repetition count and access bits that can be specified in AC3 are described in Table 3-6. Table 3-6: PMAP% Access Bits Table 3-6: PMAP% Access Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 PM%CNT Repeat the mapping operation the number of times specified by the right half of AC3. The file page number and the process page number are incremented by 1 each time the operation is performed. 2 PM%RD Allow read access to the page. 3 PM%WR Allow write access to the page. 3-26 USING FILES USING FILES 4 PM%EX Reserved. The symbol PM%RWX can be used to set B2-4. 5 PM%PLD Preload page being mapped (move the page immediately instead of waiting until it is referenced). 9 PM%CPY Create a private copy of the page if the process writes into the page. This is called copy-on-write and causes the map to be changed so that it identifies the copy instead of the original. Write access is allowed to the copy even if it was not allowed to the original. This allows a process to change a page of data without changing the data for other processes that have also mapped the page. 10 PM%EPN Bits 18-35 of AC2 contain extended (18-bit) process page number. If the section containing the page does not exist, a private section is created. 11 PM%ABT Unmap page and discard (abort) changed contents. 18-35 PM%RPT The number of times to repeat the mapping operation if bit 0(PM%CNT) is set. ______________________________________________________________________ With this use of the PMAP% call, the present contents of the page in the process are removed. If the page in the file is currently nonexistent, it will be created when it is written. This use of the PMAP% call is valid only if the file is opened for at least read access. If write access is requested in the PMAP% call, it is not granted unless it was also specified in the OPENF% call when the file was opened. A file cannot be closed while any of its pages are mapped into any process. Thus, before a file is closed, its pages must be unmapped (refer to Section 3.5.6.3). After execution of the PMAP% call, control returns to the user's program at the instruction following the call. If an error occurs, an illegal instruction trap is generated. 3.5.6.2 Mapping Process Pages to a File 3.5.6.2 Mapping Process Pages to a File - This use of the PMAP% call actually transfers data by moving the specified page in the process to the specified page in the file. The process map for the page is now 3-27 USING FILES USING FILES empty. Both the page in the process and the page in the file must be private; that is, no other process can have the page mapped into its address space. The ownership of the process page is transferred to the file page. The previous contents of the page in the file are deleted. The three words of arguments are as follows: AC1: process identifier (refer to Section 5.3) in the left half, and page number in the process in the right half AC2: JFN of the file in the left half, and the page number in the file in the right half AC3: repetition count and access (refer to Section 3.5.6.1) The access requested in the PMAP% call is granted only if it does not conflict with the access specified in the OPENF% call when the file was opened. This use of the PMAP% call does not automatically update the files byte count and the byte size. To allow the file to be read later with sequential I/O monitor calls, the program should update the file's byte count and the byte size. (Refer to the CHFDB% monitor call in _______ _______ _____ _________ ______ the TOPS-20 Monitor Calls Reference Manual). 3.5.6.3 Unmapping Pages in a Process 3.5.6.3 Unmapping Pages in a Process - As stated previously, a file cannot be closed if any of its pages are mapped in any process. To unmap a file's pages from a process, the program must execute the SMAP% call, or the following form of the PMAP% call: AC1: -1 AC2: process identifier in the left half, and page number in the process in the right half. AC3: the repeat count for the number of pages to remove from the process (refer to Section 3.5.6.1). 3.5.7 Mapping File Sections to a Process 3.5.7 Mapping File Sections to a Process A section of memory is a unit of 512 pages of process address space. File sections also contain 512 pages. The first page of each file section has a page number that is an integral multiple of 512. Like memory pages, sections can be mapped from one process to another, from a process to itself, or from a file to a process. Chapter 8 describes the SMAP% call completely. 3-28 USING FILES USING FILES The SMAP% (Section Mapping) monitor call is similar to the PMAP% call. The SMAP% call maps one or more sections from a file to a process (for input), or from one process to another process. To map a process section to a file, you must use the PMAP% call as described in Chapter 5 to map each page. Mapping a file section to a process section with SMAP% does not cause data to move from the disk to memory. Instead, SMAP% changes the contents of the process memory map so that the process section pointer points to a file section. The monitor transfers data only when your program references a memory page to which a file page is mapped. To map a file section to a process section, SMAP% requires three arguments: AC1: source identifier: a JFN in the left half, and a file section number in the right half. If several contiguous sections are to be mapped, the number in the right half is that of the first section in the group of contiguous sections. AC2: destination identifier: process identifier in the left half, and a process section number in the right half. If several contiguous sections are to be mapped, the number in the right half is the number of the first section into which SMAP% maps a file section. AC3: flags that control access to the process section in the left half, and, in the right half, the number of sections to map into the process. The number of sections to map cannot be less than 1 nor more than 32 (decimal). The flags in the left half of AC3 are described in Table 3-7. Table 3-7: SMAP% Access Bits Table 3-7: SMAP% Access Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 2 SM%RD Allow read access. 3 SM%WR Allow write access. 4 SM%EX Allow execute access. 6 SM%IND Map the destination section using an indirect section pointer. ______________________________________________________________________ 3-29 USING FILES USING FILES 3.6 CLOSING A FILE 3.6 CLOSING A FILE Once data has been transferred to or from a file, the user's program must close the file. When a file is closed, the system automatically performs the following: 1. Updates the directory information for the file. For example, for a file to which sequential bytes had been written, the byte size and byte count are updated when the file is closed. 2. Releases the JFN associated with the file. However, the user's program can request to close the file, but retain the JFN assignment. This is useful if the program plans to reopen the same file later, but does not want to execute another GTJFN% call. 3.6.1 CLOSF% Monitor Call 3.6.1 CLOSF% Monitor Call The CLOSF% (Close File) monitor call closes either the specified file or all files that are opened for the process executing the call. The CLOSF% call accepts one word of arguments in AC1 - flag bits in the left half and the JFN of the file to be closed in the right half. The flag bits are described in Table 3-8. Table 3-8: CLOSF% Flag Bits Table 3-8: CLOSF% Flag Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 CO%NRJ Do not release the JFN from the file. 6 CZ%ABT Abort any output operations currently being done. That is, close the file but do not perform normal cleanup operations (for example, do not output any data remaining in the buffers). If output to a new disk file that has not been closed is aborted, the file is closed and then deleted. 7 CS%NUD Do not update the copy of the directory on the disk (refer to the CHFDB% description in the _______ _______ _____ _________ ______ TOPS-20 Monitor Calls Reference Manual for more information). ______________________________________________________________________ If the contents of AC1 is -1, all files that are opened for this process are closed. 3-30 USING FILES USING FILES If the execution of the CLOSF% call is successful, the specified file is closed, and the JFN associated with the file is released if CO%NRJ was not set in the call. The execution of the user's program continues at the second location after the CLOSF% call. If the execution of the CLOSF% call is not successful, the file is not closed and an error code is returned in the right half of AC1. The execution of the user's program continues at the instruction following the CLOSF% call. The following sequence illustrates the closing of two files. CLOSIF: HRRZ 1,INJFN ;obtain input JFN CLOSF% ;close input file ERJMP FATAL ;if error, print message and stop CLOSOF: HRRZ 1,OUTJFN ;obtain output JFN CLOSF% ;close output file ERJMP FATAL ;if error, print message and stop 3.7 ADDITIONAL FILE I/O MONITOR CALLS 3.7 ADDITIONAL FILE I/O MONITOR CALLS 3.7.1 GTSTS% Monitor Call 3.7.1 GTSTS% Monitor Call The GTSTS% (Get Status) monitor call obtains the status of a file. This call accepts one argument word - the JFN of the file in the right half of the AC1. The left half of AC1 is zero. Control always returns to the user's program at the instruction following the GTSTS% call. Upon return, appropriate bits reflecting the status of the specified JFN are set in AC2. These bits, and their meanings, are described in Table 3-9. Note that if the JFN is illegal or unassigned, bit 10 (GS%NAM) will not be set. Table 3-9: Bits Returned on GTSTS% Call Table 3-9: Bits Returned on GTSTS% Call ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 GS%OPN The file is open. If this bit is not set, the file is not open. 1 GS%RDF If the file is open (for example, GS%OPN is set), it is open for read access. 3-31 USING FILES USING FILES 2 GS%WRF If the file is open, it is open for write access. 3 GS%XCF File is open for execute access. 4 GS%RND If the file is open, it is open for non-append access (that is, its pointer can be reset). 5-6 Reserved for Digital. 7 GS%LNG File has pages in existence beyond page number 511. 8 GS%EOF The last read operation to the file was at the end of the file. 9 GS%ERR The file may be in error (for example, the bytes read may be erroneous). 10 GS%NAM A file specification is associated with this JFN. This bit will not be set if the JFN is in any way illegal. 11 GS%AST One or more fields of the file specification associated with this JFN contain a wildcard character. 12 GS%ASG The JFN is currently being assigned (that is, a process other than the one executing the GTSTS call is assigning this JFN). 13 GS%HLT An I/O error is considered to be a terminating condition for this JFN. That is, the OPENF% call for this JFN had bit OF%HER set. 14-16 Reserved for Digital. 17 GS%FRK Access to the file is restricted to only one process. 18 GS%PLN If on, file line numbers are passed during input; if zero, line numbers are stripped before input. 19-31 Reserved for Digital. 32-35 GS%MOD The data mode of the file (refer to the OPENF% call). 3-32 USING FILES USING FILES Value Symbol Meaning 0 .GSNRM Normal (sequential) I/O 1 .GSSMB Small buffer mode 10 .GSIMG Image (binary) I/O 17 .GSDMP Dump I/O ______________________________________________________________________ An example of the GTSTS% call is shown in the first program in Section 3.9. 3.7.2 JFNS% Monitor Call 3.7.2 JFNS% Monitor Call The JFNS% (JFN to String) monitor call returns the file specification currently associated with the specified JFN. The call accepts three words of arguments in AC1 through AC3. AC1: destination designator where the file specification associated with the JFN is to be written. This specification is an ASCIZ string. AC2: JFN or pointer to string (see below) AC3: format to be used when returning the specification (see below) The contents of AC1 can be any valid destination designator (refer to Section 3.5.2). The contents of AC2 can be one of two formats. The first format is a word with either flag bits or 0 in the left half and the JFN in the right half. The bits that can be given in the left half of AC2 are the ones returned from the GTJFN% call (refer to Table 3-3). When the left half of AC2 is nonzero (that is, contains the bits returned from the GTJFN% call), the string returned will contain wildcard characters for appropriate fields and 0, -1, or -2 as a generation number if the corresponding bit is on in the JFNS% call. When the left half of AC2 is 0, the string returned is the exact specification for the file (for example, wildcard characters are not returned for any fields). If the JFN is associated only with a file specification and not with an actual file (that is, bit GJ%OFG was set in the GTJFN% call), the string returned will contain null fields for unspecified fields and the actual values for specified fields. The second format allowed for AC2 is a pointer to the string in the program's address space that is _______ to be returned upon execution of the call. Refer to the TOPS-20 _______ _____ _________ ______ Monitor Calls Reference Manual for the explanation of this format. 3-33 USING FILES USING FILES The contents of AC3 specify the format in which the specification is written to the destination. Bits 0 through 20 are divided into 3-bit bytes, each byte representing a field in the file specification. The value of the byte indicates the format for that field. The possible values are: Value Symbol Meaning 0 .JSNOF Do not return this field when returning the file specification. 1 .JSAOF Always return this field when returning the file specification. 2 .JSSSD Suppress this field if it is the standard system value for this field (refer to Table 3-1). If the contents of AC3 is zero, the file specification is written in the format dev:name.typ.gen;T with fields the same as the standard system value (see Table 3-1) not returned and protection and account fields returned only if bit 9 and bit 10 in AC2 are on, respectively. The temporary attribute (;T) is returned only if the file is temporary. Table 3-10 describes the bits that can be set in AC3. Table 3-10: JFNS% Format Options Table 3-10: JFNS% Format Options ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 JS%NOD Print node name if node name is present. 1-2 JS%DEV Format for device field. 3-5 JS%DIR Format for directory field. 6-8 JS%NAM Format for filename field. A value of 2 (that is, bit 7 set) for this field is illegal. 9-11 JS%TYP Format for file type field. A value of 2 (that is, bit 10 set) for this field is illegal. 3-34 USING FILES USING FILES 12-14 JS%GEN Format for generation number field. 0-14 JS%SPC Output for all file specification fields named above. This field should have the same bits set as would be set in the fields above. (See B35 (JS%PAF) below.) 15-17 JS%PRO Format for protection field. 18-20 JS%ACT Format for account field. 21 JS%TMP Return temporary file indication ;T if the file specification is for a temporary file. 22 JS%SIZ Return size of file in pages (see below). 23 JS%CDR Return creation date of file (see below). 24 JS%LWR Return date of last write operation to file (see below). 25 JS%LRD Return date of last read operation from file (see below). 26 JS%PTR AC2 contains a pointer to the string containing the field to be returned _______ _______ _____ (refer to the TOPS-20 Monitor Calls _________ ______ Reference Manual for a description of this use of the JFNS% call). 27 JS%ATR Return file specification attributes if appropriate. 28 JS%AT1 Return specification attribute referenced in AC4. 29 JS%OFL Return the "OFF-LINE" attribute. 30-31 Reserved for Digital. 32 JS%PSD Punctuate the size and date fields (see below) in the file specification returned. 33 JS%TBR Place a tab before all fields returned (that is, fields whose value is given as 1 in the 3-bit field) in the file specification, except for the first field. 3-35 USING FILES USING FILES 34 JS%TBP Place a tab before all fields that may be returned (that is, fields whose value is given as 1 or 2 in the 3-bit field) in the file specification, except for the first field. 35 JS%PAF Punctuate all fields (see below) returned in the file specification from the device field through the ;T field. If bits 32 through 35 are not set, no punctuation is used between the fields. ______________________________________________________________________ The punctuation used on each field is shown below. dev:name.typ.gen;A(account);P(protection);T(temporary) ,size,creation date,write date,read date Refer to Section 1.2.2 for information on error returns. 3.7.3 GNJFN% Monitor Call 3.7.3 GNJFN% Monitor Call Occasionally a program may be written to perform similar operations on a group of files instead of only on one file. However, the program should not require the user to give a file specification for each file. Because the GTJFN% call associates a JFN with only one file at a time, the program needs a method of assigning a JFN to all the files in the group. By using the GTJFN% call to initially obtain the JFN and the GNJFN% call to assign the same JFN to each subsequent file in the group, a program can accept a specification for a group of files and process each file in the group individually. After the user gives the initial file specification, the program requires no additional input. Before an example showing the interaction of these two calls is given, a description of the GNJFN% (Get Next JFN) monitor call is appropriate. The GNJFN% monitor call assigns a JFN to the next file in a group of files that have been specified with wildcard characters. The next file is determined by searching the directory in the order described in Section 3.3.1.1 using the current file as the first item. This call accepts one argument word in AC1 - the flags returned from the GTJFN% call in the left half and the JFN of the current file in the right half. In other words, the information returned in AC1 from the GTJFN% call is given as an argument to the GNJFN% call. Therefore, the program must save this information for use with the GNJFN% call. 3-36 USING FILES USING FILES If execution of the GNJFN% call is successful, the same JFN is assigned to the next file in the group. The left half of AC1 contains various flags and the right half contains the JFN. The execution of the program continues at the second instruction after the GNJFN% call. Table 3-11 describes the bits that can be returned in AC1 on a successful GNJFN% call. Table 3-11: GNJFN% Return Bits Table 3-11: GNJFN% Return Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 13 GN%STR A change in structure occurred between the previous file and this file. 14 GN%DIR A change in directory occurred between the previous file and this file. 15 GN%NAM A change in filename occurred between the previous file and this file. 16 GN%EXT A change in file type occurred between the previous file and this file. If GN%NAM is on, this bit will also be on because the system considers two files with different filenames but with the same file type as a change in both the name and type. ______________________________________________________________________ If execution of the GNJFN% call is not successful, an error code is returned in the right half of AC1. Conditions that can cause an error return are: 1. The file currently associated with the JFN must be closed, and it is not. This means that the program must execute a CLOSF% call (with CO%NRJ set to retain the JFN) before executing a GNJFN% call. 2. There are no more files in this group. This return occurs on the first GNJFN% call after all files in the group have been stepped through. The JFN is released when there are no more files. (Note: This error may occur if the file currently associated with the JFN is deleted or renamed.) 3-37 USING FILES USING FILES The execution of the program continues at the next instruction after the GNJFN% call. Consider the following situation. The user wants to write a program that will accept from his terminal a specification for a group of files and then perform an operation on each file individually without requiring additional input. Assume the user's directory contains the following files: FIRST.MAC.1 FIRST.REL.1 SECOND.REL.1 THIRD.EXE.1 As discussed in Section 3.3.1.1, a group of files can be given to the GTJFN call by supplying a specification that contains wildcard characters in one or more of its fields. Thus, the specification *.* would refer to all four files in the user's directory . In his program, the user includes a GTJFN% call that will accept the above specification. The call is MOVX AC1,GJ%OLD+GJ%IFG+GJ%FLG+GJ%FNS+GJ%SHT MOVE AC2,[.PRIIN,,.PRIOU] GTJFN% and indicates that 1. The file specification given must refer to an existing file (GJ%OLD). 2. The file specification given is allowed to contain wildcard characters (GJ%IFG). 3. Flags will be returned in AC1 on a successful call (GJ%FLG). The flags must be returned because they will be given to the GNJFN% call as arguments. 4. The contents of AC2 will be interpreted as containing an input and output JFN (GJ%FNS). 5. The short form of the GTJFN% call is being used (GJ%SHT). 6. The file specification is to be read from the user's terminal (.PRIIN,,.PRIOU). 3-38 USING FILES USING FILES When the user types the specification *.* as input, the system associates the JFN with one file only. This file is the first one found when searching the directory in the order specified in Section 3.3.1.1. Thus the JFN returned is associated with the file FIRST.MAC.1. After the GTJFN% call is successfully executed, AC1 contains appropriate flags in the left half and the JFN assigned in the right half. The flags that will be returned in this particular situation are: GJ%NAM (bit 3) A wildcard character appeared in the name field of the file specification given. GJ%EXT (bit 4) A wildcard character appeared in the type field of the file specification given. GJ%GND (bit 12) Any files marked for deletion will not be considered. These flags inform the program of the fields that contained wildcard characters. The user's program must now save the contents of AC1 because this word will be used as the argument to the GNJFN% call. The program then performs its desired operation on the first file. Once its processing is completed, the program is ready for the specification of the next file. But instead of requesting the specification from the user, the program executes the GNJFN% call to obtain it. The argument to the GNJFN% call is the contents of AC1 returned from the previous GTJFN% call. Thus, the call in this case is equivalent to: MOVE AC1,[GJ%NAM+GJ%EXT+GJ%GND,,JFN] GNJFN% Upon successful execution of the GNJFN% call, the JFN is now associated with the next file in the group (that is, FIRST.REL.1). AC1 contains appropriate flags in the left half and the same JFN in the right half. In this example, the flag returned is GN%EXT (bit 16) to indicate that the file type changed between the two files. After processing the second file, the user's program executes another GNJFN% call using the original contents of AC1 returned from the GTJFN% call. The original contents must be used because this word indicates the fields containing wildcard characters. If the current contents of AC1 (that is, the flags returned from the GNJFN% call) are used, a subsequent GNJFN% call would fail because there are no flags set indicating fields containing wildcard characters. This second GNJFN% call associates the JFN with the file SECOND.REL.1. The flags returned in AC1 are GN%NAM (bit 15) and GN%EXT (bit 16) indicating that the filename and file type changed between the two files. (Remember that a change in filename implies a change in file type even if the two file types are the same.) 3-39 USING FILES USING FILES After processing this third file, the user's program executes another GNJFN% call using the original contents of AC1. Upon execution of the call, the JFN is now associated with THIRD.EXE.1, and the flags returned are GN%NAM and GN%EXT, indicating a change in the filename and file type. After processing the file THIRD.EXE.1, the user's program executes a final GNJFN% call. Since there are no more files in the group, the call returns an error code and releases the JFN. Execution of the user's program continues at the instruction following the GNJFN% call. 3.8 SUMMARY 3.8 SUMMARY To read from or write to a file, the user's program must: 1. Obtain a JFN on the file with the GTJFN% monitor call (refer to Section 3.3.1). 2. Open the file with the OPENF% monitor call (refer to Section 3.4.1). 3. Transfer the data with byte, string, or page I/O monitor calls (refer to Section 3.5). 4. Close the file with the CLOSF% monitor call (refer to Section 3.6.1). 3.9 FILE EXAMPLES 3.9 FILE EXAMPLES Example 1 - This program assigns JFNs, opens an input file and an output file, and copies data from the input file to the output file. Data is copied until the end of the input file is reached. Refer to _______ _______ _____ _________ ______ the TOPS-20 Monitor Calls Reference Manual for explanation of the ERSTR% monitor call. ;*** PROGRAM TO COPY INPUT FILE TO OUTPUT FILE. *** ; (USING BIN%/BOUT% AND IGNORING NULLS) TITLE FILEIO ;TITLE OF PROGRAM SEARCH MONSYM ;SEARCH SYSTEM JSYS-SYMBOL LIBRARY SEARCH MACSYM .REQUIRE SYS:MACREL ;*** IMPURE DATA STORAGE AND DEFINITIONS *** INJFN: BLOCK 1 ;STORAGE FOR INPUT JFN OUTJFN: BLOCK 1 ;STORAGE FOR OUTPUT JFN 3-40 USING FILES USING FILES PDLEN=3 ;STACK HAS LENGTH 3 PDLST: BLOCK PDLEN ;SET ASIDE STORAGE FOR STACK STDAC. ;DEFINE STANDARD ACs. SEE MACSYM. ;*** PROGRAM INITILIZATION *** START: RESET% ;CLOSE FILES, ETC. MOVE P,[IOWD PDLEN,PDLST] ;ESTABLISH STACK ;*** GET INPUT FILE *** INFIL: ;PROMPT FOR INPUT FILE TMSG < INPUT FILE: > ;ON CONTROLLING TERMINAL MOVX T1,GJ%OLD+GJ%FNS+GJ%SHT ;SEARCH MODES FOR GTJFN ;EXISTING FILE ONLY, FILE-NRs IN B ;SHORT CALL MOVE T2,[.PRIIN,,.PRIOU] ;GTJFN'S I/O WITH CONTROLLING TERM GTJFN% ;GET JOB FILE NUMBER (JFN) ERJMPS [ PUSHJ P,WARN ;IF ERROR, GIVE WARNING JRST INFIL] ;AND LET HIM TRY AGAIN MOVEM T1,INJFN ;SUCCESS, SAVE THE JFN ;*** GET OUTPUT FILE *** OUTFIL: ;PRINT PROMPT FOR TMSG < OUTPUT FILE: > ;OUTPUT FILE MOVX T1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT ;GTJFN SEARCH MODES ;[DEFAULT TO NEW GENERATION, PRINT ; MESSAGE, REQUIRE CONFIRMATION ; FILE-NR'S IN T2, SHORT CALL ] MOVE T2,[.PRIIN,,.PRIOU] ;I/O WITH CONTROLLING TERMINAL GTJFN% ;GET JOB FILE NUMBER ERJMPS [ PUSHJ P,WARN ;IF ERROR, GIVE WARNING JRST OUTFIL] ;AND LET HIM TRY AGAIN MOVEM T1,OUTJFN ;SAVE THE JFN ;NOW, OPEN THE FILES WE JUST GOT ; INPUT MOVE T1,INJFN ;RETRIEVE THE INPUT JFN MOVX T2,FLD(7,OF%BSZ)+OF%RD ;MODES FOR OPENF ;[7-BIT BYTES + INPUT] OPENF% ;OPEN THE FILE ERJMPS FATAL ;IF ERROR, GIVE MESSAGE AND STOP ; OUTPUT MOVE T1,OUTJFN ;GET THE OUTPUT JFN 3-41 USING FILES USING FILES MOVX T2,FLD(7,OF%BSZ)+OF%WR ;MODES FOR OPENF ;[7-BIT BYTES + OUTPUT] OPENF% ;OPEN THE FILE ERJMPS FATAL ;IF ERROR, GIVE MESSAGE AND STOP ;*** MAIN LOOP: COPY BYTES FROM INPUT TO OUTPUT *** LOOP: MOVE T1,INJFN ;GET THE INPUT JFN BIN% ;TAKE A BYTE FROM THE SOURCE JUMPE T2,DONE ;IF 0, CHECK FOR END OF FILE MOVE T1,OUTJFN ;GET THE OUTPUT JFN BOUT ;OUTPUT THE BYTE TO DESTINATION ERCALS ERROR JRST LOOP ;LOOP, STOP ONLY ON A 0 BYTE ;(FOUND AT LOOP+2) ;*** TEST FOR END OF FILE, ON SUCCESS FINISH UP *** DONE: GTSTS% ;GET THE STATUS OF INPUT FILE TXNN T2,GS%EOF ;AT END OF FILE? JRST LOOP ;NO, FLUSH NULL AND CONTINUE COPY CLOSIF: MOVE T1,INJFN ;YES, RETRIEVE INPUT JFN CLOSF% ;CLOSE INPUT FILE ERJMPS FATAL ;IF ERROR, GIVE MESSAGE AND STOP CLOSOF: MOVE T1,OUTJFN ;RETRIEVE OUTPUT JFN CLOSF% ;CLOSE OUTPUT FILE ERJMPS FATAL ;IF ERROR, GIVE MESSAGE AND STOP TMSG < [DONE]> ;SUCCESSFULLY DONE JRST ZAP ;STOP ;*** ERROR HANDLING *** FATAL: TMSG < ?> ;FATAL ERRORS PRINT ? FIRST PUSHJ P,ERROR ;THEN PRINT ERROR MESSAGE JRST ZAP ;AND STOP WARN: TMSG < %> ;WARNINGS PRINT % FIRST ;AND FALL THRU 'ERROR' ;BACK TO CALLER ERROR: MOVEI T1,.PRIOU ;DECLARE PRINCIPAL OUTPUT DEVICE ;FOR ERROR MESSAGE MOVE T2,[.FHSLF,,-1] ;CURRENT FORK,, LAST ERROR SETZ T3, ;NO LIMIT,, FULL MESSAGE ERSTR% ;PRINT THE MESSAGE 3-42 USING FILES USING FILES JFCL ;IGNORE UNDEFINED ERROR NUMBER JFCL ;IGNORE ERROR DURING EXE OF ERSTR POPJ P, ;RETURN TO CALLER ZAP: HALTF% ;STOP JRST START ;WE ARE RESTARTABLE END START ;TELL LINKING LOADER START ADDRESS Example 2 - This program accepts input from a user at the terminal and then outputs the data to the line printer. Refer to Section 2.9 for explanation of the RDTTY% call. TITLE LPTPNT ;PROGRAM TO PRINT TERMINAL INPUT ;ON PRINTER SEARCH MONSYM ;SEARCH SYSTEM JSYS-SYMBOL LIBRARY SEARCH MACSYM .REQUIRE SYS:MACREL STDAC. ;DEFINE STANDARD ACs BUFSIZ==200 PDLEN==50 COUNT: BLOCK 1 LPTJFN: BLOCK 1 BUFFER: BLOCK BUFSIZ PDL: BLOCK PDLEN START: RESET% ;RESET I/O, ETC. MOVE P,[IOWD PDLEN,PDL] ;SET UP STACK TMSG ;OUTPUT PROMPTING TEXT HRROI T1,BUFFER ;GET POINTER TO BUFFER MOVE T2,[RD%BRK+BUFSIZ*5] ;GET FLAG AND MAX # OF CHARS TO READ SETZM T3 ;NO RE-TYPE BUFFER RDTTY% ;INPUT TEXT FROM TERMINAL EJSHLT ;ERROR, STOP HRRZS T2 ;GET CHARS REMAINING IN BUFFER MOVEI T1,BUFSIZ*5 ;COMPUTE NUMBER OF CHARS READ = SUB T1,T2 ;BUFFERSIZE MINUS CHARS REMAINING SOS T1 ;DON'T INCLUDE ^Z MOVEM T1,COUNT ;SAVE # OF CHARS INPUT ;GET A JFN FOR THE PRINTER AND OPEN THE PRINTER MOVX T1,GJ%SHT!GJ%FOU ;OUTPUT FILE, SHORT CALL HRROI T2,[ASCIZ /LPT:/] ;GET POINTER TO NAME OF FILE GTJFN% ;GET A JFN FOR THE PRINTER ERJMPS JFNERR ;ERROR, PRINT ERROR MESSAGE MOVEM T1,LPTJFN ;REMEMBER PRINTER JFN MOVX T2,FLD(7,OF%BSZ)+OF%WR ;7-BIT BYTES, ;WRITE ACCESS WANTED 3-43 USING FILES USING FILES OPENF% ;OPEN THE PRINTER FOR OUTPUT ERJMPS OPNERR ;ERROR, PRINT ERROR MESSAGE ;NOW OUTPUT THE TEXT THAT WAS INPUT FROM THE TERMINAL HRROI T2,BUFFER ;GET POINTER TO TEXT ;(PRINTER JFN STILL IN T1) MOVN T3,COUNT ;GET NUMBER OF CHARS TO OUTPUT SOUT% ;OUTPUT STRING OF CHARS TO ;THE PRINTER ERJMPS DATERR ;ERROR, PRINT ERROR MESSAGE TMSG < OUTPUT HAS BEEN SENT TO THE PRINTER... > ;OUTPUT CONFIRMATION MESSAGE MOVE T1,LPTJFN ;GET PRINTER JFN CLOSF% ;CLOSE IT ERJMPS DATERR ;UNEXPECTED ERROR, PRINT ERROR MESSAGE HALTF% ;FINISHED JRST START ;IF CONTINUED, GO BACK TO START ;ERROR ROUTINES JFNERR: TMSG< ? COULD NOT GET A JFN FOR THE PRINTER > HALTF% JRST START ;IF CONTINUED, GO BACK TO START OPNERR: TMSG< ? COULD NOT OPEN THE PRINTER FOR OUTPUT > HALTF% JRST START ;IF CONTINUED, GO BACK TO START DATERR: TMSG< ? DATA ERROR DURING OUTPUT TO PRINTER > HALTF% JRST START ;IF CONTINUED, GO BACK TO START END START 3-44 CHAPTER 4 CHAPTER 4 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM 4.1 OVERVIEW 4.1 OVERVIEW Program execution usually occurs in a sequential manner, where instructions are executed one after another. But sometimes a program must be able to receive asynchronous signals from terminals, the monitor, or other programs, or as a result of its own execution. By using the software interrupt system, the user can specify conditions that will cause his program to deviate from its sequential method of execution. An interrupt is defined as a break in the normal flow of control during a program's execution. The break, or interrupt, is caused by the occurrence of a prespecified condition. By specifying the conditions that can cause an interrupt, the program has the capability of dynamically responding to external events and error conditions and of generating requests for services. Because the program can respond to special conditions as they occur, it does not have to explicitly and repeatedly test for them. In addition, the program's execution is faster because the program does not have to include a special test after the possible occurrence of the condition. When an interrupt occurs, the system transfers control from the main program sequence to a previously-specified routine that will process the interrupt. After the routine has completed its processing of the interrupt, the system can transfer control back to the program at the point it was interrupted, and execution can continue. See Figure 4-1. 4-1 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM ----------------- | User Program | | is | | Executing | ----------------- | V ----------------- | Interrupt | | Condition | | Occurs | ----------------- | V ^ ^ / \ / \ / \ / \ / Has \ /Is An\ /Program\ /Inter- \ / Enabled \ /rupt of \ ----------------- /for Condi- \ Yes /Higher Pri-\ No | Execute | ----------->< ority Being >------->| User's Inter- | \ Channel / ^ \ Processed / | rupt Routine | \ ? / | \ ? / --------|-------- \ / | \ / | \ / | \ / | \ / | \ / | \ / | \ / | V | V | | No | | Yes | | | V | | | ---------------------- | V | | Wait Until | | ----------------- | | Higher Priority | | | Perform System| | | Interrupt Finishes | | | Default Action| | --------|------------- | | (e.g., stops | | | | | job, print | \-------------/ | | message) | | --------|-------- | | <------------------------------------------------/ V ----------------- | User Program | | Continues if | | Job Has Not | | Not Been | | Terminated | ----------------- 4-2 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM Figure 4-1: Basic Operational Sequence of the Software Interrupt Figure 4-1: Basic Operational Sequence of the Software Interrupt System System 4-3 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM 4.2 INTERRUPT CONDITIONS 4.2 INTERRUPT CONDITIONS Conditions that cause the program to be interrupted when the interrupt system is enabled are: 1. Conditions generated when specific terminal keys are typed. There are 36 possible codes; each one specifies the particular terminal character or condition on which an interrupt is to be initiated. Refer to Table 4-2 for the possible codes. 2. Invalid instructions (for example, I/O instructions given in user mode) or privileged monitor calls issued by a non privileged user. 3. Memory conditions, such as illegal memory references. 4. Arithmetic processor conditions, such as arithmetic overflow or underflow. 5. Certain file or device conditions, such as end of file. 6. Program-generated software interrupts. 7. Termination of an inferior process. 8. System resource unavailability. 9. Interprocess communication (IPCF) and Enqueue/Dequeue interrupts. 4.3 SOFTWARE INTERRUPT CHANNELS AND PRIORITIES 4.3 SOFTWARE INTERRUPT CHANNELS AND PRIORITIES Each condition is associated with one of 36 software interrupt channels. Most conditions are permanently assigned to specific channels; however, the user's program can associate some conditions (for example, conditions generated by specific terminal keys) to any one of the assignable channels. (Refer to Table 4-1 for the channel assignments.) When the condition associated with a channel occurs, and that channel has been activated, an interrupt is generated. Control can then be transferred to the routine responsible for processing interrupts on that channel. The user program assigns each channel to one of three priority levels. Priority levels allow the occurrence of some conditions to suspend the processing of other conditions. The levels are referred to as level 1, 2, or 3 with level 1 having the highest priority. Level 0 is not a legal priority level.[1] 4-4 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM Table 4-1: Software Interrupt Channel Assignments Table 4-1: Software Interrupt Channel Assignments ______________________________________________________________________ Channel Symbol Meaning ______________________________________________________________________ 0-5 Assignable by user program 6 .ICAOV Arithmetic overflow 7 .ICFOV Arithmetic floating point overflow 8 Reserved for Digital 9 .ICPOV Pushdown list (PDL) overflow* 10 .ICEOF End of file condition 11 .ICDAE Data error file condition* 12 .ICQTA Disk quota exceeded 13-14 Reserved for Digital 15 .ICILI Illegal instruction* 16 .ICIRD Illegal memory read* 17 .ICIWR Illegal memory write* 18 Reserved for Digital 19 .ICIFT Inferior process termination 20 .ICMSE System resources exhausted* 21 Reserved for Digital 22 .ICNXP Nonexistent page reference 23-35 Assignable by user program ______________________________________________________________________ --------------- [1] If an interrupt is generated in a process where the priority level is 0, the system considers that the process is not prepared to handle the interrupt. The process is then suspended or terminated according to the setting of bit 17 (SC%FRZ) in its capability word. 4-5 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM * These channels (called panic channels) cannot be completely deactivated. An interrupt generated on one of these channels terminates the process if the channel is not activated. The software interrupt system processes interrupts on activated channels only, and each channel can be activated and deactivated independently of other channels. When activated, the channel can generate an interrupt for its associated priority level. An interrupt for any priority level is initiated only if there are no interrupts in progress for the same or higher priority levels. If there are, the system remembers the interrupt request and initiates it after all equal or higher priority level interrupts finish. This means that a higher priority level request can suspend a routine processing a lower level interrupt. Thus, the user must be concerned with several items when he assigns his priority levels. He must consider 1) when one interrupt request can suspend the processing of another and 2) when the processing of a second interrupt cannot be deferred until the completion of the first. 4.4 SOFTWARE INTERRUPT TABLES 4.4 SOFTWARE INTERRUPT TABLES To process interrupts, the user includes, as part of his program, special service routines for the channels he will be using. He must then specify the addresses of these routines to the system by setting up a channel table. In addition, the user must also include a priority level table as part of his program. Finally, he must declare the addresses of these tables to the system. 4.4.1 Specifying the Software Interrupt Tables 4.4.1 Specifying the Software Interrupt Tables Before using the software interrupt system, the user's program must set up the contents of the channel table and the priority level table. The program must then specify their addresses with either the SIR% or XSIR% monitor calls. These calls are similar, but their differences are important. The SIR% call can be used in single-section programs, but the XSIR% call must be used in programs that use more than one section of memory. The SIR% call works in non-zero sections only if the tables are in the same section as the code that makes the call. The code that causes the interrupt must also be in that section, as must the code that processes the interrupt. Because of the limitations of the SIR% call, you should use the XSIR% call. The SIR% monitor call accepts two words of arguments: the identifier for the program (or process) in AC1, and the table addresses in AC2. Refer to Section 5.3 for the description of process identifiers. 4-6 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM The following example shows the use of the SIR% call. MOVEI 1,.FHSLF ;identifier of current process MOVE 2,[LEVTAB,,CHNTAB] ;addresses of the tables SIR% The XSIR% call accepts the following arguments: in AC1, the identifier of the process for which the interrupt channel tables are to be set; in AC2, the address of the argument block. The argument block is a three-word block that has the following format: !======================================================! ! Length of the argument block, including this word ! !------------------------------------------------------! ! Address of the interrupt level table ! !------------------------------------------------------! ! Address of the channel table ! !======================================================! Control always returns to the user's program at the instruction following the SIR% and XSIR% calls. If the call is successful, the table addresses are stored in the monitor. If the call is not successful, an illegal instruction trap is generated. Any changes made to the contents of the tables after the XSIR% or SIR% calls have been executed will be in effect at the time of the next interrupt. 4.4.2 Channel Table 4.4.2 Channel Table The channel table, CHNTAB,[2] contains a one-word entry for each channel; thus, the table has 36 entries. Each entry corresponds to a particular channel, and each channel is associated at any given time with only one interrupt condition. (Refer to Table 4-1 for the interrupt conditions associated with each channel.) The CHNTAB table is indexed by the channel number (0 through 35). The general format, for use with the XSIR% and XRIR% monitor calls, can be used in any section of memory. The left half of each entry contains the priority level (1, 2, or 3) in bits 0-5 (SI%LEV) to which the channel is assigned. Bits 6-35 (SI%ADR) of each entry contain the starting address of the routine to process interrupts generated on --------------- [2] The user can call his priority channel table any name he desires; however, it is good practice to call it CHNTAB. 4-7 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM that channel. If a particular channel is not used, the corresponding entry in the channel table should be zero. In the older format, for use with the SIR% and RIR% calls by any single-section program, the left half of each word contains the priority level (1, 2, or 3) for that channel. The right half contains the address of the interrupt routine that will handle interrupts on that channel. The following example is for use with the XSIR% monitor call. CHNTAB: FLD(2,SI%LEV)+FLD(CHN0SV,SI%ADR) ;channel 0 FLD(2,SI%LEV)+FLD(CHN1SV,SI%ADR) ;channel 1 FLD(2,SI%LEV)+FLD(CHN2SV,SI%ADR) ;channel 2 FLD(2,SI%LEV)+FLD(CHN3SV,SI%ADR) ;channel 3 0 ;channel 4 0 ;channel 5 FLD(1,SI%LEV)+FLD(APRSRV,SI%ADR) ;channel 6 0 ;channel 7 0 ;channel 8 FLD(1,SI%LEV)+FLD(STKSRV,SI%ADR) ;channel 9 0 ;channel 10 . . . . . . 0 ;channel 35 In this example, channels 0 through 3 are assigned to priority level 2, with the interrupt routine at CHN0SV servicing channel 0, the routine at CHN1SV servicing channel 1, the routine at CHN2SV servicing channel 2, and the routine at CHN3SV servicing channel 3. Channels 6 and 9 are assigned to priority level 1, with the routine at APRSRV servicing channel 6 and the routine at STKSRV servicing channel 9. All remaining channels are not assigned. 4.4.3 Priority Level Table 4.4.3 Priority Level Table The priority level table, LEVTAB,[3] The priority level table, LEVTAB, [3] is a three-word table, containing a one-word entry for each of the three priority levels. In the general form, each word contains the 30-bit address of the first word of the two-word block in the process address space. The block addressed by word n of LEVTAB is used to store the global PC flags and address when an interrupt of level n+1 occurs. The PC flags are stored in the first word of the PC block, and the PC --------------- [3] The user can call his priority level table any name he desires; however, it is good practice to call it LEVTAB. 4-8 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM address is stored in the second. This form of the table must be used with the XSIR% and XRIR% monitor calls, and can be used in any section. The older form of the interrupt level table can be used in any single-section program, and must be used with the SIR% and RIR% calls. This table also contains three words, indexed by the priority level minus 1. Each word contains zero in the left half, and the 18-bit address of the word in which to store the one-word section-relative PC in the right half. This address is assumed to be in the same program section that contained the SIR% monitor call. (For more information see Chapter 8.) The system must save the value of the program counter so that it can return control at the appropriate point in the program once the interrupt routine has completed processing an interrupt. If a particular priority level is not used, its corresponding entry in the level table should be zero. The following is a sample of a level table. LEVTAB: 0,,PCLEV1 ;Addresses to save PC for interrupts 0,,PCLEV2 ;occurring on priority levels 1 and 2. 0,,0 ;No priority level 3 interrupts are ;planned 4.5 ENABLING THE SOFTWARE INTERRUPT SYSTEM 4.5 ENABLING THE SOFTWARE INTERRUPT SYSTEM Once the interrupt tables have been set up and their addresses defined with the XSIR% monitor call, the user's program must enable the interrupt system. When the interrupt system is enabled, interrupts that occur on activated channels are processed by the user's interrupt routines. When the interrupt system is disabled, the monitor processes interrupts as if the channels for these interrupts were not activated. The EIR% monitor call, used to enable the system, accepts one argument: the identifier for the process in AC1. MOVEI 1,.FHSLF ;identifier of current process EIR% Control always returns to the instruction following the EIR call. 4.6 ACTIVATING INTERRUPT CHANNELS 4.6 ACTIVATING INTERRUPT CHANNELS Once the software interrupt system is enabled, the channels on which interrupts can occur must be activated (refer to Table 4-1 for the channel assignments). The channels to be activated have a nonzero entry in the appropriate word in the channel table. 4-9 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM The AIC% monitor call activates one or more of the 36 interrupt channels. This call accepts two words of arguments - the identifier for the process in AC1, and the channels to be activated in AC2. The channels are indicated by setting bits in AC2. Setting bit n indicates that channel n is to be activated. The AIC% call activates only those channels for which bits are set. MOVEI 1,.FHSLF ;identifier of current process MOVE 2,[1B<.ICAOV>+1B<.ICPOV>] ;activate channels 6 and 9 AIC% Control always returns to the instruction following the AIC% call. Some channels, called panic channels, cannot be deactivated by disabling the channel or the entire interrupt system. (Refer to Table 4-1 for these channels.) This is because the occurrence of the conditions associated with these channels cannot be completely ignored by the monitor. If one of these conditions occurs, an interrupt is generated whether the channel is activated or not. If the channel is not activated, the process is terminated, and usually a message is output before control returns to the monitor. If the channel is activated, control is given to the user's interrupt routine for that channel. 4.7 GENERATING AN INTERRUPT 4.7 GENERATING AN INTERRUPT A process generates an interrupt by producing a condition for which an interrupt channel is enabled, such as arithmetic overflow, or by using the IIC% monitor call. This call can generate an interrupt on any of the 36 interrupt channels of the process the calling process specifies. See Section 5.10 for a description of the IIC% call. 4.8 PROCESSING AN INTERRUPT 4.8 PROCESSING AN INTERRUPT When a software interrupt occurs on a given priority level, the monitor stores the current program counter (PC) word in the address indicated in the priority level table (refer to Section 4.4.3). The monitor then transfers control to the interrupt routine associated with the channel on which the interrupt occurred. The address of this routine is specified in the channel table (refer to Section 4.4.2). Since the user's program cannot determine when an interrupt will occur, the interrupt routine must preserve the state of the program so the program can be resumed properly. First, the routine stores the contents of any user accumulators for use while processing the interrupt. After the accumulators are saved, the interrupt routine processes the interrupt. 4-10 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM Occasionally, an interrupt routine may need to alter locations in the main section of the program. For example, a routine may change the stored PC word to resume execution at a location different from where the interrupt occurred. Or it may alter a value that caused the interrupt. It is important that care be used when writing routines that alter data because any changes will remain when control is returned to the main program. For example, if data is inadvertently stored in the PC word, return to the main section of the program would be incorrect when the system attempted to use the word as the value of the program counter. If a higher-priority interrupt occurs during the execution of an interrupt routine, the execution of the lower-priority routine is suspended. The value of its program counter is stored at the location indicated in the priority level table for the new interrupt. When the routine for this new interrupt is completed, the suspended routine resumes. If an interrupt of the same or lower priority occurs during the execution of a routine, the monitor holds the interrupt until all higher or equal level interrupts have been processed. The system considers the user's program unable to process an interrupt on an activated channel if any of the following is true: 1. The priority level associated with the channel is 0. 2. The program has not defined its interrupt tables by executing an XSIR% or SIR% monitor call. 3. The process has not enabled the interrupt system by executing an EIR% monitor call, and the channel on which the interrupt occurs is a panic channel. In any of these cases, an interrupt on a panic channel terminates the user's program. All other interrupts are ignored. 4.8.1 Dismissing an Interrupt 4.8.1 Dismissing an Interrupt Once the processing of an interrupt is complete, the interrupt routine should restore the user accumulators to their initial values. Then it should return control to the interrupted code by using the DEBRK% monitor call. This call restores the PC word and resumes the program. The call has no arguments, and must be the last statement in the interrupt routine. If the interrupt-processing routine has not changed the PC of the user's program, the DEBRK% call restores the program to the same state 4-11 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM the program was in just before the interrupt occurred. If the program was interrupted while waiting for I/O to complete, for example, the program will again be waiting for I/O to complete when it resumes execution after the DEBRK% call. If the PC word was changed, the program resumes execution at the new PC location. The state of the program is unchanged. 4.9 TERMINAL INTERRUPTS 4.9 TERMINAL INTERRUPTS The user's program can associate channels 0 through 5 and channels 24 through 35 with occurrences of various conditions, such as the occurrence of a particular character typed at the terminal or the receipt of an IPCF message. This section discusses terminal interrupts; refer to Chapters 6 and 7 for other types of assignable interrupts. There are 36 codes used to specify terminal characters or conditions on which interrupts can be initiated. These codes, along with their associated conditions, are shown in Table 4-2. Table 4-2: Terminal Codes and Conditions Table 4-2: Terminal Codes and Conditions ______________________________________________________________________ Code Symbol Character or Condition ______________________________________________________________________ 0 .TICBK CTRL/@ or break 1 .TICCA CTRL/A 2 .TICCB CTRL/B 3 .TICCC CTRL/C 4 .TICCD CTRL/D 5 .TICCE CTRL/E 6 .TICCF CTRL/F 7 .TICCG CTRL/G 8 .TICCH CTRL/H 9 .TICCI CTRL/I 10 .TICCJ CTRL/J 4-12 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM 11 .TICCK CTRL/K 12 .TICCL CTRL/L 13 .TICCM CTRL/M 14 .TICCN CTRL/N 15 .TICCO CTRL/O 16 .TICCP CTRL/P 17 .TICCQ CTRL/Q 18 .TICCR CTRL/R 19 .TICCS CTRL/S 20 .TICCT CTRL/T 21 .TICCU CTRL/U 22 .TICCV CTRL/V 23 .TICCW CTRL/W 24 .TICCX CTRL/X 25 .TICCY CTRL/Y 26 .TICCZ CTRL/Z 27 .TICES ESC key 28 .TICRB Delete (or rubout) key 29 .TICSP Space 30 .TICRF Dataset carrier off 31 .TICTI Typein 32 .TICTO Typeout 33 .TITCE Two-character escape sequence 34-35 Reserved ______________________________________________________________________ To cause terminal interrupts to be generated, the user's program must assign the desired terminal code to one of the assignable channels. 4-13 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM The ATI% monitor call is used to assign this code. This call accepts one word of arguments: the terminal code in the left half of AC1 and the channel number in the right half. MOVE 1,[.TICCE,,INTCH1] ;assign CTRL/E to channel INTCH1 ATI% Control always returns to the instruction following the ATI% call. If the current job is not attached to a terminal (there is no terminal controlling the job), the terminal code assignments are remembered; they will be in effect when a terminal is attached. The monitor handles the receipt of a terminal interrupt character in either immediate mode or deferred mode. In immediate mode, the terminal character causes the system to initiate an interrupt as soon as the user types the character (that is, as soon as the system receives it). In deferred mode, the terminal character is placed in either immediate mode or deferred mode. In immediate mode, the terminal character causes the system to initiate an interrupt as soon as the user types the character (as soon as the system receives it). In deferred mode, the terminal character is placed in the input stream in sequence with other characters of the input, unless two of the same character are typed in succession. In this case, an interrupt occurs at the time the second one is typed. If only one character enabled in deferred mode is typed, the system initiates an interrupt only when the program attempts to read the character. Deferred mode allows interrupt actions to occur in sequence with other actions specified in the input (for example, when characters are typed ahead of the time that the program actually requests them). In either mode, the character is not passed to the program as data. The system assumes that interrupts are to be handled immediately unless a program has issued the STIW% (Set Terminal Interrupt Word) monitor call. (Refer _______ _______ _____ _________ ______ to TOPS-20 Monitor Calls Reference Manual for a description of this call.) 4.10 ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS 4.10 ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS Additional monitor calls are available that allow the user's program to check and to clear various parts of the software interrupt system. Also, there is a call useful for interprocess communication (refer to the IIC% call in Section 5.10). 4.10.1 Testing for Enablement 4.10.1 Testing for Enablement The SKPIR% monitor call tests the software interrupt system to see if it is enabled. The call accepts in AC1 the identifier of the process. After execution of the call, control returns to the next instruction if the system is off, and to the second instruction if the system is on. 4-14 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM MOVEI 1,.FHSLF ;identifier of current process SKPIR% ;test interrupt system return ;system is off return ;system is on 4.10.2 Obtaining Interrupt Table Addresses 4.10.2 Obtaining Interrupt Table Addresses The RIR% and XRIR% monitor calls obtain the channel and priority level table addresses for a process. These calls are useful when several routines in one process want to share the interrupt tables. 4.10.2.1 The RIR% Monitor Call 4.10.2.1 The RIR% Monitor Call - The RIR% monitor call can be used in any section of memory, but is only useful for obtaining table addresses if those tables are in the same section of memory as the code that makes the call. Furthermore, it can only obtain table addresses that have been set by the SIR call. The call accepts the identifier of the process in AC1. It returns the table addresses in AC2. The left half of AC2 contains the section-relative address of the priority level table, and the right half contains the section-relative address of the channel table. If the process has not set the table addresses with the SIR% monitor call, AC2 contains zero. Control always returns to the instruction following the RIR% call. The following example shows the use of the RIR% call. MOVEI 1,.FHSLF ;identifier of current process RIR% ;return the table addresses 4.10.2.2 The XRIR% Monitor Call 4.10.2.2 The XRIR% Monitor Call - This call obtains the addresses of the interrupt tables defined for a process. The tables can be in any section of memory. The code that makes the call can also be in any section. This call can only obtain addresses that have been set by the XSIR% call. The call accepts the identifier of the process in AC1, and the address of the argument block in AC2. The argument block is three words long, word zero must contain the number 3. The call returns the addresses into words one and two. The block has the following format: 4-15 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM !=======================================================! ! Length of the argument block, including this word ! !-------------------------------------------------------! ! Address of the interrupt level table ! !-------------------------------------------------------! ! Address of the channel table ! !=======================================================! Control always returns to the instruction following the XRIR% call. If the process has not set the table addresses with the XSIR% monitor call, words one and two of the argument block contain zero. 4.10.3 Disabling the Interrupt System 4.10.3 Disabling the Interrupt System The DIR% monitor call disables the software interrupt system for the process. It accepts the identifier of the process in AC1. MOVEI 1,.FHSLF ;identifier of current process DIR% ;disable system Control always returns to the instruction following the DIR% call. If interrupts occur while the interrupt system is disabled, they are remembered until the system is reenabled. At that time, the interrupts take effect unless an intervening CIS% monitor call (refer to Section 4.10.6) has been issued. Software interrupts assigned to panic channels are not completely disabled by the DIR% call. These interrupts terminate the process, and the superior process is notified if it has enabled channel .ICIFT. In addition, if the terminal code for CTRL/C (.TICCC) is assigned to a channel, it causes an interrupt that cannot be disabled by the DIR% call. However, the CTRL/C interrupt can be disabled by deactivating the channel assigned to the CTRL/C terminal code. 4.10.4 Deactivating a Channel 4.10.4 Deactivating a Channel The DIC% monitor call is used to deactivate interrupt channels. The call accepts two words of arguments: the process identifier in AC1, and the channels to be deactivated in AC2. Setting bit n in AC2 indicates that channel n is to be deactivated. MOVEI 1,.FHSLF ;identifier of current process MOVE 2,[1B<.ICAOV>+1B<.ICPOV>] ;deactivate channels 6 and 9 DIC% Control always returns to the instruction following the DIC% call. 4-16 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM When a channel is deactivated, interrupt requests for that channel are ignored except for interrupts generated on panic channels (refer to Section 4.6). 4.10.5 Deassigning Terminal Codes 4.10.5 Deassigning Terminal Codes The DTI% monitor call deassigns a terminal code. This call accepts one argument word: the terminal code in AC1. MOVEI 1,.TICCE ;deassign CTRL/E DTI% Control always returns to the instruction following the DTI% call. This monitor call is ignored if the specified terminal code has not been defined by the current job. 4.10.6 Clearing the Interrupt System 4.10.6 Clearing the Interrupt System The CIS% monitor call clears the interrupt system for the current process. This call clears interrupts in progress and all waiting interrupts. This call requires no arguments, and control always returns to the instruction following the CIS call. The RESET% monitor call (refer to Section 2.6.1) performs these same actions as part of its initializing procedures. 4.11 SUMMARY 4.11 SUMMARY To use the software interrupt system, the user's program must: 1. Supply routines that will process the interrupts. 2. Set up a channel table containing the addresses of the routines (refer to Section 4.4.2) and a priority level table containing the addresses for storing the program counter (PC) values (refer to Section 4.4.3). 3. Specify the addresses of the tables with the XSIR% monitor call (refer to Section 4.4.3). 4. Enable the software interrupt system with the EIR% monitor call (refer to Section 4.5). 5. Activate the desired channels with the AIC% monitor call (refer to Section 4.6). 4-17 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM 4.12 SOFTWARE INTERRUPT EXAMPLE 4.12 SOFTWARE INTERRUPT EXAMPLE This program copies one file to another. It accepts the input and output filenames from the user. The end of file is detected by a software interrupt, and CTRL/E is enabled as an escape character. TITLE SOFTWARE INTERRUPT EXAMPLE SEARCH MONSYM SEARCH MACSYM .REQUIRE SYS:MACREL STDAC. ;DEFINE STANDARD ACs INTCH1=1 START: RESET% ;RELEASE FILES, ETC. XHLLI T1,EOFINT ;GET CURRENT PROCESS SECTION NUMBER HLLZS T1 ;ISOLATE SECTION NUMBER ONLY IORM T1,CHNTAB+INTCH1 ; AND ADD IT TO SERVICE ROUTINE IORM T1,CHNTAB+.ICEOF ;ADDRESSES FOR OUR ROUTINES IORM T1,LEVTAB+1 ; AND LEVTAB MOVEI T1,.FHSLF ;CURRENT PROCESS MOVEI T2,3 ;NUMBER OF WORDS IN ARG BLOCK MOVEM T2,ARGBLK ;PUT NUMBER IN WORD ZERO XMOVEI T2,LEVTAB ;GLOBAL ADDRESS OF LEVEL TABLE MOVEM T2,ARGBLK+1 ;MOVE IT TO ARGBLK WORD ONE XMOVEI T2,CHNTAB ;GLOBAL ADDRESS OF CHANNEL TABLE MOVEM T2, ARGBLK+2 ;MOVE IT TO ARGBLK WORD TWO XMOVEI T2,ARGBLK ;GLOBAL ADDRESS OF ARGUMENT BLOCK XSIR% EIR% ;ENABLE SYSTEM MOVE T2,[1B+1B<.ICEOF>] ;ACTIVATE CHANNELS AIC% MOVE T1,[.TICCE,,INTCH1] ;ASSIGN CTRL/E TO CHANNEL 1 ATI% GETIF: TMSG MOVX T1,GJ%OLD+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT MOVE T2,[.PRIIN,,.PRIOU] GTJFN% ;GET FILENAME FROM USER ERJMP ERROR1 MOVEM T1,INJFN GETOF: TMSG MOVX T1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT MOVE T2,[.PRIIN,,.PRIOU] GTJFN% ;GET FILENAME FROM USER ERJMP ERROR2 MOVEM T1,OUTJFN 4-18 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM OPNIF: MOVE T1,INJFN MOVX T2,FLD(7,OF%BSZ)+OF%RD OPENF% ;OPEN INPUT FILE ERJMP ERROR3 OPNOF: MOVE T1,OUTJFN MOVX T2,FLD(7,OF%BSZ)+OF%WR OPENF% ;OPEN OUTPUT FILE ERJMP ERROR3 CPYBYT: MOVE T1,INJFN BIN% ;READ INPUT BYTE MOVE T1,OUTJFN BOUT% ;WRITE OUTPUT BYTE JRST CPYBYT ;LOOP UNTIL EOF DONE: MOVE T1,INJFN CLOSF% ;CLOSE INPUT FILE JFCL MOVE T1,OUTJFN CLOSF% ;CLOSE OUTPUT FILE JFCL HALTF% ;ROUTINE TO HANDLE ^E - ABORTS OPERATION CTRLE: MOVEI T1,.PRIOU CFOBF% ;CLEAR OUTPUT BUFFER TMSG ;INFORM USER CIS% ;CLEAR SYSTEM JRST START ;ROUTINE TO HANDLE EOF - COMPLETES OPERATION NORMALLY EOFINT: MOVEM T1,INTAC1 ;SAVE ACs XMOVEI T1,DONE ;CHANGE PC MOVEM T1,PC2+1 ;TO DONE MOVE T1,INTAC1 ;RESTORE ACs DEBRK% ;DISMISS INTERRUPT ;LEVEL TABLE LEVTAB: 0 PC2 0 PC2: BLOCK 2 4-19 USING THE SOFTWARE INTERRUPT SYSTEM USING THE SOFTWARE INTERRUPT SYSTEM ;CHANNEL TABLE CHNTAB: 0 FLD(2,SI%LEV)!FLD(CTRLE,SI%ADR) REPEAT ^D8,<0> FLD(2,SI%LEV)!FLD(EOFINT,SI%ADR) REPEAT ^D25,<0> ARGBLK: BLOCK 3 INJFN: BLOCK 1 OUTJFN: BLOCK 1 INTAC1: BLOCK 1 ERROR1: TMSG < ?INVALID FILE SPECIFICATION> HALTF% ERROR2: TMSG < ?INVALID FILE SPECIFICATION> HALTF% ERROR3: TMSG < ?CANNOT OPEN FILE> HALTF% LIT END START 4-20 CHAPTER 5 CHAPTER 5 PROCESS STRUCTURE PROCESS STRUCTURE As stated in Chapter 1, the TOPS-20 operating system allows each job to have multiple processes that can run simultaneously. Each process has its own environment called its address space. Associated with the environment is the program counter (PC) of the process and a well-defined relationship with other processes in the job. In TOPS-20, the term fork is synonymous with the term process. The TOPS-20 operating system schedules the running of processes, not entire jobs. A process can be scheduled independent of other processes because it has a definite existence: its beginning is the time at which it is created, and its end is the time at which it is killed. At any point in its existence, a process can be described by its state, which is represented by a status word and a PC word (refer to Section 5.9). The relationships among processes in a job are shown in the diagram below. Each process has one immediate superior process (except for the top-level process) and can have one or more inferior processes. Two processes are parallel if they have the same immediate superior. A process can create an inferior process but not a parallel or superior process. -------------- | Top-Level | | Process | -------------- | ----------------------|-------------------- | | | ------------- ------------- ------------- | Process 1 | | Process 2 | | Process 3 | ------------- ------------- ------------- | | ------------- ------------- | Process 4 | | Process 5 | ------------- ------------- 5-1 PROCESS STRUCTURE PROCESS STRUCTURE Process 1 is the superior process of process 4, and process 3 is the superior of process 5. Processes 4 and 5 are the inferiors of processes 1 and 3, respectively. Process 2 has no inferior process. Processes 1, 2 and 3 are parallel because they have the same superior process (the top-level process). Processes 4 and 5, although at the same depth in the structure, are not parallel because they do not have the same superior process. Process 1 created process 4 but could not have created any other process shown in the structure above. 5.1 USES FOR MULTIPLE PROCESSES 5.1 USES FOR MULTIPLE PROCESSES A multiple-process job structure allows: 1. One job to have more than one program runnable at the same time. These programs can be independent programs, each one compiled, debugged, and loaded separately. Each program can then be placed in a separate process. These processes can be parallel to each other, but are inferior to the main process that created them. This use allows parallel execution of the individual programs. 2. One process to wait for an event to occur (for example, the completion of an I/O operation) while another process continues its computations. Communication between the two processes is such that when the event occurs, the process that is computing can be notified via the software interrupt system. This use allows two processes within a job to overlap I/O with computations. One application of a multiple-process job structure is the following situation: a superior process is responsible for accepting input from various terminals. After receiving this input, the process sends it to various inferior processes as data. These inferior processes can then initiate other processes, for example, to write reports on the data that was received. 5-2 PROCESS STRUCTURE PROCESS STRUCTURE ------------------ --------- | | --------- | | | Process that | | | | TTY |------| Accepts input |-----| TTY | | | | from Terminals | | | --------- | | --------- ------------------ | -------------|------------- | | | | | | ------- ------- ------- | | | | | | Processes that | | | | | | Receive the | | | | | | input as Data ------- ------- ------- | | | | | | ------- ------- ------- | | | | | | Processes that | | | | | | Write Reports | | | | | | on the Data ------- ------- ------- Another application is that used for the user interface on the DECSYSTEM-20. On the DECSYSTEM-20, the top-level process in the job structure is the Command Language. This process services the user at the terminal by accepting input. When the user runs a program (for example, MACRO, FORTRAN), the Command Language process creates an inferior process, places the requested program in it, and executes it. The Command Language can then wait for an event to occur, either from the program or from the user. An event from the program can be its completion, and an event from the user can be the typing of a certain terminal key (CTRL/C, for example). 5.2 PROCESS COMMUNICATION 5.2 PROCESS COMMUNICATION A process can communicate with or control other processes in the system in several ways: o direct process control o software interrupts o IPCF and ENQ/DEQ facilities o memory sharing 5-3 PROCESS STRUCTURE PROCESS STRUCTURE 5.2.1 Direct Process Control 5.2.1 Direct Process Control A process can create and control other processes inferior to it within the job structure. The superior process can cause the inferior process to begin execution and then to suspend and later resume execution. After the inferior process has completed its tasks, the superior process can delete the inferior from the job structure. Some of the monitor calls used for direct process control are: CFORK%, to create a process; SFORK%, to start a process; WFORK%, to wait for a process to terminate; RFSTS%, to obtain the status of a _______ process; and KFORK%, to delete a process. Refer to the TOPS-20 _______ _____ _________ ______ Monitor Calls Reference Manual for descriptions of additional monitor calls dealing with process control. 5.2.2 Software Interrupts 5.2.2 Software Interrupts The software interrupt facility enables a process to receive asynchronous signals from other processes, the system, or the terminal user or to receive signals as a result of its own execution. For example, a superior process can enable the interrupt system so that it receives an interrupt when one of its inferiors terminates. In addition, processes within a job structure can explicitly generate interrupts to each other for communication purposes. Some of the monitor calls used when communication occurs via the software interrupt system are: SIR%, to specify the interrupt tables; EIR%, to enable the interrupt system; AIC%, to activate the interrupt channels; and IIC%, to initiate an interrupt on a channel. Refer to Chapter 4 and Section 5.10 for more information. 5.2.3 IPCF and ENQ/DEQ Facilities 5.2.3 IPCF and ENQ/DEQ Facilities The Inter-Process Communication Facility (IPCF) enables processes and jobs to communicate by sending and receiving informational messages. The MSEND% call is used to send a message, the MRECV% call is used to receive a message, and the MUTIL% call is used to perform utility functions. Refer to Chapter 7 for descriptions of these calls. The ENQ/DEQ facility allows cooperating processes to share resources and facilitates dynamic resource allocation. The ENQ% call is used to obtain a resource, the DEQ% call is used to release a resource, and the ENQC% call is used to obtain status about a resource. Refer to Chapter 6 for descriptions of these calls. 5-4 PROCESS STRUCTURE PROCESS STRUCTURE 5.2.4 Memory Sharing 5.2.4 Memory Sharing Each page or section in a process' address space is either private to the process or shared with other processes. Pages are shared among processes when the same page is represented in more than one process' address space. This means that two or more processes can identify and use the same page of physical storage. Even when several processes have identified the same page, each process can have a different access to that page, such as access to read or write that page. A type of page access that facilitates sharing is the copy-on-write access. A page with this access remains shared as long as all processes read the page. As soon as a process writes to the page, the system makes a private copy of the page for the process doing the writing. Other processes continue to read and execute the original page. This access provides the capability of sharing as much as possible but still allows the process to change its data without changing the data of other processes. A monitor call used when sharing memory is PMAP%. Refer to Section 5.6.2 for more information. 5.3 PROCESS IDENTIFIERS 5.3 PROCESS IDENTIFIERS In order for processes to communicate with each other, a process must have an identifier, or handle, for referencing another process. When a process creates an inferior process, it is given a handle on that inferior. This handle is a number in the range 400001 to 400777 and is meaningful only to the process to which it is given (that is, to the superior process). For example, if process A creates process B, process A is given a handle (for example, 400003) on process B. Process A then specifies this handle when it uses monitor calls that refer to process B. However, process B is not known by this handle to any other process in the structure, including itself. The handle 400003 may in fact be known to process B, but it would describe a process inferior to process B. For this reason, process handles are sometimes called "relative fork handles" because they are relative to the process that created them. There are several standard process handles that are never assigned by the system but have a specific meaning when used by any process in the structure. These handles are used when a process needs to communicate with a process other than its immediate inferior or with multiple processes at once. These handles are described in Table 5-1. 5-5 PROCESS STRUCTURE PROCESS STRUCTURE Table 5-1: Process Handles Table 5-1: Process Handles ______________________________________________________________________ Number Symbol Meaning ______________________________________________________________________ 400000 .FHSLF The current process (or self). 400000+n Process n, relative to the current process. 200000 FH%EPN Extended page number (see PM%EPN in PMAP%). When used in conjunction with the above two forms, this bit indicates that addresses and/or page numbers are interpreted as absolute, not relative to the PC section of the program executing the JSYS. This bit has no meaning for programs that do not use extended addressing. -1 .FHSUP The immediate superior of the current process. -2 .FHTOP The top-level process in the job structure. -3 .FHSAI The current process and all of its inferiors. -4 .FHINF All of the inferiors of the current process. -5 .FHJOB All processes in the job structure. ______________________________________________________________________ Consider the job structure below. 5-6 PROCESS STRUCTURE PROCESS STRUCTURE ------- | A | ------- | ---------------|--------------- | | | ------- ------- ------- | B | | C | | D | ------- ------- ------- | --------|------- | | ------- ------- | E | | F | ------- ------- | -------|-------- | | ------- ------- | G | | H | ------- ------- The following indicates the specific process or processes being referenced if process E gives the handle: .FHSLF refers to process E .FHSUP refers to process D .FHTOP refers to process A .FHSAI refers to processes E, G, and H .FHINF refers to processes G and H .FHJOB refers to processes A through H The process must have the appropriate capability enabled in its capability word to use the handles .FHSUP, .FHTOP, and .FHJOB (refer to Section 5.5.1). Process E can reference one of its inferiors (for example, G) with the handle it was given when it created the inferior. Process E can reference other processes in the structure (for example, F) by executing the GFRKS% monitor call to obtain a handle on the desired _______ _______ _____ _________ ______ process. Refer to the TOPS-20 Monitor Calls Reference Manual for a description of the GFRKS% call. 5.4 OVERVIEW OF MONITOR CALLS FOR PROCESSES 5.4 OVERVIEW OF MONITOR CALLS FOR PROCESSES Monitor calls exist for creating, loading, starting, suspending, resuming, interrupting, and deleting processes. When a process is created, its address space is assigned, and the process is added to the job structure of the creating process. The contents of its 5-7 PROCESS STRUCTURE PROCESS STRUCTURE address space can be specified at the time the process is created or at a later time. The process can also be started at the time it is created. A process remains potentially runnable until it is explicitly deleted or its superior is deleted. A process may be suspended if one of the following conditions occurs: 1. The process executes an instruction that causes a software interrupt to occur, and it is not prepared to process the interrupt. 2. The process executes the HALTF% monitor call. 3. The superior process requests suspension of its inferior. 4. The superior process is suspended. When a process is suspended, all of its inferior processes are also suspended. 5. A monitor call is trapped. (Refer to TFORK% monitor call in _______ _______ _____ _________ ______ the TOPS-20 Monitor Calls Reference Manual). 5.5 CREATING A PROCESS 5.5 CREATING A PROCESS A process creates an inferior process by executing the CFORK% (Create Process) monitor call. This monitor call allows the caller to specify the address space, capabilities, initial contents of the ACs, and PC for the inferior process and to start the execution of the inferior. The CFORK% call accepts two words of arguments in AC1 and AC2. AC1: characteristics for the inferior in the left half, and PC address for the inferior in the right half. AC2: address of a 20 (octal) word block containing the AC values for the inferior. The characteristics for the inferior process are described in Table 5-2. 5-8 PROCESS STRUCTURE PROCESS STRUCTURE Table 5-2: Inferior Process Characteristic Bits Table 5-2: Inferior Process Characteristic Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 CR%MAP Set the map of the inferior process to the same as the map of the superior (creating) process. This means that the superior and the inferior will share the same address space. Changes made by one process will be seen by the other process. If this bit is not on in the call, the inferior's map will contain all zeros. If desired, the creating process can then use PMAP or GET to add pages to the inferior's map. 1 CR%CAP Set the capability word of the inferior process to the same as the capability word of the superior process. (Refer to Section 5.5.1 for the description of the capability word.) If this bit is not on in the call, the inferior will have no special capabilities. 2 Reserved for Digital (must be 0). 3 CR%ACS Set the ACs of the inferior process to the values beginning at the address given in AC2. If this bit is not on in the call, the inferior's ACs will be set to zero, and the contents of AC2 is ignored. 4 CR%ST Set the PC for the inferior process to the address given in the right half of AC1 and start execution of the inferior. If this bit is not on in the call, the right half of AC1 is ignored, and the inferior is not started. If desired, the creating process can then use SFORK% or XSFRK% to start the newly created process. 18-35 CR%PCV PC value for inferior process if CR%ST is on. ______________________________________________________________________ 5-9 PROCESS STRUCTURE PROCESS STRUCTURE If execution of the CFORK% call is not successful, the inferior process is not created and an error code is returned, as described in Section 1.2.2. If execution of the CFORK% call is successful, the inferior process is created and its process handle is returned in the right half of AC1. This handle is then used by the superior process when communicating with its inferior process. The execution of the program in the superior process continues at the second instruction following the CFORK% call. The inferior begins execution at the location contained in bits 18-35 (CR%PCV) if CR%ST is specified. Assume that process A executes the CFORK% monitor call twice to create two parallel inferior processes. This is represented pictorially below. ------------------------- | Process A | | Creates Process B | | by Executing a CFORK | ------------------------- | | ------------------------- | Process B is Created | | and Its Handle is | | | ------------------------- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- ------------------------- | Process A Executes | | Another CFORK to | | Create Process C | ------------------------- | ---------------------|--------------------- | | ------------------------- ------------------------ | | | Process C is Created | | Process B | | and Its Handle | | | | Given to Process A | ------------------------- ------------------------ Note that process A has been given two handles, one for process B and one for process C. Process A can refer to either of its inferiors by giving the appropriate handle or to both of its inferiors by giving a handle of -4 (.FHINF). 5-10 PROCESS STRUCTURE PROCESS STRUCTURE 5.5.1 Process Capabilities 5.5.1 Process Capabilities When a new process is created, it is given the same capabilities as its superior, or it is given no special capabilities. This is indicated by the setting of the CR%CAP bit in the CFORK% call. The capabilities for a process are indicated by two capability words. The first word indicates if the capability is available to the process, and the second word indicates if the capability is enabled for the process. This second word is the one being set by the CR%CAP bit in the CFORK% call. Types of capabilities represented in the capability words are job, process, and user capabilities. Each capability corresponds to a particular bit in the capability words and thus can be activated and protected independently of the other capabilities. Refer to the _______ _______ _____ _________ ______ TOPS-20 Monitor Calls Reference Manual for more information on the capability words. 5.6 SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A PROCESS 5.6 SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A PROCESS Once a process is created, the contents of its address space can be specified. This can be accomplished in one of three ways. As mentioned in Section 5.5, bit CR%MAP can be set in the CFORK% call to indicate that the address space of the inferior process is to be the same as the address space of the creating process. In addition, the creating process can execute the GET% monitor call to map specified pages from a file into the address space of the inferior process. Finally, the creating process can execute the PMAP% monitor call to map specified pages from another process into the address space of the inferior process. If the creating process does not specify the contents of the inferior's address space, the address space will be filled with zeros. 5.6.1 GET% Monitor Call 5.6.1 GET% Monitor Call The GET% monitor call gets a save file, copying or mapping it into the process as appropriate. It updates the monitor's data base for the process by copying the entry vector and the list of program data vector addresses (PDVAs) from the save file. (See the .POADD function of the PDVOP% monitor call.) This call can be executed for either sharable or nonsharable save files that were created with the SSAVE% or SAVE% monitor call, respectively. The file must not be open by any process in the user's _______ _______ _____ _________ ______ job. (Refer to the TOPS-20 Monitor Calls Reference Manual for more information regarding the PDVOP%, SSAVE%, and SAVE% monitor calls.) 5-11 PROCESS STRUCTURE PROCESS STRUCTURE The GET% monitor call accepts two words of arguments in AC1 and AC2. The first word specifies the handle of the desired process, flag bits, and the JFN of the desired file. The second word specifies where the pages from the file are to be placed in the address space of the process. Thus, AC1: process handle,,flag bits and a JFN AC2: lowest process page number in left half, and highest process page number in right half; or the address of an argument block. If this AC contains page numbers, those page numbers control the parts of memory that are loaded when GT%ADR is on in AC1. Table 5-3 describes the bits that can be set in AC1. Table 5-3: GET% Flag Bits Table 5-3: GET% Flag Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 19 GT%ADR Use the memory address limits given in AC2. If this bit is off, all existing pages of the file (according to its directory) are mapped. 20 GT%PRL Preload the pages being mapped (move the pages immediately.) If this bit is off, the pages are read in from the disk when they are referenced. 21 GT%NOV Do not overlay existing pages and do return an error. If this bit is off, existing pages will be overlaid. 22 GT%ARG If this bit is on, AC2 contains the address of an argument block. 24-25 GT%JFN JFN of the save file. ______________________________________________________________________ The format of the argument block is described in Table 5-4. 5-12 PROCESS STRUCTURE PROCESS STRUCTURE Table 5-4: GET% Argument Block Table 5-4: GET% Argument Block ______________________________________________________________________ Word Symbol Meaning ______________________________________________________________________ 0 .GFLAG Flags that indicate how the rest of the argument block is to be used. 1 .GLOW Number of the lowest page in the process into which a file page gets loaded. This page must be within the section specified by .GBASE. 2 .GHIGH Number of the highest page in the process into which a file page gets loaded. This page must be within the section specified by .GBASE. 3 .GBASE Number of the section into which the file pages are loaded. You can specify the section for single-section save files only; use of this word with a multiple-section save file causes an error. The file pages are loaded into this section of memory regardless of the section specified in the save file. ______________________________________________________________________ Table 5-5 describes the flag bits defined for use in .GFLAG. Table 5-5: GET% Argument Block Flags Table 5-5: GET% Argument Block Flags ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 GT%LOW .GLOW contains the number of the lowest page within the process to use. 1 GT%HGH .GHIGH contains the number of the highest page within the process to use. 2 GT%BAS .GBASE contains the number of the section to use. ______________________________________________________________________ 5-13 PROCESS STRUCTURE PROCESS STRUCTURE When the pages of the file are mapped into pages in the process's address space, the previous contents of the process pages are overwritten. Any full pages in the process that are not overwritten are unchanged. Any portions of process pages for which there is no data in the file are filled with zeros. For example, a GET% call executed for a file that contains 2 1/2 pages sets up the process' address space as shown in the following diagram. Process File ------------ - - - - - - - - --------- Page 1 | Data | / | Data | Page 1 | | | | | | | | | | | | / GET | | |----------| \ Call |-------| Page 2 | Data | | | Data | Page 2 | | | | | |----------| | |-------| Page 3 | Data | \ | Data | Page 3 |----------| - - - - - - - - |-------| | | | EOF | | | | | | 0 | | | |----------| --------- | | Page 4 - |Unchanged | Page 512 | | ------------ After execution of the GET% call, control returns to the user's program at the instruction following the call. If an error occurs, a software interrupt is generated, which the program can process via the software interrupt system. 5.6.2 PMAP% Monitor Call 5.6.2 PMAP% Monitor Call The PMAP% monitor call is used to map pages from one process to the address space of a second process. Data is not actually transferred; only the contents of the page map of the second (that is, destination) process are changed. The PMAP% monitor call accepts three words of arguments in AC1 through AC3. The first word contains the handle and page number of the first page to be mapped in the source process (that is, the process whose pages are being mapped). The second word contains the handle and page number of the first page to be mapped in the destination process (that is, the process into which the pages are being mapped). The third 5-14 PROCESS STRUCTURE PROCESS STRUCTURE word contains a count of the number of pages to map and bits indicating the access that the destination process will have to the pages mapped. Thus, AC1: source process handle in the left half, and page number in the process in the right half. AC2: destination process handle in the left half, and page number in the process in the right half. AC3: count of number of pages to map and the access bits. The count and access bits that can be specified in AC3 are described in Section 3.5.6.1. Upon successful execution of the PMAP% call, addresses in the destination process actually refer to addresses in the source process. The contents of the destination page previous to the execution of the call have been deleted. The access requested in the PMAP% call is granted if it does not conflict with the current access of the destination page (that is, an AND operation is performed between the specified access and the current access). Control returns to the user's program at the instruction following the PMAP% call. If an error occurs, an illegal instruction trap is generated, which the program can process via the software interrupt system or with an ERJMP or ERCAL instruction. 5.7 STARTING AN INFERIOR PROCESS 5.7 STARTING AN INFERIOR PROCESS A program in an inferior process can be started in one of two ways. As mentioned in Section 5.5, the superior process can specify in the CFORK% call the PC for the inferior process and start its execution. Alternatively, the superior process, after executing the CFORK% call to create an inferior process, can execute the SFORK% (Start Process) monitor call to start it. The SFORK% monitor call accepts two words of arguments in AC1 and AC2. AC1: flags,,process handle Flags: SF%CON(1B0) Used to continue a process that has previously halted. If SF%CON is set, the address in AC2 is ignored, and the process continues from where it was halted. AC2: the PC of the process being started. The PC contains flags in the left half and the process starting address in the right half. This call obtains the section number of the PC from the entry vector of the process. 5-15 PROCESS STRUCTURE PROCESS STRUCTURE There are two alternative ways to start processes: XSFRK% (see _______ _______ _____ _________ Section 8.3.2) or SFRKV% (see the TOPS-20 Monitor Calls Reference ______ Manual). The process handle given in AC1 cannot refer to a superior process, to more than one process (for example, .FHINF), or to a process that has already been started. After execution of the SFORK% call, control returns to the user's program at the instruction following the call. If an error occurs, a software interrupt is generated, which the program can process via the software interrupt system. 5.8 INFERIOR PROCESS TERMINATION 5.8 INFERIOR PROCESS TERMINATION The superior process has one of two ways in which it can be notified when one or more of its inferiors terminate execution: via the software interrupt system or by executing the WFORK% monitor call. An inferior process will terminate normally when it executes a HALTF% monitor call. Alternatively, the process will terminate abnormally when it executes an instruction that generates a software interrupt, such as an illegal instruction, and it has not activated the appropriate channel. By activating channel .ICIFT (channel 19) for inferior process termination and enabling the software interrupt system, the superior process will receive an interrupt when one of its inferiors terminates. (Refer to Section 4.6 for information on activating channel .ICIFT.) The interrupt occurs when any inferior process terminates. Use of the interrupt system allows the superior to do other processing until an interrupt occurs, indicating that an inferior process has terminated. In some cases, however, the superior cannot do additional processing until either a specific process or all of its inferior processes have completed execution. If this is the case, the superior process can execute the WFORK% (Wait Process) monitor call. This call blocks the superior until one or all of its inferiors have terminated. The WFORK% monitor call accepts one argument in AC1, the handle of the desired process. This handle can be .FHINF (-4) to block the superior until all inferiors terminate, but cannot be a handle on a superior process. After execution of the WFORK% monitor call, control returns to the user's program at the instruction following the call, when the specified process or all of the inferior processes terminate. If an error occurs, it generates a software interrupt, which the program can process via the software interrupt system. 5-16 PROCESS STRUCTURE PROCESS STRUCTURE 5.9 INFERIOR PROCESS STATUS 5.9 INFERIOR PROCESS STATUS The superior process can obtain the status of one of its inferiors by executing the RFSTS% (Read Process Status) monitor call. This call returns the status and PC words of the given inferior process. The short form of the RFSTS% monitor call accepts one argument in AC1, the handle of the desired process. This handle cannot refer to a superior process or to more than one process. The long form accepts two argument words: flags,, process handle in AC1 and the address of the status return block in AC2. In the long form, RF%LNG (bit 0) is set in AC1 and bits 1-17 are unused (must be zero). After execution of the short form of the RFSTS% call, control returns to the user's program at the instruction following the call. If the RFSTS% call is successful, AC1 contains the status word of the given process and AC2 contains the PC word. The status word is shown in Table 5-6. Table 5-6: Process Status Word Table 5-6: Process Status Word ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 RF%FRZ The process is suspended (that is, frozen). If this bit is not on, the process is not suspended. 1-17 RF%STS The status of the process. Value Symbol Meaning 0 .RFRUN The process is runnable. 1 .RFIO The process is halted waiting for I/O 2 .RFHLT The process is halted by a HFORK% or HALTF% monitor call or was never started. 3 .RFFPT The process is halted by the occurrence of a software interrupt for which it was not prepared to handle. 5-17 PROCESS STRUCTURE PROCESS STRUCTURE The right half of the status word contains the number of the channel on which the interrupt occurred. 4 .RFWAT The process is halted waiting for another process to terminate. 5 .RFSLP The process is halted for a specified amount of time. 6 .RFTRP The process is dismissed because it was intercepted by its superior. 7 .RFABK The process is dismissed because address break was encountered. 18-35 RF%SIC The channel number on which an interrupt occurred, which the process was not prepared to handle (see process status code .RFFPT above). ______________________________________________________________________ The RFSTS% call returns with -1 (fullword) in AC3 if the specified handle is assigned but refers to a deleted process. The call generates an illegal instruction interrupt if the handle is unassigned. In the long form of the RFSTS% monitor call, RF%LNG is set in AC1 and AC2 contains the address of a status-return block. On the return, AC1 and AC2 are not modified. The status-return block is described in Table 5-7. Table 5-7: RFSTS% Status-Return Block Table 5-7: RFSTS% Status-Return Block ______________________________________________________________________ Word Symbol Meaning ______________________________________________________________________ 0 .RFCNT Count of words returned in this block in the left half, and count of maximum number of words to return in right half (including 5-18 PROCESS STRUCTURE PROCESS STRUCTURE this word). The right half of this word is specified by the user. 1 .RFPSW Process status word. This word has the same format as AC1 on a return from a short call. If a valid, but unassigned, process handle was specified in AC1, then this word contains -1 and no other words are returned. 2 .RFPFL Process PC flags. These are the same flags returned in AC2 on a short call. 3 .RFPPC Process PC. This is the address; no flags are returned in this word. 4 .RFSFL Status flag word. Flags: Bit Symbol Meaning B0 RF%EXO Process is execute-only. ______________________________________________________________________ If an error occurs during execution of the RFSTS% call, a software interrupt is generated which the program can process via the software interrupt system. 5.10 PROCESS COMMUNICATION 5.10 PROCESS COMMUNICATION A superior process can communicate with its inferiors by sharing the same pages of memory. This sharing is accomplished with the CFORK% (bit CR%MAP) or the PMAP% monitor call. When the superior executes either of these calls, both the superior and the inferior share the same pages. Changes made to the shared pages by either process will be seen by the other process. Alternatively, processes can communicate via the software interrupt system. The superior process can cause a software interrupt to be generated in an inferior process by executing the IIC% (Initiate Interrupt on Channel) monitor call. For this type of communication to occur, the inferior's interrupt channels must be activated and its interrupt system enabled. The IIC% monitor call accepts two words of arguments in AC1 and AC2. The handle of the process to receive the interrupt is given in the right half of AC1. AC2 contains a 36-bit word, with each bit representing one of the 36 software channels. If a bit is on in AC2, 5-19 PROCESS STRUCTURE PROCESS STRUCTURE a software interrupt is initiated on the corresponding channel. For example, if bit 5 is on in AC2, an interrupt is initiated on channel 5. Thus, AC1: process handle in the right half AC2: 36-bit word, with bit n on to initiate a software interrupt on channel n The process handle given cannot refer to a superior process or to more than one process. After execution of the IIC% call, control returns to the user's program at the instruction following the call. If an error occurs, it generates a software interrupt which the program can process via the software interrupt system. 5.11 DELETING AN INFERIOR PROCESS 5.11 DELETING AN INFERIOR PROCESS A process is deleted from the job structure when the superior process executes the KFORK% (Kill Process) monitor call. When a process is deleted, its address space, its handle, and any JFNs acquired by the process are released. If the process being deleted has processes inferior to it, the inferiors are also deleted. For example, in the structure: --------------- | Process A | --------------- | | --------------- | Process B | --------------- | | --------------- | Process C | --------------- if process A deletes process B by executing a KFORK% call, process C is also deleted. The KFORK% monitor call accepts one argument in the right half of AC1, the handle of the process to be deleted. This handle cannot refer to a superior process, to more than one process (for example, .FHINF), or 5-20 PROCESS STRUCTURE PROCESS STRUCTURE to the process executing the call (that is, .FHSLF). The RESET% monitor call is used to reinitialize the current process; refer to Section 2.6.1. After execution of the KFORK% call, control returns to the user's program at the instruction following the call. If an error occurs, a software interrupt is generated, which the program can process via the software interrupt system. 5.12 PROCESS EXAMPLES 5.12 PROCESS EXAMPLES Example 1 - This program creates an inferior process to provide timing interrupts. TITLE TIMINT - AN INFERIOR PROCESS PROVIDING TIMING INTERRUPTS SEARCH MONSYM SEARCH MACSYM .REQUIRE SYS:MACREL STDAC. ;DEFINE STANDARD ACS START: RESET% ;RELEASE FILES, ETC. MOVE P,[IOWD PDLSIZ,PDL] ;INITIALIZE STACK MOVX T1,CR%MAP ;MAKE NEW PROCESS SHARE THIS ;PROCESS'S MEMORY CFORK% ;CREATE A NEW PROCESS EJSHLT ;UNEXPECTED FATAL ERROR MOVEM T1,HANDLE ;SAVE PROCESS HANDLE ;HERE TO START THE INFERIOR PROCESS STPROC: SETZB T4,FLAG ;INITIALIZE COUNTER AND FLAG MOVE T1,HANDLE ;GET PROCESS HANDLE MOVEI T2,SLEEP ;GET ADDRESS TO START PROCESS SFORK% ;START THE NEW PROCESS EJSHLT ;UNEXPECTED FATAL ERROR ; MAIN PROCESSING LOOP LOOP: AOS T4 ;INCREMENT COUNTER SKIPN FLAG ;HAS TIME ELAPSED YET? JRST LOOP ;NO, GO DO MORE PROCESSING ; HERE WHEN LOWER PROCESS HAS INTERRUPTED TMSG < Counter has reached > ;OUTPUT FIRST PART OF MESSAGE MOVX T1,.PRIOU ;GET PRIMARY OUTPUT DESIGNATOR MOVE T2,T4 ;GET VALUE OF COUNTER 5-21 PROCESS STRUCTURE PROCESS STRUCTURE MOVEI T3,^D10 ;USE DECIMAL RADIX NOUT% ;OUTPUT CURRENT COUNTER VALUE EJSERR ;PRINT ERROR MESSAGE AND CONTINUE TMSG < > ;MOVE TO A NEW LINE JRST STPROC ;CONTINUE COUNTING ; PROGRAM PERFORMED BY INFERIOR PROCESS TO WAIT FOR ONE-HALF MINUTE SLEEP: MOVX T1,^D30*^D1000 ;ONE-HALF MINUTE IN MILLISECONDS DISMS% ;WAIT FOR SPECIFIED TIME SETOM FLAG ;TELL SUPERIOR TIME HAS ELAPSED HALTF% ;FINISHED ; CONSTANTS AND STORAGE PDLSIZ==50 ;SIZE OF THE STACK PDL: BLOCK PDLSIZ ;STACK HANDLE: BLOCK 1 ;INFERIOR PROCESS HANDLE FLAG: BLOCK 1 ;INTERRUPT FLAG END START Example 2 - This program illustrates how an inferior process may be used as a source of timer interrupts. The main program increments a counter. It has an inferior process running for the sole purpose of timing 10 second intervals. Each time the inferior process has timed 10 seconds, it stops and interrupts the main program. The main program then reports how many more times it has incremented the counter since the last 10 second interrupt. TITLE TRMINT - FORK TERMINATION INTERRUPTS SEARCH MONSYM SEARCH MACSYM .REQUIRE SYS:MACREL STDAC. ;DEFINE STANDARD ACS START: RESET% ;RELEASE FILES, ETC. MOVE P,[IOWD PDLSIZ,PDL] ;INITIALIZE STACK ; SET UP THE INTERRUPT SYSTEM MOVX T1,.FHSLF ;GET PROCESS HANDLE FOR THIS FORK MOVE T2,[LEVTAB,,CHNTAB] ;GET TABLE ADDRESSES SIR% ;SET INTERRUPT TABLE ADDRESSES EJSHLT ;UNEXPECTED FATAL ERROR MOVX T2,1B<.ICIFT> ;GET PROCESS TERMINATION CHANNEL BIT AIC% ;ACTIVATE PROCESS TERMINATION CHANNEL EJSHLT ;UNEXPECTED FATAL ERROR EIR% ;ENABLE INTERRUPT SYSTEM EJSHLT ;UNEXPECTED FATAL ERROR 5-22 PROCESS STRUCTURE PROCESS STRUCTURE ; CREATE AND START THE INFERIOR PROCESS MOVX T1,CR%MAP+CR%ST+SLEEP CFORK% ;CREATE AND START TIMER AT SLEEP EJSHLT ;UNEXPECTED FATAL ERROR MOVEM T1,HANDLE ;SAVE PROCESS HANDLE ;INITIALIZE THE COUNTER STPROC: SETZB T4,OLDT4 ;CLEAR COUNTER ;MAIN LOOP OF THE PROGRAM WHICH JUST KEEPS COUNTING. (REAL ;APPLICATION WOULD PRESUMABLY HAVE A MORE USEFUL MAIN PROGRAM.) LOOP: AOJA T4,LOOP ;JUST KEEP INCREMENTING ; HERE WHEN LOWER PROCESS HAS INTERRUPTED PROINT: MOVEM P,IACS+P ;SAVE STACK POINTER MOVEI P,IACS ;MAKE POINTER FOR REST OF ACS BLT P,IACS+CX ;SAVE REST OF ACS MOVE P,IACS+P ;RESTORE P TMSG MOVX T1,.PRIOU ;GET PRIMARY OUTPUT DESIGNATOR EXCH T4,OLDT4 ;SAVE NEW COUNTER VALUE SUB T4,OLDT4 ;FIND NUMBER OF COUNTS SINCE LAST TIME MOVM T2,T4 ;MAKE IT POSITIVE MOVEI T3,^D10 ;USE DECIMAL RADIX NOUT% ;OUTPUT CURRENT COUNTER VALUE EJSERR ;PRINT ERROR MESSAGE AND CONTINUE TMSG < > ;MOVE TO A NEW LINE MOVE T1,HANDLE ;GET PROCESS HANDLE MOVEI T2,SLEEP ;GET ADDRESS TO START PROCESS SFORK% ;START THE NEW PROCESS EJSHLT ;UNEXPECTED FATAL ERROR MOVSI P,IACS ;GET POINTER TO SAVED ACS BLT P,P ;RESTORE SAVED ACS DEBRK% ;DISMISS INTERRUPT ;THE FOLLOWING IS EXECUTED AS A LOWER PROCESS TO DO THE ;TIMING. IT SLEEPS FOR 10 SECONDS AND THEN STOPS. SLEEP: MOVX T1,^D10*^D1000 ;10 SECONDS IN MILLISECONDS DISMS% ;SLEEP HALTF% ;STOP AND INTERRUPT THE MAIN PROGRAM ; CONSTANTS AND STORAGE PDLSIZ==50 ;SIZE OF THE STACK PDL: BLOCK PDLSIZ ;STACK CHNTAB: REPEAT ^D19, ;CHANNELS 0-18 ARE NOT USED 1,,PROINT ;LEVEL 1 PROCESS TERMINATION CHANNEL REPEAT ^D15, ;REMAINING CHANNELS ARE NOT USED 5-23 PROCESS STRUCTURE PROCESS STRUCTURE LEVTAB: RETPC1 ;RETURN PC STORED AT RETPC1 FOR ;LEVEL 1 0 ;LEVEL 2 NOT USED 0 ;LEVEL 3 NOT USED HANDLE: BLOCK 1 ;INFERIOR PROCESS HANDLE RETPC1: BLOCK 1 ;RETURN PC STORED HERE ON INTERRUPTS OLDT4: BLOCK 1 ;HOLDS TIMER VALUE AT LAST INTERRUPT IACS: BLOCK 20 ;STORAGE FOR ACS DURING INTERRUPTS END START Example 3 - This program creates an inferior process which waits until a line has been typed on the terminal. TITLE FRKDOC - AN INFERIOR PROCESS WAITS UNTIL A LINE IS TYPED SEARCH MONSYM SEARCH MACSYM .REQUIRE SYS:MACREL STDAC. ;DEFINE STANDARD ACS START: RESET% ;RELEASE FILES, ETC. MOVE P,[IOWD PDLSIZ,PDL] ;INITIALIZE STACK MOVX T1,CR%MAP ;MAKE NEW PROCESS SHARE THIS ;PROCESS'S MEMORY CFORK% ;CREATE A NEW PROCESS EJSHLT ;UNEXPECTED FATAL ERROR SETZB T4,FLAG ;INITIALIZE COUNTER AND FLAG MOVEI T2,GETCOM ;GET ADDRESS TO START PROCESS SFORK% ;START THE NEW PROCESS EJSHLT ;UNEXPECTED FATAL ERROR ; MAIN PROCESSING LOOP LOOP: AOS T4 ;INCREMENT COUNTER SKIPN FLAG ;HAS TIME ELAPSED YET? JRST LOOP ;NO, GO DO MORE PROCESSING ; HERE WHEN INFERIOR PROCESS HAS INPUT A LINE OF TEXT TMSG < Counter has reached > ;OUTPUT FIRST PART OF MESSAGE MOVX T1,.PRIOU ;GET PRIMARY OUTPUT DESIGNATOR MOVE T2,T4 ;GET VALUE OF COUNTER MOVEI T3,^D10 ;USE DECIMAL RADIX NOUT% ;OUTPUT CURRENT COUNTER VALUE EJSERR ;PRINT ERROR MESSAGE AND CONTINUE TMSG < Echo Check: > ;OUTPUT FIRST PART OF MESSAGE HRROI T1,BUFFER ;GET POINTER TO BUFFER PSOUT% ;OUTPUT TEXT JUST ENTERED 5-24 PROCESS STRUCTURE PROCESS STRUCTURE HALTF% ;STOP JRST START ;IN CASE PROGRAM CONTINUED ; PROGRAM PERFORMED BY INFERIOR PROCESS TO INPUT A LINE OF TEXT GETCOM: HRROI T1,BUFFER ;GET POINTER TO TEXT BUFFER MOVEI T2,BUFSIZ*5 ;GET COUNT OF MAX # OF CHARACTERS SETZM T3 ;NO RETYPE BUFFER RDTTY% ;READ A LINE FROM THE TERMINAL EJSERR ;UNEXPECTED ERROR SETOM FLAG ;TELL SUPERIOR TIME HAS ELAPSED HALTF% ;FINISHED ; CONSTANTS AND STORAGE PDLSIZ==50 ;SIZE OF THE STACK PDL: BLOCK PDLSIZ ;STACK BUFSIZ==50 ;BUFFER SIZE BUFFER: BLOCK BUFSIZ FLAG: BLOCK 1 ;INTERRUPT FLAG END START 5-25 6-1 CHAPTER 6 CHAPTER 6 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY 6.1 OVERVIEW 6.1 OVERVIEW Many times users are placed in situations where they must share files with other users. Each user wants to be guaranteed that while reading a file, other users are reading the same data and while writing a file, no users are also writing, or even reading, the same portion of the file. Consider a data file used by members of an insurance company. When many agents are reading individual accounts from the data file, they can all access the file simultaneously because no one is changing any portion of the data. However, when an agent desires to modify or replace an individual account, that portion of the file should be accessed exclusively by that agent. None of the other agents wants to access accounts that are being changed until after the changes are made. By using the ENQ/DEQ facility, cooperating users can insure that resources are shared correctly and that one user's modifications do not interfere with another user's. Examples of resources that can be controlled by this facility are devices, files, operations on files (for example, READ, WRITE), records, and memory pages. This facility can be used for dynamic resource allocation, computer networks, and internal monitor queueing. However, control of simultaneous updating of files by multiple users is its most common application. The ENQ/DEQ facility insures data integrity among processes only when the processes cooperate in their use of both the facility and the physical resource. Use of the facility does not prevent non-cooperating processes from accessing a resource without first enqueueing it. Nor does the facility provide protection from processes using it in an incorrect manner. A resource is defined by the processes using it and not by the system. Because there is competition among processes for use of a resource, each resource is associated with a queue. This queue is the ordering of the requests for the resource. When a request for the resource is 6-1 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY granted, a lock occurs between the process that made the request and the resource. For the duration of the lock, that process is the owner of the resource. Other processes requesting access to the resource are placed in the queue until the owner relinquishes the lock. However, there can be more than one owner of a resource at a time; this is called shared ownership (refer to Section 6.2). Processes obtain access to a specific resource by placing a request in the queue for the resource. This request is generated by the ENQ% monitor call. When finished with the resource, the process then issues the DEQ% monitor call. This call releases the lock by removing the request from the queue and makes the resource available to the next waiting process. This cycle continues until all requests in the queue have been satisfied. 6.2 RESOURCE OWNERSHIP 6.2 RESOURCE OWNERSHIP Ownership for a resource can be requested as either exclusive or shared. Exclusive ownership occurs when a process requests sole use of the resource. When a process is granted exclusive ownership, no other process will be allowed to use the resource until the owner relinquishes it. This type of ownership should be requested if the process plans on modifying the resource (for example, the process is updating a record in a data file). Shared ownership occurs when a process requests a resource, specifying that it will share the use of the resource with other processes. When a process is given shared ownership, other processes also specifying shared ownership are allowed to simultaneously use the resource. Access to a resource should be shared as long as any one process is not modifying the resource. Two conditions determine when a lock to a resource is given to a process: 1. The position of the process's request in the queue for the resource. 2. The type of ownership specified by the process's request. Because each resource has only one queue associated with it, requests for both exclusive and shared ownership of the resource are placed in the same queue. Requests are placed in the queue in the order in which the ENQ facility receives them, and the first request in the queue will be the first one serviced (except in the case of single requests for multiple resources; refer to Section 6.4.1). In other words, the ENQ facility processes requests on a first in, first out basis. If this first request is for shared ownership, that request will be serviced along with all following shared ownership requests up to but not including the first exclusive ownership request. If the first request is for exclusive ownership, no other processes are allowed use of the resource until the first process has released the lock. 6-2 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY Consider the following queue for a particular resource. !=======================================================! ! request 1 (shared) ! !-------------------------------------------------------! ! request 2 (shared) ! !-------------------------------------------------------! ! request 3 (exclusive) ! !-------------------------------------------------------! ! request 4 (shared) ! !-------------------------------------------------------! ! request 5 (shared) ! !=======================================================! Request 1 will be serviced first because it is the first request in the queue. However, since this request is for shared ownership, request 2 can also be serviced. Request 3 cannot be serviced until the processes with request 1 and request 2 release the lock on the resource. Eventually the lock is released by the two processes, and the first two requests are removed from the queue. The queue now has the following entries: !=======================================================! ! ! !-------------------------------------------------------! ! ! !-------------------------------------------------------! ! request 3 (exclusive) ! !-------------------------------------------------------! ! request 4 (shared) ! !-------------------------------------------------------! ! request 4 (shared) ! !=======================================================! Request 3 is now first in the queue and is given a lock on the resource. Because the request is for exclusive ownership, no other requests will be serviced. Once the process associated with request 3 releases the lock, both request 4 and request 5 can be serviced because they both are for shared ownership. 6.3 PREPARING FOR THE ENQ/DEQ FACILITY 6.3 PREPARING FOR THE ENQ/DEQ FACILITY Before using the ENQ/DEQ facility, the user must obtain an ENQ quota from the system administrator and must obtain the name of the resource 6-3 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY desired, the type of protection required, and the level number associated with the resource. The ENQ quota indicates the total number of requests that can be outstanding for the user at any given time. Any request that would cause the quota to be exceeded results in an error. The user cannot use the ENQ facility if the quota is set to zero. The resource name has a meaning agreed upon by all users of the specific resource and serves as an identifier of the resource. The system makes no association between the resource name and the physical resource itself; it is the responsibility of the user's process to make that association. The system merely uses the resource name to process requests and handles different resource names as requests for different resources. The resource name has two parts. In most cases, the first part is the JFN of the file being accessed. Before using the ENQ facility, the user must initialize the file using the appropriate monitor calls (refer to Section 3.1). The second part of the name is a modifier, which is either a pointer to a string or a 33-bit user code. The string uniquely identifies the resource to all users. The pointer can either be a standard byte pointer or be in the form -1,,ADR where ADR is the location of the left-justified ASCIZ text string. The 33-bit user code similarly identifies the resource by representing an item such as a record number or block number. The ENQ facility considers these modifiers as logical strings and does not check for cooperation among the users. Thus, users must be careful when assigning these modifiers to prevent the occurrence of two different modifiers referring to the same resource. The type of protection desired for the resource is indicated by the first part of the resource name. This part of the name can be one of four values. When the user specifies the JFN of the desired file, the file is subject to the standard access protection of the system. This is the most typical case. When the user specifies -1 instead of a JFN, it means that resources defined within a job are to be accessed only by processes of that job. Other jobs requesting resources of the same name are queued to a different resource. When the user specifies -2 instead of a JFN, it means that the resource can be accessed by any job on the system. A process must have bit SC%ENQ enabled in its capability word to specify this type of protection. If the user specifies -3 instead of a JFN, it means the same type of protection as that given when -2 is specified. However, this requires that the process have WHEEL or OPERATOR capability enabled. Quotas are not checked when -3 is given instead of a JFN. In addition to specifying the resource name and type of protection, the user also assigns a level number to each resource. The use of 6-4 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY level numbers prevents the occurrence of a deadly embrace situation: the situation where two or more processes are waiting for each to complete, but none of the processes can obtain a lock on the resource it needs for completion. This situation is represented by Figure 6-1. --------------------- | Process A is | | Waiting for a | | Resource Process |--------------------------\ | B Has. | | --------------------- | ^ v | --------------------- | | Process B is | | | Waiting for a | | | Resource Process | | | C Has. | | --------------------- | | | --------------------- | | | Process C is | | | | Waiting for a | | \---------| Resource Process |<-------/ | A Has. | --------------------- Figure 6-1: Deadly Embrace Situation Figure 6-1: Deadly Embrace Situation Each process is in the queue waiting for the resource it needs, but no request is being serviced because the desired resources are unavailable. The use of level numbers forces cooperating processes to order their use of resources by requiring that processes request resources in an ascending numerical order and that all processes assign the same level number to a specific resource. This means that the order in which resources are requested is the same for all processes and therefore, requests for the first resource will always precede requests for the second one. If both of the above requirements are not met, the process requesting the resource receives an error, unless the appropriate flag bit is set (refer to Section 6.4.1.2), and the request is not placed in the queue. Thus, instead of waiting for a resource it will never get, the process is informed immediately that the resource is not available. 6-5 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY 6.4 USING THE ENQ/DEQ FACILITY 6.4 USING THE ENQ/DEQ FACILITY There are three monitor calls available for the ENQ/DEQ facility: ENQ%, to request use of a resource; DEQ%, to release a lock on a resource; and ENQC%, to obtain information about the queues and to specify access to these queues. 6.4.1 Requesting Use of a Resource 6.4.1 Requesting Use of a Resource The user issues the ENQ% monitor call to place a request in the queue associated with the desired resource. This call is used to specify the resource name, level number, and type of protection required. A single ENQ% monitor call can be used to request any number of resources. In fact, when desiring multiple resources, the user should request all of them in one call. This method of requesting resources guarantees that the user gets either none or all of the resources requested because the ENQ/DEQ facility never allocates only some of the resources specified in one call. Because all resources in a single call must be available at the same time, the first user requesting a resource (that is, the first user in the queue for the resource) may not be the first user obtaining it if other resources in the request are currently not available. A single call for multiple resources is not functionally the same as a series of single calls of those resources. In a single call, the entire request is rejected if an error is returned for one of the resources specified. In a series of single calls, each request that did not return an error will be queued. The ENQ% monitor call accepts two words of arguments in AC1 and AC2. The first word contains the code of the desired function, and the second contains the address of the argument block. Thus, AC1: function code AC2: address of argument block 6.4.1.1 ENQ% Functions 6.4.1.1 ENQ% Functions - The functions that can be requested in the ENQ% call are described in Table 6-1. 6-6 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY Table 6-1: ENQ% Functions Table 6-1: ENQ% Functions ______________________________________________________________________ Code Symbol Meaning ______________________________________________________________________ 0 .ENQBL Queue the requests and block the process until all requested locks are acquired. This function returns an error code only if the ENQ% call is not correctly specified. 1 .ENQAA Queue the requests and acquire the locks only if all requested resources are immediately available. If the resources are available, all will be allocated to the process. If any one of the resources is not available, no requests are queued, no locks are acquired, and an error code is returned in AC1. 2 .ENQSI Queue the requests for all specified resources. If all resources are available, this function is identical to the .ENQBL function. If all resources are not immediately available, the requests are queued, and a software interrupt is generated when all requested resources have been given to the process. 3 .ENQMA Change the ownership access of a previously-queued request (refer to bit EN%SHR below). The access for each lock in this request is compared with the access for each lock in the request already queued. No action is taken if the two accesses are the same. If the access in this request is shared and the access in the previous request is exclusive, the ownership access is changed to shared access. Otherwise, an error is returned if: 1. There are processes which are locking, or waiting on the same lock, and the process tries to change the ownership access from shared to exclusive. If this is 6-7 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY the case, the process should issue a DEQ% monitor call for the shared request and then issue another ENQ% monitor call for exclusive ownership. 2. Any one of the specified locks does not have a pending request. 3. Any one of the specified locks is a pooled resource (refer to Section 6.4.1.2). Each lock specified is checked, and the access is changed for all locks that were correctly given. On receiving an error, the process should issue the ENQC% monitor call to determine the current state of each lock (refer to Section 6.4.3). 4 .ENECL Set cluster-wide ENQ/DEQ functionality for all ENQ/DEQ/ENQC JSYSes performed by this process. The contents of AC2 are ignored as this function does not require an argument block. ______________________________________________________________________ 6.4.1.2 ENQ% Argument Block 6.4.1.2 ENQ% Argument Block - The format of the argument block is described in Table 6-2. Table 6-2: ENQ% Argument Block Table 6-2: ENQ% Argument Block ______________________________________________________________________ Word Symbol Meaning ______________________________________________________________________ 0 .ENQLN Number of locks being requested in the left half, and length of argument block (including this word) in the right half. 1 .ENQID Number of software interrupt channel in the left half, and request ID in the right half. 2 .ENQLV Flags and level number in the left half, and JFN, -1, -2 or -3 (refer to Section 6.3) in the right half. 6-8 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY 3 .ENQUC Pointer to string or 5B2+33-bit user code (refer to Section 6.3). 4 .ENQRS Number of resources in the pool in the left half, and number of resources requested in the right half. 5 .ENQMS Address of a resource mask block. ______________________________________________________________________ Words .ENQLV, .ENQUC, .ENQRS, and .ENQMS (words 2 through 5) are repeated for each lock being requested. These four words are called the lock specification. ________ __________ Software Interrupts The software interrupt system is used in conjunction with the .ENQSI function (refer to Section 6.4.1.1). If all locks are not available when the user requests them, the .ENQSI function causes a software interrupt to be generated when the locks become available. The user specifies the software channel on which to receive the interrupt by placing the channel number in the left half of word .ENQID in the argument block. When the user is waiting for more than one lock to become available, he will receive an interrupt when the last lock is available. If he desires to be informed as each lock becomes available, he can assign the locks to separate channels by issuing multiple ENQ% calls. The availability of each lock will then be indicated by the occurrence of an interrupt on each channel. When the user requests the .ENQSI function, he must initialize the interrupt system first or else an interrupt will not be generated when the locks become available (refer to Chapter 4). _______ __ Request ID The 18-bit request ID is currently not used by the system, but is stored for use by the process. Thus, the process can supply an ID to use as identification for the request. This ID is useful on the .DEQID function of the DEQ% monitor call (refer to Section 6.4.2.1). _____ ___ _____ _______ Flags and Level Numbers Table 6-3 describes the flags that can be used in the left half of the first word of each lock specification (.ENQLV). 6-9 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY Table 6-3: Lock Specification Flags Table 6-3: Lock Specification Flags ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 EN%SHR Ownership for this resource is to be shared. If this bit is not on, ownership for this resource is to be exclusive. 1 EN%BLN Ignore the level number associated with this resource. If this bit is set, sequencing errors in level numbers are not considered fatal, and execution of the call continues. On successful completion of the call, AC1 contains either an error code if a sequencing error occurred, or zero if a sequencing error did not occur. WARNING A deadly embrace situation may occur when level numbers are not used. Use of these numbers guarantees that such a situation cannot arise; for this reason bit EN%BLN should not be set. 2 EN%NST Allow ownership of this lock to be nested. 3 EN%LTL Allow a long-term lock on this resource. 4-8 Reserved for Digital. 9-17 EN%LVL Level number associated with this resource. This number is specified by the user and must be agreed upon by all users of the resource. In order to eliminate a deadly embrace situation, users must request resources in numerically increasing order. ______________________________________________________________________ 6-10 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY The request is not queued, and an error is given, if EN%BLN is not set and 1. The user requests a resource with a level number less than or equal to the highest numbered resource he has requested so far. 2. The level number of this request does not match the level number supplied in previous requests for this resource. ______ _________ Pooled Resources Word .ENQRS of each lock specification is used to allocate multiple copies from a pool of identical resources. Bit EN%SHR, indicating shared ownership, is meaningless for pooled resources because each resource in the pool can be owned by only one process at a time. A process can own one or more resources in the pool; however, it cannot own more than there are in the pool or more than there are unowned in the pool. The left half of word .ENQRS contains the total number of resources existing in the pool. This number is previously agreed upon by all users of the pooled resource. The first user who requests the resource sets this number, and all subsequent requests must specify the same number or an error is given. The right half of word .ENQRS contains the number of resources being requested by this process. This number must be greater than zero if a pool of resources exists and cannot be greater than the number in the left half. This means that if a pool of resources exists, the user must request at least one resource, but cannot request more than are in the pool. Once the number of pooled resources is determined, the resources are allocated until the pool is depleted or until a request specifies more resources than are currently available. In the latter case, the user making the request is not given any resources until his entire request can be satisfied. Subsequent requests from other users are not granted until this request is satisfied even though there may be enough resources to satisfy these subsequent requests. As users release their resources, the resources are returned to the pool. When all resources have been returned, they cease to exist, and the next request completely redefines the number of resources in the new pool. The system assumes that the resource is in a pool if the left half of word .ENQRS of the lock specification is nonzero. Thus the user should set the left half to zero if only one resource of a specific type exists. If this is the case, then the right half of this word is a number defining the group of users who can simultaneously share the resource. This means that when the resource is allocated to a user for shared ownership, only other users in the same group will be allowed access to the resource. The use of sharer groups restricts 6-11 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY access to a resource to a set of processes smaller than the set for shared ownership (which is sharer group 0) but larger than the set for exclusive ownership. (Refer to Section 6.5 for more information on sharer groups). 6.4.2 Releasing a Resource 6.4.2 Releasing a Resource The user issues the DEQ% monitor call to remove a request from the queue associated with a resource. The request is removed whether or not the user actually owns a lock on the resource or is only waiting in the queue for the resource. The DEQ% monitor call can be used to remove any number of requests from the queues. If one of the requests cannot be removed, the dequeueing procedure continues until all lock specifications have been processed. An error code is then returned for the last request found that could not be dequeued. The process can then execute the ENQC% call (refer to Section 6.4.3) to determine the status of each lock. Thus, unlike the operation of the ENQ% call, the DEQ% call will dequeue as many resources as it can, even if an error is returned for one of the lock specifications in the argument block. However, when a user attempts to dequeue more pooled resources than he originally allocated, an error code is returned and none of the resources are dequeued. The DEQ% monitor call accepts two words of arguments in AC1 and AC2. The first word contains the code for the desired function, and the second word contains the address of the argument block. Thus, AC1: function code AC2: address of argument block 6-12 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY 6.4.2.1 DEQ% Functions 6.4.2.1 DEQ% Functions - The DEQ% functions are described in Table 6-4. Table 6-4: DEQ% Functions Table 6-4: DEQ% Functions ______________________________________________________________________ Code Symbol Meaning ______________________________________________________________________ 0 .DEQDR Remove the specified requests from the queues. This function is the only one that requires an argument block. 1 .DEQDA Remove all requests for this process from the queues. This action is taken on a RESET monitor call. An error code is returned if this process has not requested any resources (that is, if this process has not issued an ENQ%). 2 .DEQID Remove all requests that correspond to the specified request identifier. When this function is specified, the user must place the 18-bit request ID in AC2 on the DEQ% call. This function allows the user to release a class of locks in one call without itemizing each lock in an argument block. The function should be used when dequeueing in one call the same locks that were enqueued in one call. For example, with this function the user can specify the ID to be the same as the JFN used in the ENQ% call and thus remove all locks to that file at once. ______________________________________________________________________ 6-13 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY 6.4.2.2 DEQ% Argument Block 6.4.2.2 DEQ% Argument Block - The format of the argument block for function .DEQDR is described in Table 6-5. Table 6-5: DEQ% Argument Block Table 6-5: DEQ% Argument Block ______________________________________________________________________ Word Symbol Meaning ______________________________________________________________________ 0 .ENQLN Number of locks being requested in the left half, and length of argument block (including this word) in the right half. 1 .ENQID Number of software interrupt channel in the left half, and request ID in the right half. 2 .ENQLV Flags and level number in the left half, and JFN, -1, -2 or -3 (refer to Section 6.3) in the right half. 3 .ENQUC Pointer to string or 5B2+33-bit user code (refer to Section 6.3). 4 .ENQRS Number of resources in the pool in the left half, and number of resources requested in the right half. 5 .ENQMS Address of a resource mask block. ______________________________________________________________________ Words .ENQLV, .ENQUC, .ENQRS, and .ENQMS (words 2 through 5) are repeated for each request being dequeued. These four words are called the lock specification. 6.4.3 Obtaining Information About Resources 6.4.3 Obtaining Information About Resources The user issues the ENQC% monitor call to obtain information about the current status of the given resources. This call can also be used by privileged users to perform various utility functions on the queue structure. The format of the ENQC% call is different for these two _______ _______ _____ _________ ______ uses. (Refer to the TOPS-20 Monitor Calls Reference Manual for the explanation of the privileged use of the ENQC% call.) The ENQC% monitor call accepts three words of arguments in AC1 through AC3: 6-14 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY AC1: function code (.ENQCS) AC2: address of argument block AC3: address of area to receive status information The format of the argument block is identical to the format of the ENQ% and DEQ% argument blocks. The area in which the status is to be returned should be three times as long as the number of locks specified in the argument block. On successful execution of the ENQC% call, the current status of each lock specified is returned as a three-word entry. This three-word entry has the following format. !=======================================================! ! Flag bits indicating status of lock ! !-------------------------------------------------------! ! 36-bit time stamp ! !-------------------------------------------------------! ! Reserved ! Request ID ! !=======================================================! Table 6-6 describes the flag bits that can be used in a ENQC% call. 6-15 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY Table 6-6: ENQC% Flag Bits Table 6-6: ENQC% Flag Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 EN%QCE An error has occurred in the corresponding lock request. Bits 18-35 contain the appropriate error code. 1 EN%QCO The process issuing the ENQC% call is the owner of this lock. 2 EN%QCQ The process issuing the ENQC% call is in the queue waiting for this resource. This bit will be on when EN%QCO is on because a request remains in the queue until a DEQ% call is given. 3 EN%QCX The lock has been allocated for exclusive ownership. When this bit is off, there is no way of determining the number of sharers of the resource. 4 EN%QCB The process issuing the ENQC% call is in the queue waiting for exclusive ownership to the resource. This bit will be off if EN%QCQ is off. 5 EN%QCC This is a cluster-wide lock/request. This bit exists in both a lock-block and a q-block. 6 EN%QCN No future vote is required for this lock. This bit exists in a lock-block. 7 EN%QCS This lock requires a scheduling pass. 8 Reserved for Digital 9-17 EN%LVL The level number of the resource. 18-35 EN%JOB The number of the job that owns the lock. This value may be a job number on another system within the cluster. For locks with shared ownership, this value will be the job number of one of the owners. However, this value will be the current job's number if the current job is one of the owners. If this lock is not owned, the value is -1. If EN%QCE is on, this field contains the appropriate error code. ______________________________________________________________________ 6-16 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY The 36-bit time stamp indicates the last time a process locked the resource. The time is in the universal date-time standard. If no one currently has a lock on the resource, this word is zero. The request ID returned in the right half of the third word is either the request ID of the current process if that process is in the queue or the request ID of the owner of the lock. 6.5 SHARER GROUPS 6.5 SHARER GROUPS Processes can specify the sharing of resources by using sharer group numbers (refer to Section 6.4.1.2). The use of sharer groups restricts the ownership for a resource to a set of processes smaller than the set for shared ownership but larger than the set for exclusive ownership. Sharer group number 0 is used to indicate the group of all cooperating processes of the resource. This group number is assumed when no group is specified in the ENQ% call. To restrict use of the resource, a group number other than 0 must be explicitly specified in the call. Consider the following example. The resource is the WRITE operation on a file. There are four types of uses of this resource as shown in Figure 6-2. 6-17 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY --------------------------------------------------- |\ | | | | \ Process'| | | | \ Own Use | | | | \ of the | | | | \Resource| | Not Allowed | | \ | Write | to Write | | \ | | | | \ | | | | Other \ | | | | Process'\ | | | | Use of \ | | | | Resource \ | | | | \| | | |-------------|--------------|----------------| | | 1 | 2 | | Write | | | | | Shared, | No Need to Use | | | Group 0 | ENQ/DEQ | |-------------|--------------|----------------| | | 3 | 4 | | Not Allowed | | | | to Write | Exclusive | Shared, | | | | Group 1 | ----------------------------------------------- Figure 6-2: Use of Sharer Groups Figure 6-2: Use of Sharer Groups In block 1 of the figure, the process owning the lock wishes to allow all cooperating processes to also lock the resource (that is, to perform the WRITE operation). Therefore, in the ENQ% call, the process specifies the resource can be locked by all cooperating processes. In block 2 of the figure, the process does not plan on locking the resource and does not care if other processes lock it. Thus, there is no need for the process to use the ENQ/DEQ facility. In block 3 of the figure, the process desires to lock the resource exclusively and does not want other processes to lock it. Thus, the process obtains exclusive ownership for the resource. In block 4 of the figure, the process does not want to lock the resource immediately but also does not want other processes to lock it because it soon plans to request a lock on the resource. If the process were the only one requesting this type of use, exclusive ownership would be sufficient, because the resource would be unavailable to others as long as the process owned the lock. However, if other processes desire this same type of use, exclusive ownership is not sufficient, because once one process releases the lock, another process with a different type of use could obtain its own lock. Thus, in this example, sharer group 1 is defined to include all processes with the same type of use (that is, all processes who do not want to lock the resource immediately but also do not want other processes to lock it). 6-18 ENQUEUE/DEQUEUE FACILITY ENQUEUE/DEQUEUE FACILITY This elimates the problem of another user obtaining the resource for a different type of use. Sharer group 0 should be sufficient for most uses of the ENQ/DEQ facility. Additional groups should only be needed in those situations where a subset of the cooperating processes must have a specific use of a resource, as in the above example. 6.6 AVOIDING DEADLY EMBRACES 6.6 AVOIDING DEADLY EMBRACES Processes can interact in many undesirable ways if improper communication occurs among the processes or if resources are incorrectly shared. An example of one undesirable situation is the occurrence of a deadly embrace: when two processes are waiting for each other to complete but neither one can gain access to the resource it needs for completion. This situation can be avoided when processes consider the following guidelines. 1. Processes should request resources at the time they need them. If possible, processes should request resources one at a time and release each resource before requesting the next one. 2. Processes should request shared ownership whenever possible. However, the process should not request shared ownership if it plans on modifying the resource. 3. When a process needs more than one resource, it should request these resources in one ENQ% call instead of multiple calls for each resource. The process should also release the entire set of resources at once with a single DEQ% call. 4. When the use of one resource depends on the use of a second one, the process should define the two resources as one in the ENQ% and DEQ% calls. However, there is no protection of the resources if they are also requested separately. 5. Occasionally processes use a set of resources and require a lock on the second resource while retaining the lock on the first. In this case, the order in which the locks are obtained should be the same for all users of the set of resources. The same ordering of locks is accomplished by the processes assigning level numbers to each resource. The requirements that processes request resources in ascending numerical order and that all processes use the same level number for a specific resource ensure that a deadly embrace situation will not occur. 6-19 7-1 CHAPTER 7 CHAPTER 7 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY 7.1 OVERVIEW 7.1 OVERVIEW The Inter-Process Communication Facility (IPCF) allows communication among jobs and system processes. This communication occurs when processes send and receive information in the form of packets. Each sender and receiver has a Process ID (PID) assigned to it for identification purposes. When the sender sends a packet of information to another process, the packet is placed into the receiver's input queue. The packet remains in the queue until the receiver checks the queue and retrieves the packet. Instead of periodically checking its input queue, the receiver can enable the software interrupt system (refer to Chapter 4) to generate an interrupt when a packet is placed in its input queue. The INFO process is the information center for the Inter-Process Communication Facility. This process performs system functions related to PIDs and names, and any process can request these functions by sending INFO a packet. 7.2 QUOTAS 7.2 QUOTAS Before using IPCF, the user must acquire the ability to use IPCF privileges from the system administrator: a send packet quota and a receive packet quota. These quotas designate, on a per process basis, the number of sends and receives that can be outstanding at any one time. For example, if the process has a send quota of two and it has sent two packets, it cannot send any more until at least one packet has been retrieved by its receiver. A send packet quota of two and a receive packet quota of five are assumed as the standard quotas. If these quotas are zero, the process cannot use IPCF. 7-1 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY 7.3 PACKETS 7.3 PACKETS Information is transferred in the form of packets. Each packet is divided into two portions: a packet descriptor block of four to six words and a packet data block the length of the message. The format of the packet is shown in Figure 7-1. Packet Descriptor Block !=======================================================! .IPCFL ! flags ! !-------------------------------------------------------! .IPCFS ! PID of sender ! !-------------------------------------------------------! .IPCFR ! PID of receiver ! !-------------------------------------------------------! .IPCFP ! length of message ! address of message ! ! n ! ADR ! !-------------------------------------------------------! .IPCFD ! sender's connected ! sender's logged in ! ! directory ! directory ! !-------------------------------------------------------! .IPCFC ! enabled capabilities of sender ! !-------------------------------------------------------! .IPCSD ! connected directory of sender ! !-------------------------------------------------------! .IPCAS ! account string of sender ! !-------------------------------------------------------! .IPCLL ! logical location of sender ! !=======================================================! Packet Data Block !=======================================================! ADR ! message word 1 ! !=======================================================! . . . !=======================================================! ! message word n ! !=======================================================! Figure 7-1: IPCF Packet Figure 7-1: IPCF Packet 7-2 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY 7.3.1 Flags 7.3.1 Flags There are two types of flags that can be set in word .IPCFL of the packet descriptor block. The flags in the left half of the word are instructions to IPCF for packet communication, and the flags in the right half are descriptions of the data message. The flags in the right half are returned as part of the associated variable (refer to Section 7.4.2). The packet descriptor block flags are described in Table 7-1. Table 7-1: Packet Descriptor Block Flags Table 7-1: Packet Descriptor Block Flags ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 IP%CFB Do not block the process if there are no messages in the queue. If this bit is on, the process receives an error if there are no messages. 1 IP%CFS Use the PID obtained from the address in word .IPCFS of the packet descriptor block as the sender's PID. 2 IP%CFR Use the PID obtained from the address in word .IPCFR of the packet descriptor block as the receiver's PID. 3 IP%CFO Allow the process one send above the send quota. (The standard send quota is two.) 4 IP%TTL Truncate the message if it is longer than the area reserved for it in the packet data block. If this bit is not on, the process receives an error if the message is too long. 5 IP%CPD Create a PID to use as the sender's PID. The PID created is returned in word .IPCFS of the packet descriptor block. 6 IP%JWP Make the PID created be permanent until the job logs out (if both bits IP%CPD and IP%JWP are on). Make the PID created be temporary until the process executes a RESET% monitor call (if bit IP%CPD is on and bit IP%JWP is not on). If bit IP%CPD is not on, bit IP%JWP is ignored. 7 IP%NOA Do not allow other processes to use the PID created when bit IP%CPD is on. If bit IP%CPD is not on, bit IP%NOA is ignored. 7-3 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY 8-17 Reserved for Digital. 18 IP%CFP The packet is privileged. This bit can be set only by a process with WHEEL capability enabled. _______ _______ _____ _________ Refer to the TOPS-20 Monitor Calls Reference ______ Manual for a description of this bit. 19 IP%CFV The packet is a page of 512 (decimal) words of data. 20 IP%CFZ A zero-length message was sent. 21 Reserved for Digital. 22 IP%EPN Page number in word .IPCFP of the packet descriptor block is 18 bits long 23 Reserved for Digital. 24-29 IP%CFE Field for error code returned from INFO. Code Symbol Meaning 15 .IPCPI insufficient privileges 16 .IPCUF invalid function 66 .IPCKM PID has been deleted 67 .IPCSN INFO needs name 72 .IPCFF INFO free space exhausted 74 .IPCBP PID has no name or is invalid 75 .IPCDN duplicate name has been specified 76 .IPCNN unknown name has been specified 77 .IPCEN invalid name has been specified 30-32 IP%CFC System and sender code. This code can be set only by a process with WHEEL capability enabled, but the monitor will return the code so a nonprivileged process can examine it. Code Symbol Meaning 1 .IPCCC Sent by IPCF 2 .IPCCF Sent by system-wide INFO 7-4 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY 3 .IPCCP Sent by receiver's INFO 4 .IPCCG Sent by monitor for QUEUE% JSYS 33-35 IP%CFM Field for special messages. This code can be set only by a process with WHEEL capability enabled, but the monitor will return the code so that a nonprivileged process can examine it. Code Symbol Meaning 1 .IPCFN Process' input queue contains a packet that could not be delivered to intended PID. ______________________________________________________________________ 7.3.2 PIDs 7.3.2 PIDs Any process that wants to send or receive a packet must obtain a PID. The process can obtain a PID by sending a packet to INFO requesting that a PID be assigned. The process must also include a symbolic name that is to be associated with the assigned PID. The symbolic name can be a maximum of 29 characters and can contain any characters as long as it is terminated by a zero word. There should be mutual understanding among processes as to the symbolic names used in order to initiate communication. Once the name is defined, any process referring to that name must specify it exactly character for character. Before a process can send a packet, it must know the receiver's symbolic name or PID. If only the receiver's name is known, the sender must ask INFO for the PID associated with the name, since all communication is via PIDs. The association between a PID and a name is broken: 1. On a RESET% monitor call. 2. When the process is killed or the job logs off the system. 3. When a request to disassociate the PID from the name is made to INFO. INFO will not allow a name already associated with a PID to be assigned again unless the owner of the name makes the request. Nor will INFO assign a PID once it has been used. This action protects against messages being sent to the wrong receiver by accident. 7-5 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY The PIDs of the sender and the receiver are indicated by words .IPCFS and .IPCFR, respectively, of the packet descriptor block. 7.3.3 Length and Address of Packet Data Block 7.3.3 Length and Address of Packet Data Block Word .IPCFP of the packet descriptor block contains the length and the beginning address of the message. The length specified is one of two types, depending on the type of message (refer to Section 7.3.5). If the message is a short-form message, the length is the actual word length of the message. If the message is a long-form message, the length is 1000 (octal) words, that is, one page. The address specified is either an address or a page number, depending on the type of message (refer to Section 7.3.5). When a message is sent, it is taken from this address. When a message is received, it is placed in this address. 7.3.4 Directories and Capabilities 7.3.4 Directories and Capabilities Words .IPCFD and .IPCFC describe the sender at the time the message was sent and are used by the receiver to validate messages sent to it. These two words are not used when a message is sent, and if the sender of the packet supplies them, they are ignored. However, when a message is received, if the receiver of the packet has reserved space for these words in the packet descriptor block, the system supplies the appropriate values of the sender of the packet. The receiver of the packet does not have to reserve these words if it is not interested in knowing the sender's directories and capabilities. 7.3.5 Packet Data Block 7.3.5 Packet Data Block The packet data block contains the message being sent or received. The message can be either a short-form message or a long-form message. A short-form message is one to n words long, where n is defined by the installation. (Usually, n is assumed to be 10 words.) When a short-form message is sent or received, word .IPCFP of the packet descriptor block contains the actual word length of the message in the left half and the address of the first word of the message in the right half. A process always uses the short form when sending messages to INFO. A long-form message is one page in length (1000 octal words). When a long-form message is sent or received, word .IPCFP of the packet descriptor block contains 1000 (octal) in the left half and the page number of the message in the right half. To send and receive a 7-6 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY long-form message, both the sender and receiver must have bit IP%CFV (bit 19) set in the first word of the packet descriptor block, or else an error code is returned. 7.4 SENDING AND RECEIVING MESSAGES 7.4 SENDING AND RECEIVING MESSAGES To send a message, the sending process must set up the first four words of the packet descriptor block. The process then executes the MSEND% monitor call. After execution of this call, the packet is sent to the intended receiver's input queue. To receive a message, the receiving process must also set up the first four words of the packet descriptor block. The last two words for the directories and capabilities of the sender can be supplied, and the system will fill in the appropriate values. The process then executes the MRECV% monitor call. After execution of this call, a packet is retrieved from the receiver's input queue. The input queue is emptied on a first-message-in, first-message-out basis. 7.4.1 Sending a Packet 7.4.1 Sending a Packet The MSEND% monitor call is used to send a message via IPCF. Messages are in the form of packets of information and can be sent to a specified PID or to the system process INFO. Refer to Section 7.5 for information on sending messages to INFO. The MSEND% call accepts two words of arguments. The length of the packet descriptor block is given in AC1, and the beginning address of the packet descriptor block is given in AC2. Thus, AC1: length of packet descriptor block. The length cannot be less than 4. AC2: address of packet descriptor block The packet descriptor block consists of the following four words: .IPCFL Flags .IPCFS Sender's PID .IPCFR Receiver's PID .IPCFP Pointer to packet data block containing the message being sent. Refer to Section 7.3 for the details on the packet descriptor and packet data blocks. 7-7 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY The flags that are meaningful when sending a packet are described in Table 7-2. Refer to Table 7-1 for the complete list of flag bits. Table 7-2: Flags Meaningful on a MSEND% Call Table 7-2: Flags Meaningful on a MSEND% Call ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 IP%CFB Do not block process if no messages in queue; if set, error return if no messages. 1 IP%CFS The sender's PID is given in word .IPCFS of the packet descriptor block. 2 IP%CFR The receiver's PID is given in word .IPCFR of the packet descriptor block. 3 IP%CFO Allow the sender to send one message above its send quota. 4 IP%TTL Truncate message if larger than space reserved. 5 IP%CPD Create a PID for the sender and return it in word .IPCFS of the packet descriptor block. The PID created is to be permanent and useable by other processes according to the setting of bits IP%JWP and IP%NOA. 6 IP%JWP The PID created is to be job wide and permanent until the job logs out. If this bit is not on, the PID created is to be temporary until the process executes the RESET monitor call. 7 IP%NOA The PID created is not to be used by other processes. 18 IP%CFP The message being sent is privileged (refer to _______ _______ _____ _________ ______ the TOPS-20 Monitor Calls Reference Manual). 19 IP%CFV The message being sent is a long-form message (that is, a page). The page the message is being sent to cannot be a shared page; it must be a private page. 22 IP%EPN Page number in word .IPCFP of the packet descriptor block is 18 bits long. ______________________________________________________________________ 7-8 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY When bit IP%CFS is on in the flag word, the sender's PID is taken from word .IPCFS of the packet descriptor block. This word is zero if bit IP%CPD is on in the flag word, indicating that a PID is to be created for the sender. In this case, the PID created is returned in word .IPCFS. When bit IP%CFR is on in the flag word, the receiver's PID is taken from word .IPCFR of the packet descriptor block. If this word is 0, then the receiver of the message is INFO. Refer to Section 7.5 for information on sending messages to INFO. On successful execution of the MSEND% monitor call, the packet is sent to the receiver's input queue. Word .IPCFS of the packet descriptor block is updated with the sender's PID. Execution of the user's program continues at the second location after the MSEND% call. (MSEND%) If execution of the MSEND% call is not successful, the message is not sent, and an error code is returned in AC1. The execution of the user's program continues at the instruction following the MSEND% call. 7.4.2 Receiving a Packet 7.4.2 Receiving a Packet The MRECV% monitor call is used to retrieve a message from the process' input queue. Before a process can retrieve a message, it must know if the message is a long-form message and also must set up a packet descriptor block. The MRECV% monitor call accepts two words of arguments. The length of the packet descriptor block is given in AC1, and the beginning address of the packet descriptor block is given in AC2. Thus, AC1: length of packet descriptor block. The length cannot be less than 4. AC2: address of packet descriptor block The packet descriptor block can consist of the following nine words. The last five words are optional, and if supplied by the receiver, the values of the sender will be filled in by the system. .IPCFL Flags .IPCFS Sender's PID .IPCFR Receiver's PID .IPCFP Pointer to packet data block where the message is to be placed. .IPCFD Connected and logged-in directories of the sender. .IPCFC Enabled capabilities of the sender. .IPCSD Number of sender's connected directory. 7-9 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY .IPCAS Account string of sender. .IPCLL Byte pointer for destination of sender's node. Refer to Section 7.3 for the details on the packet descriptor and packet data blocks. The flags that are meaningful when receiving a packet are described in Table 7-3. Refer to Table 7-1 for the complete list of flag bits. Table 7-3: Flags Meaningful on a MRECV% Call Table 7-3: Flags Meaningful on a MRECV% Call ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 0 IP%CFB If there are no packets in the receiver's input queue, do not block the process and return an error code if the queue is empty. If this bit is not on, the process waits until a packet arrives, if the queue is empty. 1 IP%CFS Use PID referenced in word .IPCFS as sender's PID. 2 IP%CFR The receiver's PID is given in word .IPCFR of the packet descriptor block. 3 IP%CFO Allow one send request above quota. (Default send quota is 2.) 4 IP%TTL Truncate the message if it is larger than the space reserved for it in the packet data block. If this bit is not on and the message is too large, an error code is returned and no message is received. 5 IP%CPD Create PID for sender and return in word .IPCFS. 6 IP%JWP Make created PID job wide (ignored unless IP%CPD set). 7 IP%NOA Do not allow other processes to use created PID (ignored unless IP%CPD set). 18 IP%CFP Packet is privileged (requires IPCF capability enabled). 7-10 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY 19 IP%CFV The message is expected to be a long-form message (that is, a page). The page the message is being stored into cannot be a shared page; it must be a private page. 22 IP%EPN Page number in word .IPCFP of the packet descriptor block is 18 bits long. ______________________________________________________________________ The information in word .IPCFS is not supplied by the receiver when the MRECV% call is executed. The system fills in the PID of the sender of the packet when the packet is retrieved. Word .IPCFR is supplied by the receiver. If bit IP%CFR is on in the flag word, then the PID receiving the packet is taken from word .IPCFR of the packet descriptor block. If bit IP%CFR is not on in the flag word, then word .IPCFR contains either -1, to receive a packet for any PID belonging to this process, or -2, to receive a packet for any PID belonging to this job. When -1 or -2 is given, packets are not received in any particular order except that packets from a specific PID are received in the order in which they were sent. Any other values in this word cause an error code to be returned. The information in words .IPCFD and .IPCFC is also not supplied by the receiver. If these two words have been specified by the receiver, the system fills in the information when the packet is retrieved. Word .IPCFD contains the sender's connected directory in the left half and the sender's logged-in directory in the right half. Word .IPCFC contains the enabled capabilities of the sender. These words describe the sender at the time the message was sent. On successful execution of the MRECV% monitor call, the packet is retrieved and placed into the packet data block as indicated by word .IPCFP of the packet descriptor block. AC1 contains the length of the next packet in the queue in the left half and flags from the next packet in the right half (see below). This word returned in AC1 is called the associated variable of the next packet in the queue. If there is not another packet in the queue, AC1 contains zero. Execution of the user's program continues at the second instruction after the MRECV% call. The flags returned in the right half of AC1 on successful execution of the MRECV% monitor call are described in Table 7-4. 7-11 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY Table 7-4: MRECV% Return Bits Table 7-4: MRECV% Return Bits ______________________________________________________________________ Bit Symbol Meaning ______________________________________________________________________ 30-32 IP%CFC System and sender code, set only by a privileged process. The packet was sent by IPCF if the code is 1(.IPCCC). The packet was sent by the system-wide INFO if the code is 2(.IPCCF). The packet was sent by the receiver's INFO if the code is 3(.IPCCP). 33-35 IP%CFM Field for return of special messages. If the field contains 1(.IPCFN), then the process' input queue contains a packet that was sent to another PID, but was returned to the sender because it could not be delivered. ______________________________________________________________________ If execution of the MRECV% call is not successful, a packet is not retrieved, and an error code is returned in AC1. The execution of the user's program continues at the instruction following the MRECV% call. 7.5 SENDING MESSAGES TO INFO 7.5 SENDING MESSAGES TO INFO The INFO process is the central information utility for IPCF. It performs functions associated with names and PIDs, such as, assigning a PID or a name or returning a name associated with a PID. A process can request functions to be performed by INFO by executing the MSEND% monitor call (refer to Section 7.4.1). The message portion of the packet (that is, the packet data block) sent to INFO contains the request being made. In other words, the total request to INFO is a packet consisting of a packet descriptor block and a packet data block containing the request. 7-12 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY Packet Descriptor Block !=======================================================! ! flag word ! !-------------------------------------------------------! ! sender's PID ! !-------------------------------------------------------! ! 0 ! !-------------------------------------------------------! ! pointer to request ! !=======================================================! Packet Data Block !=======================================================! ! code ! function ! ! ! ! !-------------------------------------------------------! ! PID ! !-------------------------------------------------------! ! function argument ! !=======================================================! Refer to Section 7.4.1 for the descriptions of the words in the packet descriptor block. The receiver's PID (word .IPCFR) is 0 when sending a packet to INFO. 7.5.1 Format of INFO Requests 7.5.1 Format of INFO Requests As mentioned previously, the packet data block (that is, the message portion) of the packet contains the request to INFO. The first word (word .IPCI0) contains a user-defined code in the left half and the function being requested in the right half. The user-defined code is used to associate the response from INFO with the correct request. The functions that the process can request of INFO are described in Table 7-5. The second word (word .IPCI1) contains a PID associated with a process that is to receive a duplicate of any response from INFO. If this word is zero, the response from INFO is sent only to the process making the request. The third word (word .IPCI2) contains the argument for the function specified in the right half of word .IPCI0. The argument is different depending on the function being requested. The arguments for the functions are described in Table 7-5. 7-13 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY Table 7-5: INFO Functions and Arguments Table 7-5: INFO Functions and Arguments ______________________________________________________________________ Function Argument Meaning ______________________________________________________________________ .IPCIW name Return the PID associated with the given name (refer to Section 7.3.2 for the description of the name). .IPCIG PID Return the name associated with the given PID. .IPCII name in Assign the given name to the PID ASCIZ associated with the process making the request. The PID is permanent if IP%JWP was set in the flag word when the PID was originally created (refer to Table 7-1). .IPCIJ name in Identical to .IPCII function. ASCIZ ______________________________________________________________________ 7.5.2 Format of INFO Responses 7.5.2 Format of INFO Responses Responses from INFO are in the form of a packet sent to the process that made the request. A copy of the response is sent to the PID given in word .IPCI1, if any. The message portion (that is, the packet data block) of the packet contains the response from INFO. The format of this response is !=======================================================! ! code ! function ! ! ! ! !-------------------------------------------------------! ! response ! !-------------------------------------------------------! ! response ! !=======================================================! The first word (word .IPCI0) contains the user-defined code in the left half and the function that was requested in the right half. These values are copied from the values given in the request. The second and third words (words .IPCI1 and .IPCI2) contain the response from the function requested of INFO. The response is 7-14 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY different depending on the function requested. The responses from the functions are described in Table 7-6. Table 7-6: INFO Responses Table 7-6: INFO Responses ______________________________________________________________________ Function Requested Response ______________________________________________________________________ .IPCIW The PID associated with the name given in the request is returned in word .IPCI1. .IPCIG The name associated with the PID given in the request is returned in word .IPCI1. .IPCII No response is returned. ______________________________________________________________________ 7.6 PERFORMING IPCF UTILITY FUNCTIONS 7.6 PERFORMING IPCF UTILITY FUNCTIONS A process can request various functions to be performed by executing the MUTIL% monitor call. Some of these functions are enabling and disabling PIDs, creating and deleting PIDs, and returning quotas. Several of the functions that can be requested are privileged _______ _______ _____ _________ functions. These are described in the TOPS-20 Monitor Calls Reference ______ Manual. The MUTIL% monitor call accepts two words of argument. The length of the argument block is given in AC1, and the beginning address of the argument block is given in AC2. The argument block has the following format: !=======================================================! ! function code ! !-------------------------------------------------------! ! argument for function ! !-------------------------------------------------------! ! argument for function ! !=======================================================! The arguments are different, depending on the function being requested. Any values resulting from the function requested are returned in the argument block, starting at the second word. Table 7-7 describes the functions that can be requested, the arguments for the functions, and the values returned from the functions. 7-15 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY Table 7-7: MUTIL% Functions Table 7-7: MUTIL% Functions ______________________________________________________________________ Function Meaning ______________________________________________________________________ .MUENB Allow the PID given to receive packets. If the process executing the call is not the owner of the PID, the process must be privileged. Argument PID Value Returned None .MUDIS Disable the PID given from receiving packets. If the process executing the call is not the owner of the PID, the process must be privileged. Argument PID Value Returned None .MUGTI Return the PID associated with INFO. Argument PID or job number Value Returned PID of INFO .MUCPI Create a private copy of INFO for the specified job. The caller must have IPCF capability enabled. Argument PID to be assigned to INFO PID or number of job creating private copy .MUDES Delete the PID given. The process executing the call must own the PID being deleted. Argument PID to be deleted Value Returned None 7-16 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY .MUCRE Create a PID for the process or job given. If the job number given is not that of the process executing the call, the process must be privileged. The flag bits that can be specified are IP%JWP and IP%NOA (refer to Table 7-1 for their descriptions). Argument flag bits in the left half, and process handle or job number in the right half Value Returned PID that was created .MUSSQ Set send and receive quotas for the specified PID. The caller must have IPCF capability enabled. The new send quota is given in bits 18-26, and the new receive quota is given in bits 27-35. The receive quota applies to the specified PID, but the send quota applies to the job to which that PID belongs. Argumemts PID new quotas .MUFOJ Return the number of the job associated with the PID given. Argument PID Value Returned Job number associated with PID given .MUFJP Return all PIDs associated with the job given. Argument job number or PID belonging to the job Values Returned Two-word entries for each PID belonging to the job. The first word of the entry is the PID, and the second word has bits IP%JWP and IP%NOA set if appropriate (refer to Table 7-1 for the descriptions of these bits). The list of entries returned is terminated by a zero word. .MUFSQ Return the send quota and the receive quota for the PID given. 7-17 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY Argument PID Values Returned Send quota in bits 18-26 and receive quota in bits 27-35. .MUFFP Return all PIDs associated with the process of the PID given. Argument PID Values Returned Two-word entries for each PID belonging to the process. The first word of the entry is the PID, and the second word has bits IP%JWP and IP%NOA set if appropriate (refer to Table 7-1 for the descriptions of these bits). The list of entries returned is terminated by a zero word. .MUSPQ Set the maximum number of PIDs allowed for the specified job. The caller must have IPCF capability enabled. Argument job number or PID PID quota .MUFPQ Return the maximum number of PIDs allowed for the job given. Argument Job number or PID belonging to the job Value Returned Number of PIDs allowed for the job given .MUQRY Return the packet descriptor block for the next packet in the queue of the PID given. Argument PID, -1 to return the next descriptor block for the process, or -2 to return the next descriptor block for the job Values Returned Packet descriptor block of next packet in queue. .MUAPF Associate the PID given with the process given. 7-18 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY Arguments PID process handle Value Returned None .MUPIC Place the specified PID on a software interrupt channel. An interrupt is then generated when: 1. The MUPIC function is issued while the PID has one or more messages in its receive queue. 2. The PID's receive queue changes its state from empty to containing a message. Subsequent entries to a queue that is not empty do not cause an interrupt. If the channel number is given as -1, the PID is removed from its current channel. The calling process and the process that owns the specified PID must belong to the same job. Arguments PID channel number .MUDFI Set the PID of INFO. An error is given if INFO already has a PID. The caller must have IPCF capability enabled. Arguments PID of INFO .MURSP Return a PID from the system PID table. The PID is returned in word 2 of the argument block. The system PID table currently has the following entries: 0 .SPIPC Reserved for Digital 1 .SPINF PID of INFO 2 .SPQSR PID of QUASAR 3 .SPMDA PID of QSRMDA 4 .SPOPR PID of ORION Argument index into system PID table 7-19 INTER-PROCESS COMMUNICATION FACILITY INTER-PROCESS COMMUNICATION FACILITY .MUMPS Return the maximum packet size for the PID given. Argument PID Value Returned Maximum packet size for PID .MUSKP Set PID to receive deleted PID messages. Allows a controller task to be notified if one of its subordinate tasks crashes. After this function is performed, if the subordinate PID is ever deleted (via RESET or the .MUDES MUTIL function), the monitor will send an IPCF message to the controlling PID notifying it that the subordinate PID has been deleted. This message contains .IPCKP in word 0 and the deleted PID in word 1. Argument Source (subordinate) PID Object (controller) PID .MURKP Return controlling PID for this subordinate PID. Argument Source (subordinate) PID Object (controller) PID (returned) ______________________________________________________________________ On successful completion of the MUTIL% monitor call, the function requested is performed, and any value is returned are in the argument block. Execution of the user's program continues at the second location following the MUTIL% call. If execution of the MUTIL% monitor call is not successful, no requested function is performed and an error code is returned in AC1. Execution of the user's program continues at the location following the MUTIL% call. 7-20 CHAPTER 8 CHAPTER 8 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING The term "extended addressing" refers to the size of the addresses that TOPS-20 uses on the DECSYSTEM-20 Extended KL10 processor. Older versions of TOPS-20 (Release 4.1 and before) used 18-bit addresses; newer versions (Release 5 and after) use 30-bit addresses. This chapter discusses the two main activities associated with using TOPS-20 monitor calls with extended addressing: 1. Writing new programs for execution in sections of memory other than section 0 2. Converting existing programs so that they can be executed in sections other than section 0 This chapter also contains information on hardware instructions and macros useful to MACRO programmers who use extended addressing. The discussion in this chapter depends heavily on the material in the _________________________ _________ _________ ______ DECsystem-10/DECSYSTEM-20 Processor Reference Manual. Refer to that manual for a description of the format of 30-bit addresses, the algorithm the processor uses to calculate effective addresses, and the way that individual machine instructions work. 8.1 OVERVIEW 8.1 OVERVIEW The TOPS-20 extended address space contains 32 (decimal) sections. Each section contains 512 pages of 512 words each (256K words). An 18-bit address, called a local address, can reference any word in a given section. A 30-bit, or global, address can reference any word in any section of memory. In contrast, TOPS-20 V4.1 and earlier provided an 18-bit, 256K-word address space. The Program Counter (PC) register was 18 bits. For each instruction executed, the first action taken was the computation of an 18-bit effective address. The algorithm for calculating the 8-1 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING effective address (including indexing and indirecting rules) was the same for all instructions. Because the TOPS-20 virtual address space is limited to 32 sections, and section numbers longer than 5 bits are illegal, legal addresses are effectively limited to 23 bits. When addressing data, you can view this 32-section address space as one large memory area. From the point of view of program execution, however, memory is divided into 32 discrete sections. A program can have code in more than one section of memory, and it can execute that code (assuming the constraints discussed below), but it must change sections explicitly, as discussed below. Compatibility for existing programs is provided by section 0. A program running in section 0 behaves as though it were being executed on a system without extended addressing, except for certain instructions such as XJRSTF. For more information on the actions of _________________________ _________ specific instructions, see the DECsystem-10/DECSYSTEM-20 Processor _________ ______ Reference Manual. 8.2 ADDRESSING MEMORY AND ACS 8.2 ADDRESSING MEMORY AND ACS The extended format PC contains a section field and a word-within-section field. When an instruction is executed, only the word field is incremented. Column overflow is never carried from the word field to the section field. If the last word of a section is executed, and it is not a jump instruction, then the next instruction is fetched from word 0 of the same section. Thus a program can only change sections explicitly, by means of a PUSHJ, JRST, XJRST or XJRSTF instruction, and only an XJRST or an XJRSTF can change control from section 0 to another section. Because a whole word cannot contain a 30-bit address and the program flags, the PC and flags are a two-word entity. The flag bits are in the first word, and the figure below represents the second word. Figure 8-1 shows the format of the address fields of the PC. 0 5 6 17 18 35 -------------------------------------------------- ! un- ! section ! word-within- ! ! used ! number ! section ! -------------------------------------------------- Figure 8-1: Program Counter Address Fields Figure 8-1: Program Counter Address Fields 8-2 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING The word (word-within-section) field consists of 18 bits and thus represents a 256K-word address space similar to the single-section address space of release 4 and earlier. The section number field is 12 bits, of which only the right-hand five bits can be nonzero because section numbers greater than 31 are illegal. The leftmost seven bits of the section number field must be zero. This provides room to address 32 separate sections, each of 256K words. Each section is further divided into pages of 512 words, just as in earlier releases. The paging facilities allow the monitor to determine the existence and protection of each section. The PC section field determines what section a program is running in. If the section field contains zero, the program is running in section 0. Most extended addressing features are not available to a program running in section 0. All quantities (including addresses), when calculated from section 0, are considered to be local (18 bits). 1. A program executing in section 0 cannot address memory in any other section. (One-word global byte pointers are an _______ exception to this rule. Refer to Chapter 1 of the TOPS-20 _______ _____ _________ ______ Monitor Calls Reference Manual for more information.) 2. The program cannot jump from section 0 to another section unless it uses a monitor call or the XJRST or XJRSTF instruction. 3. The program runs exactly as it would run on a machine without extended addressing. If the section field contains a number from 1 to 31 (decimal) inclusive, the program is executing in a nonzero section (a section other than section 0). The hardware considers addresses to be 30 bits, and the program can use extended addressing features. A local address is defined as an 18-bit address in the same section as the program counter (PC) of the instruction. Local addresses are relative to the PC section. A global address is a 30-bit address, which therefore supplies its own section number. The following paragraphs explain the way effective addresses are calculated in nonzero sections. In addition, see the description in _________________________ _________ _________ ______ the DECsystem-10/DECSYSTEM-20 Processor Reference Manual. 8.2.1 Instruction Format 8.2.1 Instruction Format The format of a machine instruction is the same as on an unextended machine. The effective address calculation depends on the address field (Y, 18 bits), the index field (X, 4 bits), and the indirect field (I, 1 bit). Figure 8-2 shows these fields. 8-3 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING 0 8 9 12 13 14 17 18 35 --------------------------------------------------- ! ! ! ! ! ! ! OPCODE ! AC ! I ! X ! Y ! ! ! ! ! ! ! --------------------------------------------------- Figure 8-2: Instruction Word Address Fields Figure 8-2: Instruction Word Address Fields If I and X are 0, the instruction uses neither indexing nor indirection, so the effective address is Y (18 bits). The section number, since it is not specified in the address, is taken from the section field of the PC. The PC section field contains the number of the section from which the instruction was fetched. Such an 18-bit address is called a local address. The following is an example of an instruction whose I, X and Y fields evaluate to an 18-bit effective address. 3,,400/ MOVEM T,1000 The effective address is word 1000 of the current section. The section from which the instruction is fetched is section 3, so the instruction moves the contents of register T into memory word 3,,1000. 8.2.2 Indexing 8.2.2 Indexing The first step in the effective address calculation is indexing. If the X field is nonzero, indexing is used. The calculation of the effective address then depends on the contents of the specified index register. Indexing may be local or global as follows: o If the left half of the index register contains a negative number or zero, the contents of the right half (bits 18-35) are added to Y (from the instruction word) to yield an 18-bit local address. This is the way indexing is done on an unextended machine. It allows a program to use the usual AOBJN pointer and stack pointer formats for tables and stacks that are in the same section as the program. Note, however, that if the left half of the index register contains a positive number, the results are not the same. o If the left half of the index register contains a positive number, the contents of bits 6-35 of the register are added to Y to yield a 30-bit global address. 8-4 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING This means that instructions can reference 30-bit (global) addresses by means of an index register. If the Y field is 0, the instruction refers to the address contained in X. The Y field can contain a positive or negative offset of magnitude less than 2^17. 8.2.3 Indirection 8.2.3 Indirection If the I field contains 1, the instruction specifies indirection. An indirect word is fetched from the address determined by Y and X. Two types of indirect word exist, Instruction Format Indirect Word (IFIW) and Extended Format Indirect Word (EFIW). They are described in the following section. 8.2.3.1 Instruction Format Indirect Word (IFIW) 8.2.3.1 Instruction Format Indirect Word (IFIW) - This word contains Y, X, and I fields of the same size and in the same position as instructions (in bits 13-35). Bit 0 must be 1, and bit 1 must be 0; bits 2-12 are not used. Figure 8-3 shows an instruction format indirect word. 0 1 2 12 13 14 17 18 35 ----------------------------------------------------- ! ! ! ! ! ! ! !1!0! (not used) !I ! X ! Y ! ! ! ! ! ! ! ! ----------------------------------------------------- Figure 8-3: Instruction Format Indirect Word Figure 8-3: Instruction Format Indirect Word The effective address calculation continues with the quantities in this word just as for the original instruction. Indexing can be specified and can be local or global depending on the left half of the index. Further indirection can also be specified. Note that the default section for any local addresses produced from this indirect word is the section from which the word itself was fetched. This means that the default section can change during the course of an effective address calculation that uses indirection. The default section is always the section from which the last address word was fetched. 8-5 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING 8.2.3.2 Extended Format Indirect Word (EFIW) 8.2.3.2 Extended Format Indirect Word (EFIW) - This word also contains Y, X, and I fields, but in a different format. Figure 8-4 shows an extended format indirect word. 0 1 2 5 6 17 18 35 ----------------------------------------------------- ! ! ! ! <-------------!- Y -------------------> ! !0!I! X ! (section) ! (word) ! ! ! ! ! ! ! ----------------------------------------------------- Figure 8-4: Extended Format Indirect Word Figure 8-4: Extended Format Indirect Word If indexing is specified in this indirect word (bits 2-5 nonzero), the contents of the entire index register are added to the 30-bit Y to produce a global address. This type of indirect word never produces a local address. The type of address calculation used does not depend on the contents of the index register specified in the X field. Hence either Y or Y(X) can be used as an address or an offset within the extended address space, just as is done in the 18-bit address space. If further indirection is specified (bit 1 set), the next indirect word is fetched from Y as modified by indexing (if any). The next indirect word can be in instruction format or extended format, and its interpretation does not depend on the format of the previous indirect word. 8.2.3.3 Macros for Indirection 8.2.3.3 Macros for Indirection - The system file MACSYM.MAC contains several convenient macros for constructing indirect words. Macro LFIWM generates local (instruction format) indirect words. Both the macros EP. and GFIWM may be used to generate global (extended format) indirect words. 8.2.4 AC References 8.2.4 AC References A local address in the range 0-17 (octal) references the hardware ACs as memory. This is true in every section of memory. A global address in section 1 in the range 1,,0 to 1,,17 (octal) also refers to the hardware ACs. A global address in any other section refers to memory. This means that the following behavior occurs. 1. Addresses in the range 0-17 reference ACs as expected. The instruction MOVE 2,3 8-6 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING fetches the contents of hardware register 3 regardless of what section the instruction executes in. 2. To make a global reference to an AC, the global address must contain a section number of 0 or 1. 3. Arrays can cross section boundaries. Global addresses specifying any section except section 1 always refer to memory, never to the hardware ACs. For this reason, incrementing the address 6,,777777, for example, yields address 7,,000000, which is a memory location. 4. The ACs are regarded as local to any section; a local address (0-17) references the ACs from any section. Hence, a jump instruction which yields a local effective address of 0-17 in any section will cause code to be executed from the ACs. 8.2.5 Extended Addressing Examples 8.2.5 Extended Addressing Examples These instructions make local references within the current PC section: 3,,400/ MOVE T,1000 ; fetches from 3,,1000 JRST 2000 ; jumps to 3,,2000 The following instructions scan table TABL, which is in the current section: MOVSI X,-SIZ LP: CAMN T,TABL(X) ; TABL in current section JRST FOUND AOBJN X,LP The following instructions scan table TABL, which is in section TSEC, by using a global address: MOVEI X,0 LP: CAMN T,@[GFIWM TSEC,TABL(X)] ; extended format JRST FOUND CAIGE X,SIZ-1 AOJA X,LP Similarly, the EP. macro can be used for the same purpose: MOVEI X,0 LP: CAMN T,@[EP.B17!TABL(X)] JRST FOUND CAIGE X,SIZ-1 AOJA X,LP 8-7 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING The following examples illustrate various aspects of indexing and indirection in effective address calculation: 4/100 6,,1000/MOVE 1,@2000 6,,2000/LFIWM @4000 6,,4000/LFIWM 200(4) Effective address = 300 in section 6 6,,SUB/ MOVE 1,@[LFIWM @ZZZ] 6,,ZZZ: LFIWM @XXX XXX: LFIWM ARRAY(4) Effective address = ARRAY+100 in section 6 6/14,,ADDRX 11,,ROU/MOVE 1,@[LFIWM (6)] 14,,ADDRX: LFIWM 100 Effective address = 14,,100 8.2.6 Immediate Instructions 8.2.6 Immediate Instructions Each effective address calculation yields a 30-bit address, defaulting the section if necessary. Immediate instructions use only the low-order 18 bits of this as their operand, however, and set the high-order 18 bits to 0. Hence instructions such as MOVEI and CAI produce identical results regardless of the section in which they are executed. Two immediate instructions retain the section field of their effective addresses. These are: o XMOVEI (opcode 415) Extended Move Immediate o XHLLI (opcode 501) Extended Half Word Left to Left Immediate 8.2.6.1 XMOVEI 8.2.6.1 XMOVEI - The XMOVEI instruction loads the 30-bit effective address into the AC, and sets bits 0-5 to 0. If no indexing or indirection is used, the number of the current section is copied from the PC to the AC. This instruction can replace MOVEI when a global address is needed. 8-8 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING The following example shows the use of the XMOVEI instruction in a subroutine call. The subroutine is in section XSEC, but the argument list is in the same section as the calling program. XMOVEI AP,ARGLIST PUSHJ P,@[GFIWM XSEC,SUBR] The subroutine can reference the arguments with the following instruction. MOVE T,@1(AP) To construct the addresses of arguments, the subroutine can use the following instruction. XMOVEI T,@2(AP) The last two instructions assume that register AP contains the argument list pointer. If the address the calling program placed in AP is an IFIW, the section number in the effective address is that of the calling program. If the address the calling program placed in AP is an EFIW, the section number in the effective address of the argument block is determined by the section number the calling program placed in AP. The argument list would be found in the caller's section because of the global address in AP. The section of the effective address is determined by the caller, and is implicitly the same as the caller if an IFIW is used as the arglist pointer, or is explicitly given if an EFIW is used. 8.2.6.2 XHLLI 8.2.6.2 XHLLI - The XHLLI instruction replaces the left half of the accumulator with the section number of the PC, and places zero in the right half of the AC. This instruction is useful for constructing global addresses. 8.2.7 Other Instructions 8.2.7 Other Instructions The instructions discussed here are affected by extended addressing, but not necessarily in the way that their effective addresses are calculated. In addition to the material presented here, see the _________________________ _________ _________ ______ DECsystem-10/DECSYSTEM-20 Processor Reference Manual regarding the following instructions: LUUOs, BLT, XBLT, XCT, XJRSTF, XJEN, XPCW, SFM. 8-9 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING 8.2.7.1 Instructions that Affect the PC 8.2.7.1 Instructions that Affect the PC - These instructions are PUSHJ, POPJ, JRST. PUSHJ stores a 30-bit PC address, but stores no flags. It sets bits 0-5 of the destination word to 0. POPJ restores a 30-bit PC address from the stack, but does not restore the flags. It also sets bits 0-5 of the destination word to 0. The JSA and JRA instructions can be used only within a section. In section 0 the JSP and JSR instructions can store flags,,PC but then cannot transfer out of section 0. The JSP and JSR instructions can store flags,,PC in nonzero sections and then can transfer into any other section (if the address is specified with indexing or indirection). 8.2.7.2 Stack Instructions 8.2.7.2 Stack Instructions - PUSHJ, POPJ, PUSH, POP, and ADJSP. These instructions use a local or global address for the stack according to the contents of the stack pointer. Whether the stack address is local or global depends on the same rules as those that govern indexing in effective address calculation. (See section 8.2.2.) It is always best to use the ADJSP instruction when working with stacks. This instruction works in any section and will indicate when a pushdown overflow error occurs. In brief, if the left half of the stack pointer is zero or negative (prior to incrementing or decrementing), the pointer references a local address and the address in its right half is the address of the current item in the stack. The stack pointer is incremented or decremented by adding or subtracting one from both sides, respectively. If the left half of the stack pointer is positive, the entire word is taken as a global address. The stack pointer is incremented by adding 1, and decremented by subtracting 1. A stack that contains global addresses can be used the same way a local stack is used. The global stack, however, can contain pointers to routines in other sections. To protect against stack overflow and underflow, make the pages before and after the stack inaccessible. This method must be used because a global stack has no room for a count in the left half of the pointer. 8.2.7.3 Byte Instructions 8.2.7.3 Byte Instructions - To reference a byte in another section, you must use either a one-word, or a two-word, global byte pointer. Both global and local byte pointers are legal arguments to monitor calls from nonzero sections but there are some restrictions on the use of one-word global byte pointers from section 0. See Section 8.3 for further information. 8-10 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING _______ _______ _____ _________ ______ Chapter 1 of the TOPS-20 Monitor Calls Reference Manual describes _________________________ one-word global byte pointers. The DECsystem-10/DECSYSTEM-20 _________ _________ ______ Processor Reference Manual describes two-word global byte pointers. 8.3 USING MONITOR CALLS 8.3 USING MONITOR CALLS If a program runs in a single section, even though that section is not section 0, most monitor calls execute exactly the way they do in section 0. This is because when no section number is specified, the current section is the default. The GTFDB% call, for example, requires that AC3 contain the address of the block in which to store the data it obtains from the file data block. This address can be an 18-bit address regardless of what section the monitor call is made from. When the monitor sees that the address is local, it obtains the section number from the PC of the process that makes the call. The same is true of calls that accept page numbers. If a 9-bit page number is passed as an argument, the monitor obtains the section number from the PC of the process that made the call. Monitor calls _______ _______ _____ arguments are discussed in Chapter 1 of the TOPS-20 Monitor Calls _________ ______ Reference Manual. It is sometimes desirable to specify addresses in section 0 when executing a JSYS from a nonzero section. The bit PM%EPN for PMAP%, and FH%EPN for JSYSs that accept fork handles, prevent the current section (the section in which a program is running) from being the target section for the monitor call's arguments. Another restriction on arguments passed to monitor calls executed in sections other than section 0 concerns universal device designators, which have the format 5xxxxx,,xxxxxx or 6xxxxx,,xxxxxx (.DVDES). Universal device designators are not legal except in section 0. This is because of the existence of one-word global byte pointers, which can have the same format. Thus monitor calls that accept either a device designator or a byte pointer when called from section 0 do not accept universal device designators in any other section. Other device designators, such as .TTDES (0,,4xxxxx), can be used in any section. Conversely, these monitor calls that can accept either universal device designators or byte pointers do not accept one-word global byte pointers in section 0. The calls SIR% and RIR% should not be used in sections other than section 0. These calls work in other sections only if all the code associated with these calls exists in the same section as the code that makes the call. 8-11 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING For example, if an SIR% call is executed in section 4, it executes correctly if and only if the code that generates the interrupts, the interrupt-processing routines, and all associated tables are also located in section 4. Thus, in programs intended to run in a section other than section 0, the XSIR% and XRIR% calls, described in Chapter 4, should be used in place of SIR% and RIR%. In general, it is recommended that the extended form of monitor calls be used since this form works in any section, including section 0. 8.3.1 Mapping Memory 8.3.1 Mapping Memory The PMAP% monitor call accepts an 18-bit page number, half of which is a section number. Thus PMAP% can be used to map a page from one section to another. If the destination section does not exist, that section will be created. The SMAP% monitor call maps one or more sections of memory. It works like the PMAP call, but maps sections instead of pages. If the destination section does not exist, SMAP% creates the section. Access to the sections in a process map is determined by the same algorithm that determines access to a page within a given section. If a process section and a page in that section have different accesses, the access privileges are ANDed together. The process requesting access to the page gains access only if it has access rights at least equal to the ANDed protections. For example, if a process has read access to a section and maps a page into that section for which the process has read and write access, the page is mapped, but the process gets only read access to the mapped page. The following sections describe the SMAP% functions. 8.3.1.1 Mapping File Sections to a Process 8.3.1.1 Mapping File Sections to a Process - This function maps one or more sections of a file to a process. All pages that exist in the source sections are mapped to the destination sections. Access to the mapped pages is determined by ANDing the access allowed to the file and the access specified in the SMAP% call. Although files do not actually have section boundaries, this monitor call views them as having sections that consist of 512 contiguous pages. Each file section starts with a page number that is an integer multiple of 512. This call cannot map a process memory section to a file. To map a process section to a file, use the PMAP% monitor call to map the section page-by-page. 8-12 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING This function of the SMAP% call requires three words of arguments, as follows: AC1: source identifier: JFN,,file section number AC2: destination identifier: fork handle,,process section number AC3: flags,,count The flags determine access to the destination section, and the count is the number of contiguous sections to be mapped. The count must be between 0 and 37 (octal). The flags are as follows. B2(SM%RD) Allow read access B3(SM%WR) Allow write access B4(SM%EX) Allow execute access B18-35 The number of sections to map. This number must be between 1 and 37 (octal). 8.3.1.2 Mapping Process Sections to a Process 8.3.1.2 Mapping Process Sections to a Process - The SMAP% monitor call also maps sections from one process to another process. In addition, you can map one section of a process to another section of the same process. The SMAP% call maps all pages that exist in the source section to corresponding pages in the destination section. If you map a source section into a destination section with SM%IND set, SMAP% creates the destination section using an indirect pointer. This means that the destination section will contain all pages that exist in the source section, and the contents of the destination pages will be identical to the contents of the source pages. Furthermore, after SMAP% has mapped the destination section, changes that occur in the source section map cause the same changes to be made in the destination section map. This ensures that both the source section and the destination section contain the same data. If SM%IND is not set, SMAP% creates the new section using a shared pointer. After SMAP% maps the destination section, changes that occur in the source section's map do not cause any change in the destination section's map. Thus after a short time the source and destination sections might contain different data. If you request a shared pointer (SM%IND not set) to the destination section, what happens depends on the contents of the source section when the SMAP% call executes. The outcome is one of the following. 8-13 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING 1. If the source section does not exist, the SMAP% call creates the section. 2. If the source is a private section, a mapping to the private section is established, and the destination process is co-owner of the private section. 3. If the source section contains a file section, the source section is mapped to the destination section. 4. If the source section map is made by means of an indirect section pointer, SMAP% follows that pointer until the source section is found to be nonexistent, a private section, or a section of a file. This SMAP% function requires three words of arguments in AC1 through AC3. AC1: Source identifier: fork handle,,section number AC2: Destination identifier: fork handle,,section number AC3: access flags,,the number of contiguous sections to map. The number of sections mapped, the number in the right half of AC3, must be between 1 and 37. The flags determine access to the destination section. The flags are as follows: B2(SM%RD) Allow read access B3(SM%WR) Allow write access B4(SM%EX) Allow execute access B6(SM%IND) Map the destination section using an indirect section pointer. Once the destination section map is created, the indirect section pointer causes the destination section map to change in exactly the same way that the source section map changes. B18-35 Count of the number of contiguous sections to be mapped. 8.3.1.3 Creating Sections 8.3.1.3 Creating Sections - Before you can use a nonzero section of memory, you must create it. If your program references a nonzero section of memory that does not exist (that is not mapped), the instruction that makes the reference fails. 8-14 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING This SMAP% function requires three words of arguments in AC1 through AC3, as follows: AC1: 0 AC2: destination identifier: fork handle,,section number AC3: flags,,count The flags determine access to the destination section, and the count is the number of contiguous private sections to be created. This count must be between 1 and 37. The flags in the left half of AC3 are as follows: B2(SM%RD) Allow read access B3(SM%WR) Allow write access B4(SM%EX) Allow execute access B6(SM%IND) Create the section using an indirect pointer B18-35 The number of sections to create. This number must be between 1 and 37. All created sections are contiguous. 8.3.1.4 Unmapping a Process Section 8.3.1.4 Unmapping a Process Section - You can use the SMAP% monitor call to unmap one or more sections of memory in a process. The contents of the section are lost. If the section contains pages mapped from a file, this function does not cause the unmapped sections to be written back to the file from which they were mapped. Such pages must be mapped to the file by means of the PMAP% call. This function requires three words of arguments in AC1 through AC3, as follows. AC1: -1 AC2: Destination identifier: fork handle,,section number AC3: 0,,count The count is the number of contiguous sections to be unmapped. This number must be between 1 and 37. 8-15 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING 8.3.2 Starting a Process in Any Section 8.3.2 Starting a Process in Any Section You can use most of the calls described in Chapter 5 to control programs that run in a nonzero section. The SFORK% monitor call is an exception, and will not start a program in a nonzero section. The XSFRK% monitor call starts a process in any section of memory. If the process is frozen (by means of the FFORK% call), XSFRK% changes the double-word PC, but does not resume execution of the process. To resume the execution of any frozen fork, use the RFORK% call. The XSFRK% call requires three words of arguments in AC1 through AC3. AC1: flags,,process handle Flags: SF%CON(1B0) continue a process that has halted. If SF%CON is set, the address in AC3 is ignored and the process continues from where it was halted. AC2: PC flags,,0 AC3: address to which this call is to set the PC The XSFRK% call also starts a process in section 0. To do so, set the left half of AC3 to zero and the right half of AC3 to the address in section 0 at which you want the process to start. Most other calls consider an address with a zero in the left half to be a local address. The XSFRK% call, however, uses the contents of AC3 to set the PC. A PC with zero in the left half indicates an address in section 0. 8.3.3 Setting the Entry Vector in Any Section 8.3.3 Setting the Entry Vector in Any Section The SEVEC% monitor call has room in its argument ACs for only a half-word address, so it cannot be used to set a process entry vector to an address in a nonzero section. The XSVEC% call, on the other hand, uses an AC for the address of the entry vector, and another AC for the length of the entry vector, and can specify an entry vector in any section of memory. The XSVEC% call requires three words of arguments in AC1 through AC3. AC1: process handle AC2: length of the entry vector, or 0 AC3: address of the beginning of the entry vector 8-16 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING The length of the entry vector specified in AC2 must be less than 1000 words. If AC2 contains 0, TOPS-20 assumes a default length of two words. 8.3.4 Obtaining Information About a Process 8.3.4 Obtaining Information About a Process Although the monitor calls described in Chapter 5 work in any section of memory, several of them can only return information about the section in which they are executed. The following paragraphs describe the monitor calls you can use to obtain information about any section of memory. 8.3.4.1 Memory Access Information 8.3.4.1 Memory Access Information - Several kinds of information about memory are important. Among them are whether a page or section exists (is mapped), and, if so, what the access to a page or section is. The RSMAP% and XRMAP% calls provide this information. The RSMAP% monitor call reads a section map, and provides information about the mapping of one section of the address space of a process. RSMAP% requires one word of arguments in AC1: a fork handle in the left half, and a section number in the right half. It returns the access information in AC2. The map information that RSMAP% returns in AC1 can be the following: -1 no current mapping present (the section does not exist) 0 the mapping is a private section n,,m where n is a fork handle or a JFN, and m is a section number. If n is a fork handle, the mapping is an indirect or shared mapping to another fork's section. If n is a JFN, the mapping is a shared mapping to a file section. The access information bits returned in AC2 are the following: B2(SM%RD) Read access is allowed B3(SM%WR) Write access is allowed B4(SM%EX) Execute access is allowed B5(PA%PEX) The section exists B6(SM%IND) The section was created using an indirect pointer. 8-17 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING Although the RSMAP% call does not return information on individual pages, the data it does return is useful in preventing error returns from the XRMAP% monitor call. The XRMAP% call returns access information on a page or group of pages in any section of memory. Although the RMAP% call returns access data about a page in the current section, and you can use the RSMAP% call in any section of memory, you must use the XRMAP% call to obtain information about pages in any section other than the current section. The XRMAP% call requires two words of arguments in AC1 and AC2. AC1: process handle,,0 AC2: address of the argument block The argument block addressed by AC2 has the following format: !=======================================================! ! Length of the argument block, including this word ! !=======================================================! ! number of pages in this group on which to return data ! !-------------------------------------------------------! ! number of the first page in this group ! !-------------------------------------------------------! ! address at which to return the data block ! !=======================================================! \ . \ \ . \ \ . \ !=======================================================! ! number of pages in this group on which to return data ! !-------------------------------------------------------! ! number of the first page in this group ! !-------------------------------------------------------! ! address at which to return the data block ! !=======================================================! The number of words in the argument block is three times the number of groups of pages for which you want access data, plus one. Each group of pages requires three arguments: the number of pages in the group, the number of the first page in the group, and the address at which the monitor is to return the access data. Note that the address to which the monitor returns data should be in a section of memory that already exists. If it does not exist, the call will fail with an illegal memory reference. The access information returned for each group of pages specified in the argument block is the following: 8-18 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING B2(RM%RD) read access allowed B3(RM%WR) write access allowed B4(RM%EX) execute access allowed B5(RM%PEX) page exists B9(RM%CPY) copy-on-write access For each page specified in the argument block that does not exist, XRMAP% returns a -1. It also returns a zero flag word for each such page. The data block to which XRMAP% returns the access information should therefore contain twice as many words as the number of groups of pages about which you want information. If you execute an XRMAP% call to obtain information about a page in a nonexistent section, the XRMAP% call fails with an illegal memory reference. For this reason it is recommended to execute an RSMAP% call to determine that the section exists before you use XRMAP% to obtain information about any page within that section. 8.3.4.2 Entry Vector Information 8.3.4.2 Entry Vector Information - To obtain the entry vector of a process in any section of memory, use the XGVEC% call. This call returns the length of the entry vector in AC2 and the address of the entry vector in AC3. The XGVEC% call requires one word of argument: in AC1, the handle of the fork for which you want the entry vector. 8.3.4.3 Page-Failure Information 8.3.4.3 Page-Failure Information - A page-fail word, described in the _________________________ _________ _________ ______ DECsystem-10/DECSYSTEM-20 Processor Reference Manual, contains information that allows a program to determine the cause of a page trap and the address of the instruction that caused the trap. This information allows a program to correct the cause of the page-fail trap. Once the program has corrected the cause of the page-fail trap, the program can continue execution. The XGTPW% call obtains the page-fail word from the monitor's data base, and returns it to the calling program's address space. The XGTRP% call requires two words of arguments in AC1 and AC2. AC1: process handle AC2: address of the block in which to return data 8.3.5 Program Data Vectors 8.3.5 Program Data Vectors Program Data Vectors (PDVs) are data structures in a process that are known to the monitor by name and location. They contain information 8-19 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING about the program segments within a process. The PDV is a block of data that LINK writes into memory when loading and linking a program. The PDV resides in memory as a part of the program, and starts at a program data vector address (PDVA). PDVs are used to allow user programs to obtain information about other programs that can be mapped into a process. PDVs and PDVAs are manipulated by using the PDVOP% _______ _______ _____ _________ ______ monitor call. (Refer to the TOPS-20 Monitor Calls Reference Manual for a complete description of the PDVOP% monitor call.) The PDVOP% monitor call can be used to obtain information about an execute-only process. Certain words in the PDV (for example, .PVNAM) point to blocks of information. These words are in either IFIW or EFIW format (see Sections 8.2.3.1 and 8.2.3.2) except that they cannot use indexing, and any indirect chain pointed to by the word cannot go through an accumulator. This allows a program to find the address of a block pointed to by a PDV word by simply using an XMOVEI instruction. For example, XMOVEI AC1,@.PVNAM(AC2) puts into AC1 the global address of the name of the PDV whose PDVA is in AC2. 8.3.5.1 Manipulating PDV Addresses 8.3.5.1 Manipulating PDV Addresses - For the process specified in word .POPHD of the argument block, the .POGET function of the PDVOP% monitor call returns all PDVAs within the range of addresses specified in words .POADR and .POADE of the argument block. (See the _______ _______ _____ description of the PDVOP% monitor call in the TOPS-20 Monitor Calls _________ ______ Reference Manual for the format of the argument block.) The address range supplied by words .POADR and .POADE determines which PDVAs are affected by any given call. The .POADD function of the PDVOP% monitor call adds the PDVAs specified in the data block to the system's data base for the specified process. The PDVAs must be in ascending order within the data block. The .POREM function of the PDVOP% monitor call removes a set of PDVAs from the system's data base for the specified process. Those removed are the ones within the range specified by words .POADR and .POADE of the argument block. 8.3.5.2 PDV Names 8.3.5.2 PDV Names - The .PONAM function of the PDVOP% monitor call returns the ASCIZ name of a PDV in memory. Word .POADR of the argument block must contain a valid PDVA for the specified process. The name returned is the one to which word .PVNAM of the PDV points. The string returned by .PONAM is placed into the data block. 8-20 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING For the specified process, the .POLOC function returns in the data block all the PDVAs of PDVs with the specified name. The byte pointer in AC3 points to the PDV name. Function .POLOC is affected by .POADR/.POADE words. The following rules apply to the assignment of PDV names. If these rules are followed, it is quite unlikely that two packages that want to run in the same process will discover a conflict in PDV names. 1. PDV names assigned by DIGITAL will contain the character "%" at the end (or elsewhere). No PDV names assigned by users should contain the "%" character. 2. All PDV names containing the character "." are reserved to DIGITAL for future use. 3. The character "$" is reserved for a special use: PDV names of the form string1$string2 are reserved for the special class of use named by string1. Rules 1 and 2 still apply in this case. As a general principle, avoid using PDV names that are insufficiently specific; use of such names invites conflicts with other packages. 8.3.5.3 Version Number 8.3.5.3 Version Number - The .POVER function of the PDVOP% monitor call returns in the data block the version of a program in memory. Word .POADR must contain a valid PDVA for the specified process. The version returned is the one that word .PVVER of the PDV contains. For more information on program data vectors, including explanations of the static memory map (pointed to by word .PVMEM) and the symbol _______ ____ table vector (pointed to by word .PVSYM), refer to the TOPS-20 LINK _________ ______ Reference Manual. 8.4 MODIFYING EXISTING PROGRAMS 8.4 MODIFYING EXISTING PROGRAMS Existing programs can be modified to run in any section of memory, including both section 0 and all other sections. The sections that follow discuss the changes that must be made to an existing program so that it runs in a single nonzero section. 8.4.1 Data Structures 8.4.1 Data Structures Stacks, tables, and other data structures used in the past have often contained words with an address in the right half and a count in the left half. The count could be positive or negative because all 8-21 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING programs ran only in section 0, and when the contents of a word were evaluated for Effective Address calculation or address use in section 0, only the right half was considered. In all other sections, the entire word is considered to be an address. If the left half of the word is negative, the left half is ignored when the address is evaluated, and the address is local. Thus for a word to contain an address in the right half and a count in the left half, the count must be negative. 8.4.1.1 Index Words 8.4.1.1 Index Words - Be sure the left halves of index words contain a nonpositive quantity. To use the left half of an index register to hold a count, the count must be negative. If the left half is unused, it must be zero so that the effective address is a local address. If the left half contains a positive number, the indexed address will be global. 8.4.1.2 Indirect Words 8.4.1.2 Indirect Words - To be sure that an indirect word in a nonzero section is evaluated as a local address, always set bit 0 of the indirect word. Argument lists that produce local addresses in section 0, for example, will produce local addresses in any section if bit 0 is set. 8.4.1.3 Stack Pointers 8.4.1.3 Stack Pointers - As mentioned above, the left halves of stack pointers must contain zero or a negative number to produce local addresses. A negative number in the left half is considered to be a count. A positive number in the left half is considered to be a section number. 8.5 WRITING MULTISECTION PROGRAMS 8.5 WRITING MULTISECTION PROGRAMS Multisection programs, programs that use more than one section of memory, are similar to single-section programs that run in nonzero sections. They allow you to place tables needed for processing interrupts in any section of memory (See Chapter 4), to use very large arrays, and to write modules of code that can be dynamically mapped into a section of memory and executed. In a single-section program, local addresses and byte pointers are sufficient to specify any word or byte in the program's address space. In a multisection program, local addresses and byte pointers cannot specify any word or byte in the program's address space. Most monitor calls use only one AC per argument, so passing two-word global byte pointers is not possible. Thus, it is necessary to: 8-22 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING o keep monitor call arguments in the same section of memory as the code making the call, or o use global arguments, or o use the global form of the monitor call. In many multisection programs it is not necessary to keep all the arguments required by a call in the same section as the code that makes the call. Global arguments are required, and they take several _______ _______ _____ _________ ______ forms. Chapter 1 of the TOPS-20 Monitor Calls Reference Manual gives details on the use of these arguments. The following program computes a file checksum by XORing the words in all file pages. The program is loaded into section 0 and maps itself into section 1. It then jumps into section 1 to access the file data loaded into section 15. TITLE CHKSUM - COMPUTE A FILE CHECKSUM SEARCH MONSYM ;STANDARD UNIVERSAL FILES SEARCH MACSYM .REQUIRE SYS:MACREL ;GET JSERR SUPPORT ROUTINES STDAC. ;DEFINE STANDARD ACS ; PROGRAM CONSTANTS PDLSIZ==100 ;SIZE OF STACK CODSEC==1 ;SECTION TO MAP CODE INTO DATSEC==15 ;SECTION TO MAP FILE DATA INTO DATPAG==100 ;PAGE WITHIN DATSEC FOR FILE DATA PAGSIZ==1000 ;SIZE OF A PAGE CHKSUM: RESET% ;RESET THE WORLD MOVE P,[IOWD PDLSIZ,PDL] MOVE T1,[.FHSLF,,0] ;MAP THIS FORKS SECTION 0 MOVE T2,[.FHSLF,,CODSEC] ;TO EXTENDED CODE SECTION MOVX T3,SM%RD!SM%WR!SM%EX!SM%IND+1 ;INDIRECT POINTER RD,WR,EX 1 SECTION SMAP% EJSHLT ;UNEXPECTED FATAL ERROR GETFIL: SETZM FILJFN ;SAY NO FILE SEEN TMSG < ENTER FILE SPEC TO CHECKSUM: > ;PROMPT USER FOR FILE MOVX T1,GJ%SHT!GJ%OLD!GJ%FNS ;OLD FILE MOVE T2,[.PRIIN,,.PRIOU] ;READ FILE SPEC FROM TERMINAL GTJFN% ;GET FILE SPEC ERJMPR BADFIL ;CANNOT GET FILE TELL USER MOVEM T1,FILJFN ;SAVE FILE JFN MOVX T2,FLD(^D36,OF%BSZ)!OF%RD ;REQUEST READ ACCESS AND 36 BIT BYTES OPENF% ;OPEN THE FILE 8-23 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING ERJMPR BADFIL ;CANNOT OPEN FILE TELL USER XJRST [CODSEC,,DOCHKS] ;ENTER EXTENDED SECTION ;AND DO CHECKSUM BADFIL: JSERR ;PRINT ERROR MESSAGE SKIPE T1,FILJFN ;IS THERE A JFN RLJFN% ;YES. RELEASE IT EJSERR ;PRINT ERROR IF ANY JRST GETFIL ;AND TRY TO GET FILE AGAIN ; THE FOLLOWING CODE RUNS IN A NONZERO SECTION AND ; DOES A CHECKSUM OF THE FILE STORED IN FILJFN DOCHKS: SETZB Q1,Q2 ;Q1 HOLDS THE CHECKSUM. ;INITIALLY ZERO ;Q2 IS THE CURRENT FILE PAGE NUMBER CHKLOP: MOVE T1,Q2 ;GET FILE PAGE NUMBER HRL T1,FILJFN ;AND FILE JFN FFUFP% ;FIND FIRST USED PAGE ERJMPR NOPAGE ;CAN'T GO ANALYZE ERROR HRRZ Q2,T1 ;REMEMBER CURRENT PAGE NUMBER AOS Q2 ;USE NEXT HIGHER PAGE NEXT TIME MOVE T2,[B26+DATPAG] ;THROUGH LOOP TO DATA PAGE HRLI T2,.FHSLF ;IN DATA SECTION OF THIS FORK MOVX T3,PM%RD ;READ ACCESS PMAP% ;MAP THE FILE PAGE EJSHLT ;UNEXPECTED FATAL ERROR HRLI T1,DATSEC ;T1 IS INDEX INTO DATA PAGE. HRRI T1,DATPAG*PAGSIZ ;SETUP SECTION AND PAGE ADDRESS MOVEI T2,PAGSIZ ;T2 COUNTS THE WORDS IN A PAGE ; THE FOLLOWING LOOP DOES THE CHECKSUM FOR A PAGE XORLOP: XOR Q1,(T1) ;CHECKSUM THIS WORD AOS T1 ;STEP TO NEXT WORD SOJG T2,XORLOP ;DO THE WHOLE PAGE SETO T1, ;UNMAP THE FILE PAGE MOVE T2,[B26+DATPAG] ;TO DATA PAGE IN DATA HRLI T2,.FHSLF ;SECTION OF THIS FORK MOVX T3,PM%RD PMAP% EJSHLT ;UNEXPECTED FATAL ERROR JRST CHKLOP ;LOOP FOR MORE PAGES ; HERE WHEN FFUFP% FAILS NOPAGE: CAIE T1,FFUFX3 ;NO USED PAGE FOUND? JSHLT ;NO. UNEXPECTED FATAL ERROR ; PRINT THE CHECKSUM AND QUIT 8-24 USING EXTENDED ADDRESSING USING EXTENDED ADDRESSING TMSG < THE FILE CHECKSUM IS: > MOVX T1,.PRIOU ;PRINT IT ON THE TERMINAL MOVE T2,Q1 ;GET THE CHECKSUM MOVX T3,NO%MAG!FLD(^D8,NO%RDX) ;UNSIGNED OCTAL NUMBER NOUT% EJSHLT ;UNEXPECTED FATAL ERROR MOVE T1,FILJFN ;GET FILE AGAIN CLOSF% ;CLOSE IT EJSHLT ;UNEXPECTED FATAL ERROR HALTF% ;STOP PROGRAM XJRST [CHKSUM] ;JUMP BACK TO SECTION 0 AND ;START OVER IF USER CONTINUES ; STORAGE PDL: BLOCK PDLSIZ ;STACK FILJFN: BLOCK 1 ;FILE JFN END CHKSUM 8-25 INDEX -A- -A- Arguments (Cont.) GTJFN% short form, 3-4 AC, 1-2 IIC%, 5-19 global reference, 8-7 JFNS%, 3-33 references, 8-6 JSYS, 1-2, 1-3 Access monitor calls, 1-3 copy-on-write, 5-5 MRECV%, 7-9 file, 3-2, 3-16 MSEND%, 7-7 file append, 3-16 MUTIL%, 7-15 file frozen, 3-16 OPENF%, 3-16 file read, 3-16 PMAP%, 3-26, 3-28, 5-14 file restricted, 3-16 PMAP% JSYS, 8-15 file thawed, 3-16 RDTTY%, 2-9 file unrestricted, 3-16 SFORK%, 5-15 file write, 3-16 SIN%, 3-22 page, 5-5 SIR%, 4-6 Access bits SMAP%, 3-29, 8-13, 8-14, 8-15 OPENF%, 3-17 SOUT%, 3-23 PMAP%, 3-26 XGTPW%, 8-19 Accumulator (AC), 1-2 XRIR%, 4-15 Accumulators, 1-3 XRMAP% JSYS, 8-18 global reference, 8-7 XSFRK%, 8-16 hardware, 8-6 XSIR%, 4-7 references, 8-6 XSVEC% JSYS, 8-16 Address ASCII strings, 2-1, 3-21 global, 8-1, 8-6 ASCIZ pseudo-op, 1-6 local, 8-4, 8-6 ASCIZ strings, 2-1, 3-21 Address space, 8-1, 8-2 ATI% JSYS, 4-13 process, 1-6, 5-1, 5-11 -B- Addressing -B- extended, 8-1 Addressing ACs, 8-2 BIN% JSYS, 1-5, 3-21 Addressing memory, 8-2 example, 1-5 ADJSP instruction, 2-2, 8-10 Block AIC% JSYS, 4-9, 4-17, 5-4 packet data, 7-2 AOBJN pointer, 8-4 packet descriptor, 7-2 Argument block BLT instruction, 8-9 DEQ%, 6-14 BOUT% JSYS, 3-21 ENQ%, 6-8 Byte, 2-1, 3-1 ENQC%, 6-15 reading a, 2-8 GTJFN% long form, 3-13 transferring, 3-21 Arguments writing a, 2-8 CFORK%, 5-8 Byte instructions, 8-10 DEQ%, 6-12 Byte manipulation instructions, DIC%, 4-16 2-2 ENQ% JSYS, 6-6 ADJSP, 2-2 ENQC%, 6-14 IBP, 2-2 GET%, 5-11 ILDB, 2-2 Index-1 Byte pointer, 8-10 Deferred mode global, 8-10 terminal interrupt, 4-14 local, 8-10 Deleting inferior process, 5-20 one-word global, 2-2, 8-10 DEQ% JSYS, 6-2, 6-6, 6-12 system standard for JSYS, 2-2 argument block, 6-14 two-word global, 2-2, 8-10 arguments, 6-12 functions, 6-12 -C- -C- Descriptor block packet, 7-2 Calling sequence Designator monitor calls, 1-3 destination, 3-20 Capability words, 5-11 primary input, 2-2, 3-20 CFORK% JSYS, 5-4, 5-8, 5-15, 5-19 primary output, 2-2, 3-20 arguments, 5-8 source, 3-20 execution, 5-10 universal device, 8-11 Changing sections, 8-2 Destination designator, 3-20 Channel Device designator deactivating, 4-16 universal, 8-11 panic, 4-5, 4-10, 4-11 DIC% JSYS, 4-16 Channel assignments arguments, 4-16 software interrupt, 4-4 DIR% JSYS, 4-16 Channel table (CHNTAB), 4-7 Direct process control, 5-4 CHNTAB, 4-7 Disabling interrupt system, 4-16 CIS% JSYS, 4-17 DTI% JSYS, 4-17 Clearing interrupt system, 4-17 -E- CLOSF% JSYS, 3-30 -E- example, 3-31 execution, 3-31 Editing functions, 2-9 flag bits, 3-30 Effective address, 8-1 Closing a file, 3-30 Effective address calculation, Communication 8-3, 8-8 process, 1-6 example, 8-8 Communication facility indexing, 8-8 inter-process, 7-1 indirection, 8-8 Control bits extended, 8-3 RDTTY%, 2-10 immediate instructions, 8-8 Control process, 1-6 indexing, 8-5 Copy-on-write access, 5-5 indirection, 8-5 Counter nonzero sections, 8-3 program, 8-1 EFIW, 8-6, 8-20 Creating sections, 8-14 EIR% JSYS, 4-9, 4-11, 4-17, 5-4 EJSERR macro, 1-5 -D- -D- EJSHLT macro, 1-5 ENQ quota, 6-3 Data block ENQ% JSYS, 5-4, 6-2, 6-6, 6-17 packet, 7-2 argument block, 6-8 Data transfer, 2-1 arguments, 6-6 Data transfers, 3-19 functions, 6-6 Deactivating a channel, 4-16 ENQC% JSYS, 5-4, 6-6, 6-14 Deadly embrace, 6-4, 6-5, 6-19 argument block, 6-15 Deassigning terminal codes, 4-17 arguments, 6-14 DEBRK% JSYS, 4-11 flag bits, 6-15 Index-2 ENQUEUE/DEQUEUE (ENQ/DEQ) File thawed access, 3-16 facility, 5-4, 6-1 File unrestricted access, 3-16 use of, 6-6 File write access, 3-16 Entry vector, 8-16 Files, 3-1 information, 8-19 Flag bits EP. macro, 8-6, 8-7 CLOSF%, 3-30 ERCAL symbol, 1-4, 5-15 ENQC%, 6-15 ERCALR symbol, 1-4 GTJFN% long form, 3-14 ERCALS symbol, 1-4, 1-5 GTJFN% short form, 3-5 ERJMP symbol, 1-4, 5-15 MRECV%, 7-10 ERJMPR symbol, 1-4, 2-13 MSEND%, 7-8 ERJMPS symbol, 1-4 SMAP%, 3-29 Error returns Flags monitor calls, 1-4 packet descriptor block, 7-3 ERSTR% JSYS, 1-5 Format Execute-only process, 8-19 extended instruction, 8-3 Extended addressing, 8-1, 8-3 IPCF packet, 7-2 examples, 8-7 INFO requests, 7-13 using monitor calls with, 8-11 INFO responses, 7-14 Extended format indirect word Format options (EFIW), 8-6 JFNS%, 3-34 Extended instruction format, 8-3 NOUT%, 2-6 Extended page number, 8-11 Functions DEQ%, 6-12 -F- -F- ENQ%, 6-6 MUTIL%, 7-15 FH%EPN, 8-11 PDVOP%, 8-20 File RDTTY%, 2-9 closing a, 3-30 -G- examples, 3-40 -G- opening a, 3-16 pointer, 3-20 GET% JSYS, 5-11, 5-14 reading from arguments, 5-11 summary, 3-40 GETER% JSYS, 1-5 referencing, 3-3 GFIWM macro, 8-6 sharing, 3-2, 6-1 GFRKS% JSYS, 5-7 writing to Global address, 8-1, 8-4, 8-6 summary, 3-40 Global byte pointer, 8-10 File access, 3-2, 3-16 Global stack, 8-10 codes, 3-2 GNJFN% JSYS, 3-9, 3-36 File append access, 3-16 bits returned, 3-37 File frozen access, 3-16 GTJFN% JSYS, 3-3, 3-4 File identifier, 3-2 arguments File page mapping, 3-26 long form, 3-12 File pointer, 3-20 short form, 3-4 File read access, 3-16 bits returned, 3-10 File restricted access, 3-16 execution, 3-9, 3-14 File section flag bits mapping, 8-12 long form, 3-14 File section mapping, 3-28 short form, 3-5 File specification, 3-3 long form, 3-4, 3-12 standard, 3-3 argument block, 3-13 Index-3 GTJFN% JSYS (Cont.) Input short form, 3-4 terminal, 2-1 examples, 3-11 Input designator summary, 3-15 primary, 2-2 GTSTS% JSYS, 3-31 Instruction format bits returned, 3-31 extended, 8-3 Instruction format indirect word -H- -H- (IFIW), 8-5 Instructions HALTF% JSYS, 2-8, 5-17 byte, 8-10 example, 2-7 stack, 8-10 Handle section, 8-17 Inter-process communication HFORK% JSYS, 5-17 facility receive quota, 7-1 -I- -I- send quota, 7-1 utility functions, 7-15 I/O monitor calls, 2-2 Inter-process communication IBP instruction, 2-2 facility (IPCF), 1-6, 5-4, Identifier 7-1 file, 3-2 Interrupt, 4-1 IFIW, 8-5, 8-20 generating, 4-10 IIC% JSYS, 4-10, 5-4, 5-19 Interrupt channel assignments, arguments, 5-19 4-4 ILDB instruction, 2-2 Interrupt channels Illegal instruction trap, 1-4 activating, 4-9 Immediate instructions, 8-8 Interrupt conditions, 4-4 Immediate mode Interrupt deferred mode terminal interrupt, 4-14 terminal, 4-14 Indexing, 8-4, 8-20 Interrupt dismissing, 4-11 example, 8-8 Interrupt immediate mode Indirection, 8-5, 8-20 terminal, 4-14 example, 8-8 Interrupt processing, 4-10 extended format indirect word Interrupt service routines, 4-6 (EFIW), 8-6 Interrupt system instruction format indirect clearing, 4-17 word (IFIW), 8-5 disabling, 4-16 Inferior process, 1-6, 5-1 Interrupts characteristics, 5-8 terminal, 4-12 communicating with superior, IPCF, 1-6, 5-4, 7-1 5-10 packet data block, 7-2, 7-6, creating, 5-8, 5-10 7-12 deleting, 5-20 address, 7-6 parallel, 5-10 length, 7-6 starting, 5-15 packet descriptor block, 7-2, status, 5-17 7-12 termination, 5-16 flags, 7-3 Information receive quota, 7-1 about process, 8-17 send quota, 7-1 entry vector, 8-19 utility functions, 7-15 page-failure, 8-19 IPCF packet format, 7-2 Initialization process, 2-8 Index-4 -J- -J- JSYS (Cont.) OPENF%, 3-2, 3-16 JFN, 3-1, 3-2 PBIN%, 2-8, 2-14 JFNS% JSYS, 3-33 PBOUT%, 2-8, 2-14 arguments, 3-33 PDVOP%, 5-11, 8-19 format options, 3-34 PMAP%, 3-25, 3-26, 3-27, 3-28, Job, 1-7 5-11, 5-14, 5-15, 5-19, Job file number, 3-1, 3-2 8-12, 8-15 Job structure, 1-6 PSOUT%, 2-3, 2-14 exapmle, 1-7 RDTTY%, 2-5, 2-9, 2-12, 2-14 JRA instruction, 8-10 RESET%, 2-8, 5-21, 7-5 JRST instruction, 8-2, 8-9 RFSTS%, 5-4, 5-17 JSA instruction, 8-10 RFSTS% long form, 5-17, 5-18 JSP instruction, 8-10 RFSTS% short form, 5-17 JSR instruction, 8-10 RIN%, 3-24 JSYS, 1-2 RIR%, 4-15, 8-11 AIC%, 4-9, 4-17, 5-4 ROUT%, 3-24 arguments, 1-2, 1-3 RSMAP%, 8-17 ATI%, 4-13 SAVE%, 5-11 BIN%, 1-5, 3-21 SEVEC%, 8-16 BOUT%, 3-21 SFORK%, 5-4, 5-15 CFORK%, 5-4, 5-8, 5-10, 5-15, SFRKV%, 5-16 5-19 SIN%, 3-22 CIS%, 4-17 SIR%, 4-6, 4-11, 5-4, 8-11 CLOSF%, 3-30 SKPIR%, 4-14 DEBRK%, 4-11 SMAP%, 3-28, 8-12 DEQ%, 6-2, 6-6, 6-12 SOUT%, 3-22, 3-23 DIC%, 4-16 SPJFN%, 2-2 DIR%, 4-16 SSAVE%, 5-11 DTI%, 4-17 STIW%, 4-14 EIR%, 4-9, 4-11, 4-17, 5-4 WFORK%, 5-4, 5-16 ENQ%, 5-4, 6-2, 6-6, 6-17 XGTPW%, 8-19 ENQC%, 5-4, 6-6, 6-14 XGVEC%, 8-19 error returns, 1-4 XRIR%, 4-15, 8-12 ERSTR%, 1-5 XRMAP%, 8-18 GET%, 5-11, 5-14 XSFRK%, 5-16, 8-16 GETER%, 1-5 XSIR%, 4-6, 4-11, 4-17, 8-12 GFRKS%, 5-7 XSVEC%, 8-16 GNJFN%, 3-9, 3-36 JUMP instruction symbols, 1-4 GTJFN%, 3-3, 3-4, 3-9 ERCAL, 1-4, 5-15 GTSTS%, 3-31 ERCALR, 1-4 HALTF%, 2-8, 5-17 ERCALS, 1-4, 1-5 HFORK%, 5-17 ERJMP, 1-4, 5-15 I/O, 2-2 ERJMPR, 1-4, 2-13 IIC%, 4-10, 5-4, 5-19 ERJMPS, 1-4 JFNS%, 3-33 JUMP instructions, 1-4 KFORK%, 5-4, 5-20 MRECV%, 5-4, 7-7, 7-9 MSEND%, 5-4, 7-7, 7-12 -K- MUTIL%, 5-4, 7-15 -K- NIN%, 2-4, 2-13, 2-14 NOUT%, 2-5, 2-14 KFORK% JSYS, 5-4, 5-20 Index-5 -L- -L- MRECV% JSYS (Cont.) execution, 7-11 Level number flagbits, 7-10 resource, 6-4 flags returned, 7-11 LEVTAB, 4-8 MSEND% JSYS, 5-4, 7-7, 7-12 LFIWM macro, 8-6 arguments, 7-7 LINK, 8-19 execution, 7-9 Literals, 2-2 flag bits, 7-8 Local address, 8-4, 8-6 Multiple processes, 5-2 Local byte pointer, 8-10 Multisection programs, 8-22 Lock MUTIL% JSYS, 5-4, 7-15 resource, 6-1 arguments, 7-15 Long form GTJFN%, 3-12 execution, 7-20 LUUO instructions, 8-9 functions, 7-15 -M- -N- -M- -N- MACSYM, 1-3 NIN% JSYS, 2-4, 2-13, 2-14 MACSYM macros, 1-3 example, 2-7 EJSERR, 1-5 NOUT% JSYS, 2-5, 2-14 EJSHLT, 1-5 example, 2-6, 2-7 EP., 8-7 format options, 2-6 indirection, 8-6 Number EP., 8-6 reading a, 2-4 GFIWM, 8-6 writing a, 2-5 LFIWM, 8-6 -O- TMSG, 2-4 -O- Mapping, 8-12 file page, 3-26 One-word global byte pointer, 2-2, file section, 3-28 8-10, 8-11 file sections to a process, OPENF% JSYS, 3-2, 3-16, 3-27 8-12 access bits, 3-17 memory, 8-12 arguments, 3-16 page, 3-24, 5-14 examples, 3-19 process page, 3-27 Opening a file, 3-16 process section, 8-13 Operation code sections, 8-12 monitor calls, 1-2 Memory, 8-2 Output Memory sharing, 5-5 terminal, 2-1 Messages Output designator receiving process, 7-7 primary, 2-2 sending process, 7-7 Ownership, 6-2, 6-17 Monitor calls, 1-2 exclusive, 6-2, 6-17 arguments, 1-2, 1-3 shared, 6-1, 6-2, 6-17 calling sequence, 1-3 -P- error returns, 1-4 -P- for processes, 5-7 I/O, 2-2 Packet, 7-1, 7-2 operation code, 1-2 receiving a, 7-9 MONSYM, 1-2, 2-3 sending a, 7-7 MRECV% JSYS, 5-4, 7-7, 7-9 Packet data block, 7-2, 7-6, 7-12 arguments, 7-9 address, 7-6 Index-6 Packet data block (Cont.) Priority level table (LEVTAB), length, 7-6 4-8 Packet descriptor block, 7-2, .PRIOU symbol, 2-2, 2-9, 2-14, 7-12 3-20 flags, 7-3 Process, 1-6, 1-7 Packet format address space, 1-6, 5-11 IPCF, 7-2 capabilities, 5-11 Page, 3-1 communication, 1-6, 5-3, 5-19 Page access, 5-5 control, 1-6, 5-4 Page mapping, 5-14 deleting inferior, 5-20 file, 3-25 examples, 5-21 Page sharing, 5-5 execute-only, 8-19 Page-failure information, 8-19 handle, 5-5, 5-10 Panic channel, 4-5, 4-10, 4-11 identifiers, 5-5 Parallel inferior processes, 5-10 inferior, 1-6, 5-1 PBIN% JSYS, 2-8, 2-14 information about, 8-17 PBOUT% JSYS, 2-8, 2-14 JSYSs for, 5-7 PC, 5-1, 8-1, 8-2, 8-9 multiple, 5-2 address, 8-9 parallel, 5-1 address fields, 8-2 starting in any section, 8-16 PDV, 8-19 starting inferior, 5-15 names, 8-20 status word, 5-17 rules, 8-20 structure, 1-6, 5-1 PDVA, 8-19 superior, 1-6, 5-1 manipulating, 8-20 terminating inferior, 5-16 PDVOP% JSYS, 5-11, 8-19 use of resources, 6-5 functions, 8-20 Process communication, 1-6, 5-3, PID, 7-1, 7-5, 7-11 5-5, 5-19 PM%EPN, 8-11 sharing pages, 5-19 PMAP% JSYS, 3-25, 3-27, 3-28, software interrupt, 5-4, 5-19 5-11, 5-14, 5-15, 5-19, 8-12, Process control, 5-4 8-15 Process handle, 5-5 access bits, 3-26 Process ID (PID), 7-1, 7-5, 7-11 arguments, 3-26, 3-28, 5-14, Process identifiers, 5-5 8-15 Process initialization, 2-8 POINT pseudo-op, 2-1 Process mapping, 3-27 Pointer Process messages file, 3-20 receiving, 7-7 Pooled resources, 6-11 sending, 7-7 POP instruction, 8-10 Process relationships, 5-1 POPJ instruction, 8-9, 8-10 Process section, 3-28 .PRIIN symbol, 2-2, 2-9, 2-14, unmapping, 8-15 3-20 Process status word, 5-17 Primary input designator (.PRIIN), Process structure, 1-6, 5-1 2-2, 3-20 Process unmapping, 3-28 Primary output designator Program counter, 8-2 (.PRIOU), 2-2, 3-20 address fields, 8-2 Printing a string, 2-3 Program counter (PC), 5-1, 8-1, Priority level 8-9 interrupt, 4-11 address, 8-9 software interrupt, 4-4 Program data vector (PDV), 8-19 address (PDVA), 8-19 Index-7 Program data vector (PDV) (Cont.) Resource (Cont.) manipulating PDVAs, 8-20 use by process, 6-5 names, 8-20 Resource lock, 6-1 rules, 8-20 Resource name, 6-4 program version number, 8-21 Resource ownership, 6-2 Programs RFSTS% JSYS, 5-4, 5-17 multisection, 8-22 long form, 5-17, 5-18 Protection status-return block, 5-18 resource, 6-4 process status word, 5-17 Pseudo-ops short form, 5-17 ASCIZ, 1-6 RIN% JSYS, 3-24 POINT, 2-1 RIR% JSYS, 4-15, 8-11 PSOUT% JSYS, 2-3, 2-14 example, 4-15 example, 2-7 ROUT% JSYS, 3-24 PUSH instruction, 8-10 RSMAP% JSYS, 8-17 PUSHJ instruction, 8-2, 8-9, 8-10 information returned, 8-17 -Q- -Q- -S- Queue, 6-1, 6-2 -S- Quota, 7-1 receive, 7-1 SAVE% JSYS, 5-11 send, 7-1 Section changing, 8-2 -R- -R- creating, 8-14 nonzero, 8-14, 8-16 RDTTY% JSYS, 2-5, 2-9, 2-12, 2-14 zero, 8-3, 8-11 arguments, 2-9 Section handle, 8-17 control bits, 2-10 Section mapping, 8-12 editing functions, 2-9 file, 3-28 example, 2-13 file to process, 8-12 Reading a byte, 2-8 process, 8-13 Reading a number, 2-4 Sections, 8-2 Reading a string, 2-9 Send quota, 7-1 Reading from a file Sending a packet, 7-7 summary, 3-40 SEVEC% JSYS, 8-16 Receive quota, 7-1 SFM instruction, 8-9 Receiving a packet, 7-9 SFORK% JSYS, 5-4, 5-15 Referencing a file, 3-3 arguments, 5-15 Releasing a resource, 6-12 SFRKV% JSYS, 5-16 RESET% JSYS, 2-8, 5-21, 7-5 Sharer groups, 6-17 example, 2-7 use of, 6-17, 6-18 Resource, 6-1 Sharing files, 3-2, 6-1 level number, 6-4 Sharing pages, 5-19 obtaining information about, Sharing resources, 6-1, 6-17 6-14 Short form GTJFN%, 3-4 ownership, 6-2, 6-17 examples, 3-11 pooled, 6-11 SIN% JSYS, 3-22 protection, 6-4 arguments, 3-22 releasing a, 6-12 SIR% JSYS, 4-6, 4-11, 5-4, 8-11 requesting use of, 6-6 arguments, 4-6 sharing, 6-1, 6-17 SKPIR% JSYS, 4-14 Index-8 SMAP% JSYS, 3-28, 8-12 Strings (Cont.) arguments, 3-29, 8-13, 8-14, text, 2-1 8-15 transferring, 3-22 flag bits, 3-29 example, 3-23 Software interrupt, 1-6, 4-10, Structure 5-19 process, 1-6 channel assignments, 4-4 Superior process, 1-6, 5-1 channels and priorities, 4-4 communicating with inferior, disabling, 4-16 5-10 dismissing, 4-11 INFO, 7-1, 7-5, 7-6, 7-7, example, 4-18 7-9, 7-12 panic channel, 4-5, 4-10, 4-11 functions and arguments, 7-13 priority level, 4-11 requests, 7-12 priority levels, 4-4 format, 7-13 process communication, 5-4 responses, 7-14 processing, 4-10 INFO responses, 7-15 service routines, 4-6 -T- tables, 4-6 -T- Software interrupt system, 1-6, 4-1, 5-16 Table enabling, 4-9 channel (CHNTAB), 4-7 operational sequence, 4-2 priority level (LEVTAB), 4-8 summary, 4-17 software interrupt, 4-6 Source designator, 3-20 Terminal SOUT% JSYS, 3-22, 3-23 input, 2-1 arguments, 3-23 output, 2-1 SPJFN% JSYS, 2-2 Terminal codes SSAVE% JSYS, 5-11 deassigning, 4-17 Stack Terminal interrupts, 4-12 address, 8-10 codes, 4-12 global, 8-10 deferred mode, 4-14 pointer, 8-10 generating, 4-13 register, 8-10 immediate mode, 4-14 Stack instructions, 8-10 Terminating inferior process, ADJSP, 8-10 5-16 POP, 8-10 Text strings, 2-1 POPJ, 8-10 TMSG macro, 2-4 PUSH, 8-10 example, 2-7 PUSHJ, 8-10 Transferring bytes, 3-21 Standard file specification, 3-3 Transferring data, 3-19 Starting a process, 8-16 Transferring strings, 3-22 Starting inferior process, 5-15 example, 3-23 Status word Trap process, 5-17 illegal instruction, 1-4 Status-return block, 5-18 Two-word global byte pointer, 2-2, STIW% JSYS, 4-14 8-10 String -U- printing a, 2-3 -U- reading a, 2-9 Strings Universal device designator, 8-11 ASCII, 2-1, 3-21 Unmapping ASCIZ, 2-1, 3-21 process page, 3-28 Index-9 Unmapping (Cont.) XCT instruction, 8-9 process section, 8-15 XGTPW% JSYS, 8-19 arguments, 8-19 -V- -V- XGVEC% JSYS, 8-19 XHLLI instruction, 8-8, 8-9 Vector XJEN instruction, 8-9 entry, 8-16 XJRST instruction, 8-2 Virtual address space, 8-1 XJRSTF instruction, 8-2, 8-9 Virtual space, 1-6 XMOVEI instruction, 8-8, 8-20 XPCW instruction, 8-9 -W- -W- XRIR% JSYS, 4-15, 8-12 arguments, 4-15 WFORK% JSYS, 5-4, 5-16 XRMAP% JSYS, 8-18 Writing a byte, 2-8 arguments, 8-18 Writing a number, 2-5 XSFRK% JSYS, 5-16, 8-16 Writing to a file arguments, 8-16 summary, 3-40 XSIR% JSYS, 4-6, 4-11, 4-17, 8-12 arguments, 4-7 -X- -X- XSVEC% JSYS, 8-16 arguments, 8-16 XBLT instruction, 8-9 Index-10