















                                  TOPS-20
                         Monitor Calls User's Guide
|  
|  
|                        Electronically Distributed
|  
|  
|  
|            This manual describes the use of  TOPS-20  monitor
|            calls,  which  provide  user  programs with system
|            services such as  input/output,  process  control,
|            file handling, and device control.
|  
|            This manual supersedes the TOPS-20  Monitor  Calls
|            User's  Guide  published  in June 1988.  The order
|            number  for  that   document,   AA-D859DM-TM,   is
|            obsolete.

             Change bars in the margins indicate material  that
             has  been  added  or  changed  since  the previous
             printing of this manual.



             Operating System:              TOPS-20 Version 7.0










   digital equipment corporation                   maynard, massachusetts



|  TOPS-20 Software Update Tape No. 04, November 1990

   First Printing, May 1976
   Revised, April 1982
   Revised, September 1985
   Revised, June 1988
|  Revised, November 1990



   The information in this document is subject to change  without  notice
   and  should  not  be  construed  as  a commitment by Digital Equipment
   Corporation.  Digital Equipment Corporation assumes no  responsibility
   for any errors that may appear in this document.

   The software described in this document is furnished under  a  license
   and  may  only  be used or copied in accordance with the terms of such
   license.

   No responsibility is assumed for the use or reliability of software on
   equipment that is not supplied by Digital Equipment Corporation or its
   affiliated companies.
|  
|  
|  
|  Copyright C 1976,   1982,   1985,   1988,   1990   Digital   Equipment
|  Corporation.

   All Rights Reserved.



   The following are trademarks of Digital Equipment Corporation:

   CI             DECtape     LA50             SITGO-10
   DDCMP          DECUS       LN01             TOPS-10
   DEC            DECwriter   LN03             TOPS-20
   DECmail        DELNI       MASSBUS          TOPS-20AN
   DECnet         DELUA       PDP              UNIBUS
   DECnet-VAX     HSC         PDP-11/24        UETP
   DECserver      HSC-50      PrintServer      VAX
   DECserver 100  KA10        PrintServer 40   VAX/VMS
   DECserver 200  KI          Q-bus            VT50
   DECsystem-10   KL10        ReGIS
   DECSYSTEM-20   KS10        RSX              d i g i t a l




                                      CONTENTS



   PREFACE


   CHAPTER 1       INTRODUCTION

           1.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 1-1
           1.2     MONITOR CALLS  . . . . . . . . . . . . . . . . . . 1-2
           1.2.1     Calling Sequence . . . . . . . . . . . . . . . . 1-3
           1.2.2     Error Returns  . . . . . . . . . . . . . . . . . 1-4
           1.3     PROGRAM ENVIRONMENT  . . . . . . . . . . . . . . . 1-6


   CHAPTER 2       INPUT AND OUTPUT USING THE TERMINAL

           2.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 2-1
           2.2     PRIMARY I/O DESIGNATORS  . . . . . . . . . . . . . 2-2
           2.3     PRINTING A STRING  . . . . . . . . . . . . . . . . 2-3
           2.4     READING A NUMBER . . . . . . . . . . . . . . . . . 2-4
           2.5     WRITING A NUMBER . . . . . . . . . . . . . . . . . 2-5
           2.6     INITIALIZING AND TERMINATING THE PROGRAM . . . . . 2-7
           2.6.1     RESET% Monitor Call  . . . . . . . . . . . . . . 2-8
           2.6.2     HALTF% Monitor Call  . . . . . . . . . . . . . . 2-8
           2.7     READING A BYTE . . . . . . . . . . . . . . . . . . 2-8
           2.8     WRITING A BYTE . . . . . . . . . . . . . . . . . . 2-8
           2.9     READING A STRING . . . . . . . . . . . . . . . . . 2-9
           2.10    SUMMARY  . . . . . . . . . . . . . . . . . . . .  2-14


   CHAPTER 3       USING FILES

           3.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 3-1
           3.2     JOB FILE NUMBER  . . . . . . . . . . . . . . . . . 3-2
           3.3     ASSOCIATING A FILE WITH A JFN  . . . . . . . . . . 3-3
           3.3.1     GTJFN% Monitor Call  . . . . . . . . . . . . . . 3-4
           3.3.1.1     Short Form of GTJFN% . . . . . . . . . . . . . 3-4
           3.3.1.2     Long Form of GTJFN%  . . . . . . . . . . . .  3-12
           3.3.1.3     Summary of GTJFN%  . . . . . . . . . . . . .  3-15
           3.4     OPENING A FILE . . . . . . . . . . . . . . . . .  3-16
           3.4.1     OPENF% Monitor Call  . . . . . . . . . . . . .  3-16
           3.5     TRANSFERRING DATA  . . . . . . . . . . . . . . .  3-19
           3.5.1     File Pointer . . . . . . . . . . . . . . . . .  3-20
           3.5.2     Source and Destination Designators . . . . . .  3-20
           3.5.3     Transferring Sequential Bytes  . . . . . . . .  3-21
           3.5.4     Transferring Strings . . . . . . . . . . . . .  3-22
           3.5.5     Transferring Nonsequential Bytes . . . . . . .  3-24
           3.5.6     Mapping Pages  . . . . . . . . . . . . . . . .  3-24
           3.5.6.1     Mapping File Pages to a Process  . . . . . .  3-26
           3.5.6.2     Mapping Process Pages to a File  . . . . . .  3-27



           3.5.6.3     Unmapping Pages in a Process . . . . . . . .  3-28
           3.5.7     Mapping File Sections to a Process . . . . . .  3-28
           3.6     CLOSING A FILE . . . . . . . . . . . . . . . . .  3-30
           3.6.1     CLOSF% Monitor Call  . . . . . . . . . . . . .  3-30
           3.7     ADDITIONAL FILE I/O MONITOR CALLS  . . . . . . .  3-31
           3.7.1     GTSTS% Monitor Call  . . . . . . . . . . . . .  3-31
           3.7.2     JFNS% Monitor Call . . . . . . . . . . . . . .  3-33
           3.7.3     GNJFN% Monitor Call  . . . . . . . . . . . . .  3-36
           3.8     SUMMARY  . . . . . . . . . . . . . . . . . . . .  3-40
           3.9     FILE EXAMPLES  . . . . . . . . . . . . . . . . .  3-40


   CHAPTER 4       USING THE SOFTWARE INTERRUPT SYSTEM

           4.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 4-1
           4.2     INTERRUPT CONDITIONS . . . . . . . . . . . . . . . 4-4
           4.3     SOFTWARE INTERRUPT CHANNELS AND PRIORITIES . . . . 4-4
           4.4     SOFTWARE INTERRUPT TABLES  . . . . . . . . . . . . 4-6
           4.4.1     Specifying the Software Interrupt Tables . . . . 4-6
           4.4.2     Channel Table  . . . . . . . . . . . . . . . . . 4-7
           4.4.3     Priority Level Table . . . . . . . . . . . . . . 4-8
           4.5     ENABLING THE SOFTWARE INTERRUPT SYSTEM . . . . . . 4-9
           4.6     ACTIVATING INTERRUPT CHANNELS  . . . . . . . . . . 4-9
           4.7     GENERATING AN INTERRUPT  . . . . . . . . . . . .  4-10
           4.8     PROCESSING AN INTERRUPT  . . . . . . . . . . . .  4-10
           4.8.1     Dismissing an Interrupt  . . . . . . . . . . .  4-11
           4.9     TERMINAL INTERRUPTS  . . . . . . . . . . . . . .  4-12
           4.10    ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS  . .  4-14
           4.10.1    Testing for Enablement . . . . . . . . . . . .  4-14
           4.10.2    Obtaining Interrupt Table Addresses  . . . . .  4-15
           4.10.2.1    The RIR% Monitor Call  . . . . . . . . . . .  4-15
           4.10.2.2    The XRIR% Monitor Call . . . . . . . . . . .  4-15
           4.10.3    Disabling the Interrupt System . . . . . . . .  4-16
           4.10.4    Deactivating a Channel . . . . . . . . . . . .  4-16
           4.10.5    Deassigning Terminal Codes . . . . . . . . . .  4-17
           4.10.6    Clearing the Interrupt System  . . . . . . . .  4-17
           4.11    SUMMARY  . . . . . . . . . . . . . . . . . . . .  4-17
           4.12    SOFTWARE INTERRUPT EXAMPLE . . . . . . . . . . .  4-18


   CHAPTER 5       PROCESS STRUCTURE

           5.1     USES FOR MULTIPLE PROCESSES  . . . . . . . . . . . 5-2
           5.2     PROCESS COMMUNICATION  . . . . . . . . . . . . . . 5-3
           5.2.1     Direct Process Control . . . . . . . . . . . . . 5-4
           5.2.2     Software Interrupts  . . . . . . . . . . . . . . 5-4
           5.2.3     IPCF and ENQ/DEQ Facilities  . . . . . . . . . . 5-4
           5.2.4     Memory Sharing . . . . . . . . . . . . . . . . . 5-5
           5.3     PROCESS IDENTIFIERS  . . . . . . . . . . . . . . . 5-5
           5.4     OVERVIEW OF MONITOR CALLS FOR PROCESSES  . . . . . 5-7
           5.5     CREATING A PROCESS . . . . . . . . . . . . . . . . 5-8
           5.5.1     Process Capabilities . . . . . . . . . . . . .  5-11



           5.6     SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A 
                   PROCESS  . . . . . . . . . . . . . . . . . . . .  5-11
           5.6.1     GET% Monitor Call  . . . . . . . . . . . . . .  5-11
           5.6.2     PMAP% Monitor Call . . . . . . . . . . . . . .  5-14
           5.7     STARTING AN INFERIOR PROCESS . . . . . . . . . .  5-15
           5.8     INFERIOR PROCESS TERMINATION . . . . . . . . . .  5-16
           5.9     INFERIOR PROCESS STATUS  . . . . . . . . . . . .  5-17
           5.10    PROCESS COMMUNICATION  . . . . . . . . . . . . .  5-19
           5.11    DELETING AN INFERIOR PROCESS . . . . . . . . . .  5-20
           5.12    PROCESS EXAMPLES . . . . . . . . . . . . . . . .  5-21


   CHAPTER 6       ENQUEUE/DEQUEUE FACILITY

           6.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 6-1
           6.2     RESOURCE OWNERSHIP . . . . . . . . . . . . . . . . 6-2
           6.3     PREPARING FOR THE ENQ/DEQ FACILITY . . . . . . . . 6-3
           6.4     USING THE ENQ/DEQ FACILITY . . . . . . . . . . . . 6-6
           6.4.1     Requesting Use of a Resource . . . . . . . . . . 6-6
           6.4.1.1     ENQ% Functions . . . . . . . . . . . . . . . . 6-6
           6.4.1.2     ENQ% Argument Block  . . . . . . . . . . . . . 6-8
           6.4.2     Releasing a Resource . . . . . . . . . . . . .  6-12
           6.4.2.1     DEQ% Functions . . . . . . . . . . . . . . .  6-13
           6.4.2.2     DEQ% Argument Block  . . . . . . . . . . . .  6-14
           6.4.3     Obtaining Information About Resources  . . . .  6-14
           6.5     SHARER GROUPS  . . . . . . . . . . . . . . . . .  6-17
           6.6     AVOIDING DEADLY EMBRACES . . . . . . . . . . . .  6-19


   CHAPTER 7       INTER-PROCESS COMMUNICATION FACILITY

           7.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 7-1
           7.2     QUOTAS . . . . . . . . . . . . . . . . . . . . . . 7-1
           7.3     PACKETS  . . . . . . . . . . . . . . . . . . . . . 7-2
           7.3.1     Flags  . . . . . . . . . . . . . . . . . . . . . 7-3
           7.3.2     PIDs . . . . . . . . . . . . . . . . . . . . . . 7-5
           7.3.3     Length and Address of Packet Data Block  . . . . 7-6
           7.3.4     Directories and Capabilities . . . . . . . . . . 7-6
           7.3.5     Packet Data Block  . . . . . . . . . . . . . . . 7-6
           7.4     SENDING AND RECEIVING MESSAGES . . . . . . . . . . 7-7
           7.4.1     Sending a Packet . . . . . . . . . . . . . . . . 7-7
           7.4.2     Receiving a Packet . . . . . . . . . . . . . . . 7-9
           7.5     SENDING MESSAGES TO <SYSTEM>INFO . . . . . . . .  7-12
           7.5.1     Format of <SYSTEM>INFO Requests  . . . . . . .  7-13
           7.5.2     Format of <SYSTEM>INFO Responses . . . . . . .  7-14
           7.6     PERFORMING IPCF UTILITY FUNCTIONS  . . . . . . .  7-15


   CHAPTER 8       USING EXTENDED ADDRESSING

           8.1     OVERVIEW . . . . . . . . . . . . . . . . . . . . . 8-1
           8.2     ADDRESSING MEMORY AND ACS  . . . . . . . . . . . . 8-2



           8.2.1     Instruction Format . . . . . . . . . . . . . . . 8-3
           8.2.2     Indexing . . . . . . . . . . . . . . . . . . . . 8-4
           8.2.3     Indirection  . . . . . . . . . . . . . . . . . . 8-5
           8.2.3.1     Instruction Format Indirect Word (IFIW)  . . . 8-5
           8.2.3.2     Extended Format Indirect Word (EFIW) . . . . . 8-6
           8.2.3.3     Macros for Indirection . . . . . . . . . . . . 8-6
           8.2.4     AC References  . . . . . . . . . . . . . . . . . 8-6
           8.2.5     Extended Addressing Examples . . . . . . . . . . 8-7
           8.2.6     Immediate Instructions . . . . . . . . . . . . . 8-8
           8.2.6.1     XMOVEI . . . . . . . . . . . . . . . . . . . . 8-8
           8.2.6.2     XHLLI  . . . . . . . . . . . . . . . . . . . . 8-9
           8.2.7     Other Instructions . . . . . . . . . . . . . . . 8-9
           8.2.7.1     Instructions that Affect the PC  . . . . . .  8-10
           8.2.7.2     Stack Instructions . . . . . . . . . . . . .  8-10
           8.2.7.3     Byte Instructions  . . . . . . . . . . . . .  8-10
           8.3     USING MONITOR CALLS  . . . . . . . . . . . . . .  8-11
           8.3.1     Mapping Memory . . . . . . . . . . . . . . . .  8-12
           8.3.1.1     Mapping File Sections to a Process . . . . .  8-12
           8.3.1.2     Mapping Process Sections to a Process  . . .  8-13
           8.3.1.3     Creating Sections  . . . . . . . . . . . . .  8-14
           8.3.1.4     Unmapping a Process Section  . . . . . . . .  8-15
           8.3.2     Starting a Process in Any Section  . . . . . .  8-16
           8.3.3     Setting the Entry Vector in Any Section  . . .  8-16
           8.3.4     Obtaining Information About a Process  . . . .  8-17
           8.3.4.1     Memory Access Information  . . . . . . . . .  8-17
           8.3.4.2     Entry Vector Information . . . . . . . . . .  8-19
           8.3.4.3     Page-Failure Information . . . . . . . . . .  8-19
           8.3.5     Program Data Vectors . . . . . . . . . . . . .  8-19
           8.3.5.1     Manipulating PDV Addresses . . . . . . . . .  8-20
           8.3.5.2     PDV Names  . . . . . . . . . . . . . . . . .  8-20
           8.3.5.3     Version Number . . . . . . . . . . . . . . .  8-21
           8.4     MODIFYING EXISTING PROGRAMS  . . . . . . . . . .  8-21
           8.4.1     Data Structures  . . . . . . . . . . . . . . .  8-21
           8.4.1.1     Index Words  . . . . . . . . . . . . . . . .  8-22
           8.4.1.2     Indirect Words . . . . . . . . . . . . . . .  8-22
           8.4.1.3     Stack Pointers . . . . . . . . . . . . . . .  8-22
           8.5     WRITING MULTISECTION PROGRAMS  . . . . . . . . .  8-22


   INDEX


   FIGURES

           4-1     Basic Operational Sequence of the Software 
                   Interrupt System . . . . . . . . . . . . . . . . . 4-3
           6-1     Deadly Embrace Situation . . . . . . . . . . . . . 6-5
           6-2     Use of Sharer Groups . . . . . . . . . . . . . .  6-18
           7-1     IPCF Packet  . . . . . . . . . . . . . . . . . . . 7-2
           8-1     Program Counter Address Fields . . . . . . . . . . 8-2
           8-2     Instruction Word Address Fields  . . . . . . . . . 8-4
           8-3     Instruction Format Indirect Word . . . . . . . . . 8-5



           8-4     Extended Format Indirect Word  . . . . . . . . . . 8-6


   TABLES

           2-1     NOUT% Format Option  . . . . . . . . . . . . . . . 2-6
           2-2     RDTTY% Control Bits  . . . . . . . . . . . . . .  2-10
           3-1     Standard System Values for File Specifications . . 3-3
           3-2     GTJFN% Flag Bits . . . . . . . . . . . . . . . . . 3-5
           3-3     Bits Returned on GTJFN% Call . . . . . . . . . .  3-10
           3-4     Long Form GTJFN% Argument Block  . . . . . . . .  3-13
           3-5     OPENF% Access Bits . . . . . . . . . . . . . . .  3-17
           3-6     PMAP% Access Bits  . . . . . . . . . . . . . . .  3-26
           3-7     SMAP% Access Bits  . . . . . . . . . . . . . . .  3-29
           3-8     CLOSF% Flag Bits . . . . . . . . . . . . . . . .  3-30
           3-9     Bits Returned on GTSTS% Call . . . . . . . . . .  3-31
           3-10    JFNS% Format Options . . . . . . . . . . . . . .  3-34
           3-11    GNJFN% Return Bits . . . . . . . . . . . . . . .  3-37
           4-1     Software Interrupt Channel Assignments . . . . . . 4-5
           4-2     Terminal Codes and Conditions  . . . . . . . . .  4-12
           5-1     Process Handles  . . . . . . . . . . . . . . . . . 5-6
           5-2     Inferior Process Characteristic Bits . . . . . . . 5-9
           5-3     GET% Flag Bits . . . . . . . . . . . . . . . . .  5-12
           5-4     GET% Argument Block  . . . . . . . . . . . . . .  5-13
           5-5     GET% Argument Block Flags  . . . . . . . . . . .  5-13
           5-6     Process Status Word  . . . . . . . . . . . . . .  5-17
           5-7     RFSTS% Status-Return Block . . . . . . . . . . .  5-18
           6-1     ENQ% Functions . . . . . . . . . . . . . . . . . . 6-7
           6-2     ENQ% Argument Block  . . . . . . . . . . . . . . . 6-8
           6-3     Lock Specification Flags . . . . . . . . . . . .  6-10
           6-4     DEQ% Functions . . . . . . . . . . . . . . . . .  6-13
           6-5     DEQ% Argument Block  . . . . . . . . . . . . . .  6-14
           6-6     ENQC% Flag Bits  . . . . . . . . . . . . . . . .  6-16
           7-1     Packet Descriptor Block Flags  . . . . . . . . . . 7-3
           7-2     Flags Meaningful on a MSEND% Call  . . . . . . . . 7-8
           7-3     Flags Meaningful on a MRECV% Call  . . . . . . .  7-10
           7-4     MRECV% Return Bits . . . . . . . . . . . . . . .  7-12
           7-5     <SYSTEM>INFO Functions and Arguments . . . . . .  7-14
           7-6     <SYSTEM>INFO Responses . . . . . . . . . . . . .  7-15
           7-7     MUTIL% Functions . . . . . . . . . . . . . . . .  7-16




















                                  PREFACE



   The TOPS-20 Monitor Calls User's Guide is  written  for  the  assembly
   language  user  who is unfamiliar with the DECSYSTEM-20 monitor calls.
   The manual introduces the user to the functions that he can request of
   the  monitor  from  within his assembly language programs.  The manual
   also teaches him how to use the basic  monitor  calls  for  performing
   these functions.

   This  manual  is  not  a  reference  document,  nor  is  it   complete
   documentation  of  the  entire  set of monitor calls.  It is organized
   according to functions, starting with the simple and proceeding to the
   more advanced.

   Each chapter should be read from beginning to end.  A user  who  skips
   around  in  his reading will not gain the full benefit of this manual.
   Once the user has a working knowledge of the  monitor  calls  in  this
                                          _______ _______ _____ _________
   document,  he should then refer to the TOPS-20 Monitor Calls Reference
   ______
   Manual for the complete descriptions of all the calls.

   To understand the examples in this manual, the user must  be  familiar
   with  the  MACRO  language  and the DECSYSTEM-20 machine instructions.
       _______ _____  _________  _________  ______
   The TOPS-20 MACRO  Assembler  Reference  Manual  documents  the  MACRO
                    _______  ____  _________ ______
   language.   The  TOPS-20  LINK  Reference Manual describes the linking
                  _________________________  _________  _________  ______
   loader.   The  DECsystem-10/DECSYSTEM-20  Processor  Reference  Manual
   contains  the  information  on  the machine instructions.  These three
   manuals should be used together with the Monitor Calls  User's  Guide,
   and  should  be referred to when questions arise on the MACRO language
                                                         ____________  __
   or the instruction set.  Another useful reference is  Introduction  to
   ____________   ________  ________  ___________
   DECSYSTEM-20   Assembly  Language  Programming  by  Ralph  E.   Gorin,
   published by the Digital Press.  It provides a thorough  treatment  of
   assembly  language  programming  for the DECSYSTEM-20, emphasizing the
   analysis of programs and various methods of program synthesis.

   In addition, some of the examples in this manual  contain  macros  and
   symbols  (MOVX,  TMSG,  JSERR,  or JSHLT, for example) from the MACSYM
   system file.  This file is a universal file of  definitions  available


                                    iii



   to the user as a means of producing consistent and readable programs.

   Finally, the user should be familiar with the TOPS-20 Command Language
                                       _______ ______ _____
   to enter and run the examples.  The TOPS-20 User's Guide describes the
                                              _______ ________  _________
   TOPS-20 commands and system programs.  The TOPS-20 Commands  Reference
   ______
   Manual  describes  all  operating  system  commands  available  to the
   nonprivileged user of TOPS-20.















































                                     4












                                 CHAPTER 1
                                 CHAPTER 1

                                INTRODUCTION
                                INTRODUCTION



   1.1  OVERVIEW
   1.1  OVERVIEW

   A program written in MACRO assembly language consists of a  series  of
   statements,  each  statement  usually  corresponding  to  one  or more
   machine language instructions.  Each statement in  the  MACRO  program
   may be one of the following types:

        1.  A MACRO assembler directive, or pseudo-operation (pseudo-op),
            such  as SEARCH or END.  These pseudo-ops are commands to the
            MACRO  assembler  and  are  performed  when  the  program  is
                                           ____________  _____  _________
            assembled.    Refer   to  the  DECSYSTEM-20  MACRO  Assembler
            _________ ______
            Reference Manual  for  detailed  descriptions  of  the  MACRO
            pseudo-ops.

        2.  A  MACRO  assembler  direct  assignment   statement.    These
            statements are in the form

                 symbol=value

            and are  used  to  assign  a  specific  value  to  a  symbol.
            Assignment  statements  are  processed by the MACRO assembler
            when the program  is  assembled.   These  statements  do  not
            generate instructions or data in the assembled program.

        3.  A MACRO assembler constant declaration statement, such as

                 ONE:  EXP 1

            These statements are processed when the program is assembled.

        4.  An instruction mnemonic, or symbolic instruction  code,  such
            as  MOVE  or ADD.  These symbolic instruction codes represent
            the operations performed by the central  processor  when  the
                                                _________________________
            program  is executed.  Refer to the DECsystem-10/DECSYSTEM-20
            _________ _________ ______
            Processor Reference Manual for detailed descriptions  of  the
            symbolic instruction codes.



                                    1-1
                                INTRODUCTION
                                INTRODUCTION


        5.  A monitor call, or JSYS, such as RESET or BIN.   These  calls
            are  commands  to  the  monitor  and  are  performed when the
            program is executed.  This manual describes the commonly-used
                                                                  _______
            monitor calls.  However, the user should refer to the TOPS-20
            _______ _____ _________ ______
            Monitor Calls Reference Manual for detailed  descriptions  of
            all the calls.

   When the MACRO program is assembled, the MACRO assembler processes the
   statements in the program by

         o  translating symbolic instruction codes to binary codes.

         o  relating symbols to numeric values.

         o  assigning relocatable or absolute memory addresses.

   The MACRO assembler also converts each symbolic call  to  the  monitor
   into a Jump-to-System (JSYS) instruction.



   1.2  MONITOR CALLS
   1.2  MONITOR CALLS

   Monitor calls are used to request monitor functions, such as input  or
   output  of  data (I/O), error handling, and number conversions, during
   the execution of the program.  These calls are accomplished  with  the
   JSYS  instruction  (operation  code 104), where the address portion of
   the instruction indicates the particular function.

   Each monitor call has a predefined symbol  indicating  the  particular
   monitor  function  to  be  performed  (for example, OPENF% to indicate
   opening a file).  The symbols are defined  in  a  system  file  called
   MONSYM.   Monitor  calls  defined  in  Release  4  and later require a
   percent sign (%) as the final character in the call  symbol.   Monitor
   calls  defined  prior to Release 4 do not require the %, but do accept
   it.  The current convention is that all monitor calls  use  the  %  as
   part of the call symbol.  This manual follows that convention.  To use
   the symbols and to cause them to  be  defined  correctly,  the  user's
   program must contain the statement

        SEARCH MONSYM

   at the beginning of the program.  During the assembly of the  program,
   the  assembler  replaces  the  monitor call symbol with an instruction
   containing the operation code 104 in the left half and the appropriate
   function code in the right half.

   Arguments for a JSYS instruction are  placed  in  accumulators  (ACs).
   Any  data  resulting  from  the  execution of the JSYS instruction are
   returned in the accumulators or in an address in memory  to  which  an
   accumulator  points.   Therefore,  before  the JSYS instruction can be
   executed, the appropriate arguments must be  placed  in  the  specific
   accumulators.

                                    1-2
                                INTRODUCTION
                                INTRODUCTION


   The system file MACSYM.MAC contains a number of useful macros for  the
   assembly  language  programmer.   To  use  MACSYM  macros,  the user's
   program must contain the statements

        SEARCH MACSYM
        .REQUIRE SYS:MACREL      ;include support routines

   at the beginning of the program.  Since most bits defined for use with
   the  monitor  have  symbolic  names,  macros  enable the programmer to
   utilize these bits without knowledge of their exact position.  Several
   MACSYM  macros  that  are  especially valuable to the TOPS-20 assembly
   language programmer are MOVX, TXnn (where nn indicates one of  the  64
   test  instructions  provided by the hardware), and FLD.  MOVX loads an
   AC with a constant using the proper MOVE  instructions,  depending  on
   the  constant's position in the word.  The TXnn macros expand to allow
   all combinations of modification  and  testing  to  be  defined.   For
   example

        TXNN AC1,GS%EOF

   tests AC1 for the presence of GS%EOF, no modification, and skip if not
   equal  to  zero.   This instruction will work regardless of the actual
   bit position of GS%EOF.  The FLD macro causes  a  value  to  be  right
   justified in a field.  For example

        FLD(7,OF%BSZ)

   places the value 7 in  position  OF%BSZ,  right  justified  at  bit  5
   (OF%BSZ   is  defined  as  bits  0-5).   These  macros  will  be  used
   consistently throughout this document.



   1.2.1  Calling Sequence
   1.2.1  Calling Sequence

   Arguments for the  calls  are  placed  in  accumulators  1  through  4
   (AC1-AC4).   If more than four arguments are required for a particular
   call, the arguments are placed in  a  list  to  which  an  accumulator
   points.   The  arguments  for  the  calls are specific bit settings or
   values.  These bit settings and values  are  defined  in  MONSYM  with
   symbol  names,  which  can  be  used  in  the program.  In fact, it is
   recommended that the user write his  program  using  symbols  whenever
   possible.  This makes the program easier to read by another user.  Use
   of symbols also allows the values  of  the  symbols  to  be  redefined
   without  requiring the  program  to be changed.  In  this manual,  the
   arguments for the monitor  calls  are  described  with  both  the  bit
   settings and the symbol names.  All program examples are written using
   the symbol names.






                                    1-3
                                INTRODUCTION
                                INTRODUCTION


   The set of instructions that place the arguments in  the  accumulators
   is  followed  by  one  line of code giving the particular monitor call
   symbol.  During the program's execution, control is transferred to the
   monitor when this line of code is reached.



   1.2.2  Error Returns
   1.2.2  Error Returns

   TOPS-20 provides a consistent way to handle all JSYS errors.  For most
   monitor  calls upon a successful return, the instruction following the
   call is executed.  If an error occurs  during  the  execution  of  the
   call, the monitor examines the instruction following the call.  If the
   instruction is a JUMP instruction  with  the  AC  field  specified  as
   12-17,  the monitor transfers control to a user-specified address.  If
   the instruction is not a JUMP instruction, the  monitor  generates  an
   illegal  instruction trap indicating an illegal instruction, which the
   user's program can process via the software interrupt system (refer to
   Chapter  4).   If  the  user's  program is not prepared to process the
   instruction trap, the program execution halts, and a message is output
   stating the reason for failure.

   To place a JUMP instruction in his program, the  user  can  include  a
   statement using one of six predefined symbols.  These symbols are

        ERJMPR  address   (= JUMP 12,address)
        ERCALR  address   (= JUMP 13,address)
        ERJMPS  address   (= JUMP 14,address)
        ERCALS  address   (= JUMP 15,address)
        ERJMP   address   (= JUMP 16,address)
        ERCAL   address   (= JUMP 17,address)

   and cause the assembler to generate  a  JUMP  instruction.   The  JUMP
   instruction  is  a non-operation instruction (that is, a no-op) as far
   as the hardware is concerned.  However, the monitor executes the  JUMP
   instruction by transferring control to the address specified, which is
   normally the beginning of an error processing routine written  by  the
   user.   If  the user includes the ERJMP symbol, control is transferred
   as though a JUMPA instruction had been executed, and control does  not
   return  to  his  program  after the error routine is finished.  If the
   user includes the ERCAL symbol, control is  transferred  as  though  a
   PUSHJ 17, address instruction had been executed.  If the error routine
   executes a POPJ 17, instruction, control returns to the user's program
   at the location following the ERCAL.

   If the user includes the ERJMPR symbol, the monitor behaves  the  same
   as  it  would  if  the ERJMP symbol had been included, except that the
   last error encountered by the process is stored  in  the  user's  AC1.
                               _______ _______ _____ _________ ______
   (Refer to Appendix B of the TOPS-20 Monitor Calls Reference Manual for
   the list of error codes, mnemonics, and message strings.)  The  ERCALR
   symbol  functions  the same as ERCAL except the error code encountered
   is returned in the user's AC1.  ERJMPS and ERCALS  function  similarly
   except the monitor suppresses the storing of the error code in the

                                    1-4
                                INTRODUCTION
                                INTRODUCTION


   user's AC1.   Instead,  AC1  is  preserved  and  contains  either  the
   original contents from when the monitor call was given, or a partially
   updated value prior to the error.

   Prior to the implementation of  the  ERJMP/ERCAL  facilities,  certain
   monitor  calls  returned  control  to  the  user's  program at various
   locations after the calling address.  Approximately one third  of  the
   JSYSs  return  to  the +1 address only on failure, and to the location
   immediately following that (the +2 address) on successful execution of
   the  call.   A  few  calls  return +1, +2, or +3, dependent on varying
   conditions of success or failure (for examples, see ERSTR%  or  GACTF%
           _______ _______ _____ _________ ______
   in  the TOPS-20 Monitor Calls Reference Manual); and some calls do not
   return at all (see HALTF% or  WAIT%).   Refer  to  Chapter  3  of  the
   _______  _______  _____  _________ ______
   TOPS-20  Monitor  Calls  Reference Manual for the possible returns for
   each monitor call.

   When a failure occurs during the execution  of  a  monitor  call,  the
   monitor  stores  an error code.  The error code indicates the cause of
   the failure.  This error code is usually stored in the right  half  of
   AC1,  but  can  also  be stored in the monitor's data base or a user's
   data block.  In either case, you can  obtain  the  message  associated
   with the error by using the GETER% or ERSTR% call.

   The ERJMP/ERCAL facilities  can  also  be  used  following  a  machine
   instruction, and will trap for the following conditions:

         o  Illegal instruction

         o  Illegal memory read

         o  Illegal memory write

         o  Pushdown list overflow

   The ERJMP/ERCAL facilities  can  be  used  after  all  monitor  calls,
   regardless  of  whether  the  call  has one or two returns.  To handle
   errors consistently, users are encouraged to employ either the ERJMPR,
   ERCALR,  ERJMPS,  or  ERCALS  symbol  with  all calls.  All of the six
   predefined jump symbols are no-ops, unless they immediately  follow  a
   monitor  call  or instruction that fails.  Error codes can be obtained
   by the program and translated into their corresponding error  mnemonic
   and message strings with the GETER% and ERSTR% monitor calls.

   TOPS-20  provides  convenient  macros  and  subroutines  for  handling
   monitor  call  error  routines.   They can be found in the system file
   MACSYM.MAC.  Two such macros are EJSERR and EJSHLT.  EJSERR prints out
   an error message and returns control to the next instruction following
   the failing monitor call.  EJSHLT prints  out  an  error  message  and
   halts processing of the program.

   The following is an example of executing the BIN%  monitor  call  (see
   Chapter 3 for more information on this monitor call) that has a single


                                    1-5
                                INTRODUCTION
                                INTRODUCTION


   return.  If the execution of the call is successful, the program reads
   and  stores  a  character.   If  the  execution  of  the  call  is not
   successful, the program transfers control to an error  routine.   This
   routine  processes the error and then returns control back to the main
   program sequence.  Note that ERCALS stores the return address  on  the
   stack.

   DOIT:    MOVE    T1,INJFN     ;obtain JFN for input file
            BIN%                 ;input one character
             ERCALS ERROR        ;call error routine if problem
            MOVEM   T2,CHAR      ;store character
            JRST    DOIT         ;and get another
   ERROR:   GTSTS%               ;read file status
            TXNE    T2,GS%EOF    ;end of file?
            JRST    EOF          ;yes, process end-of-file condition
            HRROI   T1,[ASCIZ/   
   ?INPUT ERROR, CONTINUING
   /]                      ;no, data error 
            PSOUT%               ;print message
            RET                  ;return to program (POPJ 17,)

   The ASCIZ pesudo-op specifies a left-justified ASCII string terminated
   with a null (that is, a byte containing all bits equal to zero) byte.



   1.3  PROGRAM ENVIRONMENT
   1.3  PROGRAM ENVIRONMENT

   The user program environment in the TOPS-20 operating system  consists
   of  a  job  structure that can contain many processes.  A process is a
   runnable or schedulable entity capable of performing  computations  in
   parallel  with other processes.  This means that a runnable program is
   associated with at least one process.

   Each process has its own address space for storing  its  computations.
   This  address  space  is called virtual space because it is actually a
   "window" into physical storage.  The address space is divided into  32
   (decimal) sections.  Each section is divided into 512 (decimal) pages,
   and each page contains 512 (decimal) words.   Each  word  contains  36
   bits.

   A process can communicate with other processes in the following ways:

         o  explicitly, by software interrupts or system facilities  (the
            inter-process communication facility, or IPCF, for example).

         o  implicitly, by changing parts of its environment (its address
            space,  for  instance)  that  are  being  shared  with  other
            processes.

   A process can create other processes inferior to it, but there is  one
   control  process  from which the chain of creations begins.  A process


                                    1-6
                                INTRODUCTION
                                INTRODUCTION


   is said to exist when a superior process creates it and is said to end
   when  a  superior  process  deletes  it.   Refer to Chapter 5 for more
   information on the process structure.

   A set of one or more related processes, normally under  control  of  a
   single user, is a job.  Each active process is part of some job on the
   system.  A job is defined by a user name, an account number, some open
   files,  and a set of running and/or suspended processes.  A job can be
   composed of several running or suspended programs.

   The following diagram illustrates a job structure consisting  of  four
   processes.


                              -----------------
                              |               |
                              |  TOP PROCESS  |
                              |               |
                              -----------------
                                      |
                                      | 
                                      |
                         ---------------------------
                         |                         |
                 ----------------           ---------------
                 |              |           |             |
                 |  PROCESS A   |           |  PROCESS B  |
                 |              |           |             |
                 ----------------           ---------------
                                                   |
                                                   |
                                                   |
                                            ---------------
                                            |             |
                                            |  PROCESS C  |
                                            |             |
                                            ---------------


   Both process A and 1 process B are created by the TOP PROCESS and thus
   are  directly  inferior  to it.  Process C is created by process B and
   thus is directly inferior to process B only.  Process C is  indirectly
   inferior to the TOP PROCESS.

   In summary, processes can be considered as  independent  virtual  jobs
   with  well-defined relationships to other processes in the system, and
   a job is a collection of these processes.







                                    1-7

























































                                    2-1












                                 CHAPTER 2
                                 CHAPTER 2

                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL



   One of the main reasons for using monitor calls is  to  transfer  data
   from  one  location to another.  This chapter discusses moving data to
   and from the user's terminal.



   2.1  OVERVIEW
   2.1  OVERVIEW

   Data transfers to and from the terminal are  in  the  form  of  either
   individual  bytes  or  text  strings.  The bytes are 7-bit bytes.  The
   strings are ASCII strings ending with a 0  byte.   These  strings  are
   called ASCIZ strings.

   To designate the desired string, the user's  program  must  include  a
   statement  that  points  to  the beginning of the string being read or
   written.  The MACRO pseudo-op, POINT, can  be  used  to  set  up  this
   pointer, as shown in the following sequence of statements:

               MOVE AC1,PTR
                    .
                    .
                    .
        PTR:   POINT 7,MSG
        MSG:   ASCIZ/TEXT MESSAGE/

   Accumulator 1 contains the symbolic address (PTR) of the pointer.   At
   the  address  specified  by PTR is the pointer to the beginning of the
   string.  The pointer is set up by the POINT  pseudo-op.   The  general
   format of the POINT pseudo-op is:

        POINT decimal-byte-size,address,decimal-byte-position

                  _______  _____  _________  _________  ______
   (Refer to the  TOPS-20  MACRO  Assembler  Reference  Manual  for  more
   information  on  the POINT pseudo-op.) In the example above, the POINT
   pseudo-op has been written to indicate 7-bit bytes starting before the
   left-most bit in the address specified by MSG.



                                    2-1
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


   Another way of setting up an accumulator to contain the address of the
   pointer is with the following statement:

        HRROI AC1,[ASCIZ/TEXT MESSAGE/]

   The instruction mnemonic HRROI causes a -1 to be placed  in  the  left
   half  of  accumulator  1 and the address of the string to be placed in
   the right half.  However, in the above statement, a literal  (enclosed
   in  square brackets) has been used instead of a symbolic address.  The
   literal causes the MACRO assembler to:

         o  store data within brackets (the string) in a table.

         o  assign an address to the first word of the data.

         o  insert that address as the operand to the HRROI instruction.

   Literals have the advantage of showing the data at the  point  in  the
   program where it will be used, instead of showing it at the end of the
   program.

   As far as the I/O monitor calls are concerned, a word in  this  format
   (-1  in the left half and an address in the right half) designates the
   system's standard pointer (that is, a pointer to a 7-bit ASCIZ  string
   beginning  before the leftmost byte of the string).  The result of the
   HRROI  statement  is  interpreted  by  the  monitor  as   functionally
   equivalent to the word assembled by the POINT 7, address pseudo-op and
   is the recommended statement to use in preparation for a monitor call.
   However,  byte  manipulation  instructions  (for  example,  ILDB, IBP,
   ADJBP) will not operate properly with this type of pointer.

   After a string is read, the  pointer  is  advanced  to  the  character
   following  the terminating character of the string.  After a string is
   written, the pointer is advanced to the character following  the  last
   non-null character written.

   Most TOPS-20 monitor calls accept one-word global byte  pointers  when
   executed  from  a  nonzero  section  (see  Section  8.3).  Global byte
   pointers are used with extended addressing and are fully explained  in
   Chapter  8  of  this  document.   Unless  specifically stated, TOPS-20
   monitor calls do not accept two-word global byte pointers.



   2.2  PRIMARY I/O DESIGNATORS
   2.2  PRIMARY I/O DESIGNATORS

   To transfer data from one location to another, the user's program must
   indicate  the  source  from  which  the data is to be obtained and the
   destination where the data is to be placed.  By  default,  the  user's
   terminal is defined as the source and destination.  The default can be
                                                                  _______
   overridden by using the SPJFN% monitor  call  (refer  to  the  TOPS-20
   _______  _____  _________  ______
   Monitor  Calls  Reference  Manual).   Examples in this book assume the


                                    2-2
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


   user's terminal to be the  source  (input)  and  destination  (output)
   device.  Two designators are used to represent the user's terminal:

        1.  The symbol .PRIIN to represent the  user's  terminal  as  the
            source (input) device.

        2.  The symbol .PRIOU to represent the  user's  terminal  as  the
            destination (output) device.

   These symbols are called the primary input and output designators  and
   by  default  are  used  to represent the terminal running the program.
   They are defined in the system file MONSYM.MAC and do not have  to  be
   defined  in  the  user's  program  as long as the program contains the
   statement

        SEARCH MONSYM



   2.3  PRINTING A STRING
   2.3  PRINTING A STRING

   Many times a program may need to print an error message or some  other
   string,  such  as  a  prompt  to  request  input  from the user at the
   terminal.  The PSOUT% (Primary String Output) monitor call is used  to
   print  such a string on the terminal.  This call copies the designated
   string from the program's address space.  Thus, the source of the data
   is  the  program's  address space, and the destination for the data is
   the terminal.  The program need only supply the pointer to the  string
   being printed.

   Accumulator 1 (AC1) is used to contain the  address  of  the  pointer.
   After  AC1  is set up with the pointer to the string, the next line of
   code is the PSOUT% call.  Thus, an example of the PSOUT% call is:

        HRROI AC1,[ASCIZ/TEXT MESSAGE/]    ;string to print
        PSOUT%                             ;print TEXT MESSAGE

   The PSOUT% call prints on the  terminal  all  the  characters  in  the
   string  until  it  encounters  a  null  byte.  Note that the string is
   printed exactly as it is  stored  in  the  program,  starting  at  the
   current  position  of  the  terminal's print head or cursor and ending
   with the last character in the string.  If a carriage return and  line
   feed  are  to  be  output,  either  before  or after the string, these
   characters should be inserted as part of the string.  For example,  to
   print  TEXT  MESSAGE  on one line and to output a carriage return-line
   feed after it, the user's program includes the call

             HRROI AC1,[ASCIZ/TEXT MESSAGE
        /]
             PSOUT%




                                    2-3
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


   After the string is printed, the instruction following the PSOUT% call
   in  the  user's  program  is  executed.   Also,  the pointer in AC1 is
   updated  to  point  to  the  character  following  the  last  non-null
   character written.

   The macro TMSG, found in the system file MACSYM, does the  same  thing
   as  the  example above.  This macro offers the programmer a convenient
   way for printing messages on the terminal.  For example

        TMSG <TEXT MESSAGE
        >

   caused  the  text  message  contained  between  the  angle   brackets,
   including the carriage return and line feed, to print on the terminal.
   The TMSG macro, along with others previously mentioned, will  be  used
   consistently  in  examples  throughout  this  document.   Refer to the
   system file MACSYM.MAC for further information on MACSYM macros.

   Refer to Section 1.2.2 for information concerning error returns.



   2.4  READING A NUMBER
   2.4  READING A NUMBER

   The NIN% (Number Input) monitor call is used to read an integer.  This
   call does not assume the terminal as the source designator; therefore,
   the user's program must specify  this.   The  NIN%  call  accepts  the
   number from any valid source designator, including a string in memory.
   This section discusses reading a number directly  from  the  terminal.
   Refer to Section 2.9 for an example of using the NIN% call to read the
   number from a string in memory.  The destination  for  the  number  is
   AC2, and the NIN% call places the binary value of the number read into
   this accumulator.  The user's program also specifies a number  in  AC3
   that  represents the radix of the number being input.  The radix given
   can be in the range 2-36.

   Thus, the setup for the NIN% monitor call is the following:

        MOVEI AC1,.PRIIN    ;AC1 contains the primary input designator
                            ;(the user's terminal)

        MOVEI AC3,^D10      ;AC3 contains the radix of the number being
                            ;input (in this case a decimal number)

        NIN%                ;The call to input the number

   After completion of the NIN% call, control returns to the  program  at
   one of two places (refer to Section 1.2.2).  If an error occurs during
   the  execution  of  the  call,  control  returns  to  the  instruction
   following   the   call.    This  instruction  should  be  a  jump-type
   instruction to an error processing routine (see Section 1.2.2).  Also,
                                                                  _______
   an  error  code  is  placed in AC3 (refer to Appendix B of the TOPS-20
   _______ _____ _________ ______
   Monitor Calls Reference Manual for the error codes).  If the execution

                                    2-4
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


   of the  NIN%  call  is  successful,  control  returns  to  the  second
   instruction following the call.  The number input from the terminal is
   placed in AC2.

   The NIN% call terminates when it encounters a nondigit character  (for
   example,  a  letter, a punctuation character, or a control character).
   This means that if 32X1 were typed on  the  terminal,  on  return  AC2
   contains  a  40  (octal) because the NIN% call terminated when it read
   the X.

   The following program prints a message  and  then  accepts  a  decimal
   number  from  the  user  at  the  terminal.   Note  that the NIN% call
   terminates reading on any  nondigit  character;  therefore,  the  user
   cannot edit his input with any of the editing characters (for example,
   DELETE, CTRL/W).  The RDTTY% call (refer to  Section  2.9)  should  be
   used  in  programs  that  read from the terminal because it allows the
   user to edit his input as he is typing it.

          SEARCH MONSYM
          HRROI AC1,[ASCIZ/
   Enter # of seconds:  /]
          PSOUT%               ;output a prompt message
          MOVEI AC1,.PRIIN     ;input from the terminal
          MOVEI AC3,^D10       ;use the decimal radix
          NIN%                 ;input a decimal number
           ERJMP NINERR        ;error-go to error routine
          MOVEM AC2, NUMSEC    ;save number entered
            .
            .
            .
   NUMSEC:BLOCK 1
            .
            .
            .



   2.5  WRITING A NUMBER
   2.5  WRITING A NUMBER

   The NOUT% (Number Output) monitor call is used to output  an  integer.
   The  user's  program  moves  the  number  to  be output into AC2.  The
   program must specify the destination for the number  in  AC1  and  the
   radix  in  which  the  number is to be output in AC3.  The radix given
   cannot be greater than base 36.  In addition, the user's  program  can
   specify  certain  formatting  options  to  be  used  when printing the
   number.

   Thus, the general setup for the NOUT% monitor call is as follows:

        AC1:   output designator
        AC2:   number being output
        AC3:   format options in left half and radix in right half


                                    2-5
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


   The format options that can be specified in the left half of  AC3  are
   described in Table 2-1.


   Table 2-1:  NOUT% Format Option
   Table 2-1:  NOUT% Format Option

   ______________________________________________________________________

     Bit       Symbol       Meaning
   ______________________________________________________________________

      0        NO%MAG       Print  the  number  as  a  positive  36-bit
                            number.   For  example, -1 would be printed
                            as 777777 777777 if radix=8).

      1        NO%SGN       Print the appropriate sign (+ or -)  before
                            the  number.  If bits NO%MAG and NO%SGN are
                            both on, a plus sign is always printed.

      2        NO%LFL       Print leading filler.  If this bit  is  not
                            set,  trailing  filler  is  printed and bit
                            NO%ZRO is ignored.

      3        NO%ZRO       Use  0's  as  the  leading  filler  if  the
                            specified number of columns allows filling.
                            If this bit is not set, blanks are used  as
                            the leading filler if the number of columns
                            allows filling.

      4        NO%OOV       Output on column  overflow  and  return  an
                            error.   If  this  bit  is  not set, column
                            overflow is not output.

      5        NO%AST       Print asterisks when the column  overflows.
                            If  this bit is not set, and bit 4 (NO%OOV)
                            is set, all necessary  digits  are  printed
                            when the columns overflow.

      6-10                  Reserved for Digital (must be 0).

     11-17     NO%COL       Print  the  number  of  columns  indicated.
                            This  value  includes  the sign column.  If
                            this  field  is  0,  as  many  columns   as
                            necessary are printed.
   ______________________________________________________________________


   The following instruction sequence is an example of the NOUT%  monitor
   call.   This sequence prints a number, stored in location NUMB, on the
   user's terminal.  The number can be positive, negative or  zero,  with
   no special formatting.



                                    2-6
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


           MOVX AC1,.PRIOU                 ;use primary output
           MOVE AC2,NUMB                   ;get number from location NUMB
           MOVX AC3,^D10                   ;no special format
                                           ;decimal radix
           NOUT%                           ;print number
            EJSHLT                         ;unexpected fatal error. Halt
                                           ;and print message.

   Refer to Section 1.2.2 for information concerning error returns.   The
   following  example  illustrates  the  use  of  the three monitor calls
   described so far, as well as the TMSG macro.  The  RESET%  and  HALTF%
   monitor calls are described in Section 2.6.

           SEARCH MONSYM
           SEARCH MACSYM
           .REQUIRE SYS:MACREL
           AC1==1
           AC2==2
           AC3==3
   START:  RESET%                          ;prepare program environment
           HRROI AC1,[ASCIZ/PLEASE TYPE A DECIMAL NUMBER: /]
           PSOUT%
           MOVEI AC1,.PRIIN                ;source designator
           MOVEI AC3,^D10                  ;decimal radix
           NIN%
            ERJMPS ERROR                   ;if input error print message 
                                           ;halt.
           TMSG <THE OCTAL EQUIVALENT IS >
           MOVEI AC1,.PRIOU                ;destination designator
           MOVEI AC3,^D8                   ;octal radix
           NOUT%
            EJSHLT                         ;fatal error. 
                                           ;Same as ERJMPS ERROR.
           HALTF%                          ;return to command language
           JRST START                      ;begin again, if continued
   ERROR:  TMSG<
   ?ERROR-TYPE START TO BEGIN AGAIN>
           HALTF%
           JRST START                      ;user types continue-start 
                                           ;again
           END START



   2.6  INITIALIZING AND TERMINATING THE PROGRAM
   2.6  INITIALIZING AND TERMINATING THE PROGRAM

   Two monitor calls that have not yet been described were  used  in  the
   above program - RESET% and HALTF%.






                                    2-7
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


   2.6.1  RESET% Monitor Call
   2.6.1  RESET% Monitor Call

   A good programming practice is to include the RESET% monitor  call  at
   the  beginning  of  every assembly language program.  This call closes
   any existing open files and releases their JFNs,  kills  any  inferior
   processes,  clears  the software interrupt system (see Chapter 4), and
   performs  various  other  process  initilization  functions.   For   a
   complete  list  of  the functions provided by the RESET% monitor call,
                                                  _______  _______  _____
   refer to the description of the call  in  the  TOPS-20  Monitor  Calls
   _________ ______
   Reference Manual.  The format of the call is

        RESET%

   and control always returns to the next instruction following the call.



   2.6.2  HALTF% Monitor Call
   2.6.2  HALTF% Monitor Call

   To stop the execution of a program and return control to  the  TOPS-20
   Command Language, the user must include the HALTF% monitor call as the
   last instruction performed in the program.  The user can  then  resume
   execution  of the program at the instruction following the HALTF% call
   by typing the CONTINUE command after control has returned  to  command
   level.



   2.7  READING A BYTE
   2.7  READING A BYTE

   The PBIN% (Primary Byte Input) monitor call is used to read  a  single
   byte  (that  is, one character) from the terminal.  The user's program
   does not have to specify the  source  and  destination  for  the  byte
   because  this  call  uses  the  primary input designator (that is, the
   user's terminal) as the source and accumulator 1 as  the  destination.
   After  execution of the PBIN% call, control returns to the instruction
   following the PBIN%.  If execution of the call is successful, the byte
   read from the terminal is right-justified in AC1.  If execution of the
   call is not successful, an illegal instruction trap is  generated,  as
   explained in Section 1.2.2.



   2.8  WRITING A BYTE
   2.8  WRITING A BYTE

   The PBOUT% (Primary Byte Output) monitor  call  is  used  to  write  a
   single  byte  to  the  terminal.   This  call  uses the primary output
   designator (that is, the user's terminal) as the destination  for  the
   byte;   thus,  the  user's  program  does  not  have  to  specify  the
   destination.  The source of the byte being written is  accumulator  1;
   therefore,  the  user's program must place the byte right-justified in
   AC1 before the call.


                                    2-8
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


   After execution of the PBOUT% call, control returns to the instruction
   following  the  PBOUT%.   If  execution of the call is successful, the
   byte is written to the user's terminal.  If execution of the  call  is
   not successful, an illegal instruction trap is generated, as explained
   in Section 1.2.2.



   2.9  READING A STRING
   2.9  READING A STRING

   Up to this point, monitor calls have been  presented  for  printing  a
   string,  reading  and  writing  an  integer, and reading and writing a
   byte.  The next call  to  be  discussed  obtains  a  string  from  the
   terminal and, in addition, allows the user at the terminal to edit his
   input as he is typing it.

   The RDTTY% (Read from Terminal) monitor  call  reads  input  from  the
   user's  terminal  (that  is,  from  .PRIIN) into the program's address
   space.  Input is read until  the  user  either  types  an  appropriate
   terminating   (break)  character  or  inputs  the  maximum  number  of
   characters allowed in the  string,  whichever  occurs  first.   Output
   generated  as  a  result of character editing is printed on the user's
   terminal (that is, output to .PRIOU).

   The RDTTY% call handles the following editing functions:

        1.  Delete the last character in the string if the  user  presses
            the DELETE key while typing his input.

        2.  Delete back to the last punctuation character in  the  string
            if the user types CTRL/W while typing his input.

        3.  Delete the current line if the user types CTRL/U while typing
            his input.

        4.  Retype the current line if the user types CTRL/R while typing
            his input.

   Because the RDTTY% call can handle these editing functions, a  program
   can  accept  input  from  the  terminal  and  allow  this  input to be
   corrected by the user as he is typing it.  For this reason, the  RDTTY
   call  should be used to read input from the terminal before processing
   that input with calls such as NIN%.

   The RDTTY% call accepts three words of arguments in AC1 through AC3.

        AC1:   pointer to area in program's address space where input  is
               to be placed.  This area is called the text input buffer.

        AC2:   control bits in the left half, and maximum number of bytes
               in the text input buffer in the right half.



                                    2-9
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


        AC3:   pointer to buffer for text to be output before the  user's
               input  if the user types a CTRL/R, or 0 if only the user's
               input is to be output on a CTRL/R.

   The control bits in the left half of AC2  specify  the  characters  on
   which to terminate the input.  These bits are described in Table 2-2.


   Table 2-2:  RDTTY% Control Bits
   Table 2-2:  RDTTY% Control Bits

   ______________________________________________________________________

     Bit       Symbol            Meaning
   ______________________________________________________________________

      0        RD%BRK            Terminate  input  when  user  types  a
                                 CTRL/Z or presses the ESC key.

      1        RD%TOP            Terminate input when user types one of
                                 the following:

                                 CTRL/G
                                 CTRL/L
                                 CTRL/Z
                                 ESC key
                                 RETURN key
                                 Line feed key

      2        RD%PUN            Terminate input when user types one of
                                 the following:

                                 CTRL/A-CTRL/F
                                 CTRL/H-CTRL/I
                                 CTRL/K
                                 CTRL/N-CTRL/Q
                                 CTRL/S-CTRL/T
                                 CTRL/X-CTRL/Y
                                 ASCII codes 34-36
                                 ASCII codes 40-57
                                 ASCII codes 72-100
                                 ASCII codes 133-140
                                 ASCII codes 173-176

                                 The ASCII codes listed above represent
                                 the   punctuation  characters  in  the
                                 ASCII character  set.   Refer  to  the
                                 ASCII  character set table in Appendix
                                              _______   _______   _____
                                 A  of  the   TOPS-20   Monitor   Calls
                                 _________ ______
                                 Reference Manual for these characters.

      3        RD%BEL            Terminate input when  user  types  the
                                 RETURN  or line feed key (that is, end
                                 of line).

                                    2-10
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


      4        RD%CRF            Store only the line feed in the  input
                                 buffer   when  the  user  presses  the
                                 RETURN key.  A  carriage  return  will
                                 still be output to  the  terminal  but
                                 will  not be stored in the buffer.  If
                                 this bit  is  not  set  and  the  user
                                 presses   the  RETURN  key,  both  the
                                 carriage return and the line feed will
                                 be stored as part of the input.

      5        RD%RND            Return to program if the user attempts
                                 to  delete  past  the beginning of his
                                 input.  This  allows  the  program  to
                                 take  control  if  the  user  tries to
                                 delete all of his input.  If this  bit
                                 is not set, the program waits for more
                                 input.

      6                          Reserved for Digital (must be 0).

      7        RD%RIE            Return to program  when  there  is  no
                                 input  (that is, the text input buffer
                                 is empty).  If this bit  is  not  set,
                                 the program waits for more input.

      8                          Reserved for Digital (must be 0).

      9        RD%BEG            Return to user  program  if  the  user
                                 attempts  to edit beyond the beginning
                                 of the input buffer.

      10       RD%RAI            Convert  lower  case  input  to  upper
                                 case.

      11       RD%SUI            Suppress the CTRL/U indication on  the
                                 terminal when a CTRL/U is typed by the
                                 user.  This means  that  if  the  user
                                 types   a  CTRL/U,  XXX  will  not  be
                                 printed and, on display terminals, the
                                 characters  will  not  be deleted from
                                 the screen.  If this bit  is  not  set
                                 and  the user types a CTRL/U, XXX will
                                 be printed and,  if  appropriate,  the
                                 characters  will  be  deleted from the
                                 screen.  In neither case is the CTRL/U
                                 stored in the input buffer.








                                    2-11
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


      15       RD%NED            Disable  editing  characters  in  user
                                 break  mask.  If this bit is set, then
                                 any editing character (^R, ^U, ^V, ^W,
                                 and DELETE) in the user supplied break
                                 mask  does  not   have   its   editing
                                 function.
   ______________________________________________________________________


   If no control bits are set in the left half of AC2, the input will  be
   terminated when the user presses the RETURN or line feed key (that is,
   terminated on an end-of-line condition only).

   The count in the right half of  AC2  specifies  the  number  of  bytes
   available  for storing the string in the program's address space.  The
   input is terminated when this count is exhausted, even if a  specified
   break character has not yet been typed.

   The pointer in AC3 is to the beginning of a buffer containing the text
   to  be output if the user types a CTRL/R.  When this happens, the text
   in this separate buffer is output, followed by any text that has  been
   typed  by the user.  The text in this buffer cannot be edited with any
   of the editing characters (that is, DELETE, CTRL/W,  or  CTRL/U).   If
   the  contents  of  AC3 is zero, then no such buffer exists, and if the
   user types CTRL/R, only the text in the input buffer will be output.

   If execution of the RDTTY% call is successful, the  input  is  in  the
   specified  area  in  the  program's address space.  The character that
   terminated the input is also stored.  (If the terminating character is
   a  carriage  return  followed  by  a  line feed, the line feed is also
   stored.) Control returns to the user's program at the second  location
   following  the  call.  The pointer in AC1 is advanced to the character
   following the last character stored.  The count in the right  half  of
   AC2  is  updated  to  reflect  the  remaining bytes in the buffer, and
   appropriate bits are set in the left half of AC2.  The bits  that  can
   be set on a successful return are:

        Bit 12    RD%BTM         The input was terminated because one  of
                                 the   specified   break  characters  was
                                 typed.  This break character  is  placed
                                 in the input buffer.  If this bit is not
                                 set, the input  was  terminated  because
                                 the byte count was exhausted.

        Bit 13    RD%BFE         Control  was  returned  to  the  program
                                 because  there  is  no  more  input  and
                                 RD%RIE was set in the call.







                                    2-12
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


        Bit 14    RD%BLR         The limit to which the user  can  backup
                                 for editing his input was reached.

   For consistent handling of error returns refer to Section 1.2.2.

   The following example illustrates the recommended method  for  reading
   data  from  the terminal.  This example is essentially the same as the
   one in Section 2.5; however, the RDTTY%  call  is  used  to  read  the
   number  before  the  NIN%  call processes it.  This program stores the
   last error encountered in  location  LASTER  and  therefore  uses  the
   ERJMPR pseudo-op.


           SEARCH MONSYM
           SEARCH MACSYM
           .REQUIRE SYS:MACREL
           AC1==1
           AC2==2
           AC3==3
   START:  RESET%                  ;prepare program environment
           HRROI AC1,PROMPT
           PSOUT%                  ;type prompt
           HRROI AC1,BUFFER        ;location to store number
           MOVEI AC2,BUFLEN*5      ;size of buffer
           HRROI AC3,PROMPT        ;pointer to prompt
           RDTTY%                  ;read number from term. with editing
            ERJMPR ERROR           ;save error code, print message 
           HRROI AC1,BUFFER        ;and halt source designator
           MOVEI AC3,^D10          ;decimal radix
           NIN%                    
            ERJMPR ERROR           ;if input error, print message 
           TMSG <THE OCTAL EQUIVALENT IS >
           MOVEI AC1,.PRIOU        ;and halt destination designator
           MOVEI AC3,^D8           ;octal radix
           NOUT%
            ERJMPR ERROR           ;save error code, print message 
           HALTF%                  ;and halt return to command 
           JRST START              ;language begin again, if continued
   PROMPT: ASCIZ/PLEASE TYPE A DECIMAL NUMBER: /
           BUFLEN==10
   BUFFER: BLOCK BUFLEN
   LASTER: BLOCK 1
   ERROR:  MOVEM AC1,LASTER        ;save error code
           TMSG <
   ?ERROR-TYPE START TO BEGIN AGAIN>;print general error message
           HALTF%                  ;halt
           JRST START              ;start over if continued
           END START






                                    2-13
                    INPUT AND OUTPUT USING THE TERMINAL
                    INPUT AND OUTPUT USING THE TERMINAL


   2.10  SUMMARY
   2.10  SUMMARY

   Data transfers of sequential bytes or text strings can be made to  and
   from the terminal.  The monitor calls for transferring bytes are PBIN%
   and PBOUT% and for transferring strings are PSOUT%  and  RDTTY%.   The
   NIN%  and  NOUT%  monitor  calls can be used for reading and writing a
   number.  In general, the user's program must  specify  a  source  from
   which  the  data is to be obtained and a destination where the data is
   to be placed.   In  the  case  of  terminal  I/O,  the  symbol  .PRIIN
   represents  the  user's  terminal as the source, and the symbol .PRIOU
   represents the user's terminal as the destination.











































                                    2-14












                                 CHAPTER 3
                                 CHAPTER 3

                                USING FILES
                                USING FILES



   3.1  OVERVIEW
   3.1  OVERVIEW

   All information stored in the DECSYSTEM-20  is  kept  in  files.   The
   basic  unit  of storage in a file is a page containing bytes from 1 to
   36 bits in length.  Thus, a sequence of pages constitutes a file.   In
   most  cases,  files have names.  Although all files are handled in the
   same  manner,  certain  operations  are  unavailable  for   files   on
   particular devices.

   Programs can reference files by several methods:

         o  In a sequential byte-by-byte manner.

         o  In a multiple byte or string manner.

         o  In  a  random   byte-by-byte   manner   if   the   particular
            file-storage device allows it.

         o  In a page-mapping or  section-mapping  manner  for  files  on
            disk.

   Byte and string input/output are the most common types of operations.

   Generally, all programs perform I/O by moving bytes of data  from  one
   location  to  another.   For example, programs can move bytes from one
   memory area to another, from memory to  a  disk  file,  and  from  the
   user's  terminal  to  memory.  In addition, a program can map multiple
   512-word pages or 512-page sections from a disk file  into  memory  or
   vice versa.

   Data transfer operations on files require four steps:

        1.  Establishing a correspondence between a file and a  Job  File
            Number (JFN), because all files are referenced by JFNs.

        2.  Opening the file to establish the data mode, access mode, and
            byte  size  and to set up the monitor tables that permit data
            to be accessed.

                                    3-1
                                USING FILES
                                USING FILES


        3.  Transferring data either to or from the file.

        4.  Closing the file to complete any I/O, to update the directory
            if  the file is on the disk, and to release the monitor table
            space used by the file.

   Some operations on files do not require  the  execution  of  all  four
   steps  above.  Examples of these operations are:  deleting or renaming
   a file, or changing the access code or account of  a  file.   Although
   these  operations  do not require all four steps, they do require that
   the file has a JFN associated with it (step 1 above).

   It is possible for disk files on the DECSYSTEM-20 to be simultaneously
   read  or written by any number of processes.  To make sharing of files
   possible, all instances of opening  a  specific  file  in  a  specific
   directory cause a reference to the same data.  Therefore, data written
   into a file by one process can immediately be seen by other  processes
   reading the file.

   Access to files is controlled by the 6-digit (octal) file access  code
   assigned  to a file when it is created.  This code indicates the types
   of access allowed to the file for the three  classes  of  users:   the
   owner  of  the  file, the users with group access to the file, and all
                               _______ ______ _____
   other users.  (Refer to the TOPS-20 User's Guide for more  information
   on the file access codes.) If the user is allowed access to a file, he
   requests the type of access desired when opening  the  file  with  the
   OPENF%  monitor  call (refer to Section 3.4.1) in his program.  If the
   access requested in the OPENF% call does not conflict with the current
   access  to  the  file,  the  user is granted access.  Essentially, the
   current access to the file is set by the first user who opens it.

   Thus, for a user  to  be  granted  access  to  a  specific  file,  two
   conditions must be met:

        1.  The file access code must allow the user to access  the  file
            in the desired manner (for example, read, write).

        2.  The file must not be opened for a conflicting type of access.



   3.2  JOB FILE NUMBER
   3.2  JOB FILE NUMBER

   The Job File Number (JFN) is one of the more important concepts in the
   operating  system  because it serves as the identifier of a particular
   file on a particular device during a  process'  execution.   It  is  a
   small  integer  assigned  by the system upon a request from the user's
   program.  JFNs are usually assigned sequentially starting with 1.






                                    3-2
                                USING FILES
                                USING FILES


   The JFN is valid for the job in which it is assigned and may  be  used
   by  any  process in the job.  The system uses the JFN as an index into
   the table of files associated with the job and always  assigns  a  JFN
   that  is  unique  within the job.  Even though a particular JFN within
   the job can refer to only one file, a single file  can  be  associated
   with  more  than  one JFN.  This occurs when two or more processes are
   using the same file concurrently.  In this case, each of the processes
   will  probably  have a different JFN for the file, but all of the JFNs
   will be associated with the same file.



   3.3  ASSOCIATING A FILE WITH A JFN
   3.3  ASSOCIATING A FILE WITH A JFN

   In order to reference a file, the first step  the  user  program  must
   complete  is  to  associate  the  specific  file  with  a  JFN.   This
   correspondence is established with the GTJFN% (Get  Job  File  Number)
   monitor  call.   One  of  the  arguments  to  this  call is the string
   representing the desired file.  The string can be specified within the
   program  (that  is, come from memory) or can be accepted as input from
   the user's terminal or from another file.  The  string  can  represent
   the complete specification for the file:

   dev:<directory>name.typ.gen;T(temporary);P(protection);A(account);
        (device dependent attributes)

   If you omit any fields of the specification, the  system  can  provide
                                                           _______ ______
   values  for  all  except  the name field.  Refer to the TOPS-20 User's
   _____
   Guide for a complete explanation of the specification for a file.

   Table 3-1 lists the values  the  system  will  assign  to  fields  not
   specified by the input string.


   Table 3-1:  Standard System Values for File Specifications
   Table 3-1:  Standard System Values for File Specifications

   ______________________________________________________________________

     Field                       Value
   ______________________________________________________________________

     Device                      DSK:

     Directory                   Directory to which user  is  currently
                                 connected.

     Name                        No  default;  this   field   must   be
                                 specified.

     Type                        Null.




                                    3-3
                                USING FILES
                                USING FILES


     Generation number           The highest existing generation number
                                 if  the  file  is  an input file.  The
                                 next higher generation number  if  the
                                 file is an output file.

     Protection                  Protection of next lower generation of
                                 file,   if   one   exists;  otherwise,
                                 protection   as   specified   in   the
                                 directory.

     Account                     Account specified when user logged in.
   ______________________________________________________________________


   If the string specified identifies a single file, the monitor  returns
   a  JFN that remains associated with that file until either the process
   releases the JFN or the job logs off the system.  After the assignment
   of  the  JFN  is  complete,  the  user's  program  uses the JFN in all
   references to that file.

   The user's program can set up either the short or the long form of the
   GTJFN%  monitor  call.   The  long form of the GTJFN% call requires an
   argument block; the short form does not.  The long form of GTJFN%  has
   functions and flexibility not available in the short form of the call.
   The short form of GTJFN% allows a file specification  to  be  obtained
   from a string in memory or from a file, but not from both.  Fields not
   specified by the input are taken from the standard system  values  for
   those  fields  (refer to Table 3-1).  This form is sufficient for most
   uses of the call.  The long form allows a  file  specification  to  be
   obtained  from  both a string in memory and a file.  If both are given
   as arguments, the string is used first, and then the file is  used  if
   more  fields are needed to complete the specification.  This form also
   allows the user's program to specify nonstandard values to be used for
   fields not given and to request the assignment of a specific JFN.



   3.3.1  GTJFN% Monitor Call
   3.3.1  GTJFN% Monitor Call

   The GTJFN% monitor call assigns a  JFN  to  the  specified  file.   It
   accepts  two  words  of arguments.  These argument words are different
   depending on the form  of  GTJFN%  being  used.   The  user's  program
   indicates  the desired GTJFN% form by setting bit 17(GJ%SHT) of AC1 to
   1 for the short form or by clearing bit 17(GJ%SHT) for the long form.



   3.3.1.1  Short Form of GTJFN%
   3.3.1.1  Short Form of GTJFN% - The short form of the  GTJFN%  monitor
   call requires the following two words of arguments.





                                    3-4
                                USING FILES
                                USING FILES


                 0                        17 18                       35
                !=======================================================!
        AC1     !         flag bits         ! default generation number !
                !=======================================================!


                 0                                                    35
                !=======================================================!
        AC2     !     source designator for file specification per      !
                !          bit 16  (GJ%FNS) of AC1                      !
                !=======================================================!


   The flag bits that can be specified in AC1 are described in Table 3-2.


   Table 3-2:  GTJFN% Flag Bits
   Table 3-2:  GTJFN% Flag Bits

   ______________________________________________________________________

     Bit       Symbol            Meaning
   ______________________________________________________________________

      0        GJ%FOU            The file specification given is to  be
                                 assigned  the  next  higher generation
                                 number.  This bit indicates that a new
                                 version of a file is to be created and
                                 is normally set if  the  file  is  for
                                 output use.

      1        GJ%NEW            The file specification given must  not
                                 refer  to  an  existing file (that is,
                                 the file must be a new file).

      2        GJ%OLD            The  file  specification  given   must
                                 refer  to  an existing file.  This bit
                                 has no effect  on  a  parse-only  JFN.
                                 (See bit GJ%OFG.)

      3        GJ%MSG            One of the appropriate messages is  to
                                 be     printed    after    the    file
                                 specification   is   obtained.     The
                                 message  is  printed  only if the user
                                 types the ESC  key  to  end  his  file
                                 specification  (that  is,  he is using
                                 recognition input).

                                 [NEW FILE]
                                 [NEW GENERATION]
                                 [OLD GENERATION]
                                 [OK] if GJ%CFM (bit 4) is off
                                 [CONFIRM] if GJ%CFM (bit 4) is on


                                    3-5
                                USING FILES
                                USING FILES


      4        GJ%CFM            Confirmation from  the  user  will  be
                                 required   to  verify  that  the  file
                                 specification obtained is correct.  To
                                 confirm  the  file  specification, the
                                 user can press the RETURN key.

      5        GJ%TMP            The  file  specified  is   to   be   a
                                 temporary file.

      6        GJ%NS             Only the first file specification in a
                                 multiple logical name assignment is to
                                 be searched for the file.

      7        GJ%ACC            The  JFN  specified  is  not   to   be
                                 accessed by inferior processes in this
                                 job.  However, any process can  access
                                 the file by acquiring a different JFN.
                                 To  prevent  the   file   from   being
                                 accessed   by   other  processes,  the
                                 user's program can set OF%RTD (bit 29)
                                 in  the  OPENF  call (refer to Section
                                 3.4.1).

      8        GJ%DEL            The  file  specified  is  not  to   be
                                 considered  as  deleted, even if it is
                                 marked as deleted.

      9-10     GJ%JFN            These bits are off in the  short  form
                                 of  the  GTJFN  call (refer to Section
                                 3.3.1.2 for their description).

     11        GJ%IFG            The  file   specification   given   is
                                 allowed  to  have  one  or more of its
                                 fields  specified  with   a   wildcard
                                 character  (* or %).  This bit is used
                                 to process a group  of  files  and  is
                                 generally  used  for input files.  The
                                 monitor verifies  that  at  least  one
                                 value   exists  for  each  field  that
                                 contains a wildcard  and  assigns  the
                                 JFN to the first file in the group.

                                 The monitor also verifies that  fields
                                 not  containing  wildcards represent a
                                 new  or  old  file  according  to  the
                                 setting of GJ%NEW and GJ%OLD.

     12        GJ%OFG            The JFN is to be associated  with  the
                                 given  file  specification string only
                                 and  not  to  the  actual  file.   The
                                 string    may   contain   a   wildcard
                                 character (* or %) in one or  more  of


                                    3-6
                                USING FILES
                                USING FILES


                                 its fields.  It is checked for correct
                                 punctuation between fields, but is not
                                 checked for the validity of any field.
                                 This bit allows a JFN to be associated
                                 with  a file specification even if the
                                 file specification does not  refer  to
                                 an  actual  file.   The  JFN  returned
                                 cannot be used to refer to  an  actual
                                 file  (for  example, cannot be used in
                                 an OPENF call) but  can  be   used  to
                                 obtain  the  original input string via
                                 the  JFNS  monitor  call   (refer   to
                                 Section 3.7.2).

     13        GJ%FLG            Flags are to be returned in  the  left
                                 half of AC1 on a successful return.

     14        GJ%PHY            Logical  names   specified   for   the
                                 current  job are to be ignored and the
                                 physical device is to be used.

     15        GJ%XTN            This bit is off in the short  form  of
                                 the   GTJFN  call  (refer  to  Section
                                 3.3.1.2 for its description).

     16        GJ%FNS            The  contents  of  AC2   are   to   be
                                 interpreted as follows:

                                 1.  If this bit is on, AC2 contains an
                                     input  JFN in the left half and an
                                     output JFN in the right half.  The
                                     input  JFN  is  used to obtain the
                                     file    specification    to     be
                                     associated   with  the  JFN.   The
                                     output JFN is used to indicate the
                                     destination for printing the names
                                     of any  fields  being  recognized.
                                     To  omit  either  JFN,  the user's
                                     program must  specify  the  symbol
                                     .NULIO (377777).

                                 2.  If this bit is off, AC2 contains a
                                     pointer to a string in memory that
                                     specifies   the   file    to    be
                                     associated with the JFN.

     17        GJ%SHT            This bit must  be  on  (set)  for  the
                                 short form of the GTJFN% call; it must
                                 be off for the long form of the call.





                                    3-7
                                USING FILES
                                USING FILES


     18-35                       The  generation  number  of  the  file
                                 (between  1  and 377777) or one of the
                                 following:

                                 0(.GJDEF)   to indicate that the  next
                                             higher  generation  number
                                             of the file is to be  used
                                             if  GJ%FOU  (bit 0) is on,
                                             or to  indicate  that  the
                                             highest           existing
                                             generation number  of  the
                                             file  is  to  be  used  if
                                             GJ%FOU  is   off.    (This
                                             value  is  usually used in
                                             this field.)

                                 -1(.GJNHG)  to indicate that the  next
                                             higher  generation  number
                                             of the file is to be  used
                                             if no generation number is
                                             supplied.

                                 -2(.GJLEG)  to   indicate   that   the
                                             lowest existing generation
                                             number of the file  is  to
                                             be used.

                                 -3(.GJALL)  to   indicate   that   all
                                             generation  numbers (*) of
                                             the file are  to  be  used
                                             and  that the JFN is to be
                                             assigned to the first file
                                             in the group.  (Bit GJ%IFG
                                             must be set.)
   ______________________________________________________________________



















                                    3-8
                                USING FILES
                                USING FILES


   If the GTJFN% call is given with the appropriate flag bit set  (GJ%IFG
   or  GJ%OFG), the file specification given as input can have a wildcard
   character (either an asterisk or a  percent  sign)  appearing  in  the
   directory,  name, type, or generation number field.  (The percent sign
   cannot appear in the generation number field.) The wildcard  character
   is  interpreted as matching any existing occurrence of the field.  For
   example, the specification

        <LIBRARY>*.MAC

   identifies all the files with the file  type  .MAC  in  the  directory
   named <LIBRARY>.  The specification

        <LIBRARY>MYFILE.FO%

   identifies all the files in directory <LIBRARY> with the  name  MYFILE
   and  a three-character file type in which the first two characters are
   .FO.   Upon  completion  of  the  GTJFN  call,  the  JFN  returned  is
   associated  with  the  first  file found in the group according to the
   following:

         o  in numerical order by directory number

         o  in alphabetical order by filename

         o  in alphabetical order by file type

         o  in ascending numerical order by generation number

   The GNJFN% (Get Next JFN) monitor call can then be given to assign the
   JFN to the next file in the group (refer to Section 3.7.3).  Normally,
   a program that accepts wildcard characters  in  a  file  specification
   will  successively reference all files in the group using the same JFN
   and not obtain another JFN for each one.

   If execution of the GTJFN% call is  not  successful  because  problems
   were  encountered  in performing the call, the JFN is not assigned and
   an error code is returned in the right half of AC1.  The execution  of
   the program continues at the instruction following the GTJFN% call.

   If execution of the GTJFN% call is successful,  the  JFN  assigned  is
   returned in the right half of AC1 and various bits are set in the left
   half, if flag bits 11, 12, or 13 were  on  in  the  call.   (The  bits
   returned  on a successful call are described in Table 3-3.) If bit 11,
   12, or 13 was not on in the call, the left half of AC1 is  zero.   The
   execution of the program continues at the second instruction after the
   GTJFN% call.







                                    3-9
                                USING FILES
                                USING FILES


   Table 3-3:  Bits Returned on GTJFN% Call
   Table 3-3:  Bits Returned on GTJFN% Call

   ______________________________________________________________________

     Bit       Symbol            Meaning
   ______________________________________________________________________

      0        GJ%DEV            The   device   field   of   the   file
                                 specification     contains    wildcard
                                 characters.

      1        GJ%UNT            The   unit   field   of    the    file
                                 specifications    contains    wildcard
                                 characters.  This  bit  is  never  set
                                 because  wildcard  characters  are not
                                 allowed in unit fields.

      2        GJ%DIR            The  directory  field  of   the   file
                                 specification     contains    wildcard
                                 characters.

      3        GJ%NAM            The  filename  field   of   the   file
                                 specification     contains    wildcard
                                 characters.

      4        GJ%EXT            The  file  type  field  of  the   file
                                 specification     contains    wildcard
                                 characters.

      5        GJ%VER            The generation  number  field  of  the
                                 file  specification  contains wildcard
                                 characters.

      6        GJ%UHV            The  file   used   has   the   highest
                                 generation number because a generation
                                 number of 0 was given in the call.

      7        GJ%NHV            The file  used  has  the  next  higher
                                 generation number because a generation
                                 number of 0 or -1  was  given  in  the
                                 call.

      8        GJ%ULV            The   file   used   has   the   lowest
                                 generation number because a generation
                                 number of -2 was given in the call.

      9        GJ%PRO            The  protection  field  of  the   file
                                 specification was given.

     10        GJ%ACT            The  account   field   of   the   file
                                 specification was given.



                                    3-10
                                USING FILES
                                USING FILES


     11        GJ%TFS            The  file  specification  is   for   a
                                 temporary file.

     12        GJ%GND            Files  marked  for  deletion  are  not
                                 considered   when  assigning  JFNs  in
                                 subsequent calls.  This bit is set  if
                                 GJ%DEL was not set in the call.

     13        GJ%NOD            The  node  name  field  of  the   file
                                 specification was given.

     17        GJ%GIV            Invisible files  were  not  considered
                                 when assigning JFNs.
   ______________________________________________________________________


   Examples of the short form of the GTJFN% monitor call are shown in the
   following paragraphs.

   The following sequence of instructions is used  to  obtain,  from  the
   user's terminal, the specification of an existing file.

        MOVX AC1,GJ%OLD+GJ%FNS+GJ%SHT
        MOVE AC2,[.PRIIN,,.PRIOU]
        GTJFN%

   The bits specified for AC1 indicate that the file specification  given
   must  refer  to an existing file (GJ%OLD), that the file specification
   is to be accepted from the input JFN in AC2  (GJ%FNS),  and  that  the
   short  form  of  the  GTJFN% call is being used (GJ%SHT).  Because the
   right half of AC1 is zero, the standard  generation  number  algorithm
   will be used.  In this GTJFN% call, the file with the highest existing
   generation number is used.  Because GJ%FNS is set in AC1, the contents
   of  AC2  are interpreted as containing an input JFN and an output JFN.
   In this example, the file specification is obtained from the  terminal
   (.PRIIN).

   The following sequence of instructions is used  to  obtain,  from  the
   user's  terminal,  the  specification of an output file and to require
   confirmation from the  user  once  the  file  specification  has  been
   obtained.

        MOVX AC1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT
        MOVE AC2,[.PRIIN,,.PRIOU]
        GTJFN%

   In this example, the bits specified for AC1 indicate that

         o  the file obtained is to be an output file (GJ%FOU),

         o  after the file specification is obtained, a message is to  be
            typed (GJ%MSG),


                                    3-11
                                USING FILES
                                USING FILES


         o  the user is required to confirm the file  specification  that
            was obtained (GJ%CFM),

         o  the file specification is to be obtained from the  input  JFN
            in AC2 (GJ%FNS),

         o  the short form of the GTJFN% call is being used (GJ%SHT).

   Because the right half of AC1 is zero, the generation number given  to
   the  file  will  be  one  greater  than  the highest generation number
   existing for the  file.   The  contents  of  AC2  are  interpreted  as
   containing  an  input  JFN  and an output JFN because GJ%FNS is set in
   AC1.

   The following sequence of instructions is used to obtain the  name  of
   an existing file from a location in the user's program.

        MOVX AC1,GJ%OLD+GJ%SHT
        MOVE AC2,[POINT 7,NAME]
        GTJFN%
           .
           .
           .

   NAME:ASCIZ/MYFILE.TXT/

   The bits specified for AC1 indicate that the file obtained is to be an
   existing  file  (GJ%OLD) and that the short form of the GTJFN% call is
   being used (GJ%SHT).  Since the right half of AC1 is  zero,  the  file
   with  the  highest  generation number will be used.  Because GJ%FNS is
   not set, the contents of AC2 are interpreted as containing  a  pointer
   to  a  string  in memory that specifies the file to be associated with
   the JFN.  The setup  of  AC2  indicates  that  the  string  begins  at
   location  NAME in the user's program.  The file specification obtained
   from location NAME is MYFILE.TXT.

   An alternate way of specifying the same file is the sequence

        MOVX AC1,GJ%OLD+GJ%SHT
        HRROI AC2,[ASCIZ/MYFILE.TXT/]
        GTJFN%



   3.3.1.2  Long Form of GTJFN%
   3.3.1.2  Long Form of GTJFN% - The long form  of  the  GTJFN%  monitor
   call requires the following two words of arguments:


              0                        17 18                       35
             !=======================================================!
      AC1    !             0             ! address of argument table !
             !=======================================================!


                                    3-12
                                USING FILES
                                USING FILES


              0                                                    35
             !=======================================================!
      AC2    !   pointer to ASCIZ file specification string, or 0    !
             !=======================================================!


   The argument block for the long form is described in Table 3-4.


   Table 3-4:  Long Form GTJFN% Argument Block
   Table 3-4:  Long Form GTJFN% Argument Block

   ______________________________________________________________________

     Word      Symbol            Meaning
   ______________________________________________________________________

      0        .GJGEN            Flag bits appear in the left half  and
                                 generation number appears in the right
                                 half.

      1        .GJSRC            An input JFN appears in the left  half
                                 and an output JFN appears in the right
                                 half.  To omit either JFN, the  user's
                                 program must specify the symbol .NULIO
                                 (377777).

      2        .GJDEV            Pointer to ASCIZ string that specifies
                                 the  device  to  be  used when none is
                                 given.  If this word is 0, DSK will be
                                 used.

      3        .GJDIR            Pointer to ASCIZ string that specifies
                                 the  directory to be used when none is
                                 given.  If this word is 0, the  user's
                                 connected directory will be used.

      4        .GJNAM            Pointer to ASCIZ string that specifies
                                 the  filename  to be used when none is
                                 given.  If this word is 0,  the  input
                                 must specify the filename.

      5        .GJEXT            Pointer to ASCIZ string that specifies
                                 the  file type to be used when none is
                                 given.  If this word is 0, a null type
                                 will be used.

      6        .GJPRO            Pointer to ASCIZ string  or  3B2+octal
                                 protection  code.  This word indicates
                                 the protection to be used when none is
                                 given.    If   this  word  is  0,  the
                                 protection   as   specified   in   the
                                 directory will be used.


                                    3-13
                                USING FILES
                                USING FILES


      7        .GJACT            Pointer to ASCIZ string or 3B2+decimal
                                 account  number.   This word indicates
                                 the account to be used  when  none  is
                                 given.  If this word is 0, the account
                                 specified when the user logged in will
                                 be used.

     10        .GJJFN            The  JFN  to  assign   to   the   file
                                 specification  if  flag  bit GJ%JFN is
                                 set in word .GJGEN  (word  0)  of  the
                                 argument block.

     11-17                       Additional words allowed if  flag  bit
                                 GJ%XTN  (bit 15) is set in word .GJGEN
                                 (word 0) of the argument block.  These
                                 additional   words   are   used   when
                                 performing command input  parsing  and
                                                        _______ _______
                                 are  described  in the TOPS-20 Monitor
                                 _____ _________ ______
                                 Calls Reference Manual.
   ______________________________________________________________________


   The flag bits accepted in the left half of  .GJGEN  (word  0)  of  the
   argument block are the same as those accepted in the short form of the
   GTJFN% call.  The entire set of flag bits is listed in Table 3-2.

   The generation number values accepted in  the  right  half  of  .GJGEN
   (word  0)  of  the argument block can be 0, -1, -2, -3, or a specified
   number, although 0 is the normal case.  Refer to Bits 18-35  of  Table
   3-2 for explanations of these values.

   If execution of the GTJFN% call is successful,  the  JFN  assigned  is
   returned in the right half of AC1 and various bits are set in the left
   half if flag bits 11, 12 or 13 were on in the call.   Refer  to  Table
   3-3  for  the  explanations  of  the  bits returned.  Execution of the
   program continues at the second instruction following the call.

   If execution of the GTJFN call is  not  successful,  the  JFN  is  not
   assigned  and an error code is returned in the right half of AC1.  The
   execution of the program continues at the  instruction  following  the
   GTJFN% call.

   The following sequence of instructions obtains a specification for  an
   existing  file  from  the user's terminal, assigns the JFN to the next
   higher generation of that file, and specifies  default  fields  to  be
   used if the user omits a field when he gives his file specification.

             MOVEI AC1,JFNTAB
             SETZ AC2,
             GTJFN%
              .
              .
              .

                                    3-14
                                USING FILES
                                USING FILES


   JFNTAB:   GJ%FOU
             XWD .PRIIN,.PRIOU
             0
             POINT 7,[ASCIZ/TRAIN/]   ;default directory
             0
             POINT 7,[ASCIZ/MEM/]     ;default file type
             0
             0
             0


   The address of the argument table for  the  GTJFN%  call  (JFNTAB)  is
   given  in  the  right  half  of  AC1.   AC2 contains 0, which means no
   pointer to a string is given; thus, fields for the file  specification
   will  be  taken  only from the user's terminal.  The first word of the
   argument block contains a flag bit for  the  GTJFN%  call.   This  bit
   (GJ%FOU)  indicates  that  the  next higher generation number is to be
   assigned to the file.  The second word of the argument block indicates
   that  the  file  specification  is  to  be  obtained  from  the user's
   terminal, and any output  generated  because  of  the  user  employing
   recognition  is  to  be printed on his terminal.  If the user does not
   supply a directory  name  as  part  of  his  file  specification,  the
   directory  <TRAIN> will be used.  And if the user does not give a file
   type, the type MEM will be used.  If the user omits other fields  from
   his specification, the system standard value (refer to Table 3-1) will
   be used.



   3.3.1.3  Summary of GTJFN%
   3.3.1.3  Summary of GTJFN% - The GTJFN% monitor call  is  required  to
   associate a JFN with a particular file.  In most cases, the short form
   of the GTJFN% call is sufficient for  establishing  this  association.
   However, the long form is more powerful because it provides the user's
   program more control over the file  specification  that  is  obtained.
   The following summary compares the characteristics of the two forms of
   the GTJFN% monitor call.


           _____ ____                         ____ ____
           Short Form                         Long Form

        Assigns a JFN to a file.           Assigns a JFN to a file.
           System decides the JFN             User program may request
           to assign.                         a particular JFN.

        Accepts the file specification     Accepts the file specification
           from a string in memory            from a string in memory
           or a file.                         and a file.

        Uses standard system values        Allows user-supplied values
           for fields not given               to be used for fields not
           in the file                        given in the file
           specification.                     specification.


                                    3-15
                                USING FILES
                                USING FILES


   3.4  OPENING A FILE
   3.4  OPENING A FILE

   Once a JFN has been obtained for a file, the user's program must  open
   the  file  in order to transfer data.  The user's program supplies the
   JFN of the file to be opened and a word of bits indicating the desired
   byte size, data mode, and access to the file.

   The desired access to the file is specified by a separate bit for each
   type  of  access.  The file is successfully opened only if the desired
   access does not conflict with the current access to the file (refer to
   Section  3.1).   For example, if the user requests both read and write
   access to the file, but write access is not allowed, then the file  is
   not opened for this user.  The allowed types of access to a file are:

         o  Read access.  The file can be  read  with  byte,  string,  or
            random input.

         o  Write access.  The file can be written with byte, string,  or
            random output.

         o  Append access.  The file can be written only with  sequential
            byte  or  dump output, and the current byte pointer (refer to
            Section 3.5.1) cannot be changed.  The  initial  position  of
            the file pointer is at the end of the file.

         o  Frozen access.  The file can be concurrently accessed  by  at
            most  one  user  writing the file, but by any number of users
            reading the file.  This is the default access to a file.

         o  Thawed access.  The file can be accessed even if other  users
            are reading and writing the file.

         o  Restricted access.  The file cannot be  accessed  if  another
            user already has opened the file.

         o  Unrestricted read access.  The file can be read regardless of
            what other users might be doing with the file.



   3.4.1  OPENF% Monitor Call
   3.4.1  OPENF% Monitor Call

   The OPENF% (Open File)  monitor  call  opens  a  specified  file.   It
   requires the following two words of arguments.










                                    3-16
                                USING FILES
                                USING FILES


              0                        17 18                       35
             !=======================================================!
      AC1    !             0             ! JFN of file to be opened  !
             !=======================================================!


             0       5 6   9             18               30 31   35
             !=======================================================!
      AC2    !  byte   !data !     0     !    access bits    !   0   !
             !  size   !mode !           !                   !       !
             !=======================================================!


   If the left half of AC1 is not 0, the contents of AC1  is  interpreted
   as  a  pointer  to  a  string,  not  as  a JFN.  If the user's program
   requests bits returned in AC1 from the GTJFN% call, these bits must be
   cleared before executing the OPENF% call.

   The byte size (OF%BSZ) in AC2 specifies the number  of  bits  in  each
   byte of the file and can be between 1 and 36 (decimal).  If this field
   is 0 a byte size of 36 (decimal) is assumed.

   The file data mode field (OF%MOD) usually has one of two values:

        Value                                   Meaning

          0                 Normal data mode of the file (that  is,  byte
                            I/O).  Dump I/O is illegal.

          17                Dump mode (that  is,  unbuffered  word  I/O).
                            Byte  I/O  is  illegal  and  the byte size is
                            ignored.

   The access bits are described in Table 3-5.


   Table 3-5:  OPENF% Access Bits
   Table 3-5:  OPENF% Access Bits

   ______________________________________________________________________

     Bit       Symbol            Meaning
   ______________________________________________________________________

     0-5       OF%BSZ            Byte size (maximum of 36 decimal).

     6-9       OF%MOD            Data mode in which to open file.

     18        OF%HER            Halt  on  the  occurrence  of  an  I/O
                                 device    or   medium   error   during
                                 subsequent I/O to the file.   If  this
                                 bit  is  not set, a software interrupt
                                 is generated if  a  device  or  medium
                                 error occurs during subsequent I/O.

                                    3-17
                                USING FILES
                                USING FILES


     19        OF%RD             Allow read access.

     20        OF%WR             Allow write access.

     21        OF%EX             Allow execute access.

     22        OF%APP            Allow append access.

     23        OF%RDU            Allow unrestricted read access.

     24                          Reserved for Digital.

     25        OF%THW            Allow thawed access.  If this  bit  is
                                 not set, the file is opened for frozen
                                 access.

     26        OF%AWT            Block (that is,  temporarily  suspend)
                                 the  program  until access to the file
                                 is permitted.

     27        OF%PDT            Do not update the access dates of  the
                                 file.

     28        OF%NWT            Return an error if access to the  file
                                 cannot be permitted.

     29        OF%RTD            Allow access to the file to  only  one
                                 process (that is, restricted access).

     30        OF%PLN            Do not check for line numbers  in  the
                                 file.

     31        OF%DUD            Suppress system updating  of  modified
                                 pages  in  memory  to  thawed files on
                                 disk unless CLOSF or UFPGS issued.

     32        OF%OFL            Open device even if off-line.

     33        OF%FDT            Force update of .FBREF (last read)  in
                                 FDB and increment RH of .FBCNT (number
                                 of references).

     34        OF%RAR            Wait if file off-line.
   ______________________________________________________________________


   If bits OF%AWT and OF%NWT are both off, an error code is  returned  if
   access  to  the file cannot be permitted (that is, the action taken is
   identical to OF%NWT being on).





                                    3-18
                                USING FILES
                                USING FILES


   If execution of the OPENF% monitor call is  successful,  the  file  is
   opened,  and  the  execution  of  the  program continues at the second
   instruction after the OPENF% call.

   If execution of the OPENF% call is not successful,  the  file  is  not
   opened,  and  an  error code is returned in AC1.  The execution of the
   program continues at the next instruction after the OPENF% call.

   Two samples of the OPENF% call follow.

   The sequence of instructions below opens a file for input.

        HRRZ AC1,JFNEXT
        MOVX AC2,FLD(44,OF%BSZ)+OF%RD+OF%PLN
        OPENF%

   The JFN of the  file  to  be  opened  is  contained  in  the  location
   indicated  by the address in AC1 (JFNEXT).  The bits specified for AC2
   indicate that the byte size is  one  word  FLD(44,OF%BSZ),  that  read
   access  is being requested to the file (OP%RD), and that no check will
   be made for line numbers in the file; that is, the line  numbers  will
   not  be  discarded  (OF%PLN).  Because bit OF%THW is not set, the file
   can be accessed for reading by any number of processes.

   The following sequence of instructions can be used to open a file  for
   output.

        MOVE AC1,JFN
        MOVX FLD(7,OF%BSZ)+OF%HER+OF%WR+OF%AWT
        OPENF%

   The right half of AC1 contains the address that has  the  JFN  of  the
   file  to be opened.  The bits specified for AC2 indicate that the byte
   size is 7-bit bytes FLD(7,OF%BSZ), that the program is  to  be  halted
   when  an  I/O  error occurs in the file (OF%HER), that write access is
   being requested to the file (OF%WR), and that the  program  is  to  be
   blocked  if  access cannot be granted (OF%AWT).  Because bit OF%THW is
   not set, if another user has been granted write access  to  the  file,
   this user's program will be blocked until access can be granted.



   3.5  TRANSFERRING DATA
   3.5  TRANSFERRING DATA

   Data transfers of  sequential  bytes  are  the  most  common  form  of
   transfer and can be used with any file.  For disk files, nonsequential
   bytes and entire pages can also be transferred.







                                    3-19
                                USING FILES
                                USING FILES


   3.5.1  File Pointer
   3.5.1  File Pointer

   Every open file is associated with a pointer that indicates  the  last
   byte  read  from  or  written to the file.  When the file is initially
   opened, this pointer is normally positioned before  the  beginning  of
   the  file  so  that  the first data operation will reference the first
   byte in the file.  The pointer is then advanced through  the  file  as
   data  is  transferred.  However, if the file is opened for append-only
   access (bit OF%APP set in the OPENF% call), the pointer is  positioned
   after  the  last  byte  of  the  file.   This  allows  the first write
   operation to append data to the end of the file.

   For disk files, the pointer may be repositioned arbitrarily throughout
   the  file,  such as in the case of nonsequential data transfers.  When
   the pointer is positioned beyond the end of the file,  an  end-of-file
   indication  is  returned  when  the  program attempts a read operation
   using byte input.  When the program performs a write operation  beyond
   the  end  of  the file using byte output, the end-of-file indicator is
   updated to point to the end of the new data.  However, if the  program
   writes  pages  beyond  the end of the file with the PMAP% monitor call
   (refer to section 3.5.6), the byte count is not  updated.   Therefore,
   it  is  possible  for  a  file  to  contain  pages  of data beyond the
   end-of-file indicator.  To allow sequential I/O to be performed  later
   to  the  file, the program should update the byte count before closing
   the file.  (Refer to  the  CHFDB%  monitor  call  description  in  the
   _______ _______ _____ _________ ______
   TOPS-20 Monitor Calls Reference Manual.)



   3.5.2  Source and Destination Designators
   3.5.2  Source and Destination Designators

   Because I/O operations occur by  moving  data  from  one  location  to
   another, the user's program must supply a source and a destination for
   any I/O operation.  The  most  commonly-used  source  and  destination
   designators are the following:

        1.  A JFN associated with a particular file.   The  JFN  must  be
            previously  obtained  with  the GTJFN% or GNJFN% monitor call
            before it can be used.

        2.  The primary input and output designators .PRIIN  and  .PRIOU,
            respectively  (refer  to  Section  2.2).   These  designators
            should be used when referring to the terminal.

        3.  A byte pointer to the beginning of the string of bytes in the
            program's  address  space that is being read or written.  The
            byte pointer can take one of two forms:

             o  A word with a -1 in the left half and an address  in  the
                right half.  This form is used to designate a 7-bit ASCIZ
                string starting in the left-most byte  of  the  specified
                address.   A word in this form is functionally equivalent
                to a word assembled by the POINT 7,ADR pseudo-op.

                                    3-20
                                USING FILES
                                USING FILES


             o  A full word byte pointer with a byte size of 7 bits.

   Most monitor calls dealing with strings deal specifically  with  ASCII
   strings.  Normally, ASCII strings are assumed to terminate with a byte
   of 0 (that is, are assumed to be ASCIZ strings).  However  some  calls
   optionally  accept  an  explicit  byte  count and/or terminating byte.
   These calls are generally ones that handle non-ASCII strings and  byte
   sizes other than 7 bits.



   3.5.3  Transferring Sequential Bytes
   3.5.3  Transferring Sequential Bytes

   The BIN% (Byte Input) and BOUT% (Byte Output) monitor calls  are  used
   for sequential byte transfers.  The BIN% call takes the next byte from
   the given source and places it in AC2.  The BOUT% call takes the  byte
   from AC2 and writes it to the given destination.  The size of the byte
   is that given in the OPENF% call for the file.

   The BIN% monitor call accepts a source designator  in  AC1,  and  upon
   successful  execution of the call, the byte is right-justified in AC2.
   If execution of the call is not  successful,  an  illegal  instruction
   trap  is  generated.   Control  returns  to  the user's program at the
   instruction following the BIN% call.   If  the  end  of  the  file  is
   reached,  AC2  contains  0 instead of a byte.  The program can process
   this end-of-file condition if a jump style error return  is  the  next
   instruction following the BIN% call.

   The BOUT% monitor call accepts a destination designator in AC1 and the
   byte  to be output, right-justified in AC2.  Upon successful execution
   of the call, the byte is written to the destination.  If execution  of
   the  call  is not successful, an illegal instruction trap is generated
   Control returns to the user's program at the instruction following the
   BOUT% call.

   The following sequence shows the transferring of bytes from  an  input
   file to an output file.  The bytes are read from the file indicated by
   INJFN and written to the file indicated by OUTJFN.

        LOOP:  MOVE 1,INJFN      ;get source designator from INJFN
               BIN%              ;read a byte from the source
               ERJMP DONE        ;check for end of file, if 0
        LOOP2: MOVE 1,OUTJFN     ;get destination from OUTJFN
               BOUT%             ;write the byte to the destination
               JRST LOOP         ;continue until 0 byte is found
        DONE:  GTSTS%            ;obtain status of source
               TXNN 2,GS%EOF     ;test for end of file
               JRST NOTYET       ;no, test for 0 in input file
               :                 ;yes, process end of file condition
        NOTYET:MOVEI 2,0         ;0 in input file
               JRST LOOP2



                                    3-21
                                USING FILES
                                USING FILES


   3.5.4  Transferring Strings
   3.5.4  Transferring Strings

   The SIN% (String Input) and SOUT% (String Output)  monitor  calls  are
   used  for string transfers.  These calls transfer either a string of a
   specified number of bytes or a string terminated with a specific byte.

   The SIN% monitor call reads a string from the  specified  source  into
   the program's address space.  The call accepts four words of arguments
   in AC1 through AC4.

        AC1:   source designator

        AC2:   pointer to area in program's address space

        AC3:   count of number of bytes to read, or 0

        AC4:   byte on which to terminate input (optional)

   The contents of AC3 are interpreted as the  number  of  characters  to
   read.

         o  If AC3 is 0, then reading continues until a 0 byte  is  found
            in the input.

         o  If AC3 is positive, then reading continues until  either  the
            specified  number  of  bytes is read, or a byte equal to that
            given in AC4 is found in the input, whichever occurs first.

         o  If AC3 is negative, then reading continues  until  minus  the
            specified number of bytes is read.

   The contents of AC4 needs to be specified only if the contents of  AC3
   is a positive number.  The byte in AC4 is right-justified.

   The input is terminated when one of the following occurs:

         o  The byte count becomes zero.

         o  The specified terminating byte is reached.

         o  The end of the file is reached.

         o  An error occurs during the  transfer  (for  example,  a  data
            error occurs).

   Control returns to the user's program at the instruction following the
   SIN%  call.   If  an  error  occurs  (including the end of the file is
   reached), an illegal instruction  trap  is  generated.   In  addition,
   several locations are updated:





                                    3-22
                                USING FILES
                                USING FILES


        1.  The position of the file's pointer is updated for  subsequent
            I/O to the file.

        2.  The pointer to the string in AC2 is updated  to  reflect  the
            last  byte read or, if AC3 contained 0, the last nonzero byte
            read.

        3.  The count in AC3 is updated, if pertinent, by subtracting the
            number  of  bytes  actually  read  from  the  number of bytes
            requested to be read (that is, the count  is  updated  toward
            zero).  From this count, the user's program can determine the
            number of bytes actually transferred.

   The SOUT% monitor call writes a  string  from  the  program's  address
   space  to  the  specified  destination.  Like the SIN% call, this call
   accepts four words of arguments in AC1 through AC4.

        AC1:   destination designator

        AC2:   pointer to string to be written

        AC3:   count of the number of bytes to write, or 0

        AC4:   byte on which to terminate output (optional)

   The contents of AC3 and AC4 are interpreted in the same manner as they
   are in the SIN% monitor call.

   The transfer is terminated when one of the following occurs.

         o  The byte count becomes zero.

         o  The specified terminating byte is reached.  This  terminating
            byte is written to the destination.

         o  An error occurs during the transfer.

   Control returns to the user's program at the instruction following the
   SOUT%  call.   If  an  error  occurs,  an  illegal instruction trap is
   generated.  In addition, the  position  of  the  file's  pointer,  the
   pointer  to the string in AC2, and the count in AC3, if pertinent, are
   also updated in the same manner as in the SIN% monitor call.

   The following code sequence shows transferring a string from an  input
   file  to  an  output file.  The procedure is the same as at the end of
   Section 3.5.3, using SIN% and SOUT% calls instead of BIN% and BOUT%.

        LOOP:  MOVE 1,INJFN      ;get source from INJFN
               HRROI 2,BUF128    ;pointer to string to read into (128 
                                 ;word buffer)




                                    3-23
                                USING FILES
                                USING FILES


               MOVNI 3,^D128*5   ;input a maximum of 640 bytes
               SIN%              ;transfer until end of buffer or end of 
                                 ;file
                ERCAL EOFQ       ;error occurred
                   
               ADDI 3,^D128*5    ;determine negative number of 
                                 ;bytes transferred
               MOVN 3,3          ;convert to positive
               MOVE 1,OUTJFN     ;get destination from OUTJFN
               HRROI 2,BUF128    ;pointer to string to write from
               SOUT%             ;transfer as many bytes as read
        EOFQ:  MOVE 1,INJFN
               GTSTS%            ;obtain status of source
               TXNN 2,GS%EOF     ;test for end of file
               RET               ;no, continue copying



   3.5.5  Transferring Nonsequential Bytes
   3.5.5  Transferring Nonsequential Bytes

   As discussed in Section 3.5.3, the BIN% and BOUT% calls transfer bytes
   sequentially,  starting at the current position of the file's pointer.
   The RIN% (Random Input) and ROUT% (Random Output) monitor calls  allow
   the  user's  program  to  specify  where  the  transfer  will begin by
   accepting a byte number within the file.  The size of the byte is  the
   size  given in the OPENF% call for the file.  The RIN% and ROUT% calls
   can only be used when transferring data to or from disk files.

   The RIN% monitor call takes a byte from the specified location in  the
   file  and places it into the accumulator.  The call accepts the JFN of
   the file in AC1 and the byte number within  the  file  in  AC3.   Upon
   successful completion of the call, the byte is right-justified in AC2,
   and the file's pointer is updated to point to the byte  following  the
   one  just  read.   If  an error occurs, an illegal instruction trap is
   generated.  Control returns to the user's program at  the  instruction
   following the RIN% call.

   The ROUT% monitor call takes a byte from the accumulator and writes it
   into  the specified location in the file.  The call accepts the JFN of
   the file in AC1, the byte to write right-justified  in  AC2,  and  the
   byte number within the file in AC3.  Upon successful completion of the
   call, the byte is written into the specified byte in the file, and the
   file's  pointer is updated to point to the byte following the one just
   written.   If  an  error  occurs,  an  illegal  instruction  trap   is
   generated.   Control  returns to the user's program at the instruction
   following the ROUT% call.



   3.5.6  Mapping Pages
   3.5.6  Mapping Pages

   Up to this point, monitor calls have been presented  for  transferring


                                    3-24
                                USING FILES
                                USING FILES


   bytes  and  strings of data.  The next call to be discussed is used to
   transfer entire pages of data between a file and a process.

   Both files and process  address  spaces  are  divided  into  pages  of
   512(decimal)  words.   A  page  within a file can be identified by one
   word, where the JFN of the file is in  the  left  half  and  the  page
   number  within the file is in the right half.  A page within a process
   address space can also be identified by one word, where the identifier
   of the process (refer to Section 5.3) is in the left half and the page
   number within the process' address space is in the right  half.   Each
   one-word  identifier  for  the pages in  the  process address space is
   placed in what is called the process page map.  When  identifiers  for
   file  pages  are  placed  in  the  process page map, references to the
   process page actually refer to the file page.  The  following  diagram
   illustrates  a  process  map  that  has identifiers for pages from two
   files.


                                                File 1
                                                __________
                                               |          |
                  Process Map                  |          |
                  _____________                |          |
                 |             |               |          |
                 |             |               |          |
                 |-------------|               |----------|
                 |JFN1  |Page 1|-------------->| Page 1   |
                 |-------------|               |----------|
                 |             |               |          |
                 |             |               |          |
                 |-------------|               |__________|
                 |             |
                 |             |
                 |             |                File 2
                 |             |                __________
                 |             |               |          |
                 |             |               |          |
                 |-------------|               |----------|
                 |JFN2  |Page 2|-------------->| Page 2   |
                 |-------------|               |----------|
                 |             |               |          |
                 |             |               |          |
                 |_____________|               |          |
                                               |          |
                                               |          |
                                               |__________|


   The PMAP% (Page Mapping) monitor call is  used  to  map  one  or  more
   entire pages from a file to a process (for input), from a process to a
   file (for output),  or  from  one  process  to  another  process.   In
   general, this call changes the entries in the process map by accepting


                                    3-25
                                USING FILES
                                USING FILES


   file page identifiers  and  process  page  identifiers  as  arguments.
   Mapping pages between a file and a process is described below; mapping
   pages between two processes is described in Chapter 5.



   3.5.6.1  Mapping File Pages to a Process
   3.5.6.1  Mapping File Pages to a Process - This use of the PMAP%  call
   changes  the  map  of  the  process so that references to pages in the
   process reference pages in a file.  This does not actually cause  data
   to  be  transferred; it simply changes the contents of the map.  Later
   when changes are made to the actual page in the process,  the  changes
   will  also  be  made to the page in the file, if write access has been
   specified for the file.

   Note that you cannot map file pages to pages in a process section that
   does not exist in the the process map.  If you use PMAP% to input file
   pages to pages in a nonexistent section  of  a  process,  the  monitor
   generates an illegal instruction trap.

   In addition, you can map one or more file sections (of 512 pages each)
   into a process.  See Section 8.3.1 for details.

   The PMAP% call accepts three words of arguments in AC1 through AC3.

        AC1:   JFN of the file in the left half, and the page  number  in
               the file in the right half

        AC2:   process identifier (refer to  Section  5.3)  in  the  left
               half, and page number in the process in the right half

        AC3:   repetition count and access

   The repetition count and access bits that can be specified in AC3  are
   described in Table 3-6.


   Table 3-6:  PMAP% Access Bits
   Table 3-6:  PMAP% Access Bits

   ______________________________________________________________________

     Bit       Symbol    Meaning
   ______________________________________________________________________

      0        PM%CNT    Repeat the mapping  operation  the  number  of
                         times specified by the right half of AC3.  The
                         file page number and the process  page  number
                         are  incremented  by 1 each time the operation
                         is performed.

      2        PM%RD     Allow read access to the page.

      3        PM%WR     Allow write access to the page.


                                    3-26
                                USING FILES
                                USING FILES


      4        PM%EX     Reserved.
                         The symbol PM%RWX can be used to set B2-4.

      5        PM%PLD    Preload  page  being  mapped  (move  the  page
                         immediately  instead  of  waiting  until it is
                         referenced).

      9        PM%CPY    Create a private  copy  of  the  page  if  the
                         process  writes into the page.  This is called
                         copy-on-write and causes the map to be changed
                         so  that it identifies the copy instead of the
                         original.  Write access is allowed to the copy
                         even  if  it  was not allowed to the original.
                         This allows a process to change a page of data
                         without  changing the data for other processes
                         that have also mapped the page.

     10        PM%EPN    Bits 18-35 of AC2  contain  extended  (18-bit)
                         process   page   number.    If   the   section
                         containing the page does not exist, a  private
                         section is created.

     11        PM%ABT    Unmap  page  and   discard   (abort)   changed
                         contents.

     18-35     PM%RPT    The number of  times  to  repeat  the  mapping
                         operation if bit 0(PM%CNT) is set.
   ______________________________________________________________________


   With this use of the PMAP% call, the present contents of the  page  in
   the  process  are  removed.   If  the  page  in  the file is currently
   nonexistent, it will be created when it is written.

   This use of the PMAP% call is valid only if the file is opened for  at
   least read access.  If write access is requested in the PMAP% call, it
   is not granted unless it was also specified in the  OPENF%  call  when
   the file was opened.

   A file cannot be closed while any of its pages  are  mapped  into  any
   process.   Thus,  before  a file is closed, its pages must be unmapped
   (refer to Section 3.5.6.3).

   After execution of the PMAP%  call,  control  returns  to  the  user's
   program at the instruction following the call.  If an error occurs, an
   illegal instruction trap is generated.



   3.5.6.2  Mapping Process Pages to a File
   3.5.6.2  Mapping Process Pages to a File - This use of the PMAP%  call
   actually transfers data by moving the specified page in the process to
   the specified page in the file.  The process map for the page  is  now


                                    3-27
                                USING FILES
                                USING FILES


   empty.   Both the page in the process and the page in the file must be
   private; that is, no other process can have the page mapped  into  its
   address  space.   The  ownership of the process page is transferred to
   the file page.  The previous contents of the  page  in  the  file  are
   deleted.

   The three words of arguments are as follows:

        AC1:   process identifier (refer to  Section  5.3)  in  the  left
               half, and page number in the process in the right half

        AC2:   JFN of the file in the left half, and the page  number  in
               the file in the right half

        AC3:   repetition count and access (refer to Section 3.5.6.1)

   The access requested in the PMAP% call is granted only if it does  not
   conflict  with  the  access specified in the OPENF% call when the file
   was opened.

   This use of the PMAP% call does not  automatically  update  the  files
   byte count and the byte size.  To allow the file to be read later with
   sequential I/O monitor calls, the program  should  update  the  file's
   byte  count  and  the byte size.  (Refer to the CHFDB% monitor call in
       _______ _______ _____ _________ ______
   the TOPS-20 Monitor Calls Reference Manual).



   3.5.6.3  Unmapping Pages in a Process
   3.5.6.3  Unmapping Pages in a Process - As stated previously,  a  file
   cannot  be  closed  if any of its pages are mapped in any process.  To
   unmap a file's pages from a process,  the  program  must  execute  the
   SMAP% call, or the following form of the PMAP% call:

        AC1:   -1

        AC2:   process identifier in the left half, and  page  number  in
               the process in the right half.

        AC3:   the repeat count for the number of pages  to  remove  from
               the process (refer to Section 3.5.6.1).



   3.5.7  Mapping File Sections to a Process
   3.5.7  Mapping File Sections to a Process

   A section of memory is a unit of 512 pages of process  address  space.
   File  sections  also  contain  512 pages.  The first page of each file
   section has a page number that is an integral multiple of  512.   Like
   memory pages, sections can be mapped from one process to another, from
   a process to itself, or from a file to a process.  Chapter 8 describes
   the SMAP% call completely.



                                    3-28
                                USING FILES
                                USING FILES


   The SMAP% (Section Mapping) monitor call is similar to the PMAP% call.
   The SMAP% call maps one or more sections from a file to a process (for
   input), or from one process to another  process.   To  map  a  process
   section to a file, you must use the PMAP% call as described in Chapter
   5 to map each page.

   Mapping a file section to a process section with SMAP% does not  cause
   data  to  move  from  the  disk to memory.  Instead, SMAP% changes the
   contents of the process memory map so that the process section pointer
   points  to  a file section.  The monitor transfers data only when your
   program references a memory page to which a file page is mapped.

   To map a file section to  a  process  section,  SMAP%  requires  three
   arguments:

        AC1:   source identifier:  a JFN in the left  half,  and  a  file
               section  number  in the right half.  If several contiguous
               sections are to be mapped, the number in the right half is
               that  of  the  first  section  in  the group of contiguous
               sections.

        AC2:   destination identifier:  process identifier  in  the  left
               half,  and a process section number in the right half.  If
               several contiguous sections are to be mapped,  the  number
               in  the right half is the number of the first section into
               which SMAP% maps a file section.

        AC3:   flags that control access to the process  section  in  the
               left  half, and, in the right half, the number of sections
               to map into the process.  The number of  sections  to  map
               cannot be less than 1 nor more than 32 (decimal).

   The flags in the left half of AC3 are described in Table 3-7.


   Table 3-7:  SMAP% Access Bits
   Table 3-7:  SMAP% Access Bits

   ______________________________________________________________________

     Bit       Symbol    Meaning
   ______________________________________________________________________

      2        SM%RD     Allow read access.

      3        SM%WR     Allow write access.

      4        SM%EX     Allow execute access.

      6        SM%IND    Map the destination section using an  indirect
                         section pointer.
   ______________________________________________________________________



                                    3-29
                                USING FILES
                                USING FILES


   3.6  CLOSING A FILE
   3.6  CLOSING A FILE

   Once data has been transferred to or from a file, the  user's  program
   must  close the file.  When a file is closed, the system automatically
   performs the following:

        1.  Updates the directory information for the file.  For example,
            for  a  file  to which sequential bytes had been written, the
            byte size and byte count are updated when the file is closed.

        2.  Releases the JFN associated  with  the  file.   However,  the
            user's  program can request to close the file, but retain the
            JFN assignment.  This is  useful  if  the  program  plans  to
            reopen  the  same  file  later,  but does not want to execute
            another GTJFN% call.



   3.6.1  CLOSF% Monitor Call
   3.6.1  CLOSF% Monitor Call

   The CLOSF% (Close File) monitor call closes either the specified  file
   or  all files that are opened for the process executing the call.  The
   CLOSF% call accepts one word of arguments in AC1 - flag  bits  in  the
   left half and the JFN of the file to be closed in the right half.  The
   flag bits are described in Table 3-8.


   Table 3-8:  CLOSF% Flag Bits
   Table 3-8:  CLOSF% Flag Bits

   ______________________________________________________________________

     Bit      Symbol   Meaning
   ______________________________________________________________________

      0       CO%NRJ   Do not release the JFN from the file.

      6       CZ%ABT   Abort  any  output  operations  currently  being
                       done.   That  is,  close  the  file  but  do not
                       perform normal cleanup operations (for  example,
                       do   not   output  any  data  remaining  in  the
                       buffers).  If output to a new disk file that has
                       not  been  closed is aborted, the file is closed
                       and then deleted.

      7       CS%NUD   Do not update the copy of the directory  on  the
                       disk  (refer  to  the  CHFDB% description in the
                       _______ _______ _____ _________ ______
                       TOPS-20 Monitor Calls Reference Manual for  more
                       information).
   ______________________________________________________________________


   If the contents of AC1 is -1, all  files  that  are  opened  for  this
   process are closed.

                                    3-30
                                USING FILES
                                USING FILES


   If the execution of the CLOSF% call is successful, the specified  file
   is  closed, and the JFN associated with the file is released if CO%NRJ
   was not set  in  the  call.   The  execution  of  the  user's  program
   continues at the second location after the CLOSF% call.

   If the execution of the CLOSF% call is not successful, the file is not
   closed  and  an  error code is returned in the right half of AC1.  The
   execution of the user's program continues at the instruction following
   the CLOSF% call.

   The following sequence illustrates the closing of two files.

        CLOSIF:  HRRZ 1,INJFN    ;obtain input JFN
                 CLOSF%          ;close input file
                  ERJMP FATAL    ;if error, print message and stop
        CLOSOF:  HRRZ 1,OUTJFN   ;obtain output JFN
                 CLOSF%          ;close output file
                  ERJMP FATAL    ;if error, print message and stop



   3.7  ADDITIONAL FILE I/O MONITOR CALLS
   3.7  ADDITIONAL FILE I/O MONITOR CALLS



   3.7.1  GTSTS% Monitor Call
   3.7.1  GTSTS% Monitor Call

   The GTSTS% (Get Status) monitor call obtains the  status  of  a  file.
   This call accepts one argument word - the JFN of the file in the right
   half of the AC1.  The left half of AC1 is zero.

   Control always returns  to  the  user's  program  at  the  instruction
   following  the  GTSTS% call.  Upon return, appropriate bits reflecting
   the status of the specified JFN are set in AC2.  These bits, and their
   meanings, are described in Table 3-9.  Note that if the JFN is illegal
   or unassigned, bit 10 (GS%NAM) will not be set.


   Table 3-9:  Bits Returned on GTSTS% Call
   Table 3-9:  Bits Returned on GTSTS% Call

   ______________________________________________________________________

     Bit       Symbol            Meaning
   ______________________________________________________________________

      0        GS%OPN            The file is open.  If this bit is  not
                                 set, the file is not open.

      1        GS%RDF            If the  file  is  open  (for  example,
                                 GS%OPN  is  set),  it is open for read
                                 access.



                                    3-31
                                USING FILES
                                USING FILES


      2        GS%WRF            If the file is open, it  is  open  for
                                 write access.

      3        GS%XCF            File is open for execute access.

      4        GS%RND            If the file is open, it  is  open  for
                                 non-append   access   (that   is,  its
                                 pointer can be reset).

      5-6                        Reserved for Digital.

      7        GS%LNG            File has  pages  in  existence  beyond
                                 page number 511.

      8        GS%EOF            The last read operation  to  the  file
                                 was at the end of the file.

      9        GS%ERR            The file may be in error (for example,
                                 the bytes read may be erroneous).

     10        GS%NAM            A  file  specification  is  associated
                                 with  this  JFN.  This bit will not be
                                 set if the JFN is in any way illegal.

     11        GS%AST            One  or  more  fields  of   the   file
                                 specification associated with this JFN
                                 contain a wildcard character.

     12        GS%ASG            The JFN is  currently  being  assigned
                                 (that is, a process other than the one
                                 executing the GTSTS call is  assigning
                                 this JFN).

     13        GS%HLT            An I/O error is  considered  to  be  a
                                 terminating  condition  for  this JFN.
                                 That is, the OPENF% call for this  JFN
                                 had bit OF%HER set.

     14-16                       Reserved for Digital.

     17        GS%FRK            Access to the file  is  restricted  to
                                 only one process.

     18        GS%PLN            If on, file line  numbers  are  passed
                                 during  input;  if  zero, line numbers
                                 are stripped before input.

     19-31                       Reserved for Digital.

     32-35     GS%MOD            The data mode of the  file  (refer  to
                                 the OPENF% call).



                                    3-32
                                USING FILES
                                USING FILES


                                 Value  Symbol  Meaning

                                   0    .GSNRM  Normal (sequential) I/O
                                   1    .GSSMB  Small buffer mode
                                   10   .GSIMG  Image (binary) I/O
                                   17   .GSDMP  Dump I/O
   ______________________________________________________________________


   An example of the GTSTS% call is shown in the first program in Section
   3.9.



   3.7.2  JFNS% Monitor Call
   3.7.2  JFNS% Monitor Call

   The JFNS% (JFN to String) monitor call returns the file  specification
   currently  associated  with the specified JFN.  The call accepts three
   words of arguments in AC1 through AC3.

        AC1:   destination  designator  where  the   file   specification
               associated   with   the   JFN  is  to  be  written.   This
               specification is an ASCIZ string.

        AC2:   JFN or pointer to string (see below)

        AC3:   format to be used when returning  the  specification  (see
               below)

   The contents of AC1 can be any valid destination designator (refer  to
   Section 3.5.2).

   The contents of AC2 can be one of two formats.  The first format is  a
   word  with  either  flag bits or 0 in the left half and the JFN in the
   right half.  The bits that can be given in the left half  of  AC2  are
   the ones returned from the GTJFN% call (refer to Table 3-3).  When the
   left half of AC2 is nonzero (that is, contains the bits returned  from
   the GTJFN% call), the string returned will contain wildcard characters
   for appropriate fields and 0, -1, or -2 as a generation number if  the
   corresponding  bit is on in the JFNS% call.  When the left half of AC2
   is 0, the string returned is the exact specification for the file (for
   example, wildcard characters are not returned for any fields).  If the
   JFN is associated only with a  file  specification  and  not  with  an
   actual  file  (that  is,  bit  GJ%OFG was set in the GTJFN% call), the
   string returned will contain null fields for  unspecified  fields  and
   the actual values for specified fields.  The second format allowed for
   AC2 is a pointer to the string in the program's address space that  is
                                                                  _______
   to  be  returned  upon  execution  of  the call.  Refer to the TOPS-20
   _______ _____ _________ ______
   Monitor Calls Reference Manual for the explanation of this format.





                                    3-33
                                USING FILES
                                USING FILES


   The contents of AC3 specify the format in which the  specification  is
   written  to the destination.  Bits 0 through 20 are divided into 3-bit
   bytes, each byte representing a field in the file specification.   The
   value  of  the byte indicates the format for that field.  The possible
   values are:

        Value     Symbol     Meaning

          0       .JSNOF     Do not return this field when returning  the
                             file specification.

          1       .JSAOF     Always return this field when returning  the
                             file specification.

          2       .JSSSD     Suppress this field if it  is  the  standard
                             system  value for this field (refer to Table
                             3-1).

   If the contents of AC3 is zero, the file specification is  written  in
   the format

        dev:<directory>name.typ.gen;T

   with fields the same as the standard system value (see Table 3-1)  not
   returned  and protection and account fields returned only if bit 9 and
   bit 10 in AC2 are on, respectively.  The temporary attribute  (;T)  is
   returned only if the file is temporary.

   Table 3-10 describes the bits that can be set in AC3.


   Table 3-10:  JFNS% Format Options
   Table 3-10:  JFNS% Format Options

   ______________________________________________________________________

     Bit       Symbol            Meaning
   ______________________________________________________________________

      0        JS%NOD            Print  node  name  if  node  name   is
                                 present.

      1-2      JS%DEV            Format for device field.

      3-5      JS%DIR            Format for directory field.

      6-8      JS%NAM            Format for filename field.  A value of
                                 2  (that is, bit 7 set) for this field
                                 is illegal.

      9-11     JS%TYP            Format for file type field.   A  value
                                 of  2  (that  is, bit 10 set) for this
                                 field is illegal.


                                    3-34
                                USING FILES
                                USING FILES


     12-14     JS%GEN            Format for generation number field.

      0-14     JS%SPC            Output  for  all  file   specification
                                 fields named above.  This field should
                                 have the same bits set as would be set
                                 in   the   fields   above.   (See  B35
                                 (JS%PAF) below.)

     15-17     JS%PRO            Format for protection field.

     18-20     JS%ACT            Format for account field.

     21        JS%TMP            Return temporary file indication ;T if
                                 the   file   specification  is  for  a
                                 temporary file.

     22        JS%SIZ            Return size  of  file  in  pages  (see
                                 below).

     23        JS%CDR            Return  creation  date  of  file  (see
                                 below).

     24        JS%LWR            Return date of last write operation to
                                 file (see below).

     25        JS%LRD            Return date  of  last  read  operation
                                 from file (see below).

     26        JS%PTR            AC2 contains a pointer to  the  string
                                 containing  the  field  to be returned
                                                _______  _______  _____
                                 (refer to the  TOPS-20  Monitor  Calls
                                 _________  ______
                                 Reference  Manual for a description of
                                 this use of the JFNS% call).

     27        JS%ATR            Return file  specification  attributes
                                 if appropriate.

     28        JS%AT1            Return     specification     attribute
                                 referenced in AC4.

     29        JS%OFL            Return the "OFF-LINE" attribute.

     30-31                       Reserved for Digital.

     32        JS%PSD            Punctuate the  size  and  date  fields
                                 (see  below) in the file specification
                                 returned.

     33        JS%TBR            Place a tab before all fields returned
                                 (that  is, fields whose value is given
                                 as 1 in the 3-bit field) in  the  file
                                 specification,  except  for  the first
                                 field.

                                    3-35
                                USING FILES
                                USING FILES


     34        JS%TBP            Place a tab before all fields that may
                                 be  returned  (that  is,  fields whose
                                 value is given as 1 or 2 in the  3-bit
                                 field)   in  the  file  specification,
                                 except for the first field.

     35        JS%PAF            Punctuate  all  fields   (see   below)
                                 returned  in  the  file  specification
                                 from the device field through  the  ;T
                                 field.

                                 If bits 32 through 35 are not set,  no
                                 punctuation   is   used   between  the
                                 fields.
   ______________________________________________________________________


   The punctuation used on each field is shown below.

        dev:<directory>name.typ.gen;A(account);P(protection);T(temporary)
        ,size,creation date,write date,read date

   Refer to Section 1.2.2 for information on error returns.



   3.7.3  GNJFN% Monitor Call
   3.7.3  GNJFN% Monitor Call

   Occasionally a program may be written to perform similar operations on
   a  group  of  files instead of only on one file.  However, the program
   should not require the user to give  a  file  specification  for  each
   file.   Because the GTJFN% call associates a JFN with only one file at
   a time, the program needs a method of assigning a JFN to all the files
   in  the  group.   By using the GTJFN% call to initially obtain the JFN
   and the GNJFN% call to assign the same JFN to each subsequent file  in
   the  group,  a program can accept a specification for a group of files
   and process each file in the group individually.  After the user gives
   the  initial  file  specification,  the program requires no additional
   input.

   Before an example showing the interaction of these two calls is given,
   a   description   of  the  GNJFN%  (Get  Next  JFN)  monitor  call  is
   appropriate.

   The GNJFN% monitor call assigns a JFN to the next file in a  group  of
   files  that  have  been  specified with wildcard characters.  The next
   file is determined by searching the directory in the  order  described
   in  Section  3.3.1.1  using  the current file as the first item.  This
   call accepts one argument word in AC1 - the flags  returned  from  the
   GTJFN%  call in the left half and  the JFN of the  current file in the
   right half.  In other words, the information returned in AC1 from  the
   GTJFN%  call  is  given as an argument to the GNJFN% call.  Therefore,
   the program must save this information for use with the GNJFN% call.

                                    3-36
                                USING FILES
                                USING FILES


   If execution of the  GNJFN%  call  is  successful,  the  same  JFN  is
   assigned to the next file in the group.  The left half of AC1 contains
   various flags and the right half contains the JFN.  The  execution  of
   the program continues at the second instruction after the GNJFN% call.

   Table 3-11 describes the bits  that  can  be  returned  in  AC1  on  a
   successful GNJFN% call.


   Table 3-11:  GNJFN% Return Bits
   Table 3-11:  GNJFN% Return Bits

   ______________________________________________________________________

     Bit       Symbol            Meaning
   ______________________________________________________________________

     13        GN%STR            A change in structure occurred between
                                 the previous file and this file.

     14        GN%DIR            A change in directory occurred between
                                 the previous file and this file.

     15        GN%NAM            A change in filename occurred  between
                                 the previous file and this file.

     16        GN%EXT            A change in file type occurred between
                                 the  previous  file and this file.  If
                                 GN%NAM is on, this bit will also be on
                                 because the system considers two files
                                 with different filenames but with  the
                                 same file type as a change in both the
                                 name and type.
   ______________________________________________________________________


   If execution of the GNJFN% call is not successful, an  error  code  is
   returned in the right half of AC1.  Conditions that can cause an error
   return are:

        1.  The file currently associated with the JFN  must  be  closed,
            and  it  is  not.  This means that the program must execute a
            CLOSF% call (with  CO%NRJ  set  to  retain  the  JFN)  before
            executing a GNJFN% call.

        2.  There are no more files in this group.  This return occurs on
            the  first GNJFN% call after all files in the group have been
            stepped through.  The JFN is released when there are no  more
            files.   (Note:   This  error may occur if the file currently
            associated with the JFN is deleted or renamed.)





                                    3-37
                                USING FILES
                                USING FILES


   The execution of the program continues at the next  instruction  after
   the GNJFN% call.

   Consider the following situation.  The user wants to write  a  program
   that  will  accept  from  his  terminal a specification for a group of
   files and then perform an operation on each file individually  without
   requiring  additional  input.   Assume  the  user's  directory <TRAIN>
   contains the following files:

        FIRST.MAC.1
        FIRST.REL.1
        SECOND.REL.1
        THIRD.EXE.1

   As discussed in Section 3.3.1.1, a group of files can be given to  the
   GTJFN  call  by  supplying  a  specification  that  contains  wildcard
   characters in one or more of its fields.  Thus, the specification

        <TRAIN>*.*

   would refer to all four files in the user's directory <TRAIN>.

   In his program, the user includes a GTJFN% call that will  accept  the
   above specification.

   The call is

        MOVX AC1,GJ%OLD+GJ%IFG+GJ%FLG+GJ%FNS+GJ%SHT
        MOVE AC2,[.PRIIN,,.PRIOU]
        GTJFN%

   and indicates that

        1.  The file specification given must refer to an  existing  file
            (GJ%OLD).

        2.  The file specification given is allowed to  contain  wildcard
            characters (GJ%IFG).

        3.  Flags will be returned in AC1 on a successful call  (GJ%FLG).
            The  flags must be returned because they will be given to the
            GNJFN% call as arguments.

        4.  The contents of AC2 will  be  interpreted  as  containing  an
            input and output JFN (GJ%FNS).

        5.  The short form of the GTJFN% call is being used (GJ%SHT).

        6.  The file specification is to be read from the user's terminal
            (.PRIIN,,.PRIOU).




                                    3-38
                                USING FILES
                                USING FILES


   When the user types the specification <TRAIN>*.* as input, the  system
   associates  the  JFN  with  one file only.  This file is the first one
   found when searching the directory in the order specified  in  Section
   3.3.1.1.    Thus   the  JFN  returned  is  associated  with  the  file
   FIRST.MAC.1.

   After  the  GTJFN%  call  is  successfully  executed,   AC1   contains
   appropriate  flags  in the left half and the JFN assigned in the right
   half.  The flags that will be returned in  this  particular  situation
   are:

        GJ%NAM (bit 3)      A wildcard character  appeared  in  the  name
                            field of the file specification given.

        GJ%EXT (bit 4)      A wildcard character  appeared  in  the  type
                            field of the file specification given.

        GJ%GND (bit 12)     Any files marked for  deletion  will  not  be
                            considered.

   These flags inform the program of the fields that  contained  wildcard
   characters.   The  user's  program  must  now save the contents of AC1
   because this word will be used as the argument  to  the  GNJFN%  call.
   The  program  then  performs  its desired operation on the first file.
   Once its processing  is  completed,  the  program  is  ready  for  the
   specification  of  the  next  file.   But  instead  of  requesting the
   specification from the user, the program executes the GNJFN%  call  to
   obtain  it.   The  argument  to the GNJFN% call is the contents of AC1
   returned from the previous GTJFN% call.  Thus, the call in  this  case
   is equivalent to:

        MOVE AC1,[GJ%NAM+GJ%EXT+GJ%GND,,JFN]
        GNJFN%

   Upon  successful  execution  of  the  GNJFN%  call,  the  JFN  is  now
   associated  with  the  next  file in the group (that is, FIRST.REL.1).
   AC1 contains appropriate flags in the left half and the  same  JFN  in
   the right half.  In this example, the flag returned is GN%EXT (bit 16)
   to indicate that the file type changed between the two files.

   After processing the second file, the user's program executes  another
   GNJFN%  call  using  the  original  contents  of AC1 returned from the
   GTJFN% call.  The original contents must be  used  because  this  word
   indicates  the  fields containing wildcard characters.  If the current
   contents of AC1 (that is, the flags returned from the GNJFN% call) are
   used,  a  subsequent GNJFN% call would fail because there are no flags
   set indicating fields containing  wildcard  characters.   This  second
   GNJFN%  call associates the JFN with the file SECOND.REL.1.  The flags
   returned in AC1 are GN%NAM (bit 15) and  GN%EXT  (bit  16)  indicating
   that  the  filename  and  file  type  changed  between  the two files.
   (Remember that a change in filename implies a change in file type even
   if the two file types are the same.)


                                    3-39
                                USING FILES
                                USING FILES


   After processing this third file, the user's program executes  another
   GNJFN% call using the original contents of AC1.  Upon execution of the
   call, the JFN is  now  associated  with  THIRD.EXE.1,  and  the  flags
   returned  are  GN%NAM  and GN%EXT, indicating a change in the filename
   and file type.

   After processing the file THIRD.EXE.1, the user's program  executes  a
   final  GNJFN%  call.   Since there are no more files in the group, the
   call returns an error code and releases the  JFN.   Execution  of  the
   user's program continues at the instruction following the GNJFN% call.



   3.8  SUMMARY
   3.8  SUMMARY

   To read from or write to a file, the user's program must:

        1.  Obtain a JFN on the file with the GTJFN% monitor call  (refer
            to Section 3.3.1).

        2.  Open the file with the OPENF% monitor call (refer to  Section
            3.4.1).

        3.  Transfer the data with byte,  string,  or  page  I/O  monitor
            calls (refer to Section 3.5).

        4.  Close the file with the CLOSF% monitor call (refer to Section
            3.6.1).



   3.9  FILE EXAMPLES
   3.9  FILE EXAMPLES

   Example 1 - This program assigns JFNs, opens  an  input  file  and  an
   output  file,  and copies data from the input file to the output file.
   Data is copied until the end of the input file is reached.   Refer  to
        _______  _______  _____  _________  ______
   the  TOPS-20  Monitor  Calls  Reference  Manual for explanation of the
   ERSTR% monitor call.

   ;*** PROGRAM TO COPY INPUT FILE TO OUTPUT FILE. ***
   ;       (USING BIN%/BOUT% AND IGNORING NULLS)

           TITLE FILEIO            ;TITLE OF PROGRAM
           SEARCH MONSYM           ;SEARCH SYSTEM JSYS-SYMBOL LIBRARY
           SEARCH MACSYM
           .REQUIRE SYS:MACREL

   ;*** IMPURE DATA STORAGE AND DEFINITIONS ***


   INJFN:  BLOCK 1                 ;STORAGE FOR INPUT JFN
   OUTJFN: BLOCK 1                 ;STORAGE FOR OUTPUT JFN


                                    3-40
                                USING FILES
                                USING FILES


           PDLEN=3                 ;STACK HAS LENGTH 3
   PDLST:  BLOCK PDLEN             ;SET ASIDE STORAGE FOR STACK

           STDAC.                  ;DEFINE STANDARD ACs. SEE MACSYM.

   ;*** PROGRAM INITILIZATION ***

   START:  RESET%                  ;CLOSE FILES, ETC.
           MOVE P,[IOWD PDLEN,PDLST] ;ESTABLISH STACK

   ;***  GET INPUT FILE ***

   INFIL:                          ;PROMPT FOR INPUT FILE
           TMSG <
   INPUT FILE: >                   ;ON CONTROLLING TERMINAL
           MOVX T1,GJ%OLD+GJ%FNS+GJ%SHT ;SEARCH MODES FOR GTJFN
                                   ;EXISTING FILE ONLY, FILE-NRs IN B
                                   ;SHORT CALL
           MOVE T2,[.PRIIN,,.PRIOU] ;GTJFN'S I/O WITH CONTROLLING TERM
           GTJFN%                  ;GET JOB FILE NUMBER (JFN)
            ERJMPS [ PUSHJ P,WARN  ;IF ERROR, GIVE WARNING
                     JRST INFIL]   ;AND LET HIM TRY AGAIN
           MOVEM T1,INJFN          ;SUCCESS, SAVE THE JFN

   ;*** GET OUTPUT FILE ***

   OUTFIL:                         ;PRINT PROMPT FOR
           TMSG <
   OUTPUT FILE: >                  ;OUTPUT FILE
           MOVX T1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT ;GTJFN SEARCH MODES
                                   ;[DEFAULT TO NEW GENERATION, PRINT
                                   ; MESSAGE, REQUIRE CONFIRMATION
                                   ; FILE-NR'S IN T2, SHORT CALL ]
           MOVE T2,[.PRIIN,,.PRIOU] ;I/O WITH CONTROLLING TERMINAL
           GTJFN%                  ;GET JOB FILE NUMBER
            ERJMPS [ PUSHJ P,WARN  ;IF ERROR, GIVE WARNING
                    JRST OUTFIL]   ;AND LET HIM TRY AGAIN
           MOVEM T1,OUTJFN         ;SAVE THE JFN

   ;NOW, OPEN THE FILES WE JUST GOT

   ;   INPUT

           MOVE T1,INJFN           ;RETRIEVE THE INPUT JFN
           MOVX T2,FLD(7,OF%BSZ)+OF%RD ;MODES FOR OPENF 
                                   ;[7-BIT BYTES + INPUT]
           OPENF%                  ;OPEN THE FILE
            ERJMPS FATAL           ;IF ERROR, GIVE MESSAGE AND STOP

   ;   OUTPUT

           MOVE T1,OUTJFN          ;GET THE OUTPUT JFN


                                    3-41
                                USING FILES
                                USING FILES


           MOVX T2,FLD(7,OF%BSZ)+OF%WR ;MODES FOR OPENF 
                                   ;[7-BIT BYTES + OUTPUT]
           OPENF%                  ;OPEN THE FILE
            ERJMPS FATAL           ;IF ERROR, GIVE MESSAGE AND STOP


   ;*** MAIN LOOP: COPY BYTES FROM INPUT TO OUTPUT ***

   LOOP:   MOVE T1,INJFN           ;GET THE INPUT JFN
           BIN%                    ;TAKE A BYTE FROM THE SOURCE
           JUMPE T2,DONE           ;IF 0, CHECK FOR END OF FILE
           MOVE T1,OUTJFN          ;GET THE OUTPUT JFN
           BOUT                    ;OUTPUT THE BYTE TO DESTINATION
            ERCALS ERROR
           JRST LOOP               ;LOOP, STOP ONLY ON A 0 BYTE
                                   ;(FOUND AT LOOP+2)


   ;*** TEST FOR END OF FILE, ON SUCCESS FINISH UP ***

   DONE:   GTSTS%                  ;GET THE STATUS OF INPUT FILE
           TXNN T2,GS%EOF          ;AT END OF FILE?
           JRST LOOP               ;NO, FLUSH NULL AND CONTINUE COPY

   CLOSIF: MOVE T1,INJFN           ;YES, RETRIEVE INPUT JFN
           CLOSF%                  ;CLOSE INPUT FILE
            ERJMPS FATAL           ;IF ERROR, GIVE MESSAGE AND STOP

   CLOSOF: MOVE T1,OUTJFN          ;RETRIEVE OUTPUT JFN
           CLOSF%                  ;CLOSE OUTPUT FILE
            ERJMPS FATAL           ;IF ERROR, GIVE MESSAGE AND STOP
           TMSG <
   [DONE]>                         ;SUCCESSFULLY DONE
           JRST ZAP                ;STOP

   ;*** ERROR HANDLING ***

   FATAL:  TMSG <
   ?>                              ;FATAL ERRORS PRINT ? FIRST
           PUSHJ P,ERROR           ;THEN PRINT ERROR MESSAGE
           JRST ZAP                ;AND STOP

   WARN:   TMSG <
   %>                              ;WARNINGS PRINT % FIRST
                                   ;AND FALL THRU 'ERROR' 
                                   ;BACK TO CALLER

   ERROR:  MOVEI T1,.PRIOU         ;DECLARE PRINCIPAL OUTPUT DEVICE
                                   ;FOR ERROR MESSAGE
           MOVE T2,[.FHSLF,,-1]    ;CURRENT FORK,, LAST ERROR
           SETZ T3,                ;NO LIMIT,, FULL MESSAGE
           ERSTR%                  ;PRINT THE MESSAGE


                                    3-42
                                USING FILES
                                USING FILES


            JFCL                   ;IGNORE UNDEFINED ERROR NUMBER
            JFCL                   ;IGNORE ERROR DURING EXE OF ERSTR
           POPJ P,                 ;RETURN TO CALLER

   ZAP:    HALTF%                  ;STOP
           JRST START              ;WE ARE RESTARTABLE
           END START               ;TELL LINKING LOADER START ADDRESS


   Example 2 - This program accepts input from a user at the terminal and
   then  outputs  the data to the line printer.  Refer to Section 2.9 for
   explanation of the RDTTY% call.

           TITLE LPTPNT            ;PROGRAM TO PRINT TERMINAL INPUT 
                                   ;ON PRINTER
           SEARCH MONSYM           ;SEARCH SYSTEM JSYS-SYMBOL LIBRARY
           SEARCH MACSYM
           .REQUIRE SYS:MACREL

           STDAC.                  ;DEFINE STANDARD ACs

   BUFSIZ==200
   PDLEN==50

   COUNT:  BLOCK 1
   LPTJFN: BLOCK 1
   BUFFER: BLOCK BUFSIZ
   PDL:    BLOCK PDLEN

   START:  RESET%                  ;RESET I/O, ETC.
           MOVE P,[IOWD PDLEN,PDL] ;SET UP STACK
           TMSG <ENTER TEXT TO BE PRINTED (END WITH ^Z):
   >                               ;OUTPUT PROMPTING TEXT
           HRROI T1,BUFFER         ;GET POINTER TO BUFFER
           MOVE T2,[RD%BRK+BUFSIZ*5] ;GET FLAG AND MAX # OF CHARS TO READ
           SETZM T3                ;NO RE-TYPE BUFFER
           RDTTY%                  ;INPUT TEXT FROM TERMINAL
            EJSHLT                 ;ERROR, STOP
           HRRZS T2                ;GET CHARS REMAINING IN BUFFER
           MOVEI T1,BUFSIZ*5       ;COMPUTE NUMBER OF CHARS READ = 
           SUB T1,T2               ;BUFFERSIZE MINUS CHARS REMAINING
           SOS T1                  ;DON'T INCLUDE ^Z
           MOVEM T1,COUNT          ;SAVE # OF CHARS INPUT
   ;GET A JFN FOR THE PRINTER AND OPEN THE PRINTER

           MOVX T1,GJ%SHT!GJ%FOU   ;OUTPUT FILE, SHORT CALL
           HRROI T2,[ASCIZ /LPT:/] ;GET POINTER TO NAME OF FILE
           GTJFN%                  ;GET A JFN FOR THE PRINTER
            ERJMPS JFNERR          ;ERROR, PRINT ERROR MESSAGE
           MOVEM T1,LPTJFN         ;REMEMBER PRINTER JFN
           MOVX T2,FLD(7,OF%BSZ)+OF%WR ;7-BIT BYTES, 
                                   ;WRITE ACCESS WANTED


                                    3-43
                                USING FILES
                                USING FILES


           OPENF%                  ;OPEN THE PRINTER FOR OUTPUT
            ERJMPS OPNERR          ;ERROR, PRINT ERROR MESSAGE

   ;NOW OUTPUT THE TEXT THAT WAS INPUT FROM THE TERMINAL
           
           HRROI T2,BUFFER         ;GET POINTER TO TEXT 
                                   ;(PRINTER JFN STILL IN T1)
           MOVN T3,COUNT           ;GET NUMBER OF CHARS TO OUTPUT
           SOUT%                   ;OUTPUT STRING OF CHARS TO 
                                   ;THE PRINTER
            ERJMPS DATERR          ;ERROR, PRINT ERROR MESSAGE
           TMSG <
   OUTPUT HAS BEEN SENT TO THE PRINTER...
   >                               ;OUTPUT CONFIRMATION MESSAGE
           MOVE T1,LPTJFN          ;GET PRINTER JFN
           CLOSF%                  ;CLOSE IT
            ERJMPS DATERR          ;UNEXPECTED ERROR, PRINT ERROR MESSAGE
           HALTF%                  ;FINISHED
           JRST START              ;IF CONTINUED, GO BACK TO START

   ;ERROR ROUTINES

   JFNERR: TMSG<
   ? COULD NOT GET A JFN FOR THE PRINTER
   >
           HALTF%
           JRST START              ;IF CONTINUED, GO BACK TO START

   OPNERR: TMSG<
   ? COULD NOT OPEN THE PRINTER FOR OUTPUT
   >
           HALTF%
           JRST START              ;IF CONTINUED, GO BACK TO START

   DATERR: TMSG<
   ? DATA ERROR DURING OUTPUT TO PRINTER
   >
           HALTF%
           JRST START              ;IF CONTINUED, GO BACK TO START

           END START













                                    3-44












                                 CHAPTER 4
                                 CHAPTER 4

                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM



   4.1  OVERVIEW
   4.1  OVERVIEW

   Program  execution  usually  occurs  in  a  sequential  manner,  where
   instructions  are executed one after another.  But sometimes a program
   must be able to  receive  asynchronous  signals  from  terminals,  the
   monitor,  or  other programs, or as a result of its own execution.  By
   using the software interrupt system, the user can  specify  conditions
   that  will  cause his program to deviate from its sequential method of
   execution.

   An interrupt is defined as a break  in  the  normal  flow  of  control
   during  a  program's execution.  The break, or interrupt, is caused by
   the  occurrence  of  a  prespecified  condition.   By  specifying  the
   conditions that can cause an interrupt, the program has the capability
   of dynamically responding to external events and error conditions  and
   of  generating requests for services.  Because the program can respond
   to special conditions as they occur, it does not  have  to  explicitly
   and repeatedly test for them.  In addition, the program's execution is
   faster because the program does not have to  include  a  special  test
   after the possible occurrence of the condition.

   When an interrupt occurs, the system transfers control from  the  main
   program  sequence  to a previously-specified routine that will process
   the interrupt.  After the routine has completed its processing of  the
   interrupt,  the system can transfer control back to the program at the
   point it was interrupted, and execution can continue.  See Figure 4-1.













                                    4-1
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


     -----------------
     | User Program  |
     |     is        |
     | Executing     |
     -----------------
             |
             V
     -----------------
     | Interrupt     |
     | Condition     |
     | Occurs        |
     -----------------
             |
             V
             ^                          ^
            / \                        / \
           /   \                      /   \
          / Has \                    /Is An\
         /Program\                  /Inter- \          
        / Enabled \                /rupt of  \          -----------------
       /for Condi- \  Yes         /Higher Pri-\ No      | Execute       |
      <tion on this >----------->< ority Being >------->| User's Inter- |
       \ Channel   /      ^       \ Processed /         | rupt Routine  |
        \   ?     /       |        \    ?    /          --------|--------
         \       /        |         \       /                   |
          \     /         |          \     /                    |
           \   /          |           \   /                     |
            \ /           |            \ /                      |
             V            |             V                       |
             | No         |             | Yes                   |
             |            |             V                       |
             |            |     ----------------------          |
             V            |     | Wait Until         |          |
     -----------------    |     | Higher Priority    |          |
     | Perform System|    |     | Interrupt Finishes |          |
     | Default Action|    |     --------|-------------          |        
     | (e.g., stops  |    |             |                       |
     | job, print    |    \-------------/                       |
     | message)      |                                          |
     --------|--------                                          |
             | <------------------------------------------------/
             V
     -----------------
     | User Program  |
     | Continues if  |
     | Job Has Not   |
     | Not Been      |
     | Terminated    |
     -----------------





                                    4-2
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   Figure 4-1:  Basic Operational  Sequence  of  the  Software  Interrupt
   Figure 4-1:  Basic Operational  Sequence  of  the  Software  Interrupt
                System
                System




















































                                    4-3
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   4.2  INTERRUPT CONDITIONS
   4.2  INTERRUPT CONDITIONS

   Conditions that cause the program to be interrupted when the interrupt
   system is enabled are:

        1.  Conditions generated when specific terminal keys  are  typed.
            There   are   36  possible  codes;  each  one  specifies  the
            particular  terminal  character  or  condition  on  which  an
            interrupt  is  to  be  initiated.  Refer to Table 4-2 for the
            possible codes.

        2.  Invalid instructions (for example, I/O instructions given  in
            user  mode)  or  privileged  monitor  calls  issued  by a non
            privileged user.

        3.  Memory conditions, such as illegal memory references.

        4.  Arithmetic processor conditions, such as arithmetic  overflow
            or underflow.

        5.  Certain file or device conditions, such as end of file.

        6.  Program-generated software interrupts.

        7.  Termination of an inferior process.

        8.  System resource unavailability.

        9.  Interprocess   communication   (IPCF)   and   Enqueue/Dequeue
            interrupts.



   4.3  SOFTWARE INTERRUPT CHANNELS AND PRIORITIES
   4.3  SOFTWARE INTERRUPT CHANNELS AND PRIORITIES

   Each condition  is  associated  with  one  of  36  software  interrupt
   channels.   Most  conditions  are  permanently  assigned  to  specific
   channels; however, the user's program can  associate  some  conditions
   (for  example,  conditions generated by specific terminal keys) to any
   one of the assignable channels.  (Refer to Table 4-1 for  the  channel
   assignments.) When the condition associated with a channel occurs, and
   that channel has been activated, an interrupt is  generated.   Control
   can  then  be  transferred  to  the routine responsible for processing
   interrupts on that channel.

   The user program assigns each channel to one of three priority levels.
   Priority levels allow the occurrence of some conditions to suspend the
   processing of other conditions.  The levels are referred to  as  level
   1, 2, or 3 with level 1 having the highest priority.  Level 0 is not a
   legal priority level.[1]




                                    4-4
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   Table 4-1:  Software Interrupt Channel Assignments
   Table 4-1:  Software Interrupt Channel Assignments

   ______________________________________________________________________

     Channel      Symbol         Meaning
   ______________________________________________________________________

      0-5                        Assignable by user program

      6           .ICAOV         Arithmetic overflow

      7           .ICFOV         Arithmetic floating point overflow

      8                          Reserved for Digital

      9           .ICPOV         Pushdown list (PDL) overflow*

      10          .ICEOF         End of file condition

      11          .ICDAE         Data error file condition*

      12          .ICQTA         Disk quota exceeded

      13-14                      Reserved for Digital

      15          .ICILI         Illegal instruction*

      16          .ICIRD         Illegal memory read*

      17          .ICIWR         Illegal memory write*

      18                         Reserved for Digital

      19          .ICIFT         Inferior process termination

      20          .ICMSE         System resources exhausted*

      21                         Reserved for Digital

      22          .ICNXP         Nonexistent page reference

      23-35                      Assignable by user program
   ______________________________________________________________________


   ---------------

    [1]  If an interrupt is generated in a  process  where  the  priority
         level  is  0,  the  system  considers  that  the  process is not
         prepared to handle the interrupt.  The process is then suspended
         or terminated according to the setting of bit 17 (SC%FRZ) in its
         capability word.


                                    4-5
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   *  These  channels  (called  panic  channels)  cannot  be   completely
      deactivated.   An  interrupt  generated  on  one  of these channels
      terminates the process if the channel is not activated.


   The  software  interrupt  system  processes  interrupts  on  activated
   channels  only,  and  each  channel  can  be activated and deactivated
   independently of other channels.   When  activated,  the  channel  can
   generate an interrupt for its associated priority level.  An interrupt
   for any priority level is initiated only if there are no interrupts in
   progress  for  the  same or higher priority levels.  If there are, the
   system remembers the interrupt request  and  initiates  it  after  all
   equal  or  higher priority level interrupts finish.  This means that a
   higher priority level request can suspend a routine processing a lower
   level  interrupt.  Thus, the user must be concerned with several items
   when he assigns his priority levels.  He must  consider  1)  when  one
   interrupt  request  can  suspend the processing of another and 2) when
   the processing of a second interrupt  cannot  be  deferred  until  the
   completion of the first.



   4.4  SOFTWARE INTERRUPT TABLES
   4.4  SOFTWARE INTERRUPT TABLES

   To process interrupts, the user includes,  as  part  of  his  program,
   special  service  routines for the channels he will be using.  He must
   then specify the addresses of these routines to the system by  setting
   up  a  channel  table.   In  addition,  the  user  must also include a
   priority level table as part of his program.  Finally, he must declare
   the addresses of these tables to the system.



   4.4.1  Specifying the Software Interrupt Tables
   4.4.1  Specifying the Software Interrupt Tables

   Before using the software interrupt system, the  user's  program  must
   set up the contents of the channel table and the priority level table.
   The program must then specify their addresses with either the SIR%  or
   XSIR% monitor calls.

   These calls are similar, but their  differences  are  important.   The
   SIR%  call  can be used in single-section programs, but the XSIR% call
   must be used in programs that use more than  one  section  of  memory.
   The SIR% call works in non-zero sections only if the tables are in the
   same section as the code that makes the call.  The  code  that  causes
   the  interrupt  must  also  be  in that section, as must the code that
   processes the interrupt.  Because of the limitations of the SIR% call,
   you should use the XSIR% call.

   The SIR% monitor call accepts two words of arguments:  the  identifier
   for  the  program (or process) in AC1, and the table addresses in AC2.
   Refer to Section 5.3 for the description of process identifiers.


                                    4-6
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   The following example shows the use of the SIR% call.

        MOVEI 1,.FHSLF           ;identifier of current process
        MOVE 2,[LEVTAB,,CHNTAB]  ;addresses of the tables
        SIR%

   The  XSIR%  call  accepts  the  following  arguments:   in  AC1,   the
   identifier  of  the process for which the interrupt channel tables are
   to be set; in AC2, the address of the argument block.

   The argument block is  a  three-word  block  that  has  the  following
   format:


           !======================================================!
           !   Length of the argument block, including this word  !
           !------------------------------------------------------!
           !          Address of the interrupt level table        !
           !------------------------------------------------------!
           !             Address of the channel table             !
           !======================================================!


   Control always returns  to  the  user's  program  at  the  instruction
   following  the  SIR%  and XSIR% calls.  If the call is successful, the
   table addresses are stored  in  the  monitor.   If  the  call  is  not
   successful, an illegal instruction trap is generated.

   Any changes made to the contents of the tables after the XSIR% or SIR%
   calls  have  been  executed  will be in effect at the time of the next
   interrupt.



   4.4.2  Channel Table
   4.4.2  Channel Table

   The channel table, CHNTAB,[2]  contains  a  one-word  entry  for  each
   channel;  thus, the table has 36 entries.  Each entry corresponds to a
   particular channel, and each channel is associated at any  given  time
   with  only  one  interrupt  condition.   (Refer  to  Table 4-1 for the
   interrupt conditions associated with each channel.)

   The CHNTAB table is indexed by the channel number (0 through 35).  The
   general format, for use with the XSIR% and XRIR% monitor calls, can be
   used in any section of memory.  The left half of each  entry  contains
   the  priority  level  (1,  2,  or 3) in bits 0-5 (SI%LEV) to which the
   channel is assigned.  Bits 6-35 (SI%ADR) of  each  entry  contain  the
   starting  address  of  the  routine to process interrupts generated on
   ---------------

    [2]  The user can  call  his  priority  channel  table  any  name  he
         desires; however, it is good practice to call it CHNTAB.


                                    4-7
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   that channel.  If a particular channel is not used, the  corresponding
   entry in the channel table should be zero.

   In the older format, for use with the  SIR%  and  RIR%  calls  by  any
   single-section  program,  the  left  half  of  each  word contains the
   priority level (1, 2, or 3) for that channel.  The right half contains
   the  address  of  the interrupt routine that will handle interrupts on
   that channel.

   The following example is for use with the XSIR% monitor call.

   CHNTAB: FLD(2,SI%LEV)+FLD(CHN0SV,SI%ADR)        ;channel 0
           FLD(2,SI%LEV)+FLD(CHN1SV,SI%ADR)        ;channel 1
           FLD(2,SI%LEV)+FLD(CHN2SV,SI%ADR)        ;channel 2
           FLD(2,SI%LEV)+FLD(CHN3SV,SI%ADR)        ;channel 3
           0                                       ;channel 4
           0                                       ;channel 5
           FLD(1,SI%LEV)+FLD(APRSRV,SI%ADR)        ;channel 6
           0                                       ;channel 7
           0                                       ;channel 8
           FLD(1,SI%LEV)+FLD(STKSRV,SI%ADR)        ;channel 9
           0                                       ;channel 10
            .                                        .
            .                                        .
            .                                        .
           0                                       ;channel 35

   In this example, channels 0 through 3 are assigned to  priority  level
   2,  with  the  interrupt  routine  at  CHN0SV servicing channel 0, the
   routine at CHN1SV servicing channel 1, the routine at CHN2SV servicing
   channel  2, and the routine at CHN3SV servicing channel 3.  Channels 6
   and 9 are assigned to priority level 1, with  the  routine  at  APRSRV
   servicing  channel  6  and  the routine at STKSRV servicing channel 9.
   All remaining channels are not assigned.



   4.4.3  Priority Level Table
   4.4.3  Priority Level Table

   The priority level table, LEVTAB,[3] The priority level table, LEVTAB,
   [3] is a three-word table, containing a one-word entry for each of the
   three priority levels.  In the general form, each  word  contains  the
   30-bit  address of the first word of the two-word block in the process
   address space.  The block addressed by word n of  LEVTAB  is  used  to
   store  the  global PC flags and address when an interrupt of level n+1
   occurs.

   The PC flags are stored in the first word of the PC block, and the  PC
   ---------------

    [3]  The user can call his priority level table any name he  desires;
         however, it is good practice to call it LEVTAB.


                                    4-8
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   address  is stored in the second.  This form of the table must be used
   with the XSIR% and XRIR%  monitor  calls,  and  can  be  used  in  any
   section.

   The older form of the  interrupt  level  table  can  be  used  in  any
   single-section program, and must be used with the SIR% and RIR% calls.
   This table also contains three words, indexed by  the  priority  level
   minus  1.   Each  word  contains zero in the left half, and the 18-bit
   address of the word in which to store the one-word section-relative PC
   in  the right half.  This address is assumed to be in the same program
   section that contained the SIR% monitor call.  (For  more  information
   see  Chapter 8.) The system must save the value of the program counter
   so that it can return control at the appropriate point in the  program
   once  the interrupt routine has completed processing an interrupt.  If
   a particular priority level is not used, its  corresponding  entry  in
   the level table should be zero.

   The following is a sample of a level table.

        LEVTAB:   0,,PCLEV1       ;Addresses to save PC for interrupts
                  0,,PCLEV2       ;occurring on priority levels 1 and 2.
                  0,,0            ;No priority level 3 interrupts are
                                  ;planned



   4.5  ENABLING THE SOFTWARE INTERRUPT SYSTEM
   4.5  ENABLING THE SOFTWARE INTERRUPT SYSTEM

   Once the interrupt tables have been set up and their addresses defined
   with  the  XSIR%  monitor  call,  the  user's  program must enable the
   interrupt system.  When the interrupt system  is  enabled,  interrupts
   that occur on activated channels are processed by the user's interrupt
   routines.   When  the  interrupt  system  is  disabled,  the   monitor
   processes  interrupts as if the channels for these interrupts were not
   activated.

   The EIR%  monitor  call,  used  to  enable  the  system,  accepts  one
   argument:  the identifier for the process in AC1.

        MOVEI 1,.FHSLF           ;identifier of current process
        EIR%

   Control always returns to the instruction following the EIR call.



   4.6  ACTIVATING INTERRUPT CHANNELS
   4.6  ACTIVATING INTERRUPT CHANNELS

   Once the software interrupt system is enabled, the channels  on  which
   interrupts  can  occur  must  be activated (refer to Table 4-1 for the
   channel assignments).  The channels to be  activated  have  a  nonzero
   entry in the appropriate word in the channel table.


                                    4-9
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   The AIC% monitor call activates  one  or  more  of  the  36  interrupt
   channels.   This  call accepts two words of arguments - the identifier
   for the process in AC1, and the channels to be activated in AC2.

   The channels are indicated by setting bits  in  AC2.   Setting  bit  n
   indicates  that channel n is to be activated.  The AIC% call activates
   only those channels for which bits are set.

        MOVEI 1,.FHSLF                     ;identifier of current process
        MOVE 2,[1B<.ICAOV>+1B<.ICPOV>]     ;activate channels 6 and 9
        AIC%

   Control always returns to the instruction following the AIC% call.

   Some  channels,  called  panic  channels,  cannot  be  deactivated  by
   disabling the channel or the entire interrupt system.  (Refer to Table
   4-1 for these  channels.)  This  is  because  the  occurrence  of  the
   conditions associated with these channels cannot be completely ignored
   by the monitor.

   If one of these conditions occurs, an interrupt is  generated  whether
   the channel is activated or not.  If the channel is not activated, the
   process is terminated, and usually a message is output before  control
   returns to the monitor.  If the channel is activated, control is given
   to the user's interrupt routine for that channel.



   4.7  GENERATING AN INTERRUPT
   4.7  GENERATING AN INTERRUPT

   A process generates an interrupt by producing a condition for which an
   interrupt channel is enabled, such as arithmetic overflow, or by using
   the IIC% monitor call.  This call can generate an interrupt on any  of
   the   36  interrupt  channels  of  the  process  the  calling  process
   specifies.  See Section 5.10 for a description of the IIC% call.



   4.8  PROCESSING AN INTERRUPT
   4.8  PROCESSING AN INTERRUPT

   When a software interrupt  occurs  on  a  given  priority  level,  the
   monitor  stores  the  current program counter (PC) word in the address
   indicated in the priority level table (refer to Section  4.4.3).   The
   monitor  then  transfers  control  to the interrupt routine associated
   with the channel on which the interrupt occurred.  The address of this
   routine is specified in the channel table (refer to Section 4.4.2).

   Since the user's program  cannot  determine  when  an  interrupt  will
   occur, the interrupt routine must preserve the state of the program so
   the program can be resumed properly.  First, the  routine  stores  the
   contents  of  any  user  accumulators  for  use  while  processing the
   interrupt.  After the accumulators are saved,  the  interrupt  routine
   processes the interrupt.

                                    4-10
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   Occasionally, an interrupt routine may need to alter locations in  the
   main  section  of  the program.  For example, a routine may change the
   stored PC word to resume execution at a location different from  where
   the  interrupt  occurred.   Or  it  may  alter a value that caused the
   interrupt.  It is important that care be used  when  writing  routines
   that  alter  data  because  any  changes  will  remain when control is
   returned to the main program.  For example, if data  is  inadvertently
   stored in the PC word, return to the main section of the program would
   be incorrect when the system attempted to use the word as the value of
   the program counter.

   If a higher-priority interrupt  occurs  during  the  execution  of  an
   interrupt  routine,  the  execution  of  the lower-priority routine is
   suspended.  The value of its program counter is stored at the location
   indicated in the priority level table for the new interrupt.  When the
   routine for this new interrupt is  completed,  the  suspended  routine
   resumes.

   If an interrupt of the  same  or  lower  priority  occurs  during  the
   execution  of  a  routine,  the  monitor holds the interrupt until all
   higher or equal level interrupts have been processed.

   The system considers the user's program unable to process an interrupt
   on an activated channel if any of the following is true:

        1.  The priority level associated with the channel is 0.

        2.  The program has not defined its interrupt tables by executing
            an XSIR% or SIR% monitor call.

        3.  The process has not enabled the interrupt system by executing
            an  EIR% monitor call, and the channel on which the interrupt
            occurs is a panic channel.

   In any of these cases, an interrupt on a panic channel terminates  the
   user's program.  All other interrupts are ignored.



   4.8.1  Dismissing an Interrupt
   4.8.1  Dismissing an Interrupt

   Once the processing of an interrupt is complete, the interrupt routine
   should restore the user accumulators to their initial values.  Then it
   should return control to the interrupted  code  by  using  the  DEBRK%
   monitor call.  This call restores the PC word and resumes the program.
   The call has no arguments, and must  be  the  last  statement  in  the
   interrupt routine.

   If the interrupt-processing routine has not  changed  the  PC  of  the
   user's program, the DEBRK% call restores the program to the same state




                                    4-11
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   the program was in just before the interrupt occurred.  If the program
   was  interrupted  while  waiting for I/O to complete, for example, the
   program will again be waiting for I/O  to  complete  when  it  resumes
   execution after the DEBRK% call.

   If the PC word was changed, the program resumes execution at  the  new
   PC location.  The state of the program is unchanged.



   4.9  TERMINAL INTERRUPTS
   4.9  TERMINAL INTERRUPTS

   The user's program can associate channels 0 through 5 and channels  24
   through  35  with  occurrences  of  various  conditions,  such  as the
   occurrence of a particular character typed  at  the  terminal  or  the
   receipt   of   an  IPCF  message.   This  section  discusses  terminal
   interrupts; refer to Chapters 6 and 7 for other  types  of  assignable
   interrupts.

   There are 36 codes used to specify terminal characters  or  conditions
   on  which  interrupts can be initiated.  These codes, along with their
   associated conditions, are shown in Table 4-2.


   Table 4-2:  Terminal Codes and Conditions
   Table 4-2:  Terminal Codes and Conditions

   ______________________________________________________________________

     Code         Symbol                   Character or Condition
   ______________________________________________________________________

      0           .TICBK                   CTRL/@  or break

      1           .TICCA                   CTRL/A

      2           .TICCB                   CTRL/B

      3           .TICCC                   CTRL/C

      4           .TICCD                   CTRL/D

      5           .TICCE                   CTRL/E

      6           .TICCF                   CTRL/F

      7           .TICCG                   CTRL/G

      8           .TICCH                   CTRL/H

      9           .TICCI                   CTRL/I

     10           .TICCJ                   CTRL/J


                                    4-12
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


     11           .TICCK                   CTRL/K

     12           .TICCL                   CTRL/L

     13           .TICCM                   CTRL/M

     14           .TICCN                   CTRL/N

     15           .TICCO                   CTRL/O

     16           .TICCP                   CTRL/P

     17           .TICCQ                   CTRL/Q

     18           .TICCR                   CTRL/R

     19           .TICCS                   CTRL/S

     20           .TICCT                   CTRL/T

     21           .TICCU                   CTRL/U

     22           .TICCV                   CTRL/V

     23           .TICCW                   CTRL/W

     24           .TICCX                   CTRL/X

     25           .TICCY                   CTRL/Y

     26           .TICCZ                   CTRL/Z

     27           .TICES                   ESC key

     28           .TICRB                   Delete (or rubout) key

     29           .TICSP                   Space

     30           .TICRF                   Dataset carrier off

     31           .TICTI                   Typein

     32           .TICTO                   Typeout

     33           .TITCE                   Two-character escape sequence

     34-35                                 Reserved
   ______________________________________________________________________


   To cause terminal interrupts to be generated, the user's program  must
   assign the desired terminal code to one of the assignable channels.


                                    4-13
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   The ATI% monitor call is used to assign this code.  This call  accepts
   one  word of arguments:  the terminal code in the left half of AC1 and
   the channel number in the right half.

        MOVE 1,[.TICCE,,INTCH1]  ;assign CTRL/E to channel INTCH1
        ATI%

   Control always returns to the instruction following the ATI% call.  If
   the  current  job  is not attached to a terminal (there is no terminal
   controlling the job), the terminal code  assignments  are  remembered;
   they will be in effect when a terminal is attached.

   The monitor handles the receipt of a terminal interrupt  character  in
   either  immediate  mode  or  deferred  mode.   In  immediate mode, the
   terminal character causes the system to initiate an interrupt as  soon
   as  the  user  types  the  character  (that  is, as soon as the system
   receives it).  In deferred mode, the terminal character is  placed  in
   either  immediate  mode  or  deferred  mode.   In  immediate mode, the
   terminal character causes the system to initiate an interrupt as  soon
   as  the  user types the character (as soon as the system receives it).
   In deferred mode, the terminal character is placed in the input stream
   in sequence with other characters of the input, unless two of the same
   character are typed in succession.  In this case, an interrupt  occurs
   at the time the second one is typed.  If only one character enabled in
   deferred mode is typed, the system initiates an  interrupt  only  when
   the  program  attempts  to  read  the character.  Deferred mode allows
   interrupt actions to occur in sequence with other actions specified in
   the  input  (for  example, when characters are typed ahead of the time
   that the  program  actually  requests  them).   In  either  mode,  the
   character  is  not  passed to the program as data.  The system assumes
   that interrupts are to be handled immediately  unless  a  program  has
   issued  the  STIW% (Set Terminal Interrupt Word) monitor call.  (Refer
      _______ _______ _____ _________ ______
   to TOPS-20 Monitor Calls Reference Manual for a  description  of  this
   call.)



   4.10  ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS
   4.10  ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS

   Additional monitor calls are available that allow the  user's  program
   to  check and to clear various parts of the software interrupt system.
   Also, there is a call useful for interprocess communication (refer  to
   the IIC% call in Section 5.10).



   4.10.1  Testing for Enablement
   4.10.1  Testing for Enablement

   The SKPIR% monitor call tests the software interrupt system to see  if
   it is enabled.  The call accepts in AC1 the identifier of the process.
   After execution of the call, control returns to the  next  instruction
   if  the  system is off, and to the second instruction if the system is
   on.

                                    4-14
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


        MOVEI 1,.FHSLF           ;identifier of current process
        SKPIR%                   ;test interrupt system
         return                  ;system is off
        return                   ;system is on



   4.10.2  Obtaining Interrupt Table Addresses
   4.10.2  Obtaining Interrupt Table Addresses

   The RIR% and XRIR% monitor calls obtain the channel and priority level
   table  addresses  for  a process.  These calls are useful when several
   routines in one process want to share the interrupt tables.



   4.10.2.1  The RIR% Monitor Call
   4.10.2.1  The RIR% Monitor Call - The RIR% monitor call can be used in
   any  section  of  memory,  but  is  only  useful  for  obtaining table
   addresses if those tables are in the same section  of  memory  as  the
   code  that  makes  the  call.   Furthermore,  it can only obtain table
   addresses that have been set by the SIR call.

   The call accepts the identifier of the process in AC1.  It returns the
   table   addresses   in  AC2.   The  left  half  of  AC2  contains  the
   section-relative address of the priority level table,  and  the  right
   half  contains  the section-relative address of the channel table.  If
   the process has not set the table  addresses  with  the  SIR%  monitor
   call, AC2 contains zero.

   Control always returns to the instruction following the RIR% call.

   The following example shows the use of the RIR% call.

        MOVEI 1,.FHSLF           ;identifier of current process
        RIR%                     ;return the table addresses




   4.10.2.2  The XRIR% Monitor Call
   4.10.2.2  The XRIR% Monitor Call - This call obtains the addresses  of
   the  interrupt tables defined for a process.  The tables can be in any
   section of memory.  The code that makes the call can also  be  in  any
   section.   This  call  can only obtain addresses that have been set by
   the XSIR% call.

   The call accepts the identifier of the process in AC1, and the address
   of the argument block in AC2.  The argument block is three words long,
   word zero must contain the number 3.  The call returns  the  addresses
   into words one and two.  The block has the following format:






                                    4-15
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


           !=======================================================!
           !   Length of the argument block, including this word   !
           !-------------------------------------------------------!
           !          Address of the interrupt level table         !
           !-------------------------------------------------------!
           !             Address of the channel table              !
           !=======================================================!


   Control always returns to the instruction following  the  XRIR%  call.
   If  the process has not set the table addresses with the XSIR% monitor
   call, words one and two of the argument block contain zero.



   4.10.3  Disabling the Interrupt System
   4.10.3  Disabling the Interrupt System

   The DIR% monitor call disables the software interrupt system  for  the
   process.  It accepts the identifier of the process in AC1.

        MOVEI 1,.FHSLF           ;identifier of current process
        DIR%                     ;disable system

   Control always returns to the instruction following the DIR% call.

   If interrupts occur while the interrupt system is disabled,  they  are
   remembered   until  the  system  is  reenabled.   At  that  time,  the
   interrupts take effect unless an intervening CIS% monitor call  (refer
   to Section 4.10.6) has been issued.

   Software interrupts assigned to  panic  channels  are  not  completely
   disabled  by  the  DIR% call.  These interrupts terminate the process,
   and the superior process is notified if it has enabled channel .ICIFT.
   In addition, if the terminal code for CTRL/C (.TICCC) is assigned to a
   channel, it causes an interrupt that cannot be disabled  by  the  DIR%
   call.   However,  the CTRL/C interrupt can be disabled by deactivating
   the channel assigned to the CTRL/C terminal code.



   4.10.4  Deactivating a Channel
   4.10.4  Deactivating a Channel

   The DIC% monitor call is used to deactivate interrupt  channels.   The
   call  accepts  two words of arguments:  the process identifier in AC1,
   and the channels to be deactivated in  AC2.   Setting  bit  n  in  AC2
   indicates that channel n is to be deactivated.

        MOVEI 1,.FHSLF                     ;identifier of current process
        MOVE 2,[1B<.ICAOV>+1B<.ICPOV>]     ;deactivate channels 6 and 9
        DIC%

   Control always returns to the instruction following the DIC% call.


                                    4-16
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   When a channel is deactivated, interrupt requests for that channel are
   ignored  except  for  interrupts generated on panic channels (refer to
   Section 4.6).



   4.10.5  Deassigning Terminal Codes
   4.10.5  Deassigning Terminal Codes

   The DTI% monitor call deassigns a terminal code.   This  call  accepts
   one argument word:  the terminal code in AC1.

        MOVEI 1,.TICCE           ;deassign CTRL/E
        DTI%

   Control always returns to the instruction  following  the  DTI%  call.
   This  monitor  call  is ignored if the specified terminal code has not
   been defined by the current job.



   4.10.6  Clearing the Interrupt System
   4.10.6  Clearing the Interrupt System

   The CIS% monitor call clears the  interrupt  system  for  the  current
   process.   This  call  clears  interrupts  in progress and all waiting
   interrupts.  This call  requires  no  arguments,  and  control  always
   returns to the instruction following the CIS call.  The RESET% monitor
   call (refer to Section 2.6.1) performs these same actions as  part  of
   its initializing procedures.



   4.11  SUMMARY
   4.11  SUMMARY

   To use the software interrupt system, the user's program must:

        1.  Supply routines that will process the interrupts.

        2.  Set up a  channel  table  containing  the  addresses  of  the
            routines  (refer to Section 4.4.2) and a priority level table
            containing the addresses for storing the program counter (PC)
            values (refer to Section 4.4.3).

        3.  Specify the addresses of the tables with  the  XSIR%  monitor
            call (refer to Section 4.4.3).

        4.  Enable the software interrupt system with  the  EIR%  monitor
            call (refer to Section 4.5).

        5.  Activate the desired channels  with  the  AIC%  monitor  call
            (refer to Section 4.6).




                                    4-17
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   4.12  SOFTWARE INTERRUPT EXAMPLE
   4.12  SOFTWARE INTERRUPT EXAMPLE

   This program copies one file to another.  It  accepts  the  input  and
   output  filenames  from  the  user.   The end of file is detected by a
   software interrupt, and CTRL/E is enabled as an escape character.

           TITLE SOFTWARE INTERRUPT EXAMPLE
           SEARCH MONSYM
           SEARCH MACSYM
           .REQUIRE SYS:MACREL

           STDAC.                  ;DEFINE STANDARD ACs
           INTCH1=1

   START:  RESET%                  ;RELEASE FILES, ETC.
           XHLLI T1,EOFINT         ;GET CURRENT PROCESS SECTION NUMBER
           HLLZS T1                ;ISOLATE SECTION NUMBER ONLY
           IORM T1,CHNTAB+INTCH1   ; AND ADD IT TO SERVICE ROUTINE 
           IORM T1,CHNTAB+.ICEOF   ;ADDRESSES FOR OUR ROUTINES
           IORM T1,LEVTAB+1        ; AND LEVTAB
           MOVEI T1,.FHSLF         ;CURRENT PROCESS
           MOVEI T2,3              ;NUMBER OF WORDS IN ARG BLOCK
           MOVEM T2,ARGBLK         ;PUT NUMBER IN WORD ZERO
           XMOVEI T2,LEVTAB        ;GLOBAL ADDRESS OF LEVEL TABLE
           MOVEM T2,ARGBLK+1       ;MOVE IT TO ARGBLK WORD ONE
           XMOVEI T2,CHNTAB        ;GLOBAL ADDRESS OF CHANNEL TABLE
           MOVEM T2, ARGBLK+2      ;MOVE IT TO ARGBLK WORD TWO
           XMOVEI T2,ARGBLK        ;GLOBAL ADDRESS OF ARGUMENT BLOCK
           XSIR%
           EIR%                    ;ENABLE SYSTEM
           MOVE T2,[1B<INTCH1>+1B<.ICEOF>] ;ACTIVATE CHANNELS
           AIC%
           MOVE T1,[.TICCE,,INTCH1] ;ASSIGN CTRL/E TO CHANNEL 1
           ATI%
   GETIF:  TMSG <INPUT FILE: >
           MOVX T1,GJ%OLD+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT
           MOVE T2,[.PRIIN,,.PRIOU]
           GTJFN%                  ;GET FILENAME FROM USER
            ERJMP ERROR1
           MOVEM T1,INJFN
   GETOF:  TMSG <OUTPUT FILE: >
           MOVX T1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT
           MOVE T2,[.PRIIN,,.PRIOU]
           GTJFN%                  ;GET FILENAME FROM USER
            ERJMP ERROR2
           MOVEM T1,OUTJFN








                                    4-18
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   OPNIF:  MOVE T1,INJFN
           MOVX T2,FLD(7,OF%BSZ)+OF%RD
           OPENF%                  ;OPEN INPUT FILE
            ERJMP ERROR3
   OPNOF:  MOVE T1,OUTJFN
           MOVX T2,FLD(7,OF%BSZ)+OF%WR
           OPENF%                  ;OPEN OUTPUT FILE
            ERJMP ERROR3
   CPYBYT: MOVE T1,INJFN
           BIN%                    ;READ INPUT BYTE
           MOVE T1,OUTJFN
           BOUT%                   ;WRITE OUTPUT BYTE
           JRST CPYBYT             ;LOOP UNTIL EOF
   DONE:   MOVE T1,INJFN
           CLOSF%                  ;CLOSE INPUT FILE
            JFCL
           MOVE T1,OUTJFN
           CLOSF%                  ;CLOSE OUTPUT FILE
            JFCL
           HALTF%
   ;ROUTINE TO HANDLE ^E - ABORTS OPERATION

   CTRLE:  MOVEI T1,.PRIOU
           CFOBF%                  ;CLEAR OUTPUT BUFFER
           TMSG <ABORTED.>         ;INFORM USER
           CIS%                    ;CLEAR SYSTEM
           JRST START

   ;ROUTINE TO HANDLE EOF - COMPLETES OPERATION NORMALLY

   EOFINT: MOVEM T1,INTAC1         ;SAVE ACs
           XMOVEI T1,DONE          ;CHANGE PC
           MOVEM T1,PC2+1          ;TO DONE
           MOVE T1,INTAC1          ;RESTORE ACs
           DEBRK%                  ;DISMISS INTERRUPT

   ;LEVEL TABLE
   LEVTAB: 0
           PC2
           0
   PC2:    BLOCK 2













                                    4-19
                    USING THE SOFTWARE INTERRUPT SYSTEM
                    USING THE SOFTWARE INTERRUPT SYSTEM


   ;CHANNEL TABLE
   CHNTAB: 0
           FLD(2,SI%LEV)!FLD(CTRLE,SI%ADR)
           REPEAT ^D8,<0>
           FLD(2,SI%LEV)!FLD(EOFINT,SI%ADR)
           REPEAT ^D25,<0>
   ARGBLK: BLOCK 3
   INJFN:  BLOCK 1
   OUTJFN: BLOCK 1
   INTAC1: BLOCK 1
   ERROR1: TMSG <
   ?INVALID FILE SPECIFICATION>
           HALTF%
   ERROR2: TMSG <
   ?INVALID FILE SPECIFICATION>
           HALTF%
   ERROR3: TMSG <
   ?CANNOT OPEN FILE>
           HALTF%
           LIT
           END START

































                                    4-20












                                 CHAPTER 5
                                 CHAPTER 5

                             PROCESS STRUCTURE
                             PROCESS STRUCTURE



   As stated in Chapter 1, the TOPS-20 operating system allows  each  job
   to  have multiple processes that can run simultaneously.  Each process
   has its own environment called its address space.  Associated with the
   environment  is  the  program  counter  (PC)  of  the  process  and  a
   well-defined  relationship  with  other  processes  in  the  job.   In
   TOPS-20, the term fork is synonymous with the term process.

   The TOPS-20 operating system schedules the running of  processes,  not
   entire  jobs.   A  process  can  be  scheduled  independent  of  other
   processes because it has a definite existence:  its beginning  is  the
   time  at  which  it is created, and its end is the time at which it is
   killed.  At any point in its existence, a process can be described  by
   its  state, which is represented by a status word and a PC word (refer
   to Section 5.9).

   The relationships among processes in a job are shown  in  the  diagram
   below.   Each  process  has one immediate superior process (except for
   the top-level process) and can have one or  more  inferior  processes.
   Two  processes  are parallel if they have the same immediate superior.
   A process can create  an  inferior  process  but  not  a  parallel  or
   superior process.


                               --------------
                               |  Top-Level |
                               |   Process  |
                               --------------
                                      |
                ----------------------|--------------------
                |                     |                   |
           -------------         -------------       -------------
           | Process 1 |         | Process 2 |       | Process 3 |
           -------------         -------------       -------------
                |                                         |
           -------------                            -------------
           | Process 4 |                            | Process 5 |
           -------------                            -------------


                                    5-1
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   Process 1 is the superior process of process 4, and process 3  is  the
   superior  of  process  5.   Processes  4  and  5  are the inferiors of
   processes 1 and 3, respectively.  Process 2 has no  inferior  process.
   Processes  1, 2 and 3 are parallel because they have the same superior
   process (the top-level process).  Processes 4 and 5, although  at  the
   same depth in the structure, are not parallel because they do not have
   the same superior process.  Process 1 created process 4 but could  not
   have created any other process shown in the structure above.



   5.1  USES FOR MULTIPLE PROCESSES
   5.1  USES FOR MULTIPLE PROCESSES

   A multiple-process job structure allows:

        1.  One job to have more than one program runnable  at  the  same
            time.   These  programs can be independent programs, each one
            compiled, debugged, and loaded separately.  Each program  can
            then be placed in a separate process.  These processes can be
            parallel to each other, but are inferior to the main  process
            that created them.  This use allows parallel execution of the
            individual programs.

        2.  One process to wait for an event to occur (for  example,  the
            completion   of  an  I/O  operation)  while  another  process
            continues its computations.  Communication  between  the  two
            processes  is  such  that  when the event occurs, the process
            that is computing can be notified via the software  interrupt
            system.   This  use  allows  two  processes  within  a job to
            overlap I/O with computations.

   One application of a multiple-process job structure is  the  following
   situation:  a superior process is responsible for accepting input from
   various terminals.  After receiving this input, the process  sends  it
   to  various  inferior processes as data.  These inferior processes can
   then initiate other processes, for example, to write  reports  on  the
   data that was received.

















                                    5-2
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


                         ------------------
          ---------      |                |     ---------
          |       |      | Process that   |     |       |
          |  TTY  |------| Accepts input  |-----|  TTY  |
          |       |      | from Terminals |     |       |
          ---------      |                |     ---------
                         ------------------
                                  |
                     -------------|-------------
                     |            |            |
                     |            |            |
                  -------      -------      -------
                  |     |      |     |      |     | Processes that
                  |     |      |     |      |     | Receive the
                  |     |      |     |      |     | input as Data
                  -------      -------      -------
                     |            |            |
                     |            |            |
                  -------      -------      -------
                  |     |      |     |      |     | Processes that
                  |     |      |     |      |     | Write Reports
                  |     |      |     |      |     | on the Data
                  -------      -------      -------


   Another application is  that  used  for  the  user  interface  on  the
   DECSYSTEM-20.   On  the DECSYSTEM-20, the top-level process in the job
   structure is the Command Language.  This process services the user  at
   the  terminal  by  accepting input.  When the user runs a program (for
   example, MACRO, FORTRAN), the  Command  Language  process  creates  an
   inferior process, places the requested program in it, and executes it.
   The Command Language can then wait for an event to occur, either  from
   the  program  or  from the user.  An event from the program can be its
   completion, and an event from the user can be the typing of a  certain
   terminal key (CTRL/C, for example).



   5.2  PROCESS COMMUNICATION
   5.2  PROCESS COMMUNICATION

   A process can communicate with  or  control  other  processes  in  the
   system in several ways:

         o  direct process control

         o  software interrupts

         o  IPCF and ENQ/DEQ facilities

         o  memory sharing




                                    5-3
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   5.2.1  Direct Process Control
   5.2.1  Direct Process Control

   A process can create and control other processes inferior to it within
   the  job  structure.   The  superior  process  can  cause the inferior
   process to begin execution  and  then  to  suspend  and  later  resume
   execution.   After  the  inferior process has completed its tasks, the
   superior process can delete the inferior from the job structure.

   Some of the  monitor  calls  used  for  direct  process  control  are:
   CFORK%,  to  create  a process; SFORK%, to start a process; WFORK%, to
   wait for a process to terminate; RFSTS%, to obtain  the  status  of  a
                                                                  _______
   process;  and  KFORK%,  to  delete  a  process.   Refer to the TOPS-20
   _______ _____ _________ ______
   Monitor Calls Reference Manual for descriptions of additional  monitor
   calls dealing with process control.



   5.2.2  Software Interrupts
   5.2.2  Software Interrupts

   The  software  interrupt  facility  enables  a  process   to   receive
   asynchronous signals from other processes, the system, or the terminal
   user or to receive signals as a result  of  its  own  execution.   For
   example, a superior process can enable the interrupt system so that it
   receives an interrupt  when  one  of  its  inferiors  terminates.   In
   addition,  processes  within  a  job structure can explicitly generate
   interrupts to each other for communication purposes.

   Some of the monitor calls  used  when  communication  occurs  via  the
   software interrupt system are:  SIR%, to specify the interrupt tables;
   EIR%, to enable the interrupt system; AIC%, to activate the  interrupt
   channels;  and  IIC%, to initiate an interrupt on a channel.  Refer to
   Chapter 4 and Section 5.10 for more information.



   5.2.3  IPCF and ENQ/DEQ Facilities
   5.2.3  IPCF and ENQ/DEQ Facilities

   The Inter-Process Communication Facility (IPCF) enables processes  and
   jobs  to  communicate by sending and receiving informational messages.
   The MSEND% call is used to send a message, the MRECV% call is used  to
   receive  a  message,  and  the  MUTIL% call is used to perform utility
   functions.  Refer to Chapter 7 for descriptions of these calls.

   The ENQ/DEQ facility allows cooperating processes to  share  resources
   and facilitates dynamic resource allocation.  The ENQ% call is used to
   obtain a resource, the DEQ% call is used to release  a  resource,  and
   the  ENQC%  call  is used to obtain status about a resource.  Refer to
   Chapter 6 for descriptions of these calls.






                                    5-4
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   5.2.4  Memory Sharing
   5.2.4  Memory Sharing

   Each page or section in a process' address space is either private  to
   the  process  or  shared with other processes.  Pages are shared among
   processes when the same page is represented in more than one  process'
   address space.  This means that two or more processes can identify and
   use the same page of physical storage.  Even  when  several  processes
   have  identified  the  same  page,  each  process can have a different
   access to that page, such as access to read or write that page.

   A type of page access that facilitates sharing  is  the  copy-on-write
   access.   A  page  with  this  access  remains  shared  as long as all
   processes read the page.  As soon as a process writes to the page, the
   system  makes  a  private  copy  of the page for the process doing the
   writing.  Other processes continue to read and  execute  the  original
   page.   This  access  provides  the  capability  of sharing as much as
   possible but still allows the  process  to  change  its  data  without
   changing  the  data  of  other  processes.   A  monitor call used when
   sharing memory is PMAP%.  Refer to Section 5.6.2 for more information.



   5.3  PROCESS IDENTIFIERS
   5.3  PROCESS IDENTIFIERS

   In order for processes to communicate with each other, a process  must
   have  an identifier, or handle, for referencing another process.  When
   a process creates an inferior process, it is given a  handle  on  that
   inferior.   This  handle is a number in the range 400001 to 400777 and
   is meaningful only to the process to which it is given  (that  is,  to
   the  superior  process).  For example, if process A creates process B,
   process A is given a  handle  (for  example,  400003)  on  process  B.
   Process  A  then specifies this handle when it uses monitor calls that
   refer to process B.  However, process B is not known by this handle to
   any  other  process  in  the  structure, including itself.  The handle
   400003 may in fact be known to process B,  but  it  would  describe  a
   process  inferior  to process B.  For this reason, process handles are
   sometimes called "relative fork handles" because they are relative  to
   the process that created them.

   There are several standard process handles that are never assigned  by
   the system but have a specific meaning when used by any process in the
   structure.  These handles are used when a process needs to communicate
   with  a  process  other  than  its immediate inferior or with multiple
   processes at once.  These handles are described in Table 5-1.










                                    5-5
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   Table 5-1:  Process Handles
   Table 5-1:  Process Handles

   ______________________________________________________________________

     Number       Symbol         Meaning
   ______________________________________________________________________

     400000       .FHSLF         The current process (or self).

     400000+n                    Process n,  relative  to  the  current
                                 process.

     200000       FH%EPN         Extended page number  (see  PM%EPN  in
                                 PMAP%).  When used in conjunction with
                                 the  above   two   forms,   this   bit
                                 indicates  that  addresses and/or page
                                 numbers are interpreted  as  absolute,
                                 not  relative to the PC section of the
                                 program executing the JSYS.  This  bit
                                 has  no  meaning  for programs that do
                                 not use extended addressing.

       -1         .FHSUP         The immediate superior of the  current
                                 process.

       -2         .FHTOP         The  top-level  process  in  the   job
                                 structure.

       -3         .FHSAI         The current process  and  all  of  its
                                 inferiors.

       -4         .FHINF         All of the inferiors  of  the  current
                                 process.

       -5         .FHJOB         All processes in the job structure.
   ______________________________________________________________________


   Consider the job structure below.















                                    5-6
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


                                   -------
                                   |  A  |
                                   -------
                                      |
                       ---------------|---------------
                       |              |              |
                    -------        -------        -------
                    |  B  |        |  C  |        |  D  |
                    -------        -------        -------
                                                     |
                                             --------|-------
                                             |              |
                                          -------        -------
                                          |  E  |        |  F  |
                                          -------        -------
                                             | 
                                      -------|--------
                                      |              |
                                   -------        -------
                                   |  G  |        |  H  |
                                   -------        -------


   The following  indicates  the  specific  process  or  processes  being
   referenced if process E gives the handle:

        .FHSLF    refers to process E
        .FHSUP    refers to process D
        .FHTOP    refers to process A
        .FHSAI    refers to processes E, G, and H
        .FHINF    refers to processes G and H
        .FHJOB    refers to processes A through H

   The process must  have  the  appropriate  capability  enabled  in  its
   capability  word  to use the handles .FHSUP, .FHTOP, and .FHJOB (refer
   to Section 5.5.1).

   Process E can reference one of its inferiors (for example, G) with the
   handle  it  was  given  when  it  created the inferior.  Process E can
   reference other  processes  in  the  structure  (for  example,  F)  by
   executing  the  GFRKS%  monitor call to obtain a handle on the desired
                          _______ _______ _____ _________  ______
   process.  Refer to the TOPS-20 Monitor Calls Reference  Manual  for  a
   description of the GFRKS% call.



   5.4  OVERVIEW OF MONITOR CALLS FOR PROCESSES
   5.4  OVERVIEW OF MONITOR CALLS FOR PROCESSES

   Monitor calls  exist  for  creating,  loading,  starting,  suspending,
   resuming,  interrupting,  and  deleting  processes.  When a process is
   created, its address space is assigned, and the process  is  added  to
   the  job  structure  of  the  creating  process.   The contents of its


                                    5-7
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   address space can be specified at the time the process is  created  or
   at  a  later  time.  The process can also be started at the time it is
   created.   A  process  remains  potentially  runnable  until   it   is
   explicitly deleted or its superior is deleted.

   A process may be suspended if one of the following conditions occurs:

        1.  The process executes an instruction that  causes  a  software
            interrupt  to  occur,  and  it is not prepared to process the
            interrupt.

        2.  The process executes the HALTF% monitor call.

        3.  The superior process requests suspension of its inferior.

        4.  The  superior  process  is  suspended.   When  a  process  is
            suspended, all of its inferior processes are also suspended.

        5.  A monitor call is trapped.  (Refer to TFORK% monitor call  in
                _______ _______ _____ _________ ______
            the TOPS-20 Monitor Calls Reference Manual).



   5.5  CREATING A PROCESS
   5.5  CREATING A PROCESS

   A process creates an inferior process by executing the CFORK%  (Create
   Process) monitor call.  This monitor call allows the caller to specify
   the address space, capabilities, initial contents of the ACs,  and  PC
   for the inferior process and to start the execution of the inferior.

   The CFORK% call accepts two words of arguments in AC1 and AC2.

        AC1:   characteristics for the inferior in the left half, and  PC
               address for the inferior in the right half.

        AC2:   address of a 20  (octal)  word  block  containing  the  AC
               values for the inferior.

   The characteristics for the inferior process are  described  in  Table
   5-2.














                                    5-8
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   Table 5-2:  Inferior Process Characteristic Bits
   Table 5-2:  Inferior Process Characteristic Bits

   ______________________________________________________________________

     Bit       Symbol       Meaning
   ______________________________________________________________________

      0        CR%MAP       Set the map of the inferior process to  the
                            same  as the map of the superior (creating)
                            process.  This means that the superior  and
                            the  inferior  will  share the same address
                            space.  Changes made by one process will be
                            seen by the other process.

                            If this bit is not  on  in  the  call,  the
                            inferior's  map will contain all zeros.  If
                            desired, the creating process can then  use
                            PMAP  or GET to add pages to the inferior's
                            map.

      1        CR%CAP       Set the capability  word  of  the  inferior
                            process  to the same as the capability word
                            of the superior process.  (Refer to Section
                            5.5.1 for the description of the capability
                            word.)

                            If this bit is not  on  in  the  call,  the
                            inferior will have no special capabilities.

      2                     Reserved for Digital (must be 0).

      3        CR%ACS       Set the ACs of the inferior process to  the
                            values  beginning  at  the address given in
                            AC2.

                            If this bit is not  on  in  the  call,  the
                            inferior's ACs will be set to zero, and the
                            contents of AC2 is ignored.

      4        CR%ST        Set the PC for the inferior process to  the
                            address  given in the right half of AC1 and
                            start execution of the inferior.

                            If this bit is not  on  in  the  call,  the
                            right  half  of  AC1  is  ignored,  and the
                            inferior is not started.  If  desired,  the
                            creating  process  can  then  use SFORK% or
                            XSFRK% to start the newly created process.

      18-35    CR%PCV       PC value for inferior process if  CR%ST  is
                            on.
   ______________________________________________________________________


                                    5-9
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   If execution of the  CFORK%  call  is  not  successful,  the  inferior
   process  is not created and an error code is returned, as described in
   Section 1.2.2.

   If execution of the CFORK% call is successful, the inferior process is
   created  and  its process handle is returned in the right half of AC1.
   This handle is then used by the superior  process  when  communicating
   with  its  inferior  process.   The  execution  of  the program in the
   superior process continues at the  second  instruction  following  the
   CFORK%  call.  The inferior begins execution at the location contained
   in bits 18-35 (CR%PCV) if CR%ST is specified.

   Assume that process A executes the CFORK% monitor call twice to create
   two  parallel  inferior  processes.   This  is represented pictorially
   below.


                       -------------------------
                       | Process A             |
                       | Creates Process B     |
                       | by Executing a CFORK  |
                       -------------------------
                                   |
                                   |
                       -------------------------
                       | Process B is Created  |
                       | and Its Handle is     |
                       |                       |
                       -------------------------
       
   --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --
       
                       -------------------------
                       | Process A Executes    |
                       | Another CFORK to      |
                       | Create Process C      |
                       -------------------------
                                   |
              ---------------------|---------------------
              |                                         |
   -------------------------                ------------------------
   |                       |                | Process C is Created |
   |      Process B        |                | and Its Handle       |
   |                       |                | Given to Process A   |
   -------------------------                ------------------------


   Note that process A has been given two handles, one for process B  and
   one  for process C.  Process A can refer to either of its inferiors by
   giving the appropriate handle or to both of its inferiors by giving  a
   handle of -4 (.FHINF).



                                    5-10
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   5.5.1  Process Capabilities
   5.5.1  Process Capabilities

   When a new process is created, it is given the  same  capabilities  as
   its  superior,  or  it  is  given  no  special  capabilities.  This is
   indicated by the setting of the CR%CAP bit in the  CFORK%  call.   The
   capabilities for a process are indicated by two capability words.  The
   first word indicates if the capability is available  to  the  process,
   and  the  second  word  indicates if the capability is enabled for the
   process.  This second word is the one being set by the CR%CAP  bit  in
   the CFORK% call.

   Types of capabilities represented in the  capability  words  are  job,
   process,  and  user  capabilities.   Each  capability corresponds to a
   particular bit in the capability words and thus can be  activated  and
   protected  independently  of  the  other  capabilities.   Refer to the
   _______ _______ _____ _________ ______
   TOPS-20 Monitor Calls Reference Manual for  more  information  on  the
   capability words.



   5.6  SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A PROCESS
   5.6  SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A PROCESS

   Once a process is created, the contents of its address  space  can  be
   specified.   This  can  be  accomplished  in  one  of  three ways.  As
   mentioned in Section 5.5, bit CR%MAP can be set in the CFORK% call  to
   indicate  that the address space of the  inferior process is to be the
   same as the address space of the creating process.  In  addition,  the
   creating  process  can  execute the GET% monitor call to map specified
   pages from a file into the address  space  of  the  inferior  process.
   Finally,  the  creating  process can execute the PMAP% monitor call to
   map specified pages from another process into the address space of the
   inferior process.

   If  the  creating  process  does  not  specify  the  contents  of  the
   inferior's address space, the address space will be filled with zeros.



   5.6.1  GET% Monitor Call
   5.6.1  GET% Monitor Call

   The GET% monitor call gets a save file, copying or mapping it into the
   process  as  appropriate.   It updates the monitor's data base for the
   process by copying the entry vector  and  the  list  of  program  data
   vector addresses (PDVAs) from the save file.  (See the .POADD function
   of the PDVOP% monitor call.)

   This call can be executed for  either  sharable  or  nonsharable  save
   files  that  were  created  with  the  SSAVE%  or  SAVE% monitor call,
   respectively.  The file must not be open by any process in the  user's
                          _______ _______ _____ _________ ______
   job.   (Refer  to  the TOPS-20 Monitor Calls Reference Manual for more
   information regarding the PDVOP%, SSAVE%, and SAVE% monitor calls.)



                                    5-11
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   The GET% monitor call accepts two words of arguments in AC1  and  AC2.
   The first word specifies the handle of the desired process, flag bits,
   and the JFN of the desired file.  The second word specifies where  the
   pages  from  the  file  are  to  be placed in the address space of the
   process.  Thus,

        AC1:   process handle,,flag bits and a JFN

        AC2:   lowest process page  number  in  left  half,  and  highest
               process  page  number  in right half; or the address of an
               argument block.  If this AC contains page  numbers,  those
               page  numbers  control the parts of memory that are loaded
               when GT%ADR is on in AC1.

   Table 5-3 describes the bits that can be set in AC1.


   Table 5-3:  GET% Flag Bits
   Table 5-3:  GET% Flag Bits

   ______________________________________________________________________

     Bit       Symbol       Meaning
   ______________________________________________________________________

      19       GT%ADR       Use the memory address limits given in AC2.
                            If  this  bit is off, all existing pages of
                            the file (according to its  directory)  are
                            mapped.

      20       GT%PRL       Preload the pages being  mapped  (move  the
                            pages immediately.) If this bit is off, the
                            pages are read in from the disk  when  they
                            are referenced.

      21       GT%NOV       Do not overlay existing pages and do return
                            an  error.   If  this  bit is off, existing
                            pages will be overlaid.

      22       GT%ARG       If this bit is on, AC2 contains the address
                            of an argument block.

      24-25    GT%JFN       JFN of the save file.
   ______________________________________________________________________


   The format of the argument block is described in Table 5-4.








                                    5-12
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   Table 5-4:  GET% Argument Block
   Table 5-4:  GET% Argument Block

   ______________________________________________________________________

     Word      Symbol       Meaning
   ______________________________________________________________________

      0        .GFLAG       Flags that indicate how  the  rest  of  the
                            argument block is to be used.

      1        .GLOW        Number of the lowest page  in  the  process
                            into  which  a file page gets loaded.  This
                            page must be within the  section  specified
                            by .GBASE.

      2        .GHIGH       Number of the highest page in  the  process
                            into  which  a file page gets loaded.  This
                            page must be within the  section  specified
                            by .GBASE.

      3        .GBASE       Number of the section into which  the  file
                            pages  are  loaded.   You  can  specify the
                            section for single-section save files only;
                            use  of  this  word with a multiple-section
                            save file causes an error.  The file  pages
                            are  loaded  into  this  section  of memory
                            regardless of the section specified in  the
                            save file.
   ______________________________________________________________________


   Table 5-5 describes the flag bits defined for use in .GFLAG.


   Table 5-5:  GET% Argument Block Flags
   Table 5-5:  GET% Argument Block Flags

   ______________________________________________________________________

     Bit       Symbol       Meaning
   ______________________________________________________________________

      0        GT%LOW       .GLOW contains the  number  of  the  lowest
                            page within the process to use.

      1        GT%HGH       .GHIGH contains the number of  the  highest
                            page within the process to use.

      2        GT%BAS       .GBASE contains the number of  the  section
                            to use.
   ______________________________________________________________________




                                    5-13
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   When the pages of the file are mapped  into  pages  in  the  process's
   address  space,  the  previous  contents  of  the  process  pages  are
   overwritten.  Any full pages in the process that are  not  overwritten
   are  unchanged.   Any  portions of process pages for which there is no
   data in the file are filled with zeros.

   For example, a GET% call executed for a file that contains 2 1/2 pages
   sets up the process' address space as shown in the following diagram.


                  Process                       File
                 ------------  - - - - - - - - ---------
          Page 1 | Data     |   /              | Data  |  Page 1
                 |          |   |              |       |
                 |          |   |              |       |
                 |          |   /  GET         |       |
                 |----------|   \  Call        |-------|
          Page 2 | Data     |   |              | Data  |  Page 2
                 |          |   |              |       |
                 |----------|   |              |-------|
          Page 3 | Data     |   \              | Data  |  Page 3
                 |----------|  - - - - - - - - |-------|
                 |          |                  | EOF   |
                 |          |                  |       |
                 | 0        |                  |       |
                 |----------|                  ---------
                 |          |
        Page 4 - |Unchanged |
        Page 512 |          |
                 ------------


   After execution of the  GET%  call,  control  returns  to  the  user's
   program  at the instruction following the call.  If an error occurs, a
   software interrupt is generated, which the program can process via the
   software interrupt system.



   5.6.2  PMAP% Monitor Call
   5.6.2  PMAP% Monitor Call

   The PMAP% monitor call is used to map pages from one  process  to  the
   address  space of a second process.  Data is not actually transferred;
   only the contents of the page map of the second (that is, destination)
   process are changed.

   The PMAP% monitor call accepts three words of arguments in AC1 through
   AC3.   The first word contains the handle and page number of the first
   page to be mapped in the source process (that is,  the  process  whose
   pages are being mapped).  The second word contains the handle and page
   number of the first page to be mapped in the destination process (that
   is, the process into which the pages are being mapped).  The third


                                    5-14
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   word contains a  count  of  the  number  of  pages  to  map  and  bits
   indicating  the  access  that the destination process will have to the
   pages mapped.  Thus,

        AC1:  source process handle in the left half, and page number  in
              the process in the right half.

        AC2:  destination process handle  in  the  left  half,  and  page
              number in the process in the right half.

        AC3:  count of number of pages to map and the access bits.

   The count and access bits that can be specified in AC3  are  described
   in Section 3.5.6.1.

   Upon  successful  execution  of  the  PMAP%  call,  addresses  in  the
   destination process actually refer to addresses in the source process.
   The contents of the destination page previous to the execution of  the
   call  have  been  deleted.   The access requested in the PMAP% call is
   granted if it does  not  conflict  with  the  current  access  of  the
   destination  page  (that is, an AND operation is performed between the
   specified access and the current  access).   Control  returns  to  the
   user's  program  at  the  instruction following the PMAP% call.  If an
   error occurs, an illegal instruction  trap  is  generated,  which  the
   program can process via the software interrupt system or with an ERJMP
   or ERCAL instruction.



   5.7  STARTING AN INFERIOR PROCESS
   5.7  STARTING AN INFERIOR PROCESS

   A program in an inferior process can be started in one  of  two  ways.
   As  mentioned  in Section 5.5, the superior process can specify in the
   CFORK% call the PC for the inferior process and start  its  execution.
   Alternatively,  the  superior process, after executing the CFORK% call
   to create an inferior process, can execute the SFORK% (Start  Process)
   monitor call to start it.

   The SFORK% monitor call accepts two words of arguments in AC1 and AC2.

        AC1:  flags,,process handle

              Flags:

                 SF%CON(1B0)   Used  to  continue  a  process  that   has
                               previously  halted.  If SF%CON is set, the
                               address in AC2 is ignored, and the process
                               continues from where it was halted.

        AC2:  the PC of the process being started.  The PC contains flags
              in  the  left  half and the process starting address in the
              right half.  This call obtains the section number of the PC
              from the entry vector of the process.

                                    5-15
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   There are two  alternative  ways  to  start  processes:   XSFRK%  (see
                                          _______ _______ _____ _________
   Section  8.3.2)  or  SFRKV%  (see  the TOPS-20 Monitor Calls Reference
   ______
   Manual).

   The process handle given in AC1 cannot refer to a superior process, to
   more  than one process (for example, .FHINF), or to a process that has
   already been started.

   After execution of the SFORK% call,  control  returns  to  the  user's
   program  at the instruction following the call.  If an error occurs, a
   software interrupt is generated, which the program can process via the
   software interrupt system.



   5.8  INFERIOR PROCESS TERMINATION
   5.8  INFERIOR PROCESS TERMINATION

   The superior process has one of two ways in which it can  be  notified
   when  one  or  more  of  its  inferiors  terminate execution:  via the
   software interrupt system or by executing the WFORK% monitor call.  An
   inferior  process  will  terminate  normally when it executes a HALTF%
   monitor call.  Alternatively, the process  will  terminate  abnormally
   when  it  executes an instruction that generates a software interrupt,
   such  as  an  illegal  instruction,  and  it  has  not  activated  the
   appropriate channel.

   By  activating  channel  .ICIFT  (channel  19)  for  inferior  process
   termination  and  enabling the software interrupt system, the superior
   process  will  receive  an  interrupt  when  one  of   its   inferiors
   terminates.   (Refer  to  Section  4.6  for  information on activating
   channel .ICIFT.)  The  interrupt  occurs  when  any  inferior  process
   terminates.   Use  of  the  interrupt system allows the superior to do
   other  processing  until  an  interrupt  occurs,  indicating  that  an
   inferior process has terminated.

   In some cases, however, the superior cannot do  additional  processing
   until  either a specific process or all of its inferior processes have
   completed execution.  If this is the case, the  superior  process  can
   execute  the WFORK% (Wait Process) monitor call.  This call blocks the
   superior until one or all of its inferiors have terminated.

   The WFORK% monitor call accepts one argument in AC1, the handle of the
   desired process.  This handle can be .FHINF (-4) to block the superior
   until all inferiors terminate, but cannot be a handle  on  a  superior
   process.

   After execution of the WFORK% monitor call,  control  returns  to  the
   user's  program  at  the  instruction  following  the  call,  when the
   specified process or all of the inferior processes terminate.   If  an
   error occurs, it generates a software interrupt, which the program can
   process via the software interrupt system.



                                    5-16
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   5.9  INFERIOR PROCESS STATUS
   5.9  INFERIOR PROCESS STATUS

   The superior process can obtain the status of one of its inferiors  by
   executing  the  RFSTS%  (Read Process Status) monitor call.  This call
   returns the status and PC words of the given inferior process.

   The short form of the RFSTS% monitor call accepts one argument in AC1,
   the  handle  of  the  desired  process.  This handle cannot refer to a
   superior process or to more than one process.  The long  form  accepts
   two  argument words:  flags,, process handle in AC1 and the address of
   the status return block in AC2.  In the long form, RF%LNG (bit  0)  is
   set in AC1 and bits 1-17 are unused (must be zero).

   After execution of the short form of the RFSTS% call, control  returns
   to  the  user's program at the instruction following the call.  If the
   RFSTS% call is successful, AC1 contains the status word of  the  given
   process  and  AC2  contains  the PC word.  The status word is shown in
   Table 5-6.


   Table 5-6:  Process Status Word
   Table 5-6:  Process Status Word

   ______________________________________________________________________

     Bit       Symbol       Meaning
   ______________________________________________________________________

     0         RF%FRZ       The process is suspended (that is, frozen).
                            If  this  bit is not on, the process is not
                            suspended.

     1-17      RF%STS       The status of the process.

                            Value     Symbol    Meaning

                              0       .RFRUN    The     process      is
                                                runnable.

                              1       .RFIO     The process  is  halted
                                                waiting for I/O

                              2       .RFHLT    The process  is  halted
                                                by  a  HFORK% or HALTF%
                                                monitor  call  or   was
                                                never started.


                              3       .RFFPT    The process  is  halted
                                                by  the occurrence of a
                                                software interrupt  for
                                                which    it   was   not
                                                prepared   to   handle.


                                    5-17
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


                                                The  right  half of the
                                                status  word   contains
                                                the   number   of   the
                                                channel  on  which  the
                                                interrupt occurred.

                              4       .RFWAT    The process  is  halted
                                                waiting   for   another
                                                process to terminate.

                              5       .RFSLP    The process  is  halted
                                                for  a specified amount
                                                of time.

                              6       .RFTRP    The     process      is
                                                dismissed   because  it
                                                was intercepted by  its
                                                superior.

                              7       .RFABK    The     process      is
                                                dismissed       because
                                                address    break    was
                                                encountered.

     18-35     RF%SIC       The channel number on  which  an  interrupt
                            occurred,   which   the   process  was  not
                            prepared to handle (see process status code
                            .RFFPT above).
   ______________________________________________________________________


   The RFSTS% call returns with -1 (fullword) in  AC3  if  the  specified
   handle  is  assigned  but  refers  to  a  deleted  process.   The call
   generates  an  illegal  instruction  interrupt  if   the   handle   is
   unassigned.

   In the long form of the RFSTS% monitor call, RF%LNG is set in AC1  and
   AC2 contains the address of a status-return block.  On the return, AC1
   and AC2 are not modified.  The status-return  block  is  described  in
   Table 5-7.


   Table 5-7:  RFSTS% Status-Return Block
   Table 5-7:  RFSTS% Status-Return Block

   ______________________________________________________________________

     Word      Symbol       Meaning
   ______________________________________________________________________

      0        .RFCNT       Count of words returned in  this  block  in
                            the  left half, and count of maximum number
                            of words to return in right half (including


                                    5-18
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


                            this word).  The right half of this word is
                            specified by the user.

      1        .RFPSW       Process status word.   This  word  has  the
                            same format as AC1 on a return from a short
                            call.  If a valid, but unassigned,  process
                            handle was specified in AC1, then this word
                            contains  -1  and  no   other   words   are
                            returned.

      2        .RFPFL       Process PC flags.  These are the same flags
                            returned in AC2 on a short call.

      3        .RFPPC       Process PC.  This is the address; no  flags
                            are returned in this word.

      4        .RFSFL       Status flag word.

                            Flags:

                            Bit    Symbol   Meaning

                            B0     RF%EXO   Process is execute-only.
   ______________________________________________________________________


   If an error occurs during execution of the  RFSTS%  call,  a  software
   interrupt  is generated which the program can process via the software
   interrupt system.



   5.10  PROCESS COMMUNICATION
   5.10  PROCESS COMMUNICATION

   A superior process can communicate with its inferiors by  sharing  the
   same  pages  of  memory.  This sharing is accomplished with the CFORK%
   (bit CR%MAP) or the PMAP% monitor call.  When  the  superior  executes
   either  of  these  calls, both the superior and the inferior share the
   same pages.  Changes made to the shared pages by either  process  will
   be seen by the other process.

   Alternatively, processes can communicate via  the  software  interrupt
   system.   The  superior  process  can cause a software interrupt to be
   generated in an inferior  process  by  executing  the  IIC%  (Initiate
   Interrupt on Channel) monitor call.  For this type of communication to
   occur, the inferior's interrupt channels must  be  activated  and  its
   interrupt system enabled.

   The IIC% monitor call accepts two words of arguments in AC1  and  AC2.
   The  handle  of  the  process to receive the interrupt is given in the
   right half of  AC1.   AC2  contains  a  36-bit  word,  with  each  bit
   representing  one of the 36 software channels.  If a bit is on in AC2,


                                    5-19
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   a software interrupt is initiated on the corresponding  channel.   For
   example,  if  bit 5 is on in AC2, an interrupt is initiated on channel
   5.

   Thus,

        AC1:  process handle in the right half

        AC2:  36-bit word, with bit n on to initiate a software interrupt
              on channel n

   The process handle given cannot refer to a superior process or to more
   than one process.

   After execution of the  IIC%  call,  control  returns  to  the  user's
   program at the instruction following the call.  If an error occurs, it
   generates a software interrupt which the program can process  via  the
   software interrupt system.



   5.11  DELETING AN INFERIOR PROCESS
   5.11  DELETING AN INFERIOR PROCESS

   A process is deleted from the job structure when the superior  process
   executes  the  KFORK%  (Kill Process) monitor call.  When a process is
   deleted, its address space, its handle, and any JFNs acquired  by  the
   process  are  released.   If  the  process being deleted has processes
   inferior to it, the inferiors are also deleted.  For example,  in  the
   structure:


                              ---------------
                              |  Process A  |
                              ---------------
                                     |
                                     |
                              ---------------
                              |  Process B  |
                              ---------------
                                     |
                                     |
                              ---------------
                              |  Process C  |
                              ---------------


   if process A deletes process B by executing a KFORK% call,  process  C
   is also deleted.

   The KFORK% monitor call accepts one argument in the right half of AC1,
   the  handle of the process to be deleted.  This handle cannot refer to
   a superior process, to more than one process (for example, .FHINF), or


                                    5-20
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   to  the  process  executing  the  call  (that is, .FHSLF).  The RESET%
   monitor call is used to reinitialize the  current  process;  refer  to
   Section 2.6.1.

   After execution of the KFORK% call,  control  returns  to  the  user's
   program  at the instruction following the call.  If an error occurs, a
   software interrupt is generated, which the program can process via the
   software interrupt system.



   5.12  PROCESS EXAMPLES
   5.12  PROCESS EXAMPLES

   Example 1 - This program creates an inferior process to provide timing
   interrupts.

           TITLE TIMINT - AN INFERIOR PROCESS PROVIDING TIMING INTERRUPTS

           SEARCH MONSYM
           SEARCH MACSYM
           .REQUIRE SYS:MACREL

           STDAC.                  ;DEFINE STANDARD ACS

   START:  RESET%                  ;RELEASE FILES, ETC.
           MOVE P,[IOWD PDLSIZ,PDL] ;INITIALIZE STACK
           MOVX T1,CR%MAP          ;MAKE NEW PROCESS SHARE THIS 
                                   ;PROCESS'S MEMORY
           CFORK%                  ;CREATE A NEW PROCESS
            EJSHLT                 ;UNEXPECTED FATAL ERROR
           MOVEM T1,HANDLE         ;SAVE PROCESS HANDLE

   ;HERE TO START THE INFERIOR PROCESS

   STPROC: SETZB T4,FLAG           ;INITIALIZE COUNTER AND FLAG
           MOVE T1,HANDLE          ;GET PROCESS HANDLE
           MOVEI T2,SLEEP          ;GET ADDRESS TO START PROCESS
           SFORK%                  ;START THE NEW PROCESS
            EJSHLT                 ;UNEXPECTED FATAL ERROR

   ; MAIN PROCESSING LOOP

   LOOP:   AOS T4                  ;INCREMENT COUNTER
           SKIPN FLAG              ;HAS TIME ELAPSED YET?
           JRST LOOP               ;NO, GO DO MORE PROCESSING

   ; HERE WHEN LOWER PROCESS HAS INTERRUPTED

           TMSG <
   Counter has reached >           ;OUTPUT FIRST PART OF MESSAGE
           MOVX T1,.PRIOU          ;GET PRIMARY OUTPUT DESIGNATOR
           MOVE T2,T4              ;GET VALUE OF COUNTER


                                    5-21
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


           MOVEI T3,^D10           ;USE DECIMAL RADIX
           NOUT%                   ;OUTPUT CURRENT COUNTER VALUE
            EJSERR                 ;PRINT ERROR MESSAGE AND CONTINUE
           TMSG <
   >                               ;MOVE TO A NEW LINE
           JRST STPROC             ;CONTINUE COUNTING

   ; PROGRAM PERFORMED BY INFERIOR PROCESS TO WAIT FOR ONE-HALF MINUTE

   SLEEP:  MOVX T1,^D30*^D1000     ;ONE-HALF MINUTE IN MILLISECONDS
           DISMS%                  ;WAIT FOR SPECIFIED TIME
           SETOM FLAG              ;TELL SUPERIOR TIME HAS ELAPSED
           HALTF%                  ;FINISHED

   ; CONSTANTS AND STORAGE

           PDLSIZ==50              ;SIZE OF THE STACK
   PDL:    BLOCK PDLSIZ            ;STACK
   HANDLE: BLOCK 1                 ;INFERIOR PROCESS HANDLE
   FLAG:   BLOCK 1                 ;INTERRUPT FLAG

           END START

   Example 2 - This program illustrates how an inferior  process  may  be
   used  as  a source of timer interrupts.  The main program increments a
   counter.  It has an inferior process running for the sole  purpose  of
   timing  10 second intervals.  Each time the inferior process has timed
   10 seconds, it stops  and  interrupts  the  main  program.   The  main
   program  then  reports  how  many  more  times  it has incremented the
   counter since the last 10 second interrupt.

           TITLE TRMINT - FORK TERMINATION INTERRUPTS
           SEARCH MONSYM
           SEARCH MACSYM
           .REQUIRE SYS:MACREL

           STDAC.                  ;DEFINE STANDARD ACS

   START:  RESET%                  ;RELEASE FILES, ETC.
           MOVE P,[IOWD PDLSIZ,PDL] ;INITIALIZE STACK

   ; SET UP THE INTERRUPT SYSTEM

           MOVX T1,.FHSLF          ;GET PROCESS HANDLE FOR THIS FORK
           MOVE T2,[LEVTAB,,CHNTAB] ;GET TABLE ADDRESSES
           SIR%                    ;SET INTERRUPT TABLE ADDRESSES
            EJSHLT                 ;UNEXPECTED FATAL ERROR
           MOVX T2,1B<.ICIFT>      ;GET PROCESS TERMINATION CHANNEL BIT
           AIC%                    ;ACTIVATE PROCESS TERMINATION CHANNEL
            EJSHLT                 ;UNEXPECTED FATAL ERROR
           EIR%                    ;ENABLE INTERRUPT SYSTEM
            EJSHLT                 ;UNEXPECTED FATAL ERROR


                                    5-22
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   ; CREATE AND START THE INFERIOR PROCESS

           MOVX T1,CR%MAP+CR%ST+SLEEP
           CFORK%                  ;CREATE AND START TIMER AT SLEEP
            EJSHLT                 ;UNEXPECTED FATAL ERROR
           MOVEM T1,HANDLE ;SAVE PROCESS HANDLE

   ;INITIALIZE THE COUNTER

   STPROC: SETZB T4,OLDT4          ;CLEAR COUNTER

   ;MAIN LOOP OF THE PROGRAM WHICH JUST KEEPS COUNTING. (REAL
   ;APPLICATION WOULD PRESUMABLY HAVE A MORE USEFUL MAIN PROGRAM.)

   LOOP:   AOJA T4,LOOP            ;JUST KEEP INCREMENTING
   ; HERE WHEN LOWER PROCESS HAS INTERRUPTED

   PROINT: MOVEM P,IACS+P          ;SAVE STACK POINTER
           MOVEI P,IACS            ;MAKE POINTER FOR REST OF ACS
           BLT P,IACS+CX           ;SAVE REST OF ACS
           MOVE P,IACS+P           ;RESTORE P
           TMSG <NUMBER OF COUNTS: >
           MOVX T1,.PRIOU          ;GET PRIMARY OUTPUT DESIGNATOR
           EXCH T4,OLDT4           ;SAVE NEW COUNTER VALUE
           SUB T4,OLDT4            ;FIND NUMBER OF COUNTS SINCE LAST TIME
           MOVM T2,T4              ;MAKE IT POSITIVE
           MOVEI T3,^D10           ;USE DECIMAL RADIX
           NOUT%                   ;OUTPUT CURRENT COUNTER VALUE
            EJSERR                 ;PRINT ERROR MESSAGE AND CONTINUE
           TMSG <
   >                               ;MOVE TO A NEW LINE
           MOVE T1,HANDLE          ;GET PROCESS HANDLE
           MOVEI T2,SLEEP          ;GET ADDRESS TO START PROCESS
           SFORK%                  ;START THE NEW PROCESS
            EJSHLT                 ;UNEXPECTED FATAL ERROR
           MOVSI P,IACS            ;GET POINTER TO SAVED ACS
           BLT P,P                 ;RESTORE SAVED ACS
           DEBRK%                  ;DISMISS INTERRUPT
   ;THE FOLLOWING IS EXECUTED AS A LOWER PROCESS TO DO THE
   ;TIMING.  IT SLEEPS FOR 10 SECONDS AND THEN STOPS.

   SLEEP:  MOVX T1,^D10*^D1000     ;10 SECONDS IN MILLISECONDS
           DISMS%                  ;SLEEP
           HALTF%                  ;STOP AND INTERRUPT THE MAIN PROGRAM

   ; CONSTANTS AND STORAGE

           PDLSIZ==50              ;SIZE OF THE STACK
   PDL:    BLOCK PDLSIZ            ;STACK
   CHNTAB: REPEAT ^D19,<EXP 0>     ;CHANNELS 0-18 ARE NOT USED
           1,,PROINT               ;LEVEL 1 PROCESS TERMINATION CHANNEL
           REPEAT ^D15,<EXP 0>     ;REMAINING CHANNELS ARE NOT USED


                                    5-23
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


   LEVTAB: RETPC1                  ;RETURN PC STORED AT RETPC1 FOR 
                                   ;LEVEL 1
           0                       ;LEVEL 2 NOT USED
           0                       ;LEVEL 3 NOT USED
   HANDLE: BLOCK 1                 ;INFERIOR PROCESS HANDLE
   RETPC1: BLOCK 1                 ;RETURN PC STORED HERE ON INTERRUPTS
   OLDT4:  BLOCK 1                 ;HOLDS TIMER VALUE AT LAST INTERRUPT
   IACS:   BLOCK 20                ;STORAGE FOR ACS DURING INTERRUPTS

           END START

   Example 3 - This program creates an inferior process which waits until
   a line has been typed on the terminal.

           TITLE FRKDOC - AN INFERIOR PROCESS WAITS UNTIL A LINE IS TYPED

           SEARCH MONSYM
           SEARCH MACSYM
           .REQUIRE SYS:MACREL

           STDAC.                  ;DEFINE STANDARD ACS

   START:  RESET%                  ;RELEASE FILES, ETC.
           MOVE P,[IOWD PDLSIZ,PDL] ;INITIALIZE STACK
           MOVX T1,CR%MAP          ;MAKE NEW PROCESS SHARE THIS 
                                   ;PROCESS'S MEMORY
           CFORK%                  ;CREATE A NEW PROCESS
            EJSHLT                 ;UNEXPECTED FATAL ERROR
           SETZB T4,FLAG           ;INITIALIZE COUNTER AND FLAG
           MOVEI T2,GETCOM         ;GET ADDRESS TO START PROCESS
           SFORK%                  ;START THE NEW PROCESS
            EJSHLT                 ;UNEXPECTED FATAL ERROR

   ; MAIN PROCESSING LOOP

   LOOP:   AOS T4                  ;INCREMENT COUNTER
           SKIPN FLAG              ;HAS TIME ELAPSED YET?
           JRST LOOP               ;NO, GO DO MORE PROCESSING

   ; HERE WHEN INFERIOR PROCESS HAS INPUT A LINE OF TEXT

           TMSG <
   Counter has reached >           ;OUTPUT FIRST PART OF MESSAGE
           MOVX T1,.PRIOU          ;GET PRIMARY OUTPUT DESIGNATOR
           MOVE T2,T4              ;GET VALUE OF COUNTER
           MOVEI T3,^D10           ;USE DECIMAL RADIX
           NOUT%                   ;OUTPUT CURRENT COUNTER VALUE
            EJSERR                 ;PRINT ERROR MESSAGE AND CONTINUE
           TMSG <
   Echo Check: >                   ;OUTPUT FIRST PART OF MESSAGE
           HRROI T1,BUFFER         ;GET POINTER TO BUFFER
           PSOUT%                  ;OUTPUT TEXT JUST ENTERED


                                    5-24
                             PROCESS STRUCTURE
                             PROCESS STRUCTURE


           HALTF%                  ;STOP
           JRST START              ;IN CASE PROGRAM CONTINUED

   ; PROGRAM PERFORMED BY INFERIOR PROCESS TO INPUT A LINE OF TEXT

   GETCOM: HRROI T1,BUFFER         ;GET POINTER TO TEXT BUFFER
           MOVEI T2,BUFSIZ*5       ;GET COUNT OF MAX # OF CHARACTERS
           SETZM T3                ;NO RETYPE BUFFER
           RDTTY%                  ;READ A LINE FROM THE TERMINAL
            EJSERR                 ;UNEXPECTED ERROR
           SETOM FLAG              ;TELL SUPERIOR TIME HAS ELAPSED
           HALTF%                  ;FINISHED

   ; CONSTANTS AND STORAGE

           PDLSIZ==50              ;SIZE OF THE STACK
   PDL:    BLOCK PDLSIZ            ;STACK
           BUFSIZ==50              ;BUFFER SIZE
   BUFFER: BLOCK BUFSIZ
   FLAG:   BLOCK 1                 ;INTERRUPT FLAG

           END START
































                                    5-25

























































                                    6-1












                                 CHAPTER 6
                                 CHAPTER 6

                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY



   6.1  OVERVIEW
   6.1  OVERVIEW

   Many times users are placed in situations where they must share  files
   with other users.  Each user wants to be guaranteed that while reading
   a file, other users are reading the same  data  and  while  writing  a
   file,  no users are also writing, or even reading, the same portion of
   the file.

   Consider a data file used by members of an  insurance  company.   When
   many  agents  are reading individual accounts from the data file, they
   can all access the file simultaneously because no one is changing  any
   portion  of  the  data.   However,  when an agent desires to modify or
   replace an individual account, that portion  of  the  file  should  be
   accessed exclusively by that agent.  None of the other agents wants to
   access accounts that are being changed until  after  the  changes  are
   made.

   By using the ENQ/DEQ  facility,  cooperating  users  can  insure  that
   resources  are  shared  correctly and that one user's modifications do
   not interfere with another user's.  Examples of resources that can  be
   controlled  by  this  facility are devices, files, operations on files
   (for example, READ, WRITE), records, and memory pages.  This  facility
   can  be  used  for dynamic resource allocation, computer networks, and
   internal monitor queueing.  However, control of simultaneous  updating
   of files by multiple users is its most common application.

   The ENQ/DEQ facility insures data integrity among processes only  when
   the  processes  cooperate  in  their  use of both the facility and the
   physical  resource.   Use   of   the   facility   does   not   prevent
   non-cooperating  processes  from  accessing  a  resource without first
   enqueueing  it.   Nor  does  the  facility  provide  protection   from
   processes using it in an incorrect manner.

   A resource is defined by the processes using it and not by the system.
   Because  there  is  competition among processes for use of a resource,
   each resource is associated with a queue.  This queue is the  ordering
   of the requests for the resource.  When a request for the resource is


                                    6-1
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   granted, a lock occurs between the process that made the  request  and
   the resource.  For the duration of the lock, that process is the owner
   of the resource.  Other processes requesting access  to  the  resource
   are  placed  in  the  queue  until  the  owner  relinquishes the lock.
   However, there can be more than one owner of a  resource  at  a  time;
   this  is  called  shared  ownership (refer to Section 6.2).  Processes
   obtain access to a specific resource by placing a request in the queue
   for the resource.  This request is generated by the ENQ% monitor call.
   When finished with the resource, the  process  then  issues  the  DEQ%
   monitor  call.   This  call  releases the lock by removing the request
   from the queue and makes the resource available to  the  next  waiting
   process.   This  cycle  continues until all requests in the queue have
   been satisfied.



   6.2  RESOURCE OWNERSHIP
   6.2  RESOURCE OWNERSHIP

   Ownership for a resource can  be  requested  as  either  exclusive  or
   shared.   Exclusive  ownership occurs when a process requests sole use
   of the resource.  When a process is granted  exclusive  ownership,  no
   other  process  will  be  allowed  to use the resource until the owner
   relinquishes it.  This type of ownership should be  requested  if  the
   process  plans  on modifying the resource (for example, the process is
   updating a record in a data file).  Shared  ownership  occurs  when  a
   process  requests a resource, specifying that it will share the use of
   the resource with other processes.  When a  process  is  given  shared
   ownership,  other  processes  also  specifying  shared  ownership  are
   allowed to simultaneously use the  resource.   Access  to  a  resource
   should  be  shared  as  long  as  any one process is not modifying the
   resource.

   Two conditions determine when a lock to  a  resource  is  given  to  a
   process:

        1.  The position of the process's request in the  queue  for  the
            resource.

        2.  The type of ownership specified by the process's request.

   Because each resource has only one queue associated with it,  requests
   for  both exclusive and shared ownership of the resource are placed in
   the same queue.  Requests are placed in the  queue  in  the  order  in
   which  the  ENQ  facility  receives them, and the first request in the
   queue will be the first one serviced (except in  the  case  of  single
   requests  for  multiple  resources; refer to Section 6.4.1).  In other
   words, the ENQ facility processes requests on a first  in,  first  out
   basis.   If  this  first request is for shared ownership, that request
   will be serviced along with all following shared ownership requests up
   to  but  not  including the first exclusive ownership request.  If the
   first request is for  exclusive  ownership,  no  other  processes  are
   allowed  use  of the resource until the first process has released the
   lock.

                                    6-2
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   Consider the following queue for a particular resource.


         !=======================================================!
         !                  request 1 (shared)                   !
         !-------------------------------------------------------!
         !                  request 2 (shared)                   !
         !-------------------------------------------------------!
         !                 request 3 (exclusive)                 !
         !-------------------------------------------------------!
         !                  request 4 (shared)                   !
         !-------------------------------------------------------!
         !                  request 5 (shared)                   !
         !=======================================================!


   Request 1 will be serviced first because it is the  first  request  in
   the  queue.   However,  since  this  request  is for shared ownership,
   request 2 can also be serviced.  Request 3 cannot  be  serviced  until
   the  processes  with  request  1 and request 2 release the lock on the
   resource.  Eventually the lock is released by the two  processes,  and
   the  first two requests are removed from the queue.  The queue now has
   the following entries:


         !=======================================================!
         !                                                       !
         !-------------------------------------------------------!
         !                                                       !
         !-------------------------------------------------------!
         !                 request 3 (exclusive)                 !
         !-------------------------------------------------------!
         !                  request 4 (shared)                   !
         !-------------------------------------------------------!
         !                  request 4 (shared)                   !
         !=======================================================!


   Request 3 is now first in the  queue  and  is  given  a  lock  on  the
   resource.   Because  the  request is for exclusive ownership, no other
   requests will be serviced.  Once the process associated with request 3
   releases  the  lock,  both  request  4  and  request 5 can be serviced
   because they both are for shared ownership.



   6.3  PREPARING FOR THE ENQ/DEQ FACILITY
   6.3  PREPARING FOR THE ENQ/DEQ FACILITY

   Before using the ENQ/DEQ facility, the user must obtain an  ENQ  quota
   from the system administrator and must obtain the name of the resource




                                    6-3
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   desired, the  type  of  protection  required,  and  the  level  number
   associated with the resource.

   The ENQ quota indicates the total  number  of  requests  that  can  be
   outstanding  for  the  user at any given time.  Any request that would
   cause the quota to be exceeded results in an error.  The  user  cannot
   use the ENQ facility if the quota is set to zero.

   The resource name has a meaning  agreed  upon  by  all  users  of  the
   specific  resource  and  serves as an identifier of the resource.  The
   system makes no association between the resource name and the physical
   resource  itself;  it  is  the responsibility of the user's process to
   make that association.  The system merely uses the  resource  name  to
   process  requests and handles different resource names as requests for
   different resources.

   The resource name has two parts.  In most cases, the first part is the
   JFN  of  the  file being accessed.  Before using the ENQ facility, the
   user must initialize the file  using  the  appropriate  monitor  calls
   (refer  to  Section  3.1).  The second part of the name is a modifier,
   which is either a pointer to a string or  a  33-bit  user  code.   The
   string uniquely identifies the resource to all users.  The pointer can
   either be a standard byte pointer or be in the form

        -1,,ADR

   where ADR is the location of the  left-justified  ASCIZ  text  string.
   The 33-bit user code similarly identifies the resource by representing
   an item such as a record number or block  number.   The  ENQ  facility
   considers  these modifiers as logical  strings and does  not check for
   cooperation among  the  users.   Thus,  users  must  be  careful  when
   assigning  these  modifiers to prevent the occurrence of two different
   modifiers referring to the same resource.

   The type of protection desired for the resource is  indicated  by  the
   first  part of the resource name.  This part of the name can be one of
   four values.  When the user specifies the JFN of the desired file, the
   file is subject to the standard access protection of the system.  This
   is the most typical case.  When the user specifies  -1  instead  of  a
   JFN,  it  means that resources defined within a job are to be accessed
   only by processes of that job.  Other jobs requesting resources of the
   same name are queued to a different resource.  When the user specifies
   -2 instead of a JFN, it means that the resource can be accessed by any
   job  on  the  system.   A  process must have bit SC%ENQ enabled in its
   capability word to specify this  type  of  protection.   If  the  user
   specifies -3 instead of a JFN, it means the same type of protection as
   that given when -2 is specified.   However,  this  requires  that  the
   process  have  WHEEL  or  OPERATOR capability enabled.  Quotas are not
   checked when -3 is given instead of a JFN.

   In addition to specifying the resource name and  type  of  protection,
   the  user  also  assigns  a level number to each resource.  The use of


                                    6-4
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   level numbers prevents the occurrence of a deadly  embrace  situation:
   the  situation  where  two  or  more processes are waiting for each to
   complete, but none of the processes can obtain a lock on the  resource
   it needs for completion.  This situation is represented by Figure 6-1.


         ---------------------
         | Process A is      |
         | Waiting for a     |
         | Resource Process  |--------------------------\
         | B Has.            |                          |
         ---------------------                          |
                 ^                                      v
                 |                             ---------------------
                 |                             | Process B is      |
                 |                             | Waiting for a     |
                 |                             | Resource Process  |
                 |                             | C Has.            |
                 |                             ---------------------
                 |                                      |
                 |         ---------------------        |
                 |         | Process C is      |        |
                 |         | Waiting for a     |        |
                 \---------| Resource Process  |<-------/
                           | A Has.            |
                           ---------------------


   Figure 6-1:  Deadly Embrace Situation
   Figure 6-1:  Deadly Embrace Situation



   Each process is in the queue waiting for the resource it needs, but no
   request   is   being   serviced  because  the  desired  resources  are
   unavailable.

   The use of level numbers forces cooperating processes to  order  their
   use  of  resources by requiring that processes request resources in an
   ascending numerical order and that all processes assign the same level
   number  to  a  specific  resource.  This means that the order in which
   resources are requested is the same for all processes  and  therefore,
   requests  for  the first resource will always precede requests for the
   second one.

   If both of the above requirements are not met, the process  requesting
   the resource receives an error, unless the appropriate flag bit is set
   (refer to Section 6.4.1.2), and the  request  is  not  placed  in  the
   queue.  Thus, instead of waiting for a resource it will never get, the
   process is informed immediately that the resource is not available.





                                    6-5
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   6.4  USING THE ENQ/DEQ FACILITY
   6.4  USING THE ENQ/DEQ FACILITY

   There are three monitor calls  available  for  the  ENQ/DEQ  facility:
   ENQ%,  to  request  use  of  a  resource; DEQ%, to release a lock on a
   resource; and ENQC%, to obtain information about  the  queues  and  to
   specify access to these queues.



   6.4.1  Requesting Use of a Resource
   6.4.1  Requesting Use of a Resource

   The user issues the ENQ% monitor call to place a request in the  queue
   associated  with  the  desired resource.  This call is used to specify
   the resource name, level number, and type of protection required.

   A single ENQ% monitor call can  be  used  to  request  any  number  of
   resources.  In fact, when desiring multiple resources, the user should
   request all of them in one call.  This method of requesting  resources
   guarantees  that  the  user  gets  either none or all of the resources
   requested because the ENQ/DEQ facility never allocates  only  some  of
   the  resources  specified  in  one  call.   Because all resources in a
   single call must be  available  at  the  same  time,  the  first  user
   requesting  a  resource  (that is, the first user in the queue for the
   resource) may not be the first user obtaining it if other resources in
   the request are currently not available.

   A single call for multiple resources is not functionally the same as a
   series  of  single  calls  of  those resources.  In a single call, the
   entire request is rejected if an error is  returned  for  one  of  the
   resources  specified.   In a series of single calls, each request that
   did not return an error will be queued.

   The ENQ% monitor call accepts two words of arguments in AC1  and  AC2.
   The  first  word  contains  the  code of the desired function, and the
   second contains the address of the argument block.  Thus,

        AC1:  function code

        AC2:  address of argument block



   6.4.1.1  ENQ% Functions
   6.4.1.1  ENQ% Functions - The functions that can be requested  in  the
   ENQ% call are described in Table 6-1.










                                    6-6
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   Table 6-1:  ENQ% Functions
   Table 6-1:  ENQ% Functions

   ______________________________________________________________________

     Code          Symbol        Meaning
   ______________________________________________________________________

      0            .ENQBL        Queue  the  requests  and  block   the
                                 process  until all requested locks are
                                 acquired.  This  function  returns  an
                                 error  code  only  if the ENQ% call is
                                 not correctly specified.

      1            .ENQAA        Queue the  requests  and  acquire  the
                                 locks  only if all requested resources
                                 are  immediately  available.   If  the
                                 resources  are  available, all will be
                                 allocated to the process.  If any  one
                                 of  the resources is not available, no
                                 requests  are  queued,  no  locks  are
                                 acquired,   and   an   error  code  is
                                 returned in AC1.

      2            .ENQSI        Queue the requests for  all  specified
                                 resources.    If   all  resources  are
                                 available, this function is  identical
                                 to   the   .ENQBL  function.   If  all
                                 resources    are    not    immediately
                                 available,  the  requests  are queued,
                                 and a software interrupt is  generated
                                 when all requested resources have been
                                 given to the process.

      3            .ENQMA        Change  the  ownership  access  of   a
                                 previously-queued  request  (refer  to
                                 bit EN%SHR  below).   The  access  for
                                 each  lock in this request is compared
                                 with the access for each lock  in  the
                                 request  already queued.  No action is
                                 taken if  the  two  accesses  are  the
                                 same.   If  the access in this request
                                 is  shared  and  the  access  in   the
                                 previous  request  is  exclusive,  the
                                 ownership access is changed to  shared
                                 access.    Otherwise,   an   error  is
                                 returned if:

                                 1.  There  are  processes  which   are
                                     locking,  or  waiting  on the same
                                     lock, and  the  process  tries  to
                                     change  the  ownership access from
                                     shared to exclusive.  If  this  is


                                    6-7
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


                                     the case, the process should issue
                                     a DEQ% monitor call for the shared
                                     request  and  then  issue  another
                                     ENQ% monitor  call  for  exclusive
                                     ownership.

                                 2.  Any one  of  the  specified  locks
                                     does not have a pending request.

                                 3.  Any one of the specified locks  is
                                     a   pooled   resource   (refer  to
                                     Section 6.4.1.2).

                                 Each lock specified  is  checked,  and
                                 the  access  is  changed for all locks
                                 that   were   correctly   given.    On
                                 receiving an error, the process should
                                 issue  the  ENQC%  monitor   call   to
                                 determine  the  current  state of each
                                 lock (refer to Section 6.4.3).

      4            .ENECL        Set cluster-wide ENQ/DEQ functionality
                                 for  all ENQ/DEQ/ENQC JSYSes performed
                                 by this process.  The contents of  AC2
                                 are  ignored as this function does not
                                 require an argument block.
   ______________________________________________________________________



   6.4.1.2  ENQ% Argument Block
   6.4.1.2  ENQ% Argument Block - The format of  the  argument  block  is
   described in Table 6-2.


   Table 6-2:  ENQ% Argument Block
   Table 6-2:  ENQ% Argument Block

   ______________________________________________________________________

     Word      Symbol       Meaning
   ______________________________________________________________________

       0       .ENQLN       Number of locks being requested in the left
                            half,   and   length   of   argument  block
                            (including this word) in the right half.

       1       .ENQID       Number of software interrupt channel in the
                            left  half,  and  request  ID  in the right
                            half.

       2       .ENQLV       Flags and level number in  the  left  half,
                            and  JFN,  -1,  -2  or -3 (refer to Section
                            6.3) in the right half.


                                    6-8
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


       3       .ENQUC       Pointer to string or 5B2+33-bit  user  code
                            (refer to Section 6.3).

       4       .ENQRS       Number of resources in the pool in the left
                            half,  and number of resources requested in
                            the right half.

       5       .ENQMS       Address of a resource mask block.
   ______________________________________________________________________


   Words .ENQLV, .ENQUC, .ENQRS, and  .ENQMS  (words  2  through  5)  are
   repeated  for  each lock being requested.  These four words are called
   the lock specification.

   ________ __________
   Software Interrupts

   The software interrupt system is used in conjunction with  the  .ENQSI
   function  (refer  to Section 6.4.1.1).  If all locks are not available
   when the user requests them, the .ENQSI  function  causes  a  software
   interrupt  to  be generated when the locks become available.  The user
   specifies the software channel on which to receive  the  interrupt  by
   placing  the  channel  number  in  the left half of word .ENQID in the
   argument block.

   When the user is waiting for more than one lock to  become  available,
   he  will  receive an interrupt when the last lock is available.  If he
   desires to be informed as each lock becomes available, he  can  assign
   the  locks  to  separate channels by issuing multiple ENQ% calls.  The
   availability of each lock will then be indicated by the occurrence  of
   an interrupt on each channel.

   When the user requests the .ENQSI function,  he  must  initialize  the
   interrupt system first or else an interrupt will not be generated when
   the locks become available (refer to Chapter 4).

   _______ __
   Request ID

   The 18-bit request ID is currently not used  by  the  system,  but  is
   stored  for use by the process.  Thus, the process can supply an ID to
   use as identification for the request.   This  ID  is  useful  on  the
   .DEQID function of the DEQ% monitor call (refer to Section 6.4.2.1).

   _____ ___ _____ _______
   Flags and Level Numbers

   Table 6-3 describes the flags that can be used in the left half of the
   first word of each lock specification (.ENQLV).







                                    6-9
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   Table 6-3:  Lock Specification Flags
   Table 6-3:  Lock Specification Flags

   ______________________________________________________________________

     Bit       Symbol            Meaning
   ______________________________________________________________________

      0        EN%SHR            Ownership for this resource is  to  be
                                 shared.    If  this  bit  is  not  on,
                                 ownership for this resource is  to  be
                                 exclusive.

      1        EN%BLN            Ignore  the  level  number  associated
                                 with  this  resource.   If this bit is
                                 set,  sequencing   errors   in   level
                                 numbers  are not considered fatal, and
                                 execution of the call continues.

                                 On successful completion of the  call,
                                 AC1 contains either an error code if a
                                 sequencing error occurred, or zero  if
                                 a sequencing error did not occur.

                                                WARNING

                                     A deadly embrace situation may
                                     occur  when  level numbers are
                                     not  used.    Use   of   these
                                     numbers guarantees that such a
                                     situation  cannot  arise;  for
                                     this  reason bit EN%BLN should
                                     not be set.

      2        EN%NST            Allow ownership of  this  lock  to  be
                                 nested.

      3        EN%LTL            Allow  a  long-term   lock   on   this
                                 resource.

      4-8                        Reserved for Digital.

      9-17     EN%LVL            Level  number  associated  with   this
                                 resource.  This number is specified by
                                 the user and must be  agreed  upon  by
                                 all  users  of the resource.  In order
                                 to   eliminate   a   deadly    embrace
                                 situation,    users    must    request
                                 resources  in  numerically  increasing
                                 order.
   ______________________________________________________________________




                                    6-10
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   The request is not queued, and an error is given, if EN%BLN is not set
   and

        1.  The user requests a resource with a level number less than or
            equal  to  the  highest numbered resource he has requested so
            far.

        2.  The level number of this request does  not  match  the  level
            number supplied in previous requests for this resource.

   ______ _________
   Pooled Resources

   Word .ENQRS of each lock specification is used  to  allocate  multiple
   copies  from  a  pool  of identical resources.  Bit EN%SHR, indicating
   shared ownership, is meaningless for  pooled  resources  because  each
   resource  in  the  pool can be owned by only one process at a time.  A
   process can own one or more resources in the pool; however, it  cannot
   own  more than there are in the pool or more than there are unowned in
   the pool.

   The left half of word .ENQRS contains the total  number  of  resources
   existing  in  the  pool.  This number is previously agreed upon by all
   users of the  pooled  resource.   The  first  user  who  requests  the
   resource  sets  this  number, and all subsequent requests must specify
   the same number or an error is given.

   The right half of word .ENQRS contains the number of  resources  being
   requested by this process.  This number must be greater than zero if a
   pool of resources exists and cannot be greater than the number in  the
   left  half.   This  means that if a pool of resources exists, the user
   must request at least one resource, but cannot request more  than  are
   in the pool.

   Once the number of pooled resources is determined, the  resources  are
   allocated until the pool is depleted or until a request specifies more
   resources than are currently available.  In the latter case, the  user
   making the request is not given any resources until his entire request
   can be satisfied.   Subsequent  requests  from  other  users  are  not
   granted  until  this  request  is  satisfied  even though there may be
   enough resources to  satisfy  these  subsequent  requests.   As  users
   release their resources, the resources are returned to the pool.  When
   all resources have been returned, they cease to exist,  and  the  next
   request completely redefines the number of resources in the new pool.

   The system assumes that the resource is in a pool if the left half  of
   word  .ENQRS  of  the  lock  specification  is nonzero.  Thus the user
   should set the left half to zero if only one resource  of  a  specific
   type exists.  If this is the case, then the right half of this word is
   a number defining the group of users who can simultaneously share  the
   resource.   This  means  that when the resource is allocated to a user
   for shared ownership, only other users  in  the  same  group  will  be
   allowed  access  to  the resource.  The use of sharer groups restricts


                                    6-11
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   access to a resource to a set of processes smaller than  the  set  for
   shared ownership (which is sharer group 0) but larger than the set for
   exclusive ownership.  (Refer to Section 6.5 for  more  information  on
   sharer groups).



   6.4.2  Releasing a Resource
   6.4.2  Releasing a Resource

   The user issues the DEQ% monitor call to remove  a  request  from  the
   queue  associated  with a resource.  The request is removed whether or
   not the user actually owns a lock on the resource or is  only  waiting
   in the queue for the resource.

   The DEQ% monitor call can be used to remove  any  number  of  requests
   from  the  queues.   If  one  of  the  requests cannot be removed, the
   dequeueing procedure continues until all lock specifications have been
   processed.   An error code is then returned for the last request found
   that could not be dequeued.  The process can then  execute  the  ENQC%
   call  (refer  to  Section 6.4.3) to determine the status of each lock.
   Thus, unlike the operation of  the  ENQ%  call,  the  DEQ%  call  will
   dequeue  as many resources as it can, even if an error is returned for
   one of the lock specifications in the argument block.  However, when a
   user  attempts  to  dequeue  more  pooled resources than he originally
   allocated, an error code is returned and none  of  the  resources  are
   dequeued.

   The DEQ% monitor call accepts two words of arguments in AC1  and  AC2.
   The  first  word  contains  the code for the desired function, and the
   second word contains the address of the argument block.  Thus,

        AC1:  function code

        AC2:  address of argument block




















                                    6-12
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   6.4.2.1  DEQ% Functions
   6.4.2.1  DEQ% Functions - The DEQ% functions are  described  in  Table
   6-4.


   Table 6-4:  DEQ% Functions
   Table 6-4:  DEQ% Functions

   ______________________________________________________________________

     Code     Symbol     Meaning
   ______________________________________________________________________

     0        .DEQDR     Remove the specified requests from the queues.
                         This function is the only one that requires an
                         argument block.

     1        .DEQDA     Remove all requests for this process from  the
                         queues.   This  action  is  taken  on  a RESET
                         monitor call.  An error code  is  returned  if
                         this  process  has not requested any resources
                         (that is, if this process has  not  issued  an
                         ENQ%).

     2        .DEQID     Remove all requests  that  correspond  to  the
                         specified   request   identifier.   When  this
                         function is specified, the user must place the
                         18-bit  request  ID  in  AC2 on the DEQ% call.
                         This function allows the  user  to  release  a
                         class  of  locks in one call without itemizing
                         each lock in an argument block.  The  function
                         should be used when dequeueing in one call the
                         same locks that were  enqueued  in  one  call.
                         For  example,  with this function the user can
                         specify the ID to be the same as the JFN  used
                         in  the ENQ% call and thus remove all locks to
                         that file at once.
   ______________________________________________________________________


















                                    6-13
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   6.4.2.2  DEQ% Argument Block
   6.4.2.2  DEQ% Argument Block - The format of the  argument  block  for
   function .DEQDR is described in Table 6-5.


   Table 6-5:  DEQ% Argument Block
   Table 6-5:  DEQ% Argument Block

   ______________________________________________________________________

     Word      Symbol       Meaning
   ______________________________________________________________________

       0       .ENQLN       Number of locks being requested in the left
                            half,   and   length   of   argument  block
                            (including this word) in the right half.

       1       .ENQID       Number of software interrupt channel in the
                            left  half,  and  request  ID  in the right
                            half.

       2       .ENQLV       Flags and level number in  the  left  half,
                            and  JFN,  -1,  -2  or -3 (refer to Section
                            6.3) in the right half.

       3       .ENQUC       Pointer to string or 5B2+33-bit  user  code
                            (refer to Section 6.3).

       4       .ENQRS       Number of resources in the pool in the left
                            half,  and number of resources requested in
                            the right half.

       5       .ENQMS       Address of a resource mask block.
   ______________________________________________________________________


   Words .ENQLV, .ENQUC, .ENQRS, and  .ENQMS  (words  2  through  5)  are
   repeated for each request being dequeued.  These four words are called
   the lock specification.



   6.4.3  Obtaining Information About Resources
   6.4.3  Obtaining Information About Resources

   The user issues the ENQC% monitor call to obtain information about the
   current  status of the given resources.  This call can also be used by
   privileged users to perform various utility  functions  on  the  queue
   structure.   The  format  of the ENQC% call is different for these two
                        _______ _______ _____ _________  ______
   uses.  (Refer to the TOPS-20 Monitor Calls Reference  Manual  for  the
   explanation of the privileged use of the ENQC% call.)

   The ENQC% monitor call accepts three words of arguments in AC1 through
   AC3:



                                    6-14
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


        AC1:  function code (.ENQCS)

        AC2:  address of argument block

        AC3:  address of area to receive status information

   The format of the argument block is identical to  the  format  of  the
   ENQ%  and DEQ% argument blocks.  The area in which the status is to be
   returned should be  three  times  as  long  as  the  number  of  locks
   specified in the argument block.

   On successful execution of the ENQC% call, the current status of  each
   lock  specified  is  returned  as a three-word entry.  This three-word
   entry has the following format.


         !=======================================================!
         !        Flag bits indicating status of lock            !
         !-------------------------------------------------------!
         !                   36-bit time stamp                   !
         !-------------------------------------------------------!
         !         Reserved          !        Request ID         !
         !=======================================================!


   Table 6-6 describes the flag bits that can be used in a ENQC% call.




























                                    6-15
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   Table 6-6:  ENQC% Flag Bits
   Table 6-6:  ENQC% Flag Bits

   ______________________________________________________________________

     Bit     Symbol    Meaning
   ______________________________________________________________________

      0      EN%QCE    An error has occurred in the corresponding  lock
                       request.   Bits  18-35  contain  the appropriate
                       error code.

      1      EN%QCO    The process issuing the ENQC% call is the  owner
                       of this lock.

      2      EN%QCQ    The process issuing the ENQC%  call  is  in  the
                       queue  waiting for this resource.  This bit will
                       be on  when  EN%QCO  is  on  because  a  request
                       remains in the queue until a DEQ% call is given.

      3      EN%QCX    The  lock  has  been  allocated  for   exclusive
                       ownership.   When  this  bit is off, there is no
                       way of determining the number of sharers of  the
                       resource.

      4      EN%QCB    The process issuing the ENQC%  call  is  in  the
                       queue  waiting  for  exclusive  ownership to the
                       resource.  This bit will be  off  if  EN%QCQ  is
                       off.

      5      EN%QCC    This is a cluster-wide lock/request.   This  bit
                       exists in both a lock-block and a q-block.

      6      EN%QCN    No future vote is required for this lock.   This
                       bit exists in a lock-block.

      7      EN%QCS    This lock requires a scheduling pass.

      8                Reserved for Digital

     9-17    EN%LVL    The level number of the resource.

    18-35    EN%JOB    The number of the job that owns the lock.   This
                       value  may  be  a  job  number on another system
                       within  the  cluster.   For  locks  with  shared
                       ownership,  this value will be the job number of
                       one of the owners.  However, this value will  be
                       the  current  job's number if the current job is
                       one of the owners.  If this lock is  not  owned,
                       the  value  is  -1.  If EN%QCE is on, this field
                       contains the appropriate error code.
   ______________________________________________________________________



                                    6-16
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   The 36-bit time stamp indicates the last time  a  process  locked  the
   resource.  The time is in the universal date-time standard.  If no one
   currently has a lock on the resource, this word is zero.

   The request ID returned in the right half of the third word is  either
   the  request ID of the current process if that process is in the queue
   or the request ID of the owner of the lock.



   6.5  SHARER GROUPS
   6.5  SHARER GROUPS

   Processes can specify the sharing of resources by using  sharer  group
   numbers  (refer  to  Section  6.4.1.2).   The  use  of  sharer  groups
   restricts the ownership for a resource to a set of  processes  smaller
   than  the  set  for  shared  ownership  but  larger  than  the set for
   exclusive ownership.

   Sharer group number 0 is used to indicate the group of all cooperating
   processes of the resource.  This group number is assumed when no group
   is specified in the ENQ% call.  To restrict use  of  the  resource,  a
   group number other than 0 must be explicitly specified in the call.

   Consider the following example.  The resource is the  WRITE  operation
   on  a file.  There are four types of uses of this resource as shown in
   Figure 6-2.




























                                    6-17
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


            ---------------------------------------------------
            |\            |              |                |
            | \   Process'|              |                |
            |  \  Own Use |              |                |
            |   \ of the  |              |                |
            |    \Resource|              | Not Allowed    |
            |     \       | Write        | to Write       |
            |      \      |              |                |
            |       \     |              |                |
            | Other  \    |              |                |
            | Process'\   |              |                |
            | Use of   \  |              |                |
            | Resource  \ |              |                |
            |            \|              |                |
            |-------------|--------------|----------------|
            |             | 1            | 2              |
            | Write       |              |                |
            |             | Shared,      | No Need to Use |
            |             | Group 0      | ENQ/DEQ        |
            |-------------|--------------|----------------|
            |             | 3            | 4              |
            | Not Allowed |              |                |
            | to Write    | Exclusive    | Shared,        |
            |             |              | Group 1        |
            -----------------------------------------------


   Figure 6-2:  Use of Sharer Groups
   Figure 6-2:  Use of Sharer Groups


   In block 1 of the figure, the process owning the lock wishes to  allow
   all  cooperating  processes  to  also  lock  the resource (that is, to
   perform the WRITE  operation).   Therefore,  in  the  ENQ%  call,  the
   process  specifies  the  resource  can  be  locked  by all cooperating
   processes.  In block 2 of the figure, the process  does  not  plan  on
   locking  the  resource  and  does not care if other processes lock it.
   Thus, there is no need for the process to use  the  ENQ/DEQ  facility.
   In  block  3  of  the figure, the process desires to lock the resource
   exclusively and does not want other processes to lock it.   Thus,  the
   process  obtains  exclusive ownership for the resource.  In block 4 of
   the figure, the process does not want to lock the resource immediately
   but  also  does  not  want  other processes to lock it because it soon
   plans to request a lock on the resource.  If the process were the only
   one  requesting  this  type  of  use,  exclusive  ownership  would  be
   sufficient, because the resource would be  unavailable  to  others  as
   long  as  the  process  owned  the  lock.  However, if other processes
   desire this same type of use, exclusive ownership is  not  sufficient,
   because  once  one  process  releases the lock, another process with a
   different type of use could  obtain  its  own  lock.   Thus,  in  this
   example,  sharer  group 1 is defined to include all processes with the
   same type of use (that is, all processes who do not want to  lock  the
   resource immediately but also do not want other processes to lock it).


                                    6-18
                          ENQUEUE/DEQUEUE FACILITY
                          ENQUEUE/DEQUEUE FACILITY


   This elimates the problem of another user obtaining the resource for a
   different type of use.

   Sharer group 0 should be sufficient  for  most  uses  of  the  ENQ/DEQ
   facility.  Additional groups should only be needed in those situations
   where a subset of the cooperating processes must have a  specific  use
   of a resource, as in the above example.



   6.6  AVOIDING DEADLY EMBRACES
   6.6  AVOIDING DEADLY EMBRACES

   Processes  can  interact  in  many  undesirable   ways   if   improper
   communication   occurs   among  the  processes  or  if  resources  are
   incorrectly shared.  An example of one undesirable  situation  is  the
   occurrence  of  a  deadly embrace:  when two processes are waiting for
   each other to complete but neither one can gain access to the resource
   it needs for completion.  This situation can be avoided when processes
   consider the following guidelines.

        1.  Processes should request resources  at  the  time  they  need
            them.  If possible, processes should request resources one at
            a time and release each resource before requesting  the  next
            one.

        2.  Processes should request shared ownership whenever  possible.
            However,  the  process should not request shared ownership if
            it plans on modifying the resource.

        3.  When a process  needs  more  than  one  resource,  it  should
            request  these resources in one ENQ% call instead of multiple
            calls for each resource.  The process should also release the
            entire set of resources at once with a single DEQ% call.

        4.  When the use of one resource depends on the use of  a  second
            one,  the  process  should define the two resources as one in
            the ENQ% and DEQ% calls.  However, there is no protection  of
            the resources if they are also requested separately.

        5.  Occasionally processes use a set of resources and  require  a
            lock  on  the second resource while retaining the lock on the
            first.  In this case,  the  order  in  which  the  locks  are
            obtained  should  be  the  same  for  all users of the set of
            resources.  The same ordering of locks is accomplished by the
            processes  assigning  level  numbers  to  each resource.  The
            requirements that processes request  resources  in  ascending
            numerical  order  and  that  all processes use the same level
            number for a specific resource ensure that a  deadly  embrace
            situation will not occur.





                                    6-19

























































                                    7-1












                                 CHAPTER 7
                                 CHAPTER 7

                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY



   7.1  OVERVIEW
   7.1  OVERVIEW

   The Inter-Process Communication Facility (IPCF)  allows  communication
   among  jobs  and  system  processes.   This  communication occurs when
   processes send and receive information in the form of  packets.   Each
   sender  and  receiver  has  a  Process  ID  (PID)  assigned  to it for
   identification purposes.

   When the sender sends a packet of information to another process,  the
   packet  is placed into the receiver's input queue.  The packet remains
   in the queue until the receiver checks the  queue  and  retrieves  the
   packet.   Instead  of  periodically  checking  its  input  queue,  the
   receiver can enable the software interrupt system (refer to Chapter 4)
   to generate an interrupt when a packet is placed in its input queue.

   The  <SYSTEM>INFO  process  is  the   information   center   for   the
   Inter-Process  Communication  Facility.   This process performs system
   functions related to PIDs and names, and any process can request these
   functions by sending <SYSTEM>INFO a packet.



   7.2  QUOTAS
   7.2  QUOTAS

   Before using IPCF, the user must  acquire  the  ability  to  use  IPCF
   privileges  from  the system administrator:  a send packet quota and a
   receive packet quota.  These quotas designate, on a per process basis,
   the  number  of  sends and receives that can be outstanding at any one
   time.  For example, if the process has a send quota of two and it  has
   sent  two  packets,  it cannot send any more until at least one packet
   has been retrieved by its receiver.  A send packet quota of two and  a
   receive  packet  quota of five are assumed as the standard quotas.  If
   these quotas are zero, the process cannot use IPCF.






                                    7-1
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   7.3  PACKETS
   7.3  PACKETS

   Information is transferred in the form of  packets.   Each  packet  is
   divided  into  two portions:  a packet descriptor block of four to six
   words and a packet data block the length of the message.   The  format
   of the packet is shown in Figure 7-1.


   Packet Descriptor Block


           !=======================================================!
   .IPCFL  !                         flags                         !
           !-------------------------------------------------------!
   .IPCFS  !                     PID of sender                     !       
           !-------------------------------------------------------!
   .IPCFR  !                    PID of receiver                    !
           !-------------------------------------------------------!
   .IPCFP  !     length of message     !    address of message     !
           !             n             !            ADR            !
           !-------------------------------------------------------!
   .IPCFD  !    sender's connected     !    sender's logged in     !
           !         directory         !         directory         !
           !-------------------------------------------------------!
   .IPCFC  !            enabled capabilities of sender             !
           !-------------------------------------------------------!
   .IPCSD  !             connected directory of sender             !
           !-------------------------------------------------------!
   .IPCAS  !               account string of sender                !
           !-------------------------------------------------------!
   .IPCLL  !              logical location of sender               !
           !=======================================================!


   Packet Data Block


           !=======================================================!
   ADR     !                    message word 1                     !
           !=======================================================!
                                   .
                                   .
                                   .
           !=======================================================!
           !                    message word n                     !
           !=======================================================!


   Figure 7-1:  IPCF Packet
   Figure 7-1:  IPCF Packet





                                    7-2
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   7.3.1  Flags
   7.3.1  Flags

   There are two types of flags that can be set in  word  .IPCFL  of  the
   packet  descriptor  block.  The flags in the left half of the word are
   instructions to IPCF for packet communication, and the  flags  in  the
   right  half  are  descriptions  of the data message.  The flags in the
   right half are returned as part of the associated variable  (refer  to
   Section  7.4.2).   The  packet descriptor block flags are described in
   Table 7-1.


   Table 7-1:  Packet Descriptor Block Flags
   Table 7-1:  Packet Descriptor Block Flags

   ______________________________________________________________________

     Bit     Symbol    Meaning
   ______________________________________________________________________

      0      IP%CFB    Do  not  block  the  process  if  there  are  no
                       messages  in  the queue.  If this bit is on, the
                       process  receives  an  error  if  there  are  no
                       messages.

      1      IP%CFS    Use the PID obtained from the  address  in  word
                       .IPCFS  of  the  packet  descriptor block as the
                       sender's PID.

      2      IP%CFR    Use the PID obtained from the  address  in  word
                       .IPCFR  of  the  packet  descriptor block as the
                       receiver's PID.

      3      IP%CFO    Allow the process one send above the send quota.
                       (The standard send quota is two.)

      4      IP%TTL    Truncate the message if it is  longer  than  the
                       area  reserved  for it in the packet data block.
                       If this bit is not on, the process  receives  an
                       error if the message is too long.

      5      IP%CPD    Create a PID to use as the  sender's  PID.   The
                       PID  created  is  returned in word .IPCFS of the
                       packet descriptor block.

      6      IP%JWP    Make the PID created be permanent until the  job
                       logs  out  (if  both  bits IP%CPD and IP%JWP are
                       on).  Make the PID created  be  temporary  until
                       the  process  executes a RESET% monitor call (if
                       bit IP%CPD is on and bit IP%JWP is not on).   If
                       bit IP%CPD is not on, bit IP%JWP is ignored.

      7      IP%NOA    Do not allow other  processes  to  use  the  PID
                       created when bit IP%CPD is on.  If bit IP%CPD is
                       not on, bit IP%NOA is ignored.

                                    7-3
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


    8-17               Reserved for Digital.

     18      IP%CFP    The packet is privileged.  This bit can  be  set
                       only by a process with WHEEL capability enabled.
                                     _______  _______  _____  _________
                       Refer to the  TOPS-20  Monitor  Calls  Reference
                       ______
                       Manual for a description of this bit.

     19      IP%CFV    The packet is a page of 512 (decimal)  words  of
                       data.

     20      IP%CFZ    A zero-length message was sent.

     21                Reserved for Digital.

     22      IP%EPN    Page  number  in  word  .IPCFP  of  the   packet
                       descriptor block is 18 bits long

     23                Reserved for Digital.

     24-29   IP%CFE    Field for  error  code  returned  from  <SYSTEM>
                       INFO.

                       Code  Symbol  Meaning

                       15    .IPCPI  insufficient privileges

                       16    .IPCUF  invalid function

                       66    .IPCKM  PID has been deleted

                       67    .IPCSN  <SYSTEM>INFO needs name

                       72    .IPCFF  <SYSTEM>INFO free space exhausted

                       74    .IPCBP  PID has no name or is invalid

                       75    .IPCDN  duplicate name has been specified

                       76    .IPCNN  unknown name has been specified

                       77    .IPCEN  invalid name has been specified

     30-32   IP%CFC    System and sender code.  This code  can  be  set
                       only by a process with WHEEL capability enabled,
                       but the  monitor  will  return  the  code  so  a
                       nonprivileged process can examine it.

                       Code  Symbol  Meaning

                       1     .IPCCC  Sent by <SYSTEM>IPCF

                       2     .IPCCF  Sent by system-wide <SYSTEM>INFO


                                    7-4
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


                       3     .IPCCP  Sent by receiver's <SYSTEM>INFO

                       4     .IPCCG  Sent by monitor for QUEUE% JSYS

     33-35   IP%CFM    Field for special messages.  This  code  can  be
                       set  only  by  a  process  with WHEEL capability
                       enabled, but the monitor will return the code so
                       that a nonprivileged process can examine it.

                       Code  Symbol  Meaning

                       1     .IPCFN  Process' input  queue  contains  a
                                     packet that could not be delivered
                                     to intended PID.
   ______________________________________________________________________



   7.3.2  PIDs
   7.3.2  PIDs

   Any process that wants to send or receive a packet must obtain a  PID.
   The  process  can  obtain  a  PID  by sending a packet to <SYSTEM>INFO
   requesting that a PID be assigned.  The process must  also  include  a
   symbolic name that is to be associated with the assigned PID.

   The symbolic name can be a maximum of 29 characters  and  can  contain
   any  characters  as  long  as  it is terminated by a zero word.  There
   should be mutual understanding among  processes  as  to  the  symbolic
   names  used  in  order  to  initiate  communication.  Once the name is
   defined, any process referring to that name must  specify  it  exactly
   character for character.

   Before a process can send  a  packet,  it  must  know  the  receiver's
   symbolic  name  or  PID.   If  only  the receiver's name is known, the
   sender must ask <SYSTEM>INFO for the PID  associated  with  the  name,
   since all communication is via PIDs.

   The association between a PID and a name is broken:

        1.  On a RESET% monitor call.

        2.  When the process is killed or the job logs off the system.

        3.  When a request to disassociate the PID from the name is  made
            to <SYSTEM>INFO.

   <SYSTEM>INFO will not allow a name already associated with a PID to be
   assigned  again  unless  the owner of the name makes the request.  Nor
   will <SYSTEM>INFO assign a PID once it has  been  used.   This  action
   protects  against  messages  being  sent  to  the  wrong  receiver  by
   accident.



                                    7-5
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   The PIDs of the sender and the receiver are indicated by words  .IPCFS
   and .IPCFR, respectively, of the packet descriptor block.



   7.3.3  Length and Address of Packet Data Block
   7.3.3  Length and Address of Packet Data Block

   Word .IPCFP of the packet descriptor block contains the length and the
   beginning  address of the message.  The length specified is one of two
   types, depending on the type of message (refer to Section 7.3.5).   If
   the  message  is  a  short-form message, the length is the actual word
   length of the message.  If the message is  a  long-form  message,  the
   length is 1000 (octal) words, that is, one page.

   The address specified is either an address or a page number, depending
   on  the  type  of message (refer to Section 7.3.5).  When a message is
   sent, it is taken from this address.  When a message is  received,  it
   is placed in this address.



   7.3.4  Directories and Capabilities
   7.3.4  Directories and Capabilities

   Words .IPCFD and .IPCFC describe the sender at the  time  the  message
   was sent and are used by the receiver to validate messages sent to it.
   These two words are not used when a message is sent, and if the sender
   of  the  packet  supplies  them,  they  are  ignored.  However, when a
   message is received, if the receiver of the packet has reserved  space
   for  these  words  in the packet descriptor block, the system supplies
   the appropriate values of the sender of the packet.  The  receiver  of
   the  packet  does  not  have  to  reserve  these  words  if  it is not
   interested in knowing the sender's directories and capabilities.



   7.3.5  Packet Data Block
   7.3.5  Packet Data Block

   The packet data block contains the message  being  sent  or  received.
   The message can be either a short-form message or a long-form message.

   A short-form message is one to n words long, where n is defined by the
   installation.   (Usually,  n  is  assumed  to  be  10  words.)  When a
   short-form message is sent or received,  word  .IPCFP  of  the  packet
   descriptor block contains the actual word length of the message in the
   left half and the address of the first word  of  the  message  in  the
   right  half.   A  process  always  uses  the  short  form when sending
   messages to <SYSTEM>INFO.

   A long-form message is one page in length (1000 octal words).  When  a
   long-form  message  is  sent  or  received,  word .IPCFP of the packet
   descriptor block contains 1000 (octal) in the left half and  the  page
   number  of  the  message  in  the  right  half.  To send and receive a


                                    7-6
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   long-form message, both the sender and receiver must have  bit  IP%CFV
   (bit 19) set in the first word of the packet descriptor block, or else
   an error code is returned.



   7.4  SENDING AND RECEIVING MESSAGES
   7.4  SENDING AND RECEIVING MESSAGES

   To send a message, the sending process must  set  up  the  first  four
   words  of  the packet descriptor block.  The process then executes the
   MSEND% monitor call.  After execution of this call, the packet is sent
   to the intended receiver's input queue.

   To receive a message, the receiving process must also set up the first
   four words of the packet descriptor block.  The last two words for the
   directories and capabilities of the sender can be  supplied,  and  the
   system will fill in the appropriate values.  The process then executes
   the MRECV% monitor call.  After execution of this call,  a  packet  is
   retrieved from the receiver's input queue.  The input queue is emptied
   on a first-message-in, first-message-out basis.



   7.4.1  Sending a Packet
   7.4.1  Sending a Packet

   The MSEND% monitor call is used to send a message via IPCF.   Messages
   are  in  the  form  of  packets  of  information  and can be sent to a
   specified PID or to the system process <SYSTEM>INFO.  Refer to Section
   7.5 for information on sending messages to <SYSTEM>INFO.

   The MSEND% call accepts two words of arguments.   The  length  of  the
   packet  descriptor block is given in AC1, and the beginning address of
   the packet descriptor block is given in AC2.  Thus,

        AC1:  length  of packet descriptor block.  The length  cannot  be
              less than 4.

        AC2:  address of packet descriptor block

   The packet descriptor block consists of the following four words:

        .IPCFL         Flags
        .IPCFS         Sender's PID
        .IPCFR         Receiver's PID
        .IPCFP         Pointer to packet data block containing the
                       message being sent.


   Refer to Section 7.3 for the details  on  the  packet  descriptor  and
   packet data blocks.




                                    7-7
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   The flags that are meaningful when sending a packet are  described  in
   Table 7-2.  Refer to Table 7-1 for the complete list of flag bits.


   Table 7-2:  Flags Meaningful on a MSEND% Call
   Table 7-2:  Flags Meaningful on a MSEND% Call

   ______________________________________________________________________

     Bit      Symbol     Meaning
   ______________________________________________________________________

      0       IP%CFB     Do not block process if no messages in  queue;
                         if set, error return if no messages.

      1       IP%CFS     The sender's PID is given in  word  .IPCFS  of
                         the packet descriptor block.

      2       IP%CFR     The receiver's PID is given in word .IPCFR  of
                         the packet descriptor block.

      3       IP%CFO     Allow the sender to send one message above its
                         send quota.

      4       IP%TTL     Truncate  message   if   larger   than   space
                         reserved.

      5       IP%CPD     Create a PID for the sender and return  it  in
                         word  .IPCFS  of  the packet descriptor block.
                         The PID created is to be permanent and useable
                         by other processes according to the setting of
                         bits IP%JWP and IP%NOA.

      6       IP%JWP     The  PID  created  is  to  be  job  wide   and
                         permanent until the job logs out.  If this bit
                         is not on, the PID created is to be  temporary
                         until  the  process executes the RESET monitor
                         call.

      7       IP%NOA     The PID created is not to  be  used  by  other
                         processes.

     18       IP%CFP     The message being sent is privileged (refer to
                             _______ _______ _____ _________ ______
                         the TOPS-20 Monitor Calls Reference Manual).

     19       IP%CFV     The message being sent is a long-form  message
                         (that  is,  a  page).  The page the message is
                         being sent to cannot be a shared page; it must
                         be a private page.

     22       IP%EPN     Page number  in  word  .IPCFP  of  the  packet
                         descriptor block is 18 bits long.
   ______________________________________________________________________


                                    7-8
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   When bit IP%CFS is on in the flag word, the sender's PID is taken from
   word  .IPCFS of the packet descriptor block.  This word is zero if bit
   IP%CPD is on in the flag word, indicating that a PID is to be  created
   for  the  sender.   In  this case, the PID created is returned in word
   .IPCFS.

   When bit IP%CFR is on in the flag word, the receiver's  PID  is  taken
   from  word  .IPCFR of the packet descriptor block.  If this word is 0,
   then the receiver of the message is <SYSTEM>INFO.   Refer  to  Section
   7.5 for information on sending messages to <SYSTEM>INFO.

   On successful execution of the MSEND% monitor call, the packet is sent
   to  the  receiver's input queue.  Word .IPCFS of the packet descriptor
   block is updated with the  sender's  PID.   Execution  of  the  user's
   program  continues  at  the  second  location  after  the MSEND% call.
   (MSEND%)

   If execution of the MSEND% call is not successful, the message is  not
   sent,  and  an  error  code  is returned in AC1.  The execution of the
   user's program continues at the instruction following the MSEND% call.



   7.4.2  Receiving a Packet
   7.4.2  Receiving a Packet

   The MRECV% monitor call  is  used  to  retrieve  a  message  from  the
   process'  input  queue.   Before  a process can retrieve a message, it
   must know if the message is a long-form message and also must set up a
   packet descriptor block.

   The MRECV% monitor call accepts two words of arguments.  The length of
   the packet descriptor block is given in AC1, and the beginning address
   of the packet descriptor block is given in AC2.  Thus,

        AC1:  length of  packet descriptor block.  The length  cannot  be
              less than 4.

        AC2:  address of packet descriptor block

   The packet descriptor block can consist of the following  nine  words.
   The last five words are optional, and if supplied by the receiver, the
   values of the sender will be filled in by the system.


        .IPCFL         Flags
        .IPCFS         Sender's PID
        .IPCFR         Receiver's PID
        .IPCFP         Pointer to packet data block where the message  is
                       to be placed.
        .IPCFD         Connected and logged-in directories of the sender.
        .IPCFC         Enabled capabilities of the sender.
        .IPCSD         Number of sender's connected directory.


                                    7-9
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


        .IPCAS         Account string of sender.
        .IPCLL         Byte pointer for destination of sender's node.


   Refer to Section 7.3 for the details  on  the  packet  descriptor  and
   packet data blocks.

   The flags that are meaningful when receiving a packet are described in
   Table 7-3.  Refer to Table 7-1 for the complete list of flag bits.


   Table 7-3:  Flags Meaningful on a MRECV% Call
   Table 7-3:  Flags Meaningful on a MRECV% Call

   ______________________________________________________________________

     Bit      Symbol     Meaning
   ______________________________________________________________________

      0       IP%CFB     If there are  no  packets  in  the  receiver's
                         input  queue,  do  not  block  the process and
                         return an error code if the  queue  is  empty.
                         If this bit is not on, the process waits until
                         a packet arrives, if the queue is empty.

      1       IP%CFS     Use PID referenced in word .IPCFS as  sender's
                         PID.

      2       IP%CFR     The receiver's PID is given in word .IPCFR  of
                         the packet descriptor block.

      3       IP%CFO     Allow one send request above quota.   (Default
                         send quota is 2.)

      4       IP%TTL     Truncate the message if it is larger than  the
                         space  reserved  for  it  in  the  packet data
                         block.  If this bit is not on and the  message
                         is too large, an error code is returned and no
                         message is received.

      5       IP%CPD     Create PID  for  sender  and  return  in  word
                         .IPCFS.

      6       IP%JWP     Make created  PID  job  wide  (ignored  unless
                         IP%CPD set).

      7       IP%NOA     Do not allow other processes  to  use  created
                         PID (ignored unless IP%CPD set).

     18       IP%CFP     Packet is privileged (requires IPCF capability
                         enabled).




                                    7-10
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


     19       IP%CFV     The message is  expected  to  be  a  long-form
                         message  (that  is,  a  page).   The  page the
                         message is  being  stored  into  cannot  be  a
                         shared page; it must be a private page.

     22       IP%EPN     Page number  in  word  .IPCFP  of  the  packet
                         descriptor block is 18 bits long.
   ______________________________________________________________________


   The information in word .IPCFS is not supplied by  the  receiver  when
   the  MRECV%  call  is  executed.   The  system fills in the PID of the
   sender of the packet when the packet is retrieved.

   Word .IPCFR is supplied by the receiver.  If bit IP%CFR is on  in  the
   flag word, then the PID receiving the packet is taken from word .IPCFR
   of the packet descriptor block.  If bit IP%CFR is not on in  the  flag
   word, then word .IPCFR contains either -1, to receive a packet for any
   PID belonging to this process, or -2, to receive a packet for any  PID
   belonging  to  this  job.   When  -1  or  -2 is given, packets are not
   received in any particular order except that packets from  a  specific
   PID  are  received  in  the  order in which they were sent.  Any other
   values in this word cause an error code to be returned.

   The information in words .IPCFD and .IPCFC is also not supplied by the
   receiver.  If these two words have been specified by the receiver, the
   system fills in the information when the packet  is  retrieved.   Word
   .IPCFD  contains the sender's connected directory in the left half and
   the sender's logged-in directory  in  the  right  half.   Word  .IPCFC
   contains the enabled capabilities of the sender.  These words describe
   the sender at the time the message was sent.

   On successful execution of the MRECV%  monitor  call,  the  packet  is
   retrieved  and  placed into the packet data block as indicated by word
   .IPCFP of the packet descriptor block.  AC1 contains the length of the
   next  packet  in  the  queue  in the left half and flags from the next
   packet in the right half (see below).  This word returned  in  AC1  is
   called  the  associated  variable of the next packet in the queue.  If
   there  is  not  another  packet  in  the  queue,  AC1  contains  zero.
   Execution  of  the  user's program continues at the second instruction
   after the MRECV% call.

   The flags returned in the right half of AC1 on successful execution of
   the MRECV% monitor call are described in Table 7-4.










                                    7-11
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   Table 7-4:  MRECV% Return Bits
   Table 7-4:  MRECV% Return Bits

   ______________________________________________________________________

     Bit       Symbol       Meaning
   ______________________________________________________________________

     30-32     IP%CFC       System and  sender  code,  set  only  by  a
                            privileged process.  The packet was sent by
                            <SYSTEM>IPCF if the code is 1(.IPCCC).  The
                            packet   was   sent   by   the  system-wide
                            <SYSTEM>INFO if the code is 2(.IPCCF).  The
                            packet   was   sent   by   the   receiver's
                            <SYSTEM>INFO if the code is 3(.IPCCP).

     33-35     IP%CFM       Field for return of special  messages.   If
                            the  field  contains  1(.IPCFN),  then  the
                            process' input queue contains a packet that
                            was  sent  to another PID, but was returned
                            to the  sender  because  it  could  not  be
                            delivered.
   ______________________________________________________________________


   If execution of the MRECV% call is not successful,  a  packet  is  not
   retrieved, and an error code is returned in AC1.  The execution of the
   user's program continues at the instruction following the MRECV% call.



   7.5  SENDING MESSAGES TO <SYSTEM>INFO
   7.5  SENDING MESSAGES TO <SYSTEM>INFO

   The <SYSTEM>INFO process is the central information utility for  IPCF.
   It  performs  functions  associated  with  names  and  PIDs,  such as,
   assigning a PID or a name or returning a name associated with a PID.

   A process can request functions to be  performed  by  <SYSTEM>INFO  by
   executing  the  MSEND%  monitor  call  (refer  to Section 7.4.1).  The
   message portion of the packet (that is, the packet data block) sent to
   <SYSTEM>INFO  contains  the  request  being made.  In other words, the
   total request to <SYSTEM>INFO is  a  packet  consisting  of  a  packet
   descriptor block and a packet data block containing the request.












                                    7-12
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   Packet Descriptor Block


           !=======================================================!
           !                       flag word                       !
           !-------------------------------------------------------!
           !                     sender's PID                      !
           !-------------------------------------------------------!
           !                           0                           !
           !-------------------------------------------------------!
           !                  pointer to request                   !
           !=======================================================!


   Packet Data Block


           !=======================================================!
           !           code            !         function          !
           !                           !                           !
           !-------------------------------------------------------!
           !                          PID                          !
           !-------------------------------------------------------!
           !                   function argument                   !
           !=======================================================!

   Refer to Section 7.4.1 for the descriptions of the words in the packet
   descriptor  block.  The receiver's PID (word .IPCFR) is 0 when sending
   a packet to <SYSTEM>INFO.



   7.5.1  Format of <SYSTEM>INFO Requests
   7.5.1  Format of <SYSTEM>INFO Requests

   As mentioned previously, the packet data block (that is,  the  message
   portion) of the packet contains the request to <SYSTEM>INFO.

   The first word (word .IPCI0) contains a user-defined code in the  left
   half  and  the  function  being  requested  in  the  right  half.  The
   user-defined code is used to associate the response from  <SYSTEM>INFO
   with  the correct request.  The functions that the process can request
   of <SYSTEM>INFO are described in Table 7-5.

   The second word (word .IPCI1) contains a PID associated with a process
   that  is to receive a duplicate of any response from <SYSTEM>INFO.  If
   this word is zero, the response from <SYSTEM>INFO is sent only to  the
   process making the request.

   The third word (word .IPCI2) contains the argument  for  the  function
   specified in the right half of word .IPCI0.  The argument is different
   depending on the function being  requested.   The  arguments  for  the
   functions are described in Table 7-5.


                                    7-13
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   Table 7-5:  <SYSTEM>INFO Functions and Arguments
   Table 7-5:  <SYSTEM>INFO Functions and Arguments

   ______________________________________________________________________

     Function     Argument       Meaning
   ______________________________________________________________________

      .IPCIW        name         Return the  PID  associated  with  the
                                 given name (refer to Section 7.3.2 for
                                 the description of the name).

      .IPCIG        PID          Return the name  associated  with  the
                                 given PID.

      .IPCII        name in      Assign the  given name  to  the PID
                    ASCIZ        associated with the process making the
                                 request.   The  PID  is  permanent  if
                                 IP%JWP was set in the flag  word  when
                                 the  PID was originally created (refer
                                 to Table 7-1).

      .IPCIJ        name in      Identical to .IPCII function.
                    ASCIZ
   ______________________________________________________________________



   7.5.2  Format of <SYSTEM>INFO Responses
   7.5.2  Format of <SYSTEM>INFO Responses

   Responses from <SYSTEM>INFO are in the form of a packet  sent  to  the
   process  that made the request.  A copy of the response is sent to the
   PID given in word .IPCI1, if any.

   The message portion (that is, the packet data  block)  of  the  packet
   contains  the response from <SYSTEM>INFO.  The format of this response
   is

           !=======================================================!
           !           code            !         function          !
           !                           !                           !
           !-------------------------------------------------------!
           !                       response                        !
           !-------------------------------------------------------!
           !                       response                        !
           !=======================================================!

   The first word (word .IPCI0) contains the  user-defined  code  in  the
   left  half  and  the  function  that  was requested in the right half.
   These values are copied from the values given in the request.

   The second and third words  (words  .IPCI1  and  .IPCI2)  contain  the
   response from the function requested of <SYSTEM>INFO.  The response is


                                    7-14
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   different depending on the function requested.  The responses from the
   functions are described in Table 7-6.

   Table 7-6:  <SYSTEM>INFO Responses
   Table 7-6:  <SYSTEM>INFO Responses

   ______________________________________________________________________

     Function Requested     Response
   ______________________________________________________________________

          .IPCIW            The PID associated with the name  given  in
                            the request is returned in word .IPCI1.

          .IPCIG            The name associated with the PID  given  in
                            the request is returned in word .IPCI1.

          .IPCII            No response is returned.
   ______________________________________________________________________



   7.6  PERFORMING IPCF UTILITY FUNCTIONS
   7.6  PERFORMING IPCF UTILITY FUNCTIONS

   A process can request various functions to be performed  by  executing
   the  MUTIL%  monitor  call.   Some of these functions are enabling and
   disabling PIDs, creating and  deleting  PIDs,  and  returning  quotas.
   Several  of  the  functions  that  can  be  requested  are  privileged
                                          _______ _______ _____ _________
   functions.  These are described in the TOPS-20 Monitor Calls Reference
   ______
   Manual.

   The MUTIL% monitor call accepts two words of argument.  The length  of
   the  argument  block is given in AC1, and the beginning address of the
   argument block is given in AC2.

   The argument block has the following format:

           !=======================================================!
           !                     function code                     !
           !-------------------------------------------------------!
           !                 argument for function                 !
           !-------------------------------------------------------!
           !                 argument for function                 !
           !=======================================================!

   The  arguments  are  different,  depending  on  the   function   being
   requested.   Any  values  resulting  from  the  function requested are
   returned in the argument block, starting at the second word.

   Table 7-7 describes the functions that can be requested, the arguments
   for the functions, and the values returned from the functions.




                                    7-15
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


   Table 7-7:  MUTIL% Functions
   Table 7-7:  MUTIL% Functions

   ______________________________________________________________________

     Function          Meaning
   ______________________________________________________________________

     .MUENB            Allow the PID given to receive packets.  If  the
                       process  executing  the call is not the owner of
                       the PID, the process must be privileged.

                       Argument
                           PID

                       Value Returned
                           None

     .MUDIS            Disable the PID given  from  receiving  packets.
                       If  the  process  executing  the call is not the
                       owner  of  the  PID,   the   process   must   be
                       privileged.

                       Argument
                           PID

                       Value Returned
                           None

     .MUGTI            Return the PID associated with <SYSTEM>INFO.

                       Argument
                           PID or job number

                       Value Returned
                           PID of <SYSTEM>INFO

     .MUCPI            Create a private copy of  <SYSTEM>INFO  for  the
                       specified   job.   The  caller  must  have  IPCF
                       capability enabled.

                       Argument
                           PID to be assigned to <SYSTEM>INFO
                           PID or number of job creating private copy

     .MUDES            Delete the PID given.  The process executing the
                       call must own the PID being deleted.

                       Argument
                           PID to be deleted

                       Value Returned
                           None


                                    7-16
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


     .MUCRE            Create a PID for the process or job  given.   If
                       the  job number given is not that of the process
                       executing  the  call,  the   process   must   be
                       privileged.  The flag bits that can be specified
                       are IP%JWP and IP%NOA (refer to  Table  7-1  for
                       their descriptions).

                       Argument
                           flag  bits  in  the  left  half, and process
                           handle or job number in the right half

                       Value Returned
                           PID that was created

     .MUSSQ            Set send and receive quotas  for  the  specified
                       PID.   The  caller  must  have  IPCF  capability
                       enabled.  The new send quota is  given  in  bits
                       18-26,  and  the  new  receive quota is given in
                       bits 27-35.  The receive quota  applies  to  the
                       specified PID, but the send quota applies to the
                       job to which that PID belongs.

                       Argumemts
                           PID
                           new quotas

     .MUFOJ            Return the number of the job associated with the
                       PID given.

                       Argument
                           PID

                       Value Returned
                           Job number associated with PID given

     .MUFJP            Return all PIDs associated with the job given.

                       Argument
                           job number or PID belonging to the job

                       Values Returned
                           Two-word entries for each PID  belonging  to
                           the job.  The first word of the entry is the
                           PID, and the second word has bits IP%JWP and
                           IP%NOA  set  if  appropriate (refer to Table
                           7-1 for the  descriptions  of  these  bits).
                           The  list  of entries returned is terminated
                           by a zero word.

     .MUFSQ            Return the send quota and the receive quota  for
                       the PID given.



                                    7-17
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


                       Argument
                           PID

                       Values Returned
                           Send quota in bits 18-26 and  receive  quota
                           in bits 27-35.

     .MUFFP            Return all PIDs associated with the  process  of
                       the PID given.

                       Argument
                           PID

                       Values Returned
                           Two-word entries for each PID  belonging  to
                           the process.  The first word of the entry is
                           the PID, and the second word has bits IP%JWP
                           and  IP%NOA  set  if  appropriate  (refer to
                           Table 7-1  for  the  descriptions  of  these
                           bits).   The  list  of  entries  returned is
                           terminated by a zero word.

     .MUSPQ            Set the maximum number of PIDs allowed  for  the
                       specified   job.   The  caller  must  have  IPCF
                       capability enabled.

                       Argument
                          job number or PID
                          PID quota

     .MUFPQ            Return the maximum number of  PIDs  allowed  for
                       the job given.

                       Argument
                           Job number or PID belonging to the job

                       Value Returned
                           Number of PIDs allowed for the job given

     .MUQRY            Return the packet descriptor block for the  next
                       packet in the queue of the PID given.

                       Argument
                           PID, -1 to return the next descriptor  block
                           for  the  process,  or -2 to return the next
                           descriptor block for the job

                       Values Returned
                           Packet  descriptor  block of next packet in
                           queue.

     .MUAPF            Associate the PID given with the process given.


                                    7-18
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


                       Arguments
                           PID
                           process handle

                       Value Returned
                           None

     .MUPIC            Place the specified PID on a software  interrupt
                       channel.  An interrupt is then generated when:

                       1.  The MUPIC function is issued while  the  PID
                           has  one  or  more  messages  in its receive
                           queue.

                       2.  The PID's receive queue  changes  its  state
                           from   empty   to   containing   a  message.
                           Subsequent entries to a queue  that  is  not
                           empty do not cause an interrupt.

                       If the channel number is given as -1, the PID is
                       removed from its current channel.

                       The calling process and the  process  that  owns
                       the specified PID must belong to the same job.

                       Arguments
                           PID
                           channel number

     .MUDFI            Set the PID of <SYSTEM>INFO.  An error is  given
                       if  <SYSTEM>INFO  already has a PID.  The caller
                       must have IPCF capability enabled.

                       Arguments
                           PID of <SYSTEM>INFO

     .MURSP            Return a PID from the system PID table.  The PID
                       is  returned  in  word  2 of the argument block.
                       The system PID table currently has the following
                       entries:

                         0  .SPIPC  Reserved for Digital
                         1  .SPINF  PID of <SYSTEM>INFO
                         2  .SPQSR  PID of QUASAR
                         3  .SPMDA  PID of QSRMDA
                         4  .SPOPR  PID of ORION

                       Argument

                           index into system PID table




                                    7-19
                    INTER-PROCESS COMMUNICATION FACILITY
                    INTER-PROCESS COMMUNICATION FACILITY


     .MUMPS            Return the  maximum  packet  size  for  the  PID
                       given.

                       Argument
                           PID

                       Value Returned
                           Maximum packet size for PID

     .MUSKP            Set PID to receive deleted PID messages.  Allows
                       a  controller  task to be notified if one of its
                       subordinate tasks crashes.  After this  function
                       is  performed,  if  the  subordinate PID is ever
                       deleted  (via  RESET   or   the   .MUDES   MUTIL
                       function), the monitor will send an IPCF message
                       to the controlling PID  notifying  it  that  the
                       subordinate  PID has been deleted.  This message
                       contains .IPCKP in word 0 and the deleted PID in
                       word 1.

                       Argument
                           Source (subordinate) PID
                           Object (controller) PID

     .MURKP            Return controlling PID for this subordinate PID.

                       Argument
                           Source (subordinate) PID
                           Object (controller) PID (returned)
   ______________________________________________________________________


   On successful completion of the  MUTIL%  monitor  call,  the  function
   requested  is performed, and any value is returned are in the argument
   block.  Execution of  the  user's  program  continues  at  the  second
   location following the MUTIL% call.

   If execution  of  the  MUTIL%  monitor  call  is  not  successful,  no
   requested  function is performed and an error code is returned in AC1.
   Execution of the user's program continues at  the  location  following
   the MUTIL% call.













                                    7-20












                                 CHAPTER 8
                                 CHAPTER 8

                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING



   The term "extended addressing" refers to the  size  of  the  addresses
   that  TOPS-20 uses on the DECSYSTEM-20 Extended KL10 processor.  Older
   versions of TOPS-20 (Release 4.1 and before)  used  18-bit  addresses;
   newer versions (Release 5 and after) use 30-bit addresses.

   This chapter discusses the two main activities associated  with  using
   TOPS-20 monitor calls with extended addressing:

        1.  Writing new programs for  execution  in  sections  of  memory
            other than section 0

        2.  Converting existing programs so that they can be executed  in
            sections other than section 0

   This chapter also contains information on  hardware  instructions  and
   macros useful to MACRO programmers who use extended addressing.

   The discussion in this chapter depends heavily on the material in  the
   _________________________  _________  _________ ______
   DECsystem-10/DECSYSTEM-20  Processor  Reference Manual.  Refer to that
   manual for a description  of  the  format  of  30-bit  addresses,  the
   algorithm the processor uses to calculate effective addresses, and the
   way that individual machine instructions work.



   8.1  OVERVIEW
   8.1  OVERVIEW

   The TOPS-20 extended address space  contains  32  (decimal)  sections.
   Each  section  contains  512 pages of 512 words each (256K words).  An
   18-bit address, called a local address, can reference any  word  in  a
   given section.  A 30-bit, or global, address can reference any word in
   any section of memory.

   In contrast, TOPS-20 V4.1 and earlier provided  an  18-bit,  256K-word
   address  space.   The  Program Counter (PC) register was 18 bits.  For
   each instruction executed, the first action taken was the  computation
   of  an  18-bit  effective  address.  The algorithm for calculating the


                                    8-1
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   effective address (including indexing and indirecting rules)  was  the
   same for all instructions.

   Because the TOPS-20 virtual address space is limited to  32  sections,
   and  section  numbers  longer than 5 bits are illegal, legal addresses
   are effectively limited to 23 bits.  When  addressing  data,  you  can
   view this 32-section address space as one large memory area.

   From the point of  view  of  program  execution,  however,  memory  is
   divided  into  32  discrete sections.  A program can have code in more
   than one section of memory, and it can execute that code (assuming the
   constraints  discussed below), but it must change sections explicitly,
   as discussed below.

   Compatibility for existing programs  is  provided  by  section  0.   A
   program  running in section 0 behaves as though it were being executed
   on  a  system  without  extended  addressing,   except   for   certain
   instructions  such  as XJRSTF.  For more information on the actions of
                                     _________________________  _________
   specific instructions,  see  the  DECsystem-10/DECSYSTEM-20  Processor
   _________ ______
   Reference Manual.



   8.2  ADDRESSING MEMORY AND ACS
   8.2  ADDRESSING MEMORY AND ACS

   The  extended   format   PC   contains   a   section   field   and   a
   word-within-section  field.  When an instruction is executed, only the
   word field is incremented.  Column overflow is never carried from  the
   word  field  to  the  section field.  If the last word of a section is
   executed, and it is not a jump instruction, then the next  instruction
   is  fetched  from word 0 of the same section.  Thus a program can only
   change sections explicitly, by means of a PUSHJ, JRST, XJRST or XJRSTF
   instruction,  and  only  an XJRST or an XJRSTF can change control from
   section 0 to another section.

   Because a whole word cannot contain a 30-bit address and  the  program
   flags,  the  PC and flags are a two-word entity.  The flag bits are in
   the first word, and the  figure  below  represents  the  second  word.
   Figure 8-1 shows the format of the address fields of the PC.


             0     5 6              17 18                    35
             --------------------------------------------------
             ! un-  !      section   !    word-within-        !
             ! used !      number    !    section             !
             --------------------------------------------------


   Figure 8-1:  Program Counter Address Fields
   Figure 8-1:  Program Counter Address Fields





                                    8-2
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   The word (word-within-section) field consists  of  18  bits  and  thus
   represents  a  256K-word  address  space similar to the single-section
   address space of release 4 and earlier.  The section number  field  is
   12 bits, of which only the right-hand five bits can be nonzero because
   section numbers greater than 31 are illegal.  The leftmost seven  bits
   of  the  section  number  field  must  be zero.  This provides room to
   address 32 separate sections, each of 256K words.

   Each section is further divided into pages of 512 words,  just  as  in
   earlier   releases.   The  paging  facilities  allow  the  monitor  to
   determine the existence and protection of each section.

   The PC section field determines what section a program is running  in.
   If  the section field contains zero, the program is running in section
   0.  Most extended addressing features are not available to  a  program
   running  in  section  0.   All  quantities (including addresses), when
   calculated from section 0, are considered to be local (18 bits).

        1.  A program executing in section 0 cannot address memory in any
            other   section.   (One-word  global  byte  pointers  are  an
                                                                  _______
            exception to this rule.  Refer to Chapter 1  of  the  TOPS-20
            _______ _____ _________ ______
            Monitor Calls Reference Manual for more information.)

        2.  The program cannot jump from section  0  to  another  section
            unless  it  uses  a  monitor  call  or  the  XJRST  or XJRSTF
            instruction.

        3.  The program runs exactly as it would run on a machine without
            extended addressing.

   If the section  field  contains  a  number  from  1  to  31  (decimal)
   inclusive,  the  program  is executing in a nonzero section (a section
   other than section 0).  The hardware  considers  addresses  to  be  30
   bits, and the program can use extended addressing features.

   A local address is defined as an 18-bit address in the same section as
   the  program  counter  (PC)  of  the instruction.  Local addresses are
   relative to the PC section.  A global address  is  a  30-bit  address,
   which therefore supplies its own section number.

   The following paragraphs  explain  the  way  effective  addresses  are
   calculated  in  nonzero sections.  In addition, see the description in
       _________________________ _________ _________ ______
   the DECsystem-10/DECSYSTEM-20 Processor Reference Manual.



   8.2.1  Instruction Format
   8.2.1  Instruction Format

   The format of a machine instruction is the same as  on  an  unextended
   machine.   The  effective  address  calculation depends on the address
   field (Y, 18 bits), the index field (X,  4  bits),  and  the  indirect
   field (I, 1 bit).  Figure 8-2 shows these fields.


                                    8-3
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


             0       8 9  12  13 14   17 18                   35
             ---------------------------------------------------
             !        !     !   !       !                      !
             ! OPCODE ! AC  ! I !   X   !           Y          !
             !        !     !   !       !                      !
             ---------------------------------------------------


   Figure 8-2:  Instruction Word Address Fields
   Figure 8-2:  Instruction Word Address Fields


   If  I  and  X  are  0,  the  instruction  uses  neither  indexing  nor
   indirection,  so  the  effective  address is Y (18 bits).  The section
   number, since it is not specified in the address, is  taken  from  the
   section  field of the PC.  The PC section field contains the number of
   the section from which the instruction was fetched.   Such  an  18-bit
   address is called a local address.

   The following is an example of an instruction whose I, X and Y  fields
   evaluate to an 18-bit effective address.

        3,,400/    MOVEM T,1000

   The effective address is  word  1000  of  the  current  section.   The
   section  from  which  the  instruction is fetched is section 3, so the
   instruction moves the contents of register T into memory word 3,,1000.



   8.2.2  Indexing
   8.2.2  Indexing

   The first step in the effective address calculation is  indexing.   If
   the  X  field  is  nonzero,  indexing is used.  The calculation of the
   effective address then depends on the contents of the specified  index
   register.  Indexing may be local or global as follows:

         o  If the left half of the index register  contains  a  negative
            number  or  zero, the contents of the right half (bits 18-35)
            are added to Y (from the instruction word) to yield an 18-bit
            local address.

            This is the way indexing is done on  an  unextended  machine.
            It  allows a program to use the usual AOBJN pointer and stack
            pointer formats for tables and stacks that are  in  the  same
            section as the program.  Note, however, that if the left half
            of the index register contains a positive number, the results
            are not the same.

         o  If the left half of the index register  contains  a  positive
            number,  the  contents of bits 6-35 of the register are added
            to Y to yield a 30-bit global address.



                                    8-4
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


            This means that instructions can  reference  30-bit  (global)
            addresses  by  means of an index register.  If the Y field is
            0, the instruction refers to the address contained in X.  The
            Y  field  can  contain  a  positive  or  negative  offset  of
            magnitude less than 2^17.



   8.2.3  Indirection
   8.2.3  Indirection

   If the I field contains 1, the instruction specifies indirection.   An
   indirect  word is fetched from the address determined by Y and X.  Two
   types of indirect word exist, Instruction Format Indirect Word  (IFIW)
   and  Extended  Format Indirect Word (EFIW).  They are described in the
   following section.



   8.2.3.1  Instruction Format Indirect Word (IFIW)
   8.2.3.1  Instruction Format Indirect Word (IFIW) - This word  contains
   Y,  X,  and  I  fields  of  the  same size and in the same position as
   instructions (in bits 13-35).  Bit 0 must be 1, and bit 1 must  be  0;
   bits 2-12 are not used.

   Figure 8-3 shows an instruction format indirect word.


              0 1 2         12 13 14  17 18                     35
             -----------------------------------------------------
             ! ! !            !  !     !                         !
             !1!0! (not used) !I !  X  !             Y           !
             ! ! !            !  !     !                         !
             -----------------------------------------------------


   Figure 8-3:  Instruction Format Indirect Word
   Figure 8-3:  Instruction Format Indirect Word



   The effective address calculation continues  with  the  quantities  in
   this  word  just  as  for  the  original instruction.  Indexing can be
   specified and can be local or global depending on the left half of the
   index.  Further indirection can also be specified.

   Note that the default section for any local  addresses  produced  from
   this  indirect  word  is  the  section  from which the word itself was
   fetched.  This means that the default section can  change  during  the
   course of an effective address calculation that uses indirection.  The
   default section is always the section from which the last address word
   was fetched.





                                    8-5
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   8.2.3.2  Extended  Format  Indirect  Word  (EFIW)
   8.2.3.2  Extended  Format  Indirect  Word  (EFIW) - This   word   also
   contains  Y,  X,  and I fields, but in a different format.  Figure 8-4
   shows an extended format indirect word.


              0 1 2   5 6            17 18                     35
             -----------------------------------------------------
             ! ! !     ! <-------------!- Y -------------------> !
             !0!I!  X  !   (section)   !          (word)         !
             ! ! !     !               !                         !
             -----------------------------------------------------


   Figure 8-4:  Extended Format Indirect Word
   Figure 8-4:  Extended Format Indirect Word


   If indexing is specified in this indirect word (bits 2-5 nonzero), the
   contents  of  the  entire  index register are added to the 30-bit Y to
   produce a global address.  This type of indirect word never produces a
   local  address.   The type of address calculation used does not depend
   on the contents of the index register specified in the X field.

   Hence either Y or Y(X) can be used as an address or an  offset  within
   the  extended  address  space,  just  as is done in the 18-bit address
   space.  If further indirection is specified  (bit  1  set),  the  next
   indirect word is fetched from Y as modified by indexing (if any).  The
   next indirect word can be in instruction format  or  extended  format,
   and  its  interpretation does not depend on the format of the previous
   indirect word.



   8.2.3.3  Macros for Indirection
   8.2.3.3  Macros for Indirection - The system file MACSYM.MAC  contains
   several  convenient  macros  for  constructing  indirect words.  Macro
   LFIWM generates local (instruction format) indirect words.   Both  the
   macros EP.  and GFIWM may be used to generate global (extended format)
   indirect words.



   8.2.4  AC References
   8.2.4  AC References

   A local address in the range 0-17 (octal) references the hardware  ACs
   as memory.  This is true in every section of memory.

   A global address in section 1 in the range 1,,0 to 1,,17 (octal)  also
   refers  to  the  hardware  ACs.  A global address in any other section
   refers to memory.  This means that the following behavior occurs.

        1.  Addresses in the range 0-17 reference ACs as  expected.   The
            instruction

                 MOVE 2,3

                                    8-6
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


            fetches the contents of hardware  register  3  regardless  of
            what section the instruction executes in.

        2.  To make a global reference to an AC, the global address  must
            contain a section number of 0 or 1.

        3.  Arrays  can  cross  section  boundaries.   Global   addresses
            specifying  any  section  except  section  1  always refer to
            memory,  never  to  the  hardware  ACs.   For  this   reason,
            incrementing  the  address  6,,777777,  for  example,  yields
            address 7,,000000, which is a memory location.

        4.  The ACs are regarded as local to any section; a local address
            (0-17)  references  the  ACs from any section.  Hence, a jump
            instruction which yields a local effective address of 0-17 in
            any section will cause code to be executed from the ACs.



   8.2.5  Extended Addressing Examples
   8.2.5  Extended Addressing Examples

   These  instructions  make  local  references  within  the  current  PC
   section:

             3,,400/   MOVE T,1000              ; fetches from 3,,1000
                       JRST 2000                ; jumps to 3,,2000

   The following instructions scan table TABL, which is  in  the  current
   section:

                       MOVSI X,-SIZ
             LP:       CAMN T,TABL(X)           ; TABL in current section
                       JRST FOUND
                       AOBJN X,LP

   The following instructions scan table TABL, which is in section  TSEC,
   by using a global address:

                       MOVEI X,0
             LP:       CAMN T,@[GFIWM TSEC,TABL(X)] ; extended format
                       JRST FOUND
                       CAIGE X,SIZ-1
                       AOJA X,LP

   Similarly, the EP.  macro can be used for the same purpose:

                       MOVEI X,0
             LP:       CAMN T,@[EP.<TSEC>B17!TABL(X)]
                       JRST FOUND
                       CAIGE X,SIZ-1
                       AOJA X,LP



                                    8-7
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   The following examples illustrate  various  aspects  of  indexing  and
   indirection in effective address calculation:

             4/100
             6,,1000/MOVE 1,@2000
             6,,2000/LFIWM @4000
             6,,4000/LFIWM 200(4)

             Effective address = 300 in section 6


             6,,SUB/   MOVE 1,@[LFIWM @ZZZ]

             6,,ZZZ:   LFIWM @XXX
             XXX:      LFIWM ARRAY(4)

             Effective address = ARRAY+100 in section 6


             6/14,,ADDRX
             11,,ROU/MOVE 1,@[LFIWM (6)]

             14,,ADDRX: LFIWM 100

             Effective address = 14,,100




   8.2.6  Immediate Instructions
   8.2.6  Immediate Instructions

   Each effective address calculation yields a 30-bit address, defaulting
   the  section  if  necessary.   Immediate  instructions  use  only  the
   low-order 18 bits of this as  their  operand,  however,  and  set  the
   high-order  18  bits  to  0.  Hence instructions such as MOVEI and CAI
   produce identical results regardless of the section in which they  are
   executed.

   Two immediate instructions retain the section field of their effective
   addresses.  These are:

         o  XMOVEI (opcode 415) Extended Move Immediate

         o  XHLLI (opcode 501) Extended Half Word Left to Left Immediate



   8.2.6.1  XMOVEI
   8.2.6.1  XMOVEI - The XMOVEI instruction loads  the  30-bit  effective
   address  into  the  AC,  and  sets  bits  0-5 to 0.  If no indexing or
   indirection is used, the number of the current section is copied  from
   the  PC  to  the AC.  This instruction can replace MOVEI when a global
   address is needed.


                                    8-8
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   The following example shows the use of the  XMOVEI  instruction  in  a
   subroutine  call.  The subroutine is in section XSEC, but the argument
   list is in the same section as the calling program.

        XMOVEI AP,ARGLIST
        PUSHJ P,@[GFIWM XSEC,SUBR]

   The  subroutine  can  reference  the  arguments  with  the   following
   instruction.

        MOVE T,@1(AP)

   To construct the addresses of arguments, the subroutine  can  use  the
   following instruction.

        XMOVEI T,@2(AP)

   The last  two  instructions  assume  that  register  AP  contains  the
   argument  list  pointer.  If the address the calling program placed in
   AP is an IFIW, the section number in the effective address is that  of
   the  calling program.  If the address the calling program placed in AP
   is an EFIW, the  section  number  in  the  effective  address  of  the
   argument block is determined by the section number the calling program
   placed in AP.

   The argument list would be found in the caller's  section  because  of
   the  global  address  in  AP.  The section of the effective address is
   determined by the caller, and is implicitly the same as the caller  if
   an  IFIW  is used as the arglist pointer, or is explicitly given if an
   EFIW is used.



   8.2.6.2  XHLLI
   8.2.6.2  XHLLI - The XHLLI instruction replaces the left half  of  the
   accumulator  with the section number of the PC, and places zero in the
   right half of the AC.  This instruction  is  useful  for  constructing
   global addresses.



   8.2.7  Other Instructions
   8.2.7  Other Instructions

   The instructions discussed here are affected by  extended  addressing,
   but  not  necessarily  in  the  way that their effective addresses are
   calculated.  In addition to  the  material  presented  here,  see  the
   _________________________  _________  _________  ______
   DECsystem-10/DECSYSTEM-20  Processor  Reference  Manual  regarding the
   following instructions:  LUUOs, BLT, XBLT, XCT,  XJRSTF,  XJEN,  XPCW,
   SFM.






                                    8-9
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   8.2.7.1  Instructions that  Affect  the  PC
   8.2.7.1  Instructions that  Affect  the  PC - These  instructions  are
   PUSHJ,  POPJ,  JRST.   PUSHJ stores a 30-bit PC address, but stores no
   flags.  It sets bits 0-5 of the destination word to 0.

   POPJ restores a 30-bit PC address from the stack, but does not restore
   the flags.  It also sets bits 0-5 of the destination word to 0.

   The JSA and JRA instructions can be used only within  a  section.   In
   section  0  the  JSP and JSR instructions can store flags,,PC but then
   cannot transfer out of section 0.  The JSP and  JSR  instructions  can
   store  flags,,PC  in  nonzero  sections and then can transfer into any
   other  section  (if  the  address  is  specified  with   indexing   or
   indirection).



   8.2.7.2  Stack  Instructions
   8.2.7.2  Stack  Instructions - PUSHJ,  POPJ,  PUSH,  POP,  and  ADJSP.
   These  instructions  use  a  local  or  global  address  for the stack
   according to the contents of the stack  pointer.   Whether  the  stack
   address  is  local  or  global depends on the same rules as those that
   govern  indexing  in  effective  address  calculation.   (See  section
   8.2.2.)  It  is  always best to use the ADJSP instruction when working
   with stacks.  This instruction works in any section and will  indicate
   when a pushdown overflow error occurs.

   In brief, if the left half of the stack pointer is  zero  or  negative
   (prior  to  incrementing  or  decrementing),  the pointer references a
   local address and the address in its right half is the address of  the
   current  item  in  the  stack.   The  stack  pointer is incremented or
   decremented  by  adding  or   subtracting   one   from   both   sides,
   respectively.

   If the left half of the stack pointer is positive, the entire word  is
   taken as a global address.  The stack pointer is incremented by adding
   1, and decremented by subtracting 1.

   A stack that contains global addresses can be  used  the  same  way  a
   local  stack is used.  The global stack, however, can contain pointers
   to routines in other sections.

   To protect against stack overflow and underflow, make the pages before
   and  after the stack inaccessible.  This method must be used because a
   global stack has no room for a count in the left half of the pointer.



   8.2.7.3  Byte Instructions
   8.2.7.3  Byte Instructions - To reference a byte in  another  section,
   you  must  use  either a one-word, or a two-word, global byte pointer.
   Both global and local byte pointers are  legal  arguments  to  monitor
   calls from nonzero sections but there are some restrictions on the use
   of one-word global byte pointers from section 0.  See Section 8.3  for
   further information.


                                    8-10
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


                    _______  _______  _____  _________  ______
   Chapter 1 of the TOPS-20  Monitor  Calls  Reference  Manual  describes
                                                _________________________
   one-word   global   byte   pointers.    The  DECsystem-10/DECSYSTEM-20
   _________ _________ ______
   Processor Reference Manual describes two-word global byte pointers.



   8.3  USING MONITOR CALLS
   8.3  USING MONITOR CALLS

   If a program runs in a single section, even though that section is not
   section  0,  most  monitor  calls  execute  exactly the way they do in
   section 0.  This is because when no section number is  specified,  the
   current section is the default.

   The GTFDB% call, for example, requires that AC3 contain the address of
   the  block  in  which  to store the data it obtains from the file data
   block.  This address can be  an  18-bit  address  regardless  of  what
   section the monitor call is made from.  When the monitor sees that the
   address is local, it obtains the section number from  the  PC  of  the
   process that makes the call.

   The same is true of calls that accept page numbers.  If a  9-bit  page
   number  is  passed  as  an  argument,  the monitor obtains the section
   number from the PC of the process that made the call.   Monitor  calls
                                                    _______ _______ _____
   arguments  are  discussed  in  Chapter  1 of the TOPS-20 Monitor Calls
   _________ ______
   Reference Manual.

   It is sometimes desirable to  specify  addresses  in  section  0  when
   executing  a  JSYS  from a nonzero section.  The bit PM%EPN for PMAP%,
   and FH%EPN for JSYSs that accept fork  handles,  prevent  the  current
   section  (the  section  in  which a program is running) from being the
   target section for the monitor call's arguments.

   Another restriction on arguments passed to monitor calls  executed  in
   sections  other  than section 0 concerns universal device designators,
   which have  the  format  5xxxxx,,xxxxxx  or  6xxxxx,,xxxxxx  (.DVDES).
   Universal  device designators are not legal except in section 0.  This
   is because of the existence of one-word global  byte  pointers,  which
   can have the same format.

   Thus monitor calls that accept either a device designator  or  a  byte
   pointer  when  called  from  section  0 do not accept universal device
   designators in any other section.  Other device designators,  such  as
   .TTDES  (0,,4xxxxx),  can  be  used in any section.  Conversely, these
   monitor calls that can accept either universal device  designators  or
   byte  pointers  do not accept one-word global byte pointers in section
   0.

   The calls SIR% and RIR% should not be  used  in  sections  other  than
   section  0.   These  calls work in other sections only if all the code
   associated with these calls exists in the same  section  as  the  code
   that makes the call.



                                    8-11
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   For example, if an SIR% call is executed in  section  4,  it  executes
   correctly  if  and only if the code that generates the interrupts, the
   interrupt-processing routines, and  all  associated  tables  are  also
   located  in section 4.  Thus, in programs intended to run in a section
   other than section 0, the XSIR% and XRIR% calls, described in  Chapter
   4,  should  be  used  in  place  of  SIR% and RIR%.  In general, it is
   recommended that the extended form of monitor calls be used since this
   form works in any section, including section 0.



   8.3.1  Mapping Memory
   8.3.1  Mapping Memory

   The PMAP% monitor call accepts an 18-bit page number, half of which is
   a  section  number.   Thus  PMAP%  can  be used to map a page from one
   section to another.  If the destination section does not  exist,  that
   section will be created.

   The SMAP% monitor call maps one or more sections of memory.  It  works
   like  the  PMAP  call,  but  maps  sections  instead of pages.  If the
   destination section does not exist, SMAP% creates the section.

   Access to the sections in a process map  is  determined  by  the  same
   algorithm that determines access to a page within a given section.  If
   a process section and a page in that section have different  accesses,
   the  access  privileges  are  ANDed  together.  The process requesting
   access to the page gains access only if it has access rights at  least
   equal to the ANDed protections.

   For example, if a process has read access to a section and maps a page
   into that section for which the process has read and write access, the
   page is mapped, but the process gets only read access  to  the  mapped
   page.

   The following sections describe the SMAP% functions.



   8.3.1.1  Mapping File Sections to a Process
   8.3.1.1  Mapping File Sections to a Process - This function  maps  one
   or  more sections of a file to a process.  All pages that exist in the
   source sections are mapped to the destination sections.  Access to the
   mapped  pages  is  determined by ANDing the access allowed to the file
   and the access specified in the SMAP% call.

   Although files do not actually have section boundaries,  this  monitor
   call  views  them  as  having  sections that consist of 512 contiguous
   pages.  Each file section starts with a page number that is an integer
   multiple of 512.

   This call cannot map a process memory section to a  file.   To  map  a
   process  section  to  a  file,  use  the PMAP% monitor call to map the
   section page-by-page.


                                    8-12
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   This function of the SMAP% call requires three words of arguments,  as
   follows:

        AC1: source identifier:  JFN,,file section number

        AC2: destination identifier:  fork handle,,process section number

        AC3: flags,,count

   The flags determine access to the destination section, and  the  count
   is  the number of contiguous sections to be mapped.  The count must be
   between 0 and 37 (octal).  The flags are as follows.

        B2(SM%RD)   Allow read access

        B3(SM%WR)   Allow write access

        B4(SM%EX)   Allow execute access

        B18-35      The number of sections to map.  This number  must  be
                    between 1 and 37 (octal).



   8.3.1.2  Mapping Process Sections to  a  Process
   8.3.1.2  Mapping Process Sections to  a  Process - The  SMAP%  monitor
   call  also  maps  sections  from  one  process to another process.  In
   addition, you can map one section of a process to another  section  of
   the  same  process.   The  SMAP% call maps all pages that exist in the
   source section to corresponding pages in the destination section.

   If you map a source section into a  destination  section  with  SM%IND
   set,  SMAP% creates the destination section using an indirect pointer.
   This means that the destination section will contain  all  pages  that
   exist in the source section, and the contents of the destination pages
   will be identical to the contents of the source pages.

   Furthermore, after SMAP% has mapped the destination  section,  changes
   that occur in the source section map cause the same changes to be made
   in the destination section map.  This ensures  that  both  the  source
   section and the destination section contain the same data.

   If SM%IND is not set, SMAP% creates the new  section  using  a  shared
   pointer.  After SMAP% maps the destination section, changes that occur
   in the source section's map do not cause any change in the destination
   section's  map.   Thus  after  a short time the source and destination
   sections might contain different data.

   If you request a shared pointer (SM%IND not set)  to  the  destination
   section,  what  happens  depends on the contents of the source section
   when the SMAP% call executes.  The outcome is one of the following.




                                    8-13
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


        1.  If the source section does not exist, the SMAP% call  creates
            the section.

        2.  If the source is a private section, a mapping to the  private
            section  is  established,  and  the  destination  process  is
            co-owner of the private section.

        3.  If the source section contains a  file  section,  the  source
            section is mapped to the destination section.

        4.  If the source section map is made by  means  of  an  indirect
            section  pointer, SMAP% follows that pointer until the source
            section is found to be nonexistent, a private section,  or  a
            section of a file.

   This SMAP% function requires three words of arguments in  AC1  through
   AC3.

        AC1:   Source identifier:  fork handle,,section number

        AC2:   Destination identifier:  fork handle,,section number

        AC3:   access flags,,the number of contiguous sections to map.

               The number of sections mapped, the  number  in  the  right
               half of AC3, must be between 1 and 37.

               The flags determine access  to  the  destination  section.
               The flags are as follows:

               B2(SM%RD)   Allow read access

               B3(SM%WR)   Allow write access

               B4(SM%EX)   Allow execute access

               B6(SM%IND)  Map the destination section using an  indirect
                           section pointer.  Once the destination section
                           map is created, the indirect  section  pointer
                           causes  the  destination section map to change
                           in  exactly  the  same  way  that  the  source
                           section map changes.

               B18-35      Count of the number of contiguous sections  to
                           be mapped.



   8.3.1.3  Creating Sections
   8.3.1.3  Creating Sections - Before you can use a nonzero  section  of
   memory,  you  must  create  it.   If your program references a nonzero
   section of memory that does  not  exist  (that  is  not  mapped),  the
   instruction that makes the reference fails.


                                    8-14
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   This SMAP% function requires three words of arguments in  AC1  through
   AC3, as follows:

        AC1:   0

        AC2:   destination identifier:  fork handle,,section number

        AC3:   flags,,count

   The flags determine access to the destination section, and  the  count
   is  the  number  of  contiguous  private sections to be created.  This
   count must be between 1 and 37.

   The flags in the left half of AC3 are as follows:

        B2(SM%RD)      Allow read access

        B3(SM%WR)      Allow write access

        B4(SM%EX)      Allow execute access

        B6(SM%IND)     Create the section using an indirect pointer

        B18-35         The number of sections  to  create.   This  number
                       must  be  between  1 and 37.  All created sections
                       are contiguous.



   8.3.1.4  Unmapping a Process Section
   8.3.1.4  Unmapping a Process Section - You can use the  SMAP%  monitor
   call  to  unmap  one  or  more  sections  of memory in a process.  The
   contents of the section are lost.

   If the section contains pages mapped from a file, this  function  does
   not  cause  the  unmapped sections to be written back to the file from
   which they were mapped.  Such pages must be  mapped  to  the  file  by
   means of the PMAP% call.

   This function requires three words of arguments in AC1 through AC3, as
   follows.

        AC1:   -1

        AC2:   Destination identifier:  fork handle,,section number

        AC3:   0,,count
               The count is the  number  of  contiguous  sections  to  be
               unmapped.  This number must be between 1 and 37.






                                    8-15
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   8.3.2  Starting a Process in Any Section
   8.3.2  Starting a Process in Any Section

   You can use most of the  calls  described  in  Chapter  5  to  control
   programs that run in a nonzero section.  The SFORK% monitor call is an
   exception, and will not start a program in a nonzero section.

   The XSFRK% monitor call starts a process in any section of memory.  If
   the  process  is  frozen (by means of the FFORK% call), XSFRK% changes
   the double-word PC, but does not resume execution of the process.   To
   resume the execution of any frozen fork, use the RFORK% call.

   The XSFRK% call requires three words of arguments in AC1 through AC3.

        AC1:   flags,,process handle

               Flags:

                    SF%CON(1B0)    continue a process  that  has  halted.
                                   If  SF%CON  is set, the address in AC3
                                   is ignored and the  process  continues
                                   from where it was halted.

        AC2:   PC flags,,0

        AC3:   address to which this call is to set the PC

   The XSFRK% call also starts a process in section 0.  To do so, set the
   left  half  of AC3 to zero and the right half of AC3 to the address in
   section 0 at which you want the process to start.

   Most other calls consider an address with a zero in the left  half  to
   be  a  local  address.  The XSFRK% call, however, uses the contents of
   AC3 to set the PC.  A PC with zero  in  the  left  half  indicates  an
   address in section 0.



   8.3.3  Setting the Entry Vector in Any Section
   8.3.3  Setting the Entry Vector in Any Section

   The SEVEC% monitor call has room  in  its  argument  ACs  for  only  a
   half-word  address, so it cannot be used to set a process entry vector
   to an address in a nonzero section.  The XSVEC%  call,  on  the  other
   hand,  uses  an AC for the address of the entry vector, and another AC
   for the length of the entry vector, and can specify an entry vector in
   any section of memory.

   The XSVEC% call requires three words of arguments in AC1 through AC3.

        AC1:   process handle
        AC2:   length of the entry vector, or 0
        AC3:   address of the beginning of the entry vector



                                    8-16
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   The length of the entry vector specified in AC2 must be less than 1000
   words.   If  AC2  contains  0, TOPS-20 assumes a default length of two
   words.



   8.3.4  Obtaining Information About a Process
   8.3.4  Obtaining Information About a Process

   Although the monitor calls described in Chapter 5 work in any  section
   of  memory,  several  of  them  can  only return information about the
   section in which they are executed.  The following paragraphs describe
   the  monitor calls you can use to obtain information about any section
   of memory.



   8.3.4.1  Memory  Access  Information
   8.3.4.1  Memory  Access  Information - Several  kinds  of  information
   about  memory are important.  Among them are whether a page or section
   exists (is mapped), and, if so, what the access to a page  or  section
   is.  The RSMAP% and XRMAP% calls provide this information.

   The RSMAP% monitor call reads a section map, and provides  information
   about  the  mapping  of one section of the address space of a process.
   RSMAP% requires one word of arguments in AC1:  a fork  handle  in  the
   left  half,  and  a  section number in the right half.  It returns the
   access information in AC2.

   The map information that RSMAP% returns in AC1 can be the following:

        -1     no current mapping present (the section does not exist)

        0      the mapping is a private section

        n,,m   where n is a fork handle or a JFN,  and  m  is  a  section
               number.  If n is a fork handle, the mapping is an indirect
               or shared mapping to another fork's section.  If  n  is  a
               JFN, the mapping is a shared mapping to a file section.

   The access information bits returned in AC2 are the following:

        B2(SM%RD)   Read access is allowed

        B3(SM%WR)   Write access is allowed

        B4(SM%EX)   Execute access is allowed

        B5(PA%PEX)  The section exists

        B6(SM%IND)  The section was created using an indirect pointer.





                                    8-17
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   Although the RSMAP% call does not  return  information  on  individual
   pages,  the  data it does return is useful in preventing error returns
   from the XRMAP% monitor call.

   The XRMAP% call returns access information on a page or group of pages
   in any section of memory.  Although the RMAP% call returns access data
   about a page in the current section, and you can use the  RSMAP%  call
   in  any  section  of  memory,  you  must use the XRMAP% call to obtain
   information about pages in any section other than the current section.

   The XRMAP% call requires two words of arguments in AC1 and AC2.

        AC1:   process handle,,0

        AC2:   address of the argument block

   The argument block addressed by AC2 has the following format:

          !=======================================================!
          !   Length of the argument block, including this word   !
          !=======================================================!
          ! number of pages in this group on which to return data !
          !-------------------------------------------------------!
          !        number of the first page in this group         !
          !-------------------------------------------------------!
          !       address at which to return the data block       !
          !=======================================================!
          \                           .                           \
          \                           .                           \
          \                           .                           \
          !=======================================================!
          ! number of pages in this group on which to return data !
          !-------------------------------------------------------!
          !        number of the first page in this group         !
          !-------------------------------------------------------!
          !       address at which to return the data block       !
          !=======================================================!

   The number of words in the argument block is three times the number of
   groups  of pages for which you want access data, plus one.  Each group
   of pages requires three arguments:  the number of pages in the  group,
   the  number  of  the first page in the group, and the address at which
   the monitor is to return the access data.

   Note that the address to which the monitor returns data should be in a
   section of memory that already exists.  If it does not exist, the call
   will fail with an illegal memory reference.

   The access information returned for each group of pages  specified  in
   the argument block is the following:




                                    8-18
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


        B2(RM%RD)   read access allowed
        B3(RM%WR)   write access allowed
        B4(RM%EX)   execute access allowed
        B5(RM%PEX)  page exists
        B9(RM%CPY)  copy-on-write access

   For each page specified in the argument block  that  does  not  exist,
   XRMAP%  returns  a -1.  It also returns a zero flag word for each such
   page.  The data block to which XRMAP% returns the  access  information
   should  therefore  contain twice as many words as the number of groups
   of pages about which you want information.

   If you execute an XRMAP% call to obtain information about a page in  a
   nonexistent  section,  the  XRMAP%  call  fails with an illegal memory
   reference.  For this reason it is recommended  to  execute  an  RSMAP%
   call  to  determine  that  the section exists before you use XRMAP% to
   obtain information about any page within that section.



   8.3.4.2  Entry Vector Information
   8.3.4.2  Entry Vector Information - To obtain the entry  vector  of  a
   process  in  any  section  of  memory, use the XGVEC% call.  This call
   returns the length of the entry vector in AC2 and the address  of  the
   entry vector in AC3.

   The XGVEC% call requires one word of argument:  in AC1, the handle  of
   the fork for which you want the entry vector.



   8.3.4.3  Page-Failure Information
   8.3.4.3  Page-Failure Information - A page-fail word, described in the
   _________________________   _________   _________   ______
   DECsystem-10/DECSYSTEM-20   Processor   Reference   Manual,   contains
   information that allows a program to determine the  cause  of  a  page
   trap  and  the  address of the instruction that caused the trap.  This
   information allows a program to correct the  cause  of  the  page-fail
   trap.  Once the program has corrected the cause of the page-fail trap,
   the program can continue execution.

   The XGTPW% call obtains the page-fail word  from  the  monitor's  data
   base,  and  returns  it  to  the calling program's address space.  The
   XGTRP% call requires two words of arguments in AC1 and AC2.

        AC1:   process handle

        AC2:   address of the block in which to return data



   8.3.5  Program Data Vectors
   8.3.5  Program Data Vectors

   Program Data Vectors (PDVs) are data structures in a process that  are
   known to the monitor by name and location.  They contain information


                                    8-19
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   about the program segments within a process.  The PDV is  a  block  of
   data  that LINK writes into memory when loading and linking a program.
   The PDV resides in memory as a part of the program, and  starts  at  a
   program  data  vector  address  (PDVA).   PDVs  are used to allow user
   programs to obtain information about other programs that can be mapped
   into  a  process.   PDVs and PDVAs are manipulated by using the PDVOP%
                                _______ _______  _____  _________  ______
   monitor call.  (Refer to the TOPS-20 Monitor  Calls  Reference  Manual
   for  a  complete  description  of the PDVOP% monitor call.) The PDVOP%
   monitor call can be used to obtain information about  an  execute-only
   process.

   Certain words in the PDV (for example,  .PVNAM)  point  to  blocks  of
   information.   These  words  are  in  either  IFIW or EFIW format (see
   Sections 8.2.3.1 and 8.2.3.2) except that they  cannot  use  indexing,
   and  any  indirect  chain  pointed to by the word cannot go through an
   accumulator.  This allows a program to find the  address  of  a  block
   pointed  to  by a PDV word by simply using an XMOVEI instruction.  For
   example,

        XMOVEI         AC1,@.PVNAM(AC2)

   puts into AC1 the global address of the name of the PDV whose PDVA  is
   in AC2.



   8.3.5.1  Manipulating PDV Addresses
   8.3.5.1  Manipulating PDV Addresses - For  the  process  specified  in
   word  .POPHD  of the argument block, the .POGET function of the PDVOP%
   monitor call returns all PDVAs within the range of addresses specified
   in   words  .POADR  and  .POADE  of  the  argument  block.   (See  the
                                                  _______  _______  _____
   description of the PDVOP% monitor call in the  TOPS-20  Monitor  Calls
   _________  ______
   Reference  Manual  for  the format of the argument block.) The address
   range supplied by words .POADR and .POADE determines which  PDVAs  are
   affected by any given call.

   The .POADD  function  of  the  PDVOP%  monitor  call  adds  the  PDVAs
   specified  in  the  data  block  to  the  system's  data  base for the
   specified process.  The PDVAs must be in ascending  order  within  the
   data block.

   The .POREM function of the PDVOP% monitor call removes a set of  PDVAs
   from  the system's data base for the specified process.  Those removed
   are the ones within the range specified by words .POADR and .POADE  of
   the argument block.



   8.3.5.2  PDV Names
   8.3.5.2  PDV Names - The .PONAM function of the  PDVOP%  monitor  call
   returns  the  ASCIZ  name  of  a  PDV  in  memory.  Word .POADR of the
   argument block must contain a valid PDVA for  the  specified  process.
   The  name  returned is the one to which word .PVNAM of the PDV points.
   The string returned by .PONAM is placed into the data block.


                                    8-20
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   For the specified process, the .POLOC function  returns  in  the  data
   block all the PDVAs of PDVs with the specified name.  The byte pointer
   in AC3 points to  the  PDV  name.   Function  .POLOC  is  affected  by
   .POADR/.POADE words.

   The following rules apply to the assignment of PDV  names.   If  these
   rules  are  followed, it is quite unlikely that two packages that want
   to run in the same process will discover a conflict in PDV names.

        1.  PDV names assigned by DIGITAL will contain the character  "%"
            at  the  end  (or elsewhere).  No PDV names assigned by users
            should contain the "%" character.

        2.  All PDV names containing the character "."  are  reserved  to
            DIGITAL for future use.

        3.  The character "$" is reserved for a special use:   PDV  names
            of  the  form  string1$string2  are  reserved for the special
            class of use named by string1.  Rules 1 and 2 still apply  in
            this case.

   As a general principle, avoid using PDV names that are  insufficiently
   specific; use of such names invites conflicts with other packages.



   8.3.5.3  Version Number
   8.3.5.3  Version Number - The .POVER function of  the  PDVOP%  monitor
   call  returns  in  the  data block the version of a program in memory.
   Word .POADR must contain a valid PDVA for the specified process.   The
   version returned is the one that word .PVVER of the PDV contains.

   For more information on program data vectors,  including  explanations
   of  the  static  memory map (pointed to by word .PVMEM) and the symbol
                                                            _______  ____
   table vector (pointed to by word .PVSYM), refer to  the  TOPS-20  LINK
   _________ ______
   Reference Manual.



   8.4  MODIFYING EXISTING PROGRAMS
   8.4  MODIFYING EXISTING PROGRAMS

   Existing programs can be modified to run in  any  section  of  memory,
   including  both  section  0 and all other sections.  The sections that
   follow discuss the changes that must be made to an existing program so
   that it runs in a single nonzero section.



   8.4.1  Data Structures
   8.4.1  Data Structures

   Stacks, tables, and other data structures used in the past have  often
   contained  words  with an address in the right half and a count in the
   left half.  The count  could  be  positive  or  negative  because  all


                                    8-21
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


   programs  ran  only in section 0, and when the contents of a word were
   evaluated for Effective Address calculation or address use in  section
   0, only the right half was considered.

   In all other sections, the entire word is considered to be an address.
   If  the  left  half  of the word is negative, the left half is ignored
   when the address is evaluated, and the address is local.  Thus  for  a
   word  to  contain an address in the right half and a count in the left
   half, the count must be negative.



   8.4.1.1  Index Words
   8.4.1.1  Index Words - Be sure the left halves of index words  contain
   a  nonpositive quantity.  To use the left half of an index register to
   hold a count, the count must be negative.  If the left half is unused,
   it  must be zero so that the effective address is a local address.  If
   the left half contains a positive number, the indexed address will  be
   global.



   8.4.1.2  Indirect Words
   8.4.1.2  Indirect Words - To be  sure  that  an  indirect  word  in  a
   nonzero  section  is evaluated as a local address, always set bit 0 of
   the indirect word.  Argument lists that  produce  local  addresses  in
   section 0, for example, will produce local addresses in any section if
   bit 0 is set.



   8.4.1.3  Stack Pointers
   8.4.1.3  Stack Pointers - As mentioned above, the left halves of stack
   pointers  must  contain  zero  or  a  negative number to produce local
   addresses.  A negative number in the left half is considered to  be  a
   count.   A  positive  number  in  the  left half is considered to be a
   section number.



   8.5  WRITING MULTISECTION PROGRAMS
   8.5  WRITING MULTISECTION PROGRAMS

   Multisection programs, programs that use  more  than  one  section  of
   memory,  are  similar  to  single-section programs that run in nonzero
   sections.  They allow  you  to  place  tables  needed  for  processing
   interrupts in any section of memory (See Chapter 4), to use very large
   arrays, and to write modules of code that can  be  dynamically  mapped
   into a section of memory and executed.

   In a single-section program, local addresses  and  byte  pointers  are
   sufficient to specify any word or byte in the program's address space.
   In a multisection program, local addresses and  byte  pointers  cannot
   specify any word or byte in the program's address space.  Most monitor
   calls use only one AC per argument, so passing  two-word  global  byte
   pointers is not possible.  Thus, it is necessary to:


                                    8-22
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


         o  keep monitor call arguments in the same section of memory  as
            the code making the call, or

         o  use global arguments, or

         o  use the global form of the monitor call.

   In many multisection programs it is not  necessary  to  keep  all  the
   arguments  required  by  a  call  in the same section as the code that
   makes the call.  Global arguments are required, and they take  several
                             _______ _______ _____ _________ ______
   forms.   Chapter 1 of the TOPS-20 Monitor Calls Reference Manual gives
   details on the use of these arguments.

   The following program computes a file checksum by XORing the words  in
   all  file pages.  The program is loaded into section 0 and maps itself
   into section 1.  It then jumps into section 1 to access the file  data
   loaded into section 15.

           TITLE CHKSUM - COMPUTE A FILE CHECKSUM
           SEARCH MONSYM           ;STANDARD UNIVERSAL FILES
           SEARCH MACSYM
           .REQUIRE SYS:MACREL     ;GET JSERR SUPPORT ROUTINES

           STDAC.                  ;DEFINE STANDARD ACS

   ; PROGRAM CONSTANTS

           PDLSIZ==100             ;SIZE OF STACK
           CODSEC==1               ;SECTION TO MAP CODE INTO
           DATSEC==15              ;SECTION TO MAP FILE DATA INTO
           DATPAG==100             ;PAGE WITHIN DATSEC FOR FILE DATA
           PAGSIZ==1000            ;SIZE OF A PAGE

   CHKSUM: RESET%                  ;RESET THE WORLD
           MOVE P,[IOWD PDLSIZ,PDL]
           MOVE T1,[.FHSLF,,0]     ;MAP THIS FORKS SECTION 0
           MOVE T2,[.FHSLF,,CODSEC] ;TO EXTENDED CODE SECTION
           MOVX T3,SM%RD!SM%WR!SM%EX!SM%IND+1 
                                   ;INDIRECT POINTER RD,WR,EX 1 SECTION
           SMAP%
            EJSHLT                 ;UNEXPECTED FATAL ERROR
   GETFIL: SETZM FILJFN            ;SAY NO FILE SEEN
           TMSG <
   ENTER FILE SPEC TO CHECKSUM: >  ;PROMPT USER FOR FILE
           MOVX T1,GJ%SHT!GJ%OLD!GJ%FNS ;OLD FILE
           MOVE T2,[.PRIIN,,.PRIOU] ;READ FILE SPEC FROM TERMINAL
           GTJFN%                  ;GET FILE SPEC
            ERJMPR BADFIL          ;CANNOT GET FILE TELL USER
           MOVEM T1,FILJFN         ;SAVE FILE JFN
           MOVX T2,FLD(^D36,OF%BSZ)!OF%RD 
                                   ;REQUEST READ ACCESS AND 36 BIT BYTES
           OPENF%                  ;OPEN THE FILE


                                    8-23
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


            ERJMPR BADFIL          ;CANNOT OPEN FILE TELL USER

           XJRST [CODSEC,,DOCHKS]  ;ENTER EXTENDED SECTION 
                                   ;AND DO CHECKSUM

   BADFIL: JSERR                   ;PRINT ERROR MESSAGE
           SKIPE T1,FILJFN         ;IS THERE A JFN
           RLJFN%                  ;YES. RELEASE IT
            EJSERR                 ;PRINT ERROR IF ANY
           JRST GETFIL             ;AND TRY TO GET FILE AGAIN

   ; THE FOLLOWING CODE RUNS IN A NONZERO SECTION AND 
   ; DOES A CHECKSUM OF THE FILE STORED IN FILJFN

   DOCHKS: SETZB Q1,Q2             ;Q1 HOLDS THE CHECKSUM. 
                                   ;INITIALLY ZERO
                                   ;Q2 IS THE CURRENT FILE PAGE NUMBER
   CHKLOP: MOVE T1,Q2              ;GET FILE PAGE NUMBER
           HRL T1,FILJFN           ;AND FILE JFN
           FFUFP%                  ;FIND FIRST USED PAGE
            ERJMPR NOPAGE          ;CAN'T GO ANALYZE ERROR
           HRRZ Q2,T1              ;REMEMBER CURRENT PAGE NUMBER
           AOS Q2                  ;USE NEXT HIGHER PAGE NEXT TIME 
           MOVE T2,[<DATSEC>B26+DATPAG] ;THROUGH LOOP TO DATA PAGE 
           HRLI T2,.FHSLF          ;IN DATA SECTION OF THIS FORK
           MOVX T3,PM%RD           ;READ ACCESS
           PMAP%                   ;MAP THE FILE PAGE
            EJSHLT                 ;UNEXPECTED FATAL ERROR
           HRLI T1,DATSEC          ;T1 IS INDEX INTO DATA PAGE. 
           HRRI T1,DATPAG*PAGSIZ   ;SETUP SECTION AND PAGE ADDRESS
           MOVEI T2,PAGSIZ         ;T2 COUNTS THE WORDS IN A PAGE

   ; THE FOLLOWING LOOP DOES THE CHECKSUM FOR A PAGE

   XORLOP: XOR Q1,(T1)             ;CHECKSUM THIS WORD
           AOS T1                  ;STEP TO NEXT WORD
           SOJG T2,XORLOP          ;DO THE WHOLE PAGE

           SETO T1,                ;UNMAP THE FILE PAGE
           MOVE T2,[<DATSEC>B26+DATPAG] ;TO DATA PAGE IN DATA 
           HRLI T2,.FHSLF          ;SECTION OF THIS FORK
           MOVX T3,PM%RD
           PMAP%
            EJSHLT                 ;UNEXPECTED FATAL ERROR
           JRST CHKLOP             ;LOOP FOR MORE PAGES

   ; HERE WHEN FFUFP% FAILS

   NOPAGE: CAIE T1,FFUFX3          ;NO USED PAGE FOUND?
           JSHLT                   ;NO. UNEXPECTED FATAL ERROR
           
   ; PRINT THE CHECKSUM AND QUIT


                                    8-24
                         USING EXTENDED ADDRESSING
                         USING EXTENDED ADDRESSING


           TMSG <
   THE FILE CHECKSUM IS: >
           MOVX T1,.PRIOU          ;PRINT IT ON THE TERMINAL
           MOVE T2,Q1              ;GET THE CHECKSUM
           MOVX T3,NO%MAG!FLD(^D8,NO%RDX)  ;UNSIGNED OCTAL NUMBER
           NOUT%
            EJSHLT                 ;UNEXPECTED FATAL ERROR

           MOVE T1,FILJFN          ;GET FILE AGAIN
           CLOSF%                  ;CLOSE IT
            EJSHLT                 ;UNEXPECTED FATAL ERROR

           HALTF%                  ;STOP PROGRAM
           XJRST [CHKSUM]          ;JUMP BACK TO SECTION 0 AND 
                                   ;START OVER IF USER CONTINUES

   ; STORAGE

   PDL:    BLOCK PDLSIZ            ;STACK
   FILJFN: BLOCK 1                 ;FILE JFN

           END CHKSUM
































                                    8-25
                                        


                                   INDEX



               -A-
               -A-                     Arguments (Cont.)
                                         GTJFN% short form, 3-4
   AC, 1-2                               IIC%, 5-19
     global reference, 8-7               JFNS%, 3-33
     references, 8-6                     JSYS, 1-2, 1-3
   Access                                monitor calls, 1-3
     copy-on-write, 5-5                  MRECV%, 7-9
     file, 3-2, 3-16                     MSEND%, 7-7
     file append, 3-16                   MUTIL%, 7-15
     file frozen, 3-16                   OPENF%, 3-16
     file read, 3-16                     PMAP%, 3-26, 3-28, 5-14
     file restricted, 3-16               PMAP% JSYS, 8-15
     file thawed, 3-16                   RDTTY%, 2-9
     file unrestricted, 3-16             SFORK%, 5-15
     file write, 3-16                    SIN%, 3-22
     page, 5-5                           SIR%, 4-6
   Access bits                           SMAP%, 3-29, 8-13, 8-14, 8-15
     OPENF%, 3-17                        SOUT%, 3-23
     PMAP%, 3-26                         XGTPW%, 8-19
   Accumulator (AC), 1-2                 XRIR%, 4-15
   Accumulators, 1-3                     XRMAP% JSYS, 8-18
     global reference, 8-7               XSFRK%, 8-16
     hardware, 8-6                       XSIR%, 4-7
     references, 8-6                     XSVEC% JSYS, 8-16
   Address                             ASCII strings, 2-1, 3-21
     global, 8-1, 8-6                  ASCIZ pseudo-op, 1-6
     local, 8-4, 8-6                   ASCIZ strings, 2-1, 3-21
   Address space, 8-1, 8-2             ATI% JSYS, 4-13
     process, 1-6, 5-1, 5-11
                                                   -B-
   Addressing                                      -B-
     extended, 8-1
   Addressing ACs, 8-2                 BIN% JSYS, 1-5, 3-21
   Addressing memory, 8-2                example, 1-5
   ADJSP instruction, 2-2, 8-10        Block
   AIC% JSYS, 4-9, 4-17, 5-4             packet data, 7-2
   AOBJN pointer, 8-4                    packet descriptor, 7-2
   Argument block                      BLT instruction, 8-9
     DEQ%, 6-14                        BOUT% JSYS, 3-21
     ENQ%, 6-8                         Byte, 2-1, 3-1
     ENQC%, 6-15                         reading a, 2-8
     GTJFN% long form, 3-13              transferring, 3-21
   Arguments                             writing a, 2-8
     CFORK%, 5-8                       Byte instructions, 8-10
     DEQ%, 6-12                        Byte manipulation instructions,
     DIC%, 4-16                            2-2
     ENQ% JSYS, 6-6                      ADJSP, 2-2
     ENQC%, 6-14                         IBP, 2-2
     GET%, 5-11                          ILDB, 2-2


                                  Index-1
                                        


   Byte pointer, 8-10                  Deferred mode
     global, 8-10                        terminal interrupt, 4-14
     local, 8-10                       Deleting inferior process, 5-20
     one-word global, 2-2, 8-10        DEQ% JSYS, 6-2, 6-6, 6-12
     system standard for JSYS, 2-2       argument block, 6-14
     two-word global, 2-2, 8-10          arguments, 6-12
                                         functions, 6-12
               -C-
               -C-                     Descriptor block
                                         packet, 7-2
   Calling sequence                    Designator
     monitor calls, 1-3                  destination, 3-20
   Capability words, 5-11                primary input, 2-2, 3-20
   CFORK% JSYS, 5-4, 5-8, 5-15, 5-19     primary output, 2-2, 3-20
     arguments, 5-8                      source, 3-20
     execution, 5-10                     universal device, 8-11
   Changing sections, 8-2              Destination designator, 3-20
   Channel                             Device designator
     deactivating, 4-16                  universal, 8-11
     panic, 4-5, 4-10, 4-11            DIC% JSYS, 4-16
   Channel assignments                   arguments, 4-16
     software interrupt, 4-4           DIR% JSYS, 4-16
   Channel table (CHNTAB), 4-7         Direct process control, 5-4
   CHNTAB, 4-7                         Disabling interrupt system, 4-16
   CIS% JSYS, 4-17                     DTI% JSYS, 4-17
   Clearing interrupt system, 4-17
                                                   -E-
   CLOSF% JSYS, 3-30                               -E-
     example, 3-31
     execution, 3-31                   Editing functions, 2-9
     flag bits, 3-30                   Effective address, 8-1
   Closing a file, 3-30                Effective address calculation,
   Communication                           8-3, 8-8
     process, 1-6                        example, 8-8
   Communication facility                  indexing, 8-8
     inter-process, 7-1                    indirection, 8-8
   Control bits                          extended, 8-3
     RDTTY%, 2-10                        immediate instructions, 8-8
   Control process, 1-6                  indexing, 8-5
   Copy-on-write access, 5-5             indirection, 8-5
   Counter                               nonzero sections, 8-3
     program, 8-1                      EFIW, 8-6, 8-20
   Creating sections, 8-14             EIR% JSYS, 4-9, 4-11, 4-17, 5-4
                                       EJSERR macro, 1-5
               -D-
               -D-                     EJSHLT macro, 1-5
                                       ENQ quota, 6-3
   Data block                          ENQ% JSYS, 5-4, 6-2, 6-6, 6-17
     packet, 7-2                         argument block, 6-8
   Data transfer, 2-1                    arguments, 6-6
   Data transfers, 3-19                  functions, 6-6
   Deactivating a channel, 4-16        ENQC% JSYS, 5-4, 6-6, 6-14
   Deadly embrace, 6-4, 6-5, 6-19        argument block, 6-15
   Deassigning terminal codes, 4-17      arguments, 6-14
   DEBRK% JSYS, 4-11                     flag bits, 6-15


                                  Index-2
                                        


   ENQUEUE/DEQUEUE (ENQ/DEQ)           File thawed access, 3-16
       facility, 5-4, 6-1              File unrestricted access, 3-16
     use of, 6-6                       File write access, 3-16
   Entry vector, 8-16                  Files, 3-1
     information, 8-19                 Flag bits
   EP. macro, 8-6, 8-7                   CLOSF%, 3-30
   ERCAL symbol, 1-4, 5-15               ENQC%, 6-15
   ERCALR symbol, 1-4                    GTJFN% long form, 3-14
   ERCALS symbol, 1-4, 1-5               GTJFN% short form, 3-5
   ERJMP symbol, 1-4, 5-15               MRECV%, 7-10
   ERJMPR symbol, 1-4, 2-13              MSEND%, 7-8
   ERJMPS symbol, 1-4                    SMAP%, 3-29
   Error returns                       Flags
     monitor calls, 1-4                  packet descriptor block, 7-3
   ERSTR% JSYS, 1-5                    Format
   Execute-only process, 8-19            extended instruction, 8-3
   Extended addressing, 8-1, 8-3         IPCF packet, 7-2
     examples, 8-7                       <SYSTEM>INFO requests, 7-13
     using monitor calls with, 8-11      <SYSTEM>INFO responses, 7-14
   Extended format indirect word       Format options
       (EFIW), 8-6                       JFNS%, 3-34
   Extended instruction format, 8-3      NOUT%, 2-6
   Extended page number, 8-11          Functions
                                         DEQ%, 6-12
               -F-
               -F-                       ENQ%, 6-6
                                         MUTIL%, 7-15
   FH%EPN, 8-11                          PDVOP%, 8-20
   File                                  RDTTY%, 2-9
     closing a, 3-30
                                                   -G-
     examples, 3-40                                -G-
     opening a, 3-16
     pointer, 3-20                     GET% JSYS, 5-11, 5-14
     reading from                        arguments, 5-11
       summary, 3-40                   GETER% JSYS, 1-5
     referencing, 3-3                  GFIWM macro, 8-6
     sharing, 3-2, 6-1                 GFRKS% JSYS, 5-7
     writing to                        Global address, 8-1, 8-4, 8-6
       summary, 3-40                   Global byte pointer, 8-10
   File access, 3-2, 3-16              Global stack, 8-10
     codes, 3-2                        GNJFN% JSYS, 3-9, 3-36
   File append access, 3-16              bits returned, 3-37
   File frozen access, 3-16            GTJFN% JSYS, 3-3, 3-4
   File identifier, 3-2                  arguments
   File page mapping, 3-26                 long form, 3-12
   File pointer, 3-20                      short form, 3-4
   File read access, 3-16                bits returned, 3-10
   File restricted access, 3-16          execution, 3-9, 3-14
   File section                          flag bits
     mapping, 8-12                         long form, 3-14
   File section mapping, 3-28              short form, 3-5
   File specification, 3-3               long form, 3-4, 3-12
     standard, 3-3                         argument block, 3-13


                                  Index-3
                                        


   GTJFN% JSYS (Cont.)                 Input
     short form, 3-4                     terminal, 2-1
       examples, 3-11                  Input designator
     summary, 3-15                       primary, 2-2
   GTSTS% JSYS, 3-31                   Instruction format
     bits returned, 3-31                 extended, 8-3
                                       Instruction format indirect word
               -H-
               -H-                         (IFIW), 8-5
                                       Instructions
   HALTF% JSYS, 2-8, 5-17                byte, 8-10
     example, 2-7                        stack, 8-10
   Handle section, 8-17                Inter-process communication
   HFORK% JSYS, 5-17                       facility
                                         receive quota, 7-1
               -I-
               -I-                       send quota, 7-1
                                         utility functions, 7-15
   I/O monitor calls, 2-2              Inter-process communication
   IBP instruction, 2-2                    facility (IPCF), 1-6, 5-4,
   Identifier                              7-1
     file, 3-2                         Interrupt, 4-1
   IFIW, 8-5, 8-20                       generating, 4-10
   IIC% JSYS, 4-10, 5-4, 5-19          Interrupt channel assignments,
     arguments, 5-19                       4-4
   ILDB instruction, 2-2               Interrupt channels
   Illegal instruction trap, 1-4         activating, 4-9
   Immediate instructions, 8-8         Interrupt conditions, 4-4
   Immediate mode                      Interrupt deferred mode
     terminal interrupt, 4-14            terminal, 4-14
   Indexing, 8-4, 8-20                 Interrupt dismissing, 4-11
     example, 8-8                      Interrupt immediate mode
   Indirection, 8-5, 8-20                terminal, 4-14
     example, 8-8                      Interrupt processing, 4-10
     extended format indirect word     Interrupt service routines, 4-6
         (EFIW), 8-6                   Interrupt system
     instruction format indirect         clearing, 4-17
         word (IFIW), 8-5                disabling, 4-16
   Inferior process, 1-6, 5-1          Interrupts
     characteristics, 5-8                terminal, 4-12
     communicating with superior,      IPCF, 1-6, 5-4, 7-1
         5-10                            packet data block, 7-2, 7-6,
     creating, 5-8, 5-10                     7-12
     deleting, 5-20                        address, 7-6
     parallel, 5-10                        length, 7-6
     starting, 5-15                      packet descriptor block, 7-2,
     status, 5-17                            7-12
     termination, 5-16                     flags, 7-3
   Information                           receive quota, 7-1
     about process, 8-17                 send quota, 7-1
     entry vector, 8-19                  utility functions, 7-15
     page-failure, 8-19                IPCF packet format, 7-2
   Initialization
     process, 2-8


                                  Index-4
                                        


               -J-
               -J-                     JSYS (Cont.)
                                         OPENF%, 3-2, 3-16
   JFN, 3-1, 3-2                         PBIN%, 2-8, 2-14
   JFNS% JSYS, 3-33                      PBOUT%, 2-8, 2-14
     arguments, 3-33                     PDVOP%, 5-11, 8-19
     format options, 3-34                PMAP%, 3-25, 3-26, 3-27, 3-28,
   Job, 1-7                                  5-11, 5-14, 5-15, 5-19,
   Job file number, 3-1, 3-2                 8-12, 8-15
   Job structure, 1-6                    PSOUT%, 2-3, 2-14
     exapmle, 1-7                        RDTTY%, 2-5, 2-9, 2-12, 2-14
   JRA instruction, 8-10                 RESET%, 2-8, 5-21, 7-5
   JRST instruction, 8-2, 8-9            RFSTS%, 5-4, 5-17
   JSA instruction, 8-10                 RFSTS% long form, 5-17, 5-18
   JSP instruction, 8-10                 RFSTS% short form, 5-17
   JSR instruction, 8-10                 RIN%, 3-24
   JSYS, 1-2                             RIR%, 4-15, 8-11
     AIC%, 4-9, 4-17, 5-4                ROUT%, 3-24
     arguments, 1-2, 1-3                 RSMAP%, 8-17
     ATI%, 4-13                          SAVE%, 5-11
     BIN%, 1-5, 3-21                     SEVEC%, 8-16
     BOUT%, 3-21                         SFORK%, 5-4, 5-15
     CFORK%, 5-4, 5-8, 5-10, 5-15,       SFRKV%, 5-16
         5-19                            SIN%, 3-22
     CIS%, 4-17                          SIR%, 4-6, 4-11, 5-4, 8-11
     CLOSF%, 3-30                        SKPIR%, 4-14
     DEBRK%, 4-11                        SMAP%, 3-28, 8-12
     DEQ%, 6-2, 6-6, 6-12                SOUT%, 3-22, 3-23
     DIC%, 4-16                          SPJFN%, 2-2
     DIR%, 4-16                          SSAVE%, 5-11
     DTI%, 4-17                          STIW%, 4-14
     EIR%, 4-9, 4-11, 4-17, 5-4          WFORK%, 5-4, 5-16
     ENQ%, 5-4, 6-2, 6-6, 6-17           XGTPW%, 8-19
     ENQC%, 5-4, 6-6, 6-14               XGVEC%, 8-19
     error returns, 1-4                  XRIR%, 4-15, 8-12
     ERSTR%, 1-5                         XRMAP%, 8-18
     GET%, 5-11, 5-14                    XSFRK%, 5-16, 8-16
     GETER%, 1-5                         XSIR%, 4-6, 4-11, 4-17, 8-12
     GFRKS%, 5-7                         XSVEC%, 8-16
     GNJFN%, 3-9, 3-36                 JUMP instruction symbols, 1-4
     GTJFN%, 3-3, 3-4, 3-9               ERCAL, 1-4, 5-15
     GTSTS%, 3-31                        ERCALR, 1-4
     HALTF%, 2-8, 5-17                   ERCALS, 1-4, 1-5
     HFORK%, 5-17                        ERJMP, 1-4, 5-15
     I/O, 2-2                            ERJMPR, 1-4, 2-13
     IIC%, 4-10, 5-4, 5-19               ERJMPS, 1-4
     JFNS%, 3-33                       JUMP instructions, 1-4
     KFORK%, 5-4, 5-20
     MRECV%, 5-4, 7-7, 7-9
     MSEND%, 5-4, 7-7, 7-12
                                                   -K-
     MUTIL%, 5-4, 7-15                             -K-
     NIN%, 2-4, 2-13, 2-14
     NOUT%, 2-5, 2-14                  KFORK% JSYS, 5-4, 5-20


                                  Index-5
                                        


               -L-
               -L-                     MRECV% JSYS (Cont.)
                                         execution, 7-11
   Level number                          flagbits, 7-10
     resource, 6-4                       flags returned, 7-11
   LEVTAB, 4-8                         MSEND% JSYS, 5-4, 7-7, 7-12
   LFIWM macro, 8-6                      arguments, 7-7
   LINK, 8-19                            execution, 7-9
   Literals, 2-2                         flag bits, 7-8
   Local address, 8-4, 8-6             Multiple processes, 5-2
   Local byte pointer, 8-10            Multisection programs, 8-22
   Lock                                MUTIL% JSYS, 5-4, 7-15
     resource, 6-1                       arguments, 7-15
   Long form GTJFN%, 3-12                execution, 7-20
   LUUO instructions, 8-9                functions, 7-15
    
               -M-                                 -N-
               -M-                                 -N-
    
   MACSYM, 1-3                         NIN% JSYS, 2-4, 2-13, 2-14
   MACSYM macros, 1-3                    example, 2-7
     EJSERR, 1-5                       NOUT% JSYS, 2-5, 2-14
     EJSHLT, 1-5                         example, 2-6, 2-7
     EP., 8-7                            format options, 2-6
     indirection, 8-6                  Number
       EP., 8-6                          reading a, 2-4
       GFIWM, 8-6                        writing a, 2-5
       LFIWM, 8-6
                                                   -O-
     TMSG, 2-4                                     -O-
   Mapping, 8-12
     file page, 3-26                   One-word global byte pointer, 2-2,
     file section, 3-28                    8-10, 8-11
     file sections to a process,       OPENF% JSYS, 3-2, 3-16, 3-27
         8-12                            access bits, 3-17
     memory, 8-12                        arguments, 3-16
     page, 3-24, 5-14                    examples, 3-19
     process page, 3-27                Opening a file, 3-16
     process section, 8-13             Operation code
     sections, 8-12                      monitor calls, 1-2
   Memory, 8-2                         Output
   Memory sharing, 5-5                   terminal, 2-1
   Messages                            Output designator
     receiving process, 7-7              primary, 2-2
     sending process, 7-7              Ownership, 6-2, 6-17
   Monitor calls, 1-2                    exclusive, 6-2, 6-17
     arguments, 1-2, 1-3                 shared, 6-1, 6-2, 6-17
     calling sequence, 1-3
                                                   -P-
     error returns, 1-4                            -P-
     for processes, 5-7
     I/O, 2-2                          Packet, 7-1, 7-2
     operation code, 1-2                 receiving a, 7-9
   MONSYM, 1-2, 2-3                      sending a, 7-7
   MRECV% JSYS, 5-4, 7-7, 7-9          Packet data block, 7-2, 7-6, 7-12
     arguments, 7-9                      address, 7-6


                                  Index-6
                                        


   Packet data block (Cont.)           Priority level table (LEVTAB),
     length, 7-6                           4-8
   Packet descriptor block, 7-2,       .PRIOU symbol, 2-2, 2-9, 2-14,
       7-12                                3-20
     flags, 7-3                        Process, 1-6, 1-7
   Packet format                         address space, 1-6, 5-11
     IPCF, 7-2                           capabilities, 5-11
   Page, 3-1                             communication, 1-6, 5-3, 5-19
   Page access, 5-5                      control, 1-6, 5-4
   Page mapping, 5-14                    deleting inferior, 5-20
     file, 3-25                          examples, 5-21
   Page sharing, 5-5                     execute-only, 8-19
   Page-failure information, 8-19        handle, 5-5, 5-10
   Panic channel, 4-5, 4-10, 4-11        identifiers, 5-5
   Parallel inferior processes, 5-10     inferior, 1-6, 5-1
   PBIN% JSYS, 2-8, 2-14                 information about, 8-17
   PBOUT% JSYS, 2-8, 2-14                JSYSs for, 5-7
   PC, 5-1, 8-1, 8-2, 8-9                multiple, 5-2
     address, 8-9                        parallel, 5-1
     address fields, 8-2                 starting in any section, 8-16
   PDV, 8-19                             starting inferior, 5-15
     names, 8-20                         status word, 5-17
       rules, 8-20                       structure, 1-6, 5-1
   PDVA, 8-19                            superior, 1-6, 5-1
     manipulating, 8-20                  terminating inferior, 5-16
   PDVOP% JSYS, 5-11, 8-19               use of resources, 6-5
     functions, 8-20                   Process communication, 1-6, 5-3,
   PID, 7-1, 7-5, 7-11                     5-5, 5-19
   PM%EPN, 8-11                          sharing pages, 5-19
   PMAP% JSYS, 3-25, 3-27, 3-28,         software interrupt, 5-4, 5-19
       5-11, 5-14, 5-15, 5-19, 8-12,   Process control, 5-4
       8-15                            Process handle, 5-5
     access bits, 3-26                 Process ID (PID), 7-1, 7-5, 7-11
     arguments, 3-26, 3-28, 5-14,      Process identifiers, 5-5
         8-15                          Process initialization, 2-8
   POINT pseudo-op, 2-1                Process mapping, 3-27
   Pointer                             Process messages
     file, 3-20                          receiving, 7-7
   Pooled resources, 6-11                sending, 7-7
   POP instruction, 8-10               Process relationships, 5-1
   POPJ instruction, 8-9, 8-10         Process section, 3-28
   .PRIIN symbol, 2-2, 2-9, 2-14,        unmapping, 8-15
       3-20                            Process status word, 5-17
   Primary input designator (.PRIIN),  Process structure, 1-6, 5-1
       2-2, 3-20                       Process unmapping, 3-28
   Primary output designator           Program counter, 8-2
       (.PRIOU), 2-2, 3-20               address fields, 8-2
   Printing a string, 2-3              Program counter (PC), 5-1, 8-1,
   Priority level                          8-9
     interrupt, 4-11                     address, 8-9
     software interrupt, 4-4           Program data vector (PDV), 8-19
                                         address (PDVA), 8-19


                                  Index-7
                                        


   Program data vector (PDV) (Cont.)   Resource (Cont.)
     manipulating PDVAs, 8-20            use by process, 6-5
     names, 8-20                       Resource lock, 6-1
       rules, 8-20                     Resource name, 6-4
     program version number, 8-21      Resource ownership, 6-2
   Programs                            RFSTS% JSYS, 5-4, 5-17
     multisection, 8-22                  long form, 5-17, 5-18
   Protection                              status-return block, 5-18
     resource, 6-4                       process status word, 5-17
   Pseudo-ops                            short form, 5-17
     ASCIZ, 1-6                        RIN% JSYS, 3-24
     POINT, 2-1                        RIR% JSYS, 4-15, 8-11
   PSOUT% JSYS, 2-3, 2-14                example, 4-15
     example, 2-7                      ROUT% JSYS, 3-24
   PUSH instruction, 8-10              RSMAP% JSYS, 8-17
   PUSHJ instruction, 8-2, 8-9, 8-10     information returned, 8-17
    
               -Q-
               -Q-
    
                                                   -S-
   Queue, 6-1, 6-2                                 -S-
   Quota, 7-1
     receive, 7-1                      SAVE% JSYS, 5-11
     send, 7-1                         Section
                                         changing, 8-2
               -R-
               -R-                       creating, 8-14
                                         nonzero, 8-14, 8-16
   RDTTY% JSYS, 2-5, 2-9, 2-12, 2-14     zero, 8-3, 8-11
     arguments, 2-9                    Section handle, 8-17
     control bits, 2-10                Section mapping, 8-12
     editing functions, 2-9              file, 3-28
     example, 2-13                       file to process, 8-12
   Reading a byte, 2-8                   process, 8-13
   Reading a number, 2-4               Sections, 8-2
   Reading a string, 2-9               Send quota, 7-1
   Reading from a file                 Sending a packet, 7-7
     summary, 3-40                     SEVEC% JSYS, 8-16
   Receive quota, 7-1                  SFM instruction, 8-9
   Receiving a packet, 7-9             SFORK% JSYS, 5-4, 5-15
   Referencing a file, 3-3               arguments, 5-15
   Releasing a resource, 6-12          SFRKV% JSYS, 5-16
   RESET% JSYS, 2-8, 5-21, 7-5         Sharer groups, 6-17
     example, 2-7                        use of, 6-17, 6-18
   Resource, 6-1                       Sharing files, 3-2, 6-1
     level number, 6-4                 Sharing pages, 5-19
     obtaining information about,      Sharing resources, 6-1, 6-17
         6-14                          Short form GTJFN%, 3-4
     ownership, 6-2, 6-17                examples, 3-11
     pooled, 6-11                      SIN% JSYS, 3-22
     protection, 6-4                     arguments, 3-22
     releasing a, 6-12                 SIR% JSYS, 4-6, 4-11, 5-4, 8-11
     requesting use of, 6-6              arguments, 4-6
     sharing, 6-1, 6-17                SKPIR% JSYS, 4-14


                                  Index-8
                                        


   SMAP% JSYS, 3-28, 8-12              Strings (Cont.)
     arguments, 3-29, 8-13, 8-14,        text, 2-1
         8-15                            transferring, 3-22
     flag bits, 3-29                       example, 3-23
   Software interrupt, 1-6, 4-10,      Structure
       5-19                              process, 1-6
     channel assignments, 4-4          Superior process, 1-6, 5-1
     channels and priorities, 4-4        communicating with inferior,
     disabling, 4-16                         5-10
     dismissing, 4-11                  <SYSTEM>INFO, 7-1, 7-5, 7-6, 7-7,
     example, 4-18                         7-9, 7-12
     panic channel, 4-5, 4-10, 4-11      functions and arguments, 7-13
     priority level, 4-11                requests, 7-12
     priority levels, 4-4                  format, 7-13
     process communication, 5-4          responses, 7-14
     processing, 4-10                  <SYSTEM>INFO responses, 7-15
     service routines, 4-6
                                                   -T-
     tables, 4-6                                   -T-
   Software interrupt system, 1-6,
       4-1, 5-16                       Table
     enabling, 4-9                       channel (CHNTAB), 4-7
     operational sequence, 4-2           priority level (LEVTAB), 4-8
     summary, 4-17                       software interrupt, 4-6
   Source designator, 3-20             Terminal
   SOUT% JSYS, 3-22, 3-23                input, 2-1
     arguments, 3-23                     output, 2-1
   SPJFN% JSYS, 2-2                    Terminal codes
   SSAVE% JSYS, 5-11                     deassigning, 4-17
   Stack                               Terminal interrupts, 4-12
     address, 8-10                       codes, 4-12
     global, 8-10                        deferred mode, 4-14
     pointer, 8-10                       generating, 4-13
     register, 8-10                      immediate mode, 4-14
   Stack instructions, 8-10            Terminating inferior process,
     ADJSP, 8-10                           5-16
     POP, 8-10                         Text strings, 2-1
     POPJ, 8-10                        TMSG macro, 2-4
     PUSH, 8-10                          example, 2-7
     PUSHJ, 8-10                       Transferring bytes, 3-21
   Standard file specification, 3-3    Transferring data, 3-19
   Starting a process, 8-16            Transferring strings, 3-22
   Starting inferior process, 5-15       example, 3-23
   Status word                         Trap
     process, 5-17                       illegal instruction, 1-4
   Status-return block, 5-18           Two-word global byte pointer, 2-2,
   STIW% JSYS, 4-14                        8-10
   String
                                                   -U-
     printing a, 2-3                               -U-
     reading a, 2-9
   Strings                             Universal device designator, 8-11
     ASCII, 2-1, 3-21                  Unmapping
     ASCIZ, 2-1, 3-21                    process page, 3-28


                                  Index-9
                                        


   Unmapping (Cont.)                   XCT instruction, 8-9
     process section, 8-15             XGTPW% JSYS, 8-19
                                         arguments, 8-19
               -V-
               -V-                     XGVEC% JSYS, 8-19
                                       XHLLI instruction, 8-8, 8-9
   Vector                              XJEN instruction, 8-9
     entry, 8-16                       XJRST instruction, 8-2
   Virtual address space, 8-1          XJRSTF instruction, 8-2, 8-9
   Virtual space, 1-6                  XMOVEI instruction, 8-8, 8-20
                                       XPCW instruction, 8-9
               -W-
               -W-                     XRIR% JSYS, 4-15, 8-12
                                         arguments, 4-15
   WFORK% JSYS, 5-4, 5-16              XRMAP% JSYS, 8-18
   Writing a byte, 2-8                   arguments, 8-18
   Writing a number, 2-5               XSFRK% JSYS, 5-16, 8-16
   Writing to a file                     arguments, 8-16
     summary, 3-40                     XSIR% JSYS, 4-6, 4-11, 4-17, 8-12
                                         arguments, 4-7
               -X-
               -X-                     XSVEC% JSYS, 8-16
                                         arguments, 8-16
   XBLT instruction, 8-9

































                                  Index-10
