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