Trailing-Edge
-
PDP-10 Archives
-
bb-d868e-bm_tops20_v41_2020_dist_1of2
-
4-1-documentation/glxlib.mem
There are 4 other files named glxlib.mem in the archive. Click here to see a list.
Edition: 30 July 1980
Version: GLXLIB 1(577)
T H E G A L A X Y L I B R A R Y
G L X L I B
;
;
; COPYRIGHT (C) DIGITAL EQUIPMENT CORPORATION
; 1975,1976,1977,1978,1979,1982
;
; 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-4
2.3 Conditional assembly macros . . . . . . . . . . . 2-5
2.4 Storage allocation macros . . . . . . . . . . . . 2-5
2.5 Listing control macros . . . . . . . . . . . . . . 2-5
2.6 MISCELLANEOUS Macro definitions . . . . . . . . . 2-6
2.7 AC Mask PSEUDO-INSTRUCTIONS . . . . . . . . . . . 2-7
2.8 Subroutine Call and Return Pseudo-instructions . . 2-8
2.9 Locical TRUE/FALSE Pseudo-instructions . . . . . . 2-9
2.10 P-class Pseudo-instructions . . . . . . . . . . . 2-9
2.11 Miscellaneous Pseudo-instructions . . . . . . . . 2-9
2.12 Data-structure Macros . . . . . . . . . . . . . 2-10
2.12.1 Data Structure Definition Macros . . . . . . . 2-10
2.13 Data Structure Pseudo-instructions. . . . . . . 2-12
2.14 Macros to build static data structures . . . . . 2-13
2.15 AC and VARIABLE Save Facilities . . . . . . . . 2-14
2.16 NAMED VARIABLE FACILITIES . . . . . . . . . . . 2-15
2.16.1 STKVAR <namelist> . . . . . . . . . . . . . . 2-16
2.16.2 TRVAR <namelist> . . . . . . . . . . . . . . . 2-17
2.17 $TEXT Pseudo-instruction . . . . . . . . . . . . 2-18
2.17.1 Imbedded parameters and Qualifiers . . . . . . 2-19
2.17.2 Field Justification . . . . . . . . . . . . . 2-21
2.17.3 ITEXT . . . . . . . . . . . . . . . . . . . . 2-21
2.17.4 Text Output Routine . . . . . . . . . . . . . 2-22
2.18 Error processing Pseudo-instructions . . . . . . 2-23
2.19 Operator message Pseudo-instructions . . . . . . 2-25
2.20 Interrupt processing pseudo-instructions . . . . 2-27
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.2.1 F%IOPN . . . . . . . . . . . . . . . . . . . . 3-8
3.2.2.2 F%IBYT . . . . . . . . . . . . . . . . . . . . 3-8
3.2.2.3 F%IBUF . . . . . . . . . . . . . . . . . . . . 3-9
3.2.2.4 F%POS . . . . . . . . . . . . . . . . . . . . 3-9
3.2.2.5 F%REW . . . . . . . . . . . . . . . . . . . . 3-9
3.2.2.6 F%OOPN . . . . . . . . . . . . . . . . . . . 3-10
3.2.2.7 F%AOPN . . . . . . . . . . . . . . . . . . . 3-10
3.2.2.8 F%OBYT . . . . . . . . . . . . . . . . . . . 3-11
3.2.2.9 F%OBUF . . . . . . . . . . . . . . . . . . . 3-11
3.2.2.10 F%REL . . . . . . . . . . . . . . . . . . . 3-12
3.2.2.11 F%DREL . . . . . . . . . . . . . . . . . . . 3-12
3.2.2.12 F%RREL . . . . . . . . . . . . . . . . . . . 3-12
3.2.2.13 F%CHKP . . . . . . . . . . . . . . . . . . . 3-13
3.2.2.14 F%REN . . . . . . . . . . . . . . . . . . . 3-13
3.2.2.15 F%INFO . . . . . . . . . . . . . . . . . . . 3-14
3.2.2.16 F%FD . . . . . . . . . . . . . . . . . . . 3-14
3.2.2.17 F%DEL . . . . . . . . . . . . . . . . . . . 3-15
3.3 GLXIPC - IPCF Interface . . . . . . . . . . . . 3-16
3.3.1 Purpose . . . . . . . . . . . . . . . . . . . 3-16
3.3.2 Global Routines . . . . . . . . . . . . . . . 3-16
3.3.2.1 C%RPRM . . . . . . . . . . . . . . . . . . . 3-16
3.3.2.2 C%RECV . . . . . . . . . . . . . . . . . . . 3-17
3.3.2.3 C%BRCV . . . . . . . . . . . . . . . . . . . 3-17
3.3.2.4 C%REL . . . . . . . . . . . . . . . . . . . 3-17
3.3.2.5 C%SEND . . . . . . . . . . . . . . . . . . . 3-18
3.3.2.6 C%INTR . . . . . . . . . . . . . . . . . . . 3-18
3.4 GLXLNK - Linked-list facilities . . . . . . . . 3-19
3.4.1 Description . . . . . . . . . . . . . . . . . 3-19
3.4.2 Global Routines . . . . . . . . . . . . . . . 3-19
3.4.2.1 L%CLST . . . . . . . . . . . . . . . . . . . 3-20
3.4.2.2 L%DLST . . . . . . . . . . . . . . . . . . . 3-20
3.4.2.3 L%CENT . . . . . . . . . . . . . . . . . . . 3-20
3.4.2.4 L%CBFR . . . . . . . . . . . . . . . . . . . 3-21
3.4.2.5 L%NEXT . . . . . . . . . . . . . . . . . . . 3-21
3.4.2.6 L%DENT . . . . . . . . . . . . . . . . . . . 3-22
3.4.2.7 L%FIRST . . . . . . . . . . . . . . . . . . 3-22
3.4.2.8 L%LAST . . . . . . . . . . . . . . . . . . . 3-22
3.4.2.9 L%PREV . . . . . . . . . . . . . . . . . . . 3-23
3.4.2.10 L%CURR . . . . . . . . . . . . . . . . . . . 3-23
3.4.2.11 L%SIZE . . . . . . . . . . . . . . . . . . . 3-23
3.4.2.12 L%RENT . . . . . . . . . . . . . . . . . . . 3-24
3.4.2.13 L%PREM . . . . . . . . . . . . . . . . . . . 3-24
3.4.2.14 L%APOS . . . . . . . . . . . . . . . . . . . 3-24
3.5 GLXTXT - Formatted ASCII Functions . . . . . . . 3-26
3.5.1 Description . . . . . . . . . . . . . . . . . 3-26
3.5.2 Global Routines . . . . . . . . . . . . . . . 3-26
3.5.2.1 T%TEXT . . . . . . . . . . . . . . . . . . . 3-26
3.5.2.2 T%TTY . . . . . . . . . . . . . . . . . . . 3-26
3.6 GLXINT - Common Operating System Functions . . . 3-27
3.6.1 Description . . . . . . . . . . . . . . . . . 3-27
3.6.2 Global Routines . . . . . . . . . . . . . . . 3-27
3.6.2.1 I%NOW . . . . . . . . . . . . . . . . . . . 3-27
3.6.2.2 I%EXIT . . . . . . . . . . . . . . . . . . . 3-28
3.6.2.3 I%HOST . . . . . . . . . . . . . . . . . . . 3-28
3.6.2.4 I%SLP . . . . . . . . . . . . . . . . . . . 3-28
3.6.2.5 I%TIMR . . . . . . . . . . . . . . . . . . . 3-29
3.6.2.6 I%IOFF . . . . . . . . . . . . . . . . . . . 3-30
3.6.2.7 I%ION . . . . . . . . . . . . . . . . . . . 3-30
3.6.2.8 I%SOPR . . . . . . . . . . . . . . . . . . . 3-31
3.6.2.9 I%WTO . . . . . . . . . . . . . . . . . . . 3-31
3.6.2.10 I%JINF . . . . . . . . . . . . . . . . . . . 3-31
3.7 GLXKBD - Keyboard (terminal) routines . . . . . 3-33
3.7.1 Description . . . . . . . . . . . . . . . . . 3-33
3.7.2 Global Routines . . . . . . . . . . . . . . . 3-33
3.8 GLXSCN - COMMAND SCANNING ROUTINES . . . . . . . 3-33
3.8.1 Description . . . . . . . . . . . . . . . . . 3-33
3.8.2 Global Routines . . . . . . . . . . . . . . . 3-33
3.8.2.1 S%SIXB . . . . . . . . . . . . . . . . . . . 3-34
3.8.2.2 S%NUMI . . . . . . . . . . . . . . . . . . . 3-34
3.8.2.3 S%DATI . . . . . . . . . . . . . . . . . . . 3-35
3.9 GLXCOM - GLXLIB Utility Module . . . . . . . . . 3-36
3.9.1 Description . . . . . . . . . . . . . . . . . 3-36
3.9.2 Global Routines . . . . . . . . . . . . . . . 3-36
3.9.2.1 .SAVE1, .SAVE2, .SAVE3, .SAVE4 . . . . . . . 3-36
3.9.2.2 .SAVET . . . . . . . . . . . . . . . . . . . 3-37
3.9.2.3 .ZPAGA . . . . . . . . . . . . . . . . . . . 3-37
3.9.2.4 .ZPAGN . . . . . . . . . . . . . . . . . . . 3-37
3.9.2.5 .ZCHNK . . . . . . . . . . . . . . . . . . . 3-37
3.9.2.6 .RETT . . . . . . . . . . . . . . . . . . . 3-37
3.9.2.7 .RETF . . . . . . . . . . . . . . . . . . . 3-38
3.9.2.8 .POPJ . . . . . . . . . . . . . . . . . . . 3-38
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 GLXMAC) is used to pass parameters back and forth
between the host program and the library during initialization. It
contains, among other things, the name and version of the host
program, the IPCF profile wanted and data about the PSI system. It
should be stressed that initialization should take place as soon as
possible. The suggested sequence at the very start of the host
program is:
RESET ;ALWAYS
MOVE P,[stack ptr] ;SETUP PUSHDOWN LIST
MOVEI S1,IB.SZ ;LOAD SIZE OF THE IB
MOVEI S2,MYIB ;LOAD ADDRESS OF THE IB
$CALL I%INIT ;AND INITIALIZE THE WORLD
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
.CHDEL = 177 delete (rubout)
2-3
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-4
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-5
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-6
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-7
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-8
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-9
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-10
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-11
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-12
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-13
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-14
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-15
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-16
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-17
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-18
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-19
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-20
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-21
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-22
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-23
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-24
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-25
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-26
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-27
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.2.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. In addition, arguments may be
passed to F%IOPN which will allow privileged programs to have the file
"accessed checked" before returning.
Accepts S1/ The length of the File Open Block (FOB)
S2/ The address of the FOB (See GLXMAC)
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.2.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-8
GLXLIB ROUTINE DESCRIPTIONS
GLXFIL - Disk File Input/Output Routines
3.2.2.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
FALSE S1/ Error code
Possible errors: EREOF$ ERFDE$
3.2.2.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.2.5 F%REW
(byte 0). It is really a special case of F%POS.
Accepts S1/ IFN
Returns TRUE always
3-9
GLXLIB ROUTINE DESCRIPTIONS
GLXFIL - Disk File Input/Output Routines
3.2.2.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.2.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-10
GLXLIB ROUTINE DESCRIPTIONS
GLXFIL - Disk File Input/Output Routines
3.2.2.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.2.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-11
GLXLIB ROUTINE DESCRIPTIONS
GLXFIL - Disk File Input/Output Routines
3.2.2.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.2.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.2.2.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-12
GLXLIB ROUTINE DESCRIPTIONS
GLXFIL - Disk File Input/Output Routines
3.2.2.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.2.2.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 (see FRB in GLXMAC) provides
the location of two FD'S. The first file descriptor describes the
source file for the rename and the second describes the new name the
file is to be given. In addition, the FRB may specify "in his behalf"
information. The rename operation is done as the specific operating
system allows. That is, 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/ Size of the FRB
S2/ address of the FRB
Returns TRUE File has been renamed
FALSE S1/ Error code
3-13
GLXLIB ROUTINE DESCRIPTIONS
GLXFIL - Disk File Input/Output Routines
3.2.2.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.2.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-14
GLXLIB ROUTINE DESCRIPTIONS
GLXFIL - Disk File Input/Output Routines
3.2.2.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/ Size 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-15
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-16
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-17
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/ the 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-18
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 name" is returned for
the list. This handle is one of the arguments to all the other
routines to 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-19
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 name will
always be a non-zero value.
Accepts No arguments
Returns TRUE S1/ The list name
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 name
Returns TRUE always
3-20
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 name
S2/ entry size
Returns TRUE S1/ list name
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 name
S2/ entry size
Returns TRUE S1/ list name
S2/ address of CURRENT (new) entry
FALSE S1/ error code
Possible Errors: ERNCE$
3-21
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 name
Returns TRUE S1/ list name
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 name
Returns TRUE S1/ list name
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 name
Returns TRUE S1/ list name
3-22
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 name
Returns TRUE S1/ list name
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 name
Returns TRUE S1/ list name
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 name
Returns TRUE S1/ list name
S2/ address of CURRENT
3-23
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 name
Returns TRUE S1/ list name
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 name
Returns TRUE S1/ list name
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 name
Returns TRUE S1/ list name
S2/ address of CURRENT (remembered) entry
3-24
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 name
S2/ The Entry Address
Returns TRUE S1/ List name
S2/ The Entry Address
FALSE ENF Stopcode
3-25
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-26
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%NOW - Return current date and time
I%EXIT - Terminate this process
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.6.2.1 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-27
GLXLIB ROUTINE DESCRIPTIONS
GLXINT - Common Operating System Functions
3.6.2.2 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.3 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.4 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)
Accepts S1/ Number of seconds to sleep (1 to 60)
or
0 to sleep until an interrupt occurs
Returns TRUE always
3-28
GLXLIB ROUTINE DESCRIPTIONS
GLXINT - Common Operating System Functions
3.6.2.5 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
Timer request block format:
!=======================================!
.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-29
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.6 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.7 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-30
GLXLIB ROUTINE DESCRIPTIONS
GLXINT - Common Operating System Functions
3.6.2.8 I%SOPR
Sends a prebuilt page size message to ORION
Accepts S1/ Address of page containing message
3.6.2.9 I%WTO
Support routines for $WTO, $WTOR, $LOG and $ACK macros
3.6.2.10 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-31
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-32
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-33
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-34
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-35
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/ The 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/ the size of the chunk
S2/ the 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-36
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-37
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 !
!=======================================================!
PAR.SZ:
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 !
!=======================================================!
PRT.SZ:
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 !
!=======================================================!
PB%SIZ:
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: ! Offset for the flag word !
!-------------------------------------------------------!
CR.RES: ! Offset for the result word !
!-------------------------------------------------------!
CR.PDB: ! Given PDB address ! Actual PDB address !
!-------------------------------------------------------!
CR.COD: ! Function type of processed field !
!=======================================================!
CR.SIZ:
C-17
PARSER MODULE (OPRPAR)
Parser data structure definitions
INDEX
$ACK, 2-26 ERNRE$, 3-24
$BGINT, 2-27 ERNSP$, 3-18
$BUILD, 2-13 ERPRT$, 3-8, 3-15
$CALL, 1-7, 2-8 ERRQF$, 3-18
$DATA, 1-4, 2-5 ERSLE$, 3-8, 3-15, 3-18
$DEBRK, 2-27 ERSQF$, 3-18
$EOB, 2-13 ERUSE$, 3-8, 3-18
$FATAL, 1-4, 2-23 Examples
$GDATA, 1-4, 2-5 $CALL, 1-7
$RET, 2-8 $SAVE, 2-14
$RETE(XXX), 2-8 $STOP, 2-24
$RETF, 2-8 $TEXT, 2-20
$RETT, 2-8 field justification, 2-21
$SET, 2-13 ITEXT, 2-21
$STOP, 1-4, 2-23 qualifiers, 2-20
$TEXT, 2-18, 3-26 strings, 2-18
$TEXT., 2-19 data structure, 2-10
$WARN, 1-4, 2-23 $BUILD, 2-13
$WTO, 2-25 definition, 2-11
$WTOJ, 2-25 DEFSTR,mskstr, 2-11
$WTOR, 2-25 JUMPT,JUMPF, 1-7
SKIPT,SKIPF, 1-7
Accumulators, 6-3 subroutine call, 1-8
AC13-AC16, 1-6
P, 1-6 Field masks, 2-2
P1-P4, 1-6 Formatted ascii, 2-18
S1-S2, 1-6
TF, 1-6 to 1-7 IB, 1-5, 2-18, 2-22, 3-18
Accumulators T1-T4, 1-6 Initialization block, 1-5,
2-18, 2-22, 3-18
Character codes, 2-2 Interrupt, 2-27
Command syntax tree, C-4 Itext, 2-21
Constants, 2-2
Library routines
Data structures, 2-10 file management
F%AOPN, 3-10
ERARG$, 3-32 F%CHKP, 3-13
ERBOL$, 3-23 F%DEL, 3-15
ERDNA$, 3-8 F%DREL, 3-12
EREOF$, 3-8 to 3-9 F%FD, 3-14
EREOL$, 3-21 to 3-23 F%IBUF, 3-9
ERFDE$, 3-9 F%IBYT, 3-8
ERFNF$, 3-8, 3-15 F%INFO, 3-14
ERIFS$, 3-8 F%IOPN, 3-8
ERNCE$, 3-21 to 3-24 F%OBUF, 3-11
ERNMA$, 3-17 F%OBYT, 3-11
Index-1
PARSER MODULE (OPRPAR)
Parser data structure definitions
F%OOPN, 3-10 M%IPSN, 3-6
F%POS, 3-9 M%NXPG, 3-5
F%REL, 3-12 M%RELP, 3-4
F%REN, 3-13 M%RLNP, 3-4
F%REW, 3-9 M%RMEM, 3-5
F%RREL, 3-12 M%RPAG, 3-3
general support routines
.ZCHNK, 3-37 .POPJ, 3-38
.ZPAGA, 3-37 .RETF, 3-38
.ZPAGN, 3-37 .RETT, 3-37
I%EXIT, 3-28 AC co-routines, 3-36
I%JINF, 3-31 I%IWTO, 3-31
I%NOW, 3-27 I%SOPR, 3-31
I%SLP, 3-28 T%TEXT, 3-26
I%TIMR, 3-29 T%TTY, 3-26
general I%HOST, 3-28
I%SLP, 3-2 Macros, 2-1
interrupt $SAVE, 2-14
I%IOFF, 3-30 conditional assembly
I%ION, 3-30 SYSPRM, 2-5
IPCF TOPS10, 2-5
C%BRCV, 3-17 TOPS20, 2-5
C%INTR, 3-18 data structure
C%RECV, 3-17 $BUILD, 2-13
C%REL, 3-17 $EOB, 2-13
C%RPRM, 3-16 $SET, 2-13
C%SEND, 3-18 DEFSTR,MSKSTR, 2-10
list managment declaration
L%APOS, 3-24 EXT, 2-6
L%CBFR, 3-21 GLOB, 2-6
L%CENT, 3-20 MAX, 2-6
L%CLST, 3-20 MIN, 2-6
L%CURR, 3-23 ND, 2-6
L%DENT, 3-22 VRSN., 2-6
L%FIRST, 3-22 XP, 2-6
L%LAST, 3-22 field mask
L%LDST, 3-20 .RTJST, 2-4
L%NEXT, 3-21 FLD,.INVSL, 2-4
L%PREM, 3-24 MASKB, 2-4
L%PREV, 3-23 POINTR, 2-4
L%RENT, 3-24 POS, 2-4
L%SIZE, 3-23 WID, 2-4
memory management list control
M%ACQP, 3-3 CONT., 2-5
M%AQNP, 3-3 LSTOF., 2-5
M%CLNC, 3-4 LSTON., 2-5
M%GMEM, 3-4 MOD., 2-6
M%GPAG, 3-3 storage allocation
M%IPRC, 3-6 $DATA, 2-5
M%IPRM, 3-6 $GDATA, 2-5
Index-2
PARSER MODULE (OPRPAR)
Parser data structure definitions
STKVAR, 2-16 $RETF, 2-8
TRVAR, 2-17 $RETT, 2-8
TRUE/FALSE, 2-9
Program initialization, 1-5 PSI, 2-27
Pseudo-instructions, 2-1
$RETIF,$RETIT, 2-9 Returns
$TEXT, 3-26 success/failure, 1-6
arguments, 2-18, 2-22 true/false, 1-6
field justification, 2-21 Routine naming
field width, 2-21 global routines, 1-5, 5-2
imbedded parameters,
2-18 to 2-19 Software interrupt system
itext, 2-21 IPCF interrupts, 3-18
padding, 2-21 Stopcode, 2-23
qualifiers, 2-19 Storage allocation
support routine dynamic, 2-15
T%TEXT, 3-26 library components, 5-5
text output routine, 2-18, static, 2-5
2-22 Subroutine
text output routines arguments, 1-7
T%TTY, 3-26 calling, 1-7
AC mask SUCCESS/FAILURE, 1-7
ADDX,SUBX, 2-7 Subroutines
CAX class, 2-7 returns, 1-8
IMULX,IDIVX, 2-7
IORX,ANDX,XORX, 2-7
MOVX, 2-7
MULX,DIVX, 2-7
TX class, 2-7
ADR2PG,PG2ADR, 2-9
data structure
DECR, 2-12
INCR, 2-12
LOAD, 2-12
STORE, 2-12
ZERO, 2-12
error processing
$FATAL, 2-23
$STOP, 2-23
$WARN, 2-23
interrupt processing
$BGINT, 2-27
$DEBRK, 2-27
JUMPT,JUMPF, 2-9
p-class jumps, 2-9
SKIPT,SKIPF, 2-9
subroutine linkage
$CALL, 2-8
$RET, 2-8
$RETE, 2-8
Index-3