TOPS-20 Monitor Calls Reference Manual | | | Electronically Distributed | | | | This manual describes all the monitor calls that | exist in the TOPS-20 operating system. For easy | reference, the monitor call descriptions are | arranged alphabetically and presented concisely. | This manual supercedes the TOPS-20 Monitor Calls | Reference Manual published in June, 1988. The | part number for that manual, AA-FV52B-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, 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 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 1 REFERENCES . . . . . . . . . . . . . . . . . . . . iv 2 OBSOLETE JSYSS . . . . . . . . . . . . . . . . . . iv 3 CONVENTIONS USED IN THIS MANUAL . . . . . . . . . . v 3.1 Number Bases . . . . . . . . . . . . . . . . . . . v 3.2 Abbreviations . . . . . . . . . . . . . . . . . . v 3.3 Symbols . . . . . . . . . . . . . . . . . . . . vi 3.4 Unimplemented Features . . . . . . . . . . . . . vi CHAPTER 1 INTRODUCTION 1.1 CALLING CONVENTIONS . . . . . . . . . . . . . . . 1-2 1.2 MONITOR CALL ARGUMENTS . . . . . . . . . . . . . . 1-2 1.2.1 Addresses . . . . . . . . . . . . . . . . . . . 1-3 1.2.2 Page Numbers . . . . . . . . . . . . . . . . . . 1-4 1.2.3 Section Numbers . . . . . . . . . . . . . . . . 1-4 1.2.4 Byte Pointers . . . . . . . . . . . . . . . . . 1-4 1.2.5 File Handles and File Designators . . . . . . . 1-6 1.2.6 Source/Destination Designators . . . . . . . . . 1-6 1.2.6.1 File Designator . . . . . . . . . . . . . . . 1-8 1.2.6.2 Byte Pointers and ASCII Strings . . . . . . . 1-8 1.2.6.3 Special Designators . . . . . . . . . . . . . 1-9 1.2.6.4 Numeric Designators . . . . . . . . . . . . . 1-9 1.2.7 Device Designator . . . . . . . . . . . . . . 1-10 1.2.7.1 Restrictions for Extended Addressing . . . . 1-10 1.2.8 Process Handles . . . . . . . . . . . . . . . 1-10 1.2.8.1 Process/File Handle . . . . . . . . . . . . 1-11 1.3 SYSTEM DATE AND TIME . . . . . . . . . . . . . . 1-11 1.4 PROCESSING ERRORS . . . . . . . . . . . . . . . 1-12 CHAPTER 2 FUNCTIONAL ORGANIZATION OF MONITOR CALLS 2.1 ACCOUNTING FUNCTIONS . . . . . . . . . . . . . . . 2-1 2.2 REFERENCING FILES . . . . . . . . . . . . . . . . 2-1 2.2.1 File Specifications . . . . . . . . . . . . . . 2-1 2.2.2 Logical Names . . . . . . . . . . . . . . . . . 2-3 2.2.3 File Handles . . . . . . . . . . . . . . . . . . 2-3 2.2.4 File References . . . . . . . . . . . . . . . . 2-5 2.2.4.1 Files and Devices . . . . . . . . . . . . . . 2-6 2.2.5 Sample Program . . . . . . . . . . . . . . . . . 2-6 2.2.6 File Access . . . . . . . . . . . . . . . . . . 2-9 2.2.7 Directory Access . . . . . . . . . . . . . . . 2-10 2.2.8 File Descriptor Block . . . . . . . . . . . . 2-11 2.2.9 Primary Input and Output Files . . . . . . . . 2-22 2.2.10 Methods of Data Transfer . . . . . . . . . . . 2-22 2.2.11 File Byte Count . . . . . . . . . . . . . . . 2-22 2.2.12 EOF Limit . . . . . . . . . . . . . . . . . . 2-23 2.2.13 Input/Output Errors . . . . . . . . . . . . . 2-23 2.2.13.1 Testing for End-of-File . . . . . . . . . . 2-24 2.3 OBTAINING INFORMATION . . . . . . . . . . . . . 2-26 2.3.1 Error Mnemonics and Message Strings . . . . . 2-26 2.3.2 System Tables . . . . . . . . . . . . . . . . 2-27 2.4 COMMUNICATING WITH DEVICES . . . . . . . . . . . 2-34 2.4.1 Physical Card Reader (PCDR:) . . . . . . . . . 2-36 2.4.2 Spooled Card Reader (CDR:) . . . . . . . . . . 2-37 2.4.3 Physical Card Punch (PCDP:) . . . . . . . . . 2-37 2.4.4 Spooled Card Punch (CDP:) . . . . . . . . . . 2-38 2.4.5 Physical Line Printer (PLPT:) . . . . . . . . 2-38 2.4.5.1 PLPT: Status Bits . . . . . . . . . . . . . 2-40 2.4.6 Spooled Line Printer (LPT:) . . . . . . . . . 2-41 2.4.7 Physical Magnetic Tape (MTA:) . . . . . . . . 2-42 2.4.7.1 Buffered I/O . . . . . . . . . . . . . . . . 2-42 2.4.7.2 Unbuffered I/O . . . . . . . . . . . . . . . 2-44 2.4.7.3 Magnetic Tape Status . . . . . . . . . . . . 2-44 2.4.7.4 Reading a Tape in the Reverse Direction . . 2-45 2.4.7.5 Hardware Data Modes . . . . . . . . . . . . 2-45 2.4.8 Logical Magnetic Tape (MT:) . . . . . . . . . 2-48 2.4.9 Terminal (TTY:) . . . . . . . . . . . . . . . 2-48 2.4.9.1 JFN Mode Word . . . . . . . . . . . . . . . 2-49 2.4.9.2 Control Character Output Control . . . . . . 2-52 2.4.9.3 Character Set . . . . . . . . . . . . . . . 2-52 2.4.9.4 Terminal Characteristics Control . . . . . . 2-55 2.4.9.5 Terminal Linking . . . . . . . . . . . . . . 2-58 2.4.9.6 Terminal Advising . . . . . . . . . . . . . 2-58 2.4.10 Transmission Control Protocol (TCP:) . . . . . 2-58 2.4.10.1 GTJFN JSYS . . . . . . . . . . . . . . . . . 2-58 2.4.10.2 OPENF JSYS . . . . . . . . . . . . . . . . . 2-59 2.4.10.3 Other JSYSs . . . . . . . . . . . . . . . . 2-60 2.5 SOFTWARE DATA MODES . . . . . . . . . . . . . . 2-61 2.6 SOFTWARE INTERRUPT SYSTEM . . . . . . . . . . . 2-64 2.6.1 Software Interrupt Channels . . . . . . . . . 2-64 2.6.2 Software Interrupt Priority Levels . . . . . . 2-66 2.6.3 Software Interrupt Tables . . . . . . . . . . 2-66 2.6.4 Terminating Conditions . . . . . . . . . . . . 2-67 2.6.5 Panic Channels . . . . . . . . . . . . . . . . 2-67 2.6.6 Terminal Interrupts . . . . . . . . . . . . . 2-67 2.6.6.1 Terminal Interrupt Modes . . . . . . . . . . 2-70 2.6.7 Dismissing an Interrupt . . . . . . . . . . . 2-70 2.7 PROCESS CAPABILITIES . . . . . . . . . . . . . . 2-72 2.7.1 Assigned Capabilities . . . . . . . . . . . . 2-72 2.7.2 Access Control . . . . . . . . . . . . . . . . 2-74 2.7.3 Processes and Scheduling . . . . . . . . . . . 2-76 2.7.3.1 Process Freezing . . . . . . . . . . . . . . 2-76 2.7.3.2 Execute-Only Files and Execute-Only Processes 2-78 2.8 SAVE FILES . . . . . . . . . . . . . . . . . . . 2-80 2.8.1 Format for Nonsharable Save Files . . . . . . 2-80 2.8.2 Format of Sharable Save Files . . . . . . . . 2-81 2.8.3 Entry Vector . . . . . . . . . . . . . . . . . 2-84 2.8.4 Program Data Vector . . . . . . . . . . . . . 2-85 2.9 INPUT/OUTPUT CONVERSION . . . . . . . . . . . . 2-86 2.9.1 Floating Output Format Control . . . . . . . . 2-86 2.9.1.1 Free Format . . . . . . . . . . . . . . . . 2-86 2.9.1.2 General Format Control . . . . . . . . . . . 2-87 2.9.2 Date And Time Conversion Monitor Calls . . . . 2-89 2.10 ARCHIVE/VIRTUAL DISK SYSTEM . . . . . . . . . . 2-92 2.11 PRIVILEGED MONITOR CALLS . . . . . . . . . . . . 2-94 CHAPTER 3 TOPS-20 MONITOR CALLS 3.1 ACCES JSYS 552 . . . . . . . . . . . . . . . . 3-1 3.2 ADBRK JSYS 570 . . . . . . . . . . . . . . . . 3-3 3.3 AIC JSYS 131 . . . . . . . . . . . . . . . . . 3-7 3.4 ALLOC JSYS 520 . . . . . . . . . . . . . . . . 3-8 3.5 ARCF JSYS 247 . . . . . . . . . . . . . . . . . 3-9 3.6 ASND JSYS 70 . . . . . . . . . . . . . . . . 3-13 3.7 ASNIQ% JSYS 756 . . . . . . . . . . . . . . . 3-13 3.8 ASNSQ JSYS 752 . . . . . . . . . . . . . . . 3-14 3.9 ATACH JSYS 116 . . . . . . . . . . . . . . . 3-15 3.10 ATI JSYS 137 . . . . . . . . . . . . . . . . 3-17 3.11 ATNVT JSYS 274 . . . . . . . . . . . . . . . 3-17 3.12 BIN JSYS 50 . . . . . . . . . . . . . . . . . 3-18 3.13 BKJFN JSYS 42 . . . . . . . . . . . . . . . . 3-19 3.14 BOOT JSYS 562 . . . . . . . . . . . . . . . . 3-19 3.15 BOUT JSYS 51 . . . . . . . . . . . . . . . . 3-25 3.16 CACCT JSYS 4 . . . . . . . . . . . . . . . . 3-25 3.17 CFIBF JSYS 100 . . . . . . . . . . . . . . . 3-26 3.18 CFOBF JSYS 101 . . . . . . . . . . . . . . . 3-27 3.19 CFORK JSYS 152 . . . . . . . . . . . . . . . 3-27 3.20 CHFDB JSYS 64 . . . . . . . . . . . . . . . . 3-29 3.21 CHKAC JSYS 521 . . . . . . . . . . . . . . . 3-30 3.22 CIS JSYS 141 . . . . . . . . . . . . . . . . 3-31 3.23 CLOSF JSYS 22 . . . . . . . . . . . . . . . . 3-31 3.24 CLZFF JSYS 34 . . . . . . . . . . . . . . . . 3-33 3.25 CNFIG% JSYS 627 . . . . . . . . . . . . . . . 3-34 3.26 COMND JSYS 544 . . . . . . . . . . . . . . . 3-37 3.27 CRDIR JSYS 240 . . . . . . . . . . . . . . . 3-61 3.28 CRJOB JSYS 2 . . . . . . . . . . . . . . . . 3-68 3.29 CRLNM JSYS 502 . . . . . . . . . . . . . . . 3-75 3.30 DEBRK JSYS 136 . . . . . . . . . . . . . . . 3-76 3.31 DELDF JSYS 67 . . . . . . . . . . . . . . . . 3-76 3.32 DELF JSYS 26 . . . . . . . . . . . . . . . . 3-78 3.33 DELNF JSYS 317 . . . . . . . . . . . . . . . 3-79 3.34 DEQ JSYS 514 . . . . . . . . . . . . . . . . 3-80 3.35 DEVST JSYS 121 . . . . . . . . . . . . . . . 3-82 3.36 DFIN JSYS 234 . . . . . . . . . . . . . . . . 3-82 3.37 DFOUT JSYS 235 . . . . . . . . . . . . . . . 3-83 3.38 DIAG JSYS 530 . . . . . . . . . . . . . . . . 3-84 3.39 DIBE JSYS 212 . . . . . . . . . . . . . . . . 3-91 3.40 DIC JSYS 133 . . . . . . . . . . . . . . . . 3-92 3.41 DIR JSYS 130 . . . . . . . . . . . . . . . . 3-92 3.42 DIRST JSYS 41 . . . . . . . . . . . . . . . . 3-93 3.43 DISMS JSYS 167 . . . . . . . . . . . . . . . 3-94 3.44 DOB% JSYS 635 . . . . . . . . . . . . . . . . 3-94 3.45 DOBE JSYS 104 . . . . . . . . . . . . . . . . 3-97 3.46 DSKAS JSYS 244 . . . . . . . . . . . . . . . 3-97 3.47 DSKOP JSYS 242 . . . . . . . . . . . . . . . 3-98 3.48 DTACH JSYS 115 . . . . . . . . . . . . . . . 3-101 3.49 DTI JSYS 140 . . . . . . . . . . . . . . . . 3-101 3.50 DUMPI JSYS 65 . . . . . . . . . . . . . . . . 3-102 3.51 DUMPO JSYS 66 . . . . . . . . . . . . . . . . 3-103 3.52 DVCHR JSYS 117 . . . . . . . . . . . . . . . 3-105 3.53 EIR JSYS 126 . . . . . . . . . . . . . . . . 3-106 3.54 ENQ JSYS 513 . . . . . . . . . . . . . . . . 3-106 3.55 ENQC JSYS 515 . . . . . . . . . . . . . . . . 3-113 3.56 EPCAP JSYS 151 . . . . . . . . . . . . . . . 3-117 3.57 ERSTR JSYS 11 . . . . . . . . . . . . . . . . 3-118 3.58 ESOUT JSYS 313 . . . . . . . . . . . . . . . 3-118 3.59 FFFFP JSYS 31 . . . . . . . . . . . . . . . . 3-119 3.60 FFORK JSYS 154 . . . . . . . . . . . . . . . 3-119 3.61 FFUFP JSYS 211 . . . . . . . . . . . . . . . 3-120 3.62 FLIN JSYS 232 . . . . . . . . . . . . . . . . 3-120 3.63 FLOUT JSYS 233 . . . . . . . . . . . . . . . 3-121 3.64 GACCT JSYS 546 . . . . . . . . . . . . . . . 3-122 3.65 GACTF JSYS 37 . . . . . . . . . . . . . . . . 3-122 3.66 GCVEC JSYS 300 . . . . . . . . . . . . . . . 3-123 3.67 GDSKC JSYS 214 . . . . . . . . . . . . . . . 3-123 3.68 GDSTS JSYS 145 . . . . . . . . . . . . . . . 3-124 3.69 GDVEC JSYS 542 . . . . . . . . . . . . . . . 3-125 3.70 GET JSYS 200 . . . . . . . . . . . . . . . . 3-125 3.71 GETAB JSYS 10 . . . . . . . . . . . . . . . . 3-128 3.72 GETER JSYS 12 . . . . . . . . . . . . . . . . 3-129 3.73 GETJI JSYS 507 . . . . . . . . . . . . . . . 3-129 3.74 GETNM JSYS 177 . . . . . . . . . . . . . . . 3-131 3.75 GETOK% JSYS 574 . . . . . . . . . . . . . . . 3-132 3.76 GEVEC JSYS 205 . . . . . . . . . . . . . . . 3-142 3.77 GFRKH JSYS 164 . . . . . . . . . . . . . . . 3-142 3.78 GFRKS JSYS 166 . . . . . . . . . . . . . . . 3-143 3.79 GFUST JSYS 550 . . . . . . . . . . . . . . . 3-145 3.80 GIVOK% JSYS 576 . . . . . . . . . . . . . . . 3-146 3.81 GJINF JSYS 13 . . . . . . . . . . . . . . . . 3-146 3.82 GNJFN JSYS 17 . . . . . . . . . . . . . . . . 3-147 3.83 GPJFN JSYS 206 . . . . . . . . . . . . . . . 3-148 3.84 GTAD JSYS 227 . . . . . . . . . . . . . . . . 3-148 3.85 GTDAL JSYS 305 . . . . . . . . . . . . . . . 3-149 3.86 GTDIR JSYS 241 . . . . . . . . . . . . . . . 3-149 3.87 GTFDB JSYS 63 . . . . . . . . . . . . . . . . 3-151 3.88 GTHST% JSYS 273 . . . . . . . . . . . . . . . 3-151 3.89 GTJFN JSYS 20 (SHORT FORM) . . . . . . . . . 3-159 3.90 GTJFN JSYS 20 (LONG FORM) . . . . . . . . . 3-167 3.91 GTRPI JSYS 172 . . . . . . . . . . . . . . . 3-175 3.92 GTRPW JSYS 171 . . . . . . . . . . . . . . . 3-176 3.93 GTSTS JSYS 24 . . . . . . . . . . . . . . . . 3-177 3.94 GTTYP JSYS 303 . . . . . . . . . . . . . . . 3-178 3.95 HALTF JSYS 170 . . . . . . . . . . . . . . . 3-178 3.96 HFORK JSYS 162 . . . . . . . . . . . . . . . 3-179 3.97 HPTIM JSYS 501 . . . . . . . . . . . . . . . 3-179 3.98 HSYS JSYS 307 . . . . . . . . . . . . . . . . 3-180 3.99 IDCNV JSYS 223 . . . . . . . . . . . . . . . 3-181 3.100 IDTIM JSYS 221 . . . . . . . . . . . . . . . 3-182 3.101 IDTNC JSYS 231 . . . . . . . . . . . . . . . 3-184 3.102 IIC JSYS 132 . . . . . . . . . . . . . . . . 3-186 3.103 INFO% JSYS 633 . . . . . . . . . . . . . . . 3-186 3.104 INLNM JSYS 503 . . . . . . . . . . . . . . . 3-195 3.105 IPOPR% JSYS 760 . . . . . . . . . . . . . . . 3-196 3.106 JFNS JSYS 30 . . . . . . . . . . . . . . . . 3-197 3.107 KFORK JSYS 153 . . . . . . . . . . . . . . . 3-200 3.108 LATOP% JSYS 631 . . . . . . . . . . . . . . . 3-200 3.109 LGOUT JSYS 3 . . . . . . . . . . . . . . . . 3-215 3.110 LLMOP% JSYS 624 . . . . . . . . . . . . . . . 3-216 3.111 LNMST JSYS 504 . . . . . . . . . . . . . . . 3-224 3.112 LOGIN JSYS 1 . . . . . . . . . . . . . . . . 3-225 3.113 LPINI JSYS 547 . . . . . . . . . . . . . . . 3-226 3.114 MDDT% JSYS 777 . . . . . . . . . . . . . . . 3-227 3.115 METER% JSYS 766 . . . . . . . . . . . . . . . 3-227 3.116 MRECV JSYS 511 . . . . . . . . . . . . . . . 3-229 3.117 MSEND JSYS 510 . . . . . . . . . . . . . . . 3-231 3.118 MSFRK JSYS 312 . . . . . . . . . . . . . . . 3-235 3.119 MSTR JSYS 555 . . . . . . . . . . . . . . . . 3-236 3.120 MTALN JSYS 774 . . . . . . . . . . . . . . . 3-257 3.121 MTOPR JSYS 77 . . . . . . . . . . . . . . . . 3-257 3.122 MTU% JSYS 600 . . . . . . . . . . . . . . . . 3-293 3.123 MUTIL JSYS 512 . . . . . . . . . . . . . . . 3-295 3.124 NI% JSYS 630 . . . . . . . . . . . . . . . . 3-302 3.125 NIN JSYS 225 . . . . . . . . . . . . . . . . 3-320 3.126 NODE JSYS 567 . . . . . . . . . . . . . . . . 3-321 3.127 NOUT JSYS 224 . . . . . . . . . . . . . . . . 3-329 3.128 NTINF% JSYS 632 . . . . . . . . . . . . . . . 3-330 3.129 NTMAN% JSYS 604 . . . . . . . . . . . . . . . 3-332 3.130 ODCNV JSYS 222 . . . . . . . . . . . . . . . 3-334 3.131 ODTIM JSYS 220 . . . . . . . . . . . . . . . 3-336 3.132 ODTNC JSYS 230 . . . . . . . . . . . . . . . 3-338 3.133 OPENF JSYS 21 . . . . . . . . . . . . . . . . 3-339 3.134 PBIN JSYS 73 . . . . . . . . . . . . . . . . 3-344 3.135 PBOUT JSYS 74 . . . . . . . . . . . . . . . . 3-345 3.136 PDVOP% JSYS 603 . . . . . . . . . . . . . . . 3-345 3.137 PEEK JSYS 311 . . . . . . . . . . . . . . . . 3-348 3.138 PLOCK JSYS 561 . . . . . . . . . . . . . . . 3-349 3.139 PMAP JSYS 56 . . . . . . . . . . . . . . . . 3-350 3.140 PMCTL JSYS 560 . . . . . . . . . . . . . . . 3-355 3.141 PPNST JSYS 557 . . . . . . . . . . . . . . . 3-358 3.142 PRARG JSYS 545 . . . . . . . . . . . . . . . 3-359 3.143 PSOUT JSYS 76 . . . . . . . . . . . . . . . . 3-361 3.144 QUEUE% JSYS 615 . . . . . . . . . . . . . . . 3-361 3.145 RCDIR JSYS 553 . . . . . . . . . . . . . . . 3-368 3.146 RCM JSYS 134 . . . . . . . . . . . . . . . . 3-372 3.147 RCUSR JSYS 554 . . . . . . . . . . . . . . . 3-372 3.148 RCVIM JSYS 751 . . . . . . . . . . . . . . . 3-374 3.149 RCVIN% JSYS 755 . . . . . . . . . . . . . . . 3-375 3.150 RCVOK% JSYS 575 . . . . . . . . . . . . . . . 3-376 3.151 RDTTY JSYS 523 . . . . . . . . . . . . . . . 3-377 3.152 RELD JSYS 71 . . . . . . . . . . . . . . . . 3-380 3.153 RELIQ% JSYS 757 . . . . . . . . . . . . . . . 3-380 3.154 RELSQ JSYS 753 . . . . . . . . . . . . . . . 3-381 3.155 RESET JSYS 147 . . . . . . . . . . . . . . . 3-381 3.156 RFACS JSYS 161 . . . . . . . . . . . . . . . 3-382 3.157 RFBSZ JSYS 45 . . . . . . . . . . . . . . . . 3-383 3.158 RFCOC JSYS 112 . . . . . . . . . . . . . . . 3-383 3.159 RFMOD JSYS 107 . . . . . . . . . . . . . . . 3-384 3.160 RFORK JSYS 155 . . . . . . . . . . . . . . . 3-385 3.161 RFPOS JSYS 111 . . . . . . . . . . . . . . . 3-385 3.162 RFPTR JSYS 43 . . . . . . . . . . . . . . . . 3-386 3.163 RFRKH JSYS 165 . . . . . . . . . . . . . . . 3-386 3.164 RFSTS JSYS 156 . . . . . . . . . . . . . . . 3-387 3.165 RFTAD JSYS 533 . . . . . . . . . . . . . . . 3-390 3.166 RIN JSYS 54 . . . . . . . . . . . . . . . . . 3-391 3.167 RIR JSYS 144 . . . . . . . . . . . . . . . . 3-392 3.168 RIRCM JSYS 143 . . . . . . . . . . . . . . . 3-393 3.169 RLJFN JSYS 23 . . . . . . . . . . . . . . . . 3-393 3.170 RMAP JSYS 61 . . . . . . . . . . . . . . . . 3-394 3.171 RNAMF JSYS 35 . . . . . . . . . . . . . . . . 3-394 3.172 ROUT JSYS 55 . . . . . . . . . . . . . . . . 3-396 3.173 RPACS JSYS 57 . . . . . . . . . . . . . . . . 3-397 3.174 RPCAP JSYS 150 . . . . . . . . . . . . . . . 3-398 3.175 RSCAN JSYS 500 . . . . . . . . . . . . . . . 3-398 3.176 RSMAP% JSYS 610 . . . . . . . . . . . . . . . 3-400 3.177 RTFRK JSYS 322 . . . . . . . . . . . . . . . 3-401 3.178 RTIW JSYS 173 . . . . . . . . . . . . . . . . 3-402 3.179 RUNTM JSYS 15 . . . . . . . . . . . . . . . . 3-402 3.180 RWM JSYS 135 . . . . . . . . . . . . . . . . 3-403 3.181 RWSET JSYS 176 . . . . . . . . . . . . . . . 3-404 3.182 SACTF JSYS 62 . . . . . . . . . . . . . . . . 3-404 3.183 SAVE JSYS 202 . . . . . . . . . . . . . . . . 3-405 3.184 SCS% JSYS 622 . . . . . . . . . . . . . . . . 3-406 3.185 SCTTY JSYS 324 . . . . . . . . . . . . . . . 3-423 3.186 SCVEC JSYS 301 . . . . . . . . . . . . . . . 3-424 3.187 SDSTS JSYS 146 . . . . . . . . . . . . . . . 3-426 3.188 SDVEC JSYS 543 . . . . . . . . . . . . . . . 3-426 3.189 SETER JSYS 336 . . . . . . . . . . . . . . . 3-427 3.190 SETJB JSYS 541 . . . . . . . . . . . . . . . 3-428 3.191 SETNM JSYS 210 . . . . . . . . . . . . . . . 3-431 3.192 SETSN JSYS 506 . . . . . . . . . . . . . . . 3-431 3.193 SEVEC JSYS 204 . . . . . . . . . . . . . . . 3-431 3.194 SFACS JSYS 160 . . . . . . . . . . . . . . . 3-432 3.195 SFBSZ JSYS 46 . . . . . . . . . . . . . . . . 3-433 3.196 SFCOC JSYS 113 . . . . . . . . . . . . . . . 3-433 3.197 SFMOD JSYS 110 . . . . . . . . . . . . . . . 3-434 3.198 SFORK JSYS 157 . . . . . . . . . . . . . . . 3-435 3.199 SFPOS JSYS 526 . . . . . . . . . . . . . . . 3-436 3.200 SFPTR JSYS 27 . . . . . . . . . . . . . . . . 3-436 3.201 SFRKV JSYS 201 . . . . . . . . . . . . . . . 3-438 3.202 SFTAD JSYS 534 . . . . . . . . . . . . . . . 3-439 3.203 SFUST JSYS 551 . . . . . . . . . . . . . . . 3-441 3.204 SIBE JSYS 102 . . . . . . . . . . . . . . . . 3-442 3.205 SIN JSYS 52 . . . . . . . . . . . . . . . . . 3-443 3.206 SINR JSYS 531 . . . . . . . . . . . . . . . . 3-444 3.207 SIR JSYS 125 . . . . . . . . . . . . . . . . 3-446 3.208 SIRCM JSYS 142 . . . . . . . . . . . . . . . 3-447 3.209 SIZEF JSYS 36 . . . . . . . . . . . . . . . . 3-447 3.210 SJPRI JSYS 245 . . . . . . . . . . . . . . . 3-448 3.211 SKED% JSYS 577 . . . . . . . . . . . . . . . 3-449 3.212 SKPIR JSYS 127 . . . . . . . . . . . . . . . 3-455 3.213 SMAP% JSYS 767 . . . . . . . . . . . . . . . 3-455 3.214 SMON JSYS 6 . . . . . . . . . . . . . . . . . 3-459 3.215 SNDIM JSYS 750 . . . . . . . . . . . . . . . 3-464 3.216 SNDIN% JSYS 754 . . . . . . . . . . . . . . . 3-465 3.217 SNOOP JSYS 516 . . . . . . . . . . . . . . . 3-466 3.218 SOBE JSYS 103 . . . . . . . . . . . . . . . . 3-469 3.219 SOBF JSYS 175 . . . . . . . . . . . . . . . . 3-470 3.220 SOUT JSYS 53 . . . . . . . . . . . . . . . . 3-470 3.221 SOUTR JSYS 532 . . . . . . . . . . . . . . . 3-472 3.222 SPACS JSYS 60 . . . . . . . . . . . . . . . . 3-473 3.223 SPJFN JSYS 207 . . . . . . . . . . . . . . . 3-474 3.224 SPLFK JSYS 314 . . . . . . . . . . . . . . . 3-475 3.225 SPOOL JSYS 517 . . . . . . . . . . . . . . . 3-477 3.226 SPRIW JSYS 243 . . . . . . . . . . . . . . . 3-479 3.227 SSAVE JSYS 203 . . . . . . . . . . . . . . . 3-480 3.228 STAD JSYS 226 . . . . . . . . . . . . . . . . 3-482 3.229 STCMP JSYS 540 . . . . . . . . . . . . . . . 3-482 3.230 STDEV JSYS 120 . . . . . . . . . . . . . . . 3-483 3.231 STI JSYS 114 . . . . . . . . . . . . . . . . 3-484 3.232 STIW JSYS 174 . . . . . . . . . . . . . . . . 3-485 3.233 STO JSYS 246 . . . . . . . . . . . . . . . . 3-486 3.234 STPAR JSYS 217 . . . . . . . . . . . . . . . 3-487 3.235 STPPN JSYS 556 . . . . . . . . . . . . . . . 3-488 3.236 STSTS JSYS 25 . . . . . . . . . . . . . . . . 3-489 3.237 STTYP JSYS 302 . . . . . . . . . . . . . . . 3-490 3.238 SWJFN JSYS 47 . . . . . . . . . . . . . . . . 3-490 3.239 SWTRP% JSYS 573 . . . . . . . . . . . . . . . 3-491 3.240 SYERR JSYS 527 . . . . . . . . . . . . . . . 3-492 3.241 SYSGT JSYS 16 . . . . . . . . . . . . . . . . 3-493 3.242 TBADD JSYS 536 . . . . . . . . . . . . . . . 3-493 3.243 TBDEL JSYS 535 . . . . . . . . . . . . . . . 3-494 3.244 TBLUK JSYS 537 . . . . . . . . . . . . . . . 3-495 3.245 TCOPR% JSYS 761 . . . . . . . . . . . . . . . 3-497 3.246 TEXTI JSYS 524 . . . . . . . . . . . . . . . 3-499 3.247 TFORK JSYS 321 . . . . . . . . . . . . . . . 3-504 3.248 THIBR JSYS 770 . . . . . . . . . . . . . . . 3-507 3.249 TIME JSYS 14 . . . . . . . . . . . . . . . . 3-507 3.250 TIMER JSYS 522 . . . . . . . . . . . . . . . 3-507 3.251 TLINK JSYS 216 . . . . . . . . . . . . . . . 3-509 3.252 TMON JSYS 7 . . . . . . . . . . . . . . . . . 3-511 3.253 TTMSG JSYS 775 . . . . . . . . . . . . . . . 3-514 3.254 TWAKE JSYS 771 . . . . . . . . . . . . . . . 3-515 3.255 UFPGS JSYS 525 . . . . . . . . . . . . . . . 3-516 3.256 USAGE JSYS 564 . . . . . . . . . . . . . . . 3-516 3.257 USRIO JSYS 310 . . . . . . . . . . . . . . . 3-520 3.258 UTEST JSYS 563 . . . . . . . . . . . . . . . 3-520 3.259 UTFRK JSYS 323 . . . . . . . . . . . . . . . 3-521 3.260 VACCT JSYS 566 . . . . . . . . . . . . . . . 3-523 3.261 WAIT JSYS 306 . . . . . . . . . . . . . . . . 3-523 3.262 WFORK JSYS 163 . . . . . . . . . . . . . . . 3-524 3.263 WILD% JSYS 565 . . . . . . . . . . . . . . . 3-524 3.264 WSMGR% JSYS 623 . . . . . . . . . . . . . . . 3-526 3.265 XGSEV% JSYS 614 . . . . . . . . . . . . . . . 3-527 3.266 XGTPW% JSYS 612 . . . . . . . . . . . . . . . 3-528 3.267 XGVEC% JSYS 606 . . . . . . . . . . . . . . . 3-529 3.268 XPEEK% JSYS 626 . . . . . . . . . . . . . . . 3-529 3.269 XRIR% JSYS 601 . . . . . . . . . . . . . . . 3-531 3.270 XRMAP% JSYS 611 . . . . . . . . . . . . . . . 3-531 3.271 XSFRK% JSYS 605 . . . . . . . . . . . . . . . 3-533 3.272 XSIR% JSYS 602 . . . . . . . . . . . . . . . 3-533 3.273 XSSEV% JSYS 613 . . . . . . . . . . . . . . . 3-534 3.274 XSVEC% JSYS 607 . . . . . . . . . . . . . . . 3-535 APPENDIX A ASCII, SIXBIT, AND EBCDIC COLLATING SEQUENCES AND CONVERSIONS APPENDIX B TOPS-20 ERROR CODES AND MNEMONICS INDEX TABLES 1-1 P-Field Values for One-word Global Byte Pointers . 1-5 1-2 Source/Destination Designators . . . . . . . . . . 1-7 2-1 File Descriptor Block (FDB) . . . . . . . . . . 2-12 2-2 System Tables . . . . . . . . . . . . . . . . . 2-27 2-3 Device Types . . . . . . . . . . . . . . . . . . 2-35 2-4 PCDR: Status Bits . . . . . . . . . . . . . . . 2-36 2-5 PCDP: Status Bits . . . . . . . . . . . . . . . 2-37 2-6 PLPT: Control Characters . . . . . . . . . . . . 2-39 2-7 PLPT: Status Bits . . . . . . . . . . . . . . . 2-40 2-8 MTA: Status Bits . . . . . . . . . . . . . . . . 2-42 2-9 JFN Mode Word . . . . . . . . . . . . . . . . . 2-49 2-10 Wakeup Classes/CCOC Word Bits . . . . . . . . . 2-53 2-11 Terminal Characteristics . . . . . . . . . . . . 2-55 2-12 Software Interrupt Channels . . . . . . . . . . 2-65 2-13 Terminal Interrupt Codes . . . . . . . . . . . . 2-68 2-14 Process/Job Capabilities . . . . . . . . . . . . 2-72 2-15 Floating-Point Format Control . . . . . . . . . 2-87 2-16 Time Zones . . . . . . . . . . . . . . . . . . . 2-91 A-1 ASCII and SIXBIT Collating Sequence and Conversion to EBCDIC . . . . . . . . . . . . . . . . . . . . A-1 A-2 EBCDIC Collating Sequence and Conversion to ASCII A-4 PREFACE This manual is written for the assembly language programmer who is already familiar with TOPS-20 monitor calls. For an introductory _______ _______ discussion of some basic monitor calls, refer to the TOPS-20 Monitor _____ ______ _____ Calls User's Guide. Chapter 1 introduces the conventions to follow when using monitor calls, and describes the types of arguments used with the monitor calls. Chapter 2 presents the calls related to particular functions and tasks, such as using the software interrupt system. Chapter 3 contains, in alphabetical order, descriptions of all the monitor calls. Appendix A contains the EBCDIC, ASCII, and SIXBIT collating sequences, and conversions between these three character set representations. Appendix B contains a numeric list of error codes with their corresponding mnemonic, and an alphabetic list of mnemonics with their corresponding code and text string. iii 1 REFERENCES 1 REFERENCES The following publications are either referenced in this manual or are recommended as supplements to this manual: Referenced as Title _______ _______ _____ ______ _____ Monitor Calls User's Guide TOPS-20 Monitor Calls User's Guide _______ ______ _________ _____ System Administrator TOPS-20 System Manager's Guide ________ ________ __________ ________ TCP/IP Handbook Internet Protocol Transition Workbook Available from: Network Information Center SRI International Menlo Park, California 94025 _________ ______ _____ DECnet Manual DECnet-20 User's Guide _____ _________ _________ ______ Assembler Manual MACRO Assembler Reference Manual _______ ____ _________ ______ Link Manual TOPS-20 LINK Reference Manual _________________________ _________ Hardware Reference Manual DECsystem-10/DECSYSTEM-20 Processor _________ ______ Reference Manual _______ ________ _________ ______ Commands Reference Manual TOPS-20 Commands Reference Manual _______ ___ ______ _____ RMS Manual TOPS-20 RMS User's Guide _______________ _____ ______ SPEAR Manual TOPS-10/TOPS-20 SPEAR Manual _______ ______ _____ TOPS-20 User's Guide TOPS-20 User's Guide _______ __ _____ _ ____________ _____ Installation Guide TOPS-20 KL Model B Installation Guide _______ __________ ____________ Network Management Spec Network Management Architecture _____________ Specification 2 OBSOLETE JSYSS 2 OBSOLETE JSYSS The following JSYSs are obsolete as of version V6.1 of TOPS-20: CVHST CVSKT iv FLHST GTNCP 3 CONVENTIONS USED IN THIS MANUAL 3 CONVENTIONS USED IN THIS MANUAL 3.1 Number Bases 3.1 Number Bases Except where otherwise noted, numbers used in this manual, including those in the definition of a monitor call description, are octal. When indicated, bits in words are numbered in decimal with the leftmost bit of the word labeled B0 and the rightmost bit of the word labeled B35. 3.2 Abbreviations 3.2 Abbreviations The following abbreviations are used in this manual: B0, B1, ... Bit 0, bit 1, ... of the computer word nBm Field whose rightmost bit is m and whose value is n (5B2, for example). LH Left Half (B0-B17 of the word) RH Right Half (B18-B35 of the word) JFN Job File Number PSB Process Storage Block (a table containing all monitor data for the process) JSB Job Storage Block (a table containing all monitor data relevant to the job) CCOC words Control Character Output Control words (2 words containing 36 2-bit bytes that determine the way in which control characters are output. Refer to Section 2.4.9.2.) FDB File Descriptor Block (a table in a file that contains information about the file). Refer to Section 2.2.8. TCP/IP Transmission Control Protocol/Internet Protocol v 3.3 Symbols 3.3 Symbols The symbols used in this manual, including the names of the monitor calls, are defined in the system file MONSYM.MAC. A program that uses a monitor call or other symbol must include the statement SEARCH MONSYM before the first occurrence of a symbol. Failure to include this statement causes errors in the compilation of the program. 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 use these bits without knowledge of their exact position. Refer to the Monitor Calls User's Guide for more information on MACSYM macros. 3.4 Unimplemented Features 3.4 Unimplemented Features The MONSYM file contains symbol names for several monitor calls and bit positions that are not described in this manual. These features are not implemented in TOPS-20. If an unimplemented monitor call is used in a user program, it causes an illegal instruction interrupt unless followed by an ERJMP or ERCAL symbol. In this case, the ERJMP will be executed. It is recommended that unimplemented or undefined bit positions be zero to allow for future expansion. 6 CHAPTER 1 CHAPTER 1 INTRODUCTION INTRODUCTION _______ _______ _____ _________ ______ The TOPS-20 Monitor Calls Reference Manual describes every monitor call in the TOPS-20 system. Monitor calls for TCP/IP systems and DECnet systems are also described. TOPS-20 monitor calls invoke the TOPS-20 monitor by means of the JSYS instruction (op code 104). The UUO-type monitor calls (op codes 40-77) invoke the TOPS-10 compatibility package, which simulates the action of these UUO's in the TOPS-10 monitor. Programs written for TOPS-20 should use TOPS-20 monitor calls, not UUO's. For easy reference, monitor call descriptions in Chapter 3 are arranged alphabetically and presented concisely. This concise format begins with the monitor call name and numeric definition, followed by a brief description of the monitor call function. The calling sequence for the monitor call is next, indicated by statements in the format ACCEPTS IN ACn: description where n is an accumulator number. Following the list of accumulators and descriptions of their contents are statements of the form RETURNS +1: condition +2: condition These statements define where control returns, and under what conditions, after execution of the monitor call. The statement RETURNS+1: means that control returns to the memory location immediately following the calling location. The statement RETURNS+2: means that control returns to the second memory location after the calling location. Next, there is an optional description of the action taken by the monitor call. 1-1 INTRODUCTION INTRODUCTION 1.1 CALLING CONVENTIONS 1.1 CALLING CONVENTIONS Arguments for the monitor call are placed in accumulators (ACs), then the monitor call is executed. The first argument is in AC1, the second in AC2, and so forth. Many calls also require an argument block. This is a group of contiguous words of memory that contain additional arguments. If an argument block is required, an AC must contain a pointer to the argument block. See the description of the GTJFN% monitor call for an example of the use of argument blocks. In addition, arguments in an argument block can point to other argument blocks. These other argument blocks can, in turn, contain other groups of arguments. For an example of this way of passing many arguments to a monitor call, see the description of the GTJFN call in Chapter 3. (There are several exceptions to this convention; refer to the individual descriptions in Chapter 3.) Data returned by the execution of a monitor call is often returned in the ACs. If a call returns more data than can be held in four ACs, it returns the data to a data block. A pointer to the data block must be passed as an argument to the monitor call. Such a pointer can be passed in either an AC or an argument block. When using a monitor call in a program, end the name of the call with a percent (%) character. This convention helps avoid conflicts between monitor call names and symbols defined by your programs. In addition, this convention is required by monitor calls defined in TOPS-20 Version 4.0 or later. Although older calls do not require a percent character at the end of their names, they will accept one. 1.2 MONITOR CALL ARGUMENTS 1.2 MONITOR CALL ARGUMENTS A monitor call argument can be one of the following: o a word of data o the memory address word that contains data o a page number o a section number o a byte pointer o a file handle o a source (or destination) designator that defines where to obtain (or send) data 1-2 INTRODUCTION INTRODUCTION o a process handle o a file/process handle The following sections describe these arguments. 1.2.1 Addresses 1.2.1 Addresses On a DECSYSTEM-20, addresses can be one of two types: an 18-bit address, or a 30-bit address. TOPS-20 supports 30-bit addressing, but currently allows access to an address space of 32 (decimal) sections, each of which contains 256K words. Therefore, although a global address is said to be a 30-bit address, only the rightmost 23 bits are meaningful: five bits of section number and 18 bits of in-section address. An 18-bit address is called a local (section-relative) address. With such an address you can specify any word in a 256K-word section of memory, but you cannot also specify a section number. With a 30-bit, or global, address you can reference any word of any section of memory. (Refer to the Hardware Reference Manual for a description of global addresses.) TOPS-20 allows you to use 18-bit or 30-bit addresses. Some monitor calls require one kind, some the other; some calls accept either kind. Some monitor calls use only 18 bits to hold an address. These calls interpret 18-bit addresses as locations in the current section, the same section as that of the code being executed (the same section as the user PC.) To form an unambiguous global address, these calls add the section number of the PC to the section-relative address. Monitor calls that use an entire word for an address can accept either 18-bit or 30-bit addresses. If the address is 30 bits (the section number is not 0), it is a global address. If the address is 18 bits (the section number is 0), the monitor call acts in one of two ways. If the call existed in Release 4 or earlier, it interprets the address as a section-relative address, as stated above. But if the call is one of the extended-addressing calls (if the call starts with an X), the call interprets the zero in the section-number field as indicating section 0. It is sometimes desireable to specify addresses in section 0 when executing a JSYS from a nonzero section. The bit PM%EPN for PMAP%, and FH%EPN for JSYSs that accept fork handles, prevent the current section (the section in which the program is running) from being the target section for the monitor call's arguments. 1-3 INTRODUCTION INTRODUCTION 1.2.2 Page Numbers 1.2.2 Page Numbers A TOPS-20 page number can be 9 bits or 18 bits long. A page number can refer to either a page of memory, or a page of a disk file. The 9-bit number is called a section-relative page number. Such a page number can specify any page within a 256K-word section of memory, or any page within a 256K section of a file. (A file section is a unit of 512 pages within a file. The first page of each such section has a page number that is an integer multiple of 512.) The left half of a section-relative (18-bit) address can be considered to be a section-relative page number. If a monitor call uses only 9 bits of a word to hold a page number, the monitor considers that page to be within the current section. Most monitor calls that require page numbers as arguments use at least half of a word to contain the page number. Such calls allow you to specify an 18-bit, or global, page number. A global page number refers to both a section of memory and a page within that section. Page 23200, for example, is page 200 in section 23. 1.2.3 Section Numbers 1.2.3 Section Numbers A section number is five bits long. In a global address, a section number occupies bits 13 through 17. Because TOPS-20 supports 40 (octal) sections of memory, using section numbers larger than 37 causes an error. 1.2.4 Byte Pointers 1.2.4 Byte Pointers Monitor calls accept two kinds of byte pointers as arguments: one-word local byte pointers, and one-word global byte pointers. One-word local byte pointers work in all sections, but one-word global byte pointers cannot be used in section 0. The Hardware Reference Manual describes one-word local byte pointers in detail. The following paragraphs discuss one-word global byte pointers. Any monitor calls that accept source/destination designators (See Section 1.2.6.) also accept byte pointers, and the bytes can be from 1 to 36 bits long. SIN and SOUT are examples of such monitor calls. If a call cannot accept a source/destination designator, however, that call only accepts byte pointers that point to 7-bit bytes. Examples of such calls are CACCT and PSOUT. Note, however, that for historical reasons some monitor calls accept one-word global byte pointers that point to bytes of other lengths. 1-4 INTRODUCTION INTRODUCTION TOPS-20 monitor calls do not accept the two-word local byte pointers or the two-word global byte pointers described in the Hardware Reference Manual. Local byte pointers can only point to a byte in the current section. This is because they use 18 bits to hold the address of the byte. You can use indexing with local byte pointers, however, to point to a byte in another section of memory. If, for example, AC5 contains a 30-bit address, the following instruction generates an indexed local byte pointer in AC2. The pointer points to a byte in another section, the section of the address in AC5. MOVE 2,[POINT 7,0(5)] Use of indirect addressing with local byte pointers is discouraged. Global byte pointers use 30 bits to hold the address of the byte, thus they can point to a byte in any section of memory. One-word global byte pointers have the following format: ------------------------------------------------ | P | address | ------------------------------------------------ Table 1-1 shows how the KL-10 processor interprets the P field. Table 1-1: P-Field Values for One-word Global Byte Pointers Table 1-1: P-Field Values for One-word Global Byte Pointers ______________________________________________________________________ P (octal) Byte Size Position of the Right-Most Bit (count, in octal, of the number of bits to the right of the current pointer position) ______________________________________________________________________ Less than 45 a local byte pointer. 45 6 44 46 6 36 47 6 30 50 6 22 51 6 14 52 6 6 53 6 0 54 8 44 1-5 INTRODUCTION INTRODUCTION 55 8 34 56 8 24 57 8 14 60 8 4 61 7 44 62 7 35 63 7 26 64 7 17 65 7 10 66 7 1 67 9 44 70 9 33 71 9 22 72 9 11 73 9 0 74 18 44 75 18 22 76 18 0 77 unused (causes an illegal instruction trap) ______________________________________________________________________ You cannot use indexing or indirect addressing with one-word global byte pointers. 1.2.5 File Handles and File Designators 1.2.5 File Handles and File Designators A file handle is also known as a job file number, or JFN. It is an 18-bit number that, within the context of a job, uniquely identifies a file. An indexable file handle, or full-word JFN, has a JFN in the right half and flags in the left half. This file handle is useful for handling several files in sequence. See Section 2.2.3 for a more complete discussion of file handles. 1.2.6 Source/Destination Designators 1.2.6 Source/Destination Designators Some monitor calls act upon bytes or strings of bytes, or transfer bytes from one place to another. Such calls often use source/destination designators to identify where the bytes are sent or obtained. A source/destination designator is a 36-bit quantity that can have the 1-6 INTRODUCTION INTRODUCTION formats given in Table 1-2. The paragraphs following the table describe each designator. Note that byte pointers are also source/destination designators. Table 1-2: Source/Destination Designators Table 1-2: Source/Destination Designators ______________________________________________________________________ Symbol Left Half Right Half Meaning ______________________________________________________________________ (none) 0 JFN a job file number. The JFN is the job's handle on a file, and is assigned with the GTJFN monitor call. (Refer to Section 2.2.3.) .PRIIN 0 100 primary input designator .PRIOU 0 101 primary output designator .NULIO 0 377777 null designator .TTDES 0 4xxxxx universal terminal designator .SIGIO 0 677777 signal JFN. When a fork's I/O designator is .SIGIO, then any attempt to perform I/O to that JFN will freeze the fork and cause a channel 19 (fork termination) interrupt to be sent to that fork's superior. .CTTRM 0 777777 the job's controlling terminal .DVDES 6xxxxx xxxxxx universal device designator (for use only in section 0) 777777 address implicit byte pointer. TOPS-20 changes left half to 440700. (Refer to Sections 1.2.4 and 1.2.6.2.) .b.i-35 777777 777777 universal default 5xxxxx xxxxxx numeric value Note: The designators .PRIIN and .PRIOU are legal wherever a JFN is expected. You cannot assign them as JFN's, however. GTJFN and GNJFN never assign 100 or 101. ______________________________________________________________________ 1-7 INTRODUCTION INTRODUCTION The most commonly used source/destination designators are: 1. A JFN, identifying a particular file. Before a JFN can be used, it must be obtained by means of the GTJFN monitor call. (See Section 2.2.3.) 2. The primary input and output designators. (Refer to Section 2.2.9.) These designators are the ones recommended for use in referring to the job's controlling terminal because they can be changed to cause terminal input and/or output to be taken from and/or sent to a file. The controlling terminal designator .CTTRM (0,-1) cannot be redirected in this way, and its use is not recommended in normal situations. 3. A byte pointer to the beginning of the string being read or written. 1.2.6.1 File Designator 1.2.6.1 File Designator - A file designator indicates that I/O to be done by the monitor call is to be done as though to a terminal. A file designator can be any of the following: .PRIIN, .PRIOU, .NULIO, .TTDES, .CTTRM, or .DVDES. 1.2.6.2 Byte Pointers and ASCII Strings 1.2.6.2 Byte Pointers and ASCII Strings - Many monitor calls deal specifically with ASCII strings. The following conventions apply to such strings. 1. A file designator can be used if the file is in 7-bit ASCII format. This is the usual format for text files. 2. One of the following is used to designate a string in the caller's address space: a. -1,,ADR to designate a 7-bit ASCII string beginning in the leftmost byte of ADR. This is for convenience, making HRROI 1,ADR functionally equivalent to MOVE 1,[POINT 7,ADR]. b. A byte pointer with a byte size of 7 bits. If the byte size is not 7 bits, the results might be incorrect. This is because monitor calls use the ILDB and IDPB instructions to reference byte strings, and do no additional checking to see that the data is in the correct format. Note, however, that for historical reasons some monitor calls accept byte pointers with byte sizes larger or smaller than 7 bits. 1-8 INTRODUCTION INTRODUCTION NOTE Unless otherwise noted, the term "byte pointer" is used in this manual to indicate an ILDB/IDPB byte pointer that points to an ASCIZ string. The following example generates such a byte pointer: POINT 7,[ASCIZ/character string/] The term "pointer" is usually used to refer to an address, except in discussions that must make repeated references to the term "byte pointer". In the latter case, some of the occurrences of "byte pointer" will be shortened to "pointer" to avoid monotonous repetition. In these cases, however, it will be clear from the context that "pointer" implies "byte pointer". Normally, monitor calls assume that ASCII strings are terminated with a byte containing zeroes (an ASCIZ string). A few calls terminate on other ASCII characters because of context (the NIN call, for example), and some optionally accept an explicit byte count or allow you to determine the terminating byte. These latter calls (SIN and SOUT calls, for example) are generally those that can handle non-ASCII strings and byte sizes other than 7 bits. After a monitor call is used to read a string, the source byte pointer argument is updated such that an ILDB would read the character following the terminating character; an LDB would reread the terminating character. After a monitor call is used to write a string, the destination byte pointer argument is updated to point to the character following the last nonnull character written. If there is room, a null byte is appended to the string, but the byte pointer returned is such that an IDPB will overwrite the null. 1.2.6.3 Special Designators 1.2.6.3 Special Designators - The universal default designator of -1 is used to indicate the current designator, such as the current job or the connected directory. For example, the GETJI monitor call accepts an argument of -1 as the designator for the current job. 1.2.6.4 Numeric Designators 1.2.6.4 Numeric Designators - The designator 5xxxxx xxxxxx (where a numeric value is in bits 3-35) is used to supply a numeric designator as an argument to a call. Numeric designators are used to identify account numbers, directory numbers, user numbers, and the like. The DIRST monitor call, for example, accepts a user number as 5B2+33-bit number. 1-9 INTRODUCTION INTRODUCTION 1.2.7 Device Designator 1.2.7 Device Designator Many monitor calls dealing with devices (refer to Section 2.4) take a device designator as an argument. A device designator can be either LH: .DVDES(600000)+device type number RH: unit number for devices that have units, arbitrary code for structures, or -1 for nonstructure devices that do not have units or LH: 0 RH: .TTDES(400000)+ terminal number, or .CTTRM(777777) for controlling terminal Thus, terminals can be represented in two ways; the second way is provided for compatibility with the source/destination designator. Because designators for structures contain an arbitrary code, these designators must always be obtained from the monitor (by means of the STDEV call) and cannot be created by the program. Section 2.4 describes the various devices and their type numbers. 1.2.7.1 Restrictions for Extended Addressing 1.2.7.1 Restrictions for Extended Addressing - A restriction on arguments passed to monitor calls executed in sections other than section 0 concerns universal device designators and numeric designators, which have the format 5xxxxx,,xxxxxx or 6xxxxx,,xxxxxx (.DVDES). These designators are only legal in section 0. This is because of the existence of one-word global byte pointers, which can have the same format. Thus, monitor calls that accept either this type of designator or a byte pointer when called from section 0 do not accept these designators in any other section. Other device designators, such as .TTDES (0,,4xxxxx), can be used in any section. Conversely, these monitor calls that can accept either device/numberic designators or byte pointers do not accept one-word global byte pointers in section 0. 1.2.8 Process Handles 1.2.8 Process Handles Several monitor calls accept an 18-bit argument called a process handle. The following fork handles are defined within the context of a job. 1-10 INTRODUCTION INTRODUCTION Value Symbol Meaning 400000 .FHSLF Current process 400000+n - Process n, relative to the current process 200000 FH%EPN Extended page number. When used in conjunction with the above two forms, this bit indicates that addresses and/or page numbers are interpreted as absolute, NOT relative to the PC section of the program executing the JSYS. This bit has no meaning for programs that do not use extended addressing. -1 .FHSUP Superior process -2 .FHTOP Top-level process -3 .FHSAI Current process and all of its inferiors -4 .FHINF All of the current process's inferiors -5 .FHJOB All processes in the job Use of the superior process argument (.FHSUP) is legal only if the process has the superior process access capability (SC%SUP) enabled in its capability word. Meaningful operations may usually be performed with the top level process argument (.FHTOP) only if the process has WHEEL or OPERATOR capability enabled (SC%WHL or SC%OPR) in its capability word. Refer to Section 2.7.1 for information on the capability word. Process handles in the range 400001 to 400777 are called relative process handles, and are generated by the monitor to refer to specific processes. (See the CFORK monitor call description.) These handles are valid only within the context of the process to which they are given. Thus, they may not be passed between processes. GFRKH may be used to convert process handles for use by another process. 1.2.8.1 Process/File Handle 1.2.8.1 Process/File Handle - Some monitor calls accept an 18-bit argument called a process/file handle. This handle is either a process handle (as defined in Section 1.2.8), or a JFN. Note that string pointers and terminal identifiers cannot be used in this context. This is not a limitation, however, because the operations that use the process/file handle are used for changing page maps. Such operations are not meaningful for string pointers or terminals. 1.3 SYSTEM DATE AND TIME 1.3 SYSTEM DATE AND TIME The internal system date and time is a 36-bit quantity. It can be passed to a monitor call as an argument, or returned as a value. The internal date-and-time word has the following format: day,,n 1-11 INTRODUCTION INTRODUCTION where day is the number of days since November 17, 1858, and *n is the fractional part of the day elapsed since midnight, Greenwich Mean n Time. n is the numerator of a fraction that has a denominator of 2**18. Thus the fraction *n/2**18 represents the portion of the day elapsed since midnight. This format conforms to the Smithsonian Astronomical Date Standard. Because the time is stored as Greenwich Mean Time, the monitor adds the value of the TIMEZONE offset to the internal date and time to obtain your local time. The TIMEZONE offset is specified in CONFIG.CMD. (See the Installation Guide for more information on the TIMEZONE offset.) Monitor calls convert local dates and times to internal dates and times, and internal dates and times to local dates and times. Refer to Section 2.9.2 for more information about date and time conversion. 1.4 PROCESSING ERRORS 1.4 PROCESSING ERRORS TOPS-20 provides a consistent way to handle all JSYS errors. Upon a successful return of most monitor calls, 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 of the Monitor Calls User's Guide). 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 1-12 INTRODUCTION INTRODUCTION 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 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 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%); and some calls do not return at all (see HALTF% or WAIT%). Refer to Chapter 3 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 1-13 INTRODUCTION INTRODUCTION 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. 1-14 CHAPTER 2 CHAPTER 2 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS 2.1 ACCOUNTING FUNCTIONS 2.1 ACCOUNTING FUNCTIONS The monitor calls in this group initiate and delete jobs from the system. They also change and read accounting information about these jobs. The following monitor calls perform accounting functions. Calls marked with an asterisk ("*") require privileges for specific functions. GACCT* Reads a file's account GACTF Reads a file's account LOGIN Logs a job into the system SACTF Sets a file's account USAGE Writes entries into the system's accounting data file VACCT Validates an account 2.2 REFERENCING FILES 2.2 REFERENCING FILES All files in the system, including the system's file directory, are normally referenced with the calls in this group. Section 2.11 describes the privileged calls for referencing the disk directly, without using the TOPS-20 file system. 2.2.1 File Specifications 2.2.1 File Specifications A file in TOPS-20 is identified by its node name, device name, directory name, filename, file type, and generation number. These five items uniquely identify any file on the system that is accessible to a user. The device name identifies the device on which the file is stored. The directory name identifies the directory containing the file. The filename, type, and generation number identify a particular file in the directory. 2-1 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS A file can also have attributes associated with it to further specify information about the file. See the description of the long-form GTJFN JSYS for a list of the possible file attributes. The general format of a file specification is: node::dev:name.typ.gen;attribute-1;attribute-2... Refer to the TOPS-20 User's Guide for the complete description of file specifications. If a field of the file specification (or filespec) is omitted, it can be supplied by the program or from standard system values. (Refer to Section 2.2.3.) Whenever an ESC is encountered in the file specification string, the system looks for a file whose specification matches the fields input thus far. A match is indicated if the input string either exactly matches an entry in the appropriate table, or is an initial substring of exactly one entry. In the latter case, the portion of the matching entry not appearing in the input string is output to a specified output file. The field terminator is output also. Recognition is done on successive fields with the fields being defaulted if need be. If the file specification cannot be uniquely determined, the system recognizes as many entire fields as are unique, and outputs a bell to the terminal, signifying that more input is required from the user. CTRL/F behaves like ESC except recognition stops after the current field. This allows the filename to be recognized, for example, but not the file type. If recognition is not used, then each field must be included as indicated in the general format above. The input must exactly match some existing file specification unless the program specifies in the GTJFN call that new specifications are allowed (output files). Without ESC or CTRL/F, no recognition is done. The system substitutes the default values supplied by your program for fields completely omitted from the file specification. The file specification is complete whenever all fields have been recognized or a terminator has been input. File specification terminators are described in the GTJFN call description. The following editing characters are recognized during the input of file specifications: DELETE erases one character. If no more characters remain in the input, a bell is output. CTRL/W deletes back to the last punctuation character. If no more characters remain in the input, a bell is output. 2-2 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS CTRL/U aborts the entire filename-gathering operation. CTRL/R retypes the entire input as specified so far and awaits further input. 2.2.2 Logical Names 2.2.2 Logical Names Logical names are user-specified default values for one or more fields in a file specification. Through the use of logical names, the user can override standard file specification fields built into TOPS-20 programs because logical name fields take precedence over default fields set by a program. However, the user can still specify any fields explicitly since a logical name defines values to be used only if none are given by the user. The user defines logical names with the DEFINE command or the CRLNM monitor call. Refer to the TOPS-20 User's Guide for the complete description of logical names. 2.2.3 File Handles 2.2.3 File Handles It is necessary to have file handles that can be contained in a few bits and do not require extensive lookup procedures for each reference. The file specification is the fundamental handle on a file, but this specification fits neither criterion above. Therefore in TOPS-20, files are referenced by handles called JFNs (Job File Numbers). The JFN is a small number and is valid within the context of the job (that is, within any process of the job to which it is assigned). However, the handle is not valid between jobs. That is, JFN 2 in job 11 will generally be a handle on a completely different file than JFN 2 in job 18. A JFN is associated with a file with either the GTJFN or GNJFN monitor call. The GTJFN call accepts a file specification and returns a JFN for the indicated file. If a field of the specification is omitted, it may be supplied by the program defaults or from standard system values. If the file specification refers to a group of files (because of wildcard characters, see below), the GNJFN call can be used to associate the JFN to the next file in the group. A logical name can apply to one or more fields of the file specification passed to the GTJFN call. The logical name must be the first identifier passed to GTJFN and must be terminated with a colon. The GTJFN call uses a certain search order when obtaining a field in a file specification. This order is as follows: 2-3 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS 1. Use the field explicitly typed by the user or the one specified in the primary input string. 2. Use the value for the field that is specified in the logical name specification. 3. Use the value for the field that is specified in the default block by the program. This is only for the long form of the GTJFN call. 4. Use the system default value if all of the above searches fail. In the special case of a device field specification, where the device name has been obtained from either the program default or the system default, the device field is checked to see if it is actually a logical name. If it is, then the values specified in its definition become defaults for all fields, including the device field. If the specific call to GTJFN permits, wildcard characters (either an asterisk or a percent sign) can appear in the device, directory, filename, type, or generation number fields. (The percent sign cannot appear in the generation number field.) An asterisk matches any occurrence of the field, including a null field. An asterisk as part of a field matches 0 or more characters anywhere in the field. A percent sign matches any single existing character in the field. Upon completion of the operation, the JFN returned references the first file found when scanning in the following order: In order by structure name (PS: is first, arbitrary order for others) In alphabetic order by directory name In alphabetic order by filename In alphabetic order by file type In ascending numeric order by generation number Note that for structures, only the construct DSK*: can be used. This means all available structures on the system. The GNJFN call can then be given to associate the JFN to the next file that matches the file specification. The fullword JFN (flags,,JFN) is termed an "indexable file handle" because it accepts a generic file specification (one including wildcard characters) and can be successively associated (by GNJFN) with each file matching the specification. Thus the JFN is "indexed" through a range of files. The number and type of files in the range are limited by the file specification, the privileges of the program, and the protection of individual files and directories within the file system. A program with WHEEL capabilities enabled can access any file in the TOPS-20 file system. 2-4 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS The maximum number of JFN's allowed depends upon the space reserved for JFN-related information in the Job Storage Block (JSB). Currently the maximum number of JFN's allowed is 140 (octal). The JFN's 100 (.PRIIN) and 101 (.PRIOU) are reserved for the primary input and output designators, respectively, and are never returned by the GTJFN (or GNJFN) call. The JFN 377777 (.NULIO) is reserved for the null designator. Ordinarily, the process of getting a file handle with GTJFN consists of the following: 1. The user specifies the file name string. 2. GTJFN checks the file name string for grammatical correctness. 3. GTJFN checks the file for validity (For example, does the file actually exist?) 4. If the file name passes these two checks, GTJFN returns a JFN or handle for the file. Thus a JFN is associated with an actual file in the TOPS-20 file system. It is sometimes desirable to skip the step of checking a JFN for validity. This is necessary any time that the association between the JFN and the physical file cannot be made, as happens when a JFN is requested for a file on magnetic tape. Also, it may be that the user himself wishes to prevent the JFN/file association from being made in order to check the file specification for grammatical correctness and then manipulate the file specification by adding or removing selected fields, or comparing it against another file specification. This type of JFN is termed a "parse-only" JFN. As it is not associated with any file, no file operations may be performed on it. Only the following JSYSs accept a parse-only JFN: 1. JFNS - converts a JFN to its file specification (in characters) 2. WILD% - compares character strings and file specifications 2.2.4 File References 2.2.4 File References All file operations are initiated by acquiring a JFN on a file using the GTJFN (or GNJFN) call. Some file operations, such as deleting, 2-5 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS renaming, and status queries about the file, may be performed immediately after the JFN is acquired. Certain operations, particularly data transfers, require that the file be opened with an OPENF call on the JFN. When the user opens a file, he specifies the byte size to be used for byte I/O operations and the access requested to the file. Several implicit initialization operations, which affect subsequent references to the file, are also invoked when a file is opened. For example, a file's position pointer is normally reset to the beginning of the file such that the first sequential input operation reads the beginning data of the file. Access to files on regulated structures (those being tracked by the accounting system) cannot be given until the mount count for that structure is incremented with the .MSIMC function of the MSTR JSYS (or with the TOPS-20 MOUNT STRUCTURE command). All JFN's must be released before the mount count can be decremented with the .MSDMC function of the MSTR JSYS (or the TOPS-20 DISMOUNT STRUCTURE command). All structures are regulated by default except the primary structure (PS:). 2.2.4.1 Files and Devices 2.2.4.1 Files and Devices - Under TOPS-20, most devices may be treated as if they were files. For example, a GTJFN, OPENF, CLOSF, etc. may be performed directly on magnetic tape device MTA1: without specifying a file name. This is because the device name itself is the file name. Disk devices, however, have multiple directories and multiple files, and the device name itself is not sufficient to uniquely identify a file. The general rule is that, for a complete TOPS-20 file specification, only those fields necessary to make the file unique for that device are required to get a JFN for the file. Thus, for most devices, the device name itself is sufficiently unique to get a JFN for the file. In this manual, when the phrase "opening a device" is used, it is in reference to the feature described above. For TOPS-20, disk devices are the only major exception to the rule that devices can be treated as files. Labeled tapes on MT: devices may be referenced either by device name alone (which gives access to all files on the tape) or by device name and file name (which gives access only to the specified file). 2.2.5 Sample Program 2.2.5 Sample Program The following sample program acquires JFN's, opens both an input and an output file, and then copies data from the input file to the output file in 7-bit bytes until the end of the input file is encountered. 2-6 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS ;*** PROGRAM TO COPY INPUT FILE TO OUTPUT FILE. *** ; (USING BIN/BOUT AND IGNORING NULL'S) TITLE FILEIO ;TITLE OF PROGRAM SEARCH MONSYM,MACSYM ;SEARCH SYSTEM JSYS-SYMBOL ;LIBRARIES ;*** IMPURE DATA STORAGE AND DEFINITIONS *** INJFN: BLOCK 1 ;STORAGE FOR INPUT JFN OUTJFN: BLOCK 1 ;STORAGE FOR OUTPUT JFN PDLEN=3 ;STACK HAS LENGTH 3 PDLST: BLOCK PDLEN ;SET ASIDE STORAGE FOR STACK STDAC. ;DEFINE STANDARD JSYS ACs ;*** PROGRAM INITIALIZATION *** START: RESET% ;CLOSE FILES AND INITIALIZE PROCESS MOVE P,[IOWD PDLEN,PDLST] ;ESTABLISH STACK ;*** GET INPUT-FILE *** INFIL: HRROI T1,[ASCIZ / INPUT FILE: /] ;PROMPT FOR INPUT FILE PSOUT% ;ON CONTROLLING TERMINAL MOVX T1,GJ%OLD+GJ%FNS+GJ%SHT;SEARCH MODES FOR GTJFN ;[EXISTING FILE ONLY , FILE-NR'S IN B ; SHORT CALL ] MOVE T2,[.PRIIN,,.PRIOU] ;GTJFN'S I/O WITH ; CONTROLLING TERMINAL GTJFN% ;GET JOB FILE NUMBER (JFN) ERJMP [ PUSHJ P,WARN ;IF ERROR, GIVE WARNING JRST INFIL] ;AND LET HIM TRY AGAIN MOVEM T1,INJFN ;SUCCESS, SAVE THE JFN ;*** GET OUTPUT-FILE *** OUTFIL: HRROI T1,[ASCIZ / OUTPUT FILE: /] ;PROMPT FOR OUTPUT FILE PSOUT% ;PRINT IT MOVX T1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT ;GTJFN ; SEARCH MODES [DEFAULT TO NEW ; GENERATION , PRINT MESSAGE , ; REQUIRE CONFIRMATION ; FILE-NR'S IN B , SHORT CALL ] MOVE T2,[.PRIIN,,.PRIOU] ;I/O WITH CONTROLLING TERMINAL GTJFN% ;GET JOB-FILE NUMBER ERJMP [ PUSHJ P,WARN ;IF ERROR, GIVE WARNING JRST OUTFIL] ;AND LET HIM TRY AGAIN 2-7 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS MOVEM T1,OUTJFN ;SAVE THE JFN ;NOW, OPEN THE FILES WE JUST GOT ; INPUT MOVE T1,INJFN ;RETRIEVE THE INPUT JFN MOVX T2,FLD(7,OF%BSZ)+OF%RD ;DECLARE MODES FOR OPENF ;[7-BIT BYTES + INPUT] OPENF% ;OPEN THE FILE ERJMP FATAL ;IF ERROR, GIVE MESSAGE AND STOP ; OUTPUT MOVE T1,OUTJFN ;GET THE OUTPUT JFN MOVX T2,FLD(7+OF%BSZ)+OF%WR ;DECLARE MODES FOR OPENF ;[7-BIT BYTES + OUTPUT] OPENF% ;OPEN THE FILE ERJMP FATAL ;IF ERROR, GIVE MESSAGE AND STOP ;*** MAIN LOOP :COPY BYTES FROM INPUT TO OUTPUT *** LOOP: MOVE T1,INJFN ;GET THE INPUT JFN BIN% ;TAKE A BYTE FROM THE SOURCE ERJMP DONE ;IF ERROR, CHECK FOR END OF FILE. JUMPE T2,LOOP ;SUPRESS NULLS MOVE T1,OUTJFN ;GET THE OUTPUT JFN BOUT% ;OUTPUT THE BYTE TO DESTINATION ERJMP FATAL ;IF ERROR, GIVE MESSAGE AND STOP JRST LOOP ;LOOP, STOP ONLY ON A 0 BYTE ;(FOUND AT LOOP+2) ;*** TEST FOR END OF FILE, ON SUCCESS FINISH UP *** DONE: GTSTS% ;GET THE STATUS OF INPUT FILE. TXNN T2,GS%EOF ;AT END OF FILE? PUSHJ P,FATAL ;NO, I/O ERROR CLOSIF: MOVE T1,INJFN ;YES, RETRIEVE INPUT JFN CLOSF% ;CLOSE INPUT FILE ERJMP FATAL ;IF ERROR, GIVE MESSAGE AND STOP CLOSOF: MOVE T1,OUTJFN ;RETRIEVE OUTPUT JFN CLOSF% ;CLOSE OUTPUT FILE ERJMP FATAL ;IF ERROR, GIVE MESSAGE AND STOP HRROI T1,[ASCIZ/ [DONE]/] ;SUCCESSFULLY DONE PSOUT% ;PRINT IT JRST ZAP ;STOP ;*** ERROR HANDLING *** 2-8 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS FATAL: HRROI T1,[ASCIZ/ ?/] ;FATAL ERRORS PRINT ? FIRST PUSHJ P,ERROR ;THEN PRINT ERROR MESSAGE, JRST ZAP ;AND STOP WARN: HRROI T1,[ASCIZ/ %/] ;WARNINGS PRINT % FIRST AND FALL ; THRU 'ERROR' BACK TO CALLER ERROR: PSOUT% ;PRINT THE ? OR % MOVE T1,[.PRIOU] ;DECLARE PRINCIPAL OUTPUT DEVICE ;FOR ERROR MESSAGE MOVE T2,[.FHSLF,,-1] ;CURRENT FORK,, LAST ERROR SETZB T3,T4 ;NO LIMIT,, FULL MESSAGE ERSTR% ;PRINT THE MESSAGE JFCL ;IGNORE UNDEFINED ERROR NUMBER JFCL ;IGNORE ERROR DURING EXECUTION ;OF ERSTR POPJ P, ;RETURN TO CALLER ZAP: HALTF% ;STOP JRST START ;WE ARE RESTARTABLE END START ;TELL LINKING LOADER ;START ADDRESS 2.2.6 File Access 2.2.6 File Access TOPS-20 provides a general mechanism for protecting files against unauthorized access. This mechanism includes the ability to protect access to files on a directory-wide basis as well as on an individual-file basis. Generally, access to a file depends on the kind of access desired and the relationship of the user making the access to the directory containing the file. The possible relationships a user may have to the file's directory are: 1. The directory containing the file is the user's connected or one of the user's accessed directories. Users satisfying this relationship have owner access to the files in the directory. 2. The directory containing the file is in the same group as the user. Users satisfying this relationship have group member access to the files in the directory. 3. The directory containing the file is outside the group membership. Users satisfying this relationship have world access to the files in the directory. 2-9 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS Both users and directories may belong to groups. The group-member relationship is satisfied if both the directory and the user belong to one or more of the same groups. Groups are assigned by the system _______ ______ _________ _____ manager or operator. (Refer to the TOPS-20 System Manager's Guide.) The type of access permitted to a file for each relationship is represented by the value of a 6-bit field. The possible values are: Value Symbol Meaning 40 FP%RD Read access 20 FP%WR Write access 10 FP%EX Execute access 4 FP%APP Append access 2 FP%DIR Directory listing access. If a user does not have at least this type of access, a GTJFN will find the file only if wildcards are not used. A GNJFN will not find the file. The following table illustrates some useful combinations of the values shown above: Value Symbol Meaning 12 FP%EX+FP%DIR Execute-only access 42 FP%RD+FP%DIR Usual protection allowing users to access a file without being able to modify it. 60 FP%RD+FP%WR Good for hiding files that specific programs can write to. Programs should be execute-only and the program should set the "restricted" access bit in the GTJFN so as not to reveal the filename. The 6-bit field and the three relationships (owner, group, remaining users) are represented by an 18-bit code, with bits 0-5 being the owner, bits 6-11 being the group, and bits 12-17 being the remaining users. When a particular bit is on, the corresponding access is permitted for the particular relationship. The access given to a group member includes the access given to all members outside the group. Also, the access given to the owner includes the access given to group members. Thus, the owner of a file or a user in the owner's group cannot have less access than users outside the group. 2.2.7 Directory Access 2.2.7 Directory Access Access to a directory is protected in a manner similar to, but distinct from, that of a file. An 18-bit code, containing three 6-bit fields, is associated with each directory. Each of the three fields 2-10 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS controls access by users in the same way that access to files is controlled. For directories, however, each 6-bit field can have one of the following values. Value Symbol Meaning 40 DP%RD Accessing files in the directory according to the access code on the individual files is allowed. A GTJFN call for a file in the directory will fail if the user does not have this access. 10 DP%CN Connecting to the directory without giving a password is allowed. With this access, a group member can change the FDB (as the owner) as well as times, dates, and accounting information for files in the directory. Other operations on the files are subject to the access codes of the files. If the user is connected to the directory, he has ownership access to the files; if he is not connected, he has group membership access. 4 DP%CF Creating files in the directory is allowed. When a user requests access to a file, the monitor checks the directory access code first. If the directory code allows the desired access, the monitor then checks the access code of the individual file. The access actually granted to a file is specified when the user opens the file with the OPENF call. If the access specified in the OPENF call is the same as or less than the access permitted by the 18-bit access code, the user is granted access to the file. Thus, for a user to be granted access to a specific file, two conditions must be met: 1. The access code (both directory and file) must permit the user to access the file in the desired manner (for example, read, write). 2. The file must not be open for a conflicting type of access. 2.2.8 File Descriptor Block 2.2.8 File Descriptor Block Each file has an associated File Descriptor Block (FDB) that contains various information about the file. The format of the FDB is shown in Table 2-1. The description of each word or bit in the FDB indicates whether the user can change it, and if so, what types of access are required. The types of access are: 2-11 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS 1. WRITE - write access 2. OWNER - owner access 3. W/OPR - WHEEL or OPERATOR capabilities enabled In some cases, separate JSYSs are required to read, set, and/or clear various words or bits. These functions are indicated by: 1. (R) - read 2. (S) - set 3. (C) - clear 4. (SC) - set/clear Table 2-1: File Descriptor Block (FDB) Table 2-1: File Descriptor Block (FDB) ______________________________________________________________________ Word Symbol Meaning ______________________________________________________________________ 0 .FBHDR FDB header word. Individual fields are as follows: B0-B28 Reserved for DIGITAL. UNCHANGEABLE B29-35(FB%LEN) Length of this file's FDB UNCHANGEABLE 1 .FBCTL B0(FB%TMP) File is temporary. JSYS WRITE OWNER W/OPR CHFDB N Y Y B1(FB%PRM) File is permanent. The contents of the file may be deleted, but the FDB may not. JSYS WRITE OWNER W/OPR CHFDB N Y Y 2-12 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS B2(FB%NEX) File does not yet have a file type; file does not really exist. UNCHANGEABLE B3(FB%DEL) File is deleted. JSYS WRITE OWNER W/OPR CHFDB N Y* Y *This bit may be changed by the owner providing that bit FB%ARC (in .FBCTL) is not set. B4(FB%NXF) File does not exist because it has not yet been closed. UNCHANGEABLE B5(FB%LNG) File is longer than 512 pages. UNCHANGEABLE B6(FB%SHT) Reserved for DIGITAL. UNCHANGEABLE B7(FB%DIR) File is a directory. UNCHANGEABLE B8(FB%NOD) File is not to be saved by the backup system. JSYS WRITE OWNER W/OPR CHFDB Y Y Y B9(FB%BAT) File may have one or more bad pages. This bit indicates that I/O errors have occurred for a page (or pages) of a file and the contents of these pages are suspect. This bit is set whenever the system has a disk I/O error on a page of an open file. The faulty disk address is also added to the list in the system's BAT blocks for that disk structure. 2-13 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS If an EXPUNGE is performed for a file for which bit FB%BAT is set, the system performs an additional function as it releases the pages of the file back to the available resource pool: it checks each disk address in the file against the list of bad regions in the structure's BAT blocks and if it finds a match, it leaves that page marked as "in use" in the bit map of available disk pages, so that the faulty page is not reused. UNCHANGEABLE B10(FB%SDR) Directory has subdirectories. UNCHANGEABLE B11(FB%ARC) File has archive status. Appropriate words in the FDB (below) specify where the file is archived. JSYS WRITE OWNER W/OPR ARCF N N Y B12(FB%INV) File is invisible. Invisible files can be seen only by using the G1%IIN option to GTJFN. JSYS WRITE OWNER W/OPR CHFDB N Y Y B13(FB%OFF) File is offline. This is set by DELF when it removes the contents from disk and cleared when ARCF restores the contents to disk. JSYS WRITE OWNER W/OPR DELF(S) N N Y ARCF(C) N N Y B14-B17(FB%FCF) File class field. If value of field is 0(.FBNRM), file is not an RMS file. If value of field is 1(.FBRMS), file is an RMS file. 2-14 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS JSYS WRITE OWNER W/OPR CHFDB Y Y Y B18(FB%NDL) Do not delete this file. Do not delete even if overwritten by a write or a rename. JSYS WRITE OWNER W/OPR CHFDB N N Y B19(FB%WNC) Last write not closed. File has not been closed by all writers. Page count may be incorrect. JSYS WRITE OWNER W/OPR CHFDB N N Y B20(FB%FOR) File has FORTRAN-style line printer carriage control characters. JSYS WRITE OWNER W/OPR CHFDB Y Y Y | | B21(FB%SEC) File is secure. 2 .FBEXL Link to FDB of next file with the same name but different file type. UNCHANGEABLE 3 .FBADR Disk address of file index block. UNCHANGEABLE 4 .FBPRT File access code. LH: 500000 UNCHANGEABLE RH: file access bits. JSYS WRITE OWNER W/OPR CHFDB N Y N 5 .FBCRE Date and time that the file was closed after the last write to the file. Modified when any program writes to the file. 2-15 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS JSYS WRITE OWNER W/OPR CHFDB N N Y 6 .FBAUT Pointer to string containing the name of the author. This word is not under direct user control. It is only changed indirectly, when the file author string is changed. JSYS WRITE OWNER W/OPR GFUST(R) Y Y Y SFUST(SC) N Y N 7 .FBGEN Generation and directory numbers of file. LH(FB%GEN): generation number of the file. UNCHANGEABLE RH(FB%DRN): monitor internal directory number of the file (only if B7 of .FBCTL is on). UNCHANGEABLE 10 .FBACT Account information. This word contains a byte pointer to an alphanumeric account designator; it can be changed with the SACTF monitor call. JSYS WRITE OWNER W/OPR SACTF Y Y Y 11 .FBBYV File I/O information. B0-B5(FB%RET) Number of generations to retain (retention count). If two generations of the same file have different retention counts, the count is taken from the generation currently being used. JSYS WRITE OWNER W/OPR CHFDB Y Y Y B6-B11(FB%BSZ) File byte size. This field can be changed by user with write access. 2-16 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS JSYS WRITE OWNER W/OPR CHFDB Y Y Y B14-B17(FB%MOD) Data mode of last open of file. This field can be changed by user with write access. JSYS WRITE OWNER W/OPR CHFDB Y Y Y B18-B35(FB%PGC) Page count of file. Note that the monitor keeps the page count updated, so under normal circumstances a user need not and should not alter this count. JSYS WRITE OWNER W/OPR CHFDB N N Y 12 .FBSIZ Number of bytes in the file. (Refer to Section 2.2.11.) JSYS WRITE OWNER W/OPR CHFDB Y Y Y 13 .FBCRV Date and time of creation of file. JSYS WRITE OWNER W/OPR CHFDB Y Y Y 14 .FBWRT Date and time that the file was opened when the last write to the file was made. JSYS WRITE OWNER W/OPR CHFDB Y Y Y 15 .FBREF Date and time of last nonwrite access to file. JSYS WRITE OWNER W/OPR CHFDB Y Y Y 16 .FBCNT Count word. LH: number of writes to file. 2-17 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS JSYS WRITE OWNER W/OPR CHFDB N N Y RH: number of references to file. JSYS WRITE OWNER W/OPR CHFDB N N Y 17 .FBBK0 Used by DUMPER for backup purposes. JSYS WRITE OWNER W/OPR CHFDB N N Y 20 .FBBK1 Reserved for DEC. UNCHANGEABLE 21 .FBBK2 Reserved for DEC UNCHANGEABLE 22 .FBBBT The right half contains the number of pages in the file when the contents were deleted from disk. UNCHANGEABLE The left half is used for the following flags: B1(AR%RAR) User request for a file to be archived. JSYS WRITE OWNER W/OPR ARCF Y Y Y B2(AR%RIV) System request for an involuntary migration of a file. JSYS WRITE OWNER W/OPR ARCF N N Y B3(AR%NDL) Do not delete the contents of the file from disk when the archival is complete. JSYS WRITE OWNER W/OPR ARCF N Y Y 2-18 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS B4(AR%NAR) Resist involuntary migration. This bit is a note from the user to the system access control program asking that the file not be moved offline if possible. JSYS WRITE OWNER W/OPR ARCF N Y Y B5(AR%EXM) File is exempt from involuntary migration. JSYS WRITE OWNER W/OPR ARCF N N Y B6(AR%1ST) First pass of an archival-collection run is in progress. JSYS WRITE OWNER W/OPR CHFDB N N Y B7(AR%RFL) Restore failed. Set by ARCF to indicate that the restore it is waiting for has failed. JSYS WRITE OWNER W/OPR ARCF N N Y B10(AR%WRN) Generate a message warning that the file's off-line expiration date is approaching. 7B17(AR%RSN) Reason file was moved offline: .AREXP(1) file expired .ARRAR(2) archiving was requested .ARRIR(3) migration was requested JSYS WRITE OWNER W/OPR ARCF(W) N N Y GTFDB(R) Y Y Y B18-B35(AR%PSZ) The right half of .FBBBT is used to 2-19 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS store the number of pages in a file when the contents were removed from disk. JSYS WRITE OWNER W/OPR ARCF(W) N N Y GTFDB(R) Y Y Y 23 .FBNET On-line expiration date and time. Specifies the date and time at which a file is considered expired, or specifies an interval (in days) after which the file is considered expired. JSYS WRITE OWNER W/OPR SFTAD N Y Y 24 .FBUSW User-settable word. JSYS WRITE OWNER W/OPR CHFDB N Y Y 25 .FBGNL Address of FDB for next generation of file. UNCHANGEABLE 26 .FBNAM Pointer to filename block. UNCHANGEABLE 27 .FBEXT Pointer to file type block. UNCHANGEABLE 30 .FBLWR Pointer to string containing the name of the user who last wrote to the file. This name is read with the GFUST monitor call and can be changed with the SFUST monitor call. Note that word .FBLWR may only be changed indirectly (by specifying a new name string). This word cannot be changed directly. JSYS WRITE OWNER W/OPR GFUST(R) Y Y Y SFUST(CS) N N Y 31 .FBTDT Archive or collection tape-write date and time. This is the date and time (in internal format) 2-20 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS that file was last written to tape (for either archiving or migration). JSYS WRITE OWNER W/OPR ARCF N N Y 32 .FBFET Offline expiration date and time. Specifies the date and time (or interval) after which a file in the archives or on virtual disk is considered expired. Used for tape recycling. Modified by SFTAD. JSYS WRITE OWNER W/OPR SFTAD Y Y Y 33 .FBTP1 Contains the tape ID for the first archive or collection run. JSYS WRITE OWNER W/OPR ARCF N N Y 34 .FBSS1 Contains the saveset and tape file numbers for the first tape. The left half is the number of the saveset in which the file is recorded, and the right half is the tape file number within that saveset. JSYS WRITE OWNER W/OPR ARCF N N Y 35 .FBTP2 Tape ID for second archive or collection run. Otherwise similar to .FBTP1. JSYS WRITE OWNER W/OPR ARCF N N Y 36 .FBSS2 Saveset and tape file numbers for the second archive or collection run. Otherwise similar to .FBSS1. JSYS WRITE OWNER W/OPR ARCF N N Y ______________________________________________________________________ 2-21 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS The maximum length FDB block that TOPS-20 will create (37 octal) may be specified with the symbol .FBLEN. 2.2.9 Primary Input and Output Files 2.2.9 Primary Input and Output Files Each process in a job has a primary input file and a primary output file. Both files are normally the controlling terminal, but can be changed to other files (with the SPJFN call). The primary input and output files are referenced with designators .PRIIN (JFN 100) and .PRIOU (JFN 101), respectively. Programs should be coded to do their "terminal" I/O to these designators, so that they can be used with command files without modification. Only in extreme cases should a program reference its controlling terminal (.CTTRM) directly. 2.2.10 Methods of Data Transfer 2.2.10 Methods of Data Transfer The most simple form of I/O is sequential byte I/O, as shown in the sample program. (Refer to Section 2.2.5.) This form of data transfer may be used with any file. A pointer maintained in the monitor is implicitly initialized when a file is opened and advanced as data is transferred. For files on disk, there are two other methods of data transfers. First, random access byte I/O is possible by using the SFPTR call or the RIN/ROUT calls. Second, entire pages of data may be mapped with the PMAP call. 2.2.11 File Byte Count 2.2.11 File Byte Count For disk files, TOPS-20 maintains a file byte count (.FBSIZ) in the FDB. This count is set by the monitor when sequential output (for example, BOUT, SOUT) occurs to the file and thus, on sequential output, reflects the number of bytes written in the file. When output occurs to the file using the PMAP call, the monitor does not set the file byte count. In this case, the number of bytes in the file may be different from the file byte count stored in the FDB. To allow sequential I/O to occur later to the file, the program should update the file byte count (.FBSIZ) and the file byte size (FB%BSZ) in the FDB before closing the file. This is done with the CHFDB monitor call. When output occurs to the file using random output calls (ROUT, for example), the file byte count is a number one greater than the highest byte number in the file. The file byte count is interpreted according to the byte size stored in the FDB, not the byte size specified when the file is opened. When a new file is opened, the byte size stored 2-22 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS in the FDB is 36 bits, regardless of the byte size specified in the OPENF call. If the program executes a CHFDB call to change the file byte count, it must usually change the byte size (FB%BSZ) so that both values reflect the same size bytes. 2.2.12 EOF Limit 2.2.12 EOF Limit There is an EOF limit associated with every opening of a file. This limit is the number of bytes that can be read with a sequential input call (for example, BIN, SIN). When the program attempts to read beyond this limit using sequential input, the call returns a 0 byte and an end-of-file condition. This condition may generate a software interrupt (refer to Section 2.6) if the user has not included an ERJMP or ERCAL as the next instruction following the call. (Refer to Chapter 1.) The EOF limit is computed when the file is opened with the OPENF call. The monitor computes this limit by determining the total number of words in the file and dividing this number by the byte size given in the OPENF call. The total number of words in the file is determined from the file byte count (.FBSIZ) and the file byte size (FB%BSZ) stored in the FDB. Note that page-mode I/O JSYSs, such as PMAP, ignore the EOF limit and can read any existing page of the file. However, page-mode JSYSs can only read pages within an existing file section (the address space of a file delimited by 1 index block - 512 pages). 2.2.13 Input/Output Errors 2.2.13 Input/Output Errors While performing I/O or I/O-related operations, it is possible to encounter one or more error conditions. Some of these are user-caused errors (for example, illegal access attempts), and others are I/O device or medium errors. TOPS-20 indicates such error conditions by setting error bits in the JFN status word (refer to the GTSTS call) and by initiating a software interrupt request (refer to Section 2.6) if the user has not included an ERJMP or ERCAL after the call. If the process in which an I/O error occurs is not prepared to process the interrupt, the interrupt is changed into a process terminating condition with the expectation that the process' immediate superior will handle the error condition. The TOPS-20 Command Language is prepared to detect and diagnose I/O errors; thus, a process running directly beneath the process containing the Command Language need not do its own I/O error handling unless it chooses to do something special. I/O errors can occur while a process is executing ordinary machine instructions as well as JSYSs. For example, if a PMAP operation is 2-23 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS performed that maps a page of a file into a page of a process, the file I/O transfer does not usually occur until a reference is made by the process to that particular page of the file. If there is an I/O error in the transfer, it is detected at the time of this reference. An attempt to do I/O to a terminal that is assigned to another job (as a controlling terminal or with the ASND call) normally results in an error, but is legal if the process has the WHEEL capability enabled. 2.2.13.1 Testing for End-of-File 2.2.13.1 Testing for End-of-File - The GTSTS JSYS, used in conjunction with ERCAL (or ERJMP), is used to test for end-of-file. The following code fragment illustrates this: MOVE T1,INJFN ;Get input JFN BIN% ;Read a byte ERCAL EOFTST . . ;Process byte . EOFTST: MOVE T1,INJFN ;Get input JFN GTSTS% ;Get status of that JFN TXNN T2,GS%EOF ;Did end of file occur? PUSHJ P,FATAL ; No, I/O error occurred MOVE T1,INJFN ; Yes, close file CLOSF% ERCAL FATAL ;If can't close, issue message POPJ P, ;OK to return FATAL: . ;Here to issue error messages . ; on fatal file errors . HALTF% ;Halt on fatal error In the example above, the ERCAL after the BIN is executed only if a file error condition arises. The code that is entered as a result of the ERCAL can then do a GTSTS for the appropriate file and test for end-of-file. An alternate method to test for end-of-file is to use the GETER JSYS and determine if the last error for the process is IOX4 (end of file reached). The following monitor calls used in referencing files (including I/O functions). Calls marked with an asterisk ("*") require privileges for specific functions. ACCES* Specifies access to a directory BIN Reads the next byte BKJFN Backspaces file's pointer BOUT Writes the next byte 2-24 FUNCTIONAL ORGANIZATION OF MONITOR CALLS FUNCTIONAL ORGANIZATION OF MONITOR CALLS CHFDB* Changes a File Descriptor Block CHKAC Checks access to a file CLOSF Closes a file CLZFF Closes a process's files CRDIR* Creates or modifies a directory CRLNM* Creates a logical name DELDF* Expunges deleted files DELF* Deletes a file