TOPS-20 Monitor Calls User's Guide

Chapter 1 Introduction

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.
  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

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

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.

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

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.

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

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 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:

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 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

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:

A process can create other processes inferior to it, but there is one control process from which the chain of creations begins. A process 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.