THE ULTIMATE CORP. PAGE 150
CHAPTER 8 SYSTEM SOFTWARE
8.1 Introduction
Assembly level programming in the ULTIMATE system is facilitated by a set of standard system routines that allow easy interaction with the disc file structure, terminal I/O, and other system routines. These routines work with a standard set of addressing registers, storage registers, tallies, character registers, bits, and buffer pointers, collectively called "functional elements." In order to use any of these routines, therefore, i t is essential that the calling routine set up the appropriate functional elements as required by the called routine's input interface.
The standard set of functional elements is pre-defined in the permanent symbol file (PSYM), and is therefore always available to the programmer. Also included in the PSYM are the mode-id's (program entry pOints) for the standard system routines documented in this chapter.
The first part of this chapter, "User Program Interfaces," covers the methods of invoking a user-written program from the operating system and returning control to the operating system. The rest of the chapter, "System Subroutines," describes the routines available to the user program once i t has been invoked.
8.2 Documentation Conventions
The entry and exit procedures for the user program interfaces are described individually. The system subroutines, unless otherwise specified, are meant to be called using a BSL instruction, and they return to the calling program via a RTN instruction.
A brief description is given for each interface and subroutine. In each case, the Input Interface, Output Interface, and Element Usage sections describe the functional elements used by the routine. The single letter following an element name describes its type: B=b1t, C=character, H=hal f tally, T=tally (word), D=double tally, F=F-type tally, R=address register, S=storage register.
ASSEMBLER
Copyright 06 JUN 1983
THE ULTIMATE CORP. PAGE 152
Even if not specified, the following elements may be destroyed by any routine:
Bits SB60, SB61
Tallies T4, T5
Double Tallies Accumulator (DO, D1), D2
F-type Tallies FPX (overlays SYSRO), FPY (overlays SYSR1)
Registers R14, R15
Storage Registers SYSRO (overlays FPX), SYSR1 (overlays FPY) , SYSR2
If no description follows an element name, i t indicates that the element is used as a scratch element.
Input interface elements for many routines are divided into two sections: those labeled "User specified" and those labeled "System specified." The User specified elements are those that the programmer sets up explicitly before calling the routine. For example, when calling the routine to get a number of contiguous frames (GETBLK), the programmer must obviously specify this number as a parameter.
System specified elements are those that have been implicitly set up by the system some time prior to the call. For example, when calling the routine to read a line from the terminal (READLIN), the buffer location where the data are to be stored is a system standard, and does not have to be explicitly set up by the programmer.
8.3 Summary of System Software Routines
Read asynchronous channel
Get status of asynchronous channel Write asynchronous channel
Print text from object code to terminal Initialize and print heading/footing Read a line from the terminal
Set up characteristics of terminal, printer Write a line to the terminal or printer
4. Space management routines ATTOVF
Attach overflow frame automatically Get a block of overflow frames Get a frame of overflow space Attach overflow frame via register Read link fields of frame
Summary of System Software 5. Tape I/O routines
TPBCK
TPRDLBL TPRDLBL1 TPGETLBL TPREAD TPRDBLK TPREW
TPWEOF
TPWTLBL TPWTLBLl TPWRITE
6. Miscellaneous ACONV
CONV
CVDxx subs CVXxx subs DECINHIB ECONV HSISOS LINESUB
MBDSUB MBDNSUB MBDSUBX MBDNSUBX SLEEP SLEEPSUB TIME DATE
TIMDATE SORT WSINIT
Routines continued
Backward space tape 1 record Read tape label
Read a tape record Rewind the tape Write end of file Write tape label Write a tape record
Convert ASCII character to EBCDIC Call Conversion processor
Convert ASCII decimal to binary Convert ASCII hexadecimal to binary Decrement the INHIBITH counter Convert EBCDIC character to ASCII
Initalize IS, OS and HS buffer pointers Get user's line number
Convert binary to decimal ASCII string
Put terminal to sleep
Get system time and/or date Sort a string of keys
Initialize buffer pOinters
8.4 User Program Interfaces
This section describes the various means by which the operating system can transfer control to a user-written program, and the methods for
returning control to the system from the user program.
8.4.1 TCl-I Interface
The next few sections describe the Tel-I, TCl-II and WRAPUP interfaces. The system control flow should be kept in mind in order to understand the interaction between these processors. The flow diagram appears in the previous chapter. An example of a TCl-I verb and a TCl-II verb appear at the end of this chapter.
To invoke a user program as a TCl-I or TCl-II verb, a verb definition item is created in the master dictionary, with the mode-id of the program specified on line 2 (TCl-I) or on line 3 (TCl-II). line one consists of a "P", optionally followed by one other character, to identify the item as a verb. The Terminal Control language (TCl) processor then uses this information to transfer control to the user program. The entry point to the TCl processor is known as MOl in the PSYM, but this is largely irrelevant to a user program. MOl is normally entered only from WRAPUP or lOGON.
When MOl is entered, TCl checks for PROC control, and if this is present, enters the PROC processor. If a PROC is not in control (and bit CHAINFlG is zero), an input line is obtained from the terminal, and control passes immediately to M01B (documented next).
Input Interface System specified:
CHAINFlG B
PQFlG B
If set, terminal input is not obtained (as when chaining from one BASIC program to another)
Set to indicate PROC control
See M01B (next) for continuation of the TCl-I interface.
ASSEMBLER
Copyright 06 JUN 1983
THE ULTIMATE CORP. PAGE 156
8.4.2 TCl-I Interface, Continued
MD1B is the point where TCl attempts to retrieve a verb (first set of contiguous non-blank data in the input buffer) from a user's master dictionary, and validate it as such. If no errors are found, the rest of the data in the input buffer are edited and copied into the IS work space, and control passes to the processor specified in the primary-mode-id attribute of the verb, or to the PROC processor if the data define a PROC (attribute l="PO").
If the TCl statement contains "options," which are an alphabetic character string and/or numerics enclosed in parentheses at the end of the statement, the options are parsed as described below. Examples of options are "(M)" and "(AZ,100-300)".
Input Interface System specified:
IB R
Output Interface
BASE D
MODULO T SEPAR T
IB R
IBEND S
BMS R
BMSEND S
IR R
SR4 S
Points one character before the input data
=MBASE, MMODUlO, MSEPAR
Point to the SM at the end of the input line
Point to the last character in the verb name (for RETIX)
Points to the AM following attribute 4 of the verb item, or to the end-of-data AM in the item, or to the "0" in attribute one if the item defines a PROC Points to the AM at the end of the verb item in the master dictionary
The following specifications are meaningful only if the first two input characters are not "PO":
SCP C
CTRO T
Contains the character immediately following "P" in the verb definition, if present, otherwise contains a blank Contains the primary mode-id specified in the verb definition attribute 2