TOPS-20
Monitor Calls User's Guide
|
|
| Electronically Distributed
|
|
|
| This manual describes the use of TOPS-20 monitor
| calls, which provide user programs with system
| services such as input/output, process control,
| file handling, and device control.
|
| This manual supersedes the TOPS-20 Monitor Calls
| User's Guide published in June 1988. The order
| number for that document, AA-D859DM-TM, is
| obsolete.
Change bars in the margins indicate material that
has been added or changed since the previous
printing of this manual.
Operating System: TOPS-20 Version 7.0
digital equipment corporation maynard, massachusetts
| TOPS-20 Software Update Tape No. 04, November 1990
First Printing, May 1976
Revised, April 1982
Revised, September 1985
Revised, June 1988
| Revised, November 1990
The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.
|
|
|
| Copyright C 1976, 1982, 1985, 1988, 1990 Digital Equipment
| Corporation.
All Rights Reserved.
The following are trademarks of Digital Equipment Corporation:
CI DECtape LA50 SITGO-10
DDCMP DECUS LN01 TOPS-10
DEC DECwriter LN03 TOPS-20
DECmail DELNI MASSBUS TOPS-20AN
DECnet DELUA PDP UNIBUS
DECnet-VAX HSC PDP-11/24 UETP
DECserver HSC-50 PrintServer VAX
DECserver 100 KA10 PrintServer 40 VAX/VMS
DECserver 200 KI Q-bus VT50
DECsystem-10 KL10 ReGIS
DECSYSTEM-20 KS10 RSX d i g i t a l
CONTENTS
PREFACE
CHAPTER 1 INTRODUCTION
1.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 1-1
1.2 MONITOR CALLS . . . . . . . . . . . . . . . . . . 1-2
1.2.1 Calling Sequence . . . . . . . . . . . . . . . . 1-3
1.2.2 Error Returns . . . . . . . . . . . . . . . . . 1-4
1.3 PROGRAM ENVIRONMENT . . . . . . . . . . . . . . . 1-6
CHAPTER 2 INPUT AND OUTPUT USING THE TERMINAL
2.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 2-1
2.2 PRIMARY I/O DESIGNATORS . . . . . . . . . . . . . 2-2
2.3 PRINTING A STRING . . . . . . . . . . . . . . . . 2-3
2.4 READING A NUMBER . . . . . . . . . . . . . . . . . 2-4
2.5 WRITING A NUMBER . . . . . . . . . . . . . . . . . 2-5
2.6 INITIALIZING AND TERMINATING THE PROGRAM . . . . . 2-7
2.6.1 RESET% Monitor Call . . . . . . . . . . . . . . 2-8
2.6.2 HALTF% Monitor Call . . . . . . . . . . . . . . 2-8
2.7 READING A BYTE . . . . . . . . . . . . . . . . . . 2-8
2.8 WRITING A BYTE . . . . . . . . . . . . . . . . . . 2-8
2.9 READING A STRING . . . . . . . . . . . . . . . . . 2-9
2.10 SUMMARY . . . . . . . . . . . . . . . . . . . . 2-14
CHAPTER 3 USING FILES
3.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 3-1
3.2 JOB FILE NUMBER . . . . . . . . . . . . . . . . . 3-2
3.3 ASSOCIATING A FILE WITH A JFN . . . . . . . . . . 3-3
3.3.1 GTJFN% Monitor Call . . . . . . . . . . . . . . 3-4
3.3.1.1 Short Form of GTJFN% . . . . . . . . . . . . . 3-4
3.3.1.2 Long Form of GTJFN% . . . . . . . . . . . . 3-12
3.3.1.3 Summary of GTJFN% . . . . . . . . . . . . . 3-15
3.4 OPENING A FILE . . . . . . . . . . . . . . . . . 3-16
3.4.1 OPENF% Monitor Call . . . . . . . . . . . . . 3-16
3.5 TRANSFERRING DATA . . . . . . . . . . . . . . . 3-19
3.5.1 File Pointer . . . . . . . . . . . . . . . . . 3-20
3.5.2 Source and Destination Designators . . . . . . 3-20
3.5.3 Transferring Sequential Bytes . . . . . . . . 3-21
3.5.4 Transferring Strings . . . . . . . . . . . . . 3-22
3.5.5 Transferring Nonsequential Bytes . . . . . . . 3-24
3.5.6 Mapping Pages . . . . . . . . . . . . . . . . 3-24
3.5.6.1 Mapping File Pages to a Process . . . . . . 3-26
3.5.6.2 Mapping Process Pages to a File . . . . . . 3-27
3.5.6.3 Unmapping Pages in a Process . . . . . . . . 3-28
3.5.7 Mapping File Sections to a Process . . . . . . 3-28
3.6 CLOSING A FILE . . . . . . . . . . . . . . . . . 3-30
3.6.1 CLOSF% Monitor Call . . . . . . . . . . . . . 3-30
3.7 ADDITIONAL FILE I/O MONITOR CALLS . . . . . . . 3-31
3.7.1 GTSTS% Monitor Call . . . . . . . . . . . . . 3-31
3.7.2 JFNS% Monitor Call . . . . . . . . . . . . . . 3-33
3.7.3 GNJFN% Monitor Call . . . . . . . . . . . . . 3-36
3.8 SUMMARY . . . . . . . . . . . . . . . . . . . . 3-40
3.9 FILE EXAMPLES . . . . . . . . . . . . . . . . . 3-40
CHAPTER 4 USING THE SOFTWARE INTERRUPT SYSTEM
4.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 4-1
4.2 INTERRUPT CONDITIONS . . . . . . . . . . . . . . . 4-4
4.3 SOFTWARE INTERRUPT CHANNELS AND PRIORITIES . . . . 4-4
4.4 SOFTWARE INTERRUPT TABLES . . . . . . . . . . . . 4-6
4.4.1 Specifying the Software Interrupt Tables . . . . 4-6
4.4.2 Channel Table . . . . . . . . . . . . . . . . . 4-7
4.4.3 Priority Level Table . . . . . . . . . . . . . . 4-8
4.5 ENABLING THE SOFTWARE INTERRUPT SYSTEM . . . . . . 4-9
4.6 ACTIVATING INTERRUPT CHANNELS . . . . . . . . . . 4-9
4.7 GENERATING AN INTERRUPT . . . . . . . . . . . . 4-10
4.8 PROCESSING AN INTERRUPT . . . . . . . . . . . . 4-10
4.8.1 Dismissing an Interrupt . . . . . . . . . . . 4-11
4.9 TERMINAL INTERRUPTS . . . . . . . . . . . . . . 4-12
4.10 ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS . . 4-14
4.10.1 Testing for Enablement . . . . . . . . . . . . 4-14
4.10.2 Obtaining Interrupt Table Addresses . . . . . 4-15
4.10.2.1 The RIR% Monitor Call . . . . . . . . . . . 4-15
4.10.2.2 The XRIR% Monitor Call . . . . . . . . . . . 4-15
4.10.3 Disabling the Interrupt System . . . . . . . . 4-16
4.10.4 Deactivating a Channel . . . . . . . . . . . . 4-16
4.10.5 Deassigning Terminal Codes . . . . . . . . . . 4-17
4.10.6 Clearing the Interrupt System . . . . . . . . 4-17
4.11 SUMMARY . . . . . . . . . . . . . . . . . . . . 4-17
4.12 SOFTWARE INTERRUPT EXAMPLE . . . . . . . . . . . 4-18
CHAPTER 5 PROCESS STRUCTURE
5.1 USES FOR MULTIPLE PROCESSES . . . . . . . . . . . 5-2
5.2 PROCESS COMMUNICATION . . . . . . . . . . . . . . 5-3
5.2.1 Direct Process Control . . . . . . . . . . . . . 5-4
5.2.2 Software Interrupts . . . . . . . . . . . . . . 5-4
5.2.3 IPCF and ENQ/DEQ Facilities . . . . . . . . . . 5-4
5.2.4 Memory Sharing . . . . . . . . . . . . . . . . . 5-5
5.3 PROCESS IDENTIFIERS . . . . . . . . . . . . . . . 5-5
5.4 OVERVIEW OF MONITOR CALLS FOR PROCESSES . . . . . 5-7
5.5 CREATING A PROCESS . . . . . . . . . . . . . . . . 5-8
5.5.1 Process Capabilities . . . . . . . . . . . . . 5-11
5.6 SPECIFYING THE CONTENTS OF THE ADDRESS SPACE OF A
PROCESS . . . . . . . . . . . . . . . . . . . . 5-11
5.6.1 GET% Monitor Call . . . . . . . . . . . . . . 5-11
5.6.2 PMAP% Monitor Call . . . . . . . . . . . . . . 5-14
5.7 STARTING AN INFERIOR PROCESS . . . . . . . . . . 5-15
5.8 INFERIOR PROCESS TERMINATION . . . . . . . . . . 5-16
5.9 INFERIOR PROCESS STATUS . . . . . . . . . . . . 5-17
5.10 PROCESS COMMUNICATION . . . . . . . . . . . . . 5-19
5.11 DELETING AN INFERIOR PROCESS . . . . . . . . . . 5-20
5.12 PROCESS EXAMPLES . . . . . . . . . . . . . . . . 5-21
CHAPTER 6 ENQUEUE/DEQUEUE FACILITY
6.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 6-1
6.2 RESOURCE OWNERSHIP . . . . . . . . . . . . . . . . 6-2
6.3 PREPARING FOR THE ENQ/DEQ FACILITY . . . . . . . . 6-3
6.4 USING THE ENQ/DEQ FACILITY . . . . . . . . . . . . 6-6
6.4.1 Requesting Use of a Resource . . . . . . . . . . 6-6
6.4.1.1 ENQ% Functions . . . . . . . . . . . . . . . . 6-6
6.4.1.2 ENQ% Argument Block . . . . . . . . . . . . . 6-8
6.4.2 Releasing a Resource . . . . . . . . . . . . . 6-12
6.4.2.1 DEQ% Functions . . . . . . . . . . . . . . . 6-13
6.4.2.2 DEQ% Argument Block . . . . . . . . . . . . 6-14
6.4.3 Obtaining Information About Resources . . . . 6-14
6.5 SHARER GROUPS . . . . . . . . . . . . . . . . . 6-17
6.6 AVOIDING DEADLY EMBRACES . . . . . . . . . . . . 6-19
CHAPTER 7 INTER-PROCESS COMMUNICATION FACILITY
7.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 7-1
7.2 QUOTAS . . . . . . . . . . . . . . . . . . . . . . 7-1
7.3 PACKETS . . . . . . . . . . . . . . . . . . . . . 7-2
7.3.1 Flags . . . . . . . . . . . . . . . . . . . . . 7-3
7.3.2 PIDs . . . . . . . . . . . . . . . . . . . . . . 7-5
7.3.3 Length and Address of Packet Data Block . . . . 7-6
7.3.4 Directories and Capabilities . . . . . . . . . . 7-6
7.3.5 Packet Data Block . . . . . . . . . . . . . . . 7-6
7.4 SENDING AND RECEIVING MESSAGES . . . . . . . . . . 7-7
7.4.1 Sending a Packet . . . . . . . . . . . . . . . . 7-7
7.4.2 Receiving a Packet . . . . . . . . . . . . . . . 7-9
7.5 SENDING MESSAGES TO INFO . . . . . . . . 7-12
7.5.1 Format of INFO Requests . . . . . . . 7-13
7.5.2 Format of INFO Responses . . . . . . . 7-14
7.6 PERFORMING IPCF UTILITY FUNCTIONS . . . . . . . 7-15
CHAPTER 8 USING EXTENDED ADDRESSING
8.1 OVERVIEW . . . . . . . . . . . . . . . . . . . . . 8-1
8.2 ADDRESSING MEMORY AND ACS . . . . . . . . . . . . 8-2
8.2.1 Instruction Format . . . . . . . . . . . . . . . 8-3
8.2.2 Indexing . . . . . . . . . . . . . . . . . . . . 8-4
8.2.3 Indirection . . . . . . . . . . . . . . . . . . 8-5
8.2.3.1 Instruction Format Indirect Word (IFIW) . . . 8-5
8.2.3.2 Extended Format Indirect Word (EFIW) . . . . . 8-6
8.2.3.3 Macros for Indirection . . . . . . . . . . . . 8-6
8.2.4 AC References . . . . . . . . . . . . . . . . . 8-6
8.2.5 Extended Addressing Examples . . . . . . . . . . 8-7
8.2.6 Immediate Instructions . . . . . . . . . . . . . 8-8
8.2.6.1 XMOVEI . . . . . . . . . . . . . . . . . . . . 8-8
8.2.6.2 XHLLI . . . . . . . . . . . . . . . . . . . . 8-9
8.2.7 Other Instructions . . . . . . . . . . . . . . . 8-9
8.2.7.1 Instructions that Affect the PC . . . . . . 8-10
8.2.7.2 Stack Instructions . . . . . . . . . . . . . 8-10
8.2.7.3 Byte Instructions . . . . . . . . . . . . . 8-10
8.3 USING MONITOR CALLS . . . . . . . . . . . . . . 8-11
8.3.1 Mapping Memory . . . . . . . . . . . . . . . . 8-12
8.3.1.1 Mapping File Sections to a Process . . . . . 8-12
8.3.1.2 Mapping Process Sections to a Process . . . 8-13
8.3.1.3 Creating Sections . . . . . . . . . . . . . 8-14
8.3.1.4 Unmapping a Process Section . . . . . . . . 8-15
8.3.2 Starting a Process in Any Section . . . . . . 8-16
8.3.3 Setting the Entry Vector in Any Section . . . 8-16
8.3.4 Obtaining Information About a Process . . . . 8-17
8.3.4.1 Memory Access Information . . . . . . . . . 8-17
8.3.4.2 Entry Vector Information . . . . . . . . . . 8-19
8.3.4.3 Page-Failure Information . . . . . . . . . . 8-19
8.3.5 Program Data Vectors . . . . . . . . . . . . . 8-19
8.3.5.1 Manipulating PDV Addresses . . . . . . . . . 8-20
8.3.5.2 PDV Names . . . . . . . . . . . . . . . . . 8-20
8.3.5.3 Version Number . . . . . . . . . . . . . . . 8-21
8.4 MODIFYING EXISTING PROGRAMS . . . . . . . . . . 8-21
8.4.1 Data Structures . . . . . . . . . . . . . . . 8-21
8.4.1.1 Index Words . . . . . . . . . . . . . . . . 8-22
8.4.1.2 Indirect Words . . . . . . . . . . . . . . . 8-22
8.4.1.3 Stack Pointers . . . . . . . . . . . . . . . 8-22
8.5 WRITING MULTISECTION PROGRAMS . . . . . . . . . 8-22
INDEX
FIGURES
4-1 Basic Operational Sequence of the Software
Interrupt System . . . . . . . . . . . . . . . . . 4-3
6-1 Deadly Embrace Situation . . . . . . . . . . . . . 6-5
6-2 Use of Sharer Groups . . . . . . . . . . . . . . 6-18
7-1 IPCF Packet . . . . . . . . . . . . . . . . . . . 7-2
8-1 Program Counter Address Fields . . . . . . . . . . 8-2
8-2 Instruction Word Address Fields . . . . . . . . . 8-4
8-3 Instruction Format Indirect Word . . . . . . . . . 8-5
8-4 Extended Format Indirect Word . . . . . . . . . . 8-6
TABLES
2-1 NOUT% Format Option . . . . . . . . . . . . . . . 2-6
2-2 RDTTY% Control Bits . . . . . . . . . . . . . . 2-10
3-1 Standard System Values for File Specifications . . 3-3
3-2 GTJFN% Flag Bits . . . . . . . . . . . . . . . . . 3-5
3-3 Bits Returned on GTJFN% Call . . . . . . . . . . 3-10
3-4 Long Form GTJFN% Argument Block . . . . . . . . 3-13
3-5 OPENF% Access Bits . . . . . . . . . . . . . . . 3-17
3-6 PMAP% Access Bits . . . . . . . . . . . . . . . 3-26
3-7 SMAP% Access Bits . . . . . . . . . . . . . . . 3-29
3-8 CLOSF% Flag Bits . . . . . . . . . . . . . . . . 3-30
3-9 Bits Returned on GTSTS% Call . . . . . . . . . . 3-31
3-10 JFNS% Format Options . . . . . . . . . . . . . . 3-34
3-11 GNJFN% Return Bits . . . . . . . . . . . . . . . 3-37
4-1 Software Interrupt Channel Assignments . . . . . . 4-5
4-2 Terminal Codes and Conditions . . . . . . . . . 4-12
5-1 Process Handles . . . . . . . . . . . . . . . . . 5-6
5-2 Inferior Process Characteristic Bits . . . . . . . 5-9
5-3 GET% Flag Bits . . . . . . . . . . . . . . . . . 5-12
5-4 GET% Argument Block . . . . . . . . . . . . . . 5-13
5-5 GET% Argument Block Flags . . . . . . . . . . . 5-13
5-6 Process Status Word . . . . . . . . . . . . . . 5-17
5-7 RFSTS% Status-Return Block . . . . . . . . . . . 5-18
6-1 ENQ% Functions . . . . . . . . . . . . . . . . . . 6-7
6-2 ENQ% Argument Block . . . . . . . . . . . . . . . 6-8
6-3 Lock Specification Flags . . . . . . . . . . . . 6-10
6-4 DEQ% Functions . . . . . . . . . . . . . . . . . 6-13
6-5 DEQ% Argument Block . . . . . . . . . . . . . . 6-14
6-6 ENQC% Flag Bits . . . . . . . . . . . . . . . . 6-16
7-1 Packet Descriptor Block Flags . . . . . . . . . . 7-3
7-2 Flags Meaningful on a MSEND% Call . . . . . . . . 7-8
7-3 Flags Meaningful on a MRECV% Call . . . . . . . 7-10
7-4 MRECV% Return Bits . . . . . . . . . . . . . . . 7-12
7-5 INFO Functions and Arguments . . . . . . 7-14
7-6 INFO Responses . . . . . . . . . . . . . 7-15
7-7 MUTIL% Functions . . . . . . . . . . . . . . . . 7-16
PREFACE
The TOPS-20 Monitor Calls User's Guide is written for the assembly
language user who is unfamiliar with the DECSYSTEM-20 monitor calls.
The manual introduces the user to the functions that he can request of
the monitor from within his assembly language programs. The manual
also teaches him how to use the basic monitor calls for performing
these functions.
This manual is not a reference document, nor is it complete
documentation of the entire set of monitor calls. It is organized
according to functions, starting with the simple and proceeding to the
more advanced.
Each chapter should be read from beginning to end. A user who skips
around in his reading will not gain the full benefit of this manual.
Once the user has a working knowledge of the monitor calls in this
_______ _______ _____ _________
document, he should then refer to the TOPS-20 Monitor Calls Reference
______
Manual for the complete descriptions of all the calls.
To understand the examples in this manual, the user must be familiar
with the MACRO language and the DECSYSTEM-20 machine instructions.
_______ _____ _________ _________ ______
The TOPS-20 MACRO Assembler Reference Manual documents the MACRO
_______ ____ _________ ______
language. The TOPS-20 LINK Reference Manual describes the linking
_________________________ _________ _________ ______
loader. The DECsystem-10/DECSYSTEM-20 Processor Reference Manual
contains the information on the machine instructions. These three
manuals should be used together with the Monitor Calls User's Guide,
and should be referred to when questions arise on the MACRO language
____________ __
or the instruction set. Another useful reference is Introduction to
____________ ________ ________ ___________
DECSYSTEM-20 Assembly Language Programming by Ralph E. Gorin,
published by the Digital Press. It provides a thorough treatment of
assembly language programming for the DECSYSTEM-20, emphasizing the
analysis of programs and various methods of program synthesis.
In addition, some of the examples in this manual contain macros and
symbols (MOVX, TMSG, JSERR, or JSHLT, for example) from the MACSYM
system file. This file is a universal file of definitions available
iii
to the user as a means of producing consistent and readable programs.
Finally, the user should be familiar with the TOPS-20 Command Language
_______ ______ _____
to enter and run the examples. The TOPS-20 User's Guide describes the
_______ ________ _________
TOPS-20 commands and system programs. The TOPS-20 Commands Reference
______
Manual describes all operating system commands available to the
nonprivileged user of TOPS-20.
4
CHAPTER 1
CHAPTER 1
INTRODUCTION
INTRODUCTION
1.1 OVERVIEW
1.1 OVERVIEW
A program written in MACRO assembly language consists of a series of
statements, each statement usually corresponding to one or more
machine language instructions. Each statement in the MACRO program
may be one of the following types:
1. A MACRO assembler directive, or pseudo-operation (pseudo-op),
such as SEARCH or END. These pseudo-ops are commands to the
MACRO assembler and are performed when the program is
____________ _____ _________
assembled. Refer to the DECSYSTEM-20 MACRO Assembler
_________ ______
Reference Manual for detailed descriptions of the MACRO
pseudo-ops.
2. A MACRO assembler direct assignment statement. These
statements are in the form
symbol=value
and are used to assign a specific value to a symbol.
Assignment statements are processed by the MACRO assembler
when the program is assembled. These statements do not
generate instructions or data in the assembled program.
3. A MACRO assembler constant declaration statement, such as
ONE: EXP 1
These statements are processed when the program is assembled.
4. An instruction mnemonic, or symbolic instruction code, such
as MOVE or ADD. These symbolic instruction codes represent
the operations performed by the central processor when the
_________________________
program is executed. Refer to the DECsystem-10/DECSYSTEM-20
_________ _________ ______
Processor Reference Manual for detailed descriptions of the
symbolic instruction codes.
1-1
INTRODUCTION
INTRODUCTION
5. A monitor call, or JSYS, such as RESET or BIN. These calls
are commands to the monitor and are performed when the
program is executed. This manual describes the commonly-used
_______
monitor calls. However, the user should refer to the TOPS-20
_______ _____ _________ ______
Monitor Calls Reference Manual for detailed descriptions of
all the calls.
When the MACRO program is assembled, the MACRO assembler processes the
statements in the program by
o translating symbolic instruction codes to binary codes.
o relating symbols to numeric values.
o assigning relocatable or absolute memory addresses.
The MACRO assembler also converts each symbolic call to the monitor
into a Jump-to-System (JSYS) instruction.
1.2 MONITOR CALLS
1.2 MONITOR CALLS
Monitor calls are used to request monitor functions, such as input or
output of data (I/O), error handling, and number conversions, during
the execution of the program. These calls are accomplished with the
JSYS instruction (operation code 104), where the address portion of
the instruction indicates the particular function.
Each monitor call has a predefined symbol indicating the particular
monitor function to be performed (for example, OPENF% to indicate
opening a file). The symbols are defined in a system file called
MONSYM. Monitor calls defined in Release 4 and later require a
percent sign (%) as the final character in the call symbol. Monitor
calls defined prior to Release 4 do not require the %, but do accept
it. The current convention is that all monitor calls use the % as
part of the call symbol. This manual follows that convention. To use
the symbols and to cause them to be defined correctly, the user's
program must contain the statement
SEARCH MONSYM
at the beginning of the program. During the assembly of the program,
the assembler replaces the monitor call symbol with an instruction
containing the operation code 104 in the left half and the appropriate
function code in the right half.
Arguments for a JSYS instruction are placed in accumulators (ACs).
Any data resulting from the execution of the JSYS instruction are
returned in the accumulators or in an address in memory to which an
accumulator points. Therefore, before the JSYS instruction can be
executed, the appropriate arguments must be placed in the specific
accumulators.
1-2
INTRODUCTION
INTRODUCTION
The system file MACSYM.MAC contains a number of useful macros for the
assembly language programmer. To use MACSYM macros, the user's
program must contain the statements
SEARCH MACSYM
.REQUIRE SYS:MACREL ;include support routines
at the beginning of the program. Since most bits defined for use with
the monitor have symbolic names, macros enable the programmer to
utilize these bits without knowledge of their exact position. Several
MACSYM macros that are especially valuable to the TOPS-20 assembly
language programmer are MOVX, TXnn (where nn indicates one of the 64
test instructions provided by the hardware), and FLD. MOVX loads an
AC with a constant using the proper MOVE instructions, depending on
the constant's position in the word. The TXnn macros expand to allow
all combinations of modification and testing to be defined. For
example
TXNN AC1,GS%EOF
tests AC1 for the presence of GS%EOF, no modification, and skip if not
equal to zero. This instruction will work regardless of the actual
bit position of GS%EOF. The FLD macro causes a value to be right
justified in a field. For example
FLD(7,OF%BSZ)
places the value 7 in position OF%BSZ, right justified at bit 5
(OF%BSZ is defined as bits 0-5). These macros will be used
consistently throughout this document.
1.2.1 Calling Sequence
1.2.1 Calling Sequence
Arguments for the calls are placed in accumulators 1 through 4
(AC1-AC4). If more than four arguments are required for a particular
call, the arguments are placed in a list to which an accumulator
points. The arguments for the calls are specific bit settings or
values. These bit settings and values are defined in MONSYM with
symbol names, which can be used in the program. In fact, it is
recommended that the user write his program using symbols whenever
possible. This makes the program easier to read by another user. Use
of symbols also allows the values of the symbols to be redefined
without requiring the program to be changed. In this manual, the
arguments for the monitor calls are described with both the bit
settings and the symbol names. All program examples are written using
the symbol names.
1-3
INTRODUCTION
INTRODUCTION
The set of instructions that place the arguments in the accumulators
is followed by one line of code giving the particular monitor call
symbol. During the program's execution, control is transferred to the
monitor when this line of code is reached.
1.2.2 Error Returns
1.2.2 Error Returns
TOPS-20 provides a consistent way to handle all JSYS errors. For most
monitor calls upon a successful return, the instruction following the
call is executed. If an error occurs during the execution of the
call, the monitor examines the instruction following the call. If the
instruction is a JUMP instruction with the AC field specified as
12-17, the monitor transfers control to a user-specified address. If
the instruction is not a JUMP instruction, the monitor generates an
illegal instruction trap indicating an illegal instruction, which the
user's program can process via the software interrupt system (refer to
Chapter 4). If the user's program is not prepared to process the
instruction trap, the program execution halts, and a message is output
stating the reason for failure.
To place a JUMP instruction in his program, the user can include a
statement using one of six predefined symbols. These symbols are
ERJMPR address (= JUMP 12,address)
ERCALR address (= JUMP 13,address)
ERJMPS address (= JUMP 14,address)
ERCALS address (= JUMP 15,address)
ERJMP address (= JUMP 16,address)
ERCAL address (= JUMP 17,address)
and cause the assembler to generate a JUMP instruction. The JUMP
instruction is a non-operation instruction (that is, a no-op) as far
as the hardware is concerned. However, the monitor executes the JUMP
instruction by transferring control to the address specified, which is
normally the beginning of an error processing routine written by the
user. If the user includes the ERJMP symbol, control is transferred
as though a JUMPA instruction had been executed, and control does not
return to his program after the error routine is finished. If the
user includes the ERCAL symbol, control is transferred as though a
PUSHJ 17, address instruction had been executed. If the error routine
executes a POPJ 17, instruction, control returns to the user's program
at the location following the ERCAL.
If the user includes the ERJMPR symbol, the monitor behaves the same
as it would if the ERJMP symbol had been included, except that the
last error encountered by the process is stored in the user's AC1.
_______ _______ _____ _________ ______
(Refer to Appendix B of the TOPS-20 Monitor Calls Reference Manual for
the list of error codes, mnemonics, and message strings.) The ERCALR
symbol functions the same as ERCAL except the error code encountered
is returned in the user's AC1. ERJMPS and ERCALS function similarly
except the monitor suppresses the storing of the error code in the
1-4
INTRODUCTION
INTRODUCTION
user's AC1. Instead, AC1 is preserved and contains either the
original contents from when the monitor call was given, or a partially
updated value prior to the error.
Prior to the implementation of the ERJMP/ERCAL facilities, certain
monitor calls returned control to the user's program at various
locations after the calling address. Approximately one third of the
JSYSs return to the +1 address only on failure, and to the location
immediately following that (the +2 address) on successful execution of
the call. A few calls return +1, +2, or +3, dependent on varying
conditions of success or failure (for examples, see ERSTR% or GACTF%
_______ _______ _____ _________ ______
in the TOPS-20 Monitor Calls Reference Manual); and some calls do not
return at all (see HALTF% or WAIT%). Refer to Chapter 3 of the
_______ _______ _____ _________ ______
TOPS-20 Monitor Calls Reference Manual for the possible returns for
each monitor call.
When a failure occurs during the execution of a monitor call, the
monitor stores an error code. The error code indicates the cause of
the failure. This error code is usually stored in the right half of
AC1, but can also be stored in the monitor's data base or a user's
data block. In either case, you can obtain the message associated
with the error by using the GETER% or ERSTR% call.
The ERJMP/ERCAL facilities can also be used following a machine
instruction, and will trap for the following conditions:
o Illegal instruction
o Illegal memory read
o Illegal memory write
o Pushdown list overflow
The ERJMP/ERCAL facilities can be used after all monitor calls,
regardless of whether the call has one or two returns. To handle
errors consistently, users are encouraged to employ either the ERJMPR,
ERCALR, ERJMPS, or ERCALS symbol with all calls. All of the six
predefined jump symbols are no-ops, unless they immediately follow a
monitor call or instruction that fails. Error codes can be obtained
by the program and translated into their corresponding error mnemonic
and message strings with the GETER% and ERSTR% monitor calls.
TOPS-20 provides convenient macros and subroutines for handling
monitor call error routines. They can be found in the system file
MACSYM.MAC. Two such macros are EJSERR and EJSHLT. EJSERR prints out
an error message and returns control to the next instruction following
the failing monitor call. EJSHLT prints out an error message and
halts processing of the program.
The following is an example of executing the BIN% monitor call (see
Chapter 3 for more information on this monitor call) that has a single
1-5
INTRODUCTION
INTRODUCTION
return. If the execution of the call is successful, the program reads
and stores a character. If the execution of the call is not
successful, the program transfers control to an error routine. This
routine processes the error and then returns control back to the main
program sequence. Note that ERCALS stores the return address on the
stack.
DOIT: MOVE T1,INJFN ;obtain JFN for input file
BIN% ;input one character
ERCALS ERROR ;call error routine if problem
MOVEM T2,CHAR ;store character
JRST DOIT ;and get another
ERROR: GTSTS% ;read file status
TXNE T2,GS%EOF ;end of file?
JRST EOF ;yes, process end-of-file condition
HRROI T1,[ASCIZ/
?INPUT ERROR, CONTINUING
/] ;no, data error
PSOUT% ;print message
RET ;return to program (POPJ 17,)
The ASCIZ pesudo-op specifies a left-justified ASCII string terminated
with a null (that is, a byte containing all bits equal to zero) byte.
1.3 PROGRAM ENVIRONMENT
1.3 PROGRAM ENVIRONMENT
The user program environment in the TOPS-20 operating system consists
of a job structure that can contain many processes. A process is a
runnable or schedulable entity capable of performing computations in
parallel with other processes. This means that a runnable program is
associated with at least one process.
Each process has its own address space for storing its computations.
This address space is called virtual space because it is actually a
"window" into physical storage. The address space is divided into 32
(decimal) sections. Each section is divided into 512 (decimal) pages,
and each page contains 512 (decimal) words. Each word contains 36
bits.
A process can communicate with other processes in the following ways:
o explicitly, by software interrupts or system facilities (the
inter-process communication facility, or IPCF, for example).
o implicitly, by changing parts of its environment (its address
space, for instance) that are being shared with other
processes.
A process can create other processes inferior to it, but there is one
control process from which the chain of creations begins. A process
1-6
INTRODUCTION
INTRODUCTION
is said to exist when a superior process creates it and is said to end
when a superior process deletes it. Refer to Chapter 5 for more
information on the process structure.
A set of one or more related processes, normally under control of a
single user, is a job. Each active process is part of some job on the
system. A job is defined by a user name, an account number, some open
files, and a set of running and/or suspended processes. A job can be
composed of several running or suspended programs.
The following diagram illustrates a job structure consisting of four
processes.
-----------------
| |
| TOP PROCESS |
| |
-----------------
|
|
|
---------------------------
| |
---------------- ---------------
| | | |
| PROCESS A | | PROCESS B |
| | | |
---------------- ---------------
|
|
|
---------------
| |
| PROCESS C |
| |
---------------
Both process A and 1 process B are created by the TOP PROCESS and thus
are directly inferior to it. Process C is created by process B and
thus is directly inferior to process B only. Process C is indirectly
inferior to the TOP PROCESS.
In summary, processes can be considered as independent virtual jobs
with well-defined relationships to other processes in the system, and
a job is a collection of these processes.
1-7
2-1
CHAPTER 2
CHAPTER 2
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
One of the main reasons for using monitor calls is to transfer data
from one location to another. This chapter discusses moving data to
and from the user's terminal.
2.1 OVERVIEW
2.1 OVERVIEW
Data transfers to and from the terminal are in the form of either
individual bytes or text strings. The bytes are 7-bit bytes. The
strings are ASCII strings ending with a 0 byte. These strings are
called ASCIZ strings.
To designate the desired string, the user's program must include a
statement that points to the beginning of the string being read or
written. The MACRO pseudo-op, POINT, can be used to set up this
pointer, as shown in the following sequence of statements:
MOVE AC1,PTR
.
.
.
PTR: POINT 7,MSG
MSG: ASCIZ/TEXT MESSAGE/
Accumulator 1 contains the symbolic address (PTR) of the pointer. At
the address specified by PTR is the pointer to the beginning of the
string. The pointer is set up by the POINT pseudo-op. The general
format of the POINT pseudo-op is:
POINT decimal-byte-size,address,decimal-byte-position
_______ _____ _________ _________ ______
(Refer to the TOPS-20 MACRO Assembler Reference Manual for more
information on the POINT pseudo-op.) In the example above, the POINT
pseudo-op has been written to indicate 7-bit bytes starting before the
left-most bit in the address specified by MSG.
2-1
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
Another way of setting up an accumulator to contain the address of the
pointer is with the following statement:
HRROI AC1,[ASCIZ/TEXT MESSAGE/]
The instruction mnemonic HRROI causes a -1 to be placed in the left
half of accumulator 1 and the address of the string to be placed in
the right half. However, in the above statement, a literal (enclosed
in square brackets) has been used instead of a symbolic address. The
literal causes the MACRO assembler to:
o store data within brackets (the string) in a table.
o assign an address to the first word of the data.
o insert that address as the operand to the HRROI instruction.
Literals have the advantage of showing the data at the point in the
program where it will be used, instead of showing it at the end of the
program.
As far as the I/O monitor calls are concerned, a word in this format
(-1 in the left half and an address in the right half) designates the
system's standard pointer (that is, a pointer to a 7-bit ASCIZ string
beginning before the leftmost byte of the string). The result of the
HRROI statement is interpreted by the monitor as functionally
equivalent to the word assembled by the POINT 7, address pseudo-op and
is the recommended statement to use in preparation for a monitor call.
However, byte manipulation instructions (for example, ILDB, IBP,
ADJBP) will not operate properly with this type of pointer.
After a string is read, the pointer is advanced to the character
following the terminating character of the string. After a string is
written, the pointer is advanced to the character following the last
non-null character written.
Most TOPS-20 monitor calls accept one-word global byte pointers when
executed from a nonzero section (see Section 8.3). Global byte
pointers are used with extended addressing and are fully explained in
Chapter 8 of this document. Unless specifically stated, TOPS-20
monitor calls do not accept two-word global byte pointers.
2.2 PRIMARY I/O DESIGNATORS
2.2 PRIMARY I/O DESIGNATORS
To transfer data from one location to another, the user's program must
indicate the source from which the data is to be obtained and the
destination where the data is to be placed. By default, the user's
terminal is defined as the source and destination. The default can be
_______
overridden by using the SPJFN% monitor call (refer to the TOPS-20
_______ _____ _________ ______
Monitor Calls Reference Manual). Examples in this book assume the
2-2
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
user's terminal to be the source (input) and destination (output)
device. Two designators are used to represent the user's terminal:
1. The symbol .PRIIN to represent the user's terminal as the
source (input) device.
2. The symbol .PRIOU to represent the user's terminal as the
destination (output) device.
These symbols are called the primary input and output designators and
by default are used to represent the terminal running the program.
They are defined in the system file MONSYM.MAC and do not have to be
defined in the user's program as long as the program contains the
statement
SEARCH MONSYM
2.3 PRINTING A STRING
2.3 PRINTING A STRING
Many times a program may need to print an error message or some other
string, such as a prompt to request input from the user at the
terminal. The PSOUT% (Primary String Output) monitor call is used to
print such a string on the terminal. This call copies the designated
string from the program's address space. Thus, the source of the data
is the program's address space, and the destination for the data is
the terminal. The program need only supply the pointer to the string
being printed.
Accumulator 1 (AC1) is used to contain the address of the pointer.
After AC1 is set up with the pointer to the string, the next line of
code is the PSOUT% call. Thus, an example of the PSOUT% call is:
HRROI AC1,[ASCIZ/TEXT MESSAGE/] ;string to print
PSOUT% ;print TEXT MESSAGE
The PSOUT% call prints on the terminal all the characters in the
string until it encounters a null byte. Note that the string is
printed exactly as it is stored in the program, starting at the
current position of the terminal's print head or cursor and ending
with the last character in the string. If a carriage return and line
feed are to be output, either before or after the string, these
characters should be inserted as part of the string. For example, to
print TEXT MESSAGE on one line and to output a carriage return-line
feed after it, the user's program includes the call
HRROI AC1,[ASCIZ/TEXT MESSAGE
/]
PSOUT%
2-3
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
After the string is printed, the instruction following the PSOUT% call
in the user's program is executed. Also, the pointer in AC1 is
updated to point to the character following the last non-null
character written.
The macro TMSG, found in the system file MACSYM, does the same thing
as the example above. This macro offers the programmer a convenient
way for printing messages on the terminal. For example
TMSG
caused the text message contained between the angle brackets,
including the carriage return and line feed, to print on the terminal.
The TMSG macro, along with others previously mentioned, will be used
consistently in examples throughout this document. Refer to the
system file MACSYM.MAC for further information on MACSYM macros.
Refer to Section 1.2.2 for information concerning error returns.
2.4 READING A NUMBER
2.4 READING A NUMBER
The NIN% (Number Input) monitor call is used to read an integer. This
call does not assume the terminal as the source designator; therefore,
the user's program must specify this. The NIN% call accepts the
number from any valid source designator, including a string in memory.
This section discusses reading a number directly from the terminal.
Refer to Section 2.9 for an example of using the NIN% call to read the
number from a string in memory. The destination for the number is
AC2, and the NIN% call places the binary value of the number read into
this accumulator. The user's program also specifies a number in AC3
that represents the radix of the number being input. The radix given
can be in the range 2-36.
Thus, the setup for the NIN% monitor call is the following:
MOVEI AC1,.PRIIN ;AC1 contains the primary input designator
;(the user's terminal)
MOVEI AC3,^D10 ;AC3 contains the radix of the number being
;input (in this case a decimal number)
NIN% ;The call to input the number
After completion of the NIN% call, control returns to the program at
one of two places (refer to Section 1.2.2). If an error occurs during
the execution of the call, control returns to the instruction
following the call. This instruction should be a jump-type
instruction to an error processing routine (see Section 1.2.2). Also,
_______
an error code is placed in AC3 (refer to Appendix B of the TOPS-20
_______ _____ _________ ______
Monitor Calls Reference Manual for the error codes). If the execution
2-4
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
of the NIN% call is successful, control returns to the second
instruction following the call. The number input from the terminal is
placed in AC2.
The NIN% call terminates when it encounters a nondigit character (for
example, a letter, a punctuation character, or a control character).
This means that if 32X1 were typed on the terminal, on return AC2
contains a 40 (octal) because the NIN% call terminated when it read
the X.
The following program prints a message and then accepts a decimal
number from the user at the terminal. Note that the NIN% call
terminates reading on any nondigit character; therefore, the user
cannot edit his input with any of the editing characters (for example,
DELETE, CTRL/W). The RDTTY% call (refer to Section 2.9) should be
used in programs that read from the terminal because it allows the
user to edit his input as he is typing it.
SEARCH MONSYM
HRROI AC1,[ASCIZ/
Enter # of seconds: /]
PSOUT% ;output a prompt message
MOVEI AC1,.PRIIN ;input from the terminal
MOVEI AC3,^D10 ;use the decimal radix
NIN% ;input a decimal number
ERJMP NINERR ;error-go to error routine
MOVEM AC2, NUMSEC ;save number entered
.
.
.
NUMSEC:BLOCK 1
.
.
.
2.5 WRITING A NUMBER
2.5 WRITING A NUMBER
The NOUT% (Number Output) monitor call is used to output an integer.
The user's program moves the number to be output into AC2. The
program must specify the destination for the number in AC1 and the
radix in which the number is to be output in AC3. The radix given
cannot be greater than base 36. In addition, the user's program can
specify certain formatting options to be used when printing the
number.
Thus, the general setup for the NOUT% monitor call is as follows:
AC1: output designator
AC2: number being output
AC3: format options in left half and radix in right half
2-5
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
The format options that can be specified in the left half of AC3 are
described in Table 2-1.
Table 2-1: NOUT% Format Option
Table 2-1: NOUT% Format Option
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 NO%MAG Print the number as a positive 36-bit
number. For example, -1 would be printed
as 777777 777777 if radix=8).
1 NO%SGN Print the appropriate sign (+ or -) before
the number. If bits NO%MAG and NO%SGN are
both on, a plus sign is always printed.
2 NO%LFL Print leading filler. If this bit is not
set, trailing filler is printed and bit
NO%ZRO is ignored.
3 NO%ZRO Use 0's as the leading filler if the
specified number of columns allows filling.
If this bit is not set, blanks are used as
the leading filler if the number of columns
allows filling.
4 NO%OOV Output on column overflow and return an
error. If this bit is not set, column
overflow is not output.
5 NO%AST Print asterisks when the column overflows.
If this bit is not set, and bit 4 (NO%OOV)
is set, all necessary digits are printed
when the columns overflow.
6-10 Reserved for Digital (must be 0).
11-17 NO%COL Print the number of columns indicated.
This value includes the sign column. If
this field is 0, as many columns as
necessary are printed.
______________________________________________________________________
The following instruction sequence is an example of the NOUT% monitor
call. This sequence prints a number, stored in location NUMB, on the
user's terminal. The number can be positive, negative or zero, with
no special formatting.
2-6
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
MOVX AC1,.PRIOU ;use primary output
MOVE AC2,NUMB ;get number from location NUMB
MOVX AC3,^D10 ;no special format
;decimal radix
NOUT% ;print number
EJSHLT ;unexpected fatal error. Halt
;and print message.
Refer to Section 1.2.2 for information concerning error returns. The
following example illustrates the use of the three monitor calls
described so far, as well as the TMSG macro. The RESET% and HALTF%
monitor calls are described in Section 2.6.
SEARCH MONSYM
SEARCH MACSYM
.REQUIRE SYS:MACREL
AC1==1
AC2==2
AC3==3
START: RESET% ;prepare program environment
HRROI AC1,[ASCIZ/PLEASE TYPE A DECIMAL NUMBER: /]
PSOUT%
MOVEI AC1,.PRIIN ;source designator
MOVEI AC3,^D10 ;decimal radix
NIN%
ERJMPS ERROR ;if input error print message
;halt.
TMSG
MOVEI AC1,.PRIOU ;destination designator
MOVEI AC3,^D8 ;octal radix
NOUT%
EJSHLT ;fatal error.
;Same as ERJMPS ERROR.
HALTF% ;return to command language
JRST START ;begin again, if continued
ERROR: TMSG<
?ERROR-TYPE START TO BEGIN AGAIN>
HALTF%
JRST START ;user types continue-start
;again
END START
2.6 INITIALIZING AND TERMINATING THE PROGRAM
2.6 INITIALIZING AND TERMINATING THE PROGRAM
Two monitor calls that have not yet been described were used in the
above program - RESET% and HALTF%.
2-7
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
2.6.1 RESET% Monitor Call
2.6.1 RESET% Monitor Call
A good programming practice is to include the RESET% monitor call at
the beginning of every assembly language program. This call closes
any existing open files and releases their JFNs, kills any inferior
processes, clears the software interrupt system (see Chapter 4), and
performs various other process initilization functions. For a
complete list of the functions provided by the RESET% monitor call,
_______ _______ _____
refer to the description of the call in the TOPS-20 Monitor Calls
_________ ______
Reference Manual. The format of the call is
RESET%
and control always returns to the next instruction following the call.
2.6.2 HALTF% Monitor Call
2.6.2 HALTF% Monitor Call
To stop the execution of a program and return control to the TOPS-20
Command Language, the user must include the HALTF% monitor call as the
last instruction performed in the program. The user can then resume
execution of the program at the instruction following the HALTF% call
by typing the CONTINUE command after control has returned to command
level.
2.7 READING A BYTE
2.7 READING A BYTE
The PBIN% (Primary Byte Input) monitor call is used to read a single
byte (that is, one character) from the terminal. The user's program
does not have to specify the source and destination for the byte
because this call uses the primary input designator (that is, the
user's terminal) as the source and accumulator 1 as the destination.
After execution of the PBIN% call, control returns to the instruction
following the PBIN%. If execution of the call is successful, the byte
read from the terminal is right-justified in AC1. If execution of the
call is not successful, an illegal instruction trap is generated, as
explained in Section 1.2.2.
2.8 WRITING A BYTE
2.8 WRITING A BYTE
The PBOUT% (Primary Byte Output) monitor call is used to write a
single byte to the terminal. This call uses the primary output
designator (that is, the user's terminal) as the destination for the
byte; thus, the user's program does not have to specify the
destination. The source of the byte being written is accumulator 1;
therefore, the user's program must place the byte right-justified in
AC1 before the call.
2-8
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
After execution of the PBOUT% call, control returns to the instruction
following the PBOUT%. If execution of the call is successful, the
byte is written to the user's terminal. If execution of the call is
not successful, an illegal instruction trap is generated, as explained
in Section 1.2.2.
2.9 READING A STRING
2.9 READING A STRING
Up to this point, monitor calls have been presented for printing a
string, reading and writing an integer, and reading and writing a
byte. The next call to be discussed obtains a string from the
terminal and, in addition, allows the user at the terminal to edit his
input as he is typing it.
The RDTTY% (Read from Terminal) monitor call reads input from the
user's terminal (that is, from .PRIIN) into the program's address
space. Input is read until the user either types an appropriate
terminating (break) character or inputs the maximum number of
characters allowed in the string, whichever occurs first. Output
generated as a result of character editing is printed on the user's
terminal (that is, output to .PRIOU).
The RDTTY% call handles the following editing functions:
1. Delete the last character in the string if the user presses
the DELETE key while typing his input.
2. Delete back to the last punctuation character in the string
if the user types CTRL/W while typing his input.
3. Delete the current line if the user types CTRL/U while typing
his input.
4. Retype the current line if the user types CTRL/R while typing
his input.
Because the RDTTY% call can handle these editing functions, a program
can accept input from the terminal and allow this input to be
corrected by the user as he is typing it. For this reason, the RDTTY
call should be used to read input from the terminal before processing
that input with calls such as NIN%.
The RDTTY% call accepts three words of arguments in AC1 through AC3.
AC1: pointer to area in program's address space where input is
to be placed. This area is called the text input buffer.
AC2: control bits in the left half, and maximum number of bytes
in the text input buffer in the right half.
2-9
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
AC3: pointer to buffer for text to be output before the user's
input if the user types a CTRL/R, or 0 if only the user's
input is to be output on a CTRL/R.
The control bits in the left half of AC2 specify the characters on
which to terminate the input. These bits are described in Table 2-2.
Table 2-2: RDTTY% Control Bits
Table 2-2: RDTTY% Control Bits
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 RD%BRK Terminate input when user types a
CTRL/Z or presses the ESC key.
1 RD%TOP Terminate input when user types one of
the following:
CTRL/G
CTRL/L
CTRL/Z
ESC key
RETURN key
Line feed key
2 RD%PUN Terminate input when user types one of
the following:
CTRL/A-CTRL/F
CTRL/H-CTRL/I
CTRL/K
CTRL/N-CTRL/Q
CTRL/S-CTRL/T
CTRL/X-CTRL/Y
ASCII codes 34-36
ASCII codes 40-57
ASCII codes 72-100
ASCII codes 133-140
ASCII codes 173-176
The ASCII codes listed above represent
the punctuation characters in the
ASCII character set. Refer to the
ASCII character set table in Appendix
_______ _______ _____
A of the TOPS-20 Monitor Calls
_________ ______
Reference Manual for these characters.
3 RD%BEL Terminate input when user types the
RETURN or line feed key (that is, end
of line).
2-10
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
4 RD%CRF Store only the line feed in the input
buffer when the user presses the
RETURN key. A carriage return will
still be output to the terminal but
will not be stored in the buffer. If
this bit is not set and the user
presses the RETURN key, both the
carriage return and the line feed will
be stored as part of the input.
5 RD%RND Return to program if the user attempts
to delete past the beginning of his
input. This allows the program to
take control if the user tries to
delete all of his input. If this bit
is not set, the program waits for more
input.
6 Reserved for Digital (must be 0).
7 RD%RIE Return to program when there is no
input (that is, the text input buffer
is empty). If this bit is not set,
the program waits for more input.
8 Reserved for Digital (must be 0).
9 RD%BEG Return to user program if the user
attempts to edit beyond the beginning
of the input buffer.
10 RD%RAI Convert lower case input to upper
case.
11 RD%SUI Suppress the CTRL/U indication on the
terminal when a CTRL/U is typed by the
user. This means that if the user
types a CTRL/U, XXX will not be
printed and, on display terminals, the
characters will not be deleted from
the screen. If this bit is not set
and the user types a CTRL/U, XXX will
be printed and, if appropriate, the
characters will be deleted from the
screen. In neither case is the CTRL/U
stored in the input buffer.
2-11
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
15 RD%NED Disable editing characters in user
break mask. If this bit is set, then
any editing character (^R, ^U, ^V, ^W,
and DELETE) in the user supplied break
mask does not have its editing
function.
______________________________________________________________________
If no control bits are set in the left half of AC2, the input will be
terminated when the user presses the RETURN or line feed key (that is,
terminated on an end-of-line condition only).
The count in the right half of AC2 specifies the number of bytes
available for storing the string in the program's address space. The
input is terminated when this count is exhausted, even if a specified
break character has not yet been typed.
The pointer in AC3 is to the beginning of a buffer containing the text
to be output if the user types a CTRL/R. When this happens, the text
in this separate buffer is output, followed by any text that has been
typed by the user. The text in this buffer cannot be edited with any
of the editing characters (that is, DELETE, CTRL/W, or CTRL/U). If
the contents of AC3 is zero, then no such buffer exists, and if the
user types CTRL/R, only the text in the input buffer will be output.
If execution of the RDTTY% call is successful, the input is in the
specified area in the program's address space. The character that
terminated the input is also stored. (If the terminating character is
a carriage return followed by a line feed, the line feed is also
stored.) Control returns to the user's program at the second location
following the call. The pointer in AC1 is advanced to the character
following the last character stored. The count in the right half of
AC2 is updated to reflect the remaining bytes in the buffer, and
appropriate bits are set in the left half of AC2. The bits that can
be set on a successful return are:
Bit 12 RD%BTM The input was terminated because one of
the specified break characters was
typed. This break character is placed
in the input buffer. If this bit is not
set, the input was terminated because
the byte count was exhausted.
Bit 13 RD%BFE Control was returned to the program
because there is no more input and
RD%RIE was set in the call.
2-12
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
Bit 14 RD%BLR The limit to which the user can backup
for editing his input was reached.
For consistent handling of error returns refer to Section 1.2.2.
The following example illustrates the recommended method for reading
data from the terminal. This example is essentially the same as the
one in Section 2.5; however, the RDTTY% call is used to read the
number before the NIN% call processes it. This program stores the
last error encountered in location LASTER and therefore uses the
ERJMPR pseudo-op.
SEARCH MONSYM
SEARCH MACSYM
.REQUIRE SYS:MACREL
AC1==1
AC2==2
AC3==3
START: RESET% ;prepare program environment
HRROI AC1,PROMPT
PSOUT% ;type prompt
HRROI AC1,BUFFER ;location to store number
MOVEI AC2,BUFLEN*5 ;size of buffer
HRROI AC3,PROMPT ;pointer to prompt
RDTTY% ;read number from term. with editing
ERJMPR ERROR ;save error code, print message
HRROI AC1,BUFFER ;and halt source designator
MOVEI AC3,^D10 ;decimal radix
NIN%
ERJMPR ERROR ;if input error, print message
TMSG
MOVEI AC1,.PRIOU ;and halt destination designator
MOVEI AC3,^D8 ;octal radix
NOUT%
ERJMPR ERROR ;save error code, print message
HALTF% ;and halt return to command
JRST START ;language begin again, if continued
PROMPT: ASCIZ/PLEASE TYPE A DECIMAL NUMBER: /
BUFLEN==10
BUFFER: BLOCK BUFLEN
LASTER: BLOCK 1
ERROR: MOVEM AC1,LASTER ;save error code
TMSG <
?ERROR-TYPE START TO BEGIN AGAIN>;print general error message
HALTF% ;halt
JRST START ;start over if continued
END START
2-13
INPUT AND OUTPUT USING THE TERMINAL
INPUT AND OUTPUT USING THE TERMINAL
2.10 SUMMARY
2.10 SUMMARY
Data transfers of sequential bytes or text strings can be made to and
from the terminal. The monitor calls for transferring bytes are PBIN%
and PBOUT% and for transferring strings are PSOUT% and RDTTY%. The
NIN% and NOUT% monitor calls can be used for reading and writing a
number. In general, the user's program must specify a source from
which the data is to be obtained and a destination where the data is
to be placed. In the case of terminal I/O, the symbol .PRIIN
represents the user's terminal as the source, and the symbol .PRIOU
represents the user's terminal as the destination.
2-14
CHAPTER 3
CHAPTER 3
USING FILES
USING FILES
3.1 OVERVIEW
3.1 OVERVIEW
All information stored in the DECSYSTEM-20 is kept in files. The
basic unit of storage in a file is a page containing bytes from 1 to
36 bits in length. Thus, a sequence of pages constitutes a file. In
most cases, files have names. Although all files are handled in the
same manner, certain operations are unavailable for files on
particular devices.
Programs can reference files by several methods:
o In a sequential byte-by-byte manner.
o In a multiple byte or string manner.
o In a random byte-by-byte manner if the particular
file-storage device allows it.
o In a page-mapping or section-mapping manner for files on
disk.
Byte and string input/output are the most common types of operations.
Generally, all programs perform I/O by moving bytes of data from one
location to another. For example, programs can move bytes from one
memory area to another, from memory to a disk file, and from the
user's terminal to memory. In addition, a program can map multiple
512-word pages or 512-page sections from a disk file into memory or
vice versa.
Data transfer operations on files require four steps:
1. Establishing a correspondence between a file and a Job File
Number (JFN), because all files are referenced by JFNs.
2. Opening the file to establish the data mode, access mode, and
byte size and to set up the monitor tables that permit data
to be accessed.
3-1
USING FILES
USING FILES
3. Transferring data either to or from the file.
4. Closing the file to complete any I/O, to update the directory
if the file is on the disk, and to release the monitor table
space used by the file.
Some operations on files do not require the execution of all four
steps above. Examples of these operations are: deleting or renaming
a file, or changing the access code or account of a file. Although
these operations do not require all four steps, they do require that
the file has a JFN associated with it (step 1 above).
It is possible for disk files on the DECSYSTEM-20 to be simultaneously
read or written by any number of processes. To make sharing of files
possible, all instances of opening a specific file in a specific
directory cause a reference to the same data. Therefore, data written
into a file by one process can immediately be seen by other processes
reading the file.
Access to files is controlled by the 6-digit (octal) file access code
assigned to a file when it is created. This code indicates the types
of access allowed to the file for the three classes of users: the
owner of the file, the users with group access to the file, and all
_______ ______ _____
other users. (Refer to the TOPS-20 User's Guide for more information
on the file access codes.) If the user is allowed access to a file, he
requests the type of access desired when opening the file with the
OPENF% monitor call (refer to Section 3.4.1) in his program. If the
access requested in the OPENF% call does not conflict with the current
access to the file, the user is granted access. Essentially, the
current access to the file is set by the first user who opens it.
Thus, for a user to be granted access to a specific file, two
conditions must be met:
1. The file access code must allow the user to access the file
in the desired manner (for example, read, write).
2. The file must not be opened for a conflicting type of access.
3.2 JOB FILE NUMBER
3.2 JOB FILE NUMBER
The Job File Number (JFN) is one of the more important concepts in the
operating system because it serves as the identifier of a particular
file on a particular device during a process' execution. It is a
small integer assigned by the system upon a request from the user's
program. JFNs are usually assigned sequentially starting with 1.
3-2
USING FILES
USING FILES
The JFN is valid for the job in which it is assigned and may be used
by any process in the job. The system uses the JFN as an index into
the table of files associated with the job and always assigns a JFN
that is unique within the job. Even though a particular JFN within
the job can refer to only one file, a single file can be associated
with more than one JFN. This occurs when two or more processes are
using the same file concurrently. In this case, each of the processes
will probably have a different JFN for the file, but all of the JFNs
will be associated with the same file.
3.3 ASSOCIATING A FILE WITH A JFN
3.3 ASSOCIATING A FILE WITH A JFN
In order to reference a file, the first step the user program must
complete is to associate the specific file with a JFN. This
correspondence is established with the GTJFN% (Get Job File Number)
monitor call. One of the arguments to this call is the string
representing the desired file. The string can be specified within the
program (that is, come from memory) or can be accepted as input from
the user's terminal or from another file. The string can represent
the complete specification for the file:
dev:name.typ.gen;T(temporary);P(protection);A(account);
(device dependent attributes)
If you omit any fields of the specification, the system can provide
_______ ______
values for all except the name field. Refer to the TOPS-20 User's
_____
Guide for a complete explanation of the specification for a file.
Table 3-1 lists the values the system will assign to fields not
specified by the input string.
Table 3-1: Standard System Values for File Specifications
Table 3-1: Standard System Values for File Specifications
______________________________________________________________________
Field Value
______________________________________________________________________
Device DSK:
Directory Directory to which user is currently
connected.
Name No default; this field must be
specified.
Type Null.
3-3
USING FILES
USING FILES
Generation number The highest existing generation number
if the file is an input file. The
next higher generation number if the
file is an output file.
Protection Protection of next lower generation of
file, if one exists; otherwise,
protection as specified in the
directory.
Account Account specified when user logged in.
______________________________________________________________________
If the string specified identifies a single file, the monitor returns
a JFN that remains associated with that file until either the process
releases the JFN or the job logs off the system. After the assignment
of the JFN is complete, the user's program uses the JFN in all
references to that file.
The user's program can set up either the short or the long form of the
GTJFN% monitor call. The long form of the GTJFN% call requires an
argument block; the short form does not. The long form of GTJFN% has
functions and flexibility not available in the short form of the call.
The short form of GTJFN% allows a file specification to be obtained
from a string in memory or from a file, but not from both. Fields not
specified by the input are taken from the standard system values for
those fields (refer to Table 3-1). This form is sufficient for most
uses of the call. The long form allows a file specification to be
obtained from both a string in memory and a file. If both are given
as arguments, the string is used first, and then the file is used if
more fields are needed to complete the specification. This form also
allows the user's program to specify nonstandard values to be used for
fields not given and to request the assignment of a specific JFN.
3.3.1 GTJFN% Monitor Call
3.3.1 GTJFN% Monitor Call
The GTJFN% monitor call assigns a JFN to the specified file. It
accepts two words of arguments. These argument words are different
depending on the form of GTJFN% being used. The user's program
indicates the desired GTJFN% form by setting bit 17(GJ%SHT) of AC1 to
1 for the short form or by clearing bit 17(GJ%SHT) for the long form.
3.3.1.1 Short Form of GTJFN%
3.3.1.1 Short Form of GTJFN% - The short form of the GTJFN% monitor
call requires the following two words of arguments.
3-4
USING FILES
USING FILES
0 17 18 35
!=======================================================!
AC1 ! flag bits ! default generation number !
!=======================================================!
0 35
!=======================================================!
AC2 ! source designator for file specification per !
! bit 16 (GJ%FNS) of AC1 !
!=======================================================!
The flag bits that can be specified in AC1 are described in Table 3-2.
Table 3-2: GTJFN% Flag Bits
Table 3-2: GTJFN% Flag Bits
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 GJ%FOU The file specification given is to be
assigned the next higher generation
number. This bit indicates that a new
version of a file is to be created and
is normally set if the file is for
output use.
1 GJ%NEW The file specification given must not
refer to an existing file (that is,
the file must be a new file).
2 GJ%OLD The file specification given must
refer to an existing file. This bit
has no effect on a parse-only JFN.
(See bit GJ%OFG.)
3 GJ%MSG One of the appropriate messages is to
be printed after the file
specification is obtained. The
message is printed only if the user
types the ESC key to end his file
specification (that is, he is using
recognition input).
[NEW FILE]
[NEW GENERATION]
[OLD GENERATION]
[OK] if GJ%CFM (bit 4) is off
[CONFIRM] if GJ%CFM (bit 4) is on
3-5
USING FILES
USING FILES
4 GJ%CFM Confirmation from the user will be
required to verify that the file
specification obtained is correct. To
confirm the file specification, the
user can press the RETURN key.
5 GJ%TMP The file specified is to be a
temporary file.
6 GJ%NS Only the first file specification in a
multiple logical name assignment is to
be searched for the file.
7 GJ%ACC The JFN specified is not to be
accessed by inferior processes in this
job. However, any process can access
the file by acquiring a different JFN.
To prevent the file from being
accessed by other processes, the
user's program can set OF%RTD (bit 29)
in the OPENF call (refer to Section
3.4.1).
8 GJ%DEL The file specified is not to be
considered as deleted, even if it is
marked as deleted.
9-10 GJ%JFN These bits are off in the short form
of the GTJFN call (refer to Section
3.3.1.2 for their description).
11 GJ%IFG The file specification given is
allowed to have one or more of its
fields specified with a wildcard
character (* or %). This bit is used
to process a group of files and is
generally used for input files. The
monitor verifies that at least one
value exists for each field that
contains a wildcard and assigns the
JFN to the first file in the group.
The monitor also verifies that fields
not containing wildcards represent a
new or old file according to the
setting of GJ%NEW and GJ%OLD.
12 GJ%OFG The JFN is to be associated with the
given file specification string only
and not to the actual file. The
string may contain a wildcard
character (* or %) in one or more of
3-6
USING FILES
USING FILES
its fields. It is checked for correct
punctuation between fields, but is not
checked for the validity of any field.
This bit allows a JFN to be associated
with a file specification even if the
file specification does not refer to
an actual file. The JFN returned
cannot be used to refer to an actual
file (for example, cannot be used in
an OPENF call) but can be used to
obtain the original input string via
the JFNS monitor call (refer to
Section 3.7.2).
13 GJ%FLG Flags are to be returned in the left
half of AC1 on a successful return.
14 GJ%PHY Logical names specified for the
current job are to be ignored and the
physical device is to be used.
15 GJ%XTN This bit is off in the short form of
the GTJFN call (refer to Section
3.3.1.2 for its description).
16 GJ%FNS The contents of AC2 are to be
interpreted as follows:
1. If this bit is on, AC2 contains an
input JFN in the left half and an
output JFN in the right half. The
input JFN is used to obtain the
file specification to be
associated with the JFN. The
output JFN is used to indicate the
destination for printing the names
of any fields being recognized.
To omit either JFN, the user's
program must specify the symbol
.NULIO (377777).
2. If this bit is off, AC2 contains a
pointer to a string in memory that
specifies the file to be
associated with the JFN.
17 GJ%SHT This bit must be on (set) for the
short form of the GTJFN% call; it must
be off for the long form of the call.
3-7
USING FILES
USING FILES
18-35 The generation number of the file
(between 1 and 377777) or one of the
following:
0(.GJDEF) to indicate that the next
higher generation number
of the file is to be used
if GJ%FOU (bit 0) is on,
or to indicate that the
highest existing
generation number of the
file is to be used if
GJ%FOU is off. (This
value is usually used in
this field.)
-1(.GJNHG) to indicate that the next
higher generation number
of the file is to be used
if no generation number is
supplied.
-2(.GJLEG) to indicate that the
lowest existing generation
number of the file is to
be used.
-3(.GJALL) to indicate that all
generation numbers (*) of
the file are to be used
and that the JFN is to be
assigned to the first file
in the group. (Bit GJ%IFG
must be set.)
______________________________________________________________________
3-8
USING FILES
USING FILES
If the GTJFN% call is given with the appropriate flag bit set (GJ%IFG
or GJ%OFG), the file specification given as input can have a wildcard
character (either an asterisk or a percent sign) appearing in the
directory, name, type, or generation number field. (The percent sign
cannot appear in the generation number field.) The wildcard character
is interpreted as matching any existing occurrence of the field. For
example, the specification
*.MAC
identifies all the files with the file type .MAC in the directory
named . The specification
MYFILE.FO%
identifies all the files in directory with the name MYFILE
and a three-character file type in which the first two characters are
.FO. Upon completion of the GTJFN call, the JFN returned is
associated with the first file found in the group according to the
following:
o in numerical order by directory number
o in alphabetical order by filename
o in alphabetical order by file type
o in ascending numerical order by generation number
The GNJFN% (Get Next JFN) monitor call can then be given to assign the
JFN to the next file in the group (refer to Section 3.7.3). Normally,
a program that accepts wildcard characters in a file specification
will successively reference all files in the group using the same JFN
and not obtain another JFN for each one.
If execution of the GTJFN% call is not successful because problems
were encountered in performing the call, the JFN is not assigned and
an error code is returned in the right half of AC1. The execution of
the program continues at the instruction following the GTJFN% call.
If execution of the GTJFN% call is successful, the JFN assigned is
returned in the right half of AC1 and various bits are set in the left
half, if flag bits 11, 12, or 13 were on in the call. (The bits
returned on a successful call are described in Table 3-3.) If bit 11,
12, or 13 was not on in the call, the left half of AC1 is zero. The
execution of the program continues at the second instruction after the
GTJFN% call.
3-9
USING FILES
USING FILES
Table 3-3: Bits Returned on GTJFN% Call
Table 3-3: Bits Returned on GTJFN% Call
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 GJ%DEV The device field of the file
specification contains wildcard
characters.
1 GJ%UNT The unit field of the file
specifications contains wildcard
characters. This bit is never set
because wildcard characters are not
allowed in unit fields.
2 GJ%DIR The directory field of the file
specification contains wildcard
characters.
3 GJ%NAM The filename field of the file
specification contains wildcard
characters.
4 GJ%EXT The file type field of the file
specification contains wildcard
characters.
5 GJ%VER The generation number field of the
file specification contains wildcard
characters.
6 GJ%UHV The file used has the highest
generation number because a generation
number of 0 was given in the call.
7 GJ%NHV The file used has the next higher
generation number because a generation
number of 0 or -1 was given in the
call.
8 GJ%ULV The file used has the lowest
generation number because a generation
number of -2 was given in the call.
9 GJ%PRO The protection field of the file
specification was given.
10 GJ%ACT The account field of the file
specification was given.
3-10
USING FILES
USING FILES
11 GJ%TFS The file specification is for a
temporary file.
12 GJ%GND Files marked for deletion are not
considered when assigning JFNs in
subsequent calls. This bit is set if
GJ%DEL was not set in the call.
13 GJ%NOD The node name field of the file
specification was given.
17 GJ%GIV Invisible files were not considered
when assigning JFNs.
______________________________________________________________________
Examples of the short form of the GTJFN% monitor call are shown in the
following paragraphs.
The following sequence of instructions is used to obtain, from the
user's terminal, the specification of an existing file.
MOVX AC1,GJ%OLD+GJ%FNS+GJ%SHT
MOVE AC2,[.PRIIN,,.PRIOU]
GTJFN%
The bits specified for AC1 indicate that the file specification given
must refer to an existing file (GJ%OLD), that the file specification
is to be accepted from the input JFN in AC2 (GJ%FNS), and that the
short form of the GTJFN% call is being used (GJ%SHT). Because the
right half of AC1 is zero, the standard generation number algorithm
will be used. In this GTJFN% call, the file with the highest existing
generation number is used. Because GJ%FNS is set in AC1, the contents
of AC2 are interpreted as containing an input JFN and an output JFN.
In this example, the file specification is obtained from the terminal
(.PRIIN).
The following sequence of instructions is used to obtain, from the
user's terminal, the specification of an output file and to require
confirmation from the user once the file specification has been
obtained.
MOVX AC1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT
MOVE AC2,[.PRIIN,,.PRIOU]
GTJFN%
In this example, the bits specified for AC1 indicate that
o the file obtained is to be an output file (GJ%FOU),
o after the file specification is obtained, a message is to be
typed (GJ%MSG),
3-11
USING FILES
USING FILES
o the user is required to confirm the file specification that
was obtained (GJ%CFM),
o the file specification is to be obtained from the input JFN
in AC2 (GJ%FNS),
o the short form of the GTJFN% call is being used (GJ%SHT).
Because the right half of AC1 is zero, the generation number given to
the file will be one greater than the highest generation number
existing for the file. The contents of AC2 are interpreted as
containing an input JFN and an output JFN because GJ%FNS is set in
AC1.
The following sequence of instructions is used to obtain the name of
an existing file from a location in the user's program.
MOVX AC1,GJ%OLD+GJ%SHT
MOVE AC2,[POINT 7,NAME]
GTJFN%
.
.
.
NAME:ASCIZ/MYFILE.TXT/
The bits specified for AC1 indicate that the file obtained is to be an
existing file (GJ%OLD) and that the short form of the GTJFN% call is
being used (GJ%SHT). Since the right half of AC1 is zero, the file
with the highest generation number will be used. Because GJ%FNS is
not set, the contents of AC2 are interpreted as containing a pointer
to a string in memory that specifies the file to be associated with
the JFN. The setup of AC2 indicates that the string begins at
location NAME in the user's program. The file specification obtained
from location NAME is MYFILE.TXT.
An alternate way of specifying the same file is the sequence
MOVX AC1,GJ%OLD+GJ%SHT
HRROI AC2,[ASCIZ/MYFILE.TXT/]
GTJFN%
3.3.1.2 Long Form of GTJFN%
3.3.1.2 Long Form of GTJFN% - The long form of the GTJFN% monitor
call requires the following two words of arguments:
0 17 18 35
!=======================================================!
AC1 ! 0 ! address of argument table !
!=======================================================!
3-12
USING FILES
USING FILES
0 35
!=======================================================!
AC2 ! pointer to ASCIZ file specification string, or 0 !
!=======================================================!
The argument block for the long form is described in Table 3-4.
Table 3-4: Long Form GTJFN% Argument Block
Table 3-4: Long Form GTJFN% Argument Block
______________________________________________________________________
Word Symbol Meaning
______________________________________________________________________
0 .GJGEN Flag bits appear in the left half and
generation number appears in the right
half.
1 .GJSRC An input JFN appears in the left half
and an output JFN appears in the right
half. To omit either JFN, the user's
program must specify the symbol .NULIO
(377777).
2 .GJDEV Pointer to ASCIZ string that specifies
the device to be used when none is
given. If this word is 0, DSK will be
used.
3 .GJDIR Pointer to ASCIZ string that specifies
the directory to be used when none is
given. If this word is 0, the user's
connected directory will be used.
4 .GJNAM Pointer to ASCIZ string that specifies
the filename to be used when none is
given. If this word is 0, the input
must specify the filename.
5 .GJEXT Pointer to ASCIZ string that specifies
the file type to be used when none is
given. If this word is 0, a null type
will be used.
6 .GJPRO Pointer to ASCIZ string or 3B2+octal
protection code. This word indicates
the protection to be used when none is
given. If this word is 0, the
protection as specified in the
directory will be used.
3-13
USING FILES
USING FILES
7 .GJACT Pointer to ASCIZ string or 3B2+decimal
account number. This word indicates
the account to be used when none is
given. If this word is 0, the account
specified when the user logged in will
be used.
10 .GJJFN The JFN to assign to the file
specification if flag bit GJ%JFN is
set in word .GJGEN (word 0) of the
argument block.
11-17 Additional words allowed if flag bit
GJ%XTN (bit 15) is set in word .GJGEN
(word 0) of the argument block. These
additional words are used when
performing command input parsing and
_______ _______
are described in the TOPS-20 Monitor
_____ _________ ______
Calls Reference Manual.
______________________________________________________________________
The flag bits accepted in the left half of .GJGEN (word 0) of the
argument block are the same as those accepted in the short form of the
GTJFN% call. The entire set of flag bits is listed in Table 3-2.
The generation number values accepted in the right half of .GJGEN
(word 0) of the argument block can be 0, -1, -2, -3, or a specified
number, although 0 is the normal case. Refer to Bits 18-35 of Table
3-2 for explanations of these values.
If execution of the GTJFN% call is successful, the JFN assigned is
returned in the right half of AC1 and various bits are set in the left
half if flag bits 11, 12 or 13 were on in the call. Refer to Table
3-3 for the explanations of the bits returned. Execution of the
program continues at the second instruction following the call.
If execution of the GTJFN call is not successful, the JFN is not
assigned and an error code is returned in the right half of AC1. The
execution of the program continues at the instruction following the
GTJFN% call.
The following sequence of instructions obtains a specification for an
existing file from the user's terminal, assigns the JFN to the next
higher generation of that file, and specifies default fields to be
used if the user omits a field when he gives his file specification.
MOVEI AC1,JFNTAB
SETZ AC2,
GTJFN%
.
.
.
3-14
USING FILES
USING FILES
JFNTAB: GJ%FOU
XWD .PRIIN,.PRIOU
0
POINT 7,[ASCIZ/TRAIN/] ;default directory
0
POINT 7,[ASCIZ/MEM/] ;default file type
0
0
0
The address of the argument table for the GTJFN% call (JFNTAB) is
given in the right half of AC1. AC2 contains 0, which means no
pointer to a string is given; thus, fields for the file specification
will be taken only from the user's terminal. The first word of the
argument block contains a flag bit for the GTJFN% call. This bit
(GJ%FOU) indicates that the next higher generation number is to be
assigned to the file. The second word of the argument block indicates
that the file specification is to be obtained from the user's
terminal, and any output generated because of the user employing
recognition is to be printed on his terminal. If the user does not
supply a directory name as part of his file specification, the
directory will be used. And if the user does not give a file
type, the type MEM will be used. If the user omits other fields from
his specification, the system standard value (refer to Table 3-1) will
be used.
3.3.1.3 Summary of GTJFN%
3.3.1.3 Summary of GTJFN% - The GTJFN% monitor call is required to
associate a JFN with a particular file. In most cases, the short form
of the GTJFN% call is sufficient for establishing this association.
However, the long form is more powerful because it provides the user's
program more control over the file specification that is obtained.
The following summary compares the characteristics of the two forms of
the GTJFN% monitor call.
_____ ____ ____ ____
Short Form Long Form
Assigns a JFN to a file. Assigns a JFN to a file.
System decides the JFN User program may request
to assign. a particular JFN.
Accepts the file specification Accepts the file specification
from a string in memory from a string in memory
or a file. and a file.
Uses standard system values Allows user-supplied values
for fields not given to be used for fields not
in the file given in the file
specification. specification.
3-15
USING FILES
USING FILES
3.4 OPENING A FILE
3.4 OPENING A FILE
Once a JFN has been obtained for a file, the user's program must open
the file in order to transfer data. The user's program supplies the
JFN of the file to be opened and a word of bits indicating the desired
byte size, data mode, and access to the file.
The desired access to the file is specified by a separate bit for each
type of access. The file is successfully opened only if the desired
access does not conflict with the current access to the file (refer to
Section 3.1). For example, if the user requests both read and write
access to the file, but write access is not allowed, then the file is
not opened for this user. The allowed types of access to a file are:
o Read access. The file can be read with byte, string, or
random input.
o Write access. The file can be written with byte, string, or
random output.
o Append access. The file can be written only with sequential
byte or dump output, and the current byte pointer (refer to
Section 3.5.1) cannot be changed. The initial position of
the file pointer is at the end of the file.
o Frozen access. The file can be concurrently accessed by at
most one user writing the file, but by any number of users
reading the file. This is the default access to a file.
o Thawed access. The file can be accessed even if other users
are reading and writing the file.
o Restricted access. The file cannot be accessed if another
user already has opened the file.
o Unrestricted read access. The file can be read regardless of
what other users might be doing with the file.
3.4.1 OPENF% Monitor Call
3.4.1 OPENF% Monitor Call
The OPENF% (Open File) monitor call opens a specified file. It
requires the following two words of arguments.
3-16
USING FILES
USING FILES
0 17 18 35
!=======================================================!
AC1 ! 0 ! JFN of file to be opened !
!=======================================================!
0 5 6 9 18 30 31 35
!=======================================================!
AC2 ! byte !data ! 0 ! access bits ! 0 !
! size !mode ! ! ! !
!=======================================================!
If the left half of AC1 is not 0, the contents of AC1 is interpreted
as a pointer to a string, not as a JFN. If the user's program
requests bits returned in AC1 from the GTJFN% call, these bits must be
cleared before executing the OPENF% call.
The byte size (OF%BSZ) in AC2 specifies the number of bits in each
byte of the file and can be between 1 and 36 (decimal). If this field
is 0 a byte size of 36 (decimal) is assumed.
The file data mode field (OF%MOD) usually has one of two values:
Value Meaning
0 Normal data mode of the file (that is, byte
I/O). Dump I/O is illegal.
17 Dump mode (that is, unbuffered word I/O).
Byte I/O is illegal and the byte size is
ignored.
The access bits are described in Table 3-5.
Table 3-5: OPENF% Access Bits
Table 3-5: OPENF% Access Bits
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0-5 OF%BSZ Byte size (maximum of 36 decimal).
6-9 OF%MOD Data mode in which to open file.
18 OF%HER Halt on the occurrence of an I/O
device or medium error during
subsequent I/O to the file. If this
bit is not set, a software interrupt
is generated if a device or medium
error occurs during subsequent I/O.
3-17
USING FILES
USING FILES
19 OF%RD Allow read access.
20 OF%WR Allow write access.
21 OF%EX Allow execute access.
22 OF%APP Allow append access.
23 OF%RDU Allow unrestricted read access.
24 Reserved for Digital.
25 OF%THW Allow thawed access. If this bit is
not set, the file is opened for frozen
access.
26 OF%AWT Block (that is, temporarily suspend)
the program until access to the file
is permitted.
27 OF%PDT Do not update the access dates of the
file.
28 OF%NWT Return an error if access to the file
cannot be permitted.
29 OF%RTD Allow access to the file to only one
process (that is, restricted access).
30 OF%PLN Do not check for line numbers in the
file.
31 OF%DUD Suppress system updating of modified
pages in memory to thawed files on
disk unless CLOSF or UFPGS issued.
32 OF%OFL Open device even if off-line.
33 OF%FDT Force update of .FBREF (last read) in
FDB and increment RH of .FBCNT (number
of references).
34 OF%RAR Wait if file off-line.
______________________________________________________________________
If bits OF%AWT and OF%NWT are both off, an error code is returned if
access to the file cannot be permitted (that is, the action taken is
identical to OF%NWT being on).
3-18
USING FILES
USING FILES
If execution of the OPENF% monitor call is successful, the file is
opened, and the execution of the program continues at the second
instruction after the OPENF% call.
If execution of the OPENF% call is not successful, the file is not
opened, and an error code is returned in AC1. The execution of the
program continues at the next instruction after the OPENF% call.
Two samples of the OPENF% call follow.
The sequence of instructions below opens a file for input.
HRRZ AC1,JFNEXT
MOVX AC2,FLD(44,OF%BSZ)+OF%RD+OF%PLN
OPENF%
The JFN of the file to be opened is contained in the location
indicated by the address in AC1 (JFNEXT). The bits specified for AC2
indicate that the byte size is one word FLD(44,OF%BSZ), that read
access is being requested to the file (OP%RD), and that no check will
be made for line numbers in the file; that is, the line numbers will
not be discarded (OF%PLN). Because bit OF%THW is not set, the file
can be accessed for reading by any number of processes.
The following sequence of instructions can be used to open a file for
output.
MOVE AC1,JFN
MOVX FLD(7,OF%BSZ)+OF%HER+OF%WR+OF%AWT
OPENF%
The right half of AC1 contains the address that has the JFN of the
file to be opened. The bits specified for AC2 indicate that the byte
size is 7-bit bytes FLD(7,OF%BSZ), that the program is to be halted
when an I/O error occurs in the file (OF%HER), that write access is
being requested to the file (OF%WR), and that the program is to be
blocked if access cannot be granted (OF%AWT). Because bit OF%THW is
not set, if another user has been granted write access to the file,
this user's program will be blocked until access can be granted.
3.5 TRANSFERRING DATA
3.5 TRANSFERRING DATA
Data transfers of sequential bytes are the most common form of
transfer and can be used with any file. For disk files, nonsequential
bytes and entire pages can also be transferred.
3-19
USING FILES
USING FILES
3.5.1 File Pointer
3.5.1 File Pointer
Every open file is associated with a pointer that indicates the last
byte read from or written to the file. When the file is initially
opened, this pointer is normally positioned before the beginning of
the file so that the first data operation will reference the first
byte in the file. The pointer is then advanced through the file as
data is transferred. However, if the file is opened for append-only
access (bit OF%APP set in the OPENF% call), the pointer is positioned
after the last byte of the file. This allows the first write
operation to append data to the end of the file.
For disk files, the pointer may be repositioned arbitrarily throughout
the file, such as in the case of nonsequential data transfers. When
the pointer is positioned beyond the end of the file, an end-of-file
indication is returned when the program attempts a read operation
using byte input. When the program performs a write operation beyond
the end of the file using byte output, the end-of-file indicator is
updated to point to the end of the new data. However, if the program
writes pages beyond the end of the file with the PMAP% monitor call
(refer to section 3.5.6), the byte count is not updated. Therefore,
it is possible for a file to contain pages of data beyond the
end-of-file indicator. To allow sequential I/O to be performed later
to the file, the program should update the byte count before closing
the file. (Refer to the CHFDB% monitor call description in the
_______ _______ _____ _________ ______
TOPS-20 Monitor Calls Reference Manual.)
3.5.2 Source and Destination Designators
3.5.2 Source and Destination Designators
Because I/O operations occur by moving data from one location to
another, the user's program must supply a source and a destination for
any I/O operation. The most commonly-used source and destination
designators are the following:
1. A JFN associated with a particular file. The JFN must be
previously obtained with the GTJFN% or GNJFN% monitor call
before it can be used.
2. The primary input and output designators .PRIIN and .PRIOU,
respectively (refer to Section 2.2). These designators
should be used when referring to the terminal.
3. A byte pointer to the beginning of the string of bytes in the
program's address space that is being read or written. The
byte pointer can take one of two forms:
o A word with a -1 in the left half and an address in the
right half. This form is used to designate a 7-bit ASCIZ
string starting in the left-most byte of the specified
address. A word in this form is functionally equivalent
to a word assembled by the POINT 7,ADR pseudo-op.
3-20
USING FILES
USING FILES
o A full word byte pointer with a byte size of 7 bits.
Most monitor calls dealing with strings deal specifically with ASCII
strings. Normally, ASCII strings are assumed to terminate with a byte
of 0 (that is, are assumed to be ASCIZ strings). However some calls
optionally accept an explicit byte count and/or terminating byte.
These calls are generally ones that handle non-ASCII strings and byte
sizes other than 7 bits.
3.5.3 Transferring Sequential Bytes
3.5.3 Transferring Sequential Bytes
The BIN% (Byte Input) and BOUT% (Byte Output) monitor calls are used
for sequential byte transfers. The BIN% call takes the next byte from
the given source and places it in AC2. The BOUT% call takes the byte
from AC2 and writes it to the given destination. The size of the byte
is that given in the OPENF% call for the file.
The BIN% monitor call accepts a source designator in AC1, and upon
successful execution of the call, the byte is right-justified in AC2.
If execution of the call is not successful, an illegal instruction
trap is generated. Control returns to the user's program at the
instruction following the BIN% call. If the end of the file is
reached, AC2 contains 0 instead of a byte. The program can process
this end-of-file condition if a jump style error return is the next
instruction following the BIN% call.
The BOUT% monitor call accepts a destination designator in AC1 and the
byte to be output, right-justified in AC2. Upon successful execution
of the call, the byte is written to the destination. If execution of
the call is not successful, an illegal instruction trap is generated
Control returns to the user's program at the instruction following the
BOUT% call.
The following sequence shows the transferring of bytes from an input
file to an output file. The bytes are read from the file indicated by
INJFN and written to the file indicated by OUTJFN.
LOOP: MOVE 1,INJFN ;get source designator from INJFN
BIN% ;read a byte from the source
ERJMP DONE ;check for end of file, if 0
LOOP2: MOVE 1,OUTJFN ;get destination from OUTJFN
BOUT% ;write the byte to the destination
JRST LOOP ;continue until 0 byte is found
DONE: GTSTS% ;obtain status of source
TXNN 2,GS%EOF ;test for end of file
JRST NOTYET ;no, test for 0 in input file
: ;yes, process end of file condition
NOTYET:MOVEI 2,0 ;0 in input file
JRST LOOP2
3-21
USING FILES
USING FILES
3.5.4 Transferring Strings
3.5.4 Transferring Strings
The SIN% (String Input) and SOUT% (String Output) monitor calls are
used for string transfers. These calls transfer either a string of a
specified number of bytes or a string terminated with a specific byte.
The SIN% monitor call reads a string from the specified source into
the program's address space. The call accepts four words of arguments
in AC1 through AC4.
AC1: source designator
AC2: pointer to area in program's address space
AC3: count of number of bytes to read, or 0
AC4: byte on which to terminate input (optional)
The contents of AC3 are interpreted as the number of characters to
read.
o If AC3 is 0, then reading continues until a 0 byte is found
in the input.
o If AC3 is positive, then reading continues until either the
specified number of bytes is read, or a byte equal to that
given in AC4 is found in the input, whichever occurs first.
o If AC3 is negative, then reading continues until minus the
specified number of bytes is read.
The contents of AC4 needs to be specified only if the contents of AC3
is a positive number. The byte in AC4 is right-justified.
The input is terminated when one of the following occurs:
o The byte count becomes zero.
o The specified terminating byte is reached.
o The end of the file is reached.
o An error occurs during the transfer (for example, a data
error occurs).
Control returns to the user's program at the instruction following the
SIN% call. If an error occurs (including the end of the file is
reached), an illegal instruction trap is generated. In addition,
several locations are updated:
3-22
USING FILES
USING FILES
1. The position of the file's pointer is updated for subsequent
I/O to the file.
2. The pointer to the string in AC2 is updated to reflect the
last byte read or, if AC3 contained 0, the last nonzero byte
read.
3. The count in AC3 is updated, if pertinent, by subtracting the
number of bytes actually read from the number of bytes
requested to be read (that is, the count is updated toward
zero). From this count, the user's program can determine the
number of bytes actually transferred.
The SOUT% monitor call writes a string from the program's address
space to the specified destination. Like the SIN% call, this call
accepts four words of arguments in AC1 through AC4.
AC1: destination designator
AC2: pointer to string to be written
AC3: count of the number of bytes to write, or 0
AC4: byte on which to terminate output (optional)
The contents of AC3 and AC4 are interpreted in the same manner as they
are in the SIN% monitor call.
The transfer is terminated when one of the following occurs.
o The byte count becomes zero.
o The specified terminating byte is reached. This terminating
byte is written to the destination.
o An error occurs during the transfer.
Control returns to the user's program at the instruction following the
SOUT% call. If an error occurs, an illegal instruction trap is
generated. In addition, the position of the file's pointer, the
pointer to the string in AC2, and the count in AC3, if pertinent, are
also updated in the same manner as in the SIN% monitor call.
The following code sequence shows transferring a string from an input
file to an output file. The procedure is the same as at the end of
Section 3.5.3, using SIN% and SOUT% calls instead of BIN% and BOUT%.
LOOP: MOVE 1,INJFN ;get source from INJFN
HRROI 2,BUF128 ;pointer to string to read into (128
;word buffer)
3-23
USING FILES
USING FILES
MOVNI 3,^D128*5 ;input a maximum of 640 bytes
SIN% ;transfer until end of buffer or end of
;file
ERCAL EOFQ ;error occurred
ADDI 3,^D128*5 ;determine negative number of
;bytes transferred
MOVN 3,3 ;convert to positive
MOVE 1,OUTJFN ;get destination from OUTJFN
HRROI 2,BUF128 ;pointer to string to write from
SOUT% ;transfer as many bytes as read
EOFQ: MOVE 1,INJFN
GTSTS% ;obtain status of source
TXNN 2,GS%EOF ;test for end of file
RET ;no, continue copying
3.5.5 Transferring Nonsequential Bytes
3.5.5 Transferring Nonsequential Bytes
As discussed in Section 3.5.3, the BIN% and BOUT% calls transfer bytes
sequentially, starting at the current position of the file's pointer.
The RIN% (Random Input) and ROUT% (Random Output) monitor calls allow
the user's program to specify where the transfer will begin by
accepting a byte number within the file. The size of the byte is the
size given in the OPENF% call for the file. The RIN% and ROUT% calls
can only be used when transferring data to or from disk files.
The RIN% monitor call takes a byte from the specified location in the
file and places it into the accumulator. The call accepts the JFN of
the file in AC1 and the byte number within the file in AC3. Upon
successful completion of the call, the byte is right-justified in AC2,
and the file's pointer is updated to point to the byte following the
one just read. If an error occurs, an illegal instruction trap is
generated. Control returns to the user's program at the instruction
following the RIN% call.
The ROUT% monitor call takes a byte from the accumulator and writes it
into the specified location in the file. The call accepts the JFN of
the file in AC1, the byte to write right-justified in AC2, and the
byte number within the file in AC3. Upon successful completion of the
call, the byte is written into the specified byte in the file, and the
file's pointer is updated to point to the byte following the one just
written. If an error occurs, an illegal instruction trap is
generated. Control returns to the user's program at the instruction
following the ROUT% call.
3.5.6 Mapping Pages
3.5.6 Mapping Pages
Up to this point, monitor calls have been presented for transferring
3-24
USING FILES
USING FILES
bytes and strings of data. The next call to be discussed is used to
transfer entire pages of data between a file and a process.
Both files and process address spaces are divided into pages of
512(decimal) words. A page within a file can be identified by one
word, where the JFN of the file is in the left half and the page
number within the file is in the right half. A page within a process
address space can also be identified by one word, where the identifier
of the process (refer to Section 5.3) is in the left half and the page
number within the process' address space is in the right half. Each
one-word identifier for the pages in the process address space is
placed in what is called the process page map. When identifiers for
file pages are placed in the process page map, references to the
process page actually refer to the file page. The following diagram
illustrates a process map that has identifiers for pages from two
files.
File 1
__________
| |
Process Map | |
_____________ | |
| | | |
| | | |
|-------------| |----------|
|JFN1 |Page 1|-------------->| Page 1 |
|-------------| |----------|
| | | |
| | | |
|-------------| |__________|
| |
| |
| | File 2
| | __________
| | | |
| | | |
|-------------| |----------|
|JFN2 |Page 2|-------------->| Page 2 |
|-------------| |----------|
| | | |
| | | |
|_____________| | |
| |
| |
|__________|
The PMAP% (Page Mapping) monitor call is used to map one or more
entire pages from a file to a process (for input), from a process to a
file (for output), or from one process to another process. In
general, this call changes the entries in the process map by accepting
3-25
USING FILES
USING FILES
file page identifiers and process page identifiers as arguments.
Mapping pages between a file and a process is described below; mapping
pages between two processes is described in Chapter 5.
3.5.6.1 Mapping File Pages to a Process
3.5.6.1 Mapping File Pages to a Process - This use of the PMAP% call
changes the map of the process so that references to pages in the
process reference pages in a file. This does not actually cause data
to be transferred; it simply changes the contents of the map. Later
when changes are made to the actual page in the process, the changes
will also be made to the page in the file, if write access has been
specified for the file.
Note that you cannot map file pages to pages in a process section that
does not exist in the the process map. If you use PMAP% to input file
pages to pages in a nonexistent section of a process, the monitor
generates an illegal instruction trap.
In addition, you can map one or more file sections (of 512 pages each)
into a process. See Section 8.3.1 for details.
The PMAP% call accepts three words of arguments in AC1 through AC3.
AC1: JFN of the file in the left half, and the page number in
the file in the right half
AC2: process identifier (refer to Section 5.3) in the left
half, and page number in the process in the right half
AC3: repetition count and access
The repetition count and access bits that can be specified in AC3 are
described in Table 3-6.
Table 3-6: PMAP% Access Bits
Table 3-6: PMAP% Access Bits
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 PM%CNT Repeat the mapping operation the number of
times specified by the right half of AC3. The
file page number and the process page number
are incremented by 1 each time the operation
is performed.
2 PM%RD Allow read access to the page.
3 PM%WR Allow write access to the page.
3-26
USING FILES
USING FILES
4 PM%EX Reserved.
The symbol PM%RWX can be used to set B2-4.
5 PM%PLD Preload page being mapped (move the page
immediately instead of waiting until it is
referenced).
9 PM%CPY Create a private copy of the page if the
process writes into the page. This is called
copy-on-write and causes the map to be changed
so that it identifies the copy instead of the
original. Write access is allowed to the copy
even if it was not allowed to the original.
This allows a process to change a page of data
without changing the data for other processes
that have also mapped the page.
10 PM%EPN Bits 18-35 of AC2 contain extended (18-bit)
process page number. If the section
containing the page does not exist, a private
section is created.
11 PM%ABT Unmap page and discard (abort) changed
contents.
18-35 PM%RPT The number of times to repeat the mapping
operation if bit 0(PM%CNT) is set.
______________________________________________________________________
With this use of the PMAP% call, the present contents of the page in
the process are removed. If the page in the file is currently
nonexistent, it will be created when it is written.
This use of the PMAP% call is valid only if the file is opened for at
least read access. If write access is requested in the PMAP% call, it
is not granted unless it was also specified in the OPENF% call when
the file was opened.
A file cannot be closed while any of its pages are mapped into any
process. Thus, before a file is closed, its pages must be unmapped
(refer to Section 3.5.6.3).
After execution of the PMAP% call, control returns to the user's
program at the instruction following the call. If an error occurs, an
illegal instruction trap is generated.
3.5.6.2 Mapping Process Pages to a File
3.5.6.2 Mapping Process Pages to a File - This use of the PMAP% call
actually transfers data by moving the specified page in the process to
the specified page in the file. The process map for the page is now
3-27
USING FILES
USING FILES
empty. Both the page in the process and the page in the file must be
private; that is, no other process can have the page mapped into its
address space. The ownership of the process page is transferred to
the file page. The previous contents of the page in the file are
deleted.
The three words of arguments are as follows:
AC1: process identifier (refer to Section 5.3) in the left
half, and page number in the process in the right half
AC2: JFN of the file in the left half, and the page number in
the file in the right half
AC3: repetition count and access (refer to Section 3.5.6.1)
The access requested in the PMAP% call is granted only if it does not
conflict with the access specified in the OPENF% call when the file
was opened.
This use of the PMAP% call does not automatically update the files
byte count and the byte size. To allow the file to be read later with
sequential I/O monitor calls, the program should update the file's
byte count and the byte size. (Refer to the CHFDB% monitor call in
_______ _______ _____ _________ ______
the TOPS-20 Monitor Calls Reference Manual).
3.5.6.3 Unmapping Pages in a Process
3.5.6.3 Unmapping Pages in a Process - As stated previously, a file
cannot be closed if any of its pages are mapped in any process. To
unmap a file's pages from a process, the program must execute the
SMAP% call, or the following form of the PMAP% call:
AC1: -1
AC2: process identifier in the left half, and page number in
the process in the right half.
AC3: the repeat count for the number of pages to remove from
the process (refer to Section 3.5.6.1).
3.5.7 Mapping File Sections to a Process
3.5.7 Mapping File Sections to a Process
A section of memory is a unit of 512 pages of process address space.
File sections also contain 512 pages. The first page of each file
section has a page number that is an integral multiple of 512. Like
memory pages, sections can be mapped from one process to another, from
a process to itself, or from a file to a process. Chapter 8 describes
the SMAP% call completely.
3-28
USING FILES
USING FILES
The SMAP% (Section Mapping) monitor call is similar to the PMAP% call.
The SMAP% call maps one or more sections from a file to a process (for
input), or from one process to another process. To map a process
section to a file, you must use the PMAP% call as described in Chapter
5 to map each page.
Mapping a file section to a process section with SMAP% does not cause
data to move from the disk to memory. Instead, SMAP% changes the
contents of the process memory map so that the process section pointer
points to a file section. The monitor transfers data only when your
program references a memory page to which a file page is mapped.
To map a file section to a process section, SMAP% requires three
arguments:
AC1: source identifier: a JFN in the left half, and a file
section number in the right half. If several contiguous
sections are to be mapped, the number in the right half is
that of the first section in the group of contiguous
sections.
AC2: destination identifier: process identifier in the left
half, and a process section number in the right half. If
several contiguous sections are to be mapped, the number
in the right half is the number of the first section into
which SMAP% maps a file section.
AC3: flags that control access to the process section in the
left half, and, in the right half, the number of sections
to map into the process. The number of sections to map
cannot be less than 1 nor more than 32 (decimal).
The flags in the left half of AC3 are described in Table 3-7.
Table 3-7: SMAP% Access Bits
Table 3-7: SMAP% Access Bits
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
2 SM%RD Allow read access.
3 SM%WR Allow write access.
4 SM%EX Allow execute access.
6 SM%IND Map the destination section using an indirect
section pointer.
______________________________________________________________________
3-29
USING FILES
USING FILES
3.6 CLOSING A FILE
3.6 CLOSING A FILE
Once data has been transferred to or from a file, the user's program
must close the file. When a file is closed, the system automatically
performs the following:
1. Updates the directory information for the file. For example,
for a file to which sequential bytes had been written, the
byte size and byte count are updated when the file is closed.
2. Releases the JFN associated with the file. However, the
user's program can request to close the file, but retain the
JFN assignment. This is useful if the program plans to
reopen the same file later, but does not want to execute
another GTJFN% call.
3.6.1 CLOSF% Monitor Call
3.6.1 CLOSF% Monitor Call
The CLOSF% (Close File) monitor call closes either the specified file
or all files that are opened for the process executing the call. The
CLOSF% call accepts one word of arguments in AC1 - flag bits in the
left half and the JFN of the file to be closed in the right half. The
flag bits are described in Table 3-8.
Table 3-8: CLOSF% Flag Bits
Table 3-8: CLOSF% Flag Bits
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 CO%NRJ Do not release the JFN from the file.
6 CZ%ABT Abort any output operations currently being
done. That is, close the file but do not
perform normal cleanup operations (for example,
do not output any data remaining in the
buffers). If output to a new disk file that has
not been closed is aborted, the file is closed
and then deleted.
7 CS%NUD Do not update the copy of the directory on the
disk (refer to the CHFDB% description in the
_______ _______ _____ _________ ______
TOPS-20 Monitor Calls Reference Manual for more
information).
______________________________________________________________________
If the contents of AC1 is -1, all files that are opened for this
process are closed.
3-30
USING FILES
USING FILES
If the execution of the CLOSF% call is successful, the specified file
is closed, and the JFN associated with the file is released if CO%NRJ
was not set in the call. The execution of the user's program
continues at the second location after the CLOSF% call.
If the execution of the CLOSF% call is not successful, the file is not
closed and an error code is returned in the right half of AC1. The
execution of the user's program continues at the instruction following
the CLOSF% call.
The following sequence illustrates the closing of two files.
CLOSIF: HRRZ 1,INJFN ;obtain input JFN
CLOSF% ;close input file
ERJMP FATAL ;if error, print message and stop
CLOSOF: HRRZ 1,OUTJFN ;obtain output JFN
CLOSF% ;close output file
ERJMP FATAL ;if error, print message and stop
3.7 ADDITIONAL FILE I/O MONITOR CALLS
3.7 ADDITIONAL FILE I/O MONITOR CALLS
3.7.1 GTSTS% Monitor Call
3.7.1 GTSTS% Monitor Call
The GTSTS% (Get Status) monitor call obtains the status of a file.
This call accepts one argument word - the JFN of the file in the right
half of the AC1. The left half of AC1 is zero.
Control always returns to the user's program at the instruction
following the GTSTS% call. Upon return, appropriate bits reflecting
the status of the specified JFN are set in AC2. These bits, and their
meanings, are described in Table 3-9. Note that if the JFN is illegal
or unassigned, bit 10 (GS%NAM) will not be set.
Table 3-9: Bits Returned on GTSTS% Call
Table 3-9: Bits Returned on GTSTS% Call
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 GS%OPN The file is open. If this bit is not
set, the file is not open.
1 GS%RDF If the file is open (for example,
GS%OPN is set), it is open for read
access.
3-31
USING FILES
USING FILES
2 GS%WRF If the file is open, it is open for
write access.
3 GS%XCF File is open for execute access.
4 GS%RND If the file is open, it is open for
non-append access (that is, its
pointer can be reset).
5-6 Reserved for Digital.
7 GS%LNG File has pages in existence beyond
page number 511.
8 GS%EOF The last read operation to the file
was at the end of the file.
9 GS%ERR The file may be in error (for example,
the bytes read may be erroneous).
10 GS%NAM A file specification is associated
with this JFN. This bit will not be
set if the JFN is in any way illegal.
11 GS%AST One or more fields of the file
specification associated with this JFN
contain a wildcard character.
12 GS%ASG The JFN is currently being assigned
(that is, a process other than the one
executing the GTSTS call is assigning
this JFN).
13 GS%HLT An I/O error is considered to be a
terminating condition for this JFN.
That is, the OPENF% call for this JFN
had bit OF%HER set.
14-16 Reserved for Digital.
17 GS%FRK Access to the file is restricted to
only one process.
18 GS%PLN If on, file line numbers are passed
during input; if zero, line numbers
are stripped before input.
19-31 Reserved for Digital.
32-35 GS%MOD The data mode of the file (refer to
the OPENF% call).
3-32
USING FILES
USING FILES
Value Symbol Meaning
0 .GSNRM Normal (sequential) I/O
1 .GSSMB Small buffer mode
10 .GSIMG Image (binary) I/O
17 .GSDMP Dump I/O
______________________________________________________________________
An example of the GTSTS% call is shown in the first program in Section
3.9.
3.7.2 JFNS% Monitor Call
3.7.2 JFNS% Monitor Call
The JFNS% (JFN to String) monitor call returns the file specification
currently associated with the specified JFN. The call accepts three
words of arguments in AC1 through AC3.
AC1: destination designator where the file specification
associated with the JFN is to be written. This
specification is an ASCIZ string.
AC2: JFN or pointer to string (see below)
AC3: format to be used when returning the specification (see
below)
The contents of AC1 can be any valid destination designator (refer to
Section 3.5.2).
The contents of AC2 can be one of two formats. The first format is a
word with either flag bits or 0 in the left half and the JFN in the
right half. The bits that can be given in the left half of AC2 are
the ones returned from the GTJFN% call (refer to Table 3-3). When the
left half of AC2 is nonzero (that is, contains the bits returned from
the GTJFN% call), the string returned will contain wildcard characters
for appropriate fields and 0, -1, or -2 as a generation number if the
corresponding bit is on in the JFNS% call. When the left half of AC2
is 0, the string returned is the exact specification for the file (for
example, wildcard characters are not returned for any fields). If the
JFN is associated only with a file specification and not with an
actual file (that is, bit GJ%OFG was set in the GTJFN% call), the
string returned will contain null fields for unspecified fields and
the actual values for specified fields. The second format allowed for
AC2 is a pointer to the string in the program's address space that is
_______
to be returned upon execution of the call. Refer to the TOPS-20
_______ _____ _________ ______
Monitor Calls Reference Manual for the explanation of this format.
3-33
USING FILES
USING FILES
The contents of AC3 specify the format in which the specification is
written to the destination. Bits 0 through 20 are divided into 3-bit
bytes, each byte representing a field in the file specification. The
value of the byte indicates the format for that field. The possible
values are:
Value Symbol Meaning
0 .JSNOF Do not return this field when returning the
file specification.
1 .JSAOF Always return this field when returning the
file specification.
2 .JSSSD Suppress this field if it is the standard
system value for this field (refer to Table
3-1).
If the contents of AC3 is zero, the file specification is written in
the format
dev:name.typ.gen;T
with fields the same as the standard system value (see Table 3-1) not
returned and protection and account fields returned only if bit 9 and
bit 10 in AC2 are on, respectively. The temporary attribute (;T) is
returned only if the file is temporary.
Table 3-10 describes the bits that can be set in AC3.
Table 3-10: JFNS% Format Options
Table 3-10: JFNS% Format Options
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
0 JS%NOD Print node name if node name is
present.
1-2 JS%DEV Format for device field.
3-5 JS%DIR Format for directory field.
6-8 JS%NAM Format for filename field. A value of
2 (that is, bit 7 set) for this field
is illegal.
9-11 JS%TYP Format for file type field. A value
of 2 (that is, bit 10 set) for this
field is illegal.
3-34
USING FILES
USING FILES
12-14 JS%GEN Format for generation number field.
0-14 JS%SPC Output for all file specification
fields named above. This field should
have the same bits set as would be set
in the fields above. (See B35
(JS%PAF) below.)
15-17 JS%PRO Format for protection field.
18-20 JS%ACT Format for account field.
21 JS%TMP Return temporary file indication ;T if
the file specification is for a
temporary file.
22 JS%SIZ Return size of file in pages (see
below).
23 JS%CDR Return creation date of file (see
below).
24 JS%LWR Return date of last write operation to
file (see below).
25 JS%LRD Return date of last read operation
from file (see below).
26 JS%PTR AC2 contains a pointer to the string
containing the field to be returned
_______ _______ _____
(refer to the TOPS-20 Monitor Calls
_________ ______
Reference Manual for a description of
this use of the JFNS% call).
27 JS%ATR Return file specification attributes
if appropriate.
28 JS%AT1 Return specification attribute
referenced in AC4.
29 JS%OFL Return the "OFF-LINE" attribute.
30-31 Reserved for Digital.
32 JS%PSD Punctuate the size and date fields
(see below) in the file specification
returned.
33 JS%TBR Place a tab before all fields returned
(that is, fields whose value is given
as 1 in the 3-bit field) in the file
specification, except for the first
field.
3-35
USING FILES
USING FILES
34 JS%TBP Place a tab before all fields that may
be returned (that is, fields whose
value is given as 1 or 2 in the 3-bit
field) in the file specification,
except for the first field.
35 JS%PAF Punctuate all fields (see below)
returned in the file specification
from the device field through the ;T
field.
If bits 32 through 35 are not set, no
punctuation is used between the
fields.
______________________________________________________________________
The punctuation used on each field is shown below.
dev:name.typ.gen;A(account);P(protection);T(temporary)
,size,creation date,write date,read date
Refer to Section 1.2.2 for information on error returns.
3.7.3 GNJFN% Monitor Call
3.7.3 GNJFN% Monitor Call
Occasionally a program may be written to perform similar operations on
a group of files instead of only on one file. However, the program
should not require the user to give a file specification for each
file. Because the GTJFN% call associates a JFN with only one file at
a time, the program needs a method of assigning a JFN to all the files
in the group. By using the GTJFN% call to initially obtain the JFN
and the GNJFN% call to assign the same JFN to each subsequent file in
the group, a program can accept a specification for a group of files
and process each file in the group individually. After the user gives
the initial file specification, the program requires no additional
input.
Before an example showing the interaction of these two calls is given,
a description of the GNJFN% (Get Next JFN) monitor call is
appropriate.
The GNJFN% monitor call assigns a JFN to the next file in a group of
files that have been specified with wildcard characters. The next
file is determined by searching the directory in the order described
in Section 3.3.1.1 using the current file as the first item. This
call accepts one argument word in AC1 - the flags returned from the
GTJFN% call in the left half and the JFN of the current file in the
right half. In other words, the information returned in AC1 from the
GTJFN% call is given as an argument to the GNJFN% call. Therefore,
the program must save this information for use with the GNJFN% call.
3-36
USING FILES
USING FILES
If execution of the GNJFN% call is successful, the same JFN is
assigned to the next file in the group. The left half of AC1 contains
various flags and the right half contains the JFN. The execution of
the program continues at the second instruction after the GNJFN% call.
Table 3-11 describes the bits that can be returned in AC1 on a
successful GNJFN% call.
Table 3-11: GNJFN% Return Bits
Table 3-11: GNJFN% Return Bits
______________________________________________________________________
Bit Symbol Meaning
______________________________________________________________________
13 GN%STR A change in structure occurred between
the previous file and this file.
14 GN%DIR A change in directory occurred between
the previous file and this file.
15 GN%NAM A change in filename occurred between
the previous file and this file.
16 GN%EXT A change in file type occurred between
the previous file and this file. If
GN%NAM is on, this bit will also be on
because the system considers two files
with different filenames but with the
same file type as a change in both the
name and type.
______________________________________________________________________
If execution of the GNJFN% call is not successful, an error code is
returned in the right half of AC1. Conditions that can cause an error
return are:
1. The file currently associated with the JFN must be closed,
and it is not. This means that the program must execute a
CLOSF% call (with CO%NRJ set to retain the JFN) before
executing a GNJFN% call.
2. There are no more files in this group. This return occurs on
the first GNJFN% call after all files in the group have been
stepped through. The JFN is released when there are no more
files. (Note: This error may occur if the file currently
associated with the JFN is deleted or renamed.)
3-37
USING FILES
USING FILES
The execution of the program continues at the next instruction after
the GNJFN% call.
Consider the following situation. The user wants to write a program
that will accept from his terminal a specification for a group of
files and then perform an operation on each file individually without
requiring additional input. Assume the user's directory
contains the following files:
FIRST.MAC.1
FIRST.REL.1
SECOND.REL.1
THIRD.EXE.1
As discussed in Section 3.3.1.1, a group of files can be given to the
GTJFN call by supplying a specification that contains wildcard
characters in one or more of its fields. Thus, the specification
*.*
would refer to all four files in the user's directory .
In his program, the user includes a GTJFN% call that will accept the
above specification.
The call is
MOVX AC1,GJ%OLD+GJ%IFG+GJ%FLG+GJ%FNS+GJ%SHT
MOVE AC2,[.PRIIN,,.PRIOU]
GTJFN%
and indicates that
1. The file specification given must refer to an existing file
(GJ%OLD).
2. The file specification given is allowed to contain wildcard
characters (GJ%IFG).
3. Flags will be returned in AC1 on a successful call (GJ%FLG).
The flags must be returned because they will be given to the
GNJFN% call as arguments.
4. The contents of AC2 will be interpreted as containing an
input and output JFN (GJ%FNS).
5. The short form of the GTJFN% call is being used (GJ%SHT).
6. The file specification is to be read from the user's terminal
(.PRIIN,,.PRIOU).
3-38
USING FILES
USING FILES
When the user types the specification *.* as input, the system
associates the JFN with one file only. This file is the first one
found when searching the directory in the order specified in Section
3.3.1.1. Thus the JFN returned is associated with the file
FIRST.MAC.1.
After the GTJFN% call is successfully executed, AC1 contains
appropriate flags in the left half and the JFN assigned in the right
half. The flags that will be returned in this particular situation
are:
GJ%NAM (bit 3) A wildcard character appeared in the name
field of the file specification given.
GJ%EXT (bit 4) A wildcard character appeared in the type
field of the file specification given.
GJ%GND (bit 12) Any files marked for deletion will not be
considered.
These flags inform the program of the fields that contained wildcard
characters. The user's program must now save the contents of AC1
because this word will be used as the argument to the GNJFN% call.
The program then performs its desired operation on the first file.
Once its processing is completed, the program is ready for the
specification of the next file. But instead of requesting the
specification from the user, the program executes the GNJFN% call to
obtain it. The argument to the GNJFN% call is the contents of AC1
returned from the previous GTJFN% call. Thus, the call in this case
is equivalent to:
MOVE AC1,[GJ%NAM+GJ%EXT+GJ%GND,,JFN]
GNJFN%
Upon successful execution of the GNJFN% call, the JFN is now
associated with the next file in the group (that is, FIRST.REL.1).
AC1 contains appropriate flags in the left half and the same JFN in
the right half. In this example, the flag returned is GN%EXT (bit 16)
to indicate that the file type changed between the two files.
After processing the second file, the user's program executes another
GNJFN% call using the original contents of AC1 returned from the
GTJFN% call. The original contents must be used because this word
indicates the fields containing wildcard characters. If the current
contents of AC1 (that is, the flags returned from the GNJFN% call) are
used, a subsequent GNJFN% call would fail because there are no flags
set indicating fields containing wildcard characters. This second
GNJFN% call associates the JFN with the file SECOND.REL.1. The flags
returned in AC1 are GN%NAM (bit 15) and GN%EXT (bit 16) indicating
that the filename and file type changed between the two files.
(Remember that a change in filename implies a change in file type even
if the two file types are the same.)
3-39
USING FILES
USING FILES
After processing this third file, the user's program executes another
GNJFN% call using the original contents of AC1. Upon execution of the
call, the JFN is now associated with THIRD.EXE.1, and the flags
returned are GN%NAM and GN%EXT, indicating a change in the filename
and file type.
After processing the file THIRD.EXE.1, the user's program executes a
final GNJFN% call. Since there are no more files in the group, the
call returns an error code and releases the JFN. Execution of the
user's program continues at the instruction following the GNJFN% call.
3.8 SUMMARY
3.8 SUMMARY
To read from or write to a file, the user's program must:
1. Obtain a JFN on the file with the GTJFN% monitor call (refer
to Section 3.3.1).
2. Open the file with the OPENF% monitor call (refer to Section
3.4.1).
3. Transfer the data with byte, string, or page I/O monitor
calls (refer to Section 3.5).
4. Close the file with the CLOSF% monitor call (refer to Section
3.6.1).
3.9 FILE EXAMPLES
3.9 FILE EXAMPLES
Example 1 - This program assigns JFNs, opens an input file and an
output file, and copies data from the input file to the output file.
Data is copied until the end of the input file is reached. Refer to
_______ _______ _____ _________ ______
the TOPS-20 Monitor Calls Reference Manual for explanation of the
ERSTR% monitor call.
;*** PROGRAM TO COPY INPUT FILE TO OUTPUT FILE. ***
; (USING BIN%/BOUT% AND IGNORING NULLS)
TITLE FILEIO ;TITLE OF PROGRAM
SEARCH MONSYM ;SEARCH SYSTEM JSYS-SYMBOL LIBRARY
SEARCH MACSYM
.REQUIRE SYS:MACREL
;*** IMPURE DATA STORAGE AND DEFINITIONS ***
INJFN: BLOCK 1 ;STORAGE FOR INPUT JFN
OUTJFN: BLOCK 1 ;STORAGE FOR OUTPUT JFN
3-40
USING FILES
USING FILES
PDLEN=3 ;STACK HAS LENGTH 3
PDLST: BLOCK PDLEN ;SET ASIDE STORAGE FOR STACK
STDAC. ;DEFINE STANDARD ACs. SEE MACSYM.
;*** PROGRAM INITILIZATION ***
START: RESET% ;CLOSE FILES, ETC.
MOVE P,[IOWD PDLEN,PDLST] ;ESTABLISH STACK
;*** GET INPUT FILE ***
INFIL: ;PROMPT FOR INPUT FILE
TMSG <
INPUT FILE: > ;ON CONTROLLING TERMINAL
MOVX T1,GJ%OLD+GJ%FNS+GJ%SHT ;SEARCH MODES FOR GTJFN
;EXISTING FILE ONLY, FILE-NRs IN B
;SHORT CALL
MOVE T2,[.PRIIN,,.PRIOU] ;GTJFN'S I/O WITH CONTROLLING TERM
GTJFN% ;GET JOB FILE NUMBER (JFN)
ERJMPS [ PUSHJ P,WARN ;IF ERROR, GIVE WARNING
JRST INFIL] ;AND LET HIM TRY AGAIN
MOVEM T1,INJFN ;SUCCESS, SAVE THE JFN
;*** GET OUTPUT FILE ***
OUTFIL: ;PRINT PROMPT FOR
TMSG <
OUTPUT FILE: > ;OUTPUT FILE
MOVX T1,GJ%FOU+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT ;GTJFN SEARCH MODES
;[DEFAULT TO NEW GENERATION, PRINT
; MESSAGE, REQUIRE CONFIRMATION
; FILE-NR'S IN T2, SHORT CALL ]
MOVE T2,[.PRIIN,,.PRIOU] ;I/O WITH CONTROLLING TERMINAL
GTJFN% ;GET JOB FILE NUMBER
ERJMPS [ PUSHJ P,WARN ;IF ERROR, GIVE WARNING
JRST OUTFIL] ;AND LET HIM TRY AGAIN
MOVEM T1,OUTJFN ;SAVE THE JFN
;NOW, OPEN THE FILES WE JUST GOT
; INPUT
MOVE T1,INJFN ;RETRIEVE THE INPUT JFN
MOVX T2,FLD(7,OF%BSZ)+OF%RD ;MODES FOR OPENF
;[7-BIT BYTES + INPUT]
OPENF% ;OPEN THE FILE
ERJMPS FATAL ;IF ERROR, GIVE MESSAGE AND STOP
; OUTPUT
MOVE T1,OUTJFN ;GET THE OUTPUT JFN
3-41
USING FILES
USING FILES
MOVX T2,FLD(7,OF%BSZ)+OF%WR ;MODES FOR OPENF
;[7-BIT BYTES + OUTPUT]
OPENF% ;OPEN THE FILE
ERJMPS FATAL ;IF ERROR, GIVE MESSAGE AND STOP
;*** MAIN LOOP: COPY BYTES FROM INPUT TO OUTPUT ***
LOOP: MOVE T1,INJFN ;GET THE INPUT JFN
BIN% ;TAKE A BYTE FROM THE SOURCE
JUMPE T2,DONE ;IF 0, CHECK FOR END OF FILE
MOVE T1,OUTJFN ;GET THE OUTPUT JFN
BOUT ;OUTPUT THE BYTE TO DESTINATION
ERCALS ERROR
JRST LOOP ;LOOP, STOP ONLY ON A 0 BYTE
;(FOUND AT LOOP+2)
;*** TEST FOR END OF FILE, ON SUCCESS FINISH UP ***
DONE: GTSTS% ;GET THE STATUS OF INPUT FILE
TXNN T2,GS%EOF ;AT END OF FILE?
JRST LOOP ;NO, FLUSH NULL AND CONTINUE COPY
CLOSIF: MOVE T1,INJFN ;YES, RETRIEVE INPUT JFN
CLOSF% ;CLOSE INPUT FILE
ERJMPS FATAL ;IF ERROR, GIVE MESSAGE AND STOP
CLOSOF: MOVE T1,OUTJFN ;RETRIEVE OUTPUT JFN
CLOSF% ;CLOSE OUTPUT FILE
ERJMPS FATAL ;IF ERROR, GIVE MESSAGE AND STOP
TMSG <
[DONE]> ;SUCCESSFULLY DONE
JRST ZAP ;STOP
;*** ERROR HANDLING ***
FATAL: TMSG <
?> ;FATAL ERRORS PRINT ? FIRST
PUSHJ P,ERROR ;THEN PRINT ERROR MESSAGE
JRST ZAP ;AND STOP
WARN: TMSG <
%> ;WARNINGS PRINT % FIRST
;AND FALL THRU 'ERROR'
;BACK TO CALLER
ERROR: MOVEI T1,.PRIOU ;DECLARE PRINCIPAL OUTPUT DEVICE
;FOR ERROR MESSAGE
MOVE T2,[.FHSLF,,-1] ;CURRENT FORK,, LAST ERROR
SETZ T3, ;NO LIMIT,, FULL MESSAGE
ERSTR% ;PRINT THE MESSAGE
3-42
USING FILES
USING FILES
JFCL ;IGNORE UNDEFINED ERROR NUMBER
JFCL ;IGNORE ERROR DURING EXE OF ERSTR
POPJ P, ;RETURN TO CALLER
ZAP: HALTF% ;STOP
JRST START ;WE ARE RESTARTABLE
END START ;TELL LINKING LOADER START ADDRESS
Example 2 - This program accepts input from a user at the terminal and
then outputs the data to the line printer. Refer to Section 2.9 for
explanation of the RDTTY% call.
TITLE LPTPNT ;PROGRAM TO PRINT TERMINAL INPUT
;ON PRINTER
SEARCH MONSYM ;SEARCH SYSTEM JSYS-SYMBOL LIBRARY
SEARCH MACSYM
.REQUIRE SYS:MACREL
STDAC. ;DEFINE STANDARD ACs
BUFSIZ==200
PDLEN==50
COUNT: BLOCK 1
LPTJFN: BLOCK 1
BUFFER: BLOCK BUFSIZ
PDL: BLOCK PDLEN
START: RESET% ;RESET I/O, ETC.
MOVE P,[IOWD PDLEN,PDL] ;SET UP STACK
TMSG ;OUTPUT PROMPTING TEXT
HRROI T1,BUFFER ;GET POINTER TO BUFFER
MOVE T2,[RD%BRK+BUFSIZ*5] ;GET FLAG AND MAX # OF CHARS TO READ
SETZM T3 ;NO RE-TYPE BUFFER
RDTTY% ;INPUT TEXT FROM TERMINAL
EJSHLT ;ERROR, STOP
HRRZS T2 ;GET CHARS REMAINING IN BUFFER
MOVEI T1,BUFSIZ*5 ;COMPUTE NUMBER OF CHARS READ =
SUB T1,T2 ;BUFFERSIZE MINUS CHARS REMAINING
SOS T1 ;DON'T INCLUDE ^Z
MOVEM T1,COUNT ;SAVE # OF CHARS INPUT
;GET A JFN FOR THE PRINTER AND OPEN THE PRINTER
MOVX T1,GJ%SHT!GJ%FOU ;OUTPUT FILE, SHORT CALL
HRROI T2,[ASCIZ /LPT:/] ;GET POINTER TO NAME OF FILE
GTJFN% ;GET A JFN FOR THE PRINTER
ERJMPS JFNERR ;ERROR, PRINT ERROR MESSAGE
MOVEM T1,LPTJFN ;REMEMBER PRINTER JFN
MOVX T2,FLD(7,OF%BSZ)+OF%WR ;7-BIT BYTES,
;WRITE ACCESS WANTED
3-43
USING FILES
USING FILES
OPENF% ;OPEN THE PRINTER FOR OUTPUT
ERJMPS OPNERR ;ERROR, PRINT ERROR MESSAGE
;NOW OUTPUT THE TEXT THAT WAS INPUT FROM THE TERMINAL
HRROI T2,BUFFER ;GET POINTER TO TEXT
;(PRINTER JFN STILL IN T1)
MOVN T3,COUNT ;GET NUMBER OF CHARS TO OUTPUT
SOUT% ;OUTPUT STRING OF CHARS TO
;THE PRINTER
ERJMPS DATERR ;ERROR, PRINT ERROR MESSAGE
TMSG <
OUTPUT HAS BEEN SENT TO THE PRINTER...
> ;OUTPUT CONFIRMATION MESSAGE
MOVE T1,LPTJFN ;GET PRINTER JFN
CLOSF% ;CLOSE IT
ERJMPS DATERR ;UNEXPECTED ERROR, PRINT ERROR MESSAGE
HALTF% ;FINISHED
JRST START ;IF CONTINUED, GO BACK TO START
;ERROR ROUTINES
JFNERR: TMSG<
? COULD NOT GET A JFN FOR THE PRINTER
>
HALTF%
JRST START ;IF CONTINUED, GO BACK TO START
OPNERR: TMSG<
? COULD NOT OPEN THE PRINTER FOR OUTPUT
>
HALTF%
JRST START ;IF CONTINUED, GO BACK TO START
DATERR: TMSG<
? DATA ERROR DURING OUTPUT TO PRINTER
>
HALTF%
JRST START ;IF CONTINUED, GO BACK TO START
END START
3-44
CHAPTER 4
CHAPTER 4
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
4.1 OVERVIEW
4.1 OVERVIEW
Program execution usually occurs in a sequential manner, where
instructions are executed one after another. But sometimes a program
must be able to receive asynchronous signals from terminals, the
monitor, or other programs, or as a result of its own execution. By
using the software interrupt system, the user can specify conditions
that will cause his program to deviate from its sequential method of
execution.
An interrupt is defined as a break in the normal flow of control
during a program's execution. The break, or interrupt, is caused by
the occurrence of a prespecified condition. By specifying the
conditions that can cause an interrupt, the program has the capability
of dynamically responding to external events and error conditions and
of generating requests for services. Because the program can respond
to special conditions as they occur, it does not have to explicitly
and repeatedly test for them. In addition, the program's execution is
faster because the program does not have to include a special test
after the possible occurrence of the condition.
When an interrupt occurs, the system transfers control from the main
program sequence to a previously-specified routine that will process
the interrupt. After the routine has completed its processing of the
interrupt, the system can transfer control back to the program at the
point it was interrupted, and execution can continue. See Figure 4-1.
4-1
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
-----------------
| User Program |
| is |
| Executing |
-----------------
|
V
-----------------
| Interrupt |
| Condition |
| Occurs |
-----------------
|
V
^ ^
/ \ / \
/ \ / \
/ Has \ /Is An\
/Program\ /Inter- \
/ Enabled \ /rupt of \ -----------------
/for Condi- \ Yes /Higher Pri-\ No | Execute |
----------->< ority Being >------->| User's Inter- |
\ Channel / ^ \ Processed / | rupt Routine |
\ ? / | \ ? / --------|--------
\ / | \ / |
\ / | \ / |
\ / | \ / |
\ / | \ / |
V | V |
| No | | Yes |
| | V |
| | ---------------------- |
V | | Wait Until | |
----------------- | | Higher Priority | |
| Perform System| | | Interrupt Finishes | |
| Default Action| | --------|------------- |
| (e.g., stops | | | |
| job, print | \-------------/ |
| message) | |
--------|-------- |
| <------------------------------------------------/
V
-----------------
| User Program |
| Continues if |
| Job Has Not |
| Not Been |
| Terminated |
-----------------
4-2
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
Figure 4-1: Basic Operational Sequence of the Software Interrupt
Figure 4-1: Basic Operational Sequence of the Software Interrupt
System
System
4-3
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
4.2 INTERRUPT CONDITIONS
4.2 INTERRUPT CONDITIONS
Conditions that cause the program to be interrupted when the interrupt
system is enabled are:
1. Conditions generated when specific terminal keys are typed.
There are 36 possible codes; each one specifies the
particular terminal character or condition on which an
interrupt is to be initiated. Refer to Table 4-2 for the
possible codes.
2. Invalid instructions (for example, I/O instructions given in
user mode) or privileged monitor calls issued by a non
privileged user.
3. Memory conditions, such as illegal memory references.
4. Arithmetic processor conditions, such as arithmetic overflow
or underflow.
5. Certain file or device conditions, such as end of file.
6. Program-generated software interrupts.
7. Termination of an inferior process.
8. System resource unavailability.
9. Interprocess communication (IPCF) and Enqueue/Dequeue
interrupts.
4.3 SOFTWARE INTERRUPT CHANNELS AND PRIORITIES
4.3 SOFTWARE INTERRUPT CHANNELS AND PRIORITIES
Each condition is associated with one of 36 software interrupt
channels. Most conditions are permanently assigned to specific
channels; however, the user's program can associate some conditions
(for example, conditions generated by specific terminal keys) to any
one of the assignable channels. (Refer to Table 4-1 for the channel
assignments.) When the condition associated with a channel occurs, and
that channel has been activated, an interrupt is generated. Control
can then be transferred to the routine responsible for processing
interrupts on that channel.
The user program assigns each channel to one of three priority levels.
Priority levels allow the occurrence of some conditions to suspend the
processing of other conditions. The levels are referred to as level
1, 2, or 3 with level 1 having the highest priority. Level 0 is not a
legal priority level.[1]
4-4
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
Table 4-1: Software Interrupt Channel Assignments
Table 4-1: Software Interrupt Channel Assignments
______________________________________________________________________
Channel Symbol Meaning
______________________________________________________________________
0-5 Assignable by user program
6 .ICAOV Arithmetic overflow
7 .ICFOV Arithmetic floating point overflow
8 Reserved for Digital
9 .ICPOV Pushdown list (PDL) overflow*
10 .ICEOF End of file condition
11 .ICDAE Data error file condition*
12 .ICQTA Disk quota exceeded
13-14 Reserved for Digital
15 .ICILI Illegal instruction*
16 .ICIRD Illegal memory read*
17 .ICIWR Illegal memory write*
18 Reserved for Digital
19 .ICIFT Inferior process termination
20 .ICMSE System resources exhausted*
21 Reserved for Digital
22 .ICNXP Nonexistent page reference
23-35 Assignable by user program
______________________________________________________________________
---------------
[1] If an interrupt is generated in a process where the priority
level is 0, the system considers that the process is not
prepared to handle the interrupt. The process is then suspended
or terminated according to the setting of bit 17 (SC%FRZ) in its
capability word.
4-5
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
* These channels (called panic channels) cannot be completely
deactivated. An interrupt generated on one of these channels
terminates the process if the channel is not activated.
The software interrupt system processes interrupts on activated
channels only, and each channel can be activated and deactivated
independently of other channels. When activated, the channel can
generate an interrupt for its associated priority level. An interrupt
for any priority level is initiated only if there are no interrupts in
progress for the same or higher priority levels. If there are, the
system remembers the interrupt request and initiates it after all
equal or higher priority level interrupts finish. This means that a
higher priority level request can suspend a routine processing a lower
level interrupt. Thus, the user must be concerned with several items
when he assigns his priority levels. He must consider 1) when one
interrupt request can suspend the processing of another and 2) when
the processing of a second interrupt cannot be deferred until the
completion of the first.
4.4 SOFTWARE INTERRUPT TABLES
4.4 SOFTWARE INTERRUPT TABLES
To process interrupts, the user includes, as part of his program,
special service routines for the channels he will be using. He must
then specify the addresses of these routines to the system by setting
up a channel table. In addition, the user must also include a
priority level table as part of his program. Finally, he must declare
the addresses of these tables to the system.
4.4.1 Specifying the Software Interrupt Tables
4.4.1 Specifying the Software Interrupt Tables
Before using the software interrupt system, the user's program must
set up the contents of the channel table and the priority level table.
The program must then specify their addresses with either the SIR% or
XSIR% monitor calls.
These calls are similar, but their differences are important. The
SIR% call can be used in single-section programs, but the XSIR% call
must be used in programs that use more than one section of memory.
The SIR% call works in non-zero sections only if the tables are in the
same section as the code that makes the call. The code that causes
the interrupt must also be in that section, as must the code that
processes the interrupt. Because of the limitations of the SIR% call,
you should use the XSIR% call.
The SIR% monitor call accepts two words of arguments: the identifier
for the program (or process) in AC1, and the table addresses in AC2.
Refer to Section 5.3 for the description of process identifiers.
4-6
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
The following example shows the use of the SIR% call.
MOVEI 1,.FHSLF ;identifier of current process
MOVE 2,[LEVTAB,,CHNTAB] ;addresses of the tables
SIR%
The XSIR% call accepts the following arguments: in AC1, the
identifier of the process for which the interrupt channel tables are
to be set; in AC2, the address of the argument block.
The argument block is a three-word block that has the following
format:
!======================================================!
! Length of the argument block, including this word !
!------------------------------------------------------!
! Address of the interrupt level table !
!------------------------------------------------------!
! Address of the channel table !
!======================================================!
Control always returns to the user's program at the instruction
following the SIR% and XSIR% calls. If the call is successful, the
table addresses are stored in the monitor. If the call is not
successful, an illegal instruction trap is generated.
Any changes made to the contents of the tables after the XSIR% or SIR%
calls have been executed will be in effect at the time of the next
interrupt.
4.4.2 Channel Table
4.4.2 Channel Table
The channel table, CHNTAB,[2] contains a one-word entry for each
channel; thus, the table has 36 entries. Each entry corresponds to a
particular channel, and each channel is associated at any given time
with only one interrupt condition. (Refer to Table 4-1 for the
interrupt conditions associated with each channel.)
The CHNTAB table is indexed by the channel number (0 through 35). The
general format, for use with the XSIR% and XRIR% monitor calls, can be
used in any section of memory. The left half of each entry contains
the priority level (1, 2, or 3) in bits 0-5 (SI%LEV) to which the
channel is assigned. Bits 6-35 (SI%ADR) of each entry contain the
starting address of the routine to process interrupts generated on
---------------
[2] The user can call his priority channel table any name he
desires; however, it is good practice to call it CHNTAB.
4-7
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
that channel. If a particular channel is not used, the corresponding
entry in the channel table should be zero.
In the older format, for use with the SIR% and RIR% calls by any
single-section program, the left half of each word contains the
priority level (1, 2, or 3) for that channel. The right half contains
the address of the interrupt routine that will handle interrupts on
that channel.
The following example is for use with the XSIR% monitor call.
CHNTAB: FLD(2,SI%LEV)+FLD(CHN0SV,SI%ADR) ;channel 0
FLD(2,SI%LEV)+FLD(CHN1SV,SI%ADR) ;channel 1
FLD(2,SI%LEV)+FLD(CHN2SV,SI%ADR) ;channel 2
FLD(2,SI%LEV)+FLD(CHN3SV,SI%ADR) ;channel 3
0 ;channel 4
0 ;channel 5
FLD(1,SI%LEV)+FLD(APRSRV,SI%ADR) ;channel 6
0 ;channel 7
0 ;channel 8
FLD(1,SI%LEV)+FLD(STKSRV,SI%ADR) ;channel 9
0 ;channel 10
. .
. .
. .
0 ;channel 35
In this example, channels 0 through 3 are assigned to priority level
2, with the interrupt routine at CHN0SV servicing channel 0, the
routine at CHN1SV servicing channel 1, the routine at CHN2SV servicing
channel 2, and the routine at CHN3SV servicing channel 3. Channels 6
and 9 are assigned to priority level 1, with the routine at APRSRV
servicing channel 6 and the routine at STKSRV servicing channel 9.
All remaining channels are not assigned.
4.4.3 Priority Level Table
4.4.3 Priority Level Table
The priority level table, LEVTAB,[3] The priority level table, LEVTAB,
[3] is a three-word table, containing a one-word entry for each of the
three priority levels. In the general form, each word contains the
30-bit address of the first word of the two-word block in the process
address space. The block addressed by word n of LEVTAB is used to
store the global PC flags and address when an interrupt of level n+1
occurs.
The PC flags are stored in the first word of the PC block, and the PC
---------------
[3] The user can call his priority level table any name he desires;
however, it is good practice to call it LEVTAB.
4-8
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
address is stored in the second. This form of the table must be used
with the XSIR% and XRIR% monitor calls, and can be used in any
section.
The older form of the interrupt level table can be used in any
single-section program, and must be used with the SIR% and RIR% calls.
This table also contains three words, indexed by the priority level
minus 1. Each word contains zero in the left half, and the 18-bit
address of the word in which to store the one-word section-relative PC
in the right half. This address is assumed to be in the same program
section that contained the SIR% monitor call. (For more information
see Chapter 8.) The system must save the value of the program counter
so that it can return control at the appropriate point in the program
once the interrupt routine has completed processing an interrupt. If
a particular priority level is not used, its corresponding entry in
the level table should be zero.
The following is a sample of a level table.
LEVTAB: 0,,PCLEV1 ;Addresses to save PC for interrupts
0,,PCLEV2 ;occurring on priority levels 1 and 2.
0,,0 ;No priority level 3 interrupts are
;planned
4.5 ENABLING THE SOFTWARE INTERRUPT SYSTEM
4.5 ENABLING THE SOFTWARE INTERRUPT SYSTEM
Once the interrupt tables have been set up and their addresses defined
with the XSIR% monitor call, the user's program must enable the
interrupt system. When the interrupt system is enabled, interrupts
that occur on activated channels are processed by the user's interrupt
routines. When the interrupt system is disabled, the monitor
processes interrupts as if the channels for these interrupts were not
activated.
The EIR% monitor call, used to enable the system, accepts one
argument: the identifier for the process in AC1.
MOVEI 1,.FHSLF ;identifier of current process
EIR%
Control always returns to the instruction following the EIR call.
4.6 ACTIVATING INTERRUPT CHANNELS
4.6 ACTIVATING INTERRUPT CHANNELS
Once the software interrupt system is enabled, the channels on which
interrupts can occur must be activated (refer to Table 4-1 for the
channel assignments). The channels to be activated have a nonzero
entry in the appropriate word in the channel table.
4-9
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
The AIC% monitor call activates one or more of the 36 interrupt
channels. This call accepts two words of arguments - the identifier
for the process in AC1, and the channels to be activated in AC2.
The channels are indicated by setting bits in AC2. Setting bit n
indicates that channel n is to be activated. The AIC% call activates
only those channels for which bits are set.
MOVEI 1,.FHSLF ;identifier of current process
MOVE 2,[1B<.ICAOV>+1B<.ICPOV>] ;activate channels 6 and 9
AIC%
Control always returns to the instruction following the AIC% call.
Some channels, called panic channels, cannot be deactivated by
disabling the channel or the entire interrupt system. (Refer to Table
4-1 for these channels.) This is because the occurrence of the
conditions associated with these channels cannot be completely ignored
by the monitor.
If one of these conditions occurs, an interrupt is generated whether
the channel is activated or not. If the channel is not activated, the
process is terminated, and usually a message is output before control
returns to the monitor. If the channel is activated, control is given
to the user's interrupt routine for that channel.
4.7 GENERATING AN INTERRUPT
4.7 GENERATING AN INTERRUPT
A process generates an interrupt by producing a condition for which an
interrupt channel is enabled, such as arithmetic overflow, or by using
the IIC% monitor call. This call can generate an interrupt on any of
the 36 interrupt channels of the process the calling process
specifies. See Section 5.10 for a description of the IIC% call.
4.8 PROCESSING AN INTERRUPT
4.8 PROCESSING AN INTERRUPT
When a software interrupt occurs on a given priority level, the
monitor stores the current program counter (PC) word in the address
indicated in the priority level table (refer to Section 4.4.3). The
monitor then transfers control to the interrupt routine associated
with the channel on which the interrupt occurred. The address of this
routine is specified in the channel table (refer to Section 4.4.2).
Since the user's program cannot determine when an interrupt will
occur, the interrupt routine must preserve the state of the program so
the program can be resumed properly. First, the routine stores the
contents of any user accumulators for use while processing the
interrupt. After the accumulators are saved, the interrupt routine
processes the interrupt.
4-10
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
Occasionally, an interrupt routine may need to alter locations in the
main section of the program. For example, a routine may change the
stored PC word to resume execution at a location different from where
the interrupt occurred. Or it may alter a value that caused the
interrupt. It is important that care be used when writing routines
that alter data because any changes will remain when control is
returned to the main program. For example, if data is inadvertently
stored in the PC word, return to the main section of the program would
be incorrect when the system attempted to use the word as the value of
the program counter.
If a higher-priority interrupt occurs during the execution of an
interrupt routine, the execution of the lower-priority routine is
suspended. The value of its program counter is stored at the location
indicated in the priority level table for the new interrupt. When the
routine for this new interrupt is completed, the suspended routine
resumes.
If an interrupt of the same or lower priority occurs during the
execution of a routine, the monitor holds the interrupt until all
higher or equal level interrupts have been processed.
The system considers the user's program unable to process an interrupt
on an activated channel if any of the following is true:
1. The priority level associated with the channel is 0.
2. The program has not defined its interrupt tables by executing
an XSIR% or SIR% monitor call.
3. The process has not enabled the interrupt system by executing
an EIR% monitor call, and the channel on which the interrupt
occurs is a panic channel.
In any of these cases, an interrupt on a panic channel terminates the
user's program. All other interrupts are ignored.
4.8.1 Dismissing an Interrupt
4.8.1 Dismissing an Interrupt
Once the processing of an interrupt is complete, the interrupt routine
should restore the user accumulators to their initial values. Then it
should return control to the interrupted code by using the DEBRK%
monitor call. This call restores the PC word and resumes the program.
The call has no arguments, and must be the last statement in the
interrupt routine.
If the interrupt-processing routine has not changed the PC of the
user's program, the DEBRK% call restores the program to the same state
4-11
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
the program was in just before the interrupt occurred. If the program
was interrupted while waiting for I/O to complete, for example, the
program will again be waiting for I/O to complete when it resumes
execution after the DEBRK% call.
If the PC word was changed, the program resumes execution at the new
PC location. The state of the program is unchanged.
4.9 TERMINAL INTERRUPTS
4.9 TERMINAL INTERRUPTS
The user's program can associate channels 0 through 5 and channels 24
through 35 with occurrences of various conditions, such as the
occurrence of a particular character typed at the terminal or the
receipt of an IPCF message. This section discusses terminal
interrupts; refer to Chapters 6 and 7 for other types of assignable
interrupts.
There are 36 codes used to specify terminal characters or conditions
on which interrupts can be initiated. These codes, along with their
associated conditions, are shown in Table 4-2.
Table 4-2: Terminal Codes and Conditions
Table 4-2: Terminal Codes and Conditions
______________________________________________________________________
Code Symbol Character or Condition
______________________________________________________________________
0 .TICBK CTRL/@ or break
1 .TICCA CTRL/A
2 .TICCB CTRL/B
3 .TICCC CTRL/C
4 .TICCD CTRL/D
5 .TICCE CTRL/E
6 .TICCF CTRL/F
7 .TICCG CTRL/G
8 .TICCH CTRL/H
9 .TICCI CTRL/I
10 .TICCJ CTRL/J
4-12
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
11 .TICCK CTRL/K
12 .TICCL CTRL/L
13 .TICCM CTRL/M
14 .TICCN CTRL/N
15 .TICCO CTRL/O
16 .TICCP CTRL/P
17 .TICCQ CTRL/Q
18 .TICCR CTRL/R
19 .TICCS CTRL/S
20 .TICCT CTRL/T
21 .TICCU CTRL/U
22 .TICCV CTRL/V
23 .TICCW CTRL/W
24 .TICCX CTRL/X
25 .TICCY CTRL/Y
26 .TICCZ CTRL/Z
27 .TICES ESC key
28 .TICRB Delete (or rubout) key
29 .TICSP Space
30 .TICRF Dataset carrier off
31 .TICTI Typein
32 .TICTO Typeout
33 .TITCE Two-character escape sequence
34-35 Reserved
______________________________________________________________________
To cause terminal interrupts to be generated, the user's program must
assign the desired terminal code to one of the assignable channels.
4-13
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
The ATI% monitor call is used to assign this code. This call accepts
one word of arguments: the terminal code in the left half of AC1 and
the channel number in the right half.
MOVE 1,[.TICCE,,INTCH1] ;assign CTRL/E to channel INTCH1
ATI%
Control always returns to the instruction following the ATI% call. If
the current job is not attached to a terminal (there is no terminal
controlling the job), the terminal code assignments are remembered;
they will be in effect when a terminal is attached.
The monitor handles the receipt of a terminal interrupt character in
either immediate mode or deferred mode. In immediate mode, the
terminal character causes the system to initiate an interrupt as soon
as the user types the character (that is, as soon as the system
receives it). In deferred mode, the terminal character is placed in
either immediate mode or deferred mode. In immediate mode, the
terminal character causes the system to initiate an interrupt as soon
as the user types the character (as soon as the system receives it).
In deferred mode, the terminal character is placed in the input stream
in sequence with other characters of the input, unless two of the same
character are typed in succession. In this case, an interrupt occurs
at the time the second one is typed. If only one character enabled in
deferred mode is typed, the system initiates an interrupt only when
the program attempts to read the character. Deferred mode allows
interrupt actions to occur in sequence with other actions specified in
the input (for example, when characters are typed ahead of the time
that the program actually requests them). In either mode, the
character is not passed to the program as data. The system assumes
that interrupts are to be handled immediately unless a program has
issued the STIW% (Set Terminal Interrupt Word) monitor call. (Refer
_______ _______ _____ _________ ______
to TOPS-20 Monitor Calls Reference Manual for a description of this
call.)
4.10 ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS
4.10 ADDITIONAL SOFTWARE INTERRUPT MONITOR CALLS
Additional monitor calls are available that allow the user's program
to check and to clear various parts of the software interrupt system.
Also, there is a call useful for interprocess communication (refer to
the IIC% call in Section 5.10).
4.10.1 Testing for Enablement
4.10.1 Testing for Enablement
The SKPIR% monitor call tests the software interrupt system to see if
it is enabled. The call accepts in AC1 the identifier of the process.
After execution of the call, control returns to the next instruction
if the system is off, and to the second instruction if the system is
on.
4-14
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
MOVEI 1,.FHSLF ;identifier of current process
SKPIR% ;test interrupt system
return ;system is off
return ;system is on
4.10.2 Obtaining Interrupt Table Addresses
4.10.2 Obtaining Interrupt Table Addresses
The RIR% and XRIR% monitor calls obtain the channel and priority level
table addresses for a process. These calls are useful when several
routines in one process want to share the interrupt tables.
4.10.2.1 The RIR% Monitor Call
4.10.2.1 The RIR% Monitor Call - The RIR% monitor call can be used in
any section of memory, but is only useful for obtaining table
addresses if those tables are in the same section of memory as the
code that makes the call. Furthermore, it can only obtain table
addresses that have been set by the SIR call.
The call accepts the identifier of the process in AC1. It returns the
table addresses in AC2. The left half of AC2 contains the
section-relative address of the priority level table, and the right
half contains the section-relative address of the channel table. If
the process has not set the table addresses with the SIR% monitor
call, AC2 contains zero.
Control always returns to the instruction following the RIR% call.
The following example shows the use of the RIR% call.
MOVEI 1,.FHSLF ;identifier of current process
RIR% ;return the table addresses
4.10.2.2 The XRIR% Monitor Call
4.10.2.2 The XRIR% Monitor Call - This call obtains the addresses of
the interrupt tables defined for a process. The tables can be in any
section of memory. The code that makes the call can also be in any
section. This call can only obtain addresses that have been set by
the XSIR% call.
The call accepts the identifier of the process in AC1, and the address
of the argument block in AC2. The argument block is three words long,
word zero must contain the number 3. The call returns the addresses
into words one and two. The block has the following format:
4-15
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
!=======================================================!
! Length of the argument block, including this word !
!-------------------------------------------------------!
! Address of the interrupt level table !
!-------------------------------------------------------!
! Address of the channel table !
!=======================================================!
Control always returns to the instruction following the XRIR% call.
If the process has not set the table addresses with the XSIR% monitor
call, words one and two of the argument block contain zero.
4.10.3 Disabling the Interrupt System
4.10.3 Disabling the Interrupt System
The DIR% monitor call disables the software interrupt system for the
process. It accepts the identifier of the process in AC1.
MOVEI 1,.FHSLF ;identifier of current process
DIR% ;disable system
Control always returns to the instruction following the DIR% call.
If interrupts occur while the interrupt system is disabled, they are
remembered until the system is reenabled. At that time, the
interrupts take effect unless an intervening CIS% monitor call (refer
to Section 4.10.6) has been issued.
Software interrupts assigned to panic channels are not completely
disabled by the DIR% call. These interrupts terminate the process,
and the superior process is notified if it has enabled channel .ICIFT.
In addition, if the terminal code for CTRL/C (.TICCC) is assigned to a
channel, it causes an interrupt that cannot be disabled by the DIR%
call. However, the CTRL/C interrupt can be disabled by deactivating
the channel assigned to the CTRL/C terminal code.
4.10.4 Deactivating a Channel
4.10.4 Deactivating a Channel
The DIC% monitor call is used to deactivate interrupt channels. The
call accepts two words of arguments: the process identifier in AC1,
and the channels to be deactivated in AC2. Setting bit n in AC2
indicates that channel n is to be deactivated.
MOVEI 1,.FHSLF ;identifier of current process
MOVE 2,[1B<.ICAOV>+1B<.ICPOV>] ;deactivate channels 6 and 9
DIC%
Control always returns to the instruction following the DIC% call.
4-16
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
When a channel is deactivated, interrupt requests for that channel are
ignored except for interrupts generated on panic channels (refer to
Section 4.6).
4.10.5 Deassigning Terminal Codes
4.10.5 Deassigning Terminal Codes
The DTI% monitor call deassigns a terminal code. This call accepts
one argument word: the terminal code in AC1.
MOVEI 1,.TICCE ;deassign CTRL/E
DTI%
Control always returns to the instruction following the DTI% call.
This monitor call is ignored if the specified terminal code has not
been defined by the current job.
4.10.6 Clearing the Interrupt System
4.10.6 Clearing the Interrupt System
The CIS% monitor call clears the interrupt system for the current
process. This call clears interrupts in progress and all waiting
interrupts. This call requires no arguments, and control always
returns to the instruction following the CIS call. The RESET% monitor
call (refer to Section 2.6.1) performs these same actions as part of
its initializing procedures.
4.11 SUMMARY
4.11 SUMMARY
To use the software interrupt system, the user's program must:
1. Supply routines that will process the interrupts.
2. Set up a channel table containing the addresses of the
routines (refer to Section 4.4.2) and a priority level table
containing the addresses for storing the program counter (PC)
values (refer to Section 4.4.3).
3. Specify the addresses of the tables with the XSIR% monitor
call (refer to Section 4.4.3).
4. Enable the software interrupt system with the EIR% monitor
call (refer to Section 4.5).
5. Activate the desired channels with the AIC% monitor call
(refer to Section 4.6).
4-17
USING THE SOFTWARE INTERRUPT SYSTEM
USING THE SOFTWARE INTERRUPT SYSTEM
4.12 SOFTWARE INTERRUPT EXAMPLE
4.12 SOFTWARE INTERRUPT EXAMPLE
This program copies one file to another. It accepts the input and
output filenames from the user. The end of file is detected by a
software interrupt, and CTRL/E is enabled as an escape character.
TITLE SOFTWARE INTERRUPT EXAMPLE
SEARCH MONSYM
SEARCH MACSYM
.REQUIRE SYS:MACREL
STDAC. ;DEFINE STANDARD ACs
INTCH1=1
START: RESET% ;RELEASE FILES, ETC.
XHLLI T1,EOFINT ;GET CURRENT PROCESS SECTION NUMBER
HLLZS T1 ;ISOLATE SECTION NUMBER ONLY
IORM T1,CHNTAB+INTCH1 ; AND ADD IT TO SERVICE ROUTINE
IORM T1,CHNTAB+.ICEOF ;ADDRESSES FOR OUR ROUTINES
IORM T1,LEVTAB+1 ; AND LEVTAB
MOVEI T1,.FHSLF ;CURRENT PROCESS
MOVEI T2,3 ;NUMBER OF WORDS IN ARG BLOCK
MOVEM T2,ARGBLK ;PUT NUMBER IN WORD ZERO
XMOVEI T2,LEVTAB ;GLOBAL ADDRESS OF LEVEL TABLE
MOVEM T2,ARGBLK+1 ;MOVE IT TO ARGBLK WORD ONE
XMOVEI T2,CHNTAB ;GLOBAL ADDRESS OF CHANNEL TABLE
MOVEM T2, ARGBLK+2 ;MOVE IT TO ARGBLK WORD TWO
XMOVEI T2,ARGBLK ;GLOBAL ADDRESS OF ARGUMENT BLOCK
XSIR%
EIR% ;ENABLE SYSTEM
MOVE T2,[1B+1B<.ICEOF>] ;ACTIVATE CHANNELS
AIC%
MOVE T1,[.TICCE,,INTCH1] ;ASSIGN CTRL/E TO CHANNEL 1
ATI%
GETIF: TMSG
MOVX T1,GJ%OLD+GJ%MSG+GJ%CFM+GJ%FNS+GJ%SHT
MOVE T2,[.PRIIN,,.PRIOU]
GTJFN% ;GET FILENAME FROM USER
ERJMP ERROR1
MOVEM T1,INJFN
GETOF: TMSG