Google
 

Trailing-Edge - PDP-10 Archives - SRI_NIC_PERM_SRC_1_19910112 - 6-documentation/glxlib.mem
There are 4 other files named glxlib.mem in the archive. Click here to see a list.


                                           Edition: 14 January 1983
                                           Version:  GLXLIB 1(655)












                   T H E  G A L A X Y  L I B R A R Y


                              G L X L I B


   ;
   ;
   ;                COPYRIGHT (c) 1975,1976,1977,1978,1979
   ;                    DIGITAL EQUIPMENT CORPORATION
   ;
   ;     THIS DOCUMENT IS FURNISHED UNDER A LICENSE AND MAY  BE  USED
   ;     AND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE
   ;     AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE.   THIS
   ;     DOCUMENT  OR ANY OTHER COPIES THEREOF MAY NOT BE PROVIDED OR
   ;     OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON.  NO  TITLE  TO
   ;     AND OWNERSHIP OF THE DOCUMENT IS HEREBY TRANSFERRED.
   ;
   ;     THE INFORMATION  IN  THIS  DOCUMENT  IS  SUBJECT  TO  CHANGE
   ;     WITHOUT  NOTICE  AND SHOULD NOT BE CONSTRUED AS A COMMITMENT
   ;     BY DIGITAL EQUIPMENT CORPORATION.
   ;
   ;     DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
   ;     OF  ITS  SOFTWARE  ON  EQUIPMENT  WHICH  IS  NOT SUPPLIED BY
   ;     DIGITAL.


                    T A B L E  O F  C O N T E N T S




   CHAPTER 1       THE GALAXY LIBRARY

           1.1     Introduction . . . . . . . . . . . . . . . . . . . 1-1
           1.2     The GALAXY Library . . . . . . . . . . . . . . . . 1-1
           1.3     The HOST Program . . . . . . . . . . . . . . . . . 1-2
           1.4     System Layout and Environment  . . . . . . . . . . 1-3
           1.4.1     System layout  . . . . . . . . . . . . . . . . . 1-3
           1.4.2     PROLOG . . . . . . . . . . . . . . . . . . . . . 1-4
           1.4.3     Initialization . . . . . . . . . . . . . . . . . 1-5
           1.5     Conventions  . . . . . . . . . . . . . . . . . . . 1-5
           1.5.1     Global Routine Names . . . . . . . . . . . . . . 1-5
           1.5.2     Accumulators . . . . . . . . . . . . . . . . . . 1-6
           1.5.3     Subroutine argument passing conventions  . . . . 1-7
           1.5.4     Subroutine calling conventions . . . . . . . . . 1-7
           1.5.5     SUCCESS/FAILURE testing conventions  . . . . . . 1-7
           1.5.6     Subroutine return mechanisms . . . . . . . . . . 1-8


   CHAPTER 2       MACROS AND PSEUDO-INSTRUCTIONS

           2.1     Field Masks and Constants  . . . . . . . . . . . . 2-2
           2.1.1     Common Field Masks and Constants . . . . . . . . 2-2
           2.1.2     Common Control Characters  . . . . . . . . . . . 2-2
           2.2     FIELD MASK MACROS  . . . . . . . . . . . . . . . . 2-3
           2.3     Conditional assembly macros  . . . . . . . . . . . 2-4
           2.4     Storage allocation macros  . . . . . . . . . . . . 2-4
           2.5     Listing control macros . . . . . . . . . . . . . . 2-4
           2.6     MISCELLANEOUS Macro definitions  . . . . . . . . . 2-5
           2.7     AC Mask PSEUDO-INSTRUCTIONS  . . . . . . . . . . . 2-6
           2.8     Subroutine Call and Return Pseudo-instructions . . 2-7
           2.9     Logical TRUE/FALSE Pseudo-instructions . . . . . . 2-8
           2.10    P-class Pseudo-instructions  . . . . . . . . . . . 2-8
           2.11    Miscellaneous Pseudo-instructions  . . . . . . . . 2-8
           2.12    Data-structure Macros  . . . . . . . . . . . . . . 2-9
           2.12.1    Data Structure Definition Macros . . . . . . . . 2-9
           2.13    Data Structure Pseudo-instructions.  . . . . . .  2-11
           2.14    Macros to build static data structures . . . . .  2-12
           2.15    AC and VARIABLE Save Facilities  . . . . . . . .  2-13
           2.16    NAMED VARIABLE FACILITIES  . . . . . . . . . . .  2-14
           2.16.1    STKVAR <namelist>  . . . . . . . . . . . . . .  2-15
           2.16.2    TRVAR <namelist> . . . . . . . . . . . . . . .  2-16
           2.17    $TEXT Pseudo-instruction . . . . . . . . . . . .  2-17
           2.17.1    Imbedded parameters and Qualifiers . . . . . .  2-18
           2.17.2    Field Justification  . . . . . . . . . . . . .  2-20
           2.17.3    ITEXT  . . . . . . . . . . . . . . . . . . . .  2-20
           2.17.4    Text Output Routine  . . . . . . . . . . . . .  2-21
           2.18    Error processing Pseudo-instructions . . . . . .  2-22
           2.19    Operator message Pseudo-instructions . . . . . .  2-24


           2.20    Interrupt processing pseudo-instructions . . . .  2-26


   CHAPTER 3       GLXLIB ROUTINE DESCRIPTIONS

           3.1     GLXMEM - Memory Management Routines  . . . . . . . 3-2
           3.1.1     Description  . . . . . . . . . . . . . . . . . . 3-2
           3.1.2     Global Routines  . . . . . . . . . . . . . . . . 3-2
           3.1.2.1     M%GPAG . . . . . . . . . . . . . . . . . . . . 3-3
           3.1.2.2     M%ACQP . . . . . . . . . . . . . . . . . . . . 3-3
           3.1.2.3     M%AQNP . . . . . . . . . . . . . . . . . . . . 3-3
           3.1.2.4     M%RPAG . . . . . . . . . . . . . . . . . . . . 3-3
           3.1.2.5     M%RELP . . . . . . . . . . . . . . . . . . . . 3-4
           3.1.2.6     M%RLNP . . . . . . . . . . . . . . . . . . . . 3-4
           3.1.2.7     M%CLNC . . . . . . . . . . . . . . . . . . . . 3-4
           3.1.2.8     M%GMEM . . . . . . . . . . . . . . . . . . . . 3-4
           3.1.2.9     M%RMEM . . . . . . . . . . . . . . . . . . . . 3-5
           3.1.2.10    M%NXPG . . . . . . . . . . . . . . . . . . . . 3-5
           3.1.2.11    M%IPRC . . . . . . . . . . . . . . . . . . . . 3-6
           3.1.2.12    M%IPSN . . . . . . . . . . . . . . . . . . . . 3-6
           3.1.2.13    M%IPRM . . . . . . . . . . . . . . . . . . . . 3-6
           3.2     GLXFIL - Disk File Input/Output Routines . . . . . 3-7
           3.2.1     Description  . . . . . . . . . . . . . . . . . . 3-7
           3.2.2     Global Routines  . . . . . . . . . . . . . . . . 3-7
           3.2.3     File Open Block (FOB)  . . . . . . . . . . . . . 3-8
           3.2.4     File Descriptor (FD) . . . . . . . . . . . . . . 3-9
           3.2.4.1     F%IOPN . . . . . . . . . . . . . . . . . . .  3-10
           3.2.4.2     F%IBYT . . . . . . . . . . . . . . . . . . .  3-10
           3.2.4.3     F%IBUF . . . . . . . . . . . . . . . . . . .  3-10
           3.2.4.4     F%POS  . . . . . . . . . . . . . . . . . . .  3-12
           3.2.4.5     F%REW  . . . . . . . . . . . . . . . . . . .  3-12
           3.2.4.6     F%OOPN . . . . . . . . . . . . . . . . . . .  3-13
           3.2.4.7     F%AOPN . . . . . . . . . . . . . . . . . . .  3-13
           3.2.4.8     F%OBYT . . . . . . . . . . . . . . . . . . .  3-14
           3.2.4.9     F%OBUF . . . . . . . . . . . . . . . . . . .  3-14
           3.2.4.10    F%REL  . . . . . . . . . . . . . . . . . . .  3-15
           3.2.4.11    F%DREL . . . . . . . . . . . . . . . . . . .  3-15
           3.2.4.12    F%RREL . . . . . . . . . . . . . . . . . . .  3-16
           3.2.4.13    F%CHKP . . . . . . . . . . . . . . . . . . .  3-17
           3.2.4.14    F%REN  . . . . . . . . . . . . . . . . . . .  3-18
           3.2.4.15    F%INFO . . . . . . . . . . . . . . . . . . .  3-19
           3.2.4.16    F%FD   . . . . . . . . . . . . . . . . . . .  3-19
           3.2.4.17    F%DEL  . . . . . . . . . . . . . . . . . . .  3-20
           3.3     GLXIPC - IPCF Interface  . . . . . . . . . . . .  3-21
           3.3.1     Purpose  . . . . . . . . . . . . . . . . . . .  3-21
           3.3.2     Global Routines  . . . . . . . . . . . . . . .  3-21
           3.3.2.1     C%RPRM . . . . . . . . . . . . . . . . . . .  3-21
           3.3.2.2     C%RECV . . . . . . . . . . . . . . . . . . .  3-22
           3.3.2.3     C%BRCV . . . . . . . . . . . . . . . . . . .  3-22
           3.3.2.4     C%REL  . . . . . . . . . . . . . . . . . . .  3-22
           3.3.2.5     C%SEND . . . . . . . . . . . . . . . . . . .  3-23
           3.3.2.6     C%INTR . . . . . . . . . . . . . . . . . . .  3-23
           3.4     GLXLNK - Linked-list facilities  . . . . . . . .  3-24


           3.4.1     Description  . . . . . . . . . . . . . . . . .  3-24
           3.4.2     Global Routines  . . . . . . . . . . . . . . .  3-24
           3.4.2.1     L%CLST . . . . . . . . . . . . . . . . . . .  3-25
           3.4.2.2     L%DLST . . . . . . . . . . . . . . . . . . .  3-25
           3.4.2.3     L%CENT . . . . . . . . . . . . . . . . . . .  3-26
           3.4.2.4     L%CBFR . . . . . . . . . . . . . . . . . . .  3-26
           3.4.2.5     L%NEXT . . . . . . . . . . . . . . . . . . .  3-27
           3.4.2.6     L%DENT . . . . . . . . . . . . . . . . . . .  3-27
           3.4.2.7     L%FIRST  . . . . . . . . . . . . . . . . . .  3-28
           3.4.2.8     L%LAST . . . . . . . . . . . . . . . . . . .  3-28
           3.4.2.9     L%PREV . . . . . . . . . . . . . . . . . . .  3-28
           3.4.2.10    L%CURR . . . . . . . . . . . . . . . . . . .  3-29
           3.4.2.11    L%SIZE . . . . . . . . . . . . . . . . . . .  3-29
           3.4.2.12    L%RENT . . . . . . . . . . . . . . . . . . .  3-29
           3.4.2.13    L%PREM . . . . . . . . . . . . . . . . . . .  3-30
           3.4.2.14    L%APOS . . . . . . . . . . . . . . . . . . .  3-30
           3.5     GLXTXT - Formatted ASCII Functions . . . . . . .  3-31
           3.5.1     Description  . . . . . . . . . . . . . . . . .  3-31
           3.5.2     Global Routines  . . . . . . . . . . . . . . .  3-31
           3.5.2.1     T%TEXT . . . . . . . . . . . . . . . . . . .  3-31
           3.5.2.2     T%TTY  . . . . . . . . . . . . . . . . . . .  3-31
           3.6     GLXINT - Common Operating System Functions . . .  3-32
           3.6.1     Description  . . . . . . . . . . . . . . . . .  3-32
           3.6.2     Global Routines  . . . . . . . . . . . . . . .  3-32
           3.6.2.1     I%INIT . . . . . . . . . . . . . . . . . . .  3-33
           3.6.2.2     I%NOW  . . . . . . . . . . . . . . . . . . .  3-33
           3.6.2.3     I%EXIT . . . . . . . . . . . . . . . . . . .  3-34
           3.6.2.4     I%HOST . . . . . . . . . . . . . . . . . . .  3-34
           3.6.2.5     I%SLP  . . . . . . . . . . . . . . . . . . .  3-34
           3.6.2.6     I%TIMR . . . . . . . . . . . . . . . . . . .  3-35
           3.6.2.7     I%IOFF . . . . . . . . . . . . . . . . . . .  3-36
           3.6.2.8     I%ION  . . . . . . . . . . . . . . . . . . .  3-36
           3.6.2.9     I%SOPR . . . . . . . . . . . . . . . . . . .  3-37
           3.6.2.10    I%WTO  . . . . . . . . . . . . . . . . . . .  3-37
           3.6.2.11    I%JINF . . . . . . . . . . . . . . . . . . .  3-37
           3.7     GLXKBD - Keyboard (terminal) routines  . . . . .  3-39
           3.7.1     Description  . . . . . . . . . . . . . . . . .  3-39
           3.7.2     Global Routines  . . . . . . . . . . . . . . .  3-39
           3.8     GLXSCN - COMMAND SCANNING ROUTINES . . . . . . .  3-39
           3.8.1     Description  . . . . . . . . . . . . . . . . .  3-39
           3.8.2     Global Routines  . . . . . . . . . . . . . . .  3-39
           3.8.2.1     S%SIXB . . . . . . . . . . . . . . . . . . .  3-40
           3.8.2.2     S%NUMI . . . . . . . . . . . . . . . . . . .  3-40
           3.8.2.3     S%DATI . . . . . . . . . . . . . . . . . . .  3-41
           3.9     GLXCOM - GLXLIB Utility Module . . . . . . . . .  3-42
           3.9.1     Description  . . . . . . . . . . . . . . . . .  3-42
           3.9.2     Global Routines  . . . . . . . . . . . . . . .  3-42
           3.9.2.1     .SAVE1, .SAVE2, .SAVE3, .SAVE4 . . . . . . .  3-42
           3.9.2.2     .SAVET . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.3     .ZPAGA . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.4     .ZPAGN . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.5     .ZCHNK . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.6     .RETT  . . . . . . . . . . . . . . . . . . .  3-43


           3.9.2.7     .RETF  . . . . . . . . . . . . . . . . . . .  3-44
           3.9.2.8     .POPJ  . . . . . . . . . . . . . . . . . . .  3-44


   CHAPTER 4       DEBUGGING AIDS


   CHAPTER 5       INSIDE THE GALAXY LIBRARY

           5.1     Introduction . . . . . . . . . . . . . . . . . . . 5-1
           5.2     Guidelines for adding new modules  . . . . . . . . 5-1
           5.3     Module Conventions . . . . . . . . . . . . . . . . 5-2
           5.3.1     Symbol Naming Conventions  . . . . . . . . . . . 5-2
           5.3.1.1     Global Subroutines . . . . . . . . . . . . . . 5-2
           5.3.1.2     Local Names  . . . . . . . . . . . . . . . . . 5-2
           5.3.2     Error Conditions . . . . . . . . . . . . . . . . 5-2
           5.4     Physical Layout of a GLXLIB Module . . . . . . . . 5-3
           5.4.1     Overview of Module layout  . . . . . . . . . . . 5-3
           5.4.1.1     Title Page . . . . . . . . . . . . . . . . . . 5-4
           5.4.1.2     Table of Contents  . . . . . . . . . . . . . . 5-4
           5.4.1.3     Revision History . . . . . . . . . . . . . . . 5-5
           5.4.1.4     Module-wide Storage  . . . . . . . . . . . . . 5-5
           5.4.1.5     Global Routines  . . . . . . . . . . . . . . . 5-6
           5.4.1.6     Local Routines . . . . . . . . . . . . . . . . 5-6


   CHAPTER 6       GALAXY LINE AND PAGE CONVENTIONS

           6.1     Introduction . . . . . . . . . . . . . . . . . . . 6-1
           6.2     Instruction format . . . . . . . . . . . . . . . . 6-1
           6.2.1     Tags . . . . . . . . . . . . . . . . . . . . . . 6-1
           6.2.2     Operator . . . . . . . . . . . . . . . . . . . . 6-2
           6.2.3     Accumulator field  . . . . . . . . . . . . . . . 6-3
           6.2.4     Address field  . . . . . . . . . . . . . . . . . 6-3
           6.2.5     Comment field  . . . . . . . . . . . . . . . . . 6-3
           6.3     Macro Calls  . . . . . . . . . . . . . . . . . . . 6-4


   APPENDIX A      GALAXY LIBRARY ERROR CODES


   APPENDIX B      GLXLIB STOPCODES


   APPENDIX C      PARSER MODULE (OPRPAR)

           C.1     Function specific macros . . . . . . . . . . . . . C-1
           C.2     Optional arguments . . . . . . . . . . . . . . . . C-2
           C.3     Key and switch table macros  . . . . . . . . . . . C-4
           C.4     Initialization . . . . . . . . . . . . . . . . . . C-5
           C.4.1     P$INIT . . . . . . . . . . . . . . . . . . . . . C-5
           C.4.2     P$STAK . . . . . . . . . . . . . . . . . . . . . C-5
           C.4.3     P$SETU . . . . . . . . . . . . . . . . . . . . . C-5


           C.4.4     P$HELP . . . . . . . . . . . . . . . . . . . . . C-6
           C.4.5     P$CURR . . . . . . . . . . . . . . . . . . . . . C-6
           C.4.6     P$PREV . . . . . . . . . . . . . . . . . . . . . C-6
           C.4.7     P$NEXT . . . . . . . . . . . . . . . . . . . . . C-6
           C.4.8     P$NFLD . . . . . . . . . . . . . . . . . . . . . C-7
           C.5     Function specific argument fetching routines . . . C-7
           C.5.1     P$CFM  . . . . . . . . . . . . . . . . . . . . . C-7
           C.5.2     P$COMMA  . . . . . . . . . . . . . . . . . . . . C-7
           C.5.3     P$KEYW . . . . . . . . . . . . . . . . . . . . . C-7
           C.5.4     P$SWIT . . . . . . . . . . . . . . . . . . . . . C-8
           C.5.5     P$USER . . . . . . . . . . . . . . . . . . . . . C-8
           C.5.6     P$FLOT . . . . . . . . . . . . . . . . . . . . . C-8
           C.5.7     P$DIR  . . . . . . . . . . . . . . . . . . . . . C-8
           C.5.8     P$TIME . . . . . . . . . . . . . . . . . . . . . C-9
           C.5.9     P$NUM  . . . . . . . . . . . . . . . . . . . . . C-9
           C.5.10    P$FILE, P$IFIL and P$OFIL  . . . . . . . . . . . C-9
           C.5.11    P$FLD  . . . . . . . . . . . . . . . . . . . . . C-9
           C.5.12    P$TOK  . . . . . . . . . . . . . . . . . . . .  C-10
           C.5.13    P$NODE . . . . . . . . . . . . . . . . . . . .  C-10
           C.5.14    P$SIXF . . . . . . . . . . . . . . . . . . . .  C-10
           C.5.15    P$RNGE . . . . . . . . . . . . . . . . . . . .  C-10
           C.5.16    P$TEXT . . . . . . . . . . . . . . . . . . . .  C-11
           C.5.17    P$DEV  . . . . . . . . . . . . . . . . . . . .  C-11
           C.5.18    P$QSTR . . . . . . . . . . . . . . . . . . . .  C-11
           C.5.19    P$UQSTR  . . . . . . . . . . . . . . . . . . .  C-11
           C.5.20    P$ACCT . . . . . . . . . . . . . . . . . . . .  C-12
           C.6     Miscellaneous Parser routines  . . . . . . . . .  C-12
           C.6.1     P$NPRO . . . . . . . . . . . . . . . . . . . .  C-12
           C.6.2     P$GPDB . . . . . . . . . . . . . . . . . . . .  C-12
           C.6.3     P$PNXT . . . . . . . . . . . . . . . . . . . .  C-12
           C.6.4     P$PERR . . . . . . . . . . . . . . . . . . . .  C-13
           C.6.5     P$PDEF . . . . . . . . . . . . . . . . . . . .  C-13
           C.6.6     P$PACT . . . . . . . . . . . . . . . . . . . .  C-13
           C.6.7     P$INTR . . . . . . . . . . . . . . . . . . . .  C-13
           C.6.8     P$TINT . . . . . . . . . . . . . . . . . . . .  C-14
           C.7     Parser data structure definitions  . . . . . . .  C-14
           C.7.1     Parser Argument block description  . . . . . .  C-14
           C.7.2     Parser return argument block description . . .  C-15
           C.7.3     PDB data structure definition  . . . . . . . .  C-16
           C.7.4     ACTION, DEFAULT, and ERROR routine data block   C-17











                                 CHAPTER 1

                             THE GALAXY LIBRARY



   1.1  Introduction

   The first four chapters of this document are intended for  people  who
   will  be  using  the GALAXY library.  Chapter 5 is intended for people
   doing development and/or maintainance of the library itself.



   1.2  The GALAXY Library

   The purpose of The GALAXY Library is to provide  a  set  of  "building
   blocks"  for the GALAXY system which are called in an operating system
   independent manner.

   The library consists of a set  of  individual  modules.   Each  module
   contains  a  set of global routines for interfacing with the operating
   system (or  other  processes)  to  provide  a  complete  facility  for
   performing  a  given  function  such  as  reading and writing a files,
   communicating via IPCF, etc.

   The library is designed in such a way that, except in the  case  of  a
   radical  change  in  the  library,  programs using the library will be
   completely insensitive to new versions of the  library.   The  program
   will not need to be re-coded, re-assembled, or re-linked.

   ***more***













                                    1-1
   THE GALAXY LIBRARY


   1.3  The HOST Program

   The GALAXY library is built to run as a subroutine  package  (in  some
   sense  a  run-time  system)  for a "host" program.  Use of the library
   places very few restrictions on the way  the  host  is  written  hence
   making it usable by a number of different types of programs.

   The major restrictions on the host program are:

         o  The memory layout described in the following section.

         o  Programs using the library  must  use  the  library's  memory
            manager to acquire and return memory.

         o  Library  routines  (unless  specifically  documented  to  the
            contrary) may not be called at interrupt level.

         o  *****others*****

   In most cases, using one facility of the library does not  imply  that
   all  facilities  of  the library must be used if they are needed.  For
   example, a program can use the library for reading and  writing  files
   and  also  contain its own code for using IPCF if the library routines
   are not sufficient for the specific application.






























                                    1-2
                                                       THE GALAXY LIBRARY


   1.4  System Layout and Environment

   1.4.1  System layout

   The host program using GLXLIB is loaded with a small routine,  GLXINI,
   which  obtains  the library at runtime.  Because the library starts at
   location 400000, the host program code must fit  between  locations  0
   and  377777.   The  library  code  starts  at location 400000, and the
   library's impure storage has been  gathered  together  and  starts  at
   location  600000.  The remaining memory (signified by "/ / ..." in the
   following drawing) is available to  the  memory  manager  for  runtime
   requests for memory from both the host program and the various library
   modules.


           !=======================================================!
         0 !                     host program                      !
           !                                                       !
           !-------------------------------------------------------!
           !                  / / / / / / / / / /                  !
           !                  / / / / / / / / / /                  !
           !-------------------------------------------------------!
    400000 !                  GLXLIB library code                  !
           !                                                       !
           !-------------------------------------------------------!
           !                  / / / / / / / / / /                  !
           !                  / / / / / / / / / /                  !
           !-------------------------------------------------------!
    600000 !                  GLXLIB library data                  !
           !                                                       !
           !-------------------------------------------------------!
           !                  / / / / / / / / / /                  !
           !                  / / / / / / / / / /                  !
           !=======================================================!



   The library is mapped into the program's  address  space  at  runtime.
   The  following  places  are  searched for the library in the following
   order:

         o  The same  device  and  directory  as  the  host  program  was
            obtained from.

         o  Default device and directory (i.e.  whatever the system fills
            in when only the filename is specified).

         o  Device SYS:  with no directory specified.

   If the search fails in all places, the  following  is  typed  and  the
   program exits:

                 ?GLXINI - Unable to obtain run-time system

                                    1-3
   THE GALAXY LIBRARY


   1.4.2  PROLOG

   All host programs must be assembled  using  a  version  of  GLXMAC.UNV
   which is compatible with that used to build the library.  At run-time,
   a check is made to insure that this is  true.   The  correct  assembly
   sequence is:

             SEARCH GLXMAC
             PROLOG (FOO)

   where FOO is the name of the host program.  This accomplishes  several
   things:

         o  GLXMAC symbols and Macro Definitions are made available

         o  Either UUOSYM or MONSYM  is  searched  depending  on  whether
            GLXMAC was built for TOPS-10 or TOPS-20.

         o  The modules name  in  SIXBIT  is  remembered  as  the  symbol
            '%%.MOD'.   This  is  used  by  the  $STOP  $FATAL  and $WARN
            pseudo-instructions.

         o  The entry points to the GLXLIB routines are defined  so  that
            they  may  be  called  from  the host program.  GLXLIB uses a
            dispatch vector with an entry for  each  routine.   For  each
            library routine the host program gets a symbol defined.  This
            symbol has the same name as the routine, but is  actually  an
            absolute  symbol  equal  to the origin of the dispatch vector
            plus the offset to this entry.  The entry in  the  vector  in
            turn  contains  a  jump  to the real routine.  This mechanism
            allows the library to change  without  invalidating  existing
            programs.

         o  It  generates  an  internal  load  request  for  the   GLXINI
            bootstrap module and declares I%INIT to be external.

         o  Correctly defines the $DATA and  $GDATA  macros  for  storage
            allocation.
















                                    1-4
                                                       THE GALAXY LIBRARY


   1.4.3  Initialization

   As previously mentioned, the host module must be loaded with  a  small
   bootstrap  routine  which  gets  and  initializes  the  library.  This
   module, GLXINI, contains a single entry point, I%INIT, which  uses  an
   initialization  block  (IB)  supplied by the host program.  This block
   described in Chapter 3 in the section on I%INIT is used to control the
   library initialization.

   It should be stressed that initialization must take place  before  any
   other library routines are called.

   An example call to initialize the library using the default parameters
   would be.


   START:  RESET                   ;Always
           MOVE    P,[stack ptr]   ;Setup pushdown list
           SETZB   S1,S2           ;Do default initialization
           $CALL   I%INIT          ;Initialize the library
           .....                   ;Always 



   1.5  Conventions

   1.5.1  Global Routine Names

   All global subroutines in the GALAXY library have names of the form:

           x%yyyy

   where 'x' describes the module containing the routine (e.g.   "C"  for
   GLXIPC,  the  IPCF  handler,  see  chapter  3 for a complete list) and
   'yyyy' is a mnemonic for the routine's function.

   All the global routine names are defined in GLXMAC as absolute offsets
   into  the GLXLIB 'entry vector', therefore no GLXLIB subroutine should
   be declared EXTERNAL (or followed by '##').















                                    1-5
   THE GALAXY LIBRARY


   1.5.2  Accumulators

   The GALAXY library pre-defines the names (and to some extent the  use)
   of  12  of  the 16 accumulators available to the program.  The sixteen
   defined accumulators are broken up into 6 groups as follows:

            TF      TRUE/FALSE indicator            (AC0)

            TF  is  used  to  indicate  the  success  or  failure  of   a
            subroutine.   Refer to section 1.5.5 for a description of its
            use.

            S1-S2   SCRATCH accumulators            (AC1-AC2)

            S1 and S2 may be used for any reason without being saved.  In
            general,  it  should  be  assumed  that  all subroutine calls
            change the contents of these accumulators.

            S1 and S2 are also used to pass and  return  arguments.   See
            section 1.5.3 for a description argument passing.

            T1-T4   TEMPORARY accumulators          (AC3-AC6)

            T1 thru T4 are similar to  the  scratch  accumulators  except
            that  they  are  preserved  across  all  GLXLIB routines.  In
            general, they should be assumed to be destroyed when  calling
            any routine not in the library.

            P1-P4   PRESERVED accumulators          (AC7-AC12)

            P1 thru P4 are guaranteed to be preserved in all cases across
            all subroutine calls.  No routine may use these without first
            preserving them.

                    RESERVED accumulators           (AC13-AC16)

            AC13 thru AC16 are reserved for  definition  by  the  caller.
            They  are  always  preserved  over  all  calls  to any GLXLIB
            routine.

            P       Pushdown list pointer           (AC17)


   One major implication of these conventions  is  that  any  call  to  a
   routine  in  the  GALAXY  library  will  preserve  the contents of all
   accumulators except S1, S2, and TF.








                                    1-6
                                                       THE GALAXY LIBRARY


   1.5.3  Subroutine argument passing conventions

   Arguments are passed to and from library routines  using  S1  and  S2.
   The following rules apply:

         o  Single and double arguments are passed directly in S1 and S2.

         o  If more than two arguments are being passed, they are  passed
            in  an  argument  block.   S1  will contain the length of the
            block and S2 will contain the address of the block.  Argument
            blocks may not be in the accumulators.




   1.5.4  Subroutine calling conventions

   All GLXLIB routines are called  using  an  absolute  offset  into  the
   library's entry vector.  All users of the library should use the $CALL
   mechanism defined in GLXMAC to reference library routines.

   A typical library call follows:

           $CALL   I%NOW           ;RETURN CURRENT TIME IN S1
           ...                     ;RETURN HERE FROM ROUTINE

   Refer to the description of $CALL in section 2.8 for more  information
   on the calling mechanism.



   1.5.5  SUCCESS/FAILURE testing conventions

   All library routines return a value of TRUE or FALSE in accumulator TF
   to  indicate success or failure of the routine.  However, the contents
   of  TF  should  not  be  tested  directly.   One  of   the   following
   pseudo-instructions should be used.

           JUMPT ADDR      Jumps to address if TF is TRUE

           JUMPF ADDR      Jumps to address if TF is FALSE

           SKIPT           Skip next instruction if TF is TRUE

           SKIPF           Skip next instruction if TF is FALSE









                                    1-7
   THE GALAXY LIBRARY


   1.5.6  Subroutine return mechanisms

   The following conventions apply to subroutine returns:

         o  Control will be  returned  to  the  caller  at  the  location
            immediately following the calling instruction.

         o  A value of TRUE or FALSE will be returned in TF  to  indicate
            success or failure of a routine.

         o  A value of TRUE will be returned in TF by routines that  have
            no possibility of failure.

         o  If FALSE is returned in TF an error code may be  returned  in
            S1.   Refer to the individual routine descriptions for a list
            of possible error codes they may return in S1.

         o  Upon return the stack  will  be  restored  to  it's  original
            calling state.

   The following return mechanisms are defined:

           $RETT           Sets TF to TRUE and returns

           $RETF           Sets TF to FALSE and returns

           $RETE(XXX)      Load GALAXY error code XXX in S1
                           Sets TF to FALSE and returns

           $RET            Return the current value of TF
                           to the caller

   Refer to the individual pseudo-instruction descriptions in section 2.8
   for more information on return mechanisms.

   An example subroutine call and subrotine:

                   MOVE    S1,ARG          ;Call with ARG in S1
                   $CALL   SUBR            ;DO THE SUBROUTINE
                   JUMPF   DIE             ;GIVE UP IF IT FAILS
                   .....

           SUBR:   .....                   ;DO MY BUSINESS
                   CAIL    S1,LIM          ;CHECK RANGE OF RESULT
                   CAILE   S1,MAX          ;TO RETURN IN S1
                     $RETF                 ;FAIL
                   $RETT                   ;SUCCEED







                                    1-8











                                 CHAPTER 2

                       MACROS AND PSEUDO-INSTRUCTIONS



   Several macros and pseudo-instructions are defined to  perform  common
   operations.

   Many of the definitions have been taken from MACTEN or  MACSYM.   This
   eliminates  dependence  on  system  macro  definitions  and  makes  it
   possible for users of the library to  search  one  universal  file  to
   obtain  all  the standard system macros.  As stated in chapter one the
   PROLOG macro establishes a search for the proper system universal file
   for UUO or JSYS definitions.






























                                    2-1
   MACROS AND PSEUDO-INSTRUCTIONS


   2.1  Field Masks and Constants

   A field mask is defined as a value with a string of contiguous 1  bits
   used to define a particular field within a word.  Field masks are used
   to  define  fields  of  data  structures  to  be  referenced  by   the
   pseudo-instructions which operate on data structures.



   2.1.1  Common Field Masks and Constants

   Several Masks and constants are defined in GLXMAC for convienience.  A
   partial listing follows.

           FWMASK = 777777,,777777         Full word mask

           LHMASK = 777777,,000000         Left Half mask

           RHMASK = 000000,,777777         Right Half mask

           BP.POS = 770000,,000000         Byte pointer position mask

           BP.SIZ = 007700,,000000         Byte pointer size mask

           .INFIN = 377777,,777777         Plus Infinity

           .MINFI = 400000,,000000         Minus Infinity

           TRUE   = 777777,,777777         True value

           FALSE  = 000000,,000000         False value



   2.1.2  Common Control Characters

   Symbols are defined for all  control  character  codes  0  to  37  and
   175-177.  Following are some commonly used characters.

           .CHBEL = 07                     bell

           .CHBSP = 10                     backspace

           .CHTAB = 11                     tab

           .CHLFD = 12                     linefeed

           .CHFFD = 14                     formfeed

           .CHCRT = 15                     carriage return

           .CHESC = 33                     escape


                                    2-2
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.2  FIELD MASK MACROS

   The following macros operate on field masks.

         o  WID(MASK)

            Width - returns the width of a field discribed by MASK.

                    WID(77B23) = 6

         o  POS(MASK)

            Position - returns the bit number of the rightmost 1  bit  in
            MASK.

                    POS(77B23) = 27 (23 decimal)

         o  POINTR(LOC,MASK)

            Byte pointer - constructs a  byte  pointer  to  location  LOC
            which references the byte described by MASK.

                    POINTR(100,77B23) = POINT WID(77B23),100,POS(77B23)
                                      = POINT 6,100,23
                                      = 140600,,000100

         o  FLD(VAL,MASK)

            Field value - Places the value VAL into the  field  described
            by MASK.

                    FLD(33,77B23) = 000000,,330000

         o  .RTJST(VAL,MASK)

            Right-justify - Returns the value of the field  described  by
            MASK within the symbol VAL.

                    .RTJST(123456,77B23) = 12

         o  MASKB(LBIT,RBIT)

            Mask - construct a mask word which describes a field from bit
            LBIT to bit RBIT inclusive.  (LBIT and RBIT are decimal)

                    MASKB(18,26) = 000000,,777000








                                    2-3
   MACROS AND PSEUDO-INSTRUCTIONS


   2.3  Conditional assembly macros

   The following conditional assembly macros are defined:

         o  TOPS10 <Conditional assembly code>

         o  TOPS20 <Conditional assembly code>

         o  SYSPRM SYMBOL,TOPS10-value,TOPS20-value

            Assigns a TOPS10 or TOPS20 value to a given symbol




   2.4  Storage allocation macros

   The following macros allocate local and global storage for  a  program
   or  library  module.   For  a  non-library  component  the  storage is
   allocated in the callers address space.  For  library  components  the
   storage  is  allocated  in the library data segment (beginning at page
   600)

         o  $DATA NAME,SIZE Declare NAME as SIZE words of local storage

         o  $GDATA NAME,SIZE Declare NAME as SIZE words of global storage

   If SIZE is omitted one word is allocated

   Three facilities for allocating temporary storage for subroutines  are
   described in Section 2.16



   2.5  Listing control macros

   The following macros provide nested listing control.

         o  LSTON.  Enable listings and cref if at top level

         o  LSTOF.  (XCREF) Turn off listings  and  optionally  turn  off
            crefs if XCREF is specified

         o  CONT.  (SECTION) Forces a new page in the listing and  prints
            (SECTION Continued on next page)

   To disable LSTOF.  declare LSTIN.==1B0







                                    2-4
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.6  MISCELLANEOUS Macro definitions


         o  VRSN.  (PFX)

            Return a  standard  version  word  for  PFX.   Requires  that
            PFX'VER,  PFX'EDT,PFX'WHO  and  PFX'MIN  be  defined  in your
            program.

         o  XP (SYMBOL,VALUE,PRINT)

            Define SYMBOL as VALUE and allow it to be displayed by DDT if
            PRINT is any non space.

         o  ND (SYMBOL,VALUE)

            Define SYMBOL as VALUE if SYMBOL is not already defined.  The
            symbol will not be displayed by DDT.

         o  EXT <LIST>

            Declare all symbols in  LIST  to  be  external.   (e.g.   EXT
            <FOO,BAR,ETC>)

         o  GLOB <LIST>

            Declare all symbols in LIST to be GLOBAL.  Causes the  symbol
            to   be  Interned  or  Externed  as  required.   (e.g.   GLOB
            <FOO,BAR,EXT>)

         o  MIN (<LIST>,SYMBOL)

            Declare SYMBOL to be equal to the smallest element  in  LIST.
            (e.g.   MIN  <10,15,4,36>,SYM  would  cause SYM to be defined
            with a value of 4)

         o  MAX (<LIST>,SYMBOL)

            Declare SYMBOL to be equal to the largest  element  in  LIST.
            (e.g.   MAX  <10,15,4,36>,SYM  would  cause SYM to be defined
            with a value of 36.

         o  MOD.  (DEND,DSOR)

            Return the assembly time remainder of DEND divided  by  DSOR.
            (e.g.  MOD.  10,3 = 1)








                                    2-5
   MACROS AND PSEUDO-INSTRUCTIONS


   2.7  AC Mask PSEUDO-INSTRUCTIONS

   The following mnemonics are similar to machine  instructions  used  to
   move and test bits and fields.  These macros select the most efficient
   instruction to use for the mask or value being used.

         o  MOVX AC,VALUE

            Load  AC  with  VALUE.   Assembles  one  of   the   following
            instructions:  MOVEI, MOVSI, HRROI, HRLOI, or MOVE literal.

         o  OPR'X AC,VALUE  (ADDX,SUBX,IMULX,MULX,IDIVX,DIVX)

            Perform the specified operation on AC using VALUE.  Assembles
            immediate  mode  instruction  if  possible,  otherwise uses a
            literal.

         o  CAXm AC,VALUE   (CAXL,CAXLE,CAXE,CAXGE,CAXG,CAXN,CAXA)

            Compare AC with VALUE and skip if condition "m" is satisfied.
            Assembles CAIm AC,VALUE or CAMm AC,[VALUE].

         o  TXmt AC,MASK    (All Test and Modification Classes)

            Assembles TLmt AC,(MASK) or TRmt AC,MASK or TDmt AC,[MASK].

                    TXmt AC,MASK    ;TXN,TXNE,TXNA etc.
                    IORX AC,MASK    ;equivalent to TXO AC,MASK
                    ANDX AC,MASK    ;equivalent to TXZ AC,MASK
                    XORX AC,MASK    ;equivalent to TXC AC,MASK
























                                    2-6
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.8  Subroutine Call and Return Pseudo-instructions

   The  following  pseudo-instructions   are   implemented   for   GALAXY
   subroutine conventions.

         o  $CALL ROUTINE

            The calling mechanism is via PUSHJ to the routine.  A  simple
            PUSHJ or indirect PUSHJ is generated depending on the routine
            address.  The following cases exist:

             o  The routine is a library routine.  The entry  points  for
                library routines are recorded in the entry vector.  $CALL
                would generate an indirect PUSHJ to the routine.

             o  The routine is in the callers address space.  $CALL would
                generate a PUSHJ to the routine.


         o  $RETT

            Set the TF accumulator to TRUE and return to the caller via a
            POPJ.

            A true return may also be effected by transferring control to
            .RETT

         o  $RETF

            Set the TF accumulator to FALSE and return to  caller  via  a
            POPJ.

            A false return may also be effected by  transferring  control
            to .RETF

         o  $RET

            Return the current condition of TF to the caller.  $RET would
            be  used  to  return  the  status  of a sub-sub routine.  All
            galaxy subroutines must return a TRUE or FALSE value  to  the
            caller.

            A simple return may also be effected by  transfering  control
            to .POPJ

         o  $RETE(XXX)

            $RETE is used to return defined GALAXY  error  codes  to  the
            caller.   The  numeric value of ERXXX$ is stored in S1 and TF
            is set to FALSE.  Return to the caller via a POPJ.




                                    2-7
   MACROS AND PSEUDO-INSTRUCTIONS


   2.9  Logical TRUE/FALSE Pseudo-instructions

   These pseudo-instructions  should  be  used  when  testing  a  logical
   condition  to  project the idea to the reader of the program.  TRUE is
   any bit on, FALSE is all bits off.

   These pseudo-instructions are used to test the  condition  of  the  TF
   accumulator.  In this case TF is implied and they become JUMPT ADDR or
   SKIPT , JUMPF ADDR or SKIPF.

           JUMPT AC,ADDR   equivalent to JUMPN AC,ADDR

           JUMPF AC,ADDR   equivalent to JUMPE AC,ADDR

           SKIPT AC,ADDR   equivalent to SKIPN AC,ADDR

           SKIPF AC,ADDR   equivalent to SKIPE AC,ADDR

           $RETIF          equivalent to JUMPF .POPJ

           $RETIT          equivalent to JUMPT .POPJ




   2.10  P-class Pseudo-instructions

   The following pseudo instructions are used within  a  subroutine  when
   passing  control  to another routine which will return to the original
   caller.

   These instructions should be used to tell the reader  of  the  program
   that  the action of the specified routine will be performed and return
   to the caller will be effected.

           PJRST           equivalent to JRST



   2.11  Miscellaneous Pseudo-instructions

   Two convienience pseudo instructions are provided for conversion  from
   a page number to a page address and vice-versa.

           PG2ADR AC       equivalent to LSH AC,^D9

           ADR2PG AC       equivalent to LSH AC,-^D9







                                    2-8
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.12  Data-structure Macros

   There  are  many  pseudo-instructions  which  allow   accessing   data
   structures  defined  with  DEFSTR  and MSKSTR.  The primary reason for
   using these pseudo-instructions is so that the data structure  may  be
   changed  without invalidating any instructions.  It should be possible
   to write code that is completely insensitive to the position of a data
   element within a structure.



   2.12.1  Data Structure Definition Macros

   A data structure is simply a collection of named data elements.   Each
   data element within a stucture may occupy any field within any word of
   the data structure.  A data element may be from 1 to 36 bits wide.

   For example consider the following Data Structure and it's elements.

           !=======================================================!
   TABLE:  !                         TYPE                          !
           !-------------------------------------------------------!
           !            OLD            !            NEW            !
           !-------------------------------------------------------!
           !      PREV       !     CURRENT      !      FUTURE      !
           !=======================================================!

   Each data element within the structure has a name which could be  used
   to reference it.

   Two macros exist to define the data elements within a structure.

         o  DEFSTR(NAME,LOCATION,POSITION,SIZE)

            where   NAME is the data element name

                    LOCATION is the word position within the structure

                    POSITION is the rightmost bit of the element

                    SIZE is the number of bits in the element


         o  MSKSTR(NAME,LOCATION,MASK)

            where   NAME and LOCATION are the same as in DEFSTR

                    MASK is a field mask describing the position
                         and size of the data element





                                    2-9
   MACROS AND PSEUDO-INSTRUCTIONS


   The data structure on the previous page could be defined as:

           DEFSTR  (TYPE,TABLE,^D35,^D36)

           DEFSTR  (OLD,TABLE+1,^D17,^D18)

           DEFSTR  (NEW,TABLE+1,^D35,^D18)

           DEFSTR  (LINKS,TABLE+2,^D35,^D36)

             MSKSTR(PREV,TABLE+2,777B11)

             MSKSTR(CURRENT,TABLE+2,777B23)

             MSKSTR(FUTURE,TABLE+2,777B35)

   Note that the data element LINKS is a composite of PREV,  CURRENT  and
   FUTURE to allow them to be referenced as one data element.

   DEFSTR and MSKSTR may be used interchangably to define the elements of
   a  data  structure.   Note that the arguments for POSITION and SIZE in
   DEFSTR must represent decimal values.

   DEFSTR and MSKSTR make two definitions for each data element NAME.

         o  A symbol "NAME" which is a field mask describing the position
            of the data element within a word.

         o  A macro "%NAME" which describes  the  location  of  the  data
            element within a structure.
























                                    2-10
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.13  Data Structure Pseudo-instructions.

   When referencing data elements defined via DEFSTR and  MSKSTR,  the  Y
   field  is  optional in all of the following pseudo-instructions.  If Y
   is present, it is concatenated to the LOCATION  information  specified
   in the DEFSTR or MSKSTR.

   The NAME field typically represents a data element defined with DEFSTR
   or  MSKSTR.  However, NAME may optionally be a field mask representing
   a field within a word.  In this case the Y argument is mandatory since
   no LOCATION information was specified via DEFSTR or MSKSTR.

   If NAME is omitted a FULL-WORD field mask is assumed and the  Y  field
   is mandatory.

   The following pseudo instructions operate on data strucures:

         o  LOAD AC,Y,NAME

            Moves the contents of structure element NAME right  justified
            into AC.  Assembles MOVE, HLRZ HRRZ or LDB as appropriate.

         o  STORE AC,Y,NAME

            Moves the byte contained in AC  to  structure  element  NAME.
            Assembles MOVEM, HRLM, HRRM, or DPB as appropriate.

         o  ZERO Y,NAME

            Zeros stucture element NAME.  Assembles SETZM,  HRRZM,  HLLZM
            or a call to .ZERO as appropriate.

         o  INCR Y,NAME

            Adds one to structure element NAME.  Assembles AOS or a  call
            to .AOS as appropriate.

         o  DECR Y,NAME

            Subtracts one from structure element NAME.  Assembles SOS  or
            a call to .SOS as appropriate.













                                    2-11
   MACROS AND PSEUDO-INSTRUCTIONS


   2.14  Macros to build static data structures

   Since data and parameter blocks must be correct in both  the  contents
   and the position of fields, they cannot be created by static assembly.
   The layout of a block may vary as  data-structures  are  altered.   To
   facilitate   assembly-time  creation  of  complex  data  layouts,  the
   following macros exist.

         o  $BUILD (LENGTH)

            Build is given at the location where the structure is  to  be
            assembled.   LENGTH is the number of words to allocate to the
            strucure.  LENGTH must be defined prior to the  $BUILD  macro
            call.

         o  $SET (OFFSET,MASK,VALUE)

            Sets data element described by OFFSET and MASK to VALUE.   If
            MASK  is  omitted  a  full  word  mask  is  assumed.   OFFSET
            represents the word location within the structure.

            One $SET would be given for each element you wish to  preload
            with  a  value  other  than zero.  $SET is only legal between
            $BUILD and $EOB.

         o  $EOB

            Signifies the end of a  data  structure  build.   Causes  all
            unspecified fields within the structure to be set to zero and
            moves the location counter to the end of the data structure.


   An example to  preload  some  fields  of  our  previous  example  data
   strucure:

           TABLE:  $BUILD  (3*TABSIZ)      ;RESERVE A LARGE TABLE
                     $SET  (0,TYPE,ROOT)   ;DECLARE INITIAL TYPE
                     $SET  (1,OLD,TABLE)   ;POINT TO ROOT
                     $SET  (1,NEW,TABLE)   ;POINT TO ROOT
                   $EOB                    ;END OF STRUCTURE














                                    2-12
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.15  AC and VARIABLE Save Facilities

   A facility is provided to allow you to save  an  arbitrary  number  of
   AC's  or variables and have them automatically restored on return from
   your routine.

   The call to the $SAVE macro is

           $SAVE <LIST>

   where LIST may be any number of AC's or variable  names  separated  by
   commas.

   Examples:

           $SAVE <T1,T2,T3,T4>     ;preserve all temporaries
           $SAVE <P1,P2,P3>                ;preserve P1-P3
           $SAVE <P1,FOO>          ;preserve P1 and location FOO
           $SAVE <TF,S1>           ;return TF and S1 to caller

   You should choose your AC's wisely so that a library co-routine may be
   used  to  save  and  restore  them.   Co-routines exist for T1-T4, P1,
   P1-P2, P1-P3, P1-P4, AC13, AC14, AC15, AC16, P1-AC16.

   Note that $SAVE <P1,P2> is equivalent to $SAVE <P2,P1>.  In both cases
   the library co-routine .SAVE2 will be called.

   The $SAVE macro will generate  a  call  to  a  library  co-routine  to
   save/restore the specified accumulators if a co-routine exists.  If no
   co-routine exists inline pushes will be generated and the  address  of
   the restore routine will be pushed onto the stack.

   The code generated by the $SAVE macro is always  skippable  regardless
   of the number of instructions it generates.

   If you are using  the  Named  variable  facilities  described  on  the
   following  pages and you ALSO wish to preserve the contents of AC's or
   variables or the $SAVE must be done prior to the STKVAR or TRVAR since
   $SAVE always stores it's arguments on the stack.















                                    2-13
   MACROS AND PSEUDO-INSTRUCTIONS


   2.16  NAMED VARIABLE FACILITIES


   A traditional deficiency of machine language  coding  environments  is
   facilities   for   named   transient   storage   ("automatic",  etc.).
   Sometimes, permanent storage is assigned (e.g., by  BLOCK  statements)
   when  no  recursion is expected.  More often, ACs are used for a small
   number of local variables.  In this case, the previous  contents  must
   usually  be  saved, and a general mnemonic (e.g., T1, A, X) is usually
   used.  In some cases, data on the stack is referenced, e.g.,

           MOVE T1,-2(P)

   but this is completely non-mnemonic and likely to fail  if  additional
   storage is added to or removed from the stack.

   The facilities described here provide local  named  variable  storage.
   STKVAR and TRVAR allocate storage on the caller's stack.

   All of these facilities use TF as a scratch AC to setup the  Transient
   storage.   However, TF is not disturbed on return from your routine so
   that a TRUE/FALSE value may be returned to the caller.
































                                    2-14
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.16.1  STKVAR <namelist>

   This statement allocates space on the stack and assigns  local  names.
   The  list  consists  of one or more symbols separated by commas.  Each
   symbol is assigned to one stack word.  If more than one word is needed
   for a particular variable, then a size parameter may be given enclosed
   with the symbol in angle-brackets.  E.g.,

           STKVAR <AA,BB>

           STKVAR <AA,<BB,3>>

   Variables declared in this way may be referenced  as  ordinary  memory
   operands, e.g.,

           MOVE    T1,AA
           DPB     T1,[POINT 5,BB,5]

   Each variable is assembled as a negative offset from the current stack
   location, e.g.,

           MOVE T1,AA      =       MOVE T1,-2(P)

   Hence, no other index may be given in the address field.   Indirection
   may be used if desired.

   There is no explicit limit to the scope of the  variables  defined  by
   STKVAR, but the following logical constraints must be observed:

         o  The stack pointer must not  be  changed  within  the  logical
            scope  of the variables, e.g., by PUSH or PUSHJ instructions.
            This also implies that the variables may  not  be  referenced
            within a local subroutine called from the declaring routine.

         o  The declaring routine must return  with  a  $RETT,  $RETF  or
            $RET.   This will cause the stack storage to be automatically
            deallocated.

   STKVAR assumes that enough space is available on the stack (using  the
   pushdown  list  pointer  P).   STKVAR  generates a call to the library
   support routine .STKST and generates two lines of code.













                                    2-15
   MACROS AND PSEUDO-INSTRUCTIONS


   2.16.2  TRVAR <namelist>

   This statement allocates stack space and assigns local names.   It  is
   equivalent  to  STKVAR except that it uses one additional preserved AC
   and  eliminates  some  of  the  scope  restrictions  of  STKVAR.    In
   particular,  it  uses AC16 as a frame pointer.  AC16 is setup (and the
   previous contents saved) at the  same  time  as  the  stack  space  is
   allocated,  and  references  to  the  variables  use AC16 as the index
   rather than P.  This allows additional storage to be allocated on  the
   stack   and   allows   the  variables  to  be  referenced  from  local
   subroutines.  Note that  all  such  subroutines  (i.e.,  all  variable
   references)  must  appear after the declaration in the source.  STKVAR
   may be used within TRVAR, e.g., by a local subroutine.

   STKVAR and TRVAR declarations are normally placed at the beginning  of
   a  routine.   They  need not be the first statement.  If a routine has
   two or more entry points, a single declaration may be  placed  in  the
   common  path, or several identical declarations may be used in each of
   the separate paths.  Care must be taken that  control  passes  through
   exactly one declaration before any variables are referenced.  E.g.,

           ;MAIN ROUTINE

   ENT1:   TXO F,FLAG      ;entry 1, set flag
           JRST ENT0       ;join common code

   ENT2:   TXZ F,FLAG      ;entry 2, clear flag
   ENT0:   TRVAR <AA,BB>   ;common code, declare locals
           $CALL SUBR      ;call local subroutine
           $RET            ;return value from lower subroutine

           ;LOCAL SUBROUTINE

   LSUBR:  STKVAR <CC>     ;local subroutine, declare ; locals
           MOVE T1,AA      ;reference outer routine ; variable
           MOVEM T1,CC     ;reference local variable ..
           SKIPE   BB      ;test condition
           $RETT           ;true return
           $RETF           ;false return


   TRVAR generates a call to  the  library  support  routine  .TRSET  and
   generates  two lines of code.  TRVAR assumes enough space is available
   on the stack.










                                    2-16
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.17  $TEXT Pseudo-instruction

   These pseudo-instructions  perform  various  utility  functions.   The
   operations  are  in  many  cases  fairly complicated and although they
   behave as pseudo-instructions they may in reality be subroutine calls.

   The $TEXT pseudo-instruction provides a facility for formatting  ASCII
   strings.   This  facility  includes  a mechanism which allows imbedded
   variables in the strings which may be decoded into ASCII from a number
   of internal forms (decimal, sixbit, date and time etc.).

   The $TEXT instruction takes two arguments.  The first is  usually  the
   address  of  a  subroutine  (called  the Text Output Routine) which is
   called with each decoded character.  This allows the user the  ability
   to  completely  control  the  destination  of the decoded string.  The
   routine is called with the character in accumulator S1.   See  section
   2.17.4  for  a description of the rules and conventions concerning the
   Text Output Routine.  There is one $TEXT  subroutine  built  into  the
   library  for  output to the job's terminal.  See the section on GLXTXT
   subroutines for a description of this routine.

   One of the arguments in the program's Initialization Block (IB) is the
   name of a default $TEXT routine.  If $TEXT is called with a null first
   argument, the routine specified in the IB is used.

   Another alternative for the first argument to $TEXT is  an  expression
   of  the  form  "<-1,,adr>".   On the $TEXT call this is converted to a
   byte pointer of the form "POINT 7,adr" and each byte is deposited with
   that byte-pointer.

   The second argument to $TEXT is the string  to  decode.   The  overall
   format of the call is:

                     $TEXT(ROUTINE,<string to decode>)

   The string to decode may simply be an ASCII string to print or it  may
   be  a  complex  format  specification  using  imbedded  parameters  as
   described in the following section.  An example  of  a  simple  string
   would be:

                   $TEXT(ROUTINE,<THIS IS A TEST STRING>)













                                    2-17
   MACROS AND PSEUDO-INSTRUCTIONS


   2.17.1  Imbedded parameters and Qualifiers

   Variable text may be imbedded in strings formed  using  $TEXT.   These
   variables are indicated by using the action character, circumflex (^).
   The circumflex indicates that the next character is a qualifier  which
   specifies  the  type  of  parameter.  Most of the qualifiers act on an
   argument.  Immediately following the qualifier are "loc" and "pos"  of
   a  field  delimited  by  forward slashes.  The "loc" and "pos" are the
   same as  described  in  the  section  on  data-structure  manipulation
   instructions  with  the  addition  that  "loc" may also be an assembly
   literal (i.e.  [expression]).  The argument for the qualifier  is  the
   "word"  which would result from doing a LOAD pseudo-instruction on the
   specified  field.   Note  that  the  "loc"  field  may  reference  all
   accumulators  including S1, S2 and P in both the address field and the
   index register field.

   The legal qualifiers are:

   A       Suppress the free CRLF at end of line *
   B       The 'field' is the address of an object block ***
   C       The argument is a universal date/time which is
              printed as 'hh:mm:ss'  **
   D       The argument is a signed decimal number
   E       The argument is a GALAXY error code
              (-1 for last error)
   F       The 'field' is the address of a file-descriptor (FD) ***
   H       The argument is a universal date/time which is
              printed as 'dd-mmm-yy hh:mm:ss'  **
   I       INDIRECT text.  The 'field' contains address of an ITEXT
              macro.  See description of ITEXT below. ***
   J       Type a linefeed
   K       Type a vertical tab
   L       Type a formfeed
   M       Type a carriage-return
   N       The argument is a network NODE name or number
   O       The argument is an unsigned octal number
   P       The argument is a user ID. (PPN or user name) **
   Q       The argument is a byte pointer to an ASCIZ string ***
   T       The field is the address of an ASCIZ string
   U       The argument is a directory (PPN or directory name) **
   V       The argument is a version number in standard format
   W       The argument is six SIXBIT characters, trailing blanks
              suppressed
   0       Replace the free CRLF at end of line with a NULL *
   1       The argument is an OBJECT-TYPE
   5       The argument is 5 ASCII characters, left justified
   6       The low-order 6 bits of the argument represent a SIXBIT
              character
   7       The low-order 7 bits of the argument represent an ASCII
              character
   ^      Type a circumflex (i.e. ^^ produces ^).



                                    2-18
                                           MACROS AND PSEUDO-INSTRUCTIONS


   * These qualifiers may appear anywhere in the $TEXT call

   ** If the argument to these is '-1', the current value of the
   parameter is used.

   *** Note that for the ^B and ^F qualifiers it is the 'field' rather
   than the the 'argument' (i.e.  the contents of the field) that is
   used.


   Some examples of the use of qualifiers are:

      ^D/@-1(P)/     ^O/CONTNT/     ^E/[ERFNF$]/     ^D/COPIES,777/

   Some examples of $TEXT are:

      $TEXT(TTYOUT,<This is line ^D/LINENO/ of page ^D/PAGENO/>)

      $TEXT(,<?Error number ^O/T1/ - ^T/@MSGTAB(T1)/>)

      $TEXT(<-1,,BLOCK>,<Store this message in location BLOCK>)

































                                    2-19
   MACROS AND PSEUDO-INSTRUCTIONS


   2.17.2  Field Justification

   The output generated by each $TEXT qualifier may  be  justified  in  a
   fixed  length  field  and padded appropriately.  Each qualifier may be
   augmented by 3 additional arguments:

                              ^Dabc/LOCATION/

   The three arguments a, b, and c specify the field-width, justification
   and padding character as follows:

         o  Field-width - is the width of the field in which to place the
            output.   There  is  no  default  for  this  field  so  if  a
            fixed-length  field  is  desired,  this  argument   must   be
            specified.

         o  Justification Specifier - This field is  a  single  character
            which  must  be  one of R, L, or C for right, left, or center
            respectively.   This  field  specifies  "justification"   not
            "padding".   So,  R  means  Right Justified (or Left padded).
            The default for this field is L for all qualifiers  except  O
            and D which default to R.

         o  Padding Character - This is any single character (except  for
            "/")  which  is  used to pad the field to its desired length.
            The default is a space in all cases.


   For example:

             $TEXT(,<^O6R0/[3]/ produces 000003>)

             $TEXT(,< To get just the date use ^H9/[-1]/>)



   2.17.3  ITEXT

   Just as ^T can be used to include remote  ASCIZ  strings  in  a  $TEXT
   call,  the  ^I qualifier can be used to include strings which are more
   complex (i.e.  have imbedded parameters).  The argument to  an  ^I  is
   the address of a block which is built by an ITEXT macro.  For example:

            $TEXT(routine,<Error code ^O/T1/ - ^I/@MSGTAB(T1)/>)


   MSGTAB:  [ITEXT(No privs at PC ^O/FOO/>)]

   [ITEXT(Illegal function ^D/FCNBLK/>)]

   Any qualifier can be used in an ITEXT including ^I,  so  they  may  be
   nested.


                                    2-20
                                           MACROS AND PSEUDO-INSTRUCTIONS


   2.17.4  Text Output Routine

   The Text Output Routine (TOR) is the subroutine specified as the first
   argument in a $TEXT call or as the default subroutine used by $TEXT as
   specified in the program's Initialization Block.

   This routine is called by the $TEXT processor with each  character  of
   the  decoded  ASCII string.  The character is passed to the routine as
   the low-order 7 bits of accumulator S1.

   The Text Output Routine may use accumulators S1 and S2.   Accumulators
   T1  through  T4,  P1  through  P4,  and  P  may not be used in the TOR
   (without being saved) nor are their contents in any way meaningful  to
   the  routine  (except  P  which  is  the  pushdown list pointer).  The
   contents of accumulators 13, 14, 15, and 16 are guaranteed to  be  the
   same  as they were upon execution of the $TEXT unless they are changed
   by the Text Output Routine  in  which  case  their  contents  will  be
   indeterminate for all subsequent calls to the TOR during the remainder
   of the $TEXT execution.

   The $TEXT Pseudo-instruction preserves 'all' accumulators,  hence  any
   changes made to any accumulators by the TOR (or by the $TEXT processor
   itself for that matter) will not be preserved (i.e.   the  instruction
   following  the  $TEXT will always see the same accumulator contents as
   did the $TEXT instruction.





























                                    2-21
   MACROS AND PSEUDO-INSTRUCTIONS


   2.18  Error processing Pseudo-instructions

   Three error catagories are  defined  for  GALAXY  programs  using  the
   library.  $WARN, $FATAL and $STOP accept an argument which may include
   ITEXT qualifiers.

         o  $WARN (text-argument)

            This catagory is used for errors which are recoverable or for
            unusual  conditions  that  need only be reported to the user.
            Warnings are displayed on the users terminal as
            % PRGNAM MODNAM message

         o  $FATAL (text-argument)

            This catagory is used for errors which are unrecoverable  but
            where  the  cause is understood.  For example if a priviledge
            is required for a particular function and  the  user  doesn't
            have it enabled $FATAL could be used to display
            ?  PRGNAM MODNAM message

            Fatal errors cause an exit from the  program  and  cannot  be
            continued.

         o  $STOP (XXX,Message)

            where XXX is a 3 character abbreviation for the stopcode  and
            MESSAGE  is  a  concise  description  of  the  stopcode.  The
            address of the stopcode will be given a global  label  S..xXX
            therefore the three character abbreviation must be unique.

            The  $STOP  pseudo-instruction   is   used   to   signal   an
            unrecoverable   error  condition  which  is  not  understood.
            Stopcodes indicate possible internal logic problems or system
            errors which are catastrophic.

            Stopcodes and $FATAL messages are conditionally sent to ORION
            to  be  recorded  in the system log and also sent to any jobs
            running OPR.  A flag in the  program's  initialization  block
            enables this function.

            Stopcodes stop program  execution  and  cannot  be  continued
            unless  DDT  has  been  loaded  with  the program.  If DDT is
            loaded with the  program  the  stopcode  processor  transfers
            control  to DDT and the AC and crash block information (shown
            on the following page) is suppressed.








                                    2-22
                                           MACROS AND PSEUDO-INSTRUCTIONS


   An example stopcode in the library module GLXMEM follows:

           $STOP(CCC,Cannot create page)

   would display:


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

   ?STOP CODE - CCP - in module GLXMEM on 17-Jun-77 at 4:33:37
     Reason: Cannot create page
     Program is QUASAR Version 3(200) using GLXLIB Version 1(17)
     Last GALAXY Error: 777777 (no errors yet)
     Last TOPS-20 Error: 601130 (Invalid index into system ...)


   Contents of the ACS       (Crash block starts at location 600xxx)

    0/  xxxxxxxxxxxx    xxxxxxxxxxxx    xxxxxxxxxxxx    xxxxxxxxxxxx
    4/  yyyyyyyyyyyy    yyyyyyyyyyyy    yyyyyyyyyyyy    yyyyyyyyyyyy
   10/  zzzzzzzzzzzz    zzzzzzzzzzzz    zzzzzzzzzzzz    zzzzzzzzzzzz
   14/  aaaaaaaaaaaa    aaaaaaaaaaaa    aaaaaaaaaaaa    aaaaaaaaaaaa

   Last 9 stack locations:

   -1(P)/ bbbbbbbbbbbb    -2(P)/ bbbbbbbbbbbb    -3(P)/ bbbbbbbbbbbb
   -4(P)/ cccccccccccc    -5(P)/ cccccccccccc    -6(P)/ cccccccccccc
   -7(P)/ dddddddddddd    -8(P)/ dddddddddddd    -9(P)/ dddddddddddd

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

   The crash block consists of the following 24 octal locations:

    0/  PC of $STOP
    1/  last operating system error
    2/  accumulator 0 at the $STOP
    n/     acs 1 through 16
   21/  accumulator 17 at the $STOP
   22/  last GALAXY error code
   23/  PC of last $RETE

   Note that the last operating  system  error  field  is  meaningful  on
   TOPS20  only  and  that  it  might  not  have  anything to do with the
   stopcode.










                                    2-23
   MACROS AND PSEUDO-INSTRUCTIONS


   2.19  Operator message Pseudo-instructions

   The following instructions are defined to provide a convenient  method
   of sending messages to the operator (ORION and friends).

   The  following  argument  descriptions  are  common  to  all  operator
   messages

   <header>        This argument may be any valid $TEXT string.  It
                   will be displayed as the first line of the message
                   and truncated to 30 characters.

   <message>       This argument may be any valid $TEXT string.  It
                   is displayed as the message body.

   <obj-blk-adr>   This argument is the address of a standard GALAXY
                   object block which describes the object type. (i.e.
                   Printer, Batch-stream, etc..)  This block is expanded
                   and displayed in an appropriate format with the
                   message header text.

   <ack-code-adr>  This code is stored in the message header to be 
                   used to verify that this acknowledgement matches
                   what we requested. (or vice-versa for the $ACK)

   The only restriction on the text strings is that "^^" which is a valid
   argument for $TEXT is NOT legal for these instructions.

         o  $WTO (<header>,<message>,obj-blk-adr)

            This causes a WTO type operator message to be built and  sent
            to ORION.

         o  $WTOJ (<header>,<message>,obj-blk-adr)

            This causes a WTOJ type operator message to be built and sent
            to  ORION.  The display of WTOJ type messages may be disabled
            by the individual OPR programs.

         o  $WTOR (<header>,<message>,obj-blk-adr,ack-code-adr)

            This causes a WTOR type operator message to be built and sent
            to ORION.  It does not wait on a response, it merely requests
            the response.

            The acknowledgement code at ack-code-adr will be returned  by
            ORION  with  the response so that it may be used to associate
            the response with the WTOR request.






                                    2-24
                                           MACROS AND PSEUDO-INSTRUCTIONS


         o  $ACK (<header>,<message>,obj-blk-adr,ack-code-adr)

            This causes an acknowledgement type operator  message  to  be
            sent to ORION.  It is sent to ORION in response to a previous
            request from ORION.  The acknowledgement code at ack-code-adr
            must  match  the  code  that  ORION  sent  with  the previous
            request.















































                                    2-25
   MACROS AND PSEUDO-INSTRUCTIONS


   2.20  Interrupt processing pseudo-instructions

   The following pseudo-instructions are  defined  to  provide  a  common
   mechanism for the beginning and ending of all interrupt processing.

   Only one interrupt level is available on TOPS10  while  3  levels  are
   available on TOPS20.

   The caller must inform the library that the interrupt system is  being
   used  by  setting a flag in the initialization block.  This flag tells
   the library to include the support routines for $BGINT and $DEBRK.

            $BGINT (LEVEL)

            Causes a context switch to interrupt context for LEVEL.   The
            following action is taken.

             o  Save all  ACs  in  a  fixed  AC  area  reseved  for  this
                interrupt level

             o  setup a new pushdown list  reserved  for  this  interrupt
                level

             o  Return to the interrupt  processing  code  following  the
                $BGINT call

            The $BGINT should be the first instruction of  all  interrupt
            processing routines.

            $DEBRK

            Switch back to previous context.   The  following  action  is
            taken.

             o  If we were interrupted during the I%SLP  library  routine
                alter  the  interrupt  return  PC  to break us out of the
                sleep.

             o  Restore the previous context ACs and pushdown list

             o  Dismiss the interrupt and return to previous context













                                    2-26











                                 CHAPTER 3

                        GLXLIB ROUTINE DESCRIPTIONS



   The GALAXY  subroutine  library,  GLXLIB,  consists  of  six  separate
   facilities.   Each  of these facilities are "call-compatible" for both
   the DECSYSTEM-10 and the DECSYSTEM-20.  The following table contains a
   list  of  all the GLXLIB modules, their identifying letters (i.e.  the
   'x' in x%yyyy routines) and what they do.



   Module Identifying What the module
    name   Letter      Does
   ------ ----------- ---------------

   GLXMEM M The memory management facility

   GLXFIL F The disk file manipulation facility

   GLXIPC C The interprocess communication facility

   GLXLNK L The linked-list facility

   GLXTXT T The formatted ASCII ($TEXT) facility

   GLXKBD K Keyboard (terminal) routines

   GLXINT I Common Operating System functions

   GLXSCN S Command field parsing routines

   GLXCOM          Common subroutines










                                    3-1
   GLXLIB ROUTINE DESCRIPTIONS
   GLXMEM - Memory Management Routines


   3.1  GLXMEM - Memory Management Routines

   3.1.1  Description

   3.1.2  Global Routines

   The following global routines exist in GLXMEM:

            M%GPAG - Acquire a free page

            M%ACQP - Acquire a free page

            M%AQNP - Acquire 'n' contiguous free pages

            M%RPAG - Return a page to the free pool by address

            M%RELP - Return a page to the free pool by page number

            M%RLNP - Return 'n' contiguous pages to the free pool

            M%CLNC - Cleanup Core

            M%GMEM - Get a chunk of free space

            M%RMEM - Return a chunk of free space

            M%NXPG - Acquire a non-existant page

            M%IPRC - Flag that a page has been received

            M%IPSN - Flag that a page has been removed

            M%IPRM - Make room to receive a page




















                                    3-2
                                              GLXLIB ROUTINE DESCRIPTIONS
                                      GLXMEM - Memory Management Routines


   3.1.2.1  M%GPAG

   This routine is called to acquire one free page  of  memory  from  the
   free space handler.  The page is marked 'in-use' and zeroed.

    Accepts        No arguments

    Returns TRUE   S1/  ADDRESS of the first word of the page (xxx000)




   3.1.2.2  M%ACQP

   M%ACQP is identical to M%GPAG except that the page number is  returned
   instead of the address of the first word as in M%GPAG.

    Accepts        No arguments

    Returns TRUE   S1/ PAGE number of the allocated page




   3.1.2.3  M%AQNP

   M%AQNP is called to  allocate  a  block  of  contiguous  pages.   This
   routine  works  similarly  to M%ACQP except that a number of pages are
   requested.  Note that all pages will be zeroed.

    Accepts        S1/ NUMBER of contiguous pages needed

    Returns TRUE   S1/ PAGE number of the first page in the block




   3.1.2.4  M%RPAG

   This routine is the inverse routine to M%GPAG.  It is called to return
   a  page of memory (previously acquired) to the free pool.  Once a page
   has been returned to the free pool it must not be  referenced  in  any
   way by the host program.

    Accepts        S1/ ADDRESS of page to be returned

    Returns TRUE   always






                                    3-3
   GLXLIB ROUTINE DESCRIPTIONS
   GLXMEM - Memory Management Routines


   3.1.2.5  M%RELP

   M%RELP is the inverse routine to M%ACQP.  It  performs  the  identical
   function  as M%RPAG but takes a page number as an argument rather than
   an address.

    Accepts        S1/  Page number of page to be released

    Returns TRUE   always



   3.1.2.6  M%RLNP

   M%RLNP is like M%RELP except that it  is  a  mechanism  for  releasing
   multiple  contiguous  pages (as gotten from M%AQNP) rather than just a
   single page.

    Accepts        S1/  Count of pages to release
                   S2/  Page number of first page in the block

    Returns TRUE   always




   3.1.2.7  M%CLNC

   M%CLNC is an optionally called routine which destroys all pages  which
   are  not  in  use  but  are in the working set.  This reduces the load
   which the program places on the system.

    Accepts        No arguments

    Returns TRUE   always



   3.1.2.8  M%GMEM

   M%GMEM is used to obtain blocks of memory not equal  to  one  page  in
   size.   This  facility  is useful for allocating chunks of memory on a
   temporary basis or when the chunk size is not known at  compile  time.
   The block of memory obtained via M%GMEM is zeroed.

    Accepts        S1/ Number of words wanted

    Returns TRUE   S1/ Same as input argument
                   S2/  Address of start of chunk




                                    3-4
                                              GLXLIB ROUTINE DESCRIPTIONS
                                      GLXMEM - Memory Management Routines


   3.1.2.9  M%RMEM

   M%RMEM is used to de-allocate memory obtained by  M%GMEM.   The  block
   returned  may  be  the entire block obtained or only part of it.  Once
   the block has been returned, it  is  no  longer  addressable  and  its
   contents are indeterminate.

    Accepts        S1/ Number of words being returned
                   S2/  Address of first word being returned

    Returns TRUE   always



                                    NOTE

                  The  following  four  routines,  M%NXPG,
                  M%IPRC,  M%IPSN,  M%IPRM,  are  included
                  here primarily for completeness.  If the
                  host  program  uses the GLXIPC interface
                  for  communicating   via   IPCF,   these
                  routines  should  not be necessary since
                  the IPCF handler  makes  whatever  calls
                  are necessary.





   3.1.2.10  M%NXPG

   M%NXPG is  used  to  acquire  a  non-existant  page  without  actually
   creating  it.   This  is  usually used just prior to an IPCF page mode
   receive so that the incoming page may be received  into  it.   If  the
   receive  is  successful  a call to M%IPRC is made to update the memory
   manager's database.

    Accepts        No arguments

    Returns TRUE   S1/  Page number of a non-existant page













                                    3-5
   GLXLIB ROUTINE DESCRIPTIONS
   GLXMEM - Memory Management Routines


   3.1.2.11  M%IPRC

   M%IPRC is called to notify the memory manager that  a  page  has  been
   created via an IPCF page mode receive.  The sequence:

                       M%NXPG - IPCF Receive - M%IPRC

   is equivalent to a single call  to  M%ACQP,  i.e.   the  page  is  now
   allocated and created.

    Accepts        S1/  Page number of received page

    Returns TRUE   always




   3.1.2.12  M%IPSN

   After a page is set via IPCF, the memory manager must  be  told.   The
   page sent is marked as free and may then be allocated for any use.

    Accepts        S1/  Page number of the page sent

    Returns TRUE   always




   3.1.2.13  M%IPRM

   M%IPRM is a panic routine used on TOPS10 systems only (on  TOPS20  the
   routine  is a no-op).  When an IPCF receive fails because the physical
   memory limit of the program is exceeded,  M%IPRM  is  called  to  page
   "something" out so that the page can be received.

    Accepts        No arguments

    Returns TRUE   always














                                    3-6
                                              GLXLIB ROUTINE DESCRIPTIONS
                                 GLXFIL - Disk File Input/Output Routines


   3.2  GLXFIL - Disk File Input/Output Routines

   3.2.1  Description

   GLXFIL provides an operating system independent interface to the local
   file system.  Files can be opened, read or written a byte at a time or
   a buffer at a time (in any byte size), closed,  deleted,  renamed  and
   processed in a number of other ways.

   Most of the operations are performed on files which have  been  opened
   by  GLXFIL.   To  open a file, one of the OPEN routines must be called
   (there are a number of OPEN routines depending on the desired access).
   These routines take as principle arguments, the file-specification and
   the byte size.  The OPEN routines return an Internal File Number (IFN)
   which is the handle on the file for all other operations.



   3.2.2  Global Routines

   The following global routines exist in GLXFIL:

            F%IOPN - Open up a file for Input

            F%IBYT - Read a single byte from an input file

            F%IBUF - Read a buffer from an input file

            F%POS  - Position to a byte in an input file

            F%REW  - Rewind an input file

            F%OOPN - Open up a file for Output

            F%AOPN - Open an output file for Append

            F%OBYT - Write a single byte to an output file

            F%OBUF - Write a buffer to an output file

            F%REL  - Close and release an opened file

            F%DREL - Close and delete an opened file

            F%RREL - Reset an opened file

            F%CHKP - Checkpoint current state of an opened file

            F%REN  - Rename an unopened file




                                    3-7
   GLXLIB ROUTINE DESCRIPTIONS
   GLXFIL - Disk File Input/Output Routines


            F%INFO - Return system dependent file information

            F%FD   - Return the FD of an opened file

            F%DEL  - Delete an unopened file




   3.2.3  File Open Block (FOB)

   The File Open Block is an argument block which is  referenced  by  all
   routines which open a file.  The first two arguments must be specified
   for  all  open  requests.   The  logged  in  directory  and  connected
   directory  need  only  be  specified if a priviledged program wants to
   check the file access rights "in behalf of" the specified user.

   The format of the File Open Block is:

           !=======================================================!
    FOB.FD !       Address of the file descriptor (FD)             !
           !-------------------------------------------------------!
    FOB.CW !               File Open Flags           !  Byte Size  !
           !-------------------------------------------------------!
    FOB.US !  Logged in directory or PPN to use for access check   !
           !-------------------------------------------------------!
    FOB.CD !  Connected directory to use for access check (TOPS20) !
           !=======================================================!


   The flags and fields which are defined in FOB.CW are:


            FB.LSN  Ignore line sequence numbers if they are present


            FB.NFO  Create new file only (never supersede)


            FB.BSZ  Byte size to use for open













                                    3-8
                                              GLXLIB ROUTINE DESCRIPTIONS
                                 GLXFIL - Disk File Input/Output Routines


   3.2.4  File Descriptor (FD)

   The File Descriptor is an argument block which is  referenced  by  the
   FOB and all routines which require or return a file specification.

   The format of the File Descriptor on TOPS10 is:

           !=======================================================!
    .FDLEN !     Length of the FD    !            0                !
           !-------------------------------------------------------!
    .FDSTR !        Structure which contains the file              !
           !-------------------------------------------------------!
    .FDNAM !                     File name                         !
           !-------------------------------------------------------!
    .FDEXT !    File extention       !                             !
           !-------------------------------------------------------!
    .FDPPN !    User File Directory which contains the file (PPN)  !
           !-------------------------------------------------------!
    .FDPAT /    Sub File Directory path to the file (SFD list)     /
           !=======================================================!


   The format of the File Descriptor on TOPS20 is:

           !=======================================================!
    .FDLEN !     Length of the FD    !            0                !
           !-------------------------------------------------------!
    .FDFIL /              ASCIZ file specification                 /
           !=======================================================!
























                                    3-9
   GLXLIB ROUTINE DESCRIPTIONS
   GLXFIL - Disk File Input/Output Routines


   3.2.4.1  F%IOPN

   F%IOPN is called to open a file for input.  The two  principle  inputs
   to  the  routine are the file-specification of the file to be read and
   the byte size.  The file is opened and an internal file  number  (IFN)
   is  returned.   This  IFN is the handle by which the file is specified
   for all subsequent calls to GLXFIL.

    Accepts        S1/  Length of the FOB
                   S2/  Address of the FOB

    Returns TRUE   S1/  the Internal File Number (IFN)
                        assigned to this file

            FALSE  S1/  Error code


   Possible errors:  ERSLE$ ERIFS$ ERFNF$ ERPRT$ ERDNA$ ERUSE$



   3.2.4.2  F%IBYT

   The byte returned by F%IBYT will be  of  the  size  specified  in  the
   F%IOPN call.  The most common error EREOF$ will indicate that the last
   byte has been read.  Note that mixed F%IBYT and F%IBUF calls using the
   same IFN will cause data to be lost.

    Accepts        S1/  IFN of file opened via F%IOPN

    Returns TRUE   S1/  IFN given as input argument
                   S2/  Right justified byte

            FALSE  S1/  Error code


   Possible errors:  EREOF$ ERFDE$



   3.2.4.3  F%IBUF

   The F%IBUF routine provides a more efficient means of  accessing  data
   in  a  file,  saving repeated calls to F%IBYT.  The end of file return
   (EREOF$ ) indicates that the buffer  returned  on  the  previous  call
   contained the last byte of the file.

    Accepts        S1/  IFN of file opened via F%IOPN

    Returns TRUE   S1/  Number of bytes available
                   S2/  ILDB byte pointer to byte string


                                    3-10
                                              GLXLIB ROUTINE DESCRIPTIONS
                                 GLXFIL - Disk File Input/Output Routines


            FALSE  S1/  Error code


   Possible errors:  EREOF$ ERFDE$

















































                                    3-11
   GLXLIB ROUTINE DESCRIPTIONS
   GLXFIL - Disk File Input/Output Routines


   3.2.4.4  F%POS

   F%POS is  able  to  provide  random-access  to  an  input  file.   The
   positioning  is  done on a byte basis using the byte size specified in
   the F%IOPN call.  The byte  positioned  to  would  be  the  next  byte
   returned by F%IBYT or F%IBUF.  It is legal to position a file anywhere
   from its first byte (which is byte 0) to its last byte.  A request  to
   position  to  byte  "-1" positions a file to its end (i.e.  next input
   request will return end-of-file).

    Accepts        S1/  IFN
                   S2/  Number of byte to position to

    Returns TRUE   on successful positioning

            FALSE  S1/  Error code


   Possible errors:  ERIFP



   3.2.4.5  F%REW

   (byte 0).  It is really a special case of F%POS.

    Accepts        S1/  IFN

    Returns TRUE   always
























                                    3-12
                                              GLXLIB ROUTINE DESCRIPTIONS
                                 GLXFIL - Disk File Input/Output Routines


   3.2.4.6  F%OOPN

   The F%OOPN routine is used to open a file for  output.   Files  opened
   via  F%OOPN  are  new  files  which  will be written by later calls to
   F%OBYT and F%OBUF.  On TOPS-20, if the  file  already  exists,  a  new
   generation  will  be written.  On TOPS-10 a file by the same name will
   be superseded (assuming that the file is  closed  by  calling  F%REL).
   The  caller  may  also  specify that this file is not to supersede any
   existing file.  This is accomplished by setting the  appropriate  flag
   in the parameter block.

   The two principal arguments to F%OOPN are the location of an  FD  (see
   GLXMAC)  and  the  output  byte size.  In addition, information may be
   given for access checking the operation if it is being  performed  for
   someone  else.   This information is passed in a File Open Block (FOB)
   which is described in GLXMAC.

    Accepts        S1/  length of the File Open Block
                   S2/  address of the FOB

    Returns TRUE   S1/  IFN of the opened file

            FALSE  S1/  Error code




   3.2.4.7  F%AOPN

   F%AOPN is really a special case of F%OOPN.  The routine takes the same
   arguments  and  duplicates the functionality of F%OOPN routine.  Files
   opened using this routine are appended to (if  they  already  existed)
   rather  than  created  or  superseded.  If the specified file does not
   already exist, calling F%AOPN is equivalent to calling F%OOPN.

    Accepts        S1/  length of the FOB
                   S2/  address of the FOB

    Returns TRUE   S1/  IFN for the opened file

            FALSE  S1/  Error code












                                    3-13
   GLXLIB ROUTINE DESCRIPTIONS
   GLXFIL - Disk File Input/Output Routines


   3.2.4.8  F%OBYT

   F%OBYT is  used  to  deposit  a  single  byte  into  the  output  file
   previously  opened via F%OOPN or F%AOPN.  Actually, GLXFIL will buffer
   the single byte output for greater efficiency.  The bytes supplied  to
   this  routine  are  assumed  to  be  right  justified  and of the size
   specified in the "open" call.

    Accepts        S1/  IFN of the file
                   S2/  Single byte right justified

    Returns TRUE   on successful operation

            FALSE  S1/  Error code




   3.2.4.9  F%OBUF

   F%OBUF is used to write a stream of bytes to an output file.  This  is
   more  efficient  that  calling  F%OBYT  for  each byte.  The bytes are
   assumed to start on a word boundary, be contiguous and be of the  size
   specified in the FOB used to open the file.

    Accepts        S1/  IFN of the file
                   S2/  XWD number-of-bytes,address

    Returns TRUE   on successful operation

            FALSE  S1/  Error code






















                                    3-14
                                              GLXLIB ROUTINE DESCRIPTIONS
                                 GLXFIL - Disk File Input/Output Routines


   3.2.4.10  F%REL

   F%REL is called after all the desired operations have  been  performed
   on  a  file.   F%REL  closes  the  file  and  releases the IFN and any
   resources (like buffers) which were held by the  IFN.   F%REL  is  the
   simplest  form  of release.  For output files, all buffers are written
   out and the file is closed.  For input  files,  the  file  is  closed.
   After  a  call  to  F%REL  the  IFN for the released file is no longer
   valid.  Note that upon return, even FALSE return, the file  is  closed
   and the IFN is invalid.

    Accepts        S1/  IFN

    Returns TRUE   File is closed

            FALSE  S1/  Error code (could be data error)




   3.2.4.11  F%DREL

   F%DREL performs all the functions of the F%REL routine and in addition
   deletes  the  file.  Although the utility of this routine is small for
   output files it can be used to delete an input file after reading  it.
   Note  that  if  the FOB used to open the file specified "in-behalf-of"
   information, the deletion is also done in behalf of that  user.   Note
   also that upon return, even a FALSE return, the file is closed and the
   IFN is invalid.

    Accepts        S1/  The IFN

    Returns TRUE   File has been deleted

            FALSE  S1/  Error code


















                                    3-15
   GLXLIB ROUTINE DESCRIPTIONS
   GLXFIL - Disk File Input/Output Routines


   3.2.4.12  F%RREL

   F%RREL is used to reset a file and release it.  This  actually  aborts
   all  operations  on this file and makes everything look as if the file
   was never opened at all.  For output files,  nothing  will  appear  on
   disk  and  any  create or supersede will be aborted.  For input files,
   the access date is not updated to reflect "this" access.

    Accepts        S1/  The IFN

    Returns TRUE   always










































                                    3-16
                                              GLXLIB ROUTINE DESCRIPTIONS
                                 GLXFIL - Disk File Input/Output Routines


   3.2.4.13  F%CHKP

   F%CHKP is used to fail-safe all  performed  operations  on  an  opened
   file.   This  routine  is used to insure that in the event of a system
   failure the work already done on a file will not be lost.  For  output
   files,  F%CHKP  writes  out  all  buffered  data, causes the operating
   system to update its file-system database and leaves the file open for
   more  I/O.   If  the system should fail before the file is closed, the
   file would be in the same state as if it had been closed at  the  time
   of the checkpoint.  For input and output files, the number of the next
   byte to be read or written is returned.

    Accepts        S1/  The IFN

    Returns TRUE   S1/  Relative position of next byte

            FALSE  S1/  Error code




































                                    3-17
   GLXLIB ROUTINE DESCRIPTIONS
   GLXFIL - Disk File Input/Output Routines


   3.2.4.14  F%REN

   The F%REN routine provides the ability to change the name of  a  file.
   The  argument  block  is  a File Rename Block (FRB) which provides the
   location of two File Descriptors.  The first FD describes  the  source
   file  for the rename and the second describes the new name the file is
   to  be  given.   Optionally  the  FRB  may  specify  "in  behalf   of"
   information.

   The rename operation is done as the specific operating system  allows.
   On TOPS10 the rename will fail if a file already exists with the "new"
   name, and on TOPS20 will create a new generation.  Note that the files
   involved in the rename must not be open at the time of the rename.

    Accepts        S1/  Length of the FRB
                   S2/  Address of the FRB

    Returns TRUE        File has been renamed

            FALSE  S1/  Error code


   The format of the File Rename Block is:

           !=======================================================!
    FRB.SF !       Address of the FD for the existing file         !
           !-------------------------------------------------------!
    FRB.DF !       Address of the FD for the new file              !
           !-------------------------------------------------------!
    FRB.US ! Logged in directory number or PPN for access check    !
           !-------------------------------------------------------!
    FRB.CD ! Connected directory number for access check (TOPS20)  !
           !=======================================================!




















                                    3-18
                                              GLXLIB ROUTINE DESCRIPTIONS
                                 GLXFIL - Disk File Input/Output Routines


   3.2.4.15  F%INFO

   Although  GLXFIL  insulates  the  caller  from  the  operating  system
   dependent  file operations and interfaces, in certain cases the caller
   may want to know more about a file.  F%INFO provides read-only  access
   to  the  extended LOOKUP/ENTER block on TOPS10 and the File Descriptor
   Block  on  TOPS20.   The  caller  can  ask  for  a  generic  piece  of
   information  about  a  file  (e.g.   creation  time)  and  it  will be
   extracted from the operating system information  and  returned.   Note
   that  the information returned reflects the state of the file "when it
   was opened" and does not take into account operations performed  after
   the file was opened.
    Accepts        S1/  The IFN
                   S2/  The item specifier

                           FI.CRE  UDT format Creation DATE/TIME
                           FI.GEN  Version/Generation number
                           FI.PRT  Protection of the file
                           FI.CLS  Class of file (TOPS-20 only)
                           FI.AUT  Author of the file
                           FI.USW  User settable word
                           FI.SPL  Spool word (TOPS-10) 
                           FI.SIZ  Size of file in bytes
                           FI.MOD  Data mode
                           FI.CHN  Channel or JFN

    Returns TRUE   S1/  The requested parameter




   3.2.4.16  F%FD  

   Although an FD must be specified  to  open  a  file,  a  mechanism  is
   provided  for  recalling  the  FD  associated with an open file.  This
   facility is provided for two reasons.  The first is simply that the FD
   associated  with  an IFN may no longer by available even though it was
   at the time the file was opened.  The second is that the  original  FD
   may  have been incomplete and that once search lists and logical names
   have been taken into account, and  defaults  filled  in,  the  FD  may
   include more information.
   F%FD will provide the address  of  the  FD  associated  with  an  IFN.
   Depending  on the calling arguments, F%FD will return the address of a
   copy of the FD provided in the FOB or the address of an FD constructed
   by GLXFIL after the file is opened.

    Accepts        S1/  The IFN
                   S2/  0 to obtain a copy of the original FD
                                      or
                       -1 to obtain an exact FD for the file

    Returns TRUE   S1/  address of the desired FD

                                    3-19
   GLXLIB ROUTINE DESCRIPTIONS
   GLXFIL - Disk File Input/Output Routines


   3.2.4.17  F%DEL

   F%DEL is called to delete a file without having to open it first.  The
   call  provides  a  FOB  which  allows for specification of the "in his
   behalf" field is so desired.

    Accepts        S1/  Length of FOB (FOB.FD is only required word)
                   S2/  Address of FOB

    Returns TRUE   S1/  File has been deleted

            FALSE  S1/  Error code


   Possible Errors:  ERSLE$  ERFNF$  ERPRT$






































                                    3-20
                                              GLXLIB ROUTINE DESCRIPTIONS
                                                  GLXIPC - IPCF Interface


   3.3  GLXIPC - IPCF Interface

   3.3.1  Purpose

   GLXIPC  provides  a  system  independent  IPCF  interface  for  serial
   receiving  and  sending  of  messages.   Format of argument blocks and
   error codes are contained in the GLXMAC universal file.



   3.3.2  Global Routines

   The following global routines exist in GLXIPC:

            C%RPRM - Read IPCF parameters

            C%RECV - Receive an IPCF message

            C%BRCV - Blocking IPCF receive

            C%REL  - Release space for last message

            C%SEND - Send an IPCF message

            C%INTR - Flag an IPCF interrupt




   3.3.2.1  C%RPRM

   This routine is called to read IPCF parameters such as number of  PIDS
   allowed  and send/receive quotas.  It can also be used to find the PID
   of any system-wide component.

    Accepts        S1/ -1 to read quotas
                              or
                       SP.xXX to return PID of that component

    Returns TRUE   S1/  <MAX # PIDS>,,<sendquota>B26+<rcvquota>B35
                              or
                        PID of requested system component

            FALSE  An illegal system PID index was supplied









                                    3-21
   GLXLIB ROUTINE DESCRIPTIONS
   GLXIPC - IPCF Interface


   3.3.2.2  C%RECV

   This routine is used to do a non-blocking receive of one IPCF message.
   Upon successful return, the address of a Message Descriptor Block (See
   MDB in GLXMAC) is  returned.   The  MDB  and  the  data  received  are
   available  until  C%REL  is  called  or another receive is done.  This
   routine returns an error if no messages are available for receipt.

    Accepts        No arguments

    Returns TRUE   S1/  Address of the MDB

            FALSE  S1/  Error code


   Possible Errors:  ERNMA$



   3.3.2.3  C%BRCV

   This routine is identical to C%RECV  except  that  if  no  message  is
   available the routine waits until one is available before returning.

    Accepts        No arguments

    Returns TRUE   S1/  Address of the MDB




   3.3.2.4  C%REL

   C%REL releases the last IPCF message received.  If the message  was  a
   page  mode  message,  M%RELP  is called to return the page to the free
   pool.  Releasing the same message twice or releasing a message  before
   one has been received will cause a stopcode.

    Accepts        No arguments

    Returns TRUE   always












                                    3-22
                                              GLXLIB ROUTINE DESCRIPTIONS
                                                  GLXIPC - IPCF Interface


   3.3.2.5  C%SEND

   C%SEND is called to send an IPCF message  to  a  specified  PID.   The
   method  by which the message is sent is based on its length (which may
   be between 1 and 512 words).  If the specified  length  is  1000,  the
   message  is assumed to be page aligned and is sent as a paged message.
   If the specified length is less than or equal to  the  maximum  "short
   packet"  length,  the  message  is  sent  as  a  short packet.  If the
   specified length is greater than the maximum "short" packet  size  and
   not  equal  to 1000, a page is acquired, the message is transferred to
   the page and a page message is sent.  Arguments are passed  to  C%SEND
   via a Send Argument Block (see SAB in GLXMAC).

   If the IPCF Send fails and the failure is one that warrants  a  re-try
   (e.g.   send/receive  quotas etc.) then C%SEND will re-try a number of
   times (five, for now) with a three second sleep between  tries  unless
   the IP.RSE bit is set in the Initialization Block word IB.IPC in which
   case the send failure is returned immediately.

    Accepts        S1/  Length of the Send Argument Block (SAB)
                   S2/  the address of the SAB (see GLXMAC)

    Returns TRUE   on successful send

            FALSE  S1/  Error code


   Possible Errors:  ERNSP$ ERSLE$ ERRQF$ ERSQF$ ERUSE$



   3.3.2.6  C%INTR

   This routine is called by programs using the software interrupt system
   to  keep  track of the arrival of IPCF messages.  To call this routine
   the initialization call  must  have  indicated  that  interrupts  were
   expected.   Note  that S1, S2, and TF must be saved at interrupt level
   before calling C%INTR.

    Accepts        no arguments

    Returns TRUE   always











                                    3-23
   GLXLIB ROUTINE DESCRIPTIONS
   GLXLNK - Linked-list facilities


   3.4  GLXLNK - Linked-list facilities

   3.4.1  Description

   GLXLNK provides a  facility  for  manipulating  lists.   Programs  can
   create lists, create and destroy entries within a list and position to
   various entries.  When a list is created a  list  index  is  returned.
   This  handle  is  one of the arguments to all the other routines which
   manipulate the list.

   To maintain the integrity of the linked-list facility, no  routine  is
   ever  called  with  an  address.   To accomplish this, each list has a
   "CURRENT entry field" associated with it.  All  list  manipulation  is
   done  with  respect to the entry which is CURRENT (i.e.  whose address
   is in the CURRENT entry field).  Positioning  a  list  actually  means
   changing  which  entry  is  CURRENT.   Various other list manipulation
   routines also change which entry is CURRENT.  Most routines return the
   address  of  the  CURRENT entry.  It is allowable however to store the
   address of an entry and use that address even when the  entry  is  not
   CURRENT.   As  long  as an entry is not destroyed its address will not
   change.

   There are two cases in which a list has no CURRENT entry.  One case is
   when  the  list  is empty, and the other is 'after' deleting the first
   entry in the list.  Most routines will return an error if  NO  CURRENT
   is  set  (and a CURRENT entry is required for the manipulation), but a
   few routines (e.g.  L%NEXT and L%CENT) do special things in this case.
   The descriptions of the various routines describe this.



   3.4.2  Global Routines

   The following global routines exist in GLXLNK:

            L%CLST - Create a linked-list

            L%DLST - Destroy a linked-list

            L%CENT - Create a list entry 'after' the CURRENT entry

            L%CBFR - Create a list entry 'before' the CURRENT entry

            L%DENT - Delete an entry from a list

            L%NEXT - Position to the NEXT entry

            L%FIRST - Position to the FIRST entry





                                    3-24
                                              GLXLIB ROUTINE DESCRIPTIONS
                                          GLXLNK - Linked-list facilities


            L%LAST - Position to the LAST entry

            L%PREV - Position to the previous entry

            L%CURR - Return the address of the CURRENT entry

            L%SIZE - Return the size of the CURRENT entry

            L%RENT - Remember the address of the CURRENT entry

            L%PREM - Position to the REMEMBERED entry

            L%APOS - Position to an entry given its address




   3.4.2.1  L%CLST

   This routine is called to create a  list.   The  calling  program  may
   create  as  many  different lists as it requires.  The list index will
   always be a non-zero value.

    Accepts        No arguments

    Returns TRUE   S1/  The list index




   3.4.2.2  L%DLST

   L%DLST is called to destroy a list.  When a  list  is  destroyed,  all
   entries remaining in the list are deleted first.

    Accepts        S1/  list index

    Returns TRUE   always















                                    3-25
   GLXLIB ROUTINE DESCRIPTIONS
   GLXLNK - Linked-list facilities


   3.4.2.3  L%CENT

   L%CENT is the routine which creates entries  in  a  linked-list.   The
   created  entry is linked-in "after" the CURRENT entry.  If there is NO
   CURRENT entry, the entry is created at the beginning of the list.   In
   all cases the created entry becomes the CURRENT.

    Accepts        S1/  list index
                   S2/  entry size

    Returns TRUE   S1/  list index
                   S2/  address of CURRENT (new) entry




   3.4.2.4  L%CBFR

   L%CBFR is an additional routine to create an entry  in  a  list.   Its
   primary  use is when the list is ordered and an entry is to be created
   in the middle.  In this case the program usually scans the list  until
   an  entry  is found whose 'list-order attribute' is worse than the one
   to be created, and the new one must be inserted 'before' it.

    Accepts        S1/  list index
                   S2/  entry size

    Returns TRUE   S1/  list index
                   S2/  address of CURRENT (new) entry

            FALSE  S1/  error code


   Possible Errors:  ERNCE$



















                                    3-26
                                              GLXLIB ROUTINE DESCRIPTIONS
                                          GLXLNK - Linked-list facilities


   3.4.2.5  L%NEXT

   L%NEXT is the list positioning routine used to position to the  'next'
   entry  in  a  list  with respect to the CURRENT entry.  If there is NO
   CURRENT entry, L%NEXT will position to the 'first' entry in  the  list
   or  return  an  error  if  the  list  is  empty  (i.e.  L%NEXT becomes
   equivalent to L%FIRST).

    Accepts        S1/  list index

    Returns TRUE   S1/  list index
                   S2/  address of CURRENT entry

            FALSE  S1/  error code


   Possible Errors:  EREOL$



   3.4.2.6  L%DENT

   L%DENT is called to delete the CURRENT entry from the list.  After the
   entry  is deleted, the deleted entry's predecessor becomes the CURRENT
   entry.  If the deleted entry was the first entry in the  list,  it  is
   deleted but NO CURRENT is set for the list.

   Given the described operation of L%DENT, in all cases if an  entry  is
   deleted and then L%CENT is called to create a new entry, the new entry
   will occupy the same position in the list as the deleted entry.  Also,
   if  a program is scanning a list (using L%NEXT), then the 'next' entry
   can always be positioned to using L%NEXT  regardless  of  whether  the
   CURRENT entry is deleted or merely passed over.

    Accepts        S1/  list index

    Returns TRUE   S1/ list index

            FALSE  S1/ error code


   Possible Errors:  ERNCE$



   3.4.2.7  L%FIRST

   L%FIRST is called to position to the FIRST entry in the list.

    Accepts        S1/  list index

    Returns TRUE   S1/  list index

                                    3-27
   GLXLIB ROUTINE DESCRIPTIONS
   GLXLNK - Linked-list facilities


                   S2/  address of CURRENT (FIRST)

            FALSE  S1/  Error code


   Possible Errors:  EREOL$



   3.4.2.8  L%LAST

   L%LAST is called to position to the LAST entry in the list.

    Accepts        S1/  list index

    Returns TRUE   S1/  list index
                   S2/  address of CURRENT (LAST)

            FALSE  Error code


   Possible Errors:  EREOL$



   3.4.2.9  L%PREV

   L%PREV is called to position the the PREVIOUS entry in the list,  i.e.
   the predecessor to the CURRENT.

    Accepts        S1/  list index

    Returns TRUE   S1/  list index
                   S2/  address of CURRENT

            FALSE  S1/  Error code


   Possible Errors:  ERBOL$ ERNCE$



   3.4.2.10  L%CURR

   L%CURR is a utility routine which merely returns the  address  of  the
   CURRENT entry.  It is sort of like "position to CURRENT".

    Accepts        S1/  list index

    Returns TRUE   S1/  list index
                   S2/  address of CURRENT


                                    3-28
                                              GLXLIB ROUTINE DESCRIPTIONS
                                          GLXLNK - Linked-list facilities


            FALSE  S1/  Error code


   Possible Errors:  ERNCE$



   3.4.2.11  L%SIZE

   L%SIZE is a utility routine  which  will  return  the  "size"  of  the
   CURRENT entry (i.e.  the size specified when the entry was created).

    Accepts        S1/  list index

    Returns TRUE   S1/  list index
                   S2/  size in words


            FALSE  S1/  Error code


   Possible Errors:  ERNCE$



   3.4.2.12  L%RENT

   L%RENT allows the caller to 'save away' a pointer to the CURRENT entry
   in  a  list  hence  allowing  the  list to be positioned elsewhere but
   remaining able to reference the 'remembered' entry by calling one of a
   number of routines for that purpose.

    Accepts        S1/  list index

    Returns TRUE   S1/  list index
                   S2/  address of CURRENT entry

            FALSE  S1/  error code


   Possible Errors:  ERNCE$



   3.4.2.13  L%PREM

   This routine allows re-positioning to an entry 'remembered' by L%RENT.

    Accepts        S1/  list index

    Returns TRUE   S1/  list index
                   S2/  address of CURRENT (remembered) entry

                                    3-29
   GLXLIB ROUTINE DESCRIPTIONS
   GLXLNK - Linked-list facilities


            FALSE  S1/  error code


   Possible Errors:  ERNRE$



   3.4.2.14  L%APOS

   This routine allows re-positioning to an entry by its Address.

    Accepts        S1/  List index
                   S2/  The Entry Address

    Returns TRUE   S1/  List index
                   S2/  The Entry Address

            FALSE  ENF Stopcode



































                                    3-30
                                              GLXLIB ROUTINE DESCRIPTIONS
                                       GLXTXT - Formatted ASCII Functions


   3.5  GLXTXT - Formatted ASCII Functions

   3.5.1  Description

   The GLXTXT module provides a  comprehensive  set  of  subroutines  for
   formatting  ASCII  strings.  The principle facility provided by GLXTXT
   is embodied in the $TEXT macro as described in a previous  section  of
   this document.

   The global subroutines provided in GLXTXT (except for T%TEXT)  provide
   a number of useful output routines for $TEXT calls.



   3.5.2  Global Routines

   The following global routines exist in GLXTXT.

            T%TEXT - Main $TEXT entry point

            T%TTY - Output routine to terminal




   3.5.2.1  T%TEXT

   The T%TEXT subroutine is the entry point which is called by the  $TEXT
   macro.   The  argument  block is generated in line by the $TEXT and is
   not in a standard format.  This  entry  point  should  not  be  called
   directly by a user program.



   3.5.2.2  T%TTY

   T%TTY is a subroutine which is provided to act as a  $TEXT  subroutine
   (i.e.  called with each decoded character) to print the decoded string
   on the job's controlling terminal.  T%TTY provides  line-buffering  of
   the terminal output for efficiency.













                                    3-31
   GLXLIB ROUTINE DESCRIPTIONS
   GLXINT - Common Operating System Functions


   3.6  GLXINT - Common Operating System Functions

   3.6.1  Description

   3.6.2  Global Routines

   The following global routines exist in GLXINT.

            I%INIT - Library initialization

            I%NOW  - Return current date and time

            I%EXIT - Program exit

            I%SLP  - Suspend this process for a given time

            I%TIMR - Request or delete a timer event

            I%ION  - Turn on the interrupt system

            I%IOFF - Turn off the interrupt system

            I%SOPR - Send an IPCF message to ORION

            I%WTO  - Support code for $WTO, $WTOR, $LOG and $ACK macros

            I%JINF - Return general job information

            I%HOST - Return the node of the central site
























                                    3-32
                                              GLXLIB ROUTINE DESCRIPTIONS
                               GLXINT - Common Operating System Functions


   3.6.2.1  I%INIT

   This routine  must  be  called  during  program  initilization  before
   calling  any  other library routines.  This routine is responsible for
   merging GLXLIB  into  the  calling  programs  address  space  and  for
   performing general library initilization.

    Accepts       S1/  Length of the IB
                  S2/  Address of the IB

    Returns TRUE always

   The format of the Initialization Block is:


           !=======================================================!
    IB.OUT !    Address of default $TEXT output routine (~TOR)      !
           !-------------------------------------------------------!
    IB.FLG !    Initialization flags                               !
           !-------------------------------------------------------!
    IB.INT !    Address of interrupt control vector                !
           !-------------------------------------------------------!
    IB.PIB !    Address of Pid initialization block  (~PIB)         !
           !-------------------------------------------------------!
    IB.ERR !    Address of $TEXT error exit routine                !
           !-------------------------------------------------------!
    IB.PGR !           Sixbit Program Name                         !
           !=======================================================!
    

   The following flags are defined in IB.FLG

            IT.OCT  Perform an open on the  controlling  terminal  during
            initialization.

            IP.STP  Send Stopcode information to the operator




   3.6.2.2  I%NOW

   I%NOW returns the current date and time in universal date/time format.
   Each increment is approximately 1/3 of a second.

    Accepts        No arguments

    Returns TRUE   S1/  Current date and time





                                    3-33
   GLXLIB ROUTINE DESCRIPTIONS
   GLXINT - Common Operating System Functions


   3.6.2.3  I%EXIT

   This routine provides a non-continuable termination mechanism for  the
   calling  process.   On  TOPS10 this routine check to see if the job is
   logged in.  If not the routine  will  display  the  KJOB  message  and
   perform a LOGOUT uuo.

    Accepts        No arguments

    Does not return




   3.6.2.4  I%HOST

   This routine returns the node name and number of the central site

    Accepts        No arguments

    Returns TRUE   S1/ Sixbit central site node name
                   S2/ Octal central site node number




   3.6.2.5  I%SLP

   I%SLP provides a mechanism for  suspending  process  execution  for  a
   given  time or until an interrupt occurs.  Note that I%SLP will return
   immediatly if an interrupt has occurred since the  last  time  it  was
   called.   Also the use of the I%TIMR facility may cause an event to be
   processed during a call to I%SLP.  (Refer  to  I%TIMR)  An  additional
   function  on  TOPS10  is  to wake up on special events.  The currently
   supported events (indicated by flags) are wakeup  on  character  input
   and wakeup on PTY input.

    Accepts        S1/ Flags ,, Number of seconds to sleep (1 to 60)
                                          or
                          0 to sleep until an interrupt/event occurs

    Returns TRUE   always

                   S1/ Next timer wakeup time (if any)
                   All other AC's are preserved








                                    3-34
                                              GLXLIB ROUTINE DESCRIPTIONS
                               GLXINT - Common Operating System Functions


   3.6.2.6  I%TIMR

   This routine allows the caller to make timer requests  which  will  be
   placed on a timer event queue.  This routine works in conjunction with
   I%SLP so that interrupts  are  in  effect  'simulated'.   If  a  timer
   requests  exists  on  the  timer queue when I%SLP is called it will be
   checked to see if it is time to process the request.  I%SLP  will  not
   allow  the  caller  to  sleep  past  the requested event time.  If the
   caller has placed the address of a routine to process the event in the
   PC  word of the timer request block, the routine will be called within
   the call to I%SLP with S1 containing the length of the  request  block
   and  S2  containing  the address of the block.  The processing routine
   may use S1-S2 and T1-T4 without preserving them.

    Accepts        S1/ Length of request block
                   S2/ Address of request block

    Returns TRUE   S1/ Length of new timer request
                   S2/ Address of new timer request

                             or

    Accepts        S1/ 0 to return current timer event

    Returns TRUE   S1/ Length of current request block
                   S2/ Address of current request block

                             or

    Accepts        S1/ -1 to return next wakeup time

    Returns TRUE   S1/ timer list index
                   S2/ next timer event UDT


   The format of the Timer Request Block is:

           !=======================================================!
    .TIFNC !       (Reserved)        !      Requested function     !
           !-------------------------------------------------------!
    .TITIM !                  UDT or MS until event                !
           !-------------------------------------------------------!
    .TIPSI !                     (Reserved)                        !
           !-------------------------------------------------------!
    .TIMPC !         Address of routine to process event           !
           !-------------------------------------------------------!
    .TIDAT /          Optional data supplied for event             /
           !=======================================================!





                                    3-35
   GLXLIB ROUTINE DESCRIPTIONS
   GLXINT - Common Operating System Functions



    The requested functions are:

           .TIMRT          Interrupt after n milliseconds
                           of runtime (reserved)

           .TIMEL          Add a request to occur after n
                           milliseconds

           .TIMDT          Add a request to occur at a
                           specific UDT

           .TIMDD          Remove all requests for this
                           processor at a specific UDT

           .TIMBF          Remove all requests for this
                           processor before a specific UDT

           .TIMAL          Remove all requests for all
                           processors

    Possible errors:

           ERTMN$          No timer entry has expired
           ERTMA$          Timer entry already exists
           ERNCI$          Argument block may not be in the ACs




   3.6.2.7  I%IOFF

   I%IOFF is used to temporarily disable all software interrupts.  If  an
   interrupt condition occurs while interrupts are disable, the condition
   will remain pending and the interrupt will be granted upon re-enabling
   interrupts (via I%ION).

    Accepts        No arguments

    Returns TRUE   always




   3.6.2.8  I%ION

   This routine is used to enable the software interrupt system after  it
   has been setup (by I%INIT) or after it has been disabled (by I%IOFF).

    Accepts        No arguments

    Returns TRUE   always

                                    3-36
                                              GLXLIB ROUTINE DESCRIPTIONS
                               GLXINT - Common Operating System Functions


   3.6.2.9  I%SOPR

   Sends a prebuilt page size message to ORION

    Accepts        S1/ Address of page containing message




   3.6.2.10  I%WTO

   Support routines for $WTO, $WTOR, $LOG and $ACK macros



   3.6.2.11  I%JINF

   I%JINF is provided as  an  operating  system  independent  method  for
   obtaining   information  about  jobs  on  the  system.   Although  the
   interface is independent of the operating system, there are  obviously
   some  pieces  of  useful  job  related  information  that  are  system
   specific.


    Accepts        S1/ Job number or -1 for self
                   S2/ Item specifier

                           JI.JNO          Job number
                           JI.TNO          Terminal number
                           JI.USR          PPN or USER number
                           JI.CDN          Connected directory number
                           JI.PRG          Sixbit program name
                           JI.CJN          Controlling job number
                           JI.BAT          Batch data word
                           JI.JLT          Job logged in time
                           JI.LOC          Sixbit node where job is located
                           JI.RTM          Job runtime in milliseconds

    Returns TRUE   S1/ Unchanged
                   S2/ Requested information

            FALSE  S1/  error code


   Possible Errors:  ERARG$








                                    3-37
   GLXLIB ROUTINE DESCRIPTIONS
   GLXKBD - Keyboard (terminal) routines


   3.7  GLXKBD - Keyboard (terminal) routines

   3.7.1  Description

   The GLXKBD module contains a set  of  routines  for  doing  input  and
   output to a job's controlling timesharing terminal.



   3.7.2  Global Routines

   The following global routines exist in GLXKBD:

            K%STYP - Set terminal type

            K%SOUT - Output a string to the terminal

            K%BOUT - Output one character to the terminal

            K%BIN - Read one character from the terminal

            K%BACK - Back up the terminal input by one character

            K%TXTI - Read a string of characters from the terminal




   3.8  GLXSCN - COMMAND SCANNING ROUTINES

   3.8.1  Description

   The GLXSCN module contains a  set  of  routines  to  simplify  command
   parsing.   The  routines  declared  in GLXSCN are not generally called
   directly from your program.  Rather, they are called by  OPRPAR  which
   may  be loaded with your program if you have a need to parse commands.
   The major routine is S%CMND which impliments a  subset  of  the  COMND
   JSYS functionallity native to TOPS20.



   3.8.2  Global Routines

   The following global routines exist in GLXSCN:

            S%CMND - Parse a single command field.  It is not recommended
            that  your  program  call  this  routine  directly  since the
            functionallity on TOPS10 is likely to  change.   Rather  your
            program  should  define  it's command syntax using the macros
            defined in GLXMAC and use the loadable module  OPRPAR  to  do
            the actual command parsing.  (Refer to Appendix B)


                                    3-38
                                              GLXLIB ROUTINE DESCRIPTIONS
                                       GLXSCN - COMMAND SCANNING ROUTINES


            S%SIXB - Convert ASCII string to SIXBIT value

            S%NUMI - Convert ASCII string to integer value

            S%TBLK - Lookup entry in table

            S%TBAD - Add entry to table

            S%TBDL - Delete entry from table

            S%SCMP - Compare to ASCII strings

            S%DATI - Parse an ASCII date/time




   3.8.2.1  S%SIXB

   This routine is called to return the sixbit value of an  ASCII  string
   expression.   Any  non  sixbit character will terminate the parse.  If
   more than six characters are seen the parse will terminate at the  end
   of the sixth character
    Accepts        S1/ Pointer to ASCII string

    Returns TRUE   S1/ Updated pointer
                   S2/ Sixbit value




   3.8.2.2  S%NUMI

   This routine is called to return the integer value of an ASCIZ  string
   expression.   The  string  may be preceeded by any number of spaces or
   tabs and my have one Plus (+) or one Minus (-) sign.

    Accepts        S1/ Pointer to the string
                   S2/ Radix (2 to 10)

    Returns TRUE   S1/ Updated pointer to first non numeric
                   S2/ 36 bit signed integer

   Errors: ERRAD$  Invalid radix
           ERNUM$  Invalid number








                                    3-39
   GLXLIB ROUTINE DESCRIPTIONS
   GLXSCN - COMMAND SCANNING ROUTINES


   3.8.2.3  S%DATI

   This routine is called to return a UDT which represents the  value  of
   the ASCII date/time.

    Accepts        S1/ Pointer to the string
                   S2/ CM%IDA!CM%ITM!CM%NCI+address

    Flags in S2 are:

           CM%IDA  Input a date
           CM%ITM  Input a time
           CM%NCI  Return the non converted date time in the
                   three word argument block at address


    Returns TRUE   S1/ Updated pointer
                   S2/ UDT

   Errors: ERIDT$  Invalid date time

































                                    3-40
                                              GLXLIB ROUTINE DESCRIPTIONS
                                           GLXCOM - GLXLIB Utility Module


   3.9  GLXCOM - GLXLIB Utility Module

   3.9.1  Description

   The GLXCOM module does not provide a single 'facility' as do the other
   GLXLIB  modules.   This  module contains a number of minor subroutines
   (almost all are unconditionally operating  system  independent)  which
   are  of  value in virtually every program.  The subroutines are broken
   down into classes and each class as well as each subroutine within  it
   is described.



   3.9.2  Global Routines

   Accumulator save/restore routines

            .SAVE1-4 - Saves P1 or P1-P2 or P1-P3 or P1-P4

            .SAVET   - Saves T1-T4

   Zeroing memory

            .ZPAGA   - Zeros a page given its address

            .ZPAGN   - Zeros a page given its number

            .ZCHNK   - Zeros a chunk of arbitrary size

   Returns

            .RETT    - Sets TF to TRUE and returns

            .RETF    - Sets TF to FALSE and returns

            .POPJ    - Returns without disturbing TF




   3.9.2.1  .SAVE1, .SAVE2, .SAVE3, .SAVE4

   These four routines are co-routines which can be used to  save  the  P
   accumulators  (P1,  P2,  P3,  and  P4).   They  are  called  as normal
   subroutines, but return by calling the caller so that when the  caller
   returns  (to his caller) the rest of the .SAVEx subroutine is executed
   to restore the saved accumulators.  The .SAVEx routines do not  change
   the  contents  of  any accumulator other than the pushdown pointer, P.
   .SAVE1 saves P1, .SAVE2 saves P1 and P2,  .SAVE3  saves  P1,  P2,  P3,
   .SAVE4 save all four "P"reserved accumulators.



                                    3-41
   GLXLIB ROUTINE DESCRIPTIONS
   GLXCOM - GLXLIB Utility Module


   3.9.2.2  .SAVET

   This subroutine is identical to the .SAVE4 subroutine described  above
   except that it is called to save the four "T"emporary accumulators, T1
   through T4 rather than the "P" accumulators.



   3.9.2.3  .ZPAGA

   The .ZPAGA routine is used to completely zero the contents of  a  page
   given the address of the first word.

    Accepts        S1/  Address of the page

    Returns TRUE   always




   3.9.2.4  .ZPAGN

   The .ZPAGN routine is used to completely zero the contents of  a  page
   given the page number.

    Accepts        S1/  The page number

    Returns TRUE   always




   3.9.2.5  .ZCHNK

   .ZCHNK is used to zero any arbitrary block of memory.

    Accepts        S1/  Length of the chunk
                   S2/  Address of the first word





   3.9.2.6  .RETT

   .RETT is a utility which implements a  subroutine  return.   .RETT  is
   branched  to  by  a  routine to cause a return to the routine's caller
   with the true/false indicated (accumulator TF) set to TRUE.  The $RETT
   macro  is provided for returning success, but a branch to .RETT can be
   used in conjunction with a test (e.g.  JUMPL AC,.RETT).



                                    3-42
                                              GLXLIB ROUTINE DESCRIPTIONS
                                           GLXCOM - GLXLIB Utility Module


   3.9.2.7  .RETF

   This routine is just like the .RETT  routine  described  above  except
   that it is used to return FALSE or failure rather than success.



   3.9.2.8  .POPJ

   .POPJ is merely a convenience routine which  can  be  branched  to  to
   effect  a  subroutine  POPJ return.  .POPJ does not have any effect on
   the TRUE/FALSE indicator and hence should only be used  (and  this  is
   true  of  POPJ  in  general) when it is desired to pass the TRUE/FALSE
   indicator  up  from  a  lower  level  subroutine.   Similar   to   the
   $RETT/.RETT and $RETF/.RETF pairs, .POPJ should be used in conjunction
   with some sort of  conditional  instruction  (e.g.   JUMPGE  T1,.POPJ)
   since a simple POPJ P, could be used otherwise.




































                                    3-43











                                 CHAPTER 4

                               DEBUGGING AIDS










































                                    4-1











                                 CHAPTER 5

                         INSIDE THE GALAXY LIBRARY



   5.1  Introduction

   This chapter is primarily intended for people who will  be  modifying,
   developing,  and/or  maintaining  the GALAXY library rather than using
   it.



   5.2  Guidelines for adding new modules

   Guidelines are necessary for adding new modules for several reasons.

   Given the goals of GLXLIB, adding modules which will only be  used  by
   one  program  is  not  normally useful.  Before a new module is added,
   there should be a need for its functionality in at least two programs.

   Before adding a module, it is the responsibility of the programmer  to
   decide  whether  there  is similar functionality in any other existing
   GLXLIB modules, and if so, to code the new module to call  appropriate
   routines  in  the  existing module or vice versa (the module with more
   "specific" functionality should always call the module with  the  more
   "general" functionality).

   ***more***















                                    5-1
   INSIDE THE GALAXY LIBRARY
   Module Conventions


   5.3  Module Conventions

   5.3.1  Symbol Naming Conventions

   5.3.1.1  Global Subroutines

   The names of all global subroutines in GLXLIB are of the form(1):

                                   x%yyyy

   where 'x' is a single alphabetic representing the module (each  module
   is assigned a letter) and 'yyyy' is a three or four character mnemonic
   for the routine.



   5.3.1.2  Local Names

   Conventions for local symbol names are  not  quite  as  important  nor
   inviolable  as  those for global symbol names since they do not affect
   the external interface.



   5.3.2  Error Conditions

   When coding a routine in GLXLIB a  decision  must  be  made  for  each
   exceptional  condition  whether  to  return  an error code or to stop.
   ***more***



















   --------------------
   (1)  The routines in the GLXCOM module do not follow a number  of  the
   conventions  listed  in this section.  See the section on GLXCOM for a
   discussion of this.

                                    5-2
                                                INSIDE THE GALAXY LIBRARY
                                       Physical Layout of a GLXLIB Module


   5.4  Physical Layout of a GLXLIB Module

   5.4.1  Overview of Module layout

   Each module in GLXLIB contains the following parts:

         o  Title Page

         o  Table of Contents

         o  Revision History

         o  Module-wide Storage

         o  Global Routines

         o  Local Routines

   These sections will appear in every module  in  the  order  specified.
   Each is described in the following sections.

































                                    5-3
   INSIDE THE GALAXY LIBRARY
   Physical Layout of a GLXLIB Module


   5.4.1.1  Title Page

   The following  template  describes  the  Title  Page  for  all  GLXLIB
   modules.



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



   TITLE   GLXYYY  --  title of module
   SUBTTL  AUTHOR'S name   date last edited

   ;Copyright (C) 1976,1977,
   ;       Digital Equipment Corporation, Maynard, MA.


           SEARCH  GLXMAC                ;GLXLIB SYMBOLS AND MACROS


           PROLOG(GLXYYY)                ;GENERATE NECESSARY SEARCHES


           yyyEDT==:N                    ;MODULE EDIT LEVEL





   ;Short description of the module (3-4 lines) as well as any other
   ;       information which might be of interest to the reader
   ;       such as special AC conventions, debugging aids etc.



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




   5.4.1.2  Table of Contents

   This page should contain  a  table  of  contents  for  the  module  as
   produced by the TOC program.








                                    5-4
                                                INSIDE THE GALAXY LIBRARY
                                       Physical Layout of a GLXLIB Module


   5.4.1.3  Revision History

   Each time the module is edited to fix a bug or add a feature, the edit
   level  (symbol  yyyEDT on the Title Page) should be incremented and an
   entry should be appended to the existing revision history with the new
   edit number and what was done during the edit.

   The format for each entry in the revision history is:

   ;<edit nbr> Description of the edit.  The description should
   ;  include SPR or QAR number etc.



   5.4.1.4  Module-wide Storage

   Use of global storage within a module (storage used by more  than  one
   subroutine)  should  be  discouraged  on  general  principles.   It is
   however necessary to set up various global  tables,  vectors,  indices
   etc.  This module-wide storage should all be allocated in one place on
   the page(s) immediately following  the  revision  history  and  should
   (whenever possible) be allocated using $DATA and $GDATA statements.



   5.4.1.5  Global Routines

   Each global routine will start on a new page.  The routine will  start
   with a header which is formatted as in the following example:


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


   SUBTTL  F%AOPN  --  Open an output file in append mode

   ; F%AOPN is really a special case of F%OOPN, with some
   ;  positioning and set up done after the F%OOPN call.

   ;Accepts        S1/  length of file open block (FOB)
   ;               S2/  address of FOB (described in GLXMAC)
   ;
   ;Returns TRUE   S1/  IFN
   ;
   ;Errors:        ERSLE$  System limits exceeded
   ;               ERIFS$  Invalid file structure
   ;               ERPRT$  Protection failure

           ENTRY   F%AOPN




                                    5-5
   INSIDE THE GALAXY LIBRARY
   Physical Layout of a GLXLIB Module


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


   Following the header is the routine body.



   5.4.1.6  Local Routines

   Local routines should generally be gathered together after the  global
   routines.  If a local routine is specifically written for a particular
   global routine it is acceptable for the local routine  to  follow  the
   global routine (on the next page).








































                                    5-6











                                 CHAPTER 6

                      GALAXY LINE AND PAGE CONVENTIONS



   6.1  Introduction

   The purpose of this  section  is  to  provide  guidelines  for  people
   planning  to  write  code for the GALAXY system.  A set of conventions
   are presented  below  for  the  actual  format  of  assembly  language
   instructions  and  for  the  usage  of  a  number  of  the more common
   facilities provided by the MACRO assembler.

   Obviously, not all of the circumstances that will be encountered while
   writing  code  are  covered here, but the more common ones are covered
   and these should in most cases provide guidance for the other cases.

   These conventions apply to ALL code written for the GALAXY system, not
   just  the  library.   All newly coded programs should be written using
   these conventions.  Any  development  done  on  pre-existing  software
   should follow these conventions whenever possible.



   6.2  Instruction format

   6.2.1  Tags

   Indiscriminate use of tags should be avoided.  Tags should be used  on
   all locations which will be referenced by an instruction.  A tag which
   shows up in a CREF with only its definition line is a prime choice for
   removal.

   It is in some circumstances reasonable to use 'unrefereced' tags.  The
   principle  reason  for  using an unreferenced tag is to make debugging
   easier.  Tags may be placed in  the  middle  of  a  long  sequence  of
   straight  line  code,  for  example, or more generally in places which
   seem like important break-point locations.

   Tags should always start in column 1 of  a  line  and  be  immediately
   terminated  by  a  colon.  Tags should usually be 1 to 6 characters in
   length.  It is acceptable to  have  an  entry  point  tag  exceed  six
   characters   if   the  name  is  a  descriptive  English  word  (.e.g.

                                    6-1
   GALAXY LINE AND PAGE CONVENTIONS
   Instruction format


   Q$CHECKPOINT).  If the tag is  more  than  six  characters  long,  the
   terminating  colon should be immediately followed by a carraige-return
   linefeed.



   6.2.2  Operator

   The operator field is one that must exist in  all  instructions.   The
   operator must be from one of the following groups of symbols:

         o  A valid instruction from the KI-10 order code

         o  A valid monitor call

         o  A GALAXY-defined pseudo-instruction or macro

         o  Any other program or system defined macro

         o  A valid assembler pseudo-op

   The operator field may not contain a numeric quantity.

   The operator field begins at the first tab stop (column 9)  except  in
   one  specific  case;  if the instruction has a six character tag on it
   which has a two-character terminator (e.g.  ::  or :!) the  tag  field
   will  be  terminated  by  a  space rather than a tab, and the operator
   field will begin in column 10.

























                                    6-2
                                         GALAXY LINE AND PAGE CONVENTIONS
                                                       Instruction format


   6.2.3  Accumulator field

   Accumlator specifications should always be symbolic  except  in  cases
   where  symbolic  specification  actually implies an expected value for
   the  symbol.   There  are  two  common  situations  where  a  symbolic
   accumulator  specification  shouldn't  be  used.   The  first  case is
   exemplified by the following example:


           MOVEM   0,SAVE+0                ;SAVE AC 0
           MOVE    0,[XWD 1,17]            ;BLT POINTER FOR THE REST
           BLT     0,SAVE+17               ;SAVE ALL THE ACS


   In this case, using symbolic accumulator names would  be  a  bad  idea
   since  the  actual  accumulator  value  is important.  The second case
   where symbolic accumulator  names  should  not  be  used  is  when  an
   instruction  uses  multiple accumulators which are not all in the same
   group of accumulators (i.e.  S, T, P, etc.).  For example:

           MOVE    S2,DIVIDEND             ;GET THE NUMBER TO DIVIDE
           PUSH    P,S2+1                  ;SAVE AC FOR REMAINDER
           IDIVI   S2,RATE                 ;DO THE DIVISION
           MOVEM   S2+1,REMAINDER          ;SAVE THE REMAINDER
           POP     P,S2+1                  ;AND RESTORE THE AC

   In this case, it should not be assumed that S2+1 is in  fact  T1,  and
   even  if this could be assumed it would obscure the code somewhat.  An
   attempt should be made to avoid this  type  of  situation  however  by
   judicious choice of accumulators.

   Whenever an accumulator field is present in an instruction, it  should
   start at the second tab stop (column 17) and be immediately terminated
   by a comma.



   6.2.4  Address field

   6.2.5  Comment field

   All instructions should be commented.  Comments should be  descriptive
   of  the  FUNCTION  being  performed rather than the physical OPERATION
   being performed.  For example,  on  the  instruction  "ADDI  A,1"  the
   comment  "ADD  ONE  TO  ACCUMULATOR A" is not very useful, whereas the
   comment "INCREMENT THE RECORD COUNTER" is far more useful.

   Comments should immediately follow the comment character,  semi-colon,
   which  should  be  at the fifth tab stop (column 41).  Comments should
   not normally exceed 40 characters in length.



                                    6-3
   GALAXY LINE AND PAGE CONVENTIONS
   Instruction format


   In the cases where a multi-line comment is needed, the second  through
   the  last  line  of the comment should be indented one space after the
   semi-colon (which should still always be at the fifth tab  stop).   In
   cases   where   the   multi-line   comment  describes  a  sequence  of
   instructions, the subsequent comment lines can be on the same lines as
   the subsequent instructions.  For example:


                                      |
     JFFO A,FOO      ;GET THE INDEX   |   CAIL A,"0"  ;SEE IF THE
                     ; AND JUMP IF    |   CAILE A,"9" ; CHARACTER IS
                     ; THERE WAS NONE |   JRST NOTNUM ; NUMERIC
                                      |




   6.3  Macro Calls



































                                    6-4











                                 APPENDIX A

                         GALAXY LIBRARY ERROR CODES







           Error Code      Meaning
           __________      _________________________
           EREOF$          End of file
           ERIFP$          Illegal file position
           ERFDE$          File data error
           ERFND$          File is not on disk
           ERNSD$          No such device
           ERFCF$          File checkpoint failed
           ERSLE$          A system limit was exceeded
           ERIFS$          Illegal file specification
           ERFNF$          File not found
           ERPRT$          Protection violation
           ERDNA$          Device not available
           ERNCE$          No "current" entry in list
           ERNMA$          No IPCF message is available
           ERFDS$          Files are on different structures
           ERFAE$          File already exists
           ERUSE$          Unexpected system error
           ERNSP$          No such PID
           ERBOL$          Beginning of list reached
           EREOL$          End of list reached
           ERRQF$          Receivers quota full
           ERSQF$          Senders quota full
           ERNRE$          No remembered entry
           ERTBF$          Table is full
           EREIT$          Table entry already exists
           ERITE$          Invalid table entry
           ERQEF$          Quota exceeded or disk full
           ERARG$          Invalid argument specified
           ERIFN$          Invalid function specified
           ERIJN$          Invalid job number specified
           ERRAD$          Invalid radix specified
           ERNUM$          Invalid numeric argument
           ERIDT$          Invalid date field specified

                                    A-1
   GALAXY LIBRARY ERROR CODES



           ERITF$          Invalid time field specified
           ERDOR$          Date/time out of range
           ERDTM$          Value missing in date/time
           ERMDD$          Missing day in date/time
           ERDFZ$          Field zero in date/time
           ERMDS$          Mnemonic date/time switch not implemented
           ERDFL$          Field too large in date/time
           ERILR$          Illegal year format in date/time
           ERNND$          Negative number in date/time
           ERNPF$          Not known whether past or future in date/time
           ERRDP$          Relative date parse required
           ERNSW$          Switch does not begin with slash
           ERNOM$          Unrecognized switch or keyword
           ERNUL$          Null switch or keyword given
           ERINW$          Invalid guide word
           ERNC$           Not confirmed
           ERICN$          Invalid character in number
           ERNQS$          Invalid quoted string - does not begin with quote
           ERAMB$          Ambiguous switch or keyword
           ERNMT$          Does not match token
           ERCMA$          Comma not given
           ERNNC$          Node name may not exceed 6 characters
           ERINT$          Node terminator "::" must be specified
           ERNSN$          Unknown node name
           ERIPS$          Invalid path specification
           ERIUS$          Invalid user specification
           ERDGS$          Device name may not exceed 6 characters
           ERDNE$          Unknown device
           ERDIO$          Device can not do input or output
           ERBDF$          Invalid date/time format
           ERABS$          Field too long for internal buffer
           ERTMT$          Command too long for internal buffer
           ERBDS$          Invalid default string
           ERBTF$          Invalid table format
           ERTME$          Date/time must be in the future
           ERTMN$          No timer entry has expired
           ERTMA$          Timer entry already exists
           ERDVT$          Device terminator ":" must be specified
           ERNCI$          Argument block may not be in the ACs














                                    A-2











                                 APPENDIX B

                              GLXLIB STOPCODES






   All GLXLIB Stopcodes are preceeded by a three character  name.   Fatal
   and warning messages are also included in this table and are preceeded
   by a "?" or "%".


   GLXFIL


        CPE   Can't position to EOF

        CRL   Can't read last byte of file

        OTS   File Open Block is too small

        IBS   Illegal byte size given

        FOF   File operation failed unexpectedly

        CTL   Cannot trim LSN in buffered mode

        CSF   Couldn't set file pointer

        RTS   Rename block too small

        UFI   Unknown File Information Descriptor

        FIT   FD location requested with illegal type

        IFN   Illegal IFN provided in call

        IFM   Illegal file mode in subroutine call


   GLXINI


                                    B-1
   GLXLIB STOPCODES



        MUF   MERGE.  UUO Failed


   GLXINT


        CSP   Cannot Activate Panic Channels

        PDL   Pushdown list overflow at PC nnnnnn

        APT   Illegal memory reference at PC nnnnnn

        IST   Illegal Instruction Trap at PC nnnnnn

        IMR   Illegal Memory Read at PC nnnnnn

        IMW   Illegal Memory Write at PC nnnnnn

        CSI   Cannot set up interrupt system

        NIS   No interrupt system set up

        CCI   Cannot change interrupt state

        IN'n  Level n interrupts not supported

        NIP   No interrupt is in progress

        DUF   DEBRK UUO failed

        DTU   Date/Time unavailable

        HUF   HIBER UUO failed

        WFO   WTO Function n Out of range at address nnnnnn

            ? Send to ORION failed


   GLXIPC


            % Packet size n too small.  MAXPAK n

        CGP   Can't Get a PID

            ? Requested Pid belongs to JOB n

            ? No debugging name for special index n

            % Waiting for "pidname" to start


                                    B-2
                                                         GLXLIB STOPCODES



        UIR   Unexpected IPCF interrupt received

        IRF   IPCF Reception failure

        RAR   Releasing already released IPCF message

            ? Can't get a PID

            % Becomming private "pidname" (PID=nnnnnnn)

            ? Can't name the PID.  Error bits = nnn

        PIR   PID Index out of range

            ? Can't write System PID table

        IIF   IPCF to interrupt system connect failed

        AII   Cannot activate IPCF interrupts

        IIF   IPCF to interrupt system connect failed

            ? IPCF privileges required to set maximum number of PIDS

            ? IPCF privileges required to set IPCF quotas

            ? Can't read IPCF quotas

            % Alternate "pidname" (PID = nnnnnn)

        SWP   Called SNDSYS without a PID

            ? Attempt to send to non-existant system component


   GLXKBD


        COT   Cannot OPEN terminal

        BTT   Backing up terminal twice

        TNO   Terminal never opened

        FSE   Fatal System Error

        IBP   Illegal byte pointer in K%TXTI

        IIP   Illegal Input Pointer


   GLXLNK

                                    B-3
   GLXLIB STOPCODES



        ENF   Entry Not Found

        NSL   No such list


   GLXMEM


        PEF   Page existence check failed

        CAC   Count of Available Pages Confused

        RZP   Request for zero pages

        ASE   Addressing space exhausted

        CCP   Cannot create page

        CFC   Count of Free Pages Confused

        PAF   Page access check failed

        RNF   Received non-existent page

        RNW   Ridiculous number of words requested

        ZWR   Zero words of memory returned

        FCN   Free count negative

        FCE   Free count exceeds FREINI

        BPN   Bad page number nnn

        PKF   Page kill failed

        NSO   No pages to swap out

        SOF   Swap out failure


   GLXOTS


        IRE   Illegal routine executed

        ORE   Obsolete routine executed


   GLXPFH



                                    B-4
                                                         GLXLIB STOPCODES



        UPF   Unknown page fault type

        PIF   Page in failure

        CGA   Cannot give access to page

        PFH   GLXPFH is confused

        PDF   Page destroy failed

        SPF   Page out for symbols failed, error code nnnnnn

        NTS   Nothing to swap out

        POF   Page out failure

        CDW   Can't determine working set error = nnnnnn


   GLXSCN


        BFC   Bad function code

        BDS   Bad Default String

        ABS   Atom buffer too small

        TMT   Too much text

        SFP   Scanning floating point not implimented on TOPS10

        IBN   Illegal base for number

        BTF   Bad table format

        UTR   UNRECOGNIZED TABLE ADD RETURN CODE


   GLXTXT


        DOR   Default output routine required

        BTA   Bad $TEXT argument given at address nnnnnn

        IQN   Illegal qualifier number nn at address nnnnnn

        IJU   Invalid user ID in job info block

        TML   Too many levels of call


                                    B-5











                                 APPENDIX C

                           PARSER MODULE (OPRPAR)



   C.1  Function specific macros

   Several fuction specific macros are provided for the  purpose  of
   defining  the  command  syntax  tree.  Each macro generates a PDB
   (Parser data block) which contains an FDB (Function  data  block)
   for  the  specific field and links to the next PDB in the command
   syntax.

   The command syntax is generally terminated  by  a  $CRLF  without
   specifing  a  next  PDB  field.  When calling the parser you must
   specify the first PDB in your command syntax  tree.   The  parser
   will  return  to  you when it encounters a PDB without a next PDB
   field.

         o  $KEY (next_pdb_address,table_address,keyword_list)

         o  $KEYDSP (table_address,keyword_list)

         o  $NUMBER (next_pdb_address,radix,help_text,keyword_list)

         o  $DIGIT (next_pdb_address,radix,help_text,keyword_list)

         o  $NOISE (next_pdb_address,noise_text,keyword_list)

         o  $SWITCH (next_pdb_address,table_address,keyword_list)

         o  $IFILE (next_pdb_address,help_text,keyword_list)

         o  $OFILE (next_pdb_address,help_text,keyword_list)

         o  $FIELD (next_pdb_address,help_text,keyword_list)

         o  $CRLF (keyword_list)

         o  $DIR (next_pdb_address,keyword_list)




                                    C-1
   PARSER MODULE (OPRPAR)
   Function specific macros


         o  $USER (next_pdb_address,keyword_list)

         o  $COMMA (next_pdb_address,keyword_list)

         o  $INIT (next_pdb_address,keyword_list)

         o  $FLOAT (next_pdb_address,help_text,keyword_list)

         o  $DEV (next_pdb_address,keyword_list)

         o  $CTEXT (next_pdb_address,help_text,keyword_list)

         o  $DATE (next_pdb_address,keyword_list)

         o  $TIME (next_pdb_address,keyword_list)

         o  $TAD (next_pdb_address,keyword_list)

         o  $QUOTE (next_pdb_address,help_text,keyword_list)

         o  $TOKEN (next_pdb_address,token_string,keyword_list)

         o  $NODNM (next_pdb_address,help_text,keyword_list)

         o  $ACCOUNT (next_pdb_address,help_text,keyword_list)

         o  $UQSTR (next_pdb_address,BRKSET,help_text,keyword_list)




   C.2  Optional arguments

   Each  of  the  function  specific  macros  accept   an   optional
   keyword_list  as  their  last  argument.   The  following  may be
   specified in this optional keyword_list.


                                 NOTE

                  If more than one argument is to  be
                  supplied  in  the keyword_list, the
                  entire list must be  enclosed  with
                  angle brackets.



         o  $DEFAULT (default_string)





                                    C-2
                                                   PARSER MODULE (OPRPAR)
                                                       Optional arguments


            Specifies the default  string  which  will  be  used  if
            escape is typed for this field.

         o  $PDEFAULT (default_address)

            Specifies the address of the default string  which  will
            be used if escape is typed for this field.

         o  $ALTERNATE (alternate_pdb)

            Specifies the address of an alternate PDB to try if  the
            function specified in this PDB fails to parse.

         o  $NEXT (next_pdb_address)

            Specifies the address of the PDB to be used to parse the
            next field of the command.

         o  $ERROR (error_routine)

            Specifies the address of an error routine which will  be
            called  as  a  co-routine  if this field fails to parse.
            (Note that  $ERROR,  $ERRPDB  and  $ERRTXT  may  not  be
            specified together)

         o  $ERRPDB (nextpdb)

            Specifies the address of a PDB which will  be  tried  if
            this  field  fails to parse.  (Note that $ERROR, $ERRPDB
            and $ERRTXT may not be specified together)

         o  $ERRTXT (error_text)

            Specifies an error string to be returned if  this  field
            fails  to parse.  (Note that $ERROR, $ERRPDB and $ERRTXT
            may not be specified together)

         o  $ACTION (special_action_routine)

            Specifies the address of a routine which will be  called
            as a co-routine after this field parses successfully.

         o  $PREFILL (default_filling_routine)

            Specifies the address of a routine which will be  called
            as  a  co-routine  just  before attempting to parse this
            field.  This allows your program  to  establish  default
            filespecs, etc as the parse proceeds.





                                    C-3
   PARSER MODULE (OPRPAR)
   Optional arguments


         o  $FLAGS (function_flags)

            Specifies non standard flags you  wish  to  include  for
            this field.

         o  $HELP (help_text)

            Specifes fuction specific help information you  wish  to
            display if the user types ?  durring this field.




   C.3  Key and switch table macros

   The following support macros are defined to  allow  the  user  to
   generate  keyword  and  switch  tables.   Note that the user must
   always ensure that the entries are arranged alphabetically.

         o  $STAB and $ETAB

            These macros are used to generate the table header  word
            which contains the count of entries in the table in both
            half words.  The use of these macros  at  the  beginning
            ($STAB)  and end ($ETAB) of the table generates a header
            word with the proper counts at the  location  where  the
            $STAB macro was invoked.

         o  DSPTAB (next_pdb_address,user_code,keyword_entry,flags)

            This macro is commonly used to generate a keyword  table
            entry which declares the address of the next field to be
            parsed.  The DSPTAB macro would be used  to  generate  a
            table pointed to by a $KEYDSP macro.

         o  KEYTAB (user_code,keyword_entry)

            This macro would be used to generate a  table  which  is
            pointed  to  by  a $KEY macro.  An table entry generated
            with the KEYTAB macro does not contain  any  information
            about the next field to be parsed.


   For both the KEYTAB and DSPTAB macros an 18 bit user code may  be
   specified to uniquely identify the keyword which was parsed.

   Following is an example command syntax tree for two  very  simple
   commands:
   INI010: $INIT(KEY010)

   KEY010: $KEYDSP(KEY012)


                                    C-4
                                                   PARSER MODULE (OPRPAR)
                                              Key and switch table macros


   KEY012: $STAB
            DSPTAB(EXI010,.EXIT,<EXIT>)
            DSPTAB(HLP010,.HELP,<HELP>)
           $ETAB

   EXI010: $NOISE(EXI010,<TO MONITOR>)

   EXI020: $CRLF

   HLP010: $NOISE(HLP020,<WITH>)

   HLP020: $CTEXT(,<Topic for which help is wanted>)



   C.4  Initialization

   C.4.1  P$INIT

   This routine will setup for timer interrupts and init the parser.
   It must be called once during program initilization.

    Accepts        S1/     Level,, Timer channel   (TOPS20 only)
                   S2/     LEVTAB,,CHNTAB          (TOPS20 only)




   C.4.2  P$STAK

   This routine accepts a JFN for a take file to be used and updates
   the  necessary  OPRPAR data base to make all other functions work
   correctly.

    Accepts        S1/ JFN or IFN(-10) for take file




   C.4.3  P$SETU

   This routine is the  first  routine  called  after  a  successful
   return from PARSER.  It establishes the base address of arguments
   for all subsequent calls to extract the parsed fields.

    Accepts        S1/ Address of parsed data found
                          in parser return block

           




                                    C-5
   PARSER MODULE (OPRPAR)
   Initialization


   C.4.4  P$HELP

   This routine will read the specified help file and search  for  a
   specified  string.   The  information  from the file is displayed
   using $TEXT calling the default text output routine specified  in
   the IB.

    Accepts        S1/ Address of an FD for the HELP file
                   S2/ Pointer to a topic string




   C.4.5  P$CURR

   This routine will return the  address  of  current  entry  to  be
   parsed.

    Returns TRUE   S1/ Address of current parser block




   C.4.6  P$PREV

   This routine will change the parser block to the  previous  entry
   that was processed.  It will only go back one block.

    Returns TRUE   S1/ Address of previous parser block
                             now current

            FALSE  No previous entry




   C.4.7  P$NEXT

   This routine will bump to next data field and return true.

    Returns TRUE   S1/ Address of current parser block
                   S2/ Length of current parser block











                                    C-6
                                                   PARSER MODULE (OPRPAR)
                                                           Initialization


   C.4.8  P$NFLD

   This routine will return the argument type for the current  entry
   and the address of the current entry.

    Returns TRUE   S1/ Argument type
                   S2/ Address of block

            FALSE  No more arguments




   C.5  Function specific argument fetching routines

   The following routines are called  after  the  command  has  been
   parsed  to  fetch  the  data  that  was  parsed  for the specific
   function.  In some cases no data will be  returned  (e.g.   $CRLF
   and $COMMA don't store data)



   C.5.1  P$CFM

   This routine will fetch a confirmation argument block.

    Returns TRUE   Confirm was parsed

            FALSE  S1/ Type of argument block found




   C.5.2  P$COMMA

   This routine will fetch a comma argument block.

    Returns TRUE   A comma was parsed

            FALSE  S1/ Type of argument block found




   C.5.3  P$KEYW

   This routine will try to get a keyword from the next block in the
   parser data.

   Returns TRUE    S1/     Data from keyword table (18 bits)

           FALSE   S1/     Data type found

                                    C-7
   PARSER MODULE (OPRPAR)
   Function specific argument fetching routines


   C.5.4  P$SWIT

   This routine will try to get a switch from the next block in  the
   parsed data.

    Returns TRUE   S1/     Data from switch table entry (18 bits)

            FALSE  S1/     Data type found




   C.5.5  P$USER

   This routine will return a user number or  PPN  from  the  parsed
   data.

    Returns TRUE   S1/     User number or PPN

            FALSE  S1/     Data type found




   C.5.6  P$FLOT

   This routine will return a floating point number from the  parsed
   data.

    Returns TRUE   S1/     Floating point number

            FALSE  S1/     Data type found




   C.5.7  P$DIR

   This routine will return a  directory  number  or  PPN  from  the
   parsed data.

    Returns TRUE   S1/     Directory number or PPN

            FALSE  S1/     Data type found









                                    C-8
                                                   PARSER MODULE (OPRPAR)
                             Function specific argument fetching routines


   C.5.8  P$TIME

   This routine will return a DATE/TIME from the parsed data.

    Returns TRUE   S1/     DATE/TIME in UDT format

            FALSE  S1/     Data type found




   C.5.9  P$NUM

   This routine returns a 36 bit  signed  integer  from  the  parsed
   data.

    Returns TRUE   S1/     Integer
                   S2/     Radix specified for input

            FALSE  S1/     Data type found




   C.5.10  P$FILE, P$IFIL and P$OFIL

   These routines return a file  descriptor  (FD)  from  the  parsed
   data.

    Returns TRUE   S1/     Address of FD 
                   S2/     Length of FD

            FALSE  S1/     Data type found




   C.5.11  P$FLD

   This routine returns a text argument from the parsed  data.   The
   text is stored as an ASCIZ string.

    Returns TRUE   S1/     Address of text argument block
                   S2/     Length of the block

            FALSE  S1/     Data type found







                                    C-9
   PARSER MODULE (OPRPAR)
   Function specific argument fetching routines


   C.5.12  P$TOK

   This routine returns a token argument from the parsed data.   The
   token is returned as and ASCIZ string.

    Returns TRUE   S1/     Address of argument
                   S2/     Length of the block

            FALSE  S1/     Data type found




   C.5.13  P$NODE

   This routine returns a NODE name or number from the parsed data.

    Returns TRUE   S1/ Sixbit NODE name or NODE number

            FALSE  S1/ Data type found




   C.5.14  P$SIXF

   This routine returns the sixbit value of a field from the  parsed
   data.   The  actual  argument  was  parsed with the $FIELD macro.
   This routine truncates the field to six characters  and  converts
   them to sixbit.

    Returns TRUE   S1/     Sixbit value of field

            FALSE  S1/     Data type found




   C.5.15  P$RNGE

   This routine returns two  numbers  from  the  parsed  data.   The
   numbers  where parsed with the $RANGE macro which expects them to
   be input as "low:high".  If  only  one  number  is  input  it  is
   returned as the high range.

    Returns TRUE   S1/     Low range
                   S2/     High range

            FALSE  S1/     Data type found




                                    C-10
                                                   PARSER MODULE (OPRPAR)
                             Function specific argument fetching routines


   C.5.16  P$TEXT

   This routine returns a text argument from the parsed data.

    Returns TRUE   S1/     Address of text argument
                   S2/     Length of the block

            FALSE  S1/     Data type found




   C.5.17  P$DEV

   This routine returns a device  argument  block  from  the  parsed
   data.

    Returns TRUE   S1/     Address of argument block
                   S2/     Length of the block

            FALSE  S1/     Data type found




   C.5.18  P$QSTR

   This routine returns a quoted string  argument  from  the  parsed
   data.  The data is stored as an ASCIZ string without the quotes.

    Returns TRUE   S1/     Address of agrument block
                   S2/     Length of argument block

            FALSE  S1/     Data type found




   C.5.19  P$UQSTR

   This routine returns an unquoted string argument from the  parsed
   data.  The data is stored as an ASCIZ string.

    Returns TRUE   S1/     Address of the argument block
                   S2/     Length of the argument block

            FALSE  S1/     Data type found






                                    C-11
   PARSER MODULE (OPRPAR)
   Function specific argument fetching routines


   C.5.20  P$ACCT

   This routine returns an account string from the parsed data.

    Returns TRUE   S1/     Address of argument block
                   S2/     Length of argument block

            FALSE  S1/     Data type found




   C.6  Miscellaneous Parser routines

   The parser has several routines which allow the  user  to  follow
   the  command  syntax  tree  just  as  the parser would do.  These
   routines are useful within an ERROR processing routine.



   C.6.1  P$NPRO

   This routine sets the parser no processing flag.



   C.6.2  P$GPDB

   This routine returns the address of the current PDB  when  called
   from an ACTION, DEFAULT or ERROR routine.

    Accepts        S1/     Address of the FDB

    Returns TRUE   S1/     Address of the PDB
                   S2/     Length of the PDB

            FALSE          Invalid PDB entry




   C.6.3  P$PNXT

   This routine returns the address  of  the  next  PDB.   Generally
   called from an ACTION, DEFAULT or ERROR routine.

    Accepts        S1/     Address of current PDB

    Returns TRUE   S1/     Address of next PDB

            FALSE          No next PDB


                                    C-12
                                                   PARSER MODULE (OPRPAR)
                                            Miscellaneous Parser routines


   C.6.4  P$PERR

   This routine returns  the  address  of  an  error  routine.   Not
   generally called externally.

    Accepts        S1/     Address of current PDB

    Returns TRUE   S1/     Address of the ERROR processing routine

            FALSE          No error processing routine for this PDB




   C.6.5  P$PDEF

   This routine returns the address of the default  filling  routine
   for the current PDB.  Not generally called externally.

    Accepts        S1/     Address of the current PDB

    Returns TRUE   S1/     Address of the DEFAULT filling routine.

            FALSE          No DEFAULT filling routine exists for this PDB




   C.6.6  P$PACT

   This routine returns the address of an action routine for a  PDB.
   Not generally called externally.

    Accepts        S1/     Address of the PDB

    Returns TRUE   S1/     Address of the action routine

            FALSE          No action routine was specified




   C.6.7  P$INTR

   This routine is called to inform the parser that an interrupt has
   been  received.   Calling  this  routine  at interrupt level will
   cause the parser to return with  the  P.INTE  flag  set  in  word
   PRT.FL  of  the  parser  return block.  If the parser has not yet
   started parsing  a  command  (i.e.   only  the  prompt  has  been
   displayed)  it will return immediately.  If part of a command has
   been typed in, a 3 minute  timer  interrupt  will  be  requested.
   When the timer interrupt is recieved T$TINT will cause the parser

                                    C-13
   PARSER MODULE (OPRPAR)
   Miscellaneous Parser routines


   to return even if the command has not yet been completed.



   C.6.8  P$TINT

   This routine is invoked by an interrupt on the timer channel  you
   specified  you  program.   Its  function is to cause an immediate
   return from the parser.  The timer interrupts are only  requested
   in response to a previous call to P$INTR.



   C.7  Parser data structure definitions

   C.7.1  Parser Argument block description

   The parser argument block contains the address of the  first  PDB
   in the command syntax tree.  For most programs this will be a PDB
   which was build using the $INIT macro.  This function will  cause
   the  specified  prompt  to  be  displayed  prior  to  accepting a
   command.

   This argument block also specifies wether  the  commands  are  to
   come  from  the terminal or from an incore string.  Each time you
   want to accept a command you will point to  this  argument  block
   and call the parser.

                   Parser argument block definition
           

           !=======================================================!
    PAR.TB !       Address of first PDB in command syntax          !
           !-------------------------------------------------------!
    PAR.PM !       Address of prompt string for $INIT function     !
           !-------------------------------------------------------!
    PAR.CM !       Address of area to store parsed data            !
           !       or 0 if you want OPRPAR to allocate a page      !
           !-------------------------------------------------------!
    PAR.SR !       Address of asciz string to parse                !
           !       or 0 to parse commands from TTY                 !
           !       or -1 to perform RESCAN on last monitor command !
           !=======================================================!










                                    C-14
                                                   PARSER MODULE (OPRPAR)
                                        Parser data structure definitions


   C.7.2  Parser return argument block description

   Upon completion of parsing a command the parser will return  TRUE
   or FALSE to indicate success or failure in parsing a command.  It
   will always return with S1 containing the length of the block and
   S2 containing the address of the block.

   If the parse was unsuccesfull  word  PRT.EM  of  the  block  will
   contain  the  address  of  the standard error text describing the
   failure of the last field which was parsed.

   In some cases, the parser may return false because  an  interrupt
   occured.   The flags in PRT.CM should be checked to determine the
   cause of the failure.

                   Parser Return argument block definition

           !=======================================================!
    PRT.FL !               Flag word for return                    !
           !-------------------------------------------------------!
    PRT.CM !               Address of parsed data                  !
           !-------------------------------------------------------!
    PRT.CF !               Command flag word                       !
           !-------------------------------------------------------!
    PRT.MS !               Address of parsed text buffer           !
           !-------------------------------------------------------!
    PRT.EM !               Address of error text                   !
           !               on false return                         !
           !-------------------------------------------------------!
    PRT.EC !               Error code from action routine          !
           !               on false return                         !
           !=======================================================!


   Flags returned in PRT.FL

           P.CEOF          End of file on incore parse
           P.DERR          Default routine returned false

                             PRT.EC contains error code from routine
                             PRT.EM contains error text from routine

   ***More***










                                    C-15
   PARSER MODULE (OPRPAR)
   Parser data structure definitions


   C.7.3  PDB data structure definition

   The following data structure is the key  element  of  the  parser
   data  base.  Each macro which describes an element of the command
   syntax generates a PDB which points to  the  next  field  of  the
   command as well as alternate paths for the current field.

   A PDB consists of two sections.  The first is used by  S%CMND  or
   the  COMND  JSYS on TOPS20 to parse the current field.  It varies
   in length depending on the type of field  it  refers  to  an  the
   arguments specified with the field.

   The second part is used by the parser.  You may specify a routine
   to get control before the field is parsed (DEFAULTING routine), a
   routine  to  get  control  after  the  field  is  parsed  (ACTION
   routine),  and  a  routine  to get control if this field fails to
   parse (ERROR routine).  The address  of  the  next  PDB  is  also
   stored in this PDB.

   The format of a PDB is:

           !=======================================================!
    PB%HDR ! Length of entire PDB      ! Length of extensible FDB  !
           !-------------------------------------------------------!
    .CMFLG !  Function   !  Function   ! Address of alternate      !
           !    code     !    flags    ! FDB for this field        !
           !-------------------------------------------------------!
    .CMDAT !              Data for specific function               !
           !-------------------------------------------------------!
    .CMHLP !            Pointer to help text for field             !
           !-------------------------------------------------------!
    .CMDEF !          Pointer to default string for field          !
           !-------------------------------------------------------!
    .CMBRK !             Address of break set for this field       !
           +-------------------------------------------------------+
    PB%RTN !             Address of action routine                 !
           !-------------------------------------------------------!
    PB%DEF !             Address of defaulting routine             !
           !-------------------------------------------------------!
    PB%ERR !             Address of error routine for this field   !
           !-------------------------------------------------------!
    PB%NXT !             Address of PDB for next field             !
           !=======================================================!










                                    C-16
                                                   PARSER MODULE (OPRPAR)
                                        Parser data structure definitions


   C.7.4  ACTION, DEFAULT, and ERROR routine data block

   If you have specified one of the above routines  for  a  specific
   PDB  it  will  be  called  pointing to the following block.  Your
   routine should return  TRUE  to  the  parser  so  the  parse  may
   proceed.

                   S1/ Length of argument block
                   S2/ Address of argument block


           !=======================================================!
    CR.FLG ! Comnd Flag Bits      ! Address of Comnd State Block   !
           !-------------------------------------------------------!
    CR.RES !            Function specific response                 !
           !-------------------------------------------------------!
    CR.PDB !   Given PDB address  !       Actual PDB address       !
           !-------------------------------------------------------!
    CR.COD !          Function type of processed field             !
           !-------------------------------------------------------!
           !   Address of argument in parsed data (Action Only)    !
           !=======================================================!































                                    C-17
   PARSER MODULE (OPRPAR)
   Parser data structure definitions


   CHAPTER 1       THE GALAXY LIBRARY

           1.1     Introduction . . . . . . . . . . . . . . . . . . . 1-1
           1.2     The GALAXY Library . . . . . . . . . . . . . . . . 1-1
           1.3     The HOST Program . . . . . . . . . . . . . . . . . 1-2
           1.4     System Layout and Environment  . . . . . . . . . . 1-3
           1.4.1     System layout  . . . . . . . . . . . . . . . . . 1-3
           1.4.2     PROLOG . . . . . . . . . . . . . . . . . . . . . 1-4
           1.4.3     Initialization . . . . . . . . . . . . . . . . . 1-5
           1.5     Conventions  . . . . . . . . . . . . . . . . . . . 1-5
           1.5.1     Global Routine Names . . . . . . . . . . . . . . 1-5
           1.5.2     Accumulators . . . . . . . . . . . . . . . . . . 1-6
           1.5.3     Subroutine argument passing conventions  . . . . 1-7
           1.5.4     Subroutine calling conventions . . . . . . . . . 1-7
           1.5.5     SUCCESS/FAILURE testing conventions  . . . . . . 1-7
           1.5.6     Subroutine return mechanisms . . . . . . . . . . 1-8


   CHAPTER 2       MACROS AND PSEUDO-INSTRUCTIONS

           2.1     Field Masks and Constants  . . . . . . . . . . . . 2-2
           2.1.1     Common Field Masks and Constants . . . . . . . . 2-2
           2.1.2     Common Control Characters  . . . . . . . . . . . 2-2
           2.2     FIELD MASK MACROS  . . . . . . . . . . . . . . . . 2-3
           2.3     Conditional assembly macros  . . . . . . . . . . . 2-4
           2.4     Storage allocation macros  . . . . . . . . . . . . 2-4
           2.5     Listing control macros . . . . . . . . . . . . . . 2-4
           2.6     MISCELLANEOUS Macro definitions  . . . . . . . . . 2-5
           2.7     AC Mask PSEUDO-INSTRUCTIONS  . . . . . . . . . . . 2-6
           2.8     Subroutine Call and Return Pseudo-instructions . . 2-7
           2.9     Logical TRUE/FALSE Pseudo-instructions . . . . . . 2-8
           2.10    P-class Pseudo-instructions  . . . . . . . . . . . 2-8
           2.11    Miscellaneous Pseudo-instructions  . . . . . . . . 2-8
           2.12    Data-structure Macros  . . . . . . . . . . . . . . 2-9
           2.12.1    Data Structure Definition Macros . . . . . . . . 2-9
           2.13    Data Structure Pseudo-instructions.  . . . . . .  2-11
           2.14    Macros to build static data structures . . . . .  2-12
           2.15    AC and VARIABLE Save Facilities  . . . . . . . .  2-13
           2.16    NAMED VARIABLE FACILITIES  . . . . . . . . . . .  2-14
           2.16.1    STKVAR <namelist>  . . . . . . . . . . . . . .  2-15
           2.16.2    TRVAR <namelist> . . . . . . . . . . . . . . .  2-16
           2.17    $TEXT Pseudo-instruction . . . . . . . . . . . .  2-17
           2.17.1    Imbedded parameters and Qualifiers . . . . . .  2-18
           2.17.2    Field Justification  . . . . . . . . . . . . .  2-20
           2.17.3    ITEXT  . . . . . . . . . . . . . . . . . . . .  2-20
           2.17.4    Text Output Routine  . . . . . . . . . . . . .  2-21
           2.18    Error processing Pseudo-instructions . . . . . .  2-22
           2.19    Operator message Pseudo-instructions . . . . . .  2-24
           2.20    Interrupt processing pseudo-instructions . . . .  2-26




                                    C-18
                                                   PARSER MODULE (OPRPAR)
                                        Parser data structure definitions


   CHAPTER 3       GLXLIB ROUTINE DESCRIPTIONS

           3.1     GLXMEM - Memory Management Routines  . . . . . . . 3-2
           3.1.1     Description  . . . . . . . . . . . . . . . . . . 3-2
           3.1.2     Global Routines  . . . . . . . . . . . . . . . . 3-2
           3.1.2.1     M%GPAG . . . . . . . . . . . . . . . . . . . . 3-3
           3.1.2.2     M%ACQP . . . . . . . . . . . . . . . . . . . . 3-3
           3.1.2.3     M%AQNP . . . . . . . . . . . . . . . . . . . . 3-3
           3.1.2.4     M%RPAG . . . . . . . . . . . . . . . . . . . . 3-3
           3.1.2.5     M%RELP . . . . . . . . . . . . . . . . . . . . 3-4
           3.1.2.6     M%RLNP . . . . . . . . . . . . . . . . . . . . 3-4
           3.1.2.7     M%CLNC . . . . . . . . . . . . . . . . . . . . 3-4
           3.1.2.8     M%GMEM . . . . . . . . . . . . . . . . . . . . 3-4
           3.1.2.9     M%RMEM . . . . . . . . . . . . . . . . . . . . 3-5
           3.1.2.10    M%NXPG . . . . . . . . . . . . . . . . . . . . 3-5
           3.1.2.11    M%IPRC . . . . . . . . . . . . . . . . . . . . 3-6
           3.1.2.12    M%IPSN . . . . . . . . . . . . . . . . . . . . 3-6
           3.1.2.13    M%IPRM . . . . . . . . . . . . . . . . . . . . 3-6
           3.2     GLXFIL - Disk File Input/Output Routines . . . . . 3-7
           3.2.1     Description  . . . . . . . . . . . . . . . . . . 3-7
           3.2.2     Global Routines  . . . . . . . . . . . . . . . . 3-7
           3.2.3     File Open Block (FOB)  . . . . . . . . . . . . . 3-8
           3.2.4     File Descriptor (FD) . . . . . . . . . . . . . . 3-9
           3.2.4.1     F%IOPN . . . . . . . . . . . . . . . . . . .  3-10
           3.2.4.2     F%IBYT . . . . . . . . . . . . . . . . . . .  3-10
           3.2.4.3     F%IBUF . . . . . . . . . . . . . . . . . . .  3-10
           3.2.4.4     F%POS  . . . . . . . . . . . . . . . . . . .  3-12
           3.2.4.5     F%REW  . . . . . . . . . . . . . . . . . . .  3-12
           3.2.4.6     F%OOPN . . . . . . . . . . . . . . . . . . .  3-13
           3.2.4.7     F%AOPN . . . . . . . . . . . . . . . . . . .  3-13
           3.2.4.8     F%OBYT . . . . . . . . . . . . . . . . . . .  3-14
           3.2.4.9     F%OBUF . . . . . . . . . . . . . . . . . . .  3-14
           3.2.4.10    F%REL  . . . . . . . . . . . . . . . . . . .  3-15
           3.2.4.11    F%DREL . . . . . . . . . . . . . . . . . . .  3-15
           3.2.4.12    F%RREL . . . . . . . . . . . . . . . . . . .  3-16
           3.2.4.13    F%CHKP . . . . . . . . . . . . . . . . . . .  3-17
           3.2.4.14    F%REN  . . . . . . . . . . . . . . . . . . .  3-18
           3.2.4.15    F%INFO . . . . . . . . . . . . . . . . . . .  3-19
           3.2.4.16    F%FD   . . . . . . . . . . . . . . . . . . .  3-19
           3.2.4.17    F%DEL  . . . . . . . . . . . . . . . . . . .  3-20
           3.3     GLXIPC - IPCF Interface  . . . . . . . . . . . .  3-21
           3.3.1     Purpose  . . . . . . . . . . . . . . . . . . .  3-21
           3.3.2     Global Routines  . . . . . . . . . . . . . . .  3-21
           3.3.2.1     C%RPRM . . . . . . . . . . . . . . . . . . .  3-21
           3.3.2.2     C%RECV . . . . . . . . . . . . . . . . . . .  3-22
           3.3.2.3     C%BRCV . . . . . . . . . . . . . . . . . . .  3-22
           3.3.2.4     C%REL  . . . . . . . . . . . . . . . . . . .  3-22
           3.3.2.5     C%SEND . . . . . . . . . . . . . . . . . . .  3-23
           3.3.2.6     C%INTR . . . . . . . . . . . . . . . . . . .  3-23
           3.4     GLXLNK - Linked-list facilities  . . . . . . . .  3-24
           3.4.1     Description  . . . . . . . . . . . . . . . . .  3-24
           3.4.2     Global Routines  . . . . . . . . . . . . . . .  3-24

                                    C-19
   PARSER MODULE (OPRPAR)
   Parser data structure definitions


           3.4.2.1     L%CLST . . . . . . . . . . . . . . . . . . .  3-25
           3.4.2.2     L%DLST . . . . . . . . . . . . . . . . . . .  3-25
           3.4.2.3     L%CENT . . . . . . . . . . . . . . . . . . .  3-26
           3.4.2.4     L%CBFR . . . . . . . . . . . . . . . . . . .  3-26
           3.4.2.5     L%NEXT . . . . . . . . . . . . . . . . . . .  3-27
           3.4.2.6     L%DENT . . . . . . . . . . . . . . . . . . .  3-27
           3.4.2.7     L%FIRST  . . . . . . . . . . . . . . . . . .  3-28
           3.4.2.8     L%LAST . . . . . . . . . . . . . . . . . . .  3-28
           3.4.2.9     L%PREV . . . . . . . . . . . . . . . . . . .  3-28
           3.4.2.10    L%CURR . . . . . . . . . . . . . . . . . . .  3-29
           3.4.2.11    L%SIZE . . . . . . . . . . . . . . . . . . .  3-29
           3.4.2.12    L%RENT . . . . . . . . . . . . . . . . . . .  3-29
           3.4.2.13    L%PREM . . . . . . . . . . . . . . . . . . .  3-30
           3.4.2.14    L%APOS . . . . . . . . . . . . . . . . . . .  3-30
           3.5     GLXTXT - Formatted ASCII Functions . . . . . . .  3-31
           3.5.1     Description  . . . . . . . . . . . . . . . . .  3-31
           3.5.2     Global Routines  . . . . . . . . . . . . . . .  3-31
           3.5.2.1     T%TEXT . . . . . . . . . . . . . . . . . . .  3-31
           3.5.2.2     T%TTY  . . . . . . . . . . . . . . . . . . .  3-31
           3.6     GLXINT - Common Operating System Functions . . .  3-32
           3.6.1     Description  . . . . . . . . . . . . . . . . .  3-32
           3.6.2     Global Routines  . . . . . . . . . . . . . . .  3-32
           3.6.2.1     I%INIT . . . . . . . . . . . . . . . . . . .  3-33
           3.6.2.2     I%NOW  . . . . . . . . . . . . . . . . . . .  3-33
           3.6.2.3     I%EXIT . . . . . . . . . . . . . . . . . . .  3-34
           3.6.2.4     I%HOST . . . . . . . . . . . . . . . . . . .  3-34
           3.6.2.5     I%SLP  . . . . . . . . . . . . . . . . . . .  3-34
           3.6.2.6     I%TIMR . . . . . . . . . . . . . . . . . . .  3-35
           3.6.2.7     I%IOFF . . . . . . . . . . . . . . . . . . .  3-36
           3.6.2.8     I%ION  . . . . . . . . . . . . . . . . . . .  3-36
           3.6.2.9     I%SOPR . . . . . . . . . . . . . . . . . . .  3-37
           3.6.2.10    I%WTO  . . . . . . . . . . . . . . . . . . .  3-37
           3.6.2.11    I%JINF . . . . . . . . . . . . . . . . . . .  3-37
           3.7     GLXKBD - Keyboard (terminal) routines  . . . . .  3-39
           3.7.1     Description  . . . . . . . . . . . . . . . . .  3-39
           3.7.2     Global Routines  . . . . . . . . . . . . . . .  3-39
           3.8     GLXSCN - COMMAND SCANNING ROUTINES . . . . . . .  3-39
           3.8.1     Description  . . . . . . . . . . . . . . . . .  3-39
           3.8.2     Global Routines  . . . . . . . . . . . . . . .  3-39
           3.8.2.1     S%SIXB . . . . . . . . . . . . . . . . . . .  3-40
           3.8.2.2     S%NUMI . . . . . . . . . . . . . . . . . . .  3-40
           3.8.2.3     S%DATI . . . . . . . . . . . . . . . . . . .  3-41
           3.9     GLXCOM - GLXLIB Utility Module . . . . . . . . .  3-42
           3.9.1     Description  . . . . . . . . . . . . . . . . .  3-42
           3.9.2     Global Routines  . . . . . . . . . . . . . . .  3-42
           3.9.2.1     .SAVE1, .SAVE2, .SAVE3, .SAVE4 . . . . . . .  3-42
           3.9.2.2     .SAVET . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.3     .ZPAGA . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.4     .ZPAGN . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.5     .ZCHNK . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.6     .RETT  . . . . . . . . . . . . . . . . . . .  3-43
           3.9.2.7     .RETF  . . . . . . . . . . . . . . . . . . .  3-44

                                    C-20
                                                   PARSER MODULE (OPRPAR)
                                        Parser data structure definitions


           3.9.2.8     .POPJ  . . . . . . . . . . . . . . . . . . .  3-44


   CHAPTER 4       DEBUGGING AIDS


   CHAPTER 5       INSIDE THE GALAXY LIBRARY

           5.1     Introduction . . . . . . . . . . . . . . . . . . . 5-1
           5.2     Guidelines for adding new modules  . . . . . . . . 5-1
           5.3     Module Conventions . . . . . . . . . . . . . . . . 5-2
           5.3.1     Symbol Naming Conventions  . . . . . . . . . . . 5-2
           5.3.1.1     Global Subroutines . . . . . . . . . . . . . . 5-2
           5.3.1.2     Local Names  . . . . . . . . . . . . . . . . . 5-2
           5.3.2     Error Conditions . . . . . . . . . . . . . . . . 5-2
           5.4     Physical Layout of a GLXLIB Module . . . . . . . . 5-3
           5.4.1     Overview of Module layout  . . . . . . . . . . . 5-3
           5.4.1.1     Title Page . . . . . . . . . . . . . . . . . . 5-4
           5.4.1.2     Table of Contents  . . . . . . . . . . . . . . 5-4
           5.4.1.3     Revision History . . . . . . . . . . . . . . . 5-5
           5.4.1.4     Module-wide Storage  . . . . . . . . . . . . . 5-5
           5.4.1.5     Global Routines  . . . . . . . . . . . . . . . 5-6
           5.4.1.6     Local Routines . . . . . . . . . . . . . . . . 5-6


   CHAPTER 6       GALAXY LINE AND PAGE CONVENTIONS

           6.1     Introduction . . . . . . . . . . . . . . . . . . . 6-1
           6.2     Instruction format . . . . . . . . . . . . . . . . 6-1
           6.2.1     Tags . . . . . . . . . . . . . . . . . . . . . . 6-1
           6.2.2     Operator . . . . . . . . . . . . . . . . . . . . 6-2
           6.2.3     Accumulator field  . . . . . . . . . . . . . . . 6-3
           6.2.4     Address field  . . . . . . . . . . . . . . . . . 6-3
           6.2.5     Comment field  . . . . . . . . . . . . . . . . . 6-3
           6.3     Macro Calls  . . . . . . . . . . . . . . . . . . . 6-4


   APPENDIX A      GALAXY LIBRARY ERROR CODES


   APPENDIX B      GLXLIB STOPCODES


   APPENDIX C      PARSER MODULE (OPRPAR)

           C.1     Function specific macros . . . . . . . . . . . . . C-1
           C.2     Optional arguments . . . . . . . . . . . . . . . . C-2
           C.3     Key and switch table macros  . . . . . . . . . . . C-4
           C.4     Initialization . . . . . . . . . . . . . . . . . . C-5
           C.4.1     P$INIT . . . . . . . . . . . . . . . . . . . . . C-5
           C.4.2     P$STAK . . . . . . . . . . . . . . . . . . . . . C-5
           C.4.3     P$SETU . . . . . . . . . . . . . . . . . . . . . C-5

                                    C-21
   PARSER MODULE (OPRPAR)
   Parser data structure definitions


           C.4.4     P$HELP . . . . . . . . . . . . . . . . . . . . . C-6
           C.4.5     P$CURR . . . . . . . . . . . . . . . . . . . . . C-6
           C.4.6     P$PREV . . . . . . . . . . . . . . . . . . . . . C-6
           C.4.7     P$NEXT . . . . . . . . . . . . . . . . . . . . . C-6
           C.4.8     P$NFLD . . . . . . . . . . . . . . . . . . . . . C-7
           C.5     Function specific argument fetching routines . . . C-7
           C.5.1     P$CFM  . . . . . . . . . . . . . . . . . . . . . C-7
           C.5.2     P$COMMA  . . . . . . . . . . . . . . . . . . . . C-7
           C.5.3     P$KEYW . . . . . . . . . . . . . . . . . . . . . C-7
           C.5.4     P$SWIT . . . . . . . . . . . . . . . . . . . . . C-8
           C.5.5     P$USER . . . . . . . . . . . . . . . . . . . . . C-8
           C.5.6     P$FLOT . . . . . . . . . . . . . . . . . . . . . C-8
           C.5.7     P$DIR  . . . . . . . . . . . . . . . . . . . . . C-8
           C.5.8     P$TIME . . . . . . . . . . . . . . . . . . . . . C-9
           C.5.9     P$NUM  . . . . . . . . . . . . . . . . . . . . . C-9
           C.5.10    P$FILE, P$IFIL and P$OFIL  . . . . . . . . . . . C-9
           C.5.11    P$FLD  . . . . . . . . . . . . . . . . . . . . . C-9
           C.5.12    P$TOK  . . . . . . . . . . . . . . . . . . . .  C-10
           C.5.13    P$NODE . . . . . . . . . . . . . . . . . . . .  C-10
           C.5.14    P$SIXF . . . . . . . . . . . . . . . . . . . .  C-10
           C.5.15    P$RNGE . . . . . . . . . . . . . . . . . . . .  C-10
           C.5.16    P$TEXT . . . . . . . . . . . . . . . . . . . .  C-11
           C.5.17    P$DEV  . . . . . . . . . . . . . . . . . . . .  C-11
           C.5.18    P$QSTR . . . . . . . . . . . . . . . . . . . .  C-11
           C.5.19    P$UQSTR  . . . . . . . . . . . . . . . . . . .  C-11
           C.5.20    P$ACCT . . . . . . . . . . . . . . . . . . . .  C-12
           C.6     Miscellaneous Parser routines  . . . . . . . . .  C-12
           C.6.1     P$NPRO . . . . . . . . . . . . . . . . . . . .  C-12
           C.6.2     P$GPDB . . . . . . . . . . . . . . . . . . . .  C-12
           C.6.3     P$PNXT . . . . . . . . . . . . . . . . . . . .  C-12
           C.6.4     P$PERR . . . . . . . . . . . . . . . . . . . .  C-13
           C.6.5     P$PDEF . . . . . . . . . . . . . . . . . . . .  C-13
           C.6.6     P$PACT . . . . . . . . . . . . . . . . . . . .  C-13
           C.6.7     P$INTR . . . . . . . . . . . . . . . . . . . .  C-13
           C.6.8     P$TINT . . . . . . . . . . . . . . . . . . . .  C-14
           C.7     Parser data structure definitions  . . . . . . .  C-14
           C.7.1     Parser Argument block description  . . . . . .  C-14
           C.7.2     Parser return argument block description . . .  C-15
           C.7.3     PDB data structure definition  . . . . . . . .  C-16
           C.7.4     ACTION, DEFAULT, and ERROR routine data block   C-17













                                    C-22